pi-crew 0.9.50 → 0.9.51

package/docs/decisions/2026-07-26-c6-mascot-visibility-not-wired.md

@@ -0,0 +1,84 @@
+# C6 — mascot visibility gate: NOT WIRED (closed)
+
+**Date:** 2026-07-26
+**Status:** CLOSED — gate kept (tested), wiring intentionally NOT done
+**Supersedes / closes:** finding C6 in `reports/ui-animation-audit-2026-07-24.md`
+
+## Context
+
+UI-animation-audit finding **C6** (LOW): `src/ui/mascot.ts` `tick()` calls
+`requestRender()` unconditionally, even when the mascot overlay is obscured by
+another overlay on top. The audit suggested adding a visibility flag
+(`setVisible()`), gated by a note: *"needs visibility flag infrastructure;
+bounded by 7s auto-close so low priority."*
+
+The `setVisible()` gate was implemented + unit-tested (`mascot.ts:440`,
+`test/unit/mascot.test.ts` "AnimatedMascot does not requestRender when
+invisible (C6)"). The remaining question was whether to **wire** it — i.e.,
+have a caller invoke `setVisible(false)` when the mascot is obscured.
+
+## Investigation
+
+Read the pi source (`earendil-works/pi` @ `cee5ff75`) to determine whether an
+overlay component can know it is obscured:
+
+- **`ctx.ui.custom()` exposes `onHandle?: (handle: OverlayHandle) => void`**
+  (`packages/coding-agent/.../interactive-mode.ts:2448`). The `OverlayHandle`
+  offers `isFocused()` — a usable *proxy* for "not obscured" (a capturing
+  overlay loses focus when another opens on top). So wiring IS technically
+  feasible (~5 lines: `onHandle` → `mascot.setOverlayHandle(h)`; `tick()` sets
+  `this.visible = !h || h.isFocused()`).
+- **BUT pi composites ALL non-hidden overlays** (`packages/tui/src/tui.ts:1044`
+  filters `visibleEntries`, then `component.render()` at `:1054` for each).
+  `isOverlayVisible` checks only the `hidden` flag + a terminal-dimension
+  callback — **it does not account for obscuring.** So when the mascot is
+  obscured, the host STILL calls `mascot.render()` (the output is computed then
+  painted over by the overlay above).
+
+## Decision
+
+**Do NOT wire C6.** Keep the tested `setVisible()` gate (harmless, ready if pi
+ever exposes a true visibility signal), but do not add the `onHandle`/`isFocused`
+wiring.
+
+## Rationale
+
+C6 does not save the work it appears to target:
+
+| Aspect | Saved by C6 wiring? |
+|---|---|
+| Mascot's `render()` (the actual paint work — ~31-col image) | **No** — host calls it during compositing regardless (`visibleEntries` includes the non-hidden mascot) |
+| Mascot's animation state advancement in `tick()` | **No** — the gate is on `requestRender` only; the animation computation still runs |
+| Mascot's `requestRender()` pokes | Yes — but these are **cheap + render-coalesced + redundant** whenever the obscuring overlay is itself active (dashboard/settings/mailbox all drive their own repaints) |
+
+The only scenario where C6 saves a *real* repaint is: mascot obscured by a
+**static, non-render-requesting** overlay. That is rare, bounded to the
+mascot's **7 s auto-close** window, and even there the `render()` work still
+runs. Net measurable benefit: near zero.
+
+Contrast with the sibling findings that DID land: **C1** (30→10 fps) cut
+repaint pressure 3× on *every* mascot frame and fixed Windows flicker; **C3**
+(shared scheduler) cut 9→3 subscriptions/timers and per-event `schedule()` CPU
+in active runs. C6 is an order of magnitude below either.
+
+## Consequences
+
+- The `setVisible()` gate stays in `mascot.ts` (tested, documented here as
+  intentionally unwired). Future callers can use it if a true visibility signal
+  becomes available.
+- The **correct** fix for "render the mascot when obscured" is a **pi-core
+  compositing optimization**: skip `render()` for overlays fully occluded by a
+  higher opaque overlay. That belongs upstream in `packages/tui/src/tui.ts`
+  (the `visibleEntries` compositing loop), not in pi-crew. Track as a pi
+  upstream suggestion, not a pi-crew task.
+- `isFocused()` is an imperfect proxy anyway (a *non-capturing* overlay on top
+  would not steal focus, so the mascot would stay "focused" while painted over
+  — a false-negative). Wiring it would trade a rare wasted repaint for a
+  semantic mismatch; not worth it.
+
+## Verification
+
+- `setVisible()` gate: `test/unit/mascot.test.ts` → 7/7 pass (incl. the C6
+  "does not requestRender when invisible" test).
+- No production caller of `setVisible()` exists (grep confirms); the gate is
+  inert but correct.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-crew",
-  "version": "0.9.50",
+  "version": "0.9.51",
   "description": "Pi extension for coordinated AI teams, workflows, worktrees, and async task orchestration",
   "author": "baphuongna",
   "license": "MIT",

package/skills/distill-software/SKILL.md

@@ -9,6 +9,9 @@ triggers:
   - "how does this codebase do things"
   - "distill software expertise"
   - "distill [repo] conventions"
+  - "distill [source] to [target]"
+  - "port [source] features to [target]"
+  - "bring [source] capabilities to [target]"
 ---
 
 # distill-software
@@ -120,6 +123,11 @@ Ask (defaults provided; never block value):
 4. **Cost tier** (quote before Phase 1): quick (3 streams) / standard (6+extra) / deep (full archive). Codebase sweep scales with repo size.
 5. **Ethics** (engineer flavor, living non-public colleague): consent gate — require subject-provided material + consent flag (inherited M-F3).
 6. **Decomposition for large targets** (Core Principle #6 — decide HERE): if the repo is large (>200 files OR >5 subsystems/packages), decompose into sub-targets and distill each, then merge. Never ôm đồm (take it all at once). Decompose by **package/subsystem** (each gets its own coverage-manifest + 3-empty-rounds gate); then sweep the **cross-cutting** conventions (the ones spanning packages). Record the decomposition tree in `DISTILLATION-PROCESS-CHECKLIST.md`. Recursive if a sub-package is still large.
+7. **🔴 Transfer vs Audit mode** (learned from real runs: audit-only distillation produced 0 visible features for the target). Default = **Transfer** (user says "distill X to Y" → they want Y to GAIN capabilities from X). Two modes:
+   - **Transfer mode** ⭐ (default for "distill X to/about/into Y"): enumerate source **CAPABILITIES** (features, not files) → compare against target **CAPABILITY DEPTH** (not surface) → apply the gaps. Deliverable = visible/behavioral new features in target. "The user can SEE or EXPERIENCE the difference."
+   - **Audit mode**: enumerate source conventions → compare against target surface → apply pattern refactors/lint rules. Deliverable = cleaner code, invisible refactors.
+   - **Detection**: "distill X to/about/into Y" / "port X features" / "bring X to Y" → **Transfer**. "audit X conventions" / "how does X do Y" / "what can Y learn from X's conventions" → **Audit**. **When in doubt → Transfer** (audit is a subset — transfer includes convention adoption as a side effect).
+   - **Decomposition follows mode**: Transfer mode decomposes by **CAPABILITY BUCKET** (terminal/PTY, plugin system, markdown rendering, routing) NOT by directory (`components/`, `lib/`). Audit mode decomposes by package/subsystem (existing Principle #6).
 
 ## Phase 0.5 — ANALYZE TARGET
 
@@ -208,7 +216,8 @@ Mỗi verified model đi qua 3-chiều filter against the TARGET (KHÔNG phải
    ❌ KHÔNG → NECESSITY: target CẦN không?
       ❌ KHÔNG CẦN → SKIP (complexity vô ích).
       ✅ CẦN       → ADOPT (thêm mới).
-   ✅ CÓ → QUALITY COMPARISON:
+   ✅ CÓ → **🔴 CAPABILITY DEPTH check**: "target has a similar SURFACE" ≠ "target has the same CAPABILITY". Surface match (target has an extension-point system) can mask a capability gap (target lacks route-level extensibility — the distinctive feature). Before SKIP on PRESENCE=yes, verify the target has the FULL capability at the FEATURE level, not just a similarly-named file/module. If target has a SUBSET → the missing subset is an ADOPT candidate (transfer the gap), NOT a SKIP.
+   Then QUALITY COMPARISON:
       Source TỐT HƠN   → IMPROVE (thay bằng cách source).
       Source BẰNG/TỆ → SKIP.
       COMPLEMENTARY  → MERGE.
@@ -294,6 +303,12 @@ Mỗi TO-APPLY item → HOW to apply, then APPLY. Plan channels: AGENTS.md updat
   (e) Mỗi destructive action cần confirmation riêng.
   (f) Atomic writes (temp sibling + rename) — không ghi dở.
 - **APPLY-LOG.md**: every edit recorded (file:line + before→after + verification). ≥3 items required before "done". This is THE deliverable proof — NOT a SKILL.md.
+- **🔴 Post-APPLY integration checks (learned from real runs: artifact-level gates were ALL-GREEN while code had 12 runtime bugs; multiple review rounds were needed to find them):**
+  (g) **WIRED** — is the applied code actually CALLED by existing code? `grep -rn '<exported-symbol>' target-src/` — if 0 hits outside the defining file, it's DEAD CODE. Wire it into a consumer or remove it. (Observed: a routing-merge function was exported but never called by the app shell; a component prop was added but no consumer passed it.)
+  (h) **VISIBLE DELTA** — can the user SEE or EXPERIENCE the difference? If the apply is a pure refactor (same behavior, different code structure), it is NOT a capability transfer — flag it. Transfer mode (Phase 0 #7) REQUIRES visible deltas; invisible refactors are Audit-mode artifacts.
+  (i) **RUNTIME** — does the feature WORK in the real system? Don't just run unit tests — run the BUILD (`tsc --noEmit`, `vite build`, `cargo build`) AND, if the feature spans runtime boundaries (server + client, gateway + web), test END-TO-END (start the server, hit the endpoint, verify the response). Unit tests passing ≠ feature working. (Observed: a component passed unit tests but crashed in a real browser — missing vendor API flags and browser-only globals that the test environment mocked away.)
+  (j) **API VERIFIED** — before USING any target API (component prop, function signature, config option), READ ITS SOURCE to confirm the API matches your usage. Do NOT assume props exist. (Observed: code used a component prop that doesn't exist in its interface; the TypeScript object-literal excess-property check was silently bypassed.) This is the APPLY-phase analog of Phase 1's "excavate, don't recall".
+  (k) **RESOURCE LIFECYCLE** — if the applied code spawns processes, opens connections, registers listeners, or creates timers: verify CLEANUP on ALL exit paths (close, dispose, kill, unsubscribe). A missing disconnect handler that kills child processes = orphan leak. (Observed: a server endpoint spawned shell commands but never killed them when the client disconnected — process leak.)
 
 ## Phase 4 — VERIFY TARGET IMPROVED (Fidelity + Darwin ratchet, inherited F2' + software edge)
 
@@ -343,6 +358,9 @@ Refuse to ship if ANY fails; iterate Phase 2→4 until green:
 - [ ] **Coverage manifest complete** (inherited exhaustive-sweep): every content-bearing part UNCOVERED→COVERED or `[UNREADABLE — reason]`; no dangling UNCOVERED rows at ship time (the codebase analog of persona's no-dangling-checklist rule).
 - [ ] **DISTILLATION-PROCESS-CHECKLIST.md present + every phase ✅** (no ⬜/⏳ dangling) — proves no phase skipped
 - [ ] **3-empty-rounds gate fired** for every sweep/synthesis phase (≥3 consecutive zero-new rounds recorded in the round log) — proves deep-dive wasn't cut short at 1-2 passes
+- [ ] **🔴 Runtime verification**: full regression `npx vitest run` (or project test runner) passes with 0 failures — NOT just the new test file, the FULL suite. `npx tsc --noEmit` (or project typechecker) introduces 0 NEW errors. `vite build` / `cargo build` / `npm run build` succeeds.
+- [ ] **🔴 Applied code is WIRED** — every new export/function/component is imported + called by ≥1 existing file (grep proof in APPLY-LOG). Dead code (exported but never imported) = failed apply.
+- [ ] **🔴 VISIBLE DELTA** (Transfer mode only) — the user can see or experience the difference. Invisible refactors require Audit-mode justification.
 
 > **Tiered effort (#8)**: for a trivial distillation (single small file, <5 conventions) you may skip the costliest sub-step (the independent dual-agent fidelity re-score → self-score with the single-agent caveat) — but never skip the structural, V5-grep, coverage, or ungrep-ratio gates.
 
@@ -358,6 +376,11 @@ Refuse to ship if ANY fails; iterate Phase 2→4 until green:
 | 7 | Recency erasure (engineer reversed a stance) | Skill presents current-only view; hides evolution | preserve as temporal contradiction; "近期观点" prevails, old mentioned |
 | 8 | Orphaned operational scripts | Scripts exist but agent never invokes them → dead code | wire INTO Agentic Protocol Step 2 (F13) |
 | 9 | Single-source monoculture (domain skill) | One-source bias; no cross-verification | topic skills cite ≥3 independent sources |
+| 10 | **Audit-only when user wanted Transfer** — "distill X to Y" produces invisible refactors (routing table, lint config) not visible features | User sees nothing new; 0 visible delta = failed transfer | Phase 0 #7 Transfer-vs-Audit routing (default Transfer); VISIBLE DELTA check in Phase 3 + ship-gate |
+| 11 | **Surface-match SKIP masks capability gap** — target has an extension-point module → SKIP, but target lacks route-level extensibility (the distinctive capability) | Misses the highest-value transfers; filter is correct on paper, wrong in DEPTH | Phase 2.5 CAPABILITY DEPTH check: PRESENCE=yes → verify FULL capability at FEATURE level, not just surface |
+| 12 | **Applied code is dead (never wired)** — a routing function is exported but never called; a component prop is added but no consumer passes it | APPLY-LOG says "applied" but target behavior unchanged; user sees nothing | Phase 3 (g) WIRED check (grep for usage); ship-gate WIRED assertion |
+| 13 | **Unit tests pass but feature doesn't work** — tests mock the environment (jsdom lacks canvas/matchMedia/ResizeObserver) but the real browser needs them; a server endpoint has 0 integration test | Green CI, broken runtime; multiple review rounds needed to find bugs | Phase 3 (i) RUNTIME check (build + end-to-end); ship-gate runtime verification |
+| 14 | **Missing resource cleanup** — spawned child processes, open WebSockets, registered listeners never cleaned up on disconnect/unmount | Orphaned processes accumulate; memory/connection leaks in production | Phase 3 (k) RESOURCE LIFECYCLE check (verify cleanup on ALL exit paths) |
 
 ## Self-containment
 This engine embeds its methodology inline (inherited from distill-persona). The methodology is self-contained (copy dir → runs); `language`+`distilled_against` make the extraction's staleness auditable.

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[] {

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 {
@@ -428,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-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;
 			}
 		}
 	}

package/src/ui/run-dashboard.ts

@@ -20,8 +20,8 @@ import { renderTranscriptPane } from "./dashboard-panes/transcript-pane.ts";
 import { DynamicCrewBorder } from "./dynamic-border.ts";
 import { dashboardActionForKey } from "./keybinding-map.ts";
 import { HelpOverlay } from "./overlays/help-overlay.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 { applyStatusColor, colorizeStatusGlyphs, iconForStatus, type RunStatus } from "./status-colors.ts";
@@ -423,7 +423,7 @@ export class RunDashboard implements DashboardComponent {
 	private cachedSignatureAt = 0;
 	private cachedSignature = "";
 	private readonly unsubscribeTheme: () => void;
-	private readonly renderScheduler: RenderScheduler | undefined;
+	private readonly schedulerHandle: OverlaySchedulerHandle | undefined;
 
 	constructor(
 		runs: TeamRunManifest[],
@@ -466,21 +466,12 @@ export class RunDashboard implements DashboardComponent {
 		const renderTick = (): void => {
 			this.invalidateAndRender();
 		};
-		this.renderScheduler = new RenderScheduler(
-			runEventBusAsRenderScheduler(["run:state", "worker:lifecycle", "ui:invalidate"]),
-			renderTick,
-			{
-				debounceMs: 75,
-				fallbackMs: 750,
-				events: ["run:state", "worker:lifecycle", "ui:invalidate"],
-				onInvalidate: () => {
-					// Drop any cached signature — data underneath may have
-					// changed so the next buildSignature() needs to recompute.
-					this.cachedSignature = "";
-					this.cachedSignatureAt = 0;
-				},
-			},
-		);
+		this.schedulerHandle = registerOverlayScheduler(renderTick, () => {
+			// Drop any cached signature — data underneath may have
+			// changed so the next buildSignature() needs to recompute.
+			this.cachedSignature = "";
+			this.cachedSignatureAt = 0;
+		});
 		// FIND-07: route theme changes through the scheduler so they coalesce
 		// with run:state / worker:lifecycle / ui:invalidate bursts instead of
 		// each firing their own immediate invalidate+requestRender.
@@ -498,8 +489,8 @@ export class RunDashboard implements DashboardComponent {
 	 * (defensive — currently always created in the constructor).
 	 */
 	private scheduleRender(): void {
-		if (this.renderScheduler) {
-			this.renderScheduler.schedule();
+		if (this.schedulerHandle) {
+			this.schedulerHandle.schedule();
 			return;
 		}
 		this.invalidateAndRender();
@@ -619,7 +610,7 @@ export class RunDashboard implements DashboardComponent {
 
 	dispose(): void {
 		this.unsubscribeTheme();
-		this.renderScheduler?.dispose();
+		this.schedulerHandle?.dispose();
 	}
 
 	private selectedRunId(): string | undefined {