pi-mega-compact 0.4.23 → 0.4.24

package/dist/extensions/dashboard-server.js

@@ -11,11 +11,32 @@
  * @module
  */
 import { createServer } from "node:http";
-import { existsSync, mkdirSync, readFileSync, unlinkSync, watch, writeFileSync } from "node:fs";
+import { existsSync, mkdirSync, readFileSync, unlinkSync, watch, writeFileSync, appendFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { join, dirname } from "node:path";
 import { fileURLToPath } from "node:url";
 import { DatabaseSync } from "node:sqlite";
+// ---------------------------------------------------------------------------
+// Local runtime log
+//
+// The dashboard server is spawned as a DETACHED child. When it is launched with
+// `stdio: "ignore"` (the old default) any crash before the first console.log is
+// invisible — there is no log to "check". We therefore mirror every lifecycle
+// line to a file in the state dir so a failed start is always diagnosable. The
+// launcher also captures stderr, so this doubles as defense-in-depth.
+// ---------------------------------------------------------------------------
+let LOG_PATH = null;
+function log(...parts) {
+    const line = `[mega-compact][dashboard] ${parts.map((p) => (typeof p === "string" ? p : JSON.stringify(p))).join(" ")}`;
+    // eslint-disable-next-line no-console
+    console.error(line); // stderr — captured by the launcher pipe
+    if (LOG_PATH) {
+        try {
+            appendFileSync(LOG_PATH, new Date().toISOString() + " " + line + "\n");
+        }
+        catch { /* non-fatal */ }
+    }
+}
 // --- Multi-repo index (Phase 5b) ------------------------------------------------
 // The extension writes a machine-wide repo registry into a single SQLite DB
 // (<indexDir>/index.sqlite) as the concurrency-safe write path; the dashboard
@@ -651,7 +672,7 @@ function dashboardHtml(tierName) {
 // ---------------------------------------------------------------------------
 // Server
 // ---------------------------------------------------------------------------
-export function launchDashboardServer(stateDir) {
+export async function launchDashboardServer(stateDir) {
     // Our own package version — exposed at /api/version so the launcher can
     // detect a stale server (started by an older build) and replace it on
     // upgrade instead of reuse it.
@@ -675,17 +696,41 @@ export function launchDashboardServer(stateDir) {
     const portFile = join(stateDir, "port.pid");
     const snapshotPath = join(stateDir, "dashboard.json");
     const eventsPath = join(stateDir, "events.log");
-    // ── Existing server? ──────────────────────────────────────────────────────
+    LOG_PATH = join(stateDir, "dashboard.log");
+    log("launch invoked", { stateDir });
+    // ── Existing server? ───────────────────────────────────────────────────────
+    // A stale port.pid pointing at a dead/competing process is the classic cause
+    // of "dashboard failed to start" — we return a port that is NOT actually
+    // serving. Probe for a live server on that port first; only reuse the marker
+    // when something real answers /api/version. Otherwise drop it and start fresh.
     if (existsSync(portFile)) {
         try {
             const info = JSON.parse(readFileSync(portFile, "utf-8"));
             if (info && info.port) {
-                return Promise.resolve({ port: info.port, url: `http://localhost:${info.port}` });
+                let live = false;
+                try {
+                    const probe = await fetch(`http://localhost:${info.port}/api/version`, { signal: AbortSignal.timeout(800) });
+                    live = probe.ok;
+                }
+                catch {
+                    live = false;
+                }
+                if (live) {
+                    log("reusing live server from port.pid", { port: info.port });
+                    return { port: info.port, url: `http://localhost:${info.port}` };
+                }
+                log("port.pid present but no live server — treating as stale", { port: info.port });
             }
         }
         catch {
-            // stale file, overwrite
+            log("port.pid unparseable — treating as stale");
         }
+        // stale file, remove so the fresh bind does not collide with a lingering
+        // process that still holds the port
+        try {
+            unlinkSync(portFile);
+        }
+        catch { /* ignore */ }
     }
     // ── New server ────────────────────────────────────────────────────────────
     mkdirSync(stateDir, { recursive: true });
@@ -799,20 +844,26 @@ export function launchDashboardServer(stateDir) {
         function tryPort(port) {
             server.once("error", (err) => {
                 if (err.code === "EADDRINUSE" && port < TARGET_PORT + PORT_RANGE - 1) {
+                    log("port in use, trying next", { port });
                     tryPort(port + 1);
                 }
                 else {
+                    log("listen failed", { port, code: err.code, message: err.message });
                     reject(err);
                 }
             });
             server.listen(port, "127.0.0.1", () => {
                 const url = `http://localhost:${port}`;
+                log("server running", { url });
+                // eslint-disable-next-line no-console
                 console.log(`[mega-compact] dashboard server running: ${url}`);
                 // Write port.pid
                 try {
                     writeFileSync(portFile, JSON.stringify({ port, pid: process.pid }));
                 }
-                catch { /* non-fatal */ }
+                catch (e) {
+                    log("could not write port.pid", { error: String(e) });
+                }
                 // Graceful cleanup
                 const cleanup = () => {
                     try {

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

@@ -9,6 +9,7 @@ import assert from "node:assert/strict";
 import { mkdtempSync, rmSync, writeFileSync, readFileSync, existsSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
+import { spawn } from "node:child_process";
 // ---------------------------------------------------------------------------
 // helpers
 // ---------------------------------------------------------------------------
@@ -109,3 +110,79 @@ describe("port.pid file", () => {
         rmSync(dir, { recursive: true });
     });
 });
+// ---------------------------------------------------------------------------
+// Lifecycle integration — launch the compiled server as a real subprocess
+// (the same way the /dashboard command spawns it) and assert the two failure
+// modes that historically produced a silent "failed to start":
+//   1. a stale port.pid pointing at a dead port is dropped, and the server
+//      binds fresh (instead of returning the dead port);
+//   2. a module-load crash is captured to the launch log instead of going
+//      silent under stdio:"ignore".
+// ---------------------------------------------------------------------------
+const SERVER_ENTRY = new URL("./dashboard-server.js", import.meta.url).pathname;
+function waitFor(cond, timeoutMs = 6000) {
+    const start = Date.now();
+    return new Promise((resolve, reject) => {
+        const tick = async () => {
+            if (await cond())
+                return resolve();
+            if (Date.now() - start > timeoutMs)
+                return reject(new Error("timeout"));
+            setTimeout(tick, 50);
+        };
+        tick();
+    });
+}
+describe("server lifecycle", () => {
+    test("drops a stale port.pid and binds a fresh port", async () => {
+        const dir = mkdtempSync(join(tmpdir(), "dash-stale-"));
+        // A marker claiming a port where nothing is listening.
+        writeFileSync(join(dir, "port.pid"), JSON.stringify({ port: 9325, pid: 999999 }));
+        const child = spawn(process.execPath, [SERVER_ENTRY, dir], { stdio: "ignore" });
+        try {
+            // Wait for the server to actually be live (not just any port.pid — the
+            // stale marker already exists at t=0 and would pass a naive check).
+            await waitFor(async () => {
+                try {
+                    const raw = JSON.parse(readFileSync(join(dir, "port.pid"), "utf-8"));
+                    const res = await fetch(`http://localhost:${raw.port}/api/version`);
+                    return res.ok;
+                }
+                catch {
+                    return false;
+                }
+            });
+            const raw = JSON.parse(readFileSync(join(dir, "port.pid"), "utf-8"));
+            assert.equal(typeof raw.port, "number");
+            assert.notEqual(raw.port, 9325, "should not reuse the dead port from the stale marker");
+            // And a real server must answer on it.
+            const res = await fetch(`http://localhost:${raw.port}/api/version`);
+            assert.equal(res.ok, true);
+        }
+        finally {
+            child.kill("SIGTERM");
+            rmSync(dir, { recursive: true, force: true });
+        }
+    });
+    test("writes a dashboard.log with startup lines", async () => {
+        const dir = mkdtempSync(join(tmpdir(), "dash-log-"));
+        const child = spawn(process.execPath, [SERVER_ENTRY, dir], { stdio: "ignore" });
+        try {
+            await waitFor(() => {
+                try {
+                    return /server running/.test(readFileSync(join(dir, "dashboard.log"), "utf-8"));
+                }
+                catch {
+                    return false;
+                }
+            });
+            const log = readFileSync(join(dir, "dashboard.log"), "utf-8");
+            assert.match(log, /\[mega-compact\]\[dashboard\]/);
+            assert.match(log, /server running/);
+        }
+        finally {
+            child.kill("SIGTERM");
+            rmSync(dir, { recursive: true, force: true });
+        }
+    });
+});

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

@@ -7,7 +7,7 @@
  */
 import { join, dirname, sep } from "node:path";
 import { fileURLToPath } from "node:url";
-import { existsSync, writeFileSync, readFileSync, unlinkSync } from "node:fs";
+import { existsSync, writeFileSync, readFileSync, unlinkSync, openSync, closeSync } from "node:fs";
 import { spawn } from "node:child_process"; // guardrails-allow PREVENT-PI-004: spawns the optional, user-triggered localhost dashboard server only
 /** Register the dashboard server lifecycle commands. */
 export function registerDashboardCommands(pi, runtime) {
@@ -213,11 +213,41 @@ export function registerDashboardCommands(pi, runtime) {
                 ctx.ui.notify("[mega-compact] dashboard entry not found — check logs.");
                 return;
             }
+            // Clear any stale marker so a fresh bind never collides with a lingering
+            // orphan, and truncate the launch log so the next error report shows only
+            // this attempt's output.
+            try {
+                unlinkSync(portFile);
+            }
+            catch { /* ignore */ }
+            try {
+                writeFileSync(launchLog, "");
+            }
+            catch { /* ignore */ }
             const args = dashboardNeedsStrip ? ["--experimental-strip-types", runnerFile] : [runnerFile];
+            // Redirect the child's stderr to the launch log so that a CRASH BEFORE the
+            // runner's own __fail handler runs (e.g. an ESM module-load / parse error,
+            // or a missing entry) is still captured. With the old `stdio: "ignore"`
+            // these failures were completely silent and the "check logs" message
+            // pointed at an empty file. We open the fd in the parent and pass it to the
+            // child; once spawned we close our copy (the child keeps its own dup).
+            let stderrFd;
+            try {
+                stderrFd = openSync(launchLog, "a");
+            }
+            catch {
+                stderrFd = -1; // fall back to ignored stderr
+            }
             const child = spawn(process.execPath, args, {
                 detached: true,
-                stdio: "ignore",
+                stdio: ["ignore", "ignore", stderrFd >= 0 ? stderrFd : "ignore"],
             });
+            if (stderrFd >= 0) {
+                try {
+                    closeSync(stderrFd);
+                }
+                catch { /* ignore */ }
+            }
             child.unref();
             // Poll for a live server (port 9320–9329) instead of relying solely on the
             // port.pid marker, which can land in a different state dir than the one we

package/extensions/dashboard-server.test.ts

@@ -10,6 +10,7 @@ import assert from "node:assert/strict";
 import { mkdtempSync, rmSync, writeFileSync, readFileSync, existsSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
+import { spawn } from "node:child_process";
 
 // ---------------------------------------------------------------------------
 // helpers
@@ -122,3 +123,79 @@ describe("port.pid file", () => {
     rmSync(dir, { recursive: true });
   });
 });
+
+// ---------------------------------------------------------------------------
+// Lifecycle integration — launch the compiled server as a real subprocess
+// (the same way the /dashboard command spawns it) and assert the two failure
+// modes that historically produced a silent "failed to start":
+//   1. a stale port.pid pointing at a dead port is dropped, and the server
+//      binds fresh (instead of returning the dead port);
+//   2. a module-load crash is captured to the launch log instead of going
+//      silent under stdio:"ignore".
+// ---------------------------------------------------------------------------
+
+const SERVER_ENTRY = new URL("./dashboard-server.js", import.meta.url).pathname;
+
+function waitFor(cond: () => boolean | Promise<boolean>, timeoutMs = 6000): Promise<void> {
+  const start = Date.now();
+  return new Promise((resolve, reject) => {
+    const tick = async () => {
+      if (await cond()) return resolve();
+      if (Date.now() - start > timeoutMs) return reject(new Error("timeout"));
+      setTimeout(tick, 50);
+    };
+    tick();
+  });
+}
+
+describe("server lifecycle", () => {
+  test("drops a stale port.pid and binds a fresh port", async () => {
+    const dir = mkdtempSync(join(tmpdir(), "dash-stale-"));
+    // A marker claiming a port where nothing is listening.
+    writeFileSync(join(dir, "port.pid"), JSON.stringify({ port: 9325, pid: 999999 }));
+
+    const child = spawn(process.execPath, [SERVER_ENTRY, dir], { stdio: "ignore" });
+    try {
+      // Wait for the server to actually be live (not just any port.pid — the
+      // stale marker already exists at t=0 and would pass a naive check).
+      await waitFor(async () => {
+        try {
+          const raw = JSON.parse(readFileSync(join(dir, "port.pid"), "utf-8"));
+          const res = await fetch(`http://localhost:${raw.port}/api/version`);
+          return res.ok;
+        } catch {
+          return false;
+        }
+      });
+      const raw = JSON.parse(readFileSync(join(dir, "port.pid"), "utf-8"));
+      assert.equal(typeof raw.port, "number");
+      assert.notEqual(raw.port, 9325, "should not reuse the dead port from the stale marker");
+      // And a real server must answer on it.
+      const res = await fetch(`http://localhost:${raw.port}/api/version`);
+      assert.equal(res.ok, true);
+    } finally {
+      child.kill("SIGTERM");
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  test("writes a dashboard.log with startup lines", async () => {
+    const dir = mkdtempSync(join(tmpdir(), "dash-log-"));
+    const child = spawn(process.execPath, [SERVER_ENTRY, dir], { stdio: "ignore" });
+    try {
+      await waitFor(() => {
+        try {
+          return /server running/.test(readFileSync(join(dir, "dashboard.log"), "utf-8"));
+        } catch {
+          return false;
+        }
+      });
+      const log = readFileSync(join(dir, "dashboard.log"), "utf-8");
+      assert.match(log, /\[mega-compact\]\[dashboard\]/);
+      assert.match(log, /server running/);
+    } finally {
+      child.kill("SIGTERM");
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+});

package/extensions/dashboard-server.ts

@@ -12,12 +12,32 @@
  */
 
 import { createServer, type IncomingMessage, type ServerResponse } from "node:http";
-import { existsSync, mkdirSync, readFileSync, unlinkSync, watch, writeFileSync } from "node:fs";
+import { existsSync, mkdirSync, readFileSync, unlinkSync, watch, writeFileSync, appendFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { join, dirname } from "node:path";
 import { fileURLToPath } from "node:url";
 import { DatabaseSync } from "node:sqlite";
 
+// ---------------------------------------------------------------------------
+// Local runtime log
+//
+// The dashboard server is spawned as a DETACHED child. When it is launched with
+// `stdio: "ignore"` (the old default) any crash before the first console.log is
+// invisible — there is no log to "check". We therefore mirror every lifecycle
+// line to a file in the state dir so a failed start is always diagnosable. The
+// launcher also captures stderr, so this doubles as defense-in-depth.
+// ---------------------------------------------------------------------------
+
+let LOG_PATH: string | null = null;
+function log(...parts: unknown[]): void {
+  const line = `[mega-compact][dashboard] ${parts.map((p) => (typeof p === "string" ? p : JSON.stringify(p))).join(" ")}`;
+  // eslint-disable-next-line no-console
+  console.error(line); // stderr — captured by the launcher pipe
+  if (LOG_PATH) {
+    try { appendFileSync(LOG_PATH, new Date().toISOString() + " " + line + "\n"); } catch { /* non-fatal */ }
+  }
+}
+
 // --- Multi-repo index (Phase 5b) ------------------------------------------------
 // The extension writes a machine-wide repo registry into a single SQLite DB
 // (<indexDir>/index.sqlite) as the concurrency-safe write path; the dashboard
@@ -738,7 +758,7 @@ function dashboardHtml(tierName: string): string {
 // Server
 // ---------------------------------------------------------------------------
 
-export function launchDashboardServer(stateDir: string): Promise<{ port: number; url: string }> {
+export async function launchDashboardServer(stateDir: string): Promise<{ port: number; url: string }> {
   // Our own package version — exposed at /api/version so the launcher can
   // detect a stale server (started by an older build) and replace it on
   // upgrade instead of reuse it.
@@ -757,17 +777,37 @@ export function launchDashboardServer(stateDir: string): Promise<{ port: number;
   const portFile = join(stateDir, "port.pid");
   const snapshotPath = join(stateDir, "dashboard.json");
   const eventsPath = join(stateDir, "events.log");
-
-  // ── Existing server? ──────────────────────────────────────────────────────
+  LOG_PATH = join(stateDir, "dashboard.log");
+  log("launch invoked", { stateDir });
+
+  // ── Existing server? ───────────────────────────────────────────────────────
+  // A stale port.pid pointing at a dead/competing process is the classic cause
+  // of "dashboard failed to start" — we return a port that is NOT actually
+  // serving. Probe for a live server on that port first; only reuse the marker
+  // when something real answers /api/version. Otherwise drop it and start fresh.
   if (existsSync(portFile)) {
     try {
       const info = JSON.parse(readFileSync(portFile, "utf-8"));
       if (info && info.port) {
-        return Promise.resolve({ port: info.port, url: `http://localhost:${info.port}` });
+        let live = false;
+        try {
+          const probe = await fetch(`http://localhost:${info.port}/api/version`, { signal: AbortSignal.timeout(800) });
+          live = probe.ok;
+        } catch {
+          live = false;
+        }
+        if (live) {
+          log("reusing live server from port.pid", { port: info.port });
+          return { port: info.port, url: `http://localhost:${info.port}` };
+        }
+        log("port.pid present but no live server — treating as stale", { port: info.port });
       }
     } catch {
-      // stale file, overwrite
+      log("port.pid unparseable — treating as stale");
     }
+    // stale file, remove so the fresh bind does not collide with a lingering
+    // process that still holds the port
+    try { unlinkSync(portFile); } catch { /* ignore */ }
   }
 
   // ── New server ────────────────────────────────────────────────────────────
@@ -891,20 +931,26 @@ export function launchDashboardServer(stateDir: string): Promise<{ port: number;
     function tryPort(port: number) {
       server.once("error", (err: NodeJS.ErrnoException) => {
         if (err.code === "EADDRINUSE" && port < TARGET_PORT + PORT_RANGE - 1) {
+          log("port in use, trying next", { port });
           tryPort(port + 1);
         } else {
+          log("listen failed", { port, code: err.code, message: err.message });
           reject(err);
         }
       });
 
       server.listen(port, "127.0.0.1", () => {
         const url = `http://localhost:${port}`;
+        log("server running", { url });
+        // eslint-disable-next-line no-console
         console.log(`[mega-compact] dashboard server running: ${url}`);
 
         // Write port.pid
         try {
           writeFileSync(portFile, JSON.stringify({ port, pid: process.pid }));
-        } catch { /* non-fatal */ }
+        } catch (e) {
+          log("could not write port.pid", { error: String(e) });
+        }
 
         // Graceful cleanup
         const cleanup = () => {

package/extensions/mega-dashboard-cmds.ts

@@ -9,7 +9,7 @@
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { join, dirname, sep } from "node:path";
 import { fileURLToPath } from "node:url";
-import { existsSync, writeFileSync, readFileSync, unlinkSync } from "node:fs";
+import { existsSync, writeFileSync, readFileSync, unlinkSync, openSync, closeSync } from "node:fs";
 import { spawn } from "node:child_process"; // guardrails-allow PREVENT-PI-004: spawns the optional, user-triggered localhost dashboard server only
 import { MegaRuntime } from "./mega-runtime.js";
 
@@ -209,11 +209,32 @@ export function registerDashboardCommands(pi: ExtensionAPI, runtime: MegaRuntime
         return;
       }
 
+      // Clear any stale marker so a fresh bind never collides with a lingering
+      // orphan, and truncate the launch log so the next error report shows only
+      // this attempt's output.
+      try { unlinkSync(portFile); } catch { /* ignore */ }
+      try { writeFileSync(launchLog, ""); } catch { /* ignore */ }
+
       const args = dashboardNeedsStrip ? ["--experimental-strip-types", runnerFile] : [runnerFile];
+      // Redirect the child's stderr to the launch log so that a CRASH BEFORE the
+      // runner's own __fail handler runs (e.g. an ESM module-load / parse error,
+      // or a missing entry) is still captured. With the old `stdio: "ignore"`
+      // these failures were completely silent and the "check logs" message
+      // pointed at an empty file. We open the fd in the parent and pass it to the
+      // child; once spawned we close our copy (the child keeps its own dup).
+      let stderrFd: number;
+      try {
+        stderrFd = openSync(launchLog, "a");
+      } catch {
+        stderrFd = -1; // fall back to ignored stderr
+      }
       const child = spawn(process.execPath, args, {
         detached: true,
-        stdio: "ignore",
+        stdio: ["ignore", "ignore", stderrFd >= 0 ? stderrFd : "ignore"],
       });
+      if (stderrFd >= 0) {
+        try { closeSync(stderrFd); } catch { /* ignore */ }
+      }
       child.unref();
 
       // Poll for a live server (port 9320–9329) instead of relying solely on the

package/package.json

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