pi-mega-compact 0.20.25 → 0.20.26

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

@@ -254,9 +254,11 @@ export async function launchDashboardServer(stateDir) {
                     }));
                     v6.listen(port, "::1", () => log("ipv6 loopback bound", { port })); // guardrails-allow PREVENT-PI-004: IPv6 loopback (::1) mirror of the dashboard server
                 }
-                // Write port.pid
+                // Write port.pid (VC0F B2: stamp `version` so the launcher can detect
+                // a stale runner by comparing the marker against its own version
+                // without an HTTP probe — closes the orphan case for pre-B2 servers).
                 try {
-                    writeFileSync(portFile, JSON.stringify({ port, pid: process.pid }));
+                    writeFileSync(portFile, JSON.stringify({ port, pid: process.pid, version: SERVER_VERSION }));
                 }
                 catch (e) {
                     log("could not write port.pid", { error: String(e) });

package/dist/extensions/mega-dashboard-bounce.js

@@ -0,0 +1,79 @@
+/**
+ * mega-dashboard-bounce.ts — VC0F stale-runner detection + bounce.
+ *
+ * Delegate of `mega-dashboard-cmds.ts` (kept under the extensions/ soft limit):
+ * owns the once-per-process staleness gate and the pure
+ * `bounceStaleRunnerIfAny` decision, which is the durable restart-on-upgrade
+ * seam — after `pi update --extensions` replaces the on-disk package, the next
+ * `session_start` probes the running dashboard, sees the version mismatch, and
+ * kills + respawns the stale runner so it serves the current code.
+ *
+ * The function is dependency-injected so unit tests (VC0F C1–C3) can stub every
+ * primitive; the production wiring (live discovery / version / kill) lives in
+ * `mega-dashboard-cmds.ts` and is passed in. No network here — the localhost
+ * HTTP probes live behind the injected `isServerRunning`/`serverVersion` deps
+ * (already audited PREVENT-PI-004 in the parent file).
+ */
+/**
+ * Once-per-process staleness gate (VC0F A2). After the FIRST successful probe
+ * we skip re-probing on later /mega-dashboard invocations or session-start
+ * events within the same extension process — the probe is cheap but the
+ * kill+respawn it triggers is disruptive. Set regardless of outcome.
+ */
+let stalenessCheckedThisProcess = false;
+/** Test-only seam: clear the once-per-process gate between unit tests. */
+export function resetStalenessGateForTests() {
+    stalenessCheckedThisProcess = false;
+}
+/**
+ * Detect + replace a STALE dashboard runner for the current repo (VC0F A1).
+ *
+ * A runner is stale when it is an orphan (live but missing its port.pid
+ * marker), when its marker's stamped `version` differs from this extension's
+ * own version (VC0F B2 — avoids the HTTP probe), or when the version it
+ * reports over HTTP differs from our own (fallback for pre-B2 servers whose
+ * marker has no `version` field). A stale runner is killed so the next launch
+ * serves the current on-disk code.
+ *
+ * Best-effort and non-fatal (Goal 4): any failure returns `{bounced:false}`
+ * and never throws. Runs at most once per extension process (A2).
+ */
+export async function bounceStaleRunnerIfAny(deps) {
+    if (stalenessCheckedThisProcess)
+        return { bounced: false };
+    try {
+        stalenessCheckedThisProcess = true; // once per process, regardless of outcome
+        const info = await deps.isServerRunning();
+        if (!info)
+            return { bounced: false };
+        const orphan = !info.hasPidFile;
+        const want = deps.ownVersion();
+        const marker = deps.markerVersion();
+        let stale;
+        let from = null;
+        if (orphan) {
+            stale = true; // live server with no marker → orphan by definition
+        }
+        else if (want != null && marker != null) {
+            stale = marker !== want; // B2: compare the stamped marker, skip the HTTP probe
+            from = marker;
+        }
+        else {
+            const running = await deps.serverVersion(info.port);
+            from = running;
+            stale = want != null && running != null && running !== want;
+        }
+        if (stale) {
+            deps.notify(orphan
+                ? "[mega-compact] replacing orphaned dashboard server…"
+                : `[mega-compact] replacing stale dashboard (${from ?? "?"} → ${want ?? "?"})…`);
+            deps.killServerOnPort(info.port);
+            return { bounced: true };
+        }
+        return { bounced: false };
+    }
+    catch {
+        // Best-effort, non-fatal — a failed probe/kill never breaks the caller.
+        return { bounced: false };
+    }
+}

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

@@ -9,6 +9,11 @@ import { join, dirname, sep } from "node:path";
 import { fileURLToPath } from "node:url";
 import { existsSync, writeFileSync, readFileSync, unlinkSync, openSync, closeSync } from "node:fs";
 import { spawn, execSync } from "node:child_process"; // guardrails-allow PREVENT-PI-004: spawns the optional, user-triggered localhost dashboard server only
+import { bounceStaleRunnerIfAny, } from "./mega-dashboard-bounce.js";
+// Re-export the VC0F bounce seam for the unit tests, which import the parent
+// module. The implementation + once-per-process gate live in the sibling
+// delegate file to keep this module under the extensions/ soft limit (400).
+export { bounceStaleRunnerIfAny, resetStalenessGateForTests } from "./mega-dashboard-bounce.js";
 /** Register the dashboard server lifecycle commands. */
 export function registerDashboardCommands(pi, runtime) {
     // H3 fix: read currentStateDir at CALL time, not registration time. The
@@ -118,6 +123,27 @@ export function registerDashboardCommands(pi, runtime) {
         }
         catch { /* ignore */ }
     }
+    /** Version stamped in the current repo's port.pid marker (VC0F B2), or null
+     *  when the marker is absent or predates the stamped `version` field. */
+    function markerVersion() {
+        try {
+            const info = JSON.parse(readFileSync(portFile(), "utf-8"));
+            return typeof info.version === "string" ? info.version : null;
+        }
+        catch {
+            return null;
+        }
+    }
+    /**
+     * Build the dependency set `bounceStaleRunnerIfAny` needs for the CURRENT
+     * repo's dashboard lifecycle (port.pid / runner / launch-log all resolve via
+     * `runtime.currentStateDir`, so a repo switch re-targets the bounce).
+     * `notify` is threaded here so the interactive /mega-dashboard path surfaces
+     * the replace messages while the silent session-start path is a no-op.
+     */
+    function staleBounceDeps(notify) {
+        return { isServerRunning, serverVersion, markerVersion, ownVersion, killServerOnPort, notify };
+    }
     /**
      * Resolve the launchable dashboard-server module.
      *
@@ -157,9 +183,14 @@ export function registerDashboardCommands(pi, runtime) {
         if (!resolved)
             return false;
         dashboardNeedsStrip = resolved.needsStripTypes;
+        // VC0F B1: stamp the extension version in the generated script at WRITE time
+        // so a future probe can compare it against ownVersion() without a live HTTP
+        // round-trip (useful when the server is hung and /api/version times out).
+        const stampedVersion = ownVersion() ?? "0.0.0";
         const script = [
             `import { appendFileSync } from "node:fs";`,
             `const __log = ${JSON.stringify(launchLog())};`,
+            `const __VERSION = ${JSON.stringify(stampedVersion)}; // mega-compact bundle version stamped at write time (VC0F B1)`,
             `function __fail(err) {`,
             `  const msg = "[mega-compact] dashboard failed: " + (err && err.stack ? err.stack : String(err));`,
             `  try { appendFileSync(__log, msg + "\\n"); } catch { /* ignore */ }`,
@@ -188,31 +219,18 @@ export function registerDashboardCommands(pi, runtime) {
         description: "Start the local web dashboard and optionally open it in the default browser.",
         handler: async (_args, ctx) => {
             runtime.bindRepo(ctx.cwd);
-            let info = await isServerRunning();
+            // VC0F A1: lift the stale-replace decision out of the handler. Interactive
+            // path is unchanged — the user is still notified before a stale runner is
+            // killed. When a stale server is bounced, we fall straight through to a
+            // fresh spawn; otherwise reuse the live current server if there is one.
+            const { bounced } = await bounceStaleRunnerIfAny(staleBounceDeps((msg) => ctx.ui.notify(msg)));
+            const info = bounced ? null : await isServerRunning();
             if (info) {
-                // Replace the server when it's stale: either (a) an orphan — a live
-                // server with no port.pid (e.g. left running from a detached spawn or a
-                // previous upgrade) that keeps serving old HTML from memory; or (b) a
-                // server that reports a different version than this extension (an older
-                // build). A live server WITH a matching pid file and version is reused.
-                const orphan = !info.hasPidFile;
-                const running = await serverVersion(info.port);
-                const want = ownVersion();
-                const stale = orphan || (want != null && running != null && running !== want);
-                if (stale) {
-                    ctx.ui.notify(orphan
-                        ? "[mega-compact] replacing orphaned dashboard server…"
-                        : `[mega-compact] replacing stale dashboard (${running} → ${want})…`);
-                    killServerOnPort(info.port);
-                    info = null;
-                }
-                else {
-                    ctx.ui.notify(`[mega-compact] dashboard already running at ${info.url}`);
-                    const open = await ctx.ui.confirm("mega-compact dashboard", `Open ${info.url} in browser?`);
-                    if (open)
-                        openBrowser(info.url);
-                    return;
-                }
+                ctx.ui.notify(`[mega-compact] dashboard already running at ${info.url}`);
+                const open = await ctx.ui.confirm("mega-compact dashboard", `Open ${info.url} in browser?`);
+                if (open)
+                    openBrowser(info.url);
+                return;
             }
             // Start the server
             ctx.ui.notify("[mega-compact] starting dashboard server…");
@@ -332,4 +350,19 @@ export function registerDashboardCommands(pi, runtime) {
             }
         },
     });
+    // VC0F A3 — durable restart-on-upgrade: after `pi update --extensions`
+    // replaces the on-disk package, the next pi session probes the running
+    // dashboard, sees the version mismatch, and kills + respawns the stale runner
+    // automatically. SILENT — no ctx.ui.notify on this session-start path (unlike
+    // the explicit /mega-dashboard path). Best-effort and non-fatal: a probe or
+    // kill failure here never breaks session startup.
+    pi.on("session_start", async (_event, ctx) => {
+        runtime.bindRepo(ctx.cwd);
+        try {
+            await bounceStaleRunnerIfAny(staleBounceDeps(() => { }));
+        }
+        catch {
+            /* best-effort — never break the session */
+        }
+    });
 }

package/extensions/dashboard-server/server.ts

@@ -302,9 +302,11 @@ export async function launchDashboardServer(
 					v6.listen(port, "::1", () => log("ipv6 loopback bound", { port })); // guardrails-allow PREVENT-PI-004: IPv6 loopback (::1) mirror of the dashboard server
 				}
 
-				// Write port.pid
+				// Write port.pid (VC0F B2: stamp `version` so the launcher can detect
+				// a stale runner by comparing the marker against its own version
+				// without an HTTP probe — closes the orphan case for pre-B2 servers).
 				try {
-					writeFileSync(portFile, JSON.stringify({ port, pid: process.pid }));
+					writeFileSync(portFile, JSON.stringify({ port, pid: process.pid, version: SERVER_VERSION }));
 				} catch (e) {
 					log("could not write port.pid", { error: String(e) });
 				}

package/extensions/mega-dashboard-bounce.ts

@@ -0,0 +1,97 @@
+/**
+ * mega-dashboard-bounce.ts — VC0F stale-runner detection + bounce.
+ *
+ * Delegate of `mega-dashboard-cmds.ts` (kept under the extensions/ soft limit):
+ * owns the once-per-process staleness gate and the pure
+ * `bounceStaleRunnerIfAny` decision, which is the durable restart-on-upgrade
+ * seam — after `pi update --extensions` replaces the on-disk package, the next
+ * `session_start` probes the running dashboard, sees the version mismatch, and
+ * kills + respawns the stale runner so it serves the current code.
+ *
+ * The function is dependency-injected so unit tests (VC0F C1–C3) can stub every
+ * primitive; the production wiring (live discovery / version / kill) lives in
+ * `mega-dashboard-cmds.ts` and is passed in. No network here — the localhost
+ * HTTP probes live behind the injected `isServerRunning`/`serverVersion` deps
+ * (already audited PREVENT-PI-004 in the parent file).
+ */
+
+/**
+ * Once-per-process staleness gate (VC0F A2). After the FIRST successful probe
+ * we skip re-probing on later /mega-dashboard invocations or session-start
+ * events within the same extension process — the probe is cheap but the
+ * kill+respawn it triggers is disruptive. Set regardless of outcome.
+ */
+let stalenessCheckedThisProcess = false;
+
+/** Test-only seam: clear the once-per-process gate between unit tests. */
+export function resetStalenessGateForTests(): void {
+  stalenessCheckedThisProcess = false;
+}
+
+/** Injectables `bounceStaleRunnerIfAny` needs from the current repo's dashboard
+ *  lifecycle. Injected so the unit tests (VC0F C1–C3) can stub each primitive
+ *  independently. */
+export interface BounceStaleDeps {
+  /** Discover a live dashboard server for the current repo, or null. */
+  isServerRunning(): Promise<{ port: number; url: string; hasPidFile: boolean } | null>;
+  /** Version the running server reports via HTTP (/api/version), or null. */
+  serverVersion(port: number): Promise<string | null>;
+  /** Version stamped in the current repo's port.pid marker, or null. */
+  markerVersion(): string | null;
+  /** Version of THIS extension package (from its own package.json). */
+  ownVersion(): string | null;
+  /** Kill the server on `port` and clear its marker (best-effort). */
+  killServerOnPort(port: number): void;
+  /** User notification; a no-op on the silent session-start path (VC0F A3). */
+  notify(message: string): void;
+}
+
+/**
+ * Detect + replace a STALE dashboard runner for the current repo (VC0F A1).
+ *
+ * A runner is stale when it is an orphan (live but missing its port.pid
+ * marker), when its marker's stamped `version` differs from this extension's
+ * own version (VC0F B2 — avoids the HTTP probe), or when the version it
+ * reports over HTTP differs from our own (fallback for pre-B2 servers whose
+ * marker has no `version` field). A stale runner is killed so the next launch
+ * serves the current on-disk code.
+ *
+ * Best-effort and non-fatal (Goal 4): any failure returns `{bounced:false}`
+ * and never throws. Runs at most once per extension process (A2).
+ */
+export async function bounceStaleRunnerIfAny(deps: BounceStaleDeps): Promise<{ bounced: boolean }> {
+  if (stalenessCheckedThisProcess) return { bounced: false };
+  try {
+    stalenessCheckedThisProcess = true; // once per process, regardless of outcome
+    const info = await deps.isServerRunning();
+    if (!info) return { bounced: false };
+    const orphan = !info.hasPidFile;
+    const want = deps.ownVersion();
+    const marker = deps.markerVersion();
+    let stale: boolean;
+    let from: string | null = null;
+    if (orphan) {
+      stale = true; // live server with no marker → orphan by definition
+    } else if (want != null && marker != null) {
+      stale = marker !== want; // B2: compare the stamped marker, skip the HTTP probe
+      from = marker;
+    } else {
+      const running = await deps.serverVersion(info.port);
+      from = running;
+      stale = want != null && running != null && running !== want;
+    }
+    if (stale) {
+      deps.notify(
+        orphan
+          ? "[mega-compact] replacing orphaned dashboard server…"
+          : `[mega-compact] replacing stale dashboard (${from ?? "?"} → ${want ?? "?"})…`,
+      );
+      deps.killServerOnPort(info.port);
+      return { bounced: true };
+    }
+    return { bounced: false };
+  } catch {
+    // Best-effort, non-fatal — a failed probe/kill never breaks the caller.
+    return { bounced: false };
+  }
+}

package/extensions/mega-dashboard-cmds.ts

@@ -12,6 +12,15 @@ import { fileURLToPath } from "node:url";
 import { existsSync, writeFileSync, readFileSync, unlinkSync, openSync, closeSync } from "node:fs";
 import { spawn, execSync } from "node:child_process"; // guardrails-allow PREVENT-PI-004: spawns the optional, user-triggered localhost dashboard server only
 import type { MegaRuntime } from "./mega-runtime.js";
+import {
+  bounceStaleRunnerIfAny,
+  type BounceStaleDeps,
+} from "./mega-dashboard-bounce.js";
+
+// Re-export the VC0F bounce seam for the unit tests, which import the parent
+// module. The implementation + once-per-process gate live in the sibling
+// delegate file to keep this module under the extensions/ soft limit (400).
+export { bounceStaleRunnerIfAny, resetStalenessGateForTests, type BounceStaleDeps } from "./mega-dashboard-bounce.js";
 
 /** Register the dashboard server lifecycle commands. */
 export function registerDashboardCommands(pi: ExtensionAPI, runtime: MegaRuntime): void {
@@ -111,6 +120,28 @@ export function registerDashboardCommands(pi: ExtensionAPI, runtime: MegaRuntime
     try { unlinkSync(portFile()); } catch { /* ignore */ }
   }
 
+  /** Version stamped in the current repo's port.pid marker (VC0F B2), or null
+   *  when the marker is absent or predates the stamped `version` field. */
+  function markerVersion(): string | null {
+    try {
+      const info = JSON.parse(readFileSync(portFile(), "utf-8")) as { version?: unknown };
+      return typeof info.version === "string" ? info.version : null;
+    } catch {
+      return null;
+    }
+  }
+
+  /**
+   * Build the dependency set `bounceStaleRunnerIfAny` needs for the CURRENT
+   * repo's dashboard lifecycle (port.pid / runner / launch-log all resolve via
+   * `runtime.currentStateDir`, so a repo switch re-targets the bounce).
+   * `notify` is threaded here so the interactive /mega-dashboard path surfaces
+   * the replace messages while the silent session-start path is a no-op.
+   */
+  function staleBounceDeps(notify: (msg: string) => void): BounceStaleDeps {
+    return { isServerRunning, serverVersion, markerVersion, ownVersion, killServerOnPort, notify };
+  }
+
   /**
    * Resolve the launchable dashboard-server module.
    *
@@ -148,9 +179,14 @@ export function registerDashboardCommands(pi: ExtensionAPI, runtime: MegaRuntime
     const resolved = resolveDashboardEntry();
     if (!resolved) return false;
     dashboardNeedsStrip = resolved.needsStripTypes;
+    // VC0F B1: stamp the extension version in the generated script at WRITE time
+    // so a future probe can compare it against ownVersion() without a live HTTP
+    // round-trip (useful when the server is hung and /api/version times out).
+    const stampedVersion = ownVersion() ?? "0.0.0";
     const script = [
       `import { appendFileSync } from "node:fs";`,
       `const __log = ${JSON.stringify(launchLog())};`,
+      `const __VERSION = ${JSON.stringify(stampedVersion)}; // mega-compact bundle version stamped at write time (VC0F B1)`,
       `function __fail(err) {`,
       `  const msg = "[mega-compact] dashboard failed: " + (err && err.stack ? err.stack : String(err));`,
       `  try { appendFileSync(__log, msg + "\\n"); } catch { /* ignore */ }`,
@@ -181,32 +217,18 @@ export function registerDashboardCommands(pi: ExtensionAPI, runtime: MegaRuntime
     description: "Start the local web dashboard and optionally open it in the default browser.",
     handler: async (_args: string, ctx: ExtensionContext) => {
       runtime.bindRepo(ctx.cwd);
-      let info = await isServerRunning();
+      // VC0F A1: lift the stale-replace decision out of the handler. Interactive
+      // path is unchanged — the user is still notified before a stale runner is
+      // killed. When a stale server is bounced, we fall straight through to a
+      // fresh spawn; otherwise reuse the live current server if there is one.
+      const { bounced } = await bounceStaleRunnerIfAny(staleBounceDeps((msg) => ctx.ui.notify(msg)));
+      const info = bounced ? null : await isServerRunning();
 
       if (info) {
-        // Replace the server when it's stale: either (a) an orphan — a live
-        // server with no port.pid (e.g. left running from a detached spawn or a
-        // previous upgrade) that keeps serving old HTML from memory; or (b) a
-        // server that reports a different version than this extension (an older
-        // build). A live server WITH a matching pid file and version is reused.
-        const orphan = !info.hasPidFile;
-        const running = await serverVersion(info.port);
-        const want = ownVersion();
-        const stale = orphan || (want != null && running != null && running !== want);
-        if (stale) {
-          ctx.ui.notify(
-            orphan
-              ? "[mega-compact] replacing orphaned dashboard server…"
-              : `[mega-compact] replacing stale dashboard (${running} → ${want})…`,
-          );
-          killServerOnPort(info.port);
-          info = null;
-        } else {
-          ctx.ui.notify(`[mega-compact] dashboard already running at ${info.url}`);
-          const open = await ctx.ui.confirm("mega-compact dashboard", `Open ${info.url} in browser?`);
-          if (open) openBrowser(info.url);
-          return;
-        }
+        ctx.ui.notify(`[mega-compact] dashboard already running at ${info.url}`);
+        const open = await ctx.ui.confirm("mega-compact dashboard", `Open ${info.url} in browser?`);
+        if (open) openBrowser(info.url);
+        return;
       }
 
       // Start the server
@@ -310,4 +332,21 @@ export function registerDashboardCommands(pi: ExtensionAPI, runtime: MegaRuntime
       }
     },
   });
+
+  // VC0F A3 — durable restart-on-upgrade: after `pi update --extensions`
+  // replaces the on-disk package, the next pi session probes the running
+  // dashboard, sees the version mismatch, and kills + respawns the stale runner
+  // automatically. SILENT — no ctx.ui.notify on this session-start path (unlike
+  // the explicit /mega-dashboard path). Best-effort and non-fatal: a probe or
+  // kill failure here never breaks session startup.
+  pi.on("session_start", async (_event, ctx) => {
+    runtime.bindRepo(ctx.cwd);
+    try {
+      await bounceStaleRunnerIfAny(
+        staleBounceDeps(() => { /* session-start path stays silent (VC0F A3) */ }),
+      );
+    } catch {
+      /* best-effort — never break the session */
+    }
+  });
 }

package/package.json

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