pi-mega-compact 0.8.14 → 0.8.16

package/dist/extensions/mega-events/agent-handlers.js

@@ -4,6 +4,7 @@ import { recordScore } from "../../src/store/sqlite.js";
 import { evaluateAndUnlockAchievements } from "../../src/store/sqlite/game-achievements.js";
 import { isMegaCache } from "../../src/game/scoring.js";
 import { resolveRepoRoot } from "../mega-config.js";
+import { classifyError } from "./error-classifier.js";
 /** Register agent/turn tracking event handlers. */
 export function registerAgentHandlers(pi, runtime, config) {
     // ---- Agent tracking for real-time widget + status-line updates ---------
@@ -37,10 +38,31 @@ export function registerAgentHandlers(pi, runtime, config) {
                 const idle = ctx.isIdle?.() ?? true;
                 const queued = ctx.hasPendingMessages?.() ?? false;
                 const now = Date.now();
+                // S38.5: read LIVE pressure from ctx.getContextUsage() instead of the
+                // stale runtime.lastCtxTokens (only updated by the `context` event).
+                // agent_end may fire without a preceding context event this turn (e.g.
+                // a sub-agent settling), so the cached value can be null/stale and the
+                // durable-trim branch would be unreachable. ctx.getContextUsage() is the
+                // authoritative live reading (mirrors context-handler.ts:86). Fall back
+                // to the cached value only if the ctx omits it.
+                const liveUsage = ctx.getContextUsage?.();
+                const liveTokens = typeof liveUsage?.tokens === "number"
+                    ? liveUsage.tokens
+                    : runtime.lastCtxTokens ?? 0;
+                // Keep the cache fresh for snapshot()/diag regardless of which source we use.
+                if (typeof liveUsage?.tokens === "number") {
+                    runtime.lastCtxTokens = liveUsage.tokens;
+                }
+                if (typeof liveUsage?.percent === "number") {
+                    runtime.lastCtxPercent = liveUsage.percent;
+                }
+                if (typeof liveUsage?.contextWindow === "number") {
+                    runtime.lastCtxWindow = liveUsage.contextWindow;
+                }
                 // DIAG (team-run relief): surface whether the agent is idle + over
                 // threshold at agent_end so we can see if a mid-run durable-trim trigger
                 // *should* have fired but didn't.
-                const overThreshold = (runtime.lastCtxTokens ?? 0) >= runtime.effectiveThreshold;
+                const overThreshold = liveTokens >= runtime.effectiveThreshold;
                 runtime.diagAgentEndIdle++;
                 runtime.logger.info("agent-end-idle", {
                     sessionId: runtime.rt.sessionId,
@@ -87,11 +109,20 @@ export function registerAgentHandlers(pi, runtime, config) {
                     // synchronous `piCompactWouldNoop` branch check misses a native
                     // compaction that hasn't appended its entry yet — calling
                     // ctx.compact() then races with pi and throws "Already compacted"
-                    // to the user. The `lastCompactAt` cooldown (updated by the
+                    // to the user. The `lastNativeCompactAt` cooldown (updated by the
                     // session_compact listener for EVERY compaction, native or
                     // extension-supplied) closes that race window.
+                    //
+                    // S38.5: strict race guard widens the cooldown 10s -> 30s AND defers
+                    // ctx.compact() via setTimeout(500) with a re-check, so pi's
+                    // about-to-run native _checkCompaction can append its `compaction`
+                    // branch entry first (closes the first-race-in-burst window). Gated
+                    // by MEGACOMPACT_RACE_GUARD_STRICT (default true); false reverts to
+                    // the v0.7.4 synchronous 10s guard. Mirrors the legacy path in
+                    // context-handler.ts:258-287 so both call sites stay in sync.
+                    const cooldownMs = config.raceGuardStrict ? 30_000 : 10_000;
                     const sinceCompact = now - (runtime.rt.lastNativeCompactAt ?? 0);
-                    if (sinceCompact < 10_000) {
+                    if (sinceCompact < cooldownMs) {
                         runtime.diagAgentEndDurableSkipRecent++;
                     }
                     else if (!piCompactWouldNoop(ctx)) {
@@ -103,7 +134,35 @@ export function registerAgentHandlers(pi, runtime, config) {
                             thresholdTokens: config.thresholdTokens,
                             queued,
                         });
-                        ctx.compact({ customInstructions: undefined }); // guardrails-allow PREVENT-PI-004: local ctx.compact() — no network; agent settled so no in-flight abort. Race-guarded by lastCompactAt cooldown above (ctx.compact returns void → throw is surfaced by pi as compaction_end; the cooldown prevents the call entirely).
+                        if (config.raceGuardStrict) {
+                            // Strict: defer ctx.compact() with a re-check so pi's
+                            // about-to-run native _checkCompaction can append its
+                            // `compaction` branch entry first. setTimeout(500) — pi's
+                            // compaction-summary append is async I/O, so queueMicrotask
+                            // would re-check before it lands.
+                            const stamp = runtime.rt.lastNativeCompactAt;
+                            const liveSid = runtime.rt.sessionId;
+                            setTimeout(() => {
+                                try {
+                                    if (runtime.rt.sessionId !== liveSid)
+                                        return; // session reset
+                                    const since2 = now - (runtime.rt.lastNativeCompactAt ?? 0);
+                                    if (runtime.rt.lastNativeCompactAt !== stamp && since2 < cooldownMs)
+                                        return;
+                                    if (piCompactWouldNoop(ctx))
+                                        return;
+                                    ctx.compact({
+                                        customInstructions: undefined,
+                                    }); // guardrails-allow PREVENT-PI-004: local ctx.compact() — no network; deferred + re-validated.
+                                }
+                                catch {
+                                    /* non-fatal */
+                                }
+                            }, 500);
+                        }
+                        else {
+                            ctx.compact({ customInstructions: undefined }); // guardrails-allow PREVENT-PI-004: local ctx.compact() — no network; agent settled so no in-flight abort. Race-guarded by lastNativeCompactAt cooldown above (ctx.compact returns void → throw is surfaced by pi as compaction_end; the cooldown prevents the call entirely).
+                        }
                         didDurableTrim = true;
                     }
                 }
@@ -141,6 +200,7 @@ export function registerAgentHandlers(pi, runtime, config) {
     pi.on("turn_start", async (event, ctx) => {
         runtime.currentTurn = event.turnIndex;
         runtime.rt.lengthStopPending = false; // S28: re-arm defensively each user turn
+        runtime.rt.errorRetryCount = 0; // S38: reset error-retry counter each user turn
         runtime.dashboard.event("turn_start", { turnIndex: event.turnIndex });
         runtime.snapshot(ctx);
     });
@@ -218,5 +278,125 @@ export function registerAgentHandlers(pi, runtime, config) {
             runtime.rt.lengthStopPending = true;
             runtime.dashboard.event("length_stop", { turnIndex: event.turnIndex });
         }
+        // S38: broader error-retry safety net. S28 only catches stopReason==='length';
+        // this catches ALL other error types (provider failure, network timeout, 5xx,
+        // 429, auth, compaction-noop) that surface at turn_end. Non-fatal: wrapped in
+        // try/catch so a classifier/retry failure never breaks the agent loop.
+        // PREVENT-PI-003: retry nudge fires via pi.sendUserMessage (user-role).
+        try {
+            // (1) S28 owns length — skip the classifier entirely for it.
+            const sr = event.message?.stopReason;
+            if (sr === 'length') {
+                // S28 handles; nothing for S38 to do here.
+            }
+            else {
+                const category = classifyError(event.message);
+                if (category === null) {
+                    // (3) success / normal flow / unknown-but-non-retryable — reset.
+                    runtime.rt.errorRetryCount = 0;
+                    runtime.rt.consecutiveErrors = 0; // S38.6: circuit-breaker reset on success
+                }
+                else if (category === 'compaction-noop') {
+                    // (4) pi race / manual compact catch — NOT retryable. The compaction
+                    // already succeeded via pi's native path; retrying would race again
+                    // (FAIL-2026071701). Log a diagnostic, reset the counter, and surface
+                    // the original error WITHOUT firing a retry nudge.
+                    runtime.rt.errorRetryCount = 0;
+                    runtime.rt.consecutiveErrors = 0; // S38.6: circuit-breaker reset
+                    runtime.dashboard.event('compaction_noop_diagnostic', {
+                        turnIndex: event.turnIndex,
+                        sessionId: runtime.rt.sessionId,
+                    });
+                    runtime.logger.info('compaction-noop-diagnostic', {
+                        sessionId: runtime.rt.sessionId,
+                        turnIndex: event.turnIndex,
+                    });
+                }
+                else {
+                    // (5) transient or permanent — retry with exponential backoff.
+                    // S38.7: hard-stop switch — bypass ALL retry logic when set.
+                    if (config.errorRetryHardStop) {
+                        runtime.rt.errorRetryCount = 0;
+                        runtime.dashboard.event('error_retry_disabled', {
+                            category,
+                            turnIndex: event.turnIndex,
+                            reason: 'hard-stop',
+                        });
+                        return; // early exit — no retry
+                    }
+                    // S38.6: circuit-breaker — stop retrying after too many consecutive errors.
+                    runtime.rt.consecutiveErrors++;
+                    if (runtime.rt.consecutiveErrors > config.maxConsecutiveErrors) {
+                        runtime.dashboard.event('error_retry_circuit_open', {
+                            consecutive: runtime.rt.consecutiveErrors,
+                            max: config.maxConsecutiveErrors,
+                            turnIndex: event.turnIndex,
+                        });
+                        runtime.logger.warn('error-retry-circuit-open', {
+                            sessionId: runtime.rt.sessionId,
+                            consecutive: runtime.rt.consecutiveErrors,
+                            max: config.maxConsecutiveErrors,
+                        });
+                        return; // early exit — circuit breaker tripped
+                    }
+                    const max = category === 'transient'
+                        ? config.autoRetryTransientMax
+                        : config.autoRetryPermanentMax;
+                    // max === 0 disables the category entirely (revert to S28-only).
+                    if (max <= 0) {
+                        runtime.rt.errorRetryCount = 0;
+                    }
+                    else {
+                        runtime.rt.errorRetryCount++;
+                        if (runtime.rt.errorRetryCount > max) {
+                            // Exhausted — surface the error, reset for the next burst.
+                            runtime.dashboard.event('error_retry_exhausted', {
+                                category,
+                                count: runtime.rt.errorRetryCount,
+                                max,
+                                turnIndex: event.turnIndex,
+                            });
+                            runtime.logger.info('error-retry-exhausted', {
+                                sessionId: runtime.rt.sessionId,
+                                category,
+                                count: runtime.rt.errorRetryCount,
+                                max,
+                            });
+                            runtime.rt.errorRetryCount = 0;
+                        }
+                        else {
+                            // S38: fire the retry nudge. Each error turn fires its own
+                            // nudge up to `max` — we intentionally do NOT debounce on the
+                            // backoff window (errorRetryUntil) here, because that would
+                            // suppress turns 2..max on a fast-erroring provider (the exact
+                            // scenario this feature targets) and the user could see zero
+                            // retries followed by error_retry_exhausted. The per-turn cap
+                            // (errorRetryCount <= max) plus the session circuit breaker
+                            // (consecutiveErrors > maxConsecutiveErrors) already bound the
+                            // loop, so a tight turn_end storm cannot busy-loop unbounded.
+                            // errorRetryUntil + errorRetryBackoffMs() are retained on the
+                            // runtime for future/optional pacing but are not gating.
+                            runtime.dashboard.event('error_retry', {
+                                category,
+                                count: runtime.rt.errorRetryCount,
+                                max,
+                                turnIndex: event.turnIndex,
+                            });
+                            runtime.logger.info('error-retry', {
+                                sessionId: runtime.rt.sessionId,
+                                category,
+                                count: runtime.rt.errorRetryCount,
+                                max,
+                            });
+                            // PREVENT-PI-003: user-role sendUserMessage only.
+                            pi.sendUserMessage('[mega-compact] the last turn ended with an error; please retry.');
+                        }
+                    }
+                }
+            }
+        }
+        catch {
+            /* non-fatal: a classifier/retry failure never breaks the agent loop */
+        }
     });
 }

package/dist/extensions/mega-events/context-handler.js

@@ -208,10 +208,43 @@ export function registerContextHandler(pi, runtime, config) {
             // NATIVE compaction just fired (avoids racing pi and surfacing a spurious
             // "Already compacted" / "Nothing to compact" toast). Uses lastNativeCompactAt
             // (NOT lastCompactAt, which runCompact also stamps for our own checkpoint).
+            // S38.5: strict race guard widens the cooldown 10s -> 30s (gated by
+            // MEGACOMPACT_RACE_GUARD_STRICT; false reverts to v0.7.4 10s).
+            const cooldownMs = config.raceGuardStrict ? 30_000 : 10_000;
             const sinceCompact = Date.now() - (runtime.rt.lastNativeCompactAt ?? 0);
-            if (sinceCompact < 10_000 || piCompactWouldNoop(ctx))
+            if (sinceCompact < cooldownMs || piCompactWouldNoop(ctx))
                 return;
-            ctx.compact({ customInstructions: undefined }); // race-guarded by lastNativeCompactAt cooldown (ctx.compact returns void → not catchable; the cooldown prevents the call)
+            // S38.5: defer ctx.compact() with a re-check so pi's about-to-run native
+            // _checkCompaction can append its `compaction` branch entry first (closes
+            // the first-race-in-burst window). setTimeout(500) — pi's compaction-summary
+            // append is async I/O, so queueMicrotask would re-check before it lands.
+            // Non-strict (v0.7.4) keeps the synchronous call.
+            if (config.raceGuardStrict) {
+                const stamp = runtime.rt.lastNativeCompactAt;
+                const liveSid = runtime.rt.sessionId;
+                setTimeout(() => {
+                    try {
+                        if (runtime.rt.sessionId !== liveSid)
+                            return; // session reset
+                        const since2 = Date.now() - (runtime.rt.lastNativeCompactAt ?? 0);
+                        if (runtime.rt.lastNativeCompactAt !== stamp && since2 < cooldownMs)
+                            return;
+                        if (piCompactWouldNoop(ctx))
+                            return;
+                        ctx.compact({
+                            customInstructions: undefined,
+                        }); // guardrails-allow PREVENT-PI-004: local ctx.compact() — no network; deferred + re-validated.
+                    }
+                    catch {
+                        /* non-fatal */
+                    }
+                }, 500);
+            }
+            else {
+                ctx.compact({
+                    customInstructions: undefined,
+                }); // race-guarded by lastNativeCompactAt cooldown (ctx.compact returns void → not catchable; the cooldown prevents the call)
+            }
             return;
         }
         // S16 LIVE trim: collapse the compacted region to a summary + recent anchor.

package/dist/extensions/mega-events/error-classifier.js

@@ -0,0 +1,118 @@
+/**
+ * error-classifier.ts — S38.2 error classification for retry logic.
+ *
+ * Classifies turn-end error/stop signals into retry categories.
+ * Ordering matters: compaction-noop is matched BEFORE generic transient
+ * so a pi race / manual compact catch is never misclassified.
+ */
+/** S38.2: classify a turn-end error/stop signal into a retry category.
+ *
+ * `length` is returned as null — S28 owns the max-output-token length stopReason
+ * exclusively (its agent_end nudge path is separate and must not be doubled).
+ *
+ * @param message  the event.message (a pi AgentMessage) or an error string
+ * @returns 'transient' | 'permanent' | 'compaction-noop' | null (success/unknown)
+ */
+export function classifyError(message) {
+    // Resolve a searchable text blob from a pi AgentMessage or raw string.
+    let text = '';
+    if (typeof message === 'string') {
+        text = message;
+    }
+    else if (message && typeof message === 'object') {
+        const m = message;
+        const sr = typeof m.stopReason === 'string' ? m.stopReason : '';
+        // S28 guard: length stopReason is handled exclusively by the S28 path.
+        if (sr === 'length')
+            return null;
+        // Success / normal tool flow — not an error, nothing to retry.
+        if (sr === 'stop' || sr === 'toolUse' || sr === 'tool_use')
+            return null;
+        const parts = [];
+        if (sr)
+            parts.push(sr);
+        const c = m.content;
+        if (typeof c === 'string')
+            parts.push(c);
+        else if (Array.isArray(c)) {
+            for (const b of c) {
+                if (b && typeof b === 'object' && 'text' in b) {
+                    parts.push(String(b.text ?? ''));
+                }
+            }
+        }
+        if (m.error) {
+            // Extract message from error objects for pattern matching.
+            const err = m.error;
+            if (typeof err === 'string') {
+                parts.push(err);
+            }
+            else if (err && typeof err === 'object') {
+                const errObj = err;
+                if (typeof errObj.message === 'string') {
+                    parts.push(errObj.message);
+                }
+                else {
+                    parts.push(JSON.stringify(err));
+                }
+            }
+        }
+        // S38: detect mid-response errors where the stream died without a
+        // proper stopReason (empty/undefined) — this catches provider failures
+        // that cut off the response mid-stream, INCLUDING the case where the
+        // provider emitted partial content before dying (a truncated response
+        // with no stop reason is a mid-stream death, not a success).
+        // A genuine success ALWAYS carries stop/tool_use/toolUse (which
+        // short-circuit to null at the top), so any message reaching here with a
+        // falsy stopReason is a stream failure → retryable.
+        if (!sr) {
+            return 'transient';
+        }
+        text = parts.join(' ');
+    }
+    if (!text)
+        return null;
+    const s = text.toLowerCase();
+    // --- compaction-noop (ORDER FIRST: pi race / manual compact catch) ---
+    // FAIL-2026071701: these are NOT retryable — the compaction already
+    // succeeded via pi's native path; retrying would race again.
+    if (/already compacted/.test(s))
+        return 'compaction-noop';
+    if (/compaction failed/.test(s))
+        return 'compaction-noop';
+    if (/nothing to compact/.test(s))
+        return 'compaction-noop';
+    if (/auto[\s-]?compaction failed/.test(s))
+        return 'compaction-noop';
+    // --- transient (retryable) ---
+    if (s.includes('error') && !/\b(permanent|invalid request|malformed|bad request|auth|unauthorized|invalid (api )?key|permission)\b/.test(s)) {
+        return 'transient'; // generic pi stopReason 'error' / 'aborted'
+    }
+    if (s.includes('aborted'))
+        return 'transient';
+    if (/max(imum)? output token/.test(s))
+        return 'transient';
+    if (/rate[\s.-]?limit|429|too many requests/.test(s))
+        return 'transient';
+    if (/5\d\d|internal server|bad gateway|service unavailable/.test(s))
+        return 'transient';
+    if (/network|timeout|connection (lost|refused|reset)|stream (interrupted|closed|ended|failed)|disconnected/.test(s))
+        return 'transient';
+    // --- permanent (NOT retryable beyond 1) ---
+    if (/auth|unauthorized|invalid (api )?key|permission/.test(s))
+        return 'permanent';
+    if (/invalid request|malformed|bad request/.test(s))
+        return 'permanent';
+    // Unknown — do not retry (avoid busy-looping on an unclassified signal).
+    return null;
+}
+/** S38.2: exponential backoff for error-retry nudges (5s,10s,20s,30s,30s cap).
+ *  count is 1-based (the retry about to fire). */
+export function errorRetryBackoffMs(count) {
+    switch (count) {
+        case 1: return 5_000;
+        case 2: return 10_000;
+        case 3: return 20_000;
+        default: return 30_000; // cap from the 4th retry onward
+    }
+}

package/dist/extensions/mega-events.js

@@ -16,3 +16,4 @@ export * from "./mega-events/agent-handlers.js";
 export * from "./mega-events/context-handler.js";
 export * from "./mega-events/compact-handlers.js";
 export * from "./mega-events/perf-handler.js";
+export * from "./mega-events/error-classifier.js";

package/dist/extensions/mega-runtime/state.js

@@ -49,6 +49,9 @@ export class MegaRuntime {
         recallInjections: 0,
         cacheHitTokens: 0,
         lengthStopPending: false,
+        errorRetryCount: 0,
+        errorRetryUntil: 0,
+        consecutiveErrors: 0,
     };
     // v0.8.6 cache-stability: the cached live-trim view for the current
     // compaction epoch. Set after a fresh runCompact + computeLiveTrimCut, and
@@ -164,6 +167,11 @@ export class MegaRuntime {
     // getCachedGameState() snapshot re-queries the DB anyway.
     gameStateWatcher;
     gameStateWatchDir;
+    // P2: the last ExtensionContext handed to snapshot()/renderWidget(), stashed
+    // so the fs.watch game-state callback can force a widget re-render without
+    // a context event (cross-process dashboard edits while pi is idle). Cleared
+    // implicitly on construction (undefined → watcher skips until first snap).
+    lastWidgetCtx;
     /**
      * DIAG counters for the "team run doesn't relieve context" investigation.
      * Plain integers, incremented at the three compaction decision points. They
@@ -318,6 +326,8 @@ export class MegaRuntime {
     // ---- dashboard snapshot + widget ------------------------------------------
     /** Collect live state and write it to disk (+ paint the above-editor widget). */
     snapshot(ctx) {
+        if (ctx)
+            this.lastWidgetCtx = ctx;
         if (ctx)
             this.bindRepo(ctx.cwd);
         // v0.8.5: gate the expensive body (6 sync SQLite opens +
@@ -486,6 +496,16 @@ export class MegaRuntime {
                 cacheHit: { sessionSec: sec(this.rt.cacheHitTokens), totalSec: sec(cacheHitsTotalTokens) },
             },
             model,
+            // S38.8: error-retry state for the dashboard "retries" tile. The field is
+            // declared on DashboardSnapshot (mega-dashboard.ts) and surfaced here so the
+            // dashboard can render live retry/circuit-breaker status alongside the event
+            // stream (which already carries per-retry events).
+            retries: {
+                errorRetryCount: this.rt.errorRetryCount,
+                consecutiveErrors: this.rt.consecutiveErrors,
+                maxConsecutiveErrors: this.config.maxConsecutiveErrors,
+                errorRetryHardStop: this.config.errorRetryHardStop,
+            },
             diag: {
                 ctxFastGate: this.diagCtxFastGate,
                 liveTrimFires: this.diagLiveTrimFires,
@@ -742,6 +762,9 @@ export class MegaRuntime {
             recallInjections: 0,
             cacheHitTokens: 0,
             lengthStopPending: false,
+            errorRetryCount: 0,
+            errorRetryUntil: 0,
+            consecutiveErrors: 0,
         };
         this.trimCache = null; // v0.8.6: never replay a stale trim into a new session
         this.statusKey = undefined;
@@ -892,6 +915,30 @@ export class MegaRuntime {
                 if (typeof filename === "string" && filename.startsWith("sqlite.db")) {
                     this.cachedGameState = undefined;
                     this.gameStateBump++;
+                    // P2: force a widget re-render so a dashboard-made theme/toggle/
+                    // tui-mode change reflects in the live TUI immediately, even when
+                    // pi is idle (no context event to drive snapshot()). Use the
+                    // LIGHTWEIGHT refreshWidgetGameState() — NOT the full snapshot():
+                    // snapshot() recomputes 6 sync SQLite opens + writes dashboard.json
+                    // + writes to the store, and those store writes RETRIGGER this
+                    // same fs.watch callback (it fires on every sqlite.db* write) →
+                    // re-entrant thrash → 190s test timeout under mega-compact.test.js
+                    // / mega-teamrun.test.js. The lightweight path re-reads ONLY the
+                    // game_state row and patches the three game-mode fields on the
+                    // existing widgetData, then re-registers the factory via
+                    // renderWidget() — it writes nothing to the store or
+                    // dashboard.json, so it cannot retrigger itself. Guard: skip until
+                    // the first snapshot stashed a ctx (no widget registered yet →
+                    // nothing to refresh). Non-fatal: next context event re-snapshots.
+                    const ctx = this.lastWidgetCtx;
+                    if (ctx) {
+                        try {
+                            this.refreshWidgetGameState(ctx);
+                        }
+                        catch {
+                            /* non-fatal */
+                        }
+                    }
                 }
             });
             this.gameStateWatchDir = this.currentStateDir;
@@ -971,6 +1018,33 @@ export class MegaRuntime {
         }
         return this.cachedGameState;
     }
+    /** P2 cross-process re-render: lightweight game-state refresh for the
+     *  fs.watch callback. Eviction of cachedGameState + gameStateBump++ happens
+     *  in the caller BEFORE this runs. Here we re-read ONLY the game_state row
+     *  via getCachedGameState() (one SELECT; the cache is already evicted) and
+     *  patch ONLY the three game-mode fields on the EXISTING widgetData, then
+     *  re-register the widget factory via renderWidget() so pi redraws next
+     *  frame.
+     *
+     *  WHY a lightweight path: the full snapshot(ctx) recomputes 6 synchronous
+     *  SQLite opens + writeFileSync(dashboard.json) + store writes, and those
+     *  store writes RETRIGGER this same fs.watch callback → re-entrant thrash
+     *  (the watcher fires on every sqlite.db* write, including context-event
+     *  checkpoint writes) → 190s test timeout under mega-compact.test.js /
+     *  mega-teamrun.test.js. This path writes NOTHING to the store or
+     *  dashboard.json, so it cannot retrigger itself.
+     *
+     *  Guard: no-op when widgetData is null (no snapshot has run yet → nothing
+     *  to patch) or ctx is undefined. Field values mirror snapshot() exactly. */
+    refreshWidgetGameState(ctx) {
+        if (!this.widgetData || !ctx)
+            return;
+        const gs = this.getCachedGameState();
+        this.widgetData.gameMode = gs.game_mode_on;
+        this.widgetData.theme = getTheme(gs.theme) ? gs.theme : "transparent";
+        this.widgetData.tuiMode = gs.tui_display_mode;
+        this.renderWidget(ctx);
+    }
     /** S31: evict the cached game-mode state so the next widget render re-reads
      *  the game_state row. Called by /mega-game after every setGameState() so
      *  the panel picks up theme/mode/toggle changes live. */
@@ -1044,6 +1118,14 @@ export class MegaRuntime {
     }
     // Phase 3 — recall/activity ticker ring buffer.
     pushTicker(text) {
+        // P1: dedupe consecutive identical entries — skip the append when the
+        // last entry's text matches, so a re-fired compact/recall/dedup event
+        // doesn't flood the ring (keeps it at TICKER_MAX for real variety).
+        // `at` is NOT refreshed on a skip (the original event time stands).
+        if (this.ticker[this.ticker.length - 1]?.text === text) {
+            this.lastActivityAt = Date.now();
+            return;
+        }
         this.ticker.push({ text, at: Date.now() });
         while (this.ticker.length > this.TICKER_MAX)
             this.ticker.shift();

package/dist/extensions/mega-runtime/state.test.js

@@ -110,6 +110,43 @@ describe("MegaRuntime setEffect lifecycle (v0.8.3)", () => {
         assert.equal(rt.activeEffect, null, "cleared once expired");
     });
 });
+describe("MegaRuntime pushTicker dedupe (P1)", () => {
+    const dirs = [];
+    after(() => {
+        for (const d of dirs) {
+            try {
+                closeStore(d);
+            }
+            catch { /* */ }
+        }
+        delete process.env.MEGACOMPACT_STATE_DIR;
+        for (const d of dirs)
+            rmSync(d, { recursive: true, force: true });
+    });
+    it("pushTicker skips consecutive identical entries (keeps ring at capacity for variety)", () => {
+        const dir = freshDir();
+        dirs.push(dir);
+        process.env.MEGACOMPACT_STATE_DIR = dir;
+        const rt = new MegaRuntime(minimalConfig(dir));
+        rt.pushTicker("compact");
+        rt.pushTicker("compact"); // dedup — skipped
+        rt.pushTicker("compact"); // dedup — skipped
+        rt.pushTicker("recall");
+        assert.equal(rt.ticker.length, 2, "only 2 unique entries kept");
+        assert.equal(rt.ticker[0].text, "compact");
+        assert.equal(rt.ticker[1].text, "recall");
+    });
+    it("pushTicker keeps distinct entries and respects TICKER_MAX", () => {
+        const dir = freshDir();
+        dirs.push(dir);
+        process.env.MEGACOMPACT_STATE_DIR = dir;
+        const rt = new MegaRuntime(minimalConfig(dir));
+        for (let i = 0; i < rt.TICKER_MAX + 3; i++)
+            rt.pushTicker(`t${i}`);
+        assert.equal(rt.ticker.length, rt.TICKER_MAX, "capped at TICKER_MAX");
+        assert.equal(rt.ticker[rt.TICKER_MAX - 1].text, `t${rt.TICKER_MAX + 2}`);
+    });
+});
 describe("MegaRuntime game-state cache (S31)", () => {
     const dirs = [];
     after(() => {

package/dist/extensions/mega-runtime/widget.js

@@ -292,8 +292,12 @@ export function buildWidgetLines(wd, width, activeAgents) {
         lines.push(panelLine(`   ${pulse}${wd.tierTrace}`, width, panelBg));
     }
     else if (wd.ticker.length > 0) {
-        const step = Math.floor(Date.now() / 250);
-        const idx = wd.ticker.length - 1 - (step % wd.ticker.length);
+        // P1: pin to the most-recent entry (no 250ms rotation). The old
+        // `step = floor(Date.now()/250)` re-picked the head every TUI frame,
+        // flipping the footer line on a 250·N ms cycle. Pinning makes the
+        // footer hold stable until a real state change (new pushTicker /
+        // tierTrace / pulsing transition). (+N more) + lastWhy are preserved.
+        const idx = wd.ticker.length - 1;
         const head = wd.ticker[idx].text;
         const why = wd.lastWhy ? ` ${C.gray}· ${wd.lastWhy}${C.reset}` : "";
         const more = wd.ticker.length > 1

package/dist/extensions/mega-runtime/widget.test.js

@@ -181,6 +181,53 @@ describe("buildWidgetLines ambient border effect (v0.8.3)", () => {
         assert.ok(borders.some((b) => b.includes("\x1b[38;5;203m")), `flash-on phase uses red base 203`);
     });
 });
+describe("buildWidgetLines footer stability (P1 — no 250ms rotation)", () => {
+    // P1: the L5 ticker branch used to re-pick the head text every 250ms via
+    // `step = floor(Date.now()/250)`, flipping the footer line on a 250·N ms
+    // cycle. After the fix it pins to the most-recent entry, so two renders of
+    // the SAME WidgetData at t and t+500ms (well past one rotation slot) must
+    // produce byte-identical footer lines. Proves the metronome is gone.
+    const stabBase = (overrides = {}) => baseWd({
+        theme: DEFAULT_THEME, tuiMode: "full", gameMode: false, level: 1, cachePct: 42, ...overrides,
+    });
+    it("ticker footer is byte-identical across simulated frames 500ms apart", () => {
+        const wd = stabBase({
+            ticker: [
+                { text: "first", at: 1000 },
+                { text: "second", at: 2000 },
+                { text: "third", at: 3000 },
+            ],
+            lastWhy: "because",
+        });
+        const realNow = Date.now;
+        try {
+            Date.now = () => 1_000_000; // t
+            const a = buildWidgetLines(wd, WIDTH, 0);
+            Date.now = () => 1_000_500; // t+500ms (would have rotated twice under the old code)
+            const b = buildWidgetLines(wd, WIDTH, 0);
+            assert.deepEqual(a, b, "footer byte-identical across 500ms with no state change");
+            // And the pinned head is the most-recent entry (third), not a rotation:
+            assert.ok(a.some((l) => l.includes("third")), "shows most-recent ticker entry");
+            assert.ok(a.some((l) => l.includes("(+2 more)")), "(+N more) suffix preserved");
+            assert.ok(a.some((l) => l.includes("because")), "lastWhy preserved");
+        }
+        finally {
+            Date.now = realNow;
+        }
+    });
+    it("footer still flips when the ticker actually changes (new pushTicker)", () => {
+        const realNow = Date.now;
+        try {
+            Date.now = () => 1_000_000;
+            const before = buildWidgetLines(stabBase({ ticker: [{ text: "a", at: 1 }] }), WIDTH, 0);
+            const after = buildWidgetLines(stabBase({ ticker: [{ text: "a", at: 1 }, { text: "b", at: 2 }] }), WIDTH, 0);
+            assert.notDeepEqual(before, after, "footer changes when ticker grows");
+        }
+        finally {
+            Date.now = realNow;
+        }
+    });
+});
 describe("buildWidgetLines achievement flare (S35)", () => {
     const achBase = (overrides = {}) => baseWd({
         theme: DEFAULT_THEME, tuiMode: "full", gameMode: true, level: 1, cachePct: 42, ...overrides,