pi-mega-compact 0.8.1 → 0.8.3

package/dist/extensions/dashboard-server/server.js

@@ -496,6 +496,18 @@ export async function launchDashboardServer(stateDir) {
                 log("server running", { url });
                 // eslint-disable-next-line no-console
                 console.log(`[mega-compact] dashboard server running: ${url}`);
+                // v0.8.2: also bind the IPv6 loopback (::1). On many systems `localhost`
+                // resolves to ::1 first (see /etc/hosts), so an IPv4-only bind makes the
+                // browser hit ::1:port and get connection refused. PREVENT-PI-004
+                // (loopback-only) means BOTH 127.0.0.1 and ::1. Non-fatal: IPv4-only
+                // hosts or a ::1 already in use just skip the mirror.
+                let v6;
+                const v4Handler = server.listeners("request")[0];
+                if (v4Handler) {
+                    v6 = createServer((r, s) => v4Handler.call(server, r, s));
+                    v6.on("error", (e) => log("ipv6 loopback bind skipped", { port, code: e.code, message: e.message }));
+                    v6.listen(port, "::1", () => log("ipv6 loopback bound", { port })); // guardrails-allow PREVENT-PI-004: IPv6 loopback (::1) mirror of the localhost dashboard server
+                }
                 // Write port.pid
                 try {
                     writeFileSync(portFile, JSON.stringify({ port, pid: process.pid }));
@@ -510,6 +522,10 @@ export async function launchDashboardServer(stateDir) {
                     }
                     catch { /* already gone */ }
                     server.close();
+                    try {
+                        v6?.close();
+                    }
+                    catch { /* not bound */ }
                     process.exit(0);
                 };
                 process.on("SIGTERM", cleanup);

package/dist/extensions/mega-game-cmds.js

@@ -27,6 +27,15 @@ import { listAchievements } from "../src/store/sqlite/game-achievements.js";
 import { THEMES, THEME_IDS, getTheme, isValidTheme, nextTheme, DEFAULT_THEME } from "../src/config/themes.js";
 /** Notify/usage tag + command name. Primary surface is /mega-compact-settings. */
 const TAG = "mega-compact-settings";
+/** Apply a game_state mutation to the live TUI: evict the memoized cache
+ *  (bumpGameState) THEN recompute the widget snapshot (snapshot(ctx)) so the
+ *  panel picks up the new theme/mode/toggle immediately — no pi restart needed.
+ *  snapshot() re-reads the (evicted) game_state into widgetData and re-registers
+ *  the widget factory. Order matters: bump first, snapshot second. */
+function applyChange(ctx, runtime) {
+    runtime.bumpGameState();
+    runtime.snapshot(ctx);
+}
 /** Format the current state as a human-readable status line set. */
 function fmtState(s) {
     return [
@@ -40,8 +49,20 @@ async function handleSettings(args, ctx, runtime) {
     runtime.bindRepo(ctx.cwd);
     const stateDir = runtime.currentStateDir;
     const parts = args.trim().split(/\s+/).filter(Boolean);
-    // bare  → print current state.
+    // bare  → interactive in-app menu (ctx.ui.select picker). Falls back to a
+    // static status print when there's no interactive UI (RPC/print mode, or a
+    // test harness stubbing only notify). CLI subcommands below still work for
+    // power users + scripts.
     if (parts.length === 0) {
+        if (typeof ctx.ui.select === "function") {
+            try {
+                await runInteractiveMenu(ctx, runtime, stateDir);
+                return;
+            }
+            catch {
+                // select threw (non-interactive impl) → fall through to status print
+            }
+        }
         const s = getGameState(stateDir);
         for (const line of fmtState(s))
             ctx.ui.notify(line);
@@ -60,7 +81,7 @@ async function handleSettings(args, ctx, runtime) {
     // on|off
     if (sub === "on" || sub === "off") {
         const s = setGameState({ game_mode_on: sub === "on" }, stateDir);
-        runtime.bumpGameState();
+        applyChange(ctx, runtime);
         ctx.ui.notify(`[${TAG}] game mode ${s.game_mode_on ? "ON" : "off"}`);
         return;
     }
@@ -87,7 +108,7 @@ async function handleSettings(args, ctx, runtime) {
             return;
         }
         const s = setGameState({ theme: id }, stateDir);
-        runtime.bumpGameState();
+        applyChange(ctx, runtime);
         ctx.ui.notify(`[${TAG}] theme → ${s.theme} (${getTheme(s.theme)?.label ?? ""})`);
         return;
     }
@@ -99,12 +120,103 @@ async function handleSettings(args, ctx, runtime) {
             return;
         }
         const s = setGameState({ tui_display_mode: arg }, stateDir);
-        runtime.bumpGameState();
+        applyChange(ctx, runtime);
         ctx.ui.notify(`[${TAG}] tui → ${s.tui_display_mode}`);
         return;
     }
     ctx.ui.notify(`[${TAG}] usage: /${TAG} [on|off|theme [id|next]|tui [full|minimal]|achievements]`);
 }
+/** Interactive in-app menu for bare `/mega-compact-settings`. Uses ctx.ui.select
+ * (a real TUI picker in interactive mode). Loops until the user cancels (or
+ * picks "Done"). Each action mutates the global game_state row + bumps the
+ * runtime cache so the widget/dashboard reflect it immediately.
+ *
+ * Guarded by the caller via `typeof ctx.ui.select === "function"`; if select is
+ * unavailable we fall back to the static fmtState notify print. */
+async function runInteractiveMenu(ctx, runtime, stateDir) {
+    for (;;) {
+        const s = getGameState(stateDir);
+        const toggleLabel = s.game_mode_on ? "Turn game mode OFF" : "Turn game mode ON";
+        const choice = await ctx.ui.select(`[${TAG}] settings · game mode: ${s.game_mode_on ? "ON" : "off"} · theme: ${s.theme} · tui: ${s.tui_display_mode}`, [toggleLabel, "Theme…", "TUI display mode…", "Achievements…", "Done"]);
+        if (choice === undefined || choice === "Done")
+            return;
+        if (choice === toggleLabel) {
+            const next = !s.game_mode_on;
+            setGameState({ game_mode_on: next }, stateDir);
+            applyChange(ctx, runtime);
+            ctx.ui.notify(`[${TAG}] game mode ${next ? "ON" : "off"}`, "info");
+            continue;
+        }
+        if (choice === "Theme…") {
+            await themeSubmenu(ctx, runtime, stateDir);
+            continue;
+        }
+        if (choice === "TUI display mode…") {
+            await tuiSubmenu(ctx, runtime, stateDir);
+            continue;
+        }
+        if (choice === "Achievements…") {
+            await achievementsView(ctx, stateDir);
+            continue;
+        }
+    }
+}
+/** Theme picker submenu — lists all themes (current marked ✓) + a cycle option. */
+async function themeSubmenu(ctx, runtime, stateDir) {
+    const s = getGameState(stateDir);
+    const opts = THEMES.map((t) => {
+        const mark = t.id === s.theme ? " ✓" : "";
+        return `${t.id}${mark}  ${t.label}`;
+    });
+    opts.push("next (cycle to next theme)");
+    opts.push("Back");
+    const choice = await ctx.ui.select(`[${TAG}] theme (current: ${s.theme})`, opts);
+    if (choice === undefined || choice === "Back")
+        return;
+    const first = choice.split(/\s+/)[0];
+    let id;
+    if (first === "next") {
+        id = nextTheme(s.theme);
+    }
+    else if (isValidTheme(first)) {
+        id = first;
+    }
+    if (id && id !== s.theme) {
+        setGameState({ theme: id }, stateDir);
+        applyChange(ctx, runtime);
+        ctx.ui.notify(`[${TAG}] theme → ${id} (${getTheme(id)?.label ?? ""})`, "info");
+    }
+}
+/** TUI display-mode submenu — full vs minimal (current marked ✓). */
+async function tuiSubmenu(ctx, runtime, stateDir) {
+    const s = getGameState(stateDir);
+    const mark = (m) => (s.tui_display_mode === m ? " ✓" : "");
+    const choice = await ctx.ui.select(`[${TAG}] TUI display mode (current: ${s.tui_display_mode})`, [
+        `full${mark("full")}  — bars, stats, flair`,
+        `minimal${mark("minimal")}  — one-line level + cache %`,
+        "Back",
+    ]);
+    if (choice === undefined || choice === "Back")
+        return;
+    const mode = choice.split(/\s+/)[0];
+    if (mode === "full" || mode === "minimal") {
+        setGameState({ tui_display_mode: mode }, stateDir);
+        applyChange(ctx, runtime);
+        ctx.ui.notify(`[${TAG}] tui → ${mode}`, "info");
+    }
+}
+/** Achievements view — terse notify list + a read-only select viewer. */
+async function achievementsView(ctx, stateDir) {
+    const rows = listAchievements(stateDir).filter((r) => r.unlocked_at != null);
+    ctx.ui.notify(`[${TAG}] achievements unlocked (${rows.length}/9):`, "info");
+    for (const r of rows)
+        ctx.ui.notify(`  ${r.icon ?? ""} ${r.title}`, "info");
+    const lines = rows.length
+        ? rows.map((r) => `${r.icon ?? ""} ${r.title}`)
+        : ["(none unlocked yet — keep compacting!)"];
+    // select() as a read-only viewer; any selection / cancel returns to the menu.
+    await ctx.ui.select(`[${TAG}] achievements (${rows.length}/9 unlocked)`, lines);
+}
 /** Register /mega-compact-settings (primary) + /mega-game (backward-compat alias). */
 export function registerGameCommands(pi, runtime) {
     const description = "Game mode toggle + theme picker + TUI display mode. Usage: /mega-compact-settings [on|off|theme [id|next]|tui [full|minimal]|achievements]";

package/dist/extensions/mega-game-cmds.test.js

@@ -16,13 +16,19 @@ import { THEME_IDS } from "../src/config/themes.js";
 // that wires the command against a fake pi without binding to the real pi
 // module at load time.
 const require = createRequire(import.meta.url);
-function makeHarness(stateDir) {
+function makeHarness(stateDir, select, snapshotSpy) {
     const commands = {};
     const notifies = [];
-    const runtime = { bindRepo: () => { }, currentStateDir: stateDir, bumpGameState: () => { } };
+    const snapshotCalls = [];
+    const runtime = {
+        bindRepo: () => { },
+        currentStateDir: stateDir,
+        bumpGameState: () => { },
+        snapshot: () => { snapshotCalls.push(1); snapshotSpy?.(); },
+    };
     const ctx = {
         cwd: stateDir,
-        ui: { notify: (s) => notifies.push(s) },
+        ui: { notify: (s) => notifies.push(s), ...(select ? { select } : {}) },
     };
     const fakePi = {
         registerCommand: (name, opts) => {
@@ -33,7 +39,7 @@ function makeHarness(stateDir) {
     // test from binding to the real pi module at load time.
     const mod = require("./mega-game-cmds.js");
     mod.registerGameCommands(fakePi, runtime);
-    return { commands, notifies, ctx };
+    return { commands, notifies, ctx, snapshotCalls };
 }
 describe("/mega-compact-settings (S30; /mega-game alias)", () => {
     let dir;
@@ -63,6 +69,45 @@ describe("/mega-compact-settings (S30; /mega-game alias)", () => {
         assert.ok(lines.some((l) => l.includes("transparent")));
         assert.ok(lines.some((l) => l.includes("tui:")));
     });
+    it("bare command opens interactive menu (select) and toggles game mode", async () => {
+        const seq = ["Turn game mode ON", "Done"];
+        let i = 0;
+        const h = makeHarness(dir, () => Promise.resolve(seq[i++] ?? undefined));
+        h.notifies.length = 0;
+        await h.commands["mega-compact-settings"].handler("", h.ctx);
+        assert.equal(getGameState().game_mode_on, true);
+        assert.ok(h.notifies.some((l) => l.includes("game mode ON")));
+        // toggle back off via the menu
+        const seq2 = ["Turn game mode OFF", "Done"];
+        let j = 0;
+        const h2 = makeHarness(dir, () => Promise.resolve(seq2[j++] ?? undefined));
+        await h2.commands["mega-compact-settings"].handler("", h2.ctx);
+        assert.equal(getGameState().game_mode_on, false);
+    });
+    it("bare command falls back to status print when select is unavailable", async () => {
+        // default harness has no select — mimics RPC/print mode
+        const lines = await run("");
+        assert.ok(lines.some((l) => l.includes("game mode: off")));
+    });
+    it("menu Theme… → picks a theme and persists", async () => {
+        const seq = ["Theme…", "retro  Retro Terminal", "Done"];
+        let i = 0;
+        const h = makeHarness(dir, () => Promise.resolve(seq[i++] ?? undefined));
+        h.notifies.length = 0;
+        await h.commands["mega-compact-settings"].handler("", h.ctx);
+        assert.equal(getGameState().theme, "retro");
+        assert.ok(h.notifies.some((l) => l.includes("theme → retro")));
+    });
+    it("menu toggle calls runtime.snapshot() so the widget refreshes live", async () => {
+        const seq = ["Turn game mode ON", "Done"];
+        let i = 0;
+        const h = makeHarness(dir, () => Promise.resolve(seq[i++] ?? undefined));
+        h.notifies.length = 0;
+        h.snapshotCalls.length = 0;
+        await h.commands["mega-compact-settings"].handler("", h.ctx);
+        assert.equal(getGameState().game_mode_on, true);
+        assert.ok(h.snapshotCalls.length >= 1, "snapshot() called so widget refreshes live");
+    });
     it("on enables game mode and persists", async () => {
         await run("on");
         assert.equal(getGameState().game_mode_on, true);

package/dist/extensions/mega-pipeline/compact.js

@@ -44,6 +44,7 @@ export function runCompact(pi, runtime, config, ctx, messages, opts = {}) {
 }
 function doCompact(view, keepFrom, opts, sid, config, pi, ctx, runtime) {
     runtime.pulsing = true; // animate the status line while the (sync) pipeline runs
+    runtime.setEffect?.("pulse", "accent", 1500); // v0.8.3: ambient border pulse during compaction
     // S21.2: reset the per-compaction memory-op counter so the post-compact
     // consolidate pass only fires when memory rows actually changed during the
     // compaction window (turn_end → auto-review may have written some).

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

@@ -60,6 +60,12 @@ export class MegaRuntime {
     // when cachePct > 100). Copied into widgetData.megaCacheFlare on the next
     // snapshot() so the widget renders the oopsie gag, then reset (one cycle).
     megaCacheFlare = false;
+    /** v0.8.3: ambient effect state for animated panel borders keyed off
+     *  status transitions (level-up, mega-cache overshoot, achievement unlock,
+     *  compaction start). Threaded into widgetData as `activeEffect`; the widget
+     *  computes the per-frame phase from startedAt vs Date.now() (non-expired).
+     *  Null when idle/expired. */
+    activeEffect = null;
     megaCacheFlarePct = 0;
     levelUpFlare = false;
     lastLevel = 0;
@@ -510,8 +516,11 @@ export class MegaRuntime {
             const gs = this.getCachedGameState();
             // S34: derive the level-up flare from the turn count each snapshot.
             const curLevel = this.getTurnLevel();
-            if (curLevel > this.lastLevel)
+            if (curLevel > this.lastLevel) {
                 this.levelUpFlare = true;
+                // v0.8.3: arm a pulse border effect to celebrate the level-up.
+                this.setEffect("pulse", "accent", 1500);
+            }
             const cachePct = st.dedupHitRate * 100;
             this.widgetData = {
                 version: ownVersion(),
@@ -555,6 +564,9 @@ export class MegaRuntime {
                 levelUpFlare: this.levelUpFlare,
                 achievementFlare: this.achievementFlare,
                 achievementFlareTitles: this.achievementFlareTitles,
+                // v0.8.3: ambient border effect — threaded live so the widget can
+                // compute the per-frame phase and render animated borders.
+                activeEffect: this.activeEffect,
             };
             // S33: consume the flare after copying it into widgetData so it fires
             // for exactly one render cycle (the gag flares once, then clears).
@@ -568,6 +580,17 @@ export class MegaRuntime {
             // (mirrors the megaCacheFlare/levelUpFlare one-shot semantics).
             this.achievementFlare = false;
             this.achievementFlareTitles = [];
+            // v0.8.3: expire the ambient border effect once its time window has
+            // elapsed. SEPARATE from the one-shot flares above (those are per-cycle
+            // consumes; activeEffect is time-windowed and cleared when Date.now()
+            // crosses startedAt + durationMs). The widget also defends this per-frame
+            // (effectBorderSgr returns '' once expired), so this is bookkeeping to
+            // free the slot and prevent a stale effect lingering between snapshots.
+            if (this.activeEffect &&
+                Date.now() - this.activeEffect.startedAt >=
+                    this.activeEffect.durationMs) {
+                this.activeEffect = null;
+            }
             // Auto-fit: register a factory so pi re-renders the panel at the REAL
             // terminal width every frame (tui.columns), instead of guessing with
             // process.stdout.columns. buildWidgetLines reads this.widgetData live.
@@ -833,17 +856,31 @@ export class MegaRuntime {
         return turnLevel(this.currentTurn);
     }
     /** S33: arm the transient MEGA CACHE flare so the next snapshot() copies it
-     *  into widgetData and the widget renders the oopsie gag for one cycle. */
+     *  into widgetData and the widget renders the oopsie gag for one cycle.
+     *  v0.8.3: also arm a 'flash' ambient effect on the panel borders (mega
+     *  color) for 1.2s. */
     armMegaCacheFlare(peakPct) {
         this.megaCacheFlare = true;
         this.megaCacheFlarePct = peakPct;
+        this.setEffect("flash", "mega", 1200);
     }
     /** S35: arm the transient achievement-unlock flare with the newly-unlocked
      *  titles so the next snapshot() copies them into widgetData and the widget
-     *  renders the one-time unlock toast for one render cycle. */
+     *  renders the one-time unlock toast for one render cycle.
+     *  v0.8.3: also arm a 'pulse' ambient effect on the panel borders (accent
+     *  color) for 2s to celebrate the unlock. */
     armAchievementFlare(titles) {
         this.achievementFlare = true;
         this.achievementFlareTitles = titles;
+        this.setEffect("pulse", "accent", 2000);
+    }
+    /** v0.8.3: arm an ambient border effect (animated pulse/flash on the panel
+     *  borders). Replaces any in-flight effect (last call wins — a later event
+     *  like a level-up during an achievement pulse simply overrides). The widget
+     *  reads activeEffect each frame and computes the per-frame phase from
+     *  startedAt vs Date.now(); it renders '' once the window elapses. */
+    setEffect(type, role, durationMs) {
+        this.activeEffect = { type, role, startedAt: Date.now(), durationMs };
     }
     /** Build the sync onTier callback that paints the live per-tier trace. */
     makeTierCallback(ctx) {

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

@@ -52,6 +52,64 @@ function minimalConfig(stateDir) {
 function freshDir() {
     return mkdtempSync(join(tmpdir(), "mc-state-"));
 }
+describe("MegaRuntime setEffect lifecycle (v0.8.3)", () => {
+    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("activeEffect starts null and setEffect arms it with startedAt ~now", () => {
+        const dir = freshDir();
+        dirs.push(dir);
+        process.env.MEGACOMPACT_STATE_DIR = dir;
+        const rt = new MegaRuntime(minimalConfig(dir));
+        assert.equal(rt.activeEffect, null, "idle on construction");
+        const before = Date.now();
+        rt.setEffect("pulse", "accent", 2000);
+        const after = Date.now();
+        assert.equal(rt.activeEffect.type, "pulse");
+        assert.equal(rt.activeEffect.role, "accent");
+        assert.equal(rt.activeEffect.durationMs, 2000);
+        assert.ok(rt.activeEffect.startedAt >= before && rt.activeEffect.startedAt <= after, "startedAt within the call window");
+    });
+    it("setEffect replaces an in-flight effect (last call wins)", () => {
+        const dir = freshDir();
+        dirs.push(dir);
+        process.env.MEGACOMPACT_STATE_DIR = dir;
+        const rt = new MegaRuntime(minimalConfig(dir));
+        rt.setEffect("pulse", "accent", 2000);
+        const first = rt.activeEffect;
+        rt.setEffect("flash", "mega", 1200);
+        assert.notEqual(rt.activeEffect, first, "a fresh object replaced the prior");
+        assert.equal(rt.activeEffect.type, "flash");
+        assert.equal(rt.activeEffect.role, "mega");
+        assert.equal(rt.activeEffect.durationMs, 1200);
+    });
+    it("a backdated effect is recognized as expired by the snapshot predicate", () => {
+        const dir = freshDir();
+        dirs.push(dir);
+        process.env.MEGACOMPACT_STATE_DIR = dir;
+        const rt = new MegaRuntime(minimalConfig(dir));
+        rt.setEffect("pulse", "accent", 2000);
+        // Backdate startedAt past the duration window (no snapshot/ctx needed —
+        // this mirrors the exact predicate snapshot() runs after the flare consume).
+        rt.activeEffect.startedAt = Date.now() - 3000;
+        const expired = !!rt.activeEffect &&
+            Date.now() - rt.activeEffect.startedAt >= rt.activeEffect.durationMs;
+        assert.ok(expired, "backdated effect satisfies the expiry predicate");
+        // Clearing mirrors the snapshot() bookkeeping branch:
+        if (expired)
+            rt.activeEffect = null;
+        assert.equal(rt.activeEffect, null, "cleared once expired");
+    });
+});
 describe("MegaRuntime game-state cache (S31)", () => {
     const dirs = [];
     after(() => {

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

@@ -121,6 +121,47 @@ function panelBar(width, ch = "─", panelBg = DEFAULT_PANEL_BG) {
     // ever swapped for a wide/fullwidth character.
     return truncateToWidth(panelBg + ch.repeat(Math.max(0, width)), width, "", false) + "\x1b[0m";
 }
+// ── v0.8.3: ambient border-effect helpers ───────────────────────────────
+// The panel borders animate when an `activeEffect` is armed (level-up,
+// mega-cache overshoot, achievement unlock, compaction start). Two modes:
+//   • pulse — a sine ramp on a 256-color base (accent=51 / mega=214 / red=203):
+//     the base index is scaled by sin(π·t) so the border swells 0→peak→0 over
+//     the duration, then returns to '' (idle). 256-color indices are clamped
+//     to 0–255 defensively (the bases are all ≤214 so the clamp rarely bites).
+//   • flash — a 120ms hard on/off alternate using the base index at full.
+// Returns '' when idle, expired, or elapsed<0 (clock skew) so non-effect
+// renders are byte-identical to the pre-effect panel (S31 matrix stays green).
+const EFFECT_BASE = {
+    accent: 51,
+    mega: 214,
+    red: 203,
+};
+/** Resolve the per-frame border-fg SGR for an active effect. '' when idle or
+ *  expired (the widget's real per-frame expiry enforcer — snapshot-level clear
+ *  is just bookkeeping since snapshot is event-driven). */
+function effectBorderSgr(ae, now) {
+    if (!ae)
+        return "";
+    const elapsed = now - ae.startedAt;
+    if (elapsed < 0 || elapsed >= ae.durationMs)
+        return "";
+    const base = EFFECT_BASE[ae.role];
+    if (ae.type === "flash") {
+        // 120ms hard alternate: on (full base) / off (no SGR).
+        return Math.floor(elapsed / 120) % 2 === 0 ? `\x1b[38;5;${base}m` : "";
+    }
+    // pulse: sine ramp 0 → peak → 0 over the duration.
+    const t = elapsed / ae.durationMs;
+    const amp = Math.sin(Math.PI * t); // 0 at start/end, 1 at midpoint
+    const idx = Math.max(0, Math.min(255, Math.round(base * amp)));
+    return `\x1b[38;5;${idx}m`;
+}
+/** Prepend the effect border SGR to a panel bar line. The SGR is a pure-fg
+ *  escape (zero visible width), so it never perturbs truncateToWidth's width
+ *  math — the bar's own `\x1b[0m` tail resets both fg + bg. No-op when sgr=''. */
+function effectBar(bar, sgr) {
+    return sgr ? sgr + bar : bar;
+}
 /** Token-count formatter: M at/above 1e6, k at/above 1e3, raw below.
  *  5,472,700 → "5.5mil", 24,100 → "24.1k", 142 → "142". */
 function fmtTokens(x) {
@@ -175,11 +216,16 @@ export function buildWidgetLines(wd, width, activeAgents) {
     // every panelLine/panelBar/wrapLine so the bg stays continuous and the width
     // guard (truncateToWidth) still holds for transparent themes.
     const panelBg = wd?.theme ? panelBgFor(wd.theme) : DEFAULT_PANEL_BG;
+    // v0.8.3: resolve the animated border SGR once per render. '' when idle,
+    // expired, or wd is null (warm-up) — so non-effect renders are byte-identical
+    // to the pre-effect panel (the existing S31 matrix tests stay green).
+    const now = Date.now();
+    const borderSgr = effectBorderSgr(wd?.activeEffect ?? null, now);
     if (!wd) {
         return [
-            panelBar(width, "─", panelBg),
+            effectBar(panelBar(width, "─", panelBg), borderSgr),
             panelLine(" mega-compact: warming up…", width, panelBg),
-            panelBar(width, "─", panelBg),
+            effectBar(panelBar(width, "─", panelBg), borderSgr),
         ];
     }
     // S31: minimal TUI mode — a single content line `LVL n | cache NN%` flanked
@@ -199,9 +245,9 @@ export function buildWidgetLines(wd, width, activeAgents) {
             ? `${accent}${wd.gameMode && wd.levelUpFlare ? "\x1b[5m" : ""}LVL ${lvl}${wd.gameMode && wd.levelUpFlare ? "\x1b[0m" : ""}${sgrReset(accent)} ${C.dim}|${C.reset} cache ${cacheStr}${megaFlare}`
             : `cache ${cacheStr}${megaFlare}`;
         return [
-            panelBar(width, "─", panelBg),
+            effectBar(panelBar(width, "─", panelBg), borderSgr),
             panelLine(` ${body}`, width, panelBg),
-            panelBar(width, "─", panelBg),
+            effectBar(panelBar(width, "─", panelBg), borderSgr),
         ];
     }
     const pulse = wd.pulsing
@@ -234,7 +280,7 @@ export function buildWidgetLines(wd, width, activeAgents) {
     // Wrap to terminal width and pad each line
     const wrapped = wrapLine(content, width - 2, panelBg); // 2-char indent
     const lines = [
-        panelBar(width, "─", panelBg),
+        effectBar(panelBar(width, "─", panelBg), borderSgr),
         ...wrapped.map((l) => panelLine(l, width, panelBg)),
     ];
     // L4 — agents block (S27, count + status; per-agent tokens gated on P0)
@@ -265,6 +311,6 @@ export function buildWidgetLines(wd, width, activeAgents) {
         lines.push(panelLine(`   ${accentSgr}🏆 Achievement unlocked: ${titlesStr}${sgrReset(accentSgr)}`, width, panelBg));
     }
     // bottom border
-    lines.push(panelBar(width, "─", panelBg));
+    lines.push(effectBar(panelBar(width, "─", panelBg), borderSgr));
     return lines;
 }

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

@@ -136,6 +136,51 @@ describe("buildWidgetLines (S31)", () => {
         }
     }
 });
+describe("buildWidgetLines ambient border effect (v0.8.3)", () => {
+    const effBase = (overrides = {}) => baseWd({
+        theme: DEFAULT_THEME, tuiMode: "full", gameMode: true, level: 1, cachePct: 42, ...overrides,
+    });
+    const isBorder = (l) => l.includes("─");
+    it("activeEffect (pulse, mid-window) -> border lines carry a 256-color fg SGR", () => {
+        const ae = { type: "pulse", role: "accent", startedAt: Date.now() - 250, durationMs: 2000 };
+        const lines = buildWidgetLines(effBase({ activeEffect: ae }), WIDTH, 0);
+        const borders = lines.filter(isBorder);
+        assert.ok(borders.length >= 2, "has top + bottom borders");
+        for (const b of borders) {
+            assert.ok(b.includes("\x1b[38;5;"), `border carries 256-color fg: ${JSON.stringify(b)}`);
+        }
+    });
+    it("activeEffect null -> plain borders, no 38;5 fg SGR on border lines", () => {
+        const lines = buildWidgetLines(effBase({ activeEffect: null }), WIDTH, 0);
+        const borders = lines.filter(isBorder);
+        for (const b of borders) {
+            assert.ok(!b.includes("\x1b[38;5;"), `no effect SGR on plain border: ${JSON.stringify(b)}`);
+        }
+    });
+    it("expired activeEffect -> plain borders (per-frame expiry enforced)", () => {
+        const ae = { type: "pulse", role: "accent", startedAt: Date.now() - 5000, durationMs: 1000 };
+        const lines = buildWidgetLines(effBase({ activeEffect: ae }), WIDTH, 0);
+        const borders = lines.filter(isBorder);
+        for (const b of borders) {
+            assert.ok(!b.includes("\x1b[38;5;"), `expired effect -> plain border: ${JSON.stringify(b)}`);
+        }
+    });
+    it("activeEffect border lines are width-safe (pulse, minimal + full)", () => {
+        for (const tuiMode of ["minimal", "full"]) {
+            const ae = { type: "pulse", role: "mega", startedAt: Date.now() - 100, durationMs: 2000 };
+            const lines = buildWidgetLines(effBase({ activeEffect: ae, tuiMode }), 60, 0);
+            for (const l of lines)
+                assert.ok(visibleWidth(l) <= 60, `width safe (${tuiMode}): ${visibleWidth(l)}`);
+        }
+    });
+    it("flash effect mid-window border carries the full base index SGR", () => {
+        // Force an 'on' phase of the 120ms alternate by starting just now.
+        const ae = { type: "flash", role: "red", startedAt: Date.now(), durationMs: 1200 };
+        const lines = buildWidgetLines(effBase({ activeEffect: ae }), WIDTH, 0);
+        const borders = lines.filter(isBorder);
+        assert.ok(borders.some((b) => b.includes("\x1b[38;5;203m")), `flash-on phase uses red base 203`);
+    });
+});
 describe("buildWidgetLines achievement flare (S35)", () => {
     const achBase = (overrides = {}) => baseWd({
         theme: DEFAULT_THEME, tuiMode: "full", gameMode: true, level: 1, cachePct: 42, ...overrides,

package/extensions/dashboard-server/server.ts

@@ -470,6 +470,21 @@ export async function launchDashboardServer(stateDir: string): Promise<{ port: n
         // eslint-disable-next-line no-console
         console.log(`[mega-compact] dashboard server running: ${url}`);
 
+        // v0.8.2: also bind the IPv6 loopback (::1). On many systems `localhost`
+        // resolves to ::1 first (see /etc/hosts), so an IPv4-only bind makes the
+        // browser hit ::1:port and get connection refused. PREVENT-PI-004
+        // (loopback-only) means BOTH 127.0.0.1 and ::1. Non-fatal: IPv4-only
+        // hosts or a ::1 already in use just skip the mirror.
+        let v6: ReturnType<typeof createServer> | undefined;
+        const v4Handler = server.listeners("request")[0];
+        if (v4Handler) {
+          v6 = createServer((r, s) => (v4Handler as (a: IncomingMessage, b: ServerResponse) => void).call(server, r, s));
+          v6.on("error", (e: NodeJS.ErrnoException) =>
+            log("ipv6 loopback bind skipped", { port, code: e.code, message: e.message }),
+          );
+          v6.listen(port, "::1", () => log("ipv6 loopback bound", { port })); // guardrails-allow PREVENT-PI-004: IPv6 loopback (::1) mirror of the localhost dashboard server
+        }
+
         // Write port.pid
         try {
           writeFileSync(portFile, JSON.stringify({ port, pid: process.pid }));
@@ -481,6 +496,7 @@ export async function launchDashboardServer(stateDir: string): Promise<{ port: n
         const cleanup = () => {
           try { unlinkSync(portFile); } catch { /* already gone */ }
           server.close();
+          try { v6?.close(); } catch { /* not bound */ }
           process.exit(0);
         };
         process.on("SIGTERM", cleanup);

package/extensions/mega-game-cmds.test.ts

@@ -24,15 +24,26 @@ type Harness = {
   commands: Record<string, Cmd>;
   notifies: string[];
   ctx: any;
+  snapshotCalls: number[];
 };
 
-function makeHarness(stateDir: string): Harness {
+function makeHarness(
+  stateDir: string,
+  select?: (title: string, options: string[]) => Promise<string | undefined>,
+  snapshotSpy?: () => void,
+): Harness {
   const commands: Record<string, Cmd> = {};
   const notifies: string[] = [];
-  const runtime = { bindRepo: () => {}, currentStateDir: stateDir, bumpGameState: () => {} };
+  const snapshotCalls: number[] = [];
+  const runtime = {
+    bindRepo: () => {},
+    currentStateDir: stateDir,
+    bumpGameState: () => {},
+    snapshot: () => { snapshotCalls.push(1); snapshotSpy?.(); },
+  };
   const ctx = {
     cwd: stateDir,
-    ui: { notify: (s: string) => notifies.push(s) },
+    ui: { notify: (s: string) => notifies.push(s), ...(select ? { select } : {}) },
   };
   const fakePi = {
     registerCommand: (name: string, opts: Cmd) => {
@@ -45,7 +56,7 @@ function makeHarness(stateDir: string): Harness {
     registerGameCommands: (pi: unknown, runtime: unknown) => void;
   };
   mod.registerGameCommands(fakePi, runtime);
-  return { commands, notifies, ctx };
+  return { commands, notifies, ctx, snapshotCalls };
 }
 
 describe("/mega-compact-settings (S30; /mega-game alias)", () => {
@@ -80,6 +91,49 @@ describe("/mega-compact-settings (S30; /mega-game alias)", () => {
     assert.ok(lines.some((l) => l.includes("tui:")));
   });
 
+  it("bare command opens interactive menu (select) and toggles game mode", async () => {
+    const seq = ["Turn game mode ON", "Done"];
+    let i = 0;
+    const h = makeHarness(dir, () => Promise.resolve(seq[i++] ?? undefined));
+    h.notifies.length = 0;
+    await h.commands["mega-compact-settings"].handler("", h.ctx);
+    assert.equal(getGameState().game_mode_on, true);
+    assert.ok(h.notifies.some((l) => l.includes("game mode ON")));
+    // toggle back off via the menu
+    const seq2 = ["Turn game mode OFF", "Done"];
+    let j = 0;
+    const h2 = makeHarness(dir, () => Promise.resolve(seq2[j++] ?? undefined));
+    await h2.commands["mega-compact-settings"].handler("", h2.ctx);
+    assert.equal(getGameState().game_mode_on, false);
+  });
+
+  it("bare command falls back to status print when select is unavailable", async () => {
+    // default harness has no select — mimics RPC/print mode
+    const lines = await run("");
+    assert.ok(lines.some((l) => l.includes("game mode: off")));
+  });
+
+  it("menu Theme… → picks a theme and persists", async () => {
+    const seq = ["Theme…", "retro  Retro Terminal", "Done"];
+    let i = 0;
+    const h = makeHarness(dir, () => Promise.resolve(seq[i++] ?? undefined));
+    h.notifies.length = 0;
+    await h.commands["mega-compact-settings"].handler("", h.ctx);
+    assert.equal(getGameState().theme, "retro");
+    assert.ok(h.notifies.some((l) => l.includes("theme → retro")));
+  });
+
+  it("menu toggle calls runtime.snapshot() so the widget refreshes live", async () => {
+    const seq = ["Turn game mode ON", "Done"];
+    let i = 0;
+    const h = makeHarness(dir, () => Promise.resolve(seq[i++] ?? undefined));
+    h.notifies.length = 0;
+    h.snapshotCalls.length = 0;
+    await h.commands["mega-compact-settings"].handler("", h.ctx);
+    assert.equal(getGameState().game_mode_on, true);
+    assert.ok(h.snapshotCalls.length >= 1, "snapshot() called so widget refreshes live");
+  });
+
   it("on enables game mode and persists", async () => {
     await run("on");
     assert.equal(getGameState().game_mode_on, true);

package/extensions/mega-game-cmds.ts

@@ -36,6 +36,16 @@ import { THEMES, THEME_IDS, getTheme, isValidTheme, nextTheme, DEFAULT_THEME } f
 /** Notify/usage tag + command name. Primary surface is /mega-compact-settings. */
 const TAG = "mega-compact-settings";
 
+/** Apply a game_state mutation to the live TUI: evict the memoized cache
+ *  (bumpGameState) THEN recompute the widget snapshot (snapshot(ctx)) so the
+ *  panel picks up the new theme/mode/toggle immediately — no pi restart needed.
+ *  snapshot() re-reads the (evicted) game_state into widgetData and re-registers
+ *  the widget factory. Order matters: bump first, snapshot second. */
+function applyChange(ctx: ExtensionContext, runtime: MegaRuntime): void {
+  runtime.bumpGameState();
+  runtime.snapshot(ctx);
+}
+
 /** Format the current state as a human-readable status line set. */
 function fmtState(s: GameState): string[] {
   return [
@@ -55,8 +65,19 @@ async function handleSettings(
   const stateDir = runtime.currentStateDir;
   const parts = args.trim().split(/\s+/).filter(Boolean);
 
-  // bare  → print current state.
+  // bare  → interactive in-app menu (ctx.ui.select picker). Falls back to a
+  // static status print when there's no interactive UI (RPC/print mode, or a
+  // test harness stubbing only notify). CLI subcommands below still work for
+  // power users + scripts.
   if (parts.length === 0) {
+    if (typeof ctx.ui.select === "function") {
+      try {
+        await runInteractiveMenu(ctx, runtime, stateDir);
+        return;
+      } catch {
+        // select threw (non-interactive impl) → fall through to status print
+      }
+    }
     const s = getGameState(stateDir);
     for (const line of fmtState(s)) ctx.ui.notify(line);
     return;
@@ -77,7 +98,7 @@ async function handleSettings(
   // on|off
   if (sub === "on" || sub === "off") {
     const s = setGameState({ game_mode_on: sub === "on" }, stateDir);
-    runtime.bumpGameState();
+    applyChange(ctx, runtime);
     ctx.ui.notify(`[${TAG}] game mode ${s.game_mode_on ? "ON" : "off"}`);
     return;
   }
@@ -103,7 +124,7 @@ async function handleSettings(
       return;
     }
     const s = setGameState({ theme: id }, stateDir);
-    runtime.bumpGameState();
+    applyChange(ctx, runtime);
     ctx.ui.notify(`[${TAG}] theme → ${s.theme} (${getTheme(s.theme)?.label ?? ""})`);
     return;
   }
@@ -116,7 +137,7 @@ async function handleSettings(
       return;
     }
     const s = setGameState({ tui_display_mode: arg }, stateDir);
-    runtime.bumpGameState();
+    applyChange(ctx, runtime);
     ctx.ui.notify(`[${TAG}] tui → ${s.tui_display_mode}`);
     return;
   }
@@ -126,6 +147,111 @@ async function handleSettings(
   );
 }
 
+/** Interactive in-app menu for bare `/mega-compact-settings`. Uses ctx.ui.select
+ * (a real TUI picker in interactive mode). Loops until the user cancels (or
+ * picks "Done"). Each action mutates the global game_state row + bumps the
+ * runtime cache so the widget/dashboard reflect it immediately.
+ *
+ * Guarded by the caller via `typeof ctx.ui.select === "function"`; if select is
+ * unavailable we fall back to the static fmtState notify print. */
+async function runInteractiveMenu(
+  ctx: ExtensionContext,
+  runtime: MegaRuntime,
+  stateDir: string,
+): Promise<void> {
+  for (;;) {
+    const s = getGameState(stateDir);
+    const toggleLabel = s.game_mode_on ? "Turn game mode OFF" : "Turn game mode ON";
+    const choice = await ctx.ui.select(
+      `[${TAG}] settings · game mode: ${s.game_mode_on ? "ON" : "off"} · theme: ${s.theme} · tui: ${s.tui_display_mode}`,
+      [toggleLabel, "Theme…", "TUI display mode…", "Achievements…", "Done"],
+    );
+    if (choice === undefined || choice === "Done") return;
+    if (choice === toggleLabel) {
+      const next = !s.game_mode_on;
+      setGameState({ game_mode_on: next }, stateDir);
+      applyChange(ctx, runtime);
+      ctx.ui.notify(`[${TAG}] game mode ${next ? "ON" : "off"}`, "info");
+      continue;
+    }
+    if (choice === "Theme…") {
+      await themeSubmenu(ctx, runtime, stateDir);
+      continue;
+    }
+    if (choice === "TUI display mode…") {
+      await tuiSubmenu(ctx, runtime, stateDir);
+      continue;
+    }
+    if (choice === "Achievements…") {
+      await achievementsView(ctx, stateDir);
+      continue;
+    }
+  }
+}
+
+/** Theme picker submenu — lists all themes (current marked ✓) + a cycle option. */
+async function themeSubmenu(
+  ctx: ExtensionContext,
+  runtime: MegaRuntime,
+  stateDir: string,
+): Promise<void> {
+  const s = getGameState(stateDir);
+  const opts = THEMES.map((t) => {
+    const mark = t.id === s.theme ? " ✓" : "";
+    return `${t.id}${mark}  ${t.label}`;
+  });
+  opts.push("next (cycle to next theme)");
+  opts.push("Back");
+  const choice = await ctx.ui.select(`[${TAG}] theme (current: ${s.theme})`, opts);
+  if (choice === undefined || choice === "Back") return;
+  const first = choice.split(/\s+/)[0]!;
+  let id: string | undefined;
+  if (first === "next") {
+    id = nextTheme(s.theme);
+  } else if (isValidTheme(first)) {
+    id = first;
+  }
+  if (id && id !== s.theme) {
+    setGameState({ theme: id }, stateDir);
+    applyChange(ctx, runtime);
+    ctx.ui.notify(`[${TAG}] theme → ${id} (${getTheme(id)?.label ?? ""})`, "info");
+  }
+}
+
+/** TUI display-mode submenu — full vs minimal (current marked ✓). */
+async function tuiSubmenu(
+  ctx: ExtensionContext,
+  runtime: MegaRuntime,
+  stateDir: string,
+): Promise<void> {
+  const s = getGameState(stateDir);
+  const mark = (m: string) => (s.tui_display_mode === m ? " ✓" : "");
+  const choice = await ctx.ui.select(`[${TAG}] TUI display mode (current: ${s.tui_display_mode})`, [
+    `full${mark("full")}  — bars, stats, flair`,
+    `minimal${mark("minimal")}  — one-line level + cache %`,
+    "Back",
+  ]);
+  if (choice === undefined || choice === "Back") return;
+  const mode = choice.split(/\s+/)[0];
+  if (mode === "full" || mode === "minimal") {
+    setGameState({ tui_display_mode: mode }, stateDir);
+    applyChange(ctx, runtime);
+    ctx.ui.notify(`[${TAG}] tui → ${mode}`, "info");
+  }
+}
+
+/** Achievements view — terse notify list + a read-only select viewer. */
+async function achievementsView(ctx: ExtensionContext, stateDir: string): Promise<void> {
+  const rows = listAchievements(stateDir).filter((r) => r.unlocked_at != null);
+  ctx.ui.notify(`[${TAG}] achievements unlocked (${rows.length}/9):`, "info");
+  for (const r of rows) ctx.ui.notify(`  ${r.icon ?? ""} ${r.title}`, "info");
+  const lines = rows.length
+    ? rows.map((r) => `${r.icon ?? ""} ${r.title}`)
+    : ["(none unlocked yet — keep compacting!)"];
+  // select() as a read-only viewer; any selection / cancel returns to the menu.
+  await ctx.ui.select(`[${TAG}] achievements (${rows.length}/9 unlocked)`, lines);
+}
+
 /** Register /mega-compact-settings (primary) + /mega-game (backward-compat alias). */
 export function registerGameCommands(pi: ExtensionAPI, runtime: MegaRuntime): void {
   const description =

package/extensions/mega-pipeline/compact.ts

@@ -79,6 +79,7 @@ function doCompact(
   runtime: MegaRuntime,
 ): RunCompactResult {
   runtime.pulsing = true; // animate the status line while the (sync) pipeline runs
+  runtime.setEffect?.("pulse", "accent", 1500); // v0.8.3: ambient border pulse during compaction
   // S21.2: reset the per-compaction memory-op counter so the post-compact
   // consolidate pass only fires when memory rows actually changed during the
   // compaction window (turn_end → auto-review may have written some).

package/extensions/mega-runtime/state.test.ts

@@ -58,6 +58,64 @@ function freshDir(): string {
 	return mkdtempSync(join(tmpdir(), "mc-state-"));
 }
 
+describe("MegaRuntime setEffect lifecycle (v0.8.3)", () => {
+	const dirs: string[] = [];
+	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("activeEffect starts null and setEffect arms it with startedAt ~now", () => {
+		const dir = freshDir(); dirs.push(dir);
+		process.env.MEGACOMPACT_STATE_DIR = dir;
+		const rt = new MegaRuntime(minimalConfig(dir));
+		assert.equal(rt.activeEffect, null, "idle on construction");
+		const before = Date.now();
+		rt.setEffect("pulse", "accent", 2000);
+		const after = Date.now();
+		assert.equal(rt.activeEffect.type, "pulse");
+		assert.equal(rt.activeEffect.role, "accent");
+		assert.equal(rt.activeEffect.durationMs, 2000);
+		assert.ok(
+			rt.activeEffect.startedAt >= before && rt.activeEffect.startedAt <= after,
+			"startedAt within the call window",
+		);
+	});
+
+	it("setEffect replaces an in-flight effect (last call wins)", () => {
+		const dir = freshDir(); dirs.push(dir);
+		process.env.MEGACOMPACT_STATE_DIR = dir;
+		const rt = new MegaRuntime(minimalConfig(dir));
+		rt.setEffect("pulse", "accent", 2000);
+		const first = rt.activeEffect;
+		rt.setEffect("flash", "mega", 1200);
+		assert.notEqual(rt.activeEffect, first, "a fresh object replaced the prior");
+		assert.equal(rt.activeEffect.type, "flash");
+		assert.equal(rt.activeEffect.role, "mega");
+		assert.equal(rt.activeEffect.durationMs, 1200);
+	});
+
+	it("a backdated effect is recognized as expired by the snapshot predicate", () => {
+		const dir = freshDir(); dirs.push(dir);
+		process.env.MEGACOMPACT_STATE_DIR = dir;
+		const rt = new MegaRuntime(minimalConfig(dir));
+		rt.setEffect("pulse", "accent", 2000);
+		// Backdate startedAt past the duration window (no snapshot/ctx needed —
+		// this mirrors the exact predicate snapshot() runs after the flare consume).
+		rt.activeEffect.startedAt = Date.now() - 3000;
+		const expired =
+			!!rt.activeEffect &&
+			Date.now() - rt.activeEffect.startedAt >= rt.activeEffect.durationMs;
+		assert.ok(expired, "backdated effect satisfies the expiry predicate");
+		// Clearing mirrors the snapshot() bookkeeping branch:
+		if (expired) rt.activeEffect = null;
+		assert.equal(rt.activeEffect, null, "cleared once expired");
+	});
+});
+
 describe("MegaRuntime game-state cache (S31)", () => {
 	const dirs: string[] = [];
 	after(() => {

package/extensions/mega-runtime/state.ts

@@ -97,6 +97,12 @@ export class MegaRuntime {
 	// when cachePct > 100). Copied into widgetData.megaCacheFlare on the next
 	// snapshot() so the widget renders the oopsie gag, then reset (one cycle).
 	megaCacheFlare = false;
+	/** v0.8.3: ambient effect state for animated panel borders keyed off
+	 *  status transitions (level-up, mega-cache overshoot, achievement unlock,
+	 *  compaction start). Threaded into widgetData as `activeEffect`; the widget
+	 *  computes the per-frame phase from startedAt vs Date.now() (non-expired).
+	 *  Null when idle/expired. */
+	activeEffect: { type: "pulse" | "flash"; role: "accent" | "mega" | "red"; startedAt: number; durationMs: number } | null = null;
 	megaCacheFlarePct = 0;
 	levelUpFlare = false;
 	lastLevel = 0;
@@ -575,7 +581,11 @@ export class MegaRuntime {
 			const gs = this.getCachedGameState();
 			// S34: derive the level-up flare from the turn count each snapshot.
 			const curLevel = this.getTurnLevel();
-			if (curLevel > this.lastLevel) this.levelUpFlare = true;
+			if (curLevel > this.lastLevel) {
+				this.levelUpFlare = true;
+				// v0.8.3: arm a pulse border effect to celebrate the level-up.
+				this.setEffect("pulse", "accent", 1500);
+			}
 			const cachePct = st.dedupHitRate * 100;
 			this.widgetData = {
 				version: ownVersion(),
@@ -619,6 +629,9 @@ export class MegaRuntime {
 				levelUpFlare: this.levelUpFlare,
 				achievementFlare: this.achievementFlare,
 				achievementFlareTitles: this.achievementFlareTitles,
+				// v0.8.3: ambient border effect — threaded live so the widget can
+				// compute the per-frame phase and render animated borders.
+				activeEffect: this.activeEffect,
 			};
 			// S33: consume the flare after copying it into widgetData so it fires
 			// for exactly one render cycle (the gag flares once, then clears).
@@ -633,6 +646,19 @@ export class MegaRuntime {
 			// (mirrors the megaCacheFlare/levelUpFlare one-shot semantics).
 			this.achievementFlare = false;
 			this.achievementFlareTitles = [];
+			// v0.8.3: expire the ambient border effect once its time window has
+			// elapsed. SEPARATE from the one-shot flares above (those are per-cycle
+			// consumes; activeEffect is time-windowed and cleared when Date.now()
+			// crosses startedAt + durationMs). The widget also defends this per-frame
+			// (effectBorderSgr returns '' once expired), so this is bookkeeping to
+			// free the slot and prevent a stale effect lingering between snapshots.
+			if (
+				this.activeEffect &&
+				Date.now() - this.activeEffect.startedAt >=
+					this.activeEffect.durationMs
+			) {
+				this.activeEffect = null;
+			}
 			// Auto-fit: register a factory so pi re-renders the panel at the REAL
 			// terminal width every frame (tui.columns), instead of guessing with
 			// process.stdout.columns. buildWidgetLines reads this.widgetData live.
@@ -915,18 +941,37 @@ export class MegaRuntime {
 	}
 
 	/** S33: arm the transient MEGA CACHE flare so the next snapshot() copies it
-	 *  into widgetData and the widget renders the oopsie gag for one cycle. */
+	 *  into widgetData and the widget renders the oopsie gag for one cycle.
+	 *  v0.8.3: also arm a 'flash' ambient effect on the panel borders (mega
+	 *  color) for 1.2s. */
 	armMegaCacheFlare(peakPct: number): void {
 		this.megaCacheFlare = true;
 		this.megaCacheFlarePct = peakPct;
+		this.setEffect("flash", "mega", 1200);
 	}
 
 	/** S35: arm the transient achievement-unlock flare with the newly-unlocked
 	 *  titles so the next snapshot() copies them into widgetData and the widget
-	 *  renders the one-time unlock toast for one render cycle. */
+	 *  renders the one-time unlock toast for one render cycle.
+	 *  v0.8.3: also arm a 'pulse' ambient effect on the panel borders (accent
+	 *  color) for 2s to celebrate the unlock. */
 	armAchievementFlare(titles: string[]): void {
 		this.achievementFlare = true;
 		this.achievementFlareTitles = titles;
+		this.setEffect("pulse", "accent", 2000);
+	}
+
+	/** v0.8.3: arm an ambient border effect (animated pulse/flash on the panel
+	 *  borders). Replaces any in-flight effect (last call wins — a later event
+	 *  like a level-up during an achievement pulse simply overrides). The widget
+	 *  reads activeEffect each frame and computes the per-frame phase from
+	 *  startedAt vs Date.now(); it renders '' once the window elapses. */
+	setEffect(
+		type: "pulse" | "flash",
+		role: "accent" | "mega" | "red",
+		durationMs: number,
+	): void {
+		this.activeEffect = { type, role, startedAt: Date.now(), durationMs };
 	}
 
 	/** Build the sync onTier callback that paints the live per-tier trace. */

package/extensions/mega-runtime/widget.test.ts

@@ -162,6 +162,56 @@ describe("buildWidgetLines (S31)", () => {
 });
 
 
+describe("buildWidgetLines ambient border effect (v0.8.3)", () => {
+  const effBase = (overrides: Partial<WidgetData> = {}): WidgetData => baseWd({
+    theme: DEFAULT_THEME, tuiMode: "full", gameMode: true, level: 1, cachePct: 42, ...overrides,
+  });
+  const isBorder = (l: string): boolean => l.includes("─");
+
+  it("activeEffect (pulse, mid-window) -> border lines carry a 256-color fg SGR", () => {
+    const ae = { type: "pulse" as const, role: "accent" as const, startedAt: Date.now() - 250, durationMs: 2000 };
+    const lines = buildWidgetLines(effBase({ activeEffect: ae }), WIDTH, 0);
+    const borders = lines.filter(isBorder);
+    assert.ok(borders.length >= 2, "has top + bottom borders");
+    for (const b of borders) {
+      assert.ok(b.includes("\x1b[38;5;"), `border carries 256-color fg: ${JSON.stringify(b)}`);
+    }
+  });
+
+  it("activeEffect null -> plain borders, no 38;5 fg SGR on border lines", () => {
+    const lines = buildWidgetLines(effBase({ activeEffect: null }), WIDTH, 0);
+    const borders = lines.filter(isBorder);
+    for (const b of borders) {
+      assert.ok(!b.includes("\x1b[38;5;"), `no effect SGR on plain border: ${JSON.stringify(b)}`);
+    }
+  });
+
+  it("expired activeEffect -> plain borders (per-frame expiry enforced)", () => {
+    const ae = { type: "pulse" as const, role: "accent" as const, startedAt: Date.now() - 5000, durationMs: 1000 };
+    const lines = buildWidgetLines(effBase({ activeEffect: ae }), WIDTH, 0);
+    const borders = lines.filter(isBorder);
+    for (const b of borders) {
+      assert.ok(!b.includes("\x1b[38;5;"), `expired effect -> plain border: ${JSON.stringify(b)}`);
+    }
+  });
+
+  it("activeEffect border lines are width-safe (pulse, minimal + full)", () => {
+    for (const tuiMode of ["minimal", "full"] as const) {
+      const ae = { type: "pulse" as const, role: "mega" as const, startedAt: Date.now() - 100, durationMs: 2000 };
+      const lines = buildWidgetLines(effBase({ activeEffect: ae, tuiMode }), 60, 0);
+      for (const l of lines) assert.ok(visibleWidth(l) <= 60, `width safe (${tuiMode}): ${visibleWidth(l)}`);
+    }
+  });
+
+  it("flash effect mid-window border carries the full base index SGR", () => {
+    // Force an 'on' phase of the 120ms alternate by starting just now.
+    const ae = { type: "flash" as const, role: "red" as const, startedAt: Date.now(), durationMs: 1200 };
+    const lines = buildWidgetLines(effBase({ activeEffect: ae }), WIDTH, 0);
+    const borders = lines.filter(isBorder);
+    assert.ok(borders.some((b) => b.includes("\x1b[38;5;203m")), `flash-on phase uses red base 203`);
+  });
+});
+
 describe("buildWidgetLines achievement flare (S35)", () => {
   const achBase = (overrides: Partial<WidgetData> = {}): WidgetData => baseWd({
     theme: DEFAULT_THEME, tuiMode: "full", gameMode: true, level: 1, cachePct: 42, ...overrides,

package/extensions/mega-runtime/widget.ts

@@ -128,6 +128,51 @@ function panelBar(width: number, ch = "─", panelBg: string = DEFAULT_PANEL_BG)
 	return truncateToWidth(panelBg + ch.repeat(Math.max(0, width)), width, "", false) + "\x1b[0m";
 }
 
+// ── v0.8.3: ambient border-effect helpers ───────────────────────────────
+// The panel borders animate when an `activeEffect` is armed (level-up,
+// mega-cache overshoot, achievement unlock, compaction start). Two modes:
+//   • pulse — a sine ramp on a 256-color base (accent=51 / mega=214 / red=203):
+//     the base index is scaled by sin(π·t) so the border swells 0→peak→0 over
+//     the duration, then returns to '' (idle). 256-color indices are clamped
+//     to 0–255 defensively (the bases are all ≤214 so the clamp rarely bites).
+//   • flash — a 120ms hard on/off alternate using the base index at full.
+// Returns '' when idle, expired, or elapsed<0 (clock skew) so non-effect
+// renders are byte-identical to the pre-effect panel (S31 matrix stays green).
+const EFFECT_BASE: Record<"accent" | "mega" | "red", number> = {
+	accent: 51,
+	mega: 214,
+	red: 203,
+};
+
+/** Resolve the per-frame border-fg SGR for an active effect. '' when idle or
+ *  expired (the widget's real per-frame expiry enforcer — snapshot-level clear
+ *  is just bookkeeping since snapshot is event-driven). */
+function effectBorderSgr(
+	ae: NonNullable<WidgetData["activeEffect"]> | null,
+	now: number,
+): string {
+	if (!ae) return "";
+	const elapsed = now - ae.startedAt;
+	if (elapsed < 0 || elapsed >= ae.durationMs) return "";
+	const base = EFFECT_BASE[ae.role];
+	if (ae.type === "flash") {
+		// 120ms hard alternate: on (full base) / off (no SGR).
+		return Math.floor(elapsed / 120) % 2 === 0 ? `\x1b[38;5;${base}m` : "";
+	}
+	// pulse: sine ramp 0 → peak → 0 over the duration.
+	const t = elapsed / ae.durationMs;
+	const amp = Math.sin(Math.PI * t); // 0 at start/end, 1 at midpoint
+	const idx = Math.max(0, Math.min(255, Math.round(base * amp)));
+	return `\x1b[38;5;${idx}m`;
+}
+
+/** Prepend the effect border SGR to a panel bar line. The SGR is a pure-fg
+ *  escape (zero visible width), so it never perturbs truncateToWidth's width
+ *  math — the bar's own `\x1b[0m` tail resets both fg + bg. No-op when sgr=''. */
+function effectBar(bar: string, sgr: string): string {
+	return sgr ? sgr + bar : bar;
+}
+
 /** Token-count formatter: M at/above 1e6, k at/above 1e3, raw below.
  *  5,472,700 → "5.5mil", 24,100 → "24.1k", 142 → "142". */
 function fmtTokens(x: number): string {
@@ -231,6 +276,15 @@ export interface WidgetData {
 	/** S35: achievement-unlock flare -- renders a one-line toast for one cycle. */
 	achievementFlare?: boolean;
 	achievementFlareTitles?: string[];
+	/** v0.8.3: ambient animated border effect (null when idle/expired). The
+	 *  widget computes the per-frame phase from startedAt vs Date.now() and
+	 *  renders a pulse/flash on the panel borders; '' once the window elapses. */
+	activeEffect?: {
+		type: "pulse" | "flash";
+		role: "accent" | "mega" | "red";
+		startedAt: number;
+		durationMs: number;
+	} | null;
 }
 
 // ── buildWidgetLines ───────────────────────────────────────────────────────
@@ -250,11 +304,16 @@ export function buildWidgetLines(
 	// every panelLine/panelBar/wrapLine so the bg stays continuous and the width
 	// guard (truncateToWidth) still holds for transparent themes.
 	const panelBg = wd?.theme ? panelBgFor(wd.theme) : DEFAULT_PANEL_BG;
+	// v0.8.3: resolve the animated border SGR once per render. '' when idle,
+	// expired, or wd is null (warm-up) — so non-effect renders are byte-identical
+	// to the pre-effect panel (the existing S31 matrix tests stay green).
+	const now = Date.now();
+	const borderSgr = effectBorderSgr(wd?.activeEffect ?? null, now);
 	if (!wd) {
 		return [
-			panelBar(width, "─", panelBg),
+			effectBar(panelBar(width, "─", panelBg), borderSgr),
 			panelLine(" mega-compact: warming up…", width, panelBg),
-			panelBar(width, "─", panelBg),
+			effectBar(panelBar(width, "─", panelBg), borderSgr),
 		];
 	}
 	// S31: minimal TUI mode — a single content line `LVL n | cache NN%` flanked
@@ -276,9 +335,9 @@ export function buildWidgetLines(
 				? `${accent}${wd.gameMode && wd.levelUpFlare ? "\x1b[5m" : ""}LVL ${lvl}${wd.gameMode && wd.levelUpFlare ? "\x1b[0m" : ""}${sgrReset(accent)} ${C.dim}|${C.reset} cache ${cacheStr}${megaFlare}`
 				: `cache ${cacheStr}${megaFlare}`;
 		return [
-			panelBar(width, "─", panelBg),
+			effectBar(panelBar(width, "─", panelBg), borderSgr),
 			panelLine(` ${body}`, width, panelBg),
-			panelBar(width, "─", panelBg),
+			effectBar(panelBar(width, "─", panelBg), borderSgr),
 		];
 	}
 	const pulse = wd.pulsing
@@ -312,7 +371,7 @@ export function buildWidgetLines(
 	// Wrap to terminal width and pad each line
 	const wrapped = wrapLine(content, width - 2, panelBg); // 2-char indent
 	const lines: string[] = [
-		panelBar(width, "─", panelBg),
+		effectBar(panelBar(width, "─", panelBg), borderSgr),
 		...wrapped.map((l) => panelLine(l, width, panelBg)),
 	];
 	// L4 — agents block (S27, count + status; per-agent tokens gated on P0)
@@ -354,6 +413,6 @@ export function buildWidgetLines(
 		lines.push(panelLine(`   ${accentSgr}🏆 Achievement unlocked: ${titlesStr}${sgrReset(accentSgr)}`, width, panelBg));
 	}
 	// bottom border
-	lines.push(panelBar(width, "─", panelBg));
+	lines.push(effectBar(panelBar(width, "─", panelBg), borderSgr));
 	return lines;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-mega-compact",
-  "version": "0.8.1",
+  "version": "0.8.3",
   "description": "Layered, local, vector-backed context compressor for pi — supersede/collapse/cluster compaction with deduped inline recall.",
   "type": "module",
   "license": "BSD-2-Clause",