@vanillagreen/pi-qol 1.5.0 → 1.7.0

package/README.md

@@ -5,16 +5,18 @@
 ![Session search popup](https://raw.githubusercontent.com/vanillagreencom/vstack/main/pi-extensions/pi-qol/assets/session-search.gif)
 ![/context usage breakdown](https://raw.githubusercontent.com/vanillagreencom/vstack/main/pi-extensions/pi-qol/assets/context-usage.png)
 
-Quality-of-life extension for Pi: compact statusline, multiline input, session naming and search, notifications, and a permission gate.
+Quality-of-life extension for Pi: compact statusline, multiline input, session naming and search, scheduled prompts, notifications, and a permission gate.
 
 ## Highlights
 
-- Compact statusline with repo, branch, model, thinking level, and context percent.
+- Compact statusline with repo, branch, model, thinking level, and context percent; can be disabled.
 - Newline-insert in the editor (multi-line drafts without auto-submit), with a fallback binding for terminals that can't distinguish the primary key.
 - Sessions auto-name from your first prompt. `/rename` overrides anytime.
 - `/search` browses previous sessions with snippet previews; the configured shortcut opens it instantly.
 - `/context` shows a Claude-style context-window breakdown.
 - `/handoff <goal>` drafts a focused prompt for a new session.
+- `/schedule 20m <message>` or `/schedule 1h45m <message>` sends a delayed prompt without invoking the model until the timer fires.
+- Optional rate-limit auto-resume sends a configurable continuation after reset.
 - Permission gate prompts before risky `bash` commands. Default match: `rm -Rf`.
 - Notifications for ready, questions, blocked states, and task completion.
 - Thinking timer next to collapsed `Thinking...` labels.
@@ -51,9 +53,12 @@ Restart Pi after installation.
 | `/search [query]` | Open previous-session search. |
 | `/search:refresh` | Refresh the session search cache. |
 | `/handoff <goal>` | Draft a handoff prompt for a new session. |
+| `/schedule <delay> <message>` | Send a user message after a timer without invoking the model now. Example: `/schedule 1h45m retry the previous request`. |
 
 Arguments support autocomplete.
 
+`/schedule` accepts `ms`, `s`, `m`, `h`, and `d` units; bare numbers mean minutes. Compact composite durations are accepted in largest-to-smallest order, like `1h45m`, `45m10s`, or `1h45m30s`. Pending prompts render above the statusline like steering/follow-up previews until they are sent or cancelled. Manage pending prompts with `/schedule list` and `/schedule cancel <id|all>`. Schedules are stored in the Pi session and re-armed on reload/resume; if Pi is not running at the due time, an overdue prompt sends when that session is next loaded.
+
 ## Settings
 
 Open `/extensions:settings`; settings appear under the **QOL** tab. Names below match the labels shown there.
@@ -65,7 +70,8 @@ Glyph style: each package exposes `glyphStyle` (`unicode` default, `ascii` for t
 | Setting | What it does |
 | --- | --- |
 | Enable QOL editor helpers | Master toggle for QOL statusline, commands, notifications, search, compaction, and editor helpers. |
-| Replace built-in footer | Hide Pi's default footer while the QOL statusline is active. |
+| Show compact statusline | Render or disable the QOL statusline row. |
+| Replace built-in footer | Hide Pi's default footer while the QOL statusline is enabled. |
 | Use π prompt editor | Use the compact prompt editor. |
 | Show session name title | Show the session name above the prompt and in the tmux pane title. |
 | Sync session name to tmux window name | Rename the tmux window to `π <session>`. |
@@ -82,11 +88,13 @@ Glyph style: each package exposes `glyphStyle` (`unicode` default, `ascii` for t
 | Style image chips | Render `[Image #N]` placeholders as distinct chips. |
 | Show attachment count | Show a status badge when the draft has image placeholders. |
 
-### Session naming
+### Session
 
 | Setting | What it does |
 | --- | --- |
 | Enable /rename command | Register the `/rename` command. |
+| Enable /schedule command | Register `/schedule` for timer-based prompts, useful for retrying after rate limits reset. |
+| Auto-resume after rate limits | Send the configured continuation after a detected reset; cancels on newer turn. |
 | Auto-name new sessions | Generate a friendly session name from the first prompt. |
 | Auto-rename model | Model used for title generation. |
 | Auto-rename fallback model | Model tried when the primary fails. |
@@ -130,7 +138,7 @@ Master toggle: **Enable notifications**.
 
 Triggers (notify when): ready, direction needed, question popups, all tasks complete, critical/blocked.
 
-Channels: terminal bell, native terminal notifications (OSC 777/99 or Windows toast), tmux `display-message`, tmux window marking, OSC passthrough, and an optional in-Pi UI notice.
+Channels: terminal bell, **Mute bell sound**, native terminal notifications (OSC 777/99 or Windows toast), tmux `display-message`, tmux window marking, OSC passthrough, and an optional in-Pi UI notice.
 
 Tuning: cooldown seconds, title, ready message, body length, tmux durations.
 
@@ -138,9 +146,10 @@ Notes:
 
 - **Terminal notification protocol** picks between OSC 99 (Kitty) and OSC 777 automatically.
 - **Bell when tmux window active** is off so you don't get bells while looking at Pi.
+- **Mute bell sound** keeps notification routing enabled but suppresses QOL-emitted BEL bytes and uses ST terminators for OSC 777/99 where supported. Terminals or operating systems may still play their own sound for native notifications outside QOL control.
 - **tmux native via client TTY** sends OSC notifications to attached tmux clients so notifications still appear when the Pi window is inactive.
 
-Use `/qol notify-test` to verify your terminal/tmux setup.
+Use `/qol notify-test` to verify your terminal/tmux setup, including silent behavior with **Mute bell sound** enabled.
 
 ### Permission gate
 
@@ -184,6 +193,8 @@ For autonomous/Flightdeck-style runs the agent never goes idle, so idle compacti
 
 When the budget guard fires it injects a sentinel into the compaction request so the QOL bounded handler always runs — chunked summarizer + handoff artifact — even if **Custom compaction summaries** is off. Manual compactions (`/tree`, idle compaction, user-triggered) still only use the QOL handler when **Custom compaction summaries** is on; otherwise they fall through to Pi's default compaction with no handoff artifact and no chunking. If you want every compaction to use the QOL bounded path, turn **Custom compaction summaries** on.
 
+While budget-guard compaction is running, QOL keeps a persistent status line above the prompt (and in the normal status footer when the compact statusline is disabled). After Pi prints the compacted-summary block, the line changes to `QOL budget guard finalizing compaction…` until `ctx.compact()` reports completion, so long reload/finalization gaps do not look frozen.
+
 Recommended values for autonomous/Flightdeck runs:
 
 - Keep **Long-session budget guard** on. Lower **Budget guard percent** to `75` if your provider buffers are tight.

package/extensions/qol/budget-guard-runtime.ts

@@ -17,6 +17,7 @@ export interface GuardDispatchInput {
 	trigger: BudgetTrigger | undefined;
 	compact: ((options: GuardCompactOptions) => void) | undefined;
 	notify: (message: string, level: GuardLevel) => void;
+	onStatus?: (message: string | undefined) => void;
 	staleCtx?: () => boolean;
 }
 
@@ -70,6 +71,7 @@ export class BudgetGuardDriver {
 			return { kind: "no-compact-fn" };
 		}
 		input.notify(`QOL budget guard starting compaction: ${trigger.reason}`, "info");
+		input.onStatus?.(`QOL budget guard compacting session: ${trigger.reason}`);
 		this.inFlight = true;
 		this.lastKey = trigger.key;
 		const instructions = `${QOL_BUDGET_GUARD_SENTINEL} QOL budget guard triggered at agent_end because ${trigger.reason}. Bound the summary input, preserve current task state, decisions, files, blockers, and next steps.`;
@@ -78,6 +80,7 @@ export class BudgetGuardDriver {
 				customInstructions: instructions,
 				onComplete: () => {
 					this.inFlight = false;
+					input.onStatus?.(undefined);
 					input.notify("QOL budget guard compaction completed.", "info");
 				},
 				onError: (error: Error) => {
@@ -85,6 +88,7 @@ export class BudgetGuardDriver {
 					// Allow the next agent_end to retry rather than poisoning the
 					// crossing key after a transient failure.
 					this.lastKey = undefined;
+					input.onStatus?.(undefined);
 					input.notify(`QOL budget guard compaction failed: ${error.message}`, "error");
 				},
 			});
@@ -92,6 +96,7 @@ export class BudgetGuardDriver {
 		} catch (error) {
 			this.inFlight = false;
 			this.lastKey = undefined;
+			input.onStatus?.(undefined);
 			const message = error instanceof Error ? error.message : String(error);
 			input.notify(`QOL budget guard compaction failed to start: ${message}`, "error");
 			return { kind: "dispatch-threw", error: message, reason: trigger.reason };

package/extensions/qol/notifications.ts

@@ -52,6 +52,19 @@ function tmuxPassthrough(sequence: string): string {
 	return `\x1bPtmux;${sequence.replace(/\x1b/g, "\x1b\x1b")}\x1b\\`;
 }
 
+export function terminalBellSequence(muteBellSound: boolean): string | undefined {
+	return muteBellSound ? undefined : "\x07";
+}
+
+export function osc777NotificationSequence(title: string, body: string, muteBellSound = false): string {
+	const terminator = muteBellSound ? "\x1b\\" : "\x07";
+	return `\x1b]777;notify;${title};${body}${terminator}`;
+}
+
+function notificationBellMuted(cwd?: string): boolean {
+	return settingBoolean("notification.muteBellSound", false, cwd);
+}
+
 function sourcePaneTty(): string | undefined {
 	try {
 		if (!process.env.TMUX_PANE) return undefined;
@@ -127,21 +140,22 @@ function writeTerminalSequence(sequence: string, cwd?: string): void {
 	if (process.env.TMUX && settingBoolean("notification.tmuxNativeClientTty", true, cwd)) {
 		// Inactive tmux windows do not forward arbitrary OSC output to the terminal.
 		// Send native terminal notifications straight to attached tmux client TTYs,
-		// while BEL still goes through the source pane so tmux marks the right tab.
+		// while the explicit terminal bell still goes through the source pane when unmuted.
 		if (writeRawToPaths(tmuxClientTtys(), sequence)) return;
 	}
 	const output = process.env.TMUX && settingBoolean("notification.tmuxPassthrough", true, cwd) ? tmuxPassthrough(sequence) : sequence;
 	writeToTerminal(output);
 }
 
-function writeTerminalBell(): void {
+function writeTerminalBell(cwd?: string): void {
 	// Match Claude-style hooks: resolve the source pane TTY and write raw BEL there.
 	// This lets tmux set window_bell_flag for the correct source window.
-	writeToTerminal("\x07");
+	const sequence = terminalBellSequence(notificationBellMuted(cwd));
+	if (sequence) writeToTerminal(sequence);
 }
 
 function notifyOSC777(title: string, body: string, cwd?: string): void {
-	writeTerminalSequence(`\x1b]777;notify;${title};${body}\x07`, cwd);
+	writeTerminalSequence(osc777NotificationSequence(title, body, notificationBellMuted(cwd)), cwd);
 }
 
 function notifyOSC99(title: string, body: string, cwd?: string): void {
@@ -242,7 +256,7 @@ export function sendQolNotification(ctx: ExtensionContext | undefined, kind: Qol
 	const title = sanitizeNotificationPart(settingString("notification.title", DEFAULT_NOTIFICATION_TITLE, cwd), 80) || DEFAULT_NOTIFICATION_TITLE;
 	const text = sanitizeNotificationPart(body, Math.max(40, Math.floor(settingNumber("notification.bodyMaxChars", DEFAULT_NOTIFICATION_BODY_MAX_CHARS, cwd))));
 	const tmuxWindowActive = sourceTmuxWindowActive();
-	if (settingBoolean("notification.bell", true, cwd) && (!tmuxWindowActive || settingBoolean("notification.bellWhenActive", false, cwd))) writeTerminalBell();
+	if (settingBoolean("notification.bell", true, cwd) && (!tmuxWindowActive || settingBoolean("notification.bellWhenActive", false, cwd))) writeTerminalBell(cwd);
 	if (settingBoolean("notification.native", true, cwd)) notifyNativeTerminal(title, text, cwd);
 	if (!tmuxWindowActive) markTmuxWindow(cwd);
 	if (settingBoolean("notification.tmux", false, cwd)) notifyTmux(title, text, cwd);

package/extensions/qol/rate-limit-auto-resume.ts

@@ -0,0 +1,447 @@
+import { truncateToWidth } from "@earendil-works/pi-tui";
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { ansiRed } from "./ansi.js";
+import { boundedSettingNumber, settingBoolean, settingString } from "./settings.js";
+import { stringifyError } from "./util.js";
+
+export const RATE_LIMIT_AUTO_RESUME_EVENT = "vstack:rate-limit";
+export const DEFAULT_RATE_LIMIT_RESUME_MESSAGE = "Hit API rate limit. It has been reset. Continue";
+
+const MAX_TIMER_DELAY_MS = 2_147_000_000;
+const DEFAULT_BUFFER_SECONDS = 10;
+const DEFAULT_MAX_DELAY_MINUTES = 24 * 60;
+const RATE_LIMIT_TOKEN = "[rate-limit]";
+
+interface RateLimitTimer {
+	unref?: () => void;
+}
+
+export interface RateLimitClock {
+	now(): number;
+	setTimeout(callback: () => void, delayMs: number): RateLimitTimer;
+	clearTimeout(timer: RateLimitTimer): void;
+}
+
+export interface RateLimitHint {
+	message?: string;
+	model?: string;
+	observedAt: number;
+	provider?: string;
+	reason?: string;
+	resetAt?: number;
+	source: string;
+	turnId: number;
+}
+
+interface PendingRateLimitResume {
+	dueAt: number;
+	message: string;
+	reason?: string;
+	resetAt: number;
+	source: string;
+	timer?: RateLimitTimer;
+	turnId: number;
+}
+
+const DEFAULT_CLOCK: RateLimitClock = {
+	now: () => Date.now(),
+	setTimeout: (callback, delayMs) => setTimeout(callback, delayMs),
+	clearTimeout: (timer) => clearTimeout(timer as ReturnType<typeof setTimeout>),
+};
+
+function asRecord(value: unknown): Record<string, unknown> | undefined {
+	return value && typeof value === "object" && !Array.isArray(value) ? value as Record<string, unknown> : undefined;
+}
+
+function stringValue(value: unknown): string | undefined {
+	return typeof value === "string" && value.trim().length > 0 ? value.trim() : undefined;
+}
+
+function numberValue(value: unknown): number | undefined {
+	const parsed = typeof value === "number" ? value : typeof value === "string" && value.trim() ? Number(value) : Number.NaN;
+	return Number.isFinite(parsed) ? parsed : undefined;
+}
+
+function allHeaderValues(headers: unknown, key: string): string[] {
+	const wanted = key.toLowerCase();
+	if (!headers || typeof headers !== "object") return [];
+	const anyHeaders = headers as any;
+	try {
+		if (typeof anyHeaders.get === "function") {
+			const value = anyHeaders.get(key) ?? anyHeaders.get(wanted);
+			if (typeof value === "string" && value.trim()) return [value.trim()];
+		}
+	} catch {
+		// Fall through to object form.
+	}
+	const out: string[] = [];
+	for (const [rawKey, rawValue] of Object.entries(headers as Record<string, unknown>)) {
+		if (rawKey.toLowerCase() !== wanted) continue;
+		if (Array.isArray(rawValue)) {
+			for (const item of rawValue) if (typeof item === "string" && item.trim()) out.push(item.trim());
+		} else if (typeof rawValue === "string" && rawValue.trim()) out.push(rawValue.trim());
+		else if (typeof rawValue === "number" && Number.isFinite(rawValue)) out.push(String(rawValue));
+	}
+	return out;
+}
+
+export function looksLikeRateLimitText(text: string): boolean {
+	return /\b(rate[-\s]?limit(?:ed)?|too many requests|\b429\b|quota exceeded|resource exhausted|try again later|retry[-\s]?after|out of extra usage|extra usage)\b/i.test(text);
+}
+
+function parseUnitDurationMs(amount: number, unit: string | undefined, defaultUnit: "ms" | "s" | "m" = "s"): number | undefined {
+	if (!Number.isFinite(amount) || amount < 0) return undefined;
+	const normalized = (unit ?? defaultUnit).toLowerCase();
+	const multiplier = ["ms", "msec", "msecs", "millisecond", "milliseconds"].includes(normalized)
+		? 1
+		: ["s", "sec", "secs", "second", "seconds"].includes(normalized)
+			? 1000
+			: ["m", "min", "mins", "minute", "minutes"].includes(normalized)
+				? 60 * 1000
+				: ["h", "hr", "hrs", "hour", "hours"].includes(normalized)
+					? 60 * 60 * 1000
+					: ["d", "day", "days"].includes(normalized)
+						? 24 * 60 * 60 * 1000
+						: undefined;
+	if (!multiplier) return undefined;
+	const delay = Math.round(amount * multiplier);
+	return Number.isFinite(delay) ? delay : undefined;
+}
+
+export function parseDurationLikeMs(value: string, defaultUnit: "ms" | "s" | "m" = "s"): number | undefined {
+	const text = value.trim().toLowerCase();
+	if (!text) return undefined;
+	if (/^\d+(?:\.\d+)?$/.test(text)) return parseUnitDurationMs(Number(text), undefined, defaultUnit);
+	const single = text.match(/^(\d+(?:\.\d+)?)\s*(ms|msec|msecs|milliseconds?|s|sec|secs|seconds?|m|min|mins|minutes?|h|hr|hrs|hours?|d|days?)$/i);
+	if (single) return parseUnitDurationMs(Number(single[1]), single[2], defaultUnit);
+	let total = 0;
+	let matched = false;
+	const re = /(\d+(?:\.\d+)?)\s*(ms|msec|msecs|milliseconds?|s|sec|secs|seconds?|m|min|mins|minutes?|h|hr|hrs|hours?|d|days?)/gi;
+	for (const match of text.matchAll(re)) {
+		const part = parseUnitDurationMs(Number(match[1]), match[2], defaultUnit);
+		if (part === undefined) return undefined;
+		total += part;
+		matched = true;
+	}
+	return matched && Number.isFinite(total) ? Math.round(total) : undefined;
+}
+
+export function parseRetryAfterMs(value: string, now = Date.now(), defaultUnit: "ms" | "s" | "m" = "s"): number | undefined {
+	const duration = parseDurationLikeMs(value, defaultUnit);
+	if (duration !== undefined) return now + duration;
+	const parsedDate = Date.parse(value);
+	return Number.isFinite(parsedDate) ? parsedDate : undefined;
+}
+
+export function parseResetValueMs(value: string, now = Date.now()): number | undefined {
+	const trimmed = value.trim();
+	if (!trimmed) return undefined;
+	const numeric = Number(trimmed);
+	if (Number.isFinite(numeric)) {
+		if (numeric > 1_000_000_000_000) return numeric;
+		if (numeric > 1_000_000_000) return numeric * 1000;
+		return now + numeric * 1000;
+	}
+	const parsedDate = Date.parse(trimmed);
+	if (Number.isFinite(parsedDate)) return parsedDate;
+	const duration = parseDurationLikeMs(trimmed, "s");
+	return duration !== undefined ? now + duration : undefined;
+}
+
+export function extractResetAtFromHeaders(headers: unknown, now = Date.now()): { resetAt: number; source: string } | undefined {
+	for (const value of allHeaderValues(headers, "retry-after-ms")) {
+		const resetAt = parseRetryAfterMs(value, now, "ms");
+		if (resetAt !== undefined) return { resetAt, source: "retry-after-ms" };
+	}
+	for (const value of allHeaderValues(headers, "retry-after")) {
+		const resetAt = parseRetryAfterMs(value, now, "s");
+		if (resetAt !== undefined) return { resetAt, source: "retry-after" };
+	}
+	const resetHeaders = [
+		"x-ratelimit-reset",
+		"x-rate-limit-reset",
+		"ratelimit-reset",
+		"x-ratelimit-reset-requests",
+		"x-ratelimit-reset-tokens",
+		"anthropic-ratelimit-requests-reset",
+		"anthropic-ratelimit-tokens-reset",
+		"anthropic-ratelimit-input-tokens-reset",
+		"anthropic-ratelimit-output-tokens-reset",
+	];
+	for (const header of resetHeaders) {
+		for (const value of allHeaderValues(headers, header)) {
+			const resetAt = parseResetValueMs(value, now);
+			if (resetAt !== undefined) return { resetAt, source: header };
+		}
+	}
+	return undefined;
+}
+
+function parseClockReset(text: string, now = Date.now()): number | undefined {
+	const match = text.match(/\bresets?(?:\s+at)?\s+(\d{1,2})(?::(\d{2}))?(?::(\d{2}))?\s*(am|pm)?\b/i);
+	if (!match) return undefined;
+	let hour = Number(match[1]);
+	const minute = Number(match[2] ?? "0");
+	const second = Number(match[3] ?? "0");
+	const meridiem = match[4]?.toLowerCase();
+	if (!Number.isInteger(hour) || !Number.isInteger(minute) || !Number.isInteger(second)) return undefined;
+	if (minute > 59 || second > 59) return undefined;
+	if (meridiem) {
+		if (hour < 1 || hour > 12) return undefined;
+		if (meridiem === "pm" && hour !== 12) hour += 12;
+		if (meridiem === "am" && hour === 12) hour = 0;
+	} else if (hour > 23) return undefined;
+	const date = new Date(now);
+	date.setHours(hour, minute, second, 0);
+	if (date.getTime() <= now) date.setDate(date.getDate() + 1);
+	return date.getTime();
+}
+
+export function extractResetAtFromText(text: string, now = Date.now()): { resetAt: number; source: string } | undefined {
+	const iso = text.match(/\b\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?(?:Z|[+-]\d{2}:?\d{2})\b/);
+	if (iso) {
+		const resetAt = Date.parse(iso[0]);
+		if (Number.isFinite(resetAt)) return { resetAt, source: "text-iso" };
+	}
+	const durationMatch = text.match(/\b(?:retry(?:\s+after|\s+in)?|try again in|wait)\s+(\d+(?:\.\d+)?\s*(?:ms|msec|msecs|milliseconds?|s|sec|secs|seconds?|m|min|mins|minutes?|h|hr|hrs|hours?|d|days?)(?:\s*\d+(?:\.\d+)?\s*(?:ms|msec|msecs|milliseconds?|s|sec|secs|seconds?|m|min|mins|minutes?|h|hr|hrs|hours?|d|days?))*)\b/i);
+	if (durationMatch) {
+		const duration = parseDurationLikeMs(durationMatch[1], "s");
+		if (duration !== undefined) return { resetAt: now + duration, source: "text-duration" };
+	}
+	const clock = parseClockReset(text, now);
+	return clock !== undefined ? { resetAt: clock, source: "text-clock" } : undefined;
+}
+
+function messageText(message: any): string {
+	const parts: string[] = [];
+	if (typeof message?.errorMessage === "string") parts.push(message.errorMessage);
+	if (typeof message?.content === "string") parts.push(message.content);
+	else if (Array.isArray(message?.content)) {
+		for (const block of message.content) {
+			if (typeof block === "string") parts.push(block);
+			else if (block?.type === "text" && typeof block.text === "string") parts.push(block.text);
+		}
+	}
+	return parts.filter(Boolean).join("\n");
+}
+
+function lastAssistantMessage(event: any, ctx: ExtensionContext): any | undefined {
+	const eventMessages = Array.isArray(event?.messages) ? event.messages : [];
+	for (let index = eventMessages.length - 1; index >= 0; index -= 1) {
+		const message = eventMessages[index];
+		if (message?.role === "assistant") return message;
+	}
+	const branch = ctx.sessionManager.getBranch?.() ?? [];
+	for (let index = branch.length - 1; index >= 0; index -= 1) {
+		const entry = branch[index] as any;
+		if (entry?.type === "message" && entry.message?.role === "assistant") return entry.message;
+	}
+	return undefined;
+}
+
+function formatDueTime(timestamp: number): string {
+	return new Date(timestamp).toLocaleString(undefined, {
+		day: "numeric",
+		hour: "numeric",
+		minute: "2-digit",
+		month: "short",
+		timeZoneName: "short",
+	});
+}
+
+function previewMessage(message: string, max = 72): string {
+	const singleLine = message.replace(/\s+/g, " ").trim();
+	return singleLine.length <= max ? singleLine : `${singleLine.slice(0, Math.max(0, max - 1))}…`;
+}
+
+function settingsEnabled(ctx: ExtensionContext): boolean {
+	return settingBoolean("rateLimitAutoResume.enabled", false, ctx.cwd);
+}
+
+function settingsNotify(ctx: ExtensionContext): boolean {
+	return settingBoolean("rateLimitAutoResume.notify", true, ctx.cwd);
+}
+
+function settingsMessage(ctx: ExtensionContext): string {
+	return settingString("rateLimitAutoResume.message", DEFAULT_RATE_LIMIT_RESUME_MESSAGE, ctx.cwd);
+}
+
+function settingsBufferMs(ctx: ExtensionContext): number {
+	return boundedSettingNumber("rateLimitAutoResume.bufferSeconds", DEFAULT_BUFFER_SECONDS, 0, 600, ctx.cwd) * 1000;
+}
+
+function settingsMaxDelayMs(ctx: ExtensionContext): number {
+	return boundedSettingNumber("rateLimitAutoResume.maxDelayMinutes", DEFAULT_MAX_DELAY_MINUTES, 1, 30 * 24 * 60, ctx.cwd) * 60 * 1000;
+}
+
+export function createRateLimitAutoResumeController(pi: ExtensionAPI, clock: RateLimitClock = DEFAULT_CLOCK) {
+	let onChange: (() => void) | undefined;
+	let turnId = 0;
+	let latestHint: RateLimitHint | undefined;
+	let pending: PendingRateLimitResume | undefined;
+
+	const notifyChanged = (): void => {
+		try { onChange?.(); }
+		catch { /* UI refresh must never break recovery state. */ }
+	};
+
+	const clearPendingTimer = (): void => {
+		if (!pending?.timer) return;
+		clock.clearTimeout(pending.timer);
+		pending.timer = undefined;
+	};
+
+	const clearPending = (): void => {
+		const hadPending = Boolean(pending);
+		clearPendingTimer();
+		pending = undefined;
+		if (hadPending) notifyChanged();
+	};
+
+	const noteHint = (hint: Omit<RateLimitHint, "observedAt" | "turnId"> & { observedAt?: number; turnId?: number }): void => {
+		if (hint.resetAt !== undefined && (!Number.isFinite(hint.resetAt) || hint.resetAt <= 0)) return;
+		latestHint = {
+			...hint,
+			observedAt: hint.observedAt ?? clock.now(),
+			turnId: hint.turnId ?? turnId,
+		};
+	};
+
+	const deliverPending = async (snapshot: PendingRateLimitResume, ctx: ExtensionContext): Promise<void> => {
+		if (pending !== snapshot) return;
+		if (snapshot.turnId !== turnId || !settingsEnabled(ctx)) {
+			clearPending();
+			return;
+		}
+		if (clock.now() < snapshot.dueAt) {
+			armPending(snapshot, ctx);
+			return;
+		}
+		clearPending();
+		try {
+			let idle = true;
+			try { idle = ctx.isIdle?.() ?? true; }
+			catch { idle = false; }
+			await Promise.resolve(idle ? pi.sendUserMessage(snapshot.message) : pi.sendUserMessage(snapshot.message, { deliverAs: "followUp" }));
+			if (ctx.hasUI && settingsNotify(ctx)) ctx.ui.notify(`${RATE_LIMIT_TOKEN} Auto-resume sent after rate-limit reset.`, "info");
+		} catch (error) {
+			if (ctx.hasUI) ctx.ui.notify(`${RATE_LIMIT_TOKEN} Auto-resume failed: ${stringifyError(error)}`, "error");
+		}
+	};
+
+	function armPending(snapshot: PendingRateLimitResume, ctx: ExtensionContext): void {
+		clearPendingTimer();
+		const remaining = Math.max(0, snapshot.dueAt - clock.now());
+		snapshot.timer = clock.setTimeout(() => { void deliverPending(snapshot, ctx); }, Math.min(remaining, MAX_TIMER_DELAY_MS));
+		snapshot.timer.unref?.();
+	}
+
+	const scheduleFromHint = (hint: RateLimitHint, ctx: ExtensionContext): boolean => {
+		if (!settingsEnabled(ctx)) return false;
+		if (hint.turnId !== turnId) return false;
+		if (ctx.hasPendingMessages?.()) return false;
+		if (hint.resetAt === undefined || !Number.isFinite(hint.resetAt)) return false;
+		const dueAt = Math.max(clock.now() + 1000, hint.resetAt + settingsBufferMs(ctx));
+		const delay = dueAt - clock.now();
+		if (delay > settingsMaxDelayMs(ctx)) return false;
+		const message = settingsMessage(ctx);
+		clearPendingTimer();
+		pending = { dueAt, message, reason: hint.reason, resetAt: hint.resetAt, source: hint.source, turnId };
+		armPending(pending, ctx);
+		notifyChanged();
+		if (ctx.hasUI && settingsNotify(ctx)) {
+			ctx.ui.notify(`${RATE_LIMIT_TOKEN} Rate limit hit. Auto-resume scheduled for ${formatDueTime(dueAt)}.`, "warning");
+		}
+		return true;
+	};
+
+	return {
+		enabled(ctx: ExtensionContext): boolean {
+			return settingsEnabled(ctx);
+		},
+		clearTimers(): void {
+			clearPending();
+		},
+		noteAgentStart(_ctx: ExtensionContext): void {
+			turnId += 1;
+			latestHint = undefined;
+			clearPending();
+		},
+		noteAgentEnd(event: any, ctx: ExtensionContext): boolean {
+			const assistant = lastAssistantMessage(event, ctx);
+			const text = messageText(assistant);
+			const textShowsRateLimit = Boolean(text && looksLikeRateLimitText(text));
+			if (textShowsRateLimit) {
+				const reset = extractResetAtFromText(text, clock.now());
+				noteHint({
+					message: text,
+					model: stringValue(assistant?.model),
+					provider: stringValue(assistant?.provider),
+					reason: "assistant error",
+					resetAt: reset?.resetAt ?? latestHint?.resetAt,
+					source: reset?.source ?? latestHint?.source ?? "assistant-message",
+				});
+			}
+			const stoppedOnHint = !assistant || assistant?.stopReason === "error" || assistant?.stopReason === "aborted";
+			if (!textShowsRateLimit && !stoppedOnHint) return false;
+			return latestHint ? scheduleFromHint(latestHint, ctx) : false;
+		},
+		noteMessageEnd(event: any, _ctx: ExtensionContext): void {
+			const message = event?.message;
+			if (!message || message.role !== "assistant") return;
+			const text = messageText(message);
+			if (!looksLikeRateLimitText(text)) return;
+			const reset = extractResetAtFromText(text, clock.now());
+			noteHint({
+				message: text,
+				model: stringValue(message.model),
+				provider: stringValue(message.provider),
+				reason: "assistant message",
+				resetAt: reset?.resetAt ?? latestHint?.resetAt,
+				source: reset?.source ?? latestHint?.source ?? "message_end",
+			});
+		},
+		noteProviderResponse(event: any, _ctx: ExtensionContext): void {
+			if (Number(event?.status) !== 429) return;
+			const reset = extractResetAtFromHeaders(event?.headers, clock.now());
+			noteHint({
+				model: stringValue(event?.model?.id) ?? stringValue(event?.model),
+				provider: stringValue(event?.provider?.id) ?? stringValue(event?.provider),
+				reason: "HTTP 429",
+				resetAt: reset?.resetAt ?? latestHint?.resetAt,
+				source: reset?.source ?? latestHint?.source ?? "after_provider_response",
+			});
+		},
+		noteExternalRateLimitEvent(payload: unknown, _ctx: ExtensionContext): void {
+			const event = asRecord(payload);
+			if (!event) return;
+			const status = stringValue(event.status);
+			if (status && status !== "rejected" && status !== "rate_limited" && status !== "error") return;
+			const rawReset = numberValue(event.resetAtMs) ?? numberValue(event.resetAtUnixMs);
+			const textReset = stringValue(event.resetAt) ?? stringValue(event.resetsAt);
+			const parsedTextReset = textReset ? parseResetValueMs(textReset, clock.now()) : undefined;
+			const resetAt = rawReset ?? parsedTextReset;
+			noteHint({
+				message: stringValue(event.message),
+				model: stringValue(event.model),
+				provider: stringValue(event.provider),
+				reason: stringValue(event.reason) ?? stringValue(event.rateLimitType),
+				resetAt: resetAt ?? latestHint?.resetAt,
+				source: stringValue(event.source) ?? latestHint?.source ?? RATE_LIMIT_AUTO_RESUME_EVENT,
+			});
+		},
+		renderPreviewLines(width: number): string[] {
+			if (!pending) return [];
+			const line = `| ${RATE_LIMIT_TOKEN} Auto-resume ${formatDueTime(pending.dueAt)} — ${previewMessage(pending.message)}`;
+			return [truncateToWidth(ansiRed(line), width, "")];
+		},
+		setOnChange(callback: (() => void) | undefined): void {
+			onChange = callback;
+		},
+		// Test helper / low-level extension bridge.
+		scheduleForHint(hint: RateLimitHint, ctx: ExtensionContext): boolean {
+			latestHint = hint;
+			return scheduleFromHint(hint, ctx);
+		},
+	};
+}