pi-crew 0.9.49 → 0.9.51

package/src/extension/registration/viewers.ts

@@ -103,6 +103,9 @@ export async function openLiveConversation(
 				invalidate() {
 					/* overlay polls */
 				},
+				dispose() {
+					overlay.dispose();
+				},
 			};
 		},
 		{

package/src/extension/team-tool/run.ts

@@ -15,6 +15,7 @@ import { assertCleanLeaderAsync, findGitRootAsync } from "../../worktree/worktre
 // eslint-disable-next-line @typescript-eslint/no-unused-vars -- type-only import for TS inference
 const _typeCheck: typeof ExecuteTeamRunFn = null as never as typeof ExecuteTeamRunFn;
 
+import { errorMessage } from "../../utils/guards.ts";
 import { logInternalError } from "../../utils/internal-error.ts";
 import { resolveContainedPath, resolveRealContainedPath } from "../../utils/safe-paths.ts";
 
@@ -432,7 +433,7 @@ export async function handleRun(params: TeamToolParamsValue, ctx: TeamContext):
 			try {
 				await assertCleanLeaderAsync(gitRoot);
 			} catch (err) {
-				const msg = err instanceof Error ? err.message : String(err);
+				const msg = errorMessage(err);
 				return result(
 					`${msg}\nCommit or stash changes before using worktree mode, or use workspaceMode: 'single'.`,
 					{ action: "run", status: "error" },
@@ -655,7 +656,7 @@ export async function handleRun(params: TeamToolParamsValue, ctx: TeamContext):
 				// Round-11 runtime fix: persist manifest with status=failed when runner throws
 				// (e.g., script timeout, script syntax error, async failure). Previously the
 				// manifest stayed at 'queued' indefinitely, leaving an orphan state file.
-				const failureReason = runnerError instanceof Error ? runnerError.message : String(runnerError);
+				const failureReason = errorMessage(runnerError);
 				const failedManifest = {
 					...dwfManifest,
 					status: "failed" as const,
@@ -856,13 +857,13 @@ export async function handleRun(params: TeamToolParamsValue, ctx: TeamContext):
 				workspaceId: ctx.sessionId ?? ctx.cwd,
 			});
 		} catch (waitError: unknown) {
-			const errorMessage = waitError instanceof Error ? waitError.message : String(waitError);
+			const waitErrMsg = errorMessage(waitError);
 			return result(
 				[
 					`pi-crew run timed out or failed: ${updatedManifest.runId}`,
 					`Team: ${team.name}`,
 					`Workflow: ${workflow.name}`,
-					`Error: ${errorMessage}`,
+					`Error: ${waitErrMsg}`,
 					"",
 					`Check status with: team status runId=${updatedManifest.runId}`,
 					`State: ${updatedManifest.stateRoot}`,
@@ -970,13 +971,13 @@ export async function handleRun(params: TeamToolParamsValue, ctx: TeamContext):
 				workspaceId: ctx.sessionId ?? ctx.cwd,
 			});
 		} catch (waitError: unknown) {
-			const errorMessage = waitError instanceof Error ? waitError.message : String(waitError);
+			const waitErrMsg = errorMessage(waitError);
 			return result(
 				[
 					`pi-crew run timed out or failed: ${updatedManifest.runId}`,
 					`Team: ${team.name}`,
 					`Workflow: ${workflow.name}`,
-					`Error: ${errorMessage}`,
+					`Error: ${waitErrMsg}`,
 					"",
 					`Check status with: team status runId=${updatedManifest.runId}`,
 					`State: ${updatedManifest.stateRoot}`,

package/src/runtime/chain-runner.ts

@@ -10,6 +10,7 @@
  * @see docs/pi-boomerang-integration-plan.md
  */
 
+import { errorMessage } from "../utils/guards.ts";
 import type { ChainStep as DSLChainStep } from "./chain-parser.ts";
 import { parseChainDSL } from "./chain-parser.ts";
 import type { HandoffManager, HandoffSummary, TaskPacket, TaskResult } from "./handoff-manager.ts";
@@ -250,14 +251,14 @@ export class ChainRunner {
 					});
 				}
 			} catch (error) {
-				const errorMessage = error instanceof Error ? error.message : String(error);
+				const errMsg = errorMessage(error);
 
 				stepResults.push({
 					step: i + 1,
 					name: step.name,
 					outcome: "failure",
 					duration: Date.now() - stepStart,
-					error: errorMessage,
+					error: errMsg,
 				});
 
 				// Stop chain on failure unless configured to continue

package/src/runtime/pipeline-runner.ts

@@ -1,5 +1,6 @@
 import { errors } from "../errors.ts";
 import { appendEventAsync, flushEventLogBuffer } from "../state/event-log.ts";
+import { errorMessage } from "../utils/guards.ts";
 import type { WorkflowConfig } from "../workflows/workflow-config.ts";
 import { mapConcurrent } from "./parallel-utils.ts";
 
@@ -166,26 +167,26 @@ export class PipelineRunner {
 					});
 				} catch (error) {
 					const duration = Date.now() - stageStartTime;
-					const errorMessage = error instanceof Error ? error.message : String(error);
+					const errMsg = errorMessage(error);
 
 					if (effectiveStopOnError) {
 						stages.push({
 							name: stage.name,
 							status: "failed",
 							results: [],
-							error: errorMessage,
+							error: errMsg,
 							duration,
 						});
 
 						await appendEventAsync(eventsPath, {
 							type: "pipeline:stage_failed",
 							runId,
-							message: `Stage '${stage.name}' failed: ${errorMessage}`,
+							message: `Stage '${stage.name}' failed: ${errMsg}`,
 							data: {
 								stageIndex: i,
 								stageName: stage.name,
 								duration,
-								error: errorMessage,
+								error: errMsg,
 							},
 						});
 
@@ -193,7 +194,7 @@ export class PipelineRunner {
 							type: "pipeline:failed",
 							runId,
 							message: `Pipeline '${workflow.name}' failed at stage '${stage.name}'`,
-							data: { failedStage: stage.name, error: errorMessage },
+							data: { failedStage: stage.name, error: errMsg },
 						});
 
 						return {
@@ -207,7 +208,7 @@ export class PipelineRunner {
 							name: stage.name,
 							status: "failed",
 							results: [],
-							error: errorMessage,
+							error: errMsg,
 							duration,
 						});
 
@@ -219,7 +220,7 @@ export class PipelineRunner {
 								stageIndex: i,
 								stageName: stage.name,
 								duration,
-								error: errorMessage,
+								error: errMsg,
 							},
 						});
 					}

package/src/ui/live-run-sidebar.ts

@@ -8,8 +8,8 @@ import type { TeamTaskState } from "../state/types.ts";
 import { aggregateUsage, formatUsage } from "../state/usage.ts";
 import { readJsonFileCoalesced } from "../utils/file-coalescer.ts";
 import { pad, truncate } from "../utils/visual.ts";
-import { RenderScheduler } from "./render-scheduler.ts";
-import { runEventBusAsRenderScheduler } from "./run-event-bus.ts";
+import type { OverlaySchedulerHandle } from "./shared-overlay-scheduler.ts";
+import { registerOverlayScheduler } from "./shared-overlay-scheduler.ts";
 import type { RunSnapshotCache, RunUiSnapshot } from "./snapshot-types.ts";
 import { spinnerBucket, spinnerFrame } from "./spinner.ts";
 import { colorizeStatusGlyphs, iconForStatus } from "./status-colors.ts";
@@ -53,7 +53,7 @@ export class LiveRunSidebar {
 	private readonly theme: CrewTheme;
 	private readonly config: CrewUiConfig;
 	private readonly unsubscribeTheme: () => void;
-	private readonly renderScheduler: RenderScheduler;
+	private readonly schedulerHandle: OverlaySchedulerHandle;
 	private readonly snapshotCache?: RunSnapshotCache;
 	private cachedLines: string[] = [];
 	private cachedWidth = 0;
@@ -82,15 +82,7 @@ export class LiveRunSidebar {
 		// subscribing independently a single event triggered up to 9 callbacks
 		// and ~150 invalidates/sec under load. The scheduler collapses bursts
 		// into one debounced invalidate.
-		this.renderScheduler = new RenderScheduler(
-			runEventBusAsRenderScheduler(["run:state", "worker:lifecycle", "ui:invalidate"]),
-			() => this.invalidate(),
-			{
-				debounceMs: 75,
-				fallbackMs: 750,
-				events: ["run:state", "worker:lifecycle", "ui:invalidate"],
-			},
-		);
+		this.schedulerHandle = registerOverlayScheduler(() => this.invalidate());
 	}
 
 	private buildSignature(
@@ -150,7 +142,7 @@ export class LiveRunSidebar {
 			this.autoCloseTimeout = undefined;
 		}
 		this.unsubscribeTheme();
-		this.renderScheduler.dispose();
+		this.schedulerHandle.dispose();
 	}
 
 	render(width: number): string[] {
@@ -270,10 +262,12 @@ export class LiveRunSidebar {
 			if (isTerminal && !hasActiveAgents && !this.hasAutoClosed) {
 				const autoCloseMs = this.config?.autoCloseDashboardMs ?? 3000;
 				if (autoCloseMs > 0) {
+					if (this.autoCloseTimeout) clearTimeout(this.autoCloseTimeout);
 					this.autoCloseTimeout = setTimeout(() => {
 						this.hasAutoClosed = true;
 						this.done(undefined);
 					}, autoCloseMs);
+					this.autoCloseTimeout?.unref();
 					lines.push(line(`auto-close in ${Math.round(autoCloseMs / 1000)}s…`, w));
 				}
 			}

package/src/ui/loaders.ts

@@ -1,176 +1,6 @@
-import { pad, truncate } from "../utils/visual.ts";
-import { DynamicCrewBorder } from "./dynamic-border.ts";
-import type { CrewTheme } from "./theme-adapter.ts";
-import { asCrewTheme } from "./theme-adapter.ts";
-
-export interface BorderedLoaderOptions {
-	message: string;
-	cancellable?: boolean;
-	frames?: string[];
-	intervalMs?: number;
-	minWidth?: number;
-	onAbort?: () => void;
-}
-
-const DEFAULT_FRAMES = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
-
-export class CrewBorderedLoader {
-	private readonly abortController = new AbortController();
-	private readonly frameOptions: string[];
-	private readonly intervalMs: number;
-	private readonly minWidth: number;
-	private readonly onAbort?: () => void;
-	private theme: CrewTheme;
-	private message: string;
-	private lineCache = "";
-	private width = 0;
-	private startedAt = Date.now();
-
-	constructor(_ui: unknown, themeLike: unknown, options: BorderedLoaderOptions) {
-		const theme = asCrewTheme(themeLike);
-		this.theme = theme;
-		this.message = options.message;
-		this.minWidth = Math.max(12, options.minWidth ?? 24);
-		this.onAbort = options.onAbort;
-		this.frameOptions = options.frames ?? DEFAULT_FRAMES;
-		this.intervalMs = Math.max(40, options.intervalMs ?? 120);
-	}
-
-	private spinnerFrame(): string {
-		if (this.frameOptions.length === 0) return "•";
-		const elapsed = Date.now() - this.startedAt;
-		const index = Math.floor(elapsed / this.intervalMs) % this.frameOptions.length;
-		return this.frameOptions[Math.max(0, index)];
-	}
-
-	setMessage(message: string): void {
-		this.message = message;
-	}
-
-	get signal(): AbortSignal {
-		return this.abortController.signal;
-	}
-
-	handleInput(data: string): void {
-		if (!this.onAbort || this.abortController.signal.aborted) return;
-		if (data === "c" || data === "q" || data === "\u001b" || data === "\u0003") {
-			this.abortController.abort();
-			this.onAbort();
-		}
-	}
-
-	render(width: number): string[] {
-		if (width === this.width && this.lineCache) {
-			return this.lineCache.split("\n");
-		}
-		const innerWidth = Math.max(this.minWidth - 4, 1);
-		const contentWidth = Math.max(1, Math.min(width - 4, innerWidth));
-		const frame = this.spinnerFrame();
-		const loaderLine = ` ${frame} ${truncate(this.message, Math.max(1, contentWidth - 4))} `;
-		const body = ` ${truncate(loaderLine, contentWidth - 2)} `;
-		const inner = ` ${pad(body, contentWidth - 1)} `;
-		const padWidth = Math.max(0, width - (contentWidth + 4));
-		const leftRightPad = " ".repeat(Math.floor(padWidth / 2));
-		const widthAwareInner = contentWidth + padWidth;
-		const border = new DynamicCrewBorder(this.theme).render(widthAwareInner + 2)[0];
-		const top = `${leftRightPad}${this.theme.fg("border", "┌")}${border}${this.theme.fg("border", "┐")}`;
-		const line = `${leftRightPad}${this.theme.fg("border", "│")} ${truncate(inner, widthAwareInner)} ${this.theme.fg("border", "│")}`;
-		const hint = `${leftRightPad}${this.theme.fg("border", "│")}${" ".repeat(widthAwareInner + 2)}${this.theme.fg("border", "│")}`;
-		const bottom = `${leftRightPad}${this.theme.fg("border", "└")}${border}${this.theme.fg("border", "┘")}`;
-		const lineWithHint = optionsHint(this.theme, this.message, widthAwareInner);
-		this.width = width;
-		const lines = [top, line, `${leftRightPad}│ ${pad(lineWithHint, widthAwareInner)} │`, hint, bottom];
-		this.lineCache = lines.join("\n");
-		return lines;
-	}
-
-	invalidate(): void {
-		this.lineCache = "";
-		this.width = 0;
-	}
-
-	dispose(): void {
-		this.abortController.abort();
-	}
-}
-
-export interface CountdownTimerOptions {
-	timeoutMs: number;
-	onTick: (seconds: number) => void;
-	onExpire: () => void;
-}
-
-export class CountdownTimer {
-	private readonly onExpire: () => void;
-	private readonly onTick: (seconds: number) => void;
-	private readonly startedAt: number;
-	private readonly timeoutMs: number;
-	private timer: ReturnType<typeof setTimeout> | undefined;
-	private expired = false;
-	private lastEmittedSeconds = -1;
-
-	constructor(options: CountdownTimerOptions) {
-		this.timeoutMs = Math.max(0, options.timeoutMs);
-		this.onTick = options.onTick;
-		this.onExpire = options.onExpire;
-		this.startedAt = Date.now();
-		this.lastEmittedSeconds = this.secondsLeft();
-		this.onTick(this.lastEmittedSeconds);
-		if (this.timeoutMs === 0) {
-			this.emitExpire();
-			return;
-		}
-		this.scheduleNextTick();
-	}
-
-	/**
-	 * Schedule the next tick via recursive setTimeout. Each tick re-emits the
-	 * current `secondsLeft()` only if it differs from the last emitted value
-	 * (lastEmittedSeconds guard). This makes the countdown correct even under
-	 * event-loop pressure: if the previous tick fired 1.2s late, the next
-	 * tick still emits the right value for the current second rather than
-	 * skipping it (the pre-fix `setInterval` could SKIP a second value when
-	 * the loop was busy, producing [3,2,0] instead of [3,2,1,0] in tests).
-	 */
-	private scheduleNextTick(): void {
-		this.timer = setTimeout(() => {
-			const seconds = this.secondsLeft();
-			if (seconds !== this.lastEmittedSeconds) {
-				this.lastEmittedSeconds = seconds;
-				this.onTick(seconds);
-			}
-			if (seconds <= 0) {
-				this.emitExpire();
-				return;
-			}
-			this.scheduleNextTick();
-		}, 1000);
-		// Defense-in-depth: never let the countdown timer keep the event loop
-		// alive. If dispose() is missed (e.g. UI unmount race), the timer must
-		// not block process exit.
-		if (typeof this.timer.unref === "function") this.timer.unref();
-	}
-
-	private emitExpire(): void {
-		if (this.expired) return;
-		this.expired = true;
-		this.dispose();
-		this.onExpire();
-	}
-
-	private secondsLeft(): number {
-		const remainingMs = this.startedAt + this.timeoutMs - Date.now();
-		return Math.max(0, Math.ceil(remainingMs / 1000));
-	}
-
-	dispose(): void {
-		if (this.timer === undefined) return;
-		clearTimeout(this.timer);
-		this.timer = undefined;
-	}
-}
-
-function optionsHint(theme: CrewTheme, message: string, width: number): string {
-	if (!message) return "";
-	return truncate(theme.fg("muted", message), width);
-}
+/**
+ * CrewBorderedLoader and CountdownTimer were removed (UI-animation-audit C9).
+ * They were dead production code — referenced only by test/unit/loaders.test.ts
+ * (now deleted) and never instantiated in src/ or re-exported from the public
+ * index.  If a new loader component is needed, add it here.
+ */

package/src/ui/mascot.ts

@@ -99,6 +99,7 @@ export class AnimatedMascot {
 	private currentArminGrid: string[][];
 	private effectState: EffectState = {};
 	private effectDone = false;
+	private visible = true;
 	private frame = 0;
 	private effectPhase = 0;
 	private gridVersion = 0;
@@ -199,7 +200,10 @@ export class AnimatedMascot {
 			this.gridVersion++;
 		}
 		this.invalidate();
-		this.requestRender?.();
+		// Only request a re-render when the mascot is visible (not obscured by
+		// another overlay such as the dashboard or live sidebar).  This avoids
+		// pointless repaints on every animation frame while hidden.
+		if (this.visible) this.requestRender?.();
 	}
 
 	private tickArminEffect(): boolean {
@@ -226,7 +230,7 @@ export class AnimatedMascot {
 	private tickTypewriter(): boolean {
 		const state = this.effectState;
 		if (state.pos === undefined) return true;
-		for (let i = 0; i < 6; i++) {
+		for (let i = 0; i < 18; i++) {
 			const row = Math.floor(state.pos / ARMIN_WIDTH);
 			const x = state.pos % ARMIN_WIDTH;
 			if (row >= ARMIN_DISPLAY_HEIGHT) return true;
@@ -239,9 +243,11 @@ export class AnimatedMascot {
 	private tickScanline(): boolean {
 		const state = this.effectState;
 		if (state.row === undefined) return true;
-		if (state.row >= ARMIN_DISPLAY_HEIGHT) return true;
-		for (let x = 0; x < ARMIN_WIDTH; x++) this.currentArminGrid[state.row][x] = this.finalArminGrid[state.row][x];
-		state.row++;
+		for (let step = 0; step < 3; step++) {
+			if (state.row >= ARMIN_DISPLAY_HEIGHT) return true;
+			for (let x = 0; x < ARMIN_WIDTH; x++) this.currentArminGrid[state.row][x] = this.finalArminGrid[state.row][x];
+			state.row++;
+		}
 		return false;
 	}
 
@@ -264,7 +270,7 @@ export class AnimatedMascot {
 					break;
 				}
 			}
-			drop.y++;
+			drop.y += 3;
 			if (drop.y >= 0 && drop.y < ARMIN_DISPLAY_HEIGHT) {
 				if (targetRow >= 0 && drop.y >= targetRow) {
 					drop.settled = ARMIN_DISPLAY_HEIGHT - targetRow;
@@ -280,7 +286,7 @@ export class AnimatedMascot {
 	private tickFade(): boolean {
 		const state = this.effectState;
 		if (!state.positions || state.idx === undefined) return true;
-		for (let i = 0; i < 18; i++) {
+		for (let i = 0; i < 54; i++) {
 			if (state.idx >= state.positions.length) return true;
 			const [row, x] = state.positions[state.idx];
 			this.currentArminGrid[row][x] = this.finalArminGrid[row][x];
@@ -299,7 +305,7 @@ export class AnimatedMascot {
 		for (let row = Math.max(0, top); row <= Math.min(ARMIN_DISPLAY_HEIGHT - 1, bottom); row++) {
 			for (let x = 0; x < ARMIN_WIDTH; x++) this.currentArminGrid[row][x] = this.finalArminGrid[row][x];
 		}
-		state.expansion++;
+		state.expansion += 3;
 		return state.expansion > ARMIN_DISPLAY_HEIGHT;
 	}
 
@@ -321,7 +327,7 @@ export class AnimatedMascot {
 					}
 				}
 			}
-			state.phase++;
+			state.phase += 3;
 			return false;
 		}
 		// Restore final grid in-place
@@ -336,7 +342,7 @@ export class AnimatedMascot {
 	private tickDissolve(): boolean {
 		const state = this.effectState;
 		if (!state.positions || state.idx === undefined) return true;
-		for (let i = 0; i < 22; i++) {
+		for (let i = 0; i < 66; i++) {
 			if (state.idx >= state.positions.length) return true;
 			const [row, x] = state.positions[state.idx];
 			this.currentArminGrid[row][x] = this.finalArminGrid[row][x];
@@ -426,6 +432,15 @@ export class AnimatedMascot {
 		}
 	}
 
+	/**
+	 * Set whether the mascot is currently visible (not obscured by another
+	 * overlay).  When invisible, tick() skips requestRender so the animation
+	 * does not trigger needless repaints while hidden.
+	 */
+	setVisible(visible: boolean): void {
+		this.visible = visible;
+	}
+
 	dispose(): void {
 		this.doneGuard.called = true;
 		if (this.interval) clearInterval(this.interval);

package/src/ui/render-coalescer.ts

@@ -73,6 +73,15 @@ export class RenderCoalescer {
 			this.#timerId = null;
 		}
 		this.#pending = false;
+		const dropped = this.#dropped;
+		this.#dropped = 0;
+		if (dropped > 0) {
+			try {
+				this.#onDrop(dropped);
+			} catch {
+				/* drop callback errors are non-fatal */
+			}
+		}
 		this.#callback();
 	}
 

package/src/ui/render-scheduler.ts

@@ -21,6 +21,13 @@ export interface RenderSchedulerOptions {
 	 * trigger a single cache invalidate instead of N. Set to 0 to disable.
 	 */
 	invalidateCoalesceMs?: number;
+	/**
+	 * R1: maximum number of consecutive catch-up renders the fallback loop
+	 * emits while idle (no real external event) before it stops re-arming.
+	 * Prevents a hung run from rendering forever. A real event resets the
+	 * count and re-arms the loop. Defaults to 8.
+	 */
+	maxIdleFallbackRenders?: number;
 }
 
 const DEFAULT_EVENTS = [
@@ -34,6 +41,9 @@ const DEFAULT_EVENTS = [
 	"crew.mailbox.message",
 ];
 
+/** R4: max exponent for flush re-entrancy backoff (delay = debounceMs * 2^exp). */
+const CAP_BACKOFF_MAX_EXP = 5;
+
 /**
  * Coordinates UI renders with debounce + fallback polling.
  *
@@ -50,6 +60,7 @@ export class RenderScheduler {
 	private readonly fallbackProvider: () => number;
 	private readonly fallbackMs: number;
 	private readonly invalidateCoalesceMs: number;
+	private readonly maxIdleFallbackRenders: number;
 	private debounceTimer: ReturnType<typeof setTimeout> | undefined;
 	private fallbackTimer: ReturnType<typeof setTimeout> | undefined;
 	private invalidateTimer: ReturnType<typeof setTimeout> | undefined;
@@ -59,6 +70,10 @@ export class RenderScheduler {
 	private lastEventAt = 0;
 	private rendering = false;
 	private pendingRender = false;
+	/** R1: consecutive idle fallback renders since the last real event. */
+	private idleFallbackRenders = 0;
+	/** R4: consecutive re-entrancy cap-hits — drives exponential backoff. */
+	private consecutiveCapHits = 0;
 	private readonly unsubs: Array<() => void> = [];
 
 	constructor(events: RenderSchedulerEventBus | undefined, render: () => void, options: RenderSchedulerOptions = {}) {
@@ -69,6 +84,7 @@ export class RenderScheduler {
 		this.fallbackProvider = typeof fallback === "function" ? fallback : () => fallback;
 		this.fallbackMs = typeof fallback === "number" ? fallback : 750;
 		this.invalidateCoalesceMs = options.invalidateCoalesceMs ?? 50;
+		this.maxIdleFallbackRenders = options.maxIdleFallbackRenders ?? 8;
 		for (const event of options.events ?? DEFAULT_EVENTS) this.subscribe(events, event);
 		this.fallbackTimer = setTimeout(() => this.fallbackLoop(), this.currentFallbackMs());
 		this.fallbackTimer.unref();
@@ -100,13 +116,25 @@ export class RenderScheduler {
 		if (this.disposed) return;
 		const fallbackMs = this.currentFallbackMs();
 		if (Date.now() - this.lastEventAt < fallbackMs) {
-			if (this.disposed) return;
+			// A real external event arrived recently — not idle. Keep polling.
+			this.idleFallbackRenders = 0;
 			this.fallbackTimer = setTimeout(() => this.fallbackLoop(), fallbackMs);
 			this.fallbackTimer.unref();
 			return;
 		}
-		this.schedule();
-		if (this.disposed) return;
+		// R1: truly idle (no real event for `fallbackMs`). `lastEventAt` is only
+		// advanced by real external events (schedule()), so this idle check stays
+		// honest — unlike the old code which called schedule() here and thereby
+		// reset lastEventAt, self-perpetuating a ~fallbackMs render loop forever.
+		if (this.idleFallbackRenders >= this.maxIdleFallbackRenders) {
+			// Sustained idleness — stop re-arming so a hung run does not render
+			// forever. A subsequent real event (schedule()) re-arms the loop.
+			this.fallbackTimer = undefined;
+			return;
+		}
+		// Emit one catch-up render WITHOUT advancing lastEventAt (no real event).
+		this.armDebouncedRender();
+		this.idleFallbackRenders += 1;
 		this.fallbackTimer = setTimeout(() => this.fallbackLoop(), this.currentFallbackMs());
 		this.fallbackTimer.unref();
 	}
@@ -114,12 +142,30 @@ export class RenderScheduler {
 	schedule(payload?: unknown): void {
 		if (this.disposed) return;
 		this.lastEventAt = Date.now();
+		this.idleFallbackRenders = 0;
+		this.consecutiveCapHits = 0;
 		this.invalidate(payload);
+		this.armDebouncedRender();
+		// R1: if the fallback loop stopped itself after a sustained idle period,
+		// a real event means activity resumed — re-arm the safety-net loop.
+		if (!this.fallbackTimer) {
+			this.fallbackTimer = setTimeout(() => this.fallbackLoop(), this.currentFallbackMs());
+			this.fallbackTimer.unref();
+		}
+	}
+
+	/**
+	 * Arm (or re-arm) the debounce timer that triggers a single flush. Shared by
+	 * real-event schedules, the fallback path, and the re-entrancy cap drain.
+	 * `delay` lets the cap apply exponential backoff (R4) without touching
+	 * `lastEventAt` or `onInvalidate` (those belong to real external events).
+	 */
+	private armDebouncedRender(delay: number = this.debounceMs): void {
 		if (this.debounceTimer) clearTimeout(this.debounceTimer);
 		this.debounceTimer = setTimeout(() => {
 			this.debounceTimer = undefined;
 			this.flush();
-		}, this.debounceMs);
+		}, delay);
 		this.debounceTimer.unref();
 	}
 
@@ -196,9 +242,17 @@ export class RenderScheduler {
 			logInternalError("render-scheduler.render", error);
 		} finally {
 			this.rendering = false;
-			// If we hit the iteration cap, schedule one more render to drain.
+			// R4: if we hit the re-entrancy cap with more work pending, drain it —
+			// but with exponential backoff on consecutive cap-hits so a pathological
+			// render() cannot sustain a tight debounceMs render loop. We re-arm via
+			// armDebouncedRender (not schedule()) so lastEventAt / onInvalidate are
+			// not perturbed by a pure re-entrancy drain.
 			if (iterations >= 5 && this.pendingRender && !this.disposed) {
-				this.schedule();
+				this.consecutiveCapHits += 1;
+				const exp = Math.min(this.consecutiveCapHits - 1, CAP_BACKOFF_MAX_EXP);
+				this.armDebouncedRender(this.debounceMs * 2 ** exp);
+			} else {
+				this.consecutiveCapHits = 0;
 			}
 		}
 	}