@zaip-ai/cli 1.0.7 → 1.0.8

package/templates/.agents/dashboard/packages/local-runtime/start-dashboard.mjs

@@ -1,6 +1,6 @@
 import { spawn } from "node:child_process";
 import { createHash, randomBytes } from "node:crypto";
-import { appendFileSync, mkdirSync } from "node:fs";
+import { appendFileSync, closeSync, mkdirSync, openSync } from "node:fs";
 import {
   access,
   mkdir,
@@ -15,35 +15,57 @@ import {
 import { createServer as createHttpServer } from "node:http";
 import { createServer } from "node:net";
 import { tmpdir } from "node:os";
-import { dirname, join, resolve, win32 } from "node:path";
+import { dirname, join, relative, resolve, win32 } from "node:path";
 import process from "node:process";
 import { fileURLToPath } from "node:url";
+import { collectPreviousDashboardSessions } from "./start-dashboard-history.mjs";
+import {
+  stopOwnedDashboardProcess,
+  stopProcessTree,
+  teardownWarning,
+} from "./start-dashboard-processes.mjs";
 
+export {
+  isAncestorProcess,
+  isProcessAlive,
+  registeredListenerMatches,
+  stopOwnedDashboardProcess,
+  teardownWarning,
+} from "./start-dashboard-processes.mjs";
 export const host = "127.0.0.1";
-export const defaultPort = 4317;
+export const defaultPort = 4417;
 export const maxPortAttempts = 25;
-export const runtimeKind = "zaip-dashboard-local-runtime";
-
+export const runtimeKind = "zaip-dashboard-sqlite-runtime";
 const packageRoot = dirname(fileURLToPath(import.meta.url));
 export const workspaceRoot = resolve(packageRoot, "../../../..");
-export const workspaceKey = createHash("sha256").update(workspaceRoot).digest("hex").slice(0, 16);
-export const sessionDirectory = join(tmpdir(), "zaip-aios", workspaceKey);
-export const sessionPath = join(sessionDirectory, "dashboard-session.json");
-export const portRegistryPath = join(sessionDirectory, "dashboard-ports.json");
-export const lockPath = join(sessionDirectory, "dashboard-launcher.lock");
-export const launcherLogPath = join(sessionDirectory, "dashboard-launcher.log");
-
+export const workspaceKey = createHash("sha256").update(`${workspaceRoot}:dashboard-sqlite`).digest("hex").slice(0, 16);
+export const sessionDirectory = join(tmpdir(), "zaip-aios", `dashboard-sqlite-${workspaceKey}`);
+export const sessionPath = join(sessionDirectory, "dashboard-sqlite-session.json");
+export const portRegistryPath = join(sessionDirectory, "dashboard-sqlite-ports.json");
+export const lockPath = join(sessionDirectory, "dashboard-sqlite-launcher.lock");
+export const launcherLogPath = join(sessionDirectory, "dashboard-sqlite-launcher.log");
 const frontendRoot = resolve(workspaceRoot, ".agents/dashboard/apps/frontend/dist");
+const sqliteReadModelDirectory = resolve(workspaceRoot, ".local", "dashboard-sqlite");
+// Keep the immutable seed cache in one durable workspace location.  Runtime
+// generations and the isolated background refresher must never derive a
+// different cache directory from their temporary SQLite path.
+const sqliteSnapshotCacheDirectory = join(sqliteReadModelDirectory, "cache");
+// Node's bytecode cache is disposable runtime acceleration, never dashboard
+// data. Keep it beside the private SQLite generations so fresh-port semantics
+// and canonical sources remain unchanged.
+const nodeCompileCacheDirectory = join(sqliteReadModelDirectory, "node-compile-cache");
 const installedServer = resolve(packageRoot, "server.mjs");
-const sourceServer = resolve(packageRoot, "dist/server.js");
+const sourceServer = resolve(packageRoot, "dist/server.cjs");
 const healthPath = "/api/v2/health";
-// A fresh dashboard build can legitimately take longer than the old ten-second
-// contention window.  A second executable click waits for the first handoff
-// and then coalesces with it instead of surfacing a spurious lock failure.
+// Fresh-generation probe marker: changes the immutable source fingerprint only.
+// Keep the preparation lock through a full build so concurrent clicks coalesce safely.
 const lockTimeoutMs = 120_000;
 const staleLockMs = 30_000;
 const lockHeartbeatFloorMs = 10;
-const startupTimeoutMs = 12_000;
+// A cold immutable seed can legitimately take ~176 s on a busy Windows
+// volume. Keep the immediate preparation page and fresh-port handoff, but do
+// not kill that one-time canonical build before it can populate the cache.
+const startupTimeoutMs = 180_000;
 const maxServerStartAttempts = 4;
 const maxPortHistory = 50;
 const dashboardSourceRoots = [
@@ -52,20 +74,16 @@ const dashboardSourceRoots = [
   resolve(workspaceRoot, ".agents/dashboard/packages/ui/src"),
   resolve(packageRoot, "src"),
 ];
-
 export function preferredPort(value = process.env.ZAIP_SERVER_PORT) {
   const parsed = Number.parseInt(value ?? "", 10);
   return Number.isInteger(parsed) && parsed > 0 && parsed <= 65_535 ? parsed : defaultPort;
 }
-
 export function dashboardHealthUrl(port) {
   return `http://${host}:${port}${healthPath}`;
 }
-
-export function dashboardUrl(port, token) {
-  return `http://${host}:${port}/?token=${encodeURIComponent(token)}`;
+export function dashboardUrl(port, token, snapshotUpdating = false) {
+  return `http://${host}:${port}/?token=${encodeURIComponent(token)}${snapshotUpdating ? "&snapshot=updating" : ""}`;
 }
-
 export function appendLauncherLog(message) {
   try {
     mkdirSync(sessionDirectory, { recursive: true });
@@ -78,7 +96,6 @@ export function appendLauncherLog(message) {
     // Best-effort diagnostics must not hide the launcher failure.
   }
 }
-
 export function stripTerminalControlCodes(value) {
   const escapeCode = String.fromCharCode(27);
   const bell = String.fromCharCode(7);
@@ -93,16 +110,37 @@ export function stripTerminalControlCodes(value) {
     .replace(/\r/g, "")
     .trim();
 }
-
 export function formatLauncherError(value, maximumLength = 3_600) {
   const message = stripTerminalControlCodes(value);
   if (message.length <= maximumLength) return message;
-
   const firstHalf = Math.floor(maximumLength / 2);
   const lastHalf = maximumLength - firstHalf;
   return `${message.slice(0, firstHalf)}\n\n… detalhes reduzidos; consulte o log temporário …\n\n${message.slice(-lastHalf)}`;
 }
-
+export async function assertDashboardPrerequisites() {
+  const major = Number.parseInt(process.versions.node.split(".")[0] ?? "", 10);
+  if (!Number.isInteger(major) || major < 22)
+    throw new Error(
+      `O Dashboard SQLite requer Node.js 22 ou superior; a versão encontrada foi ${process.versions.node}. Instale o Node.js 22 e tente novamente.`,
+    );
+  try {
+    await import("node:sqlite");
+  } catch {
+    throw new Error(
+      "O Node.js instalado não disponibiliza node:sqlite. Reinstale uma versão suportada do Node.js 22 ou superior.",
+    );
+  }
+  for (const required of [
+    resolve(workspaceRoot, ".agents/records"),
+    resolve(workspaceRoot, ".agents/config"),
+    resolve(workspaceRoot, "node_modules/esbuild"),
+  ]) {
+    if (!(await exists(required)))
+      throw new Error(
+        `Pré-requisito do Dashboard SQLite ausente: ${relative(workspaceRoot, required) || required}. Execute corepack pnpm install na raiz do ZAIP-AIOS e tente novamente.`,
+      );
+  }
+}
 export async function readDashboardSession(path = sessionPath) {
   try {
     return JSON.parse(await readFile(path, "utf8"));
@@ -110,11 +148,9 @@ export async function readDashboardSession(path = sessionPath) {
     return null;
   }
 }
-
 export async function writeDashboardSession(session, path = sessionPath) {
   await writeJsonAtomic(path, session);
 }
-
 async function writeJsonAtomic(path, value) {
   const directory = dirname(path);
   await mkdir(directory, { recursive: true });
@@ -125,7 +161,6 @@ async function writeJsonAtomic(path, value) {
   });
   await rename(temporaryPath, path);
 }
-
 export async function readPortRegistry(path = portRegistryPath) {
   try {
     const registry = JSON.parse(await readFile(path, "utf8"));
@@ -141,7 +176,6 @@ export async function readPortRegistry(path = portRegistryPath) {
     return [];
   }
 }
-
 export async function recordPortStatus(session, status, path = portRegistryPath) {
   const entries = await readPortRegistry(path);
   const now = new Date().toISOString();
@@ -152,6 +186,7 @@ export async function recordPortStatus(session, status, path = portRegistryPath)
     port: session.port,
     rootPid: session.rootPid,
     serverPid: session.serverPid ?? null,
+    dbPath: typeof session.dbPath === "string" ? session.dbPath : null,
     openedAt: session.createdAt ?? session.openedAt ?? now,
     status,
     closedAt: status === "active" ? null : now,
@@ -166,12 +201,10 @@ export async function recordPortStatus(session, status, path = portRegistryPath)
     ports: entries.slice(-maxPortHistory),
   });
 }
-
 export async function clearOwnedDashboardSession(rootPid = process.pid, path = sessionPath) {
   const session = await readDashboardSession(path);
   if (session?.rootPid === rootPid) await rm(path, { force: true });
 }
-
 export async function probeDashboardPort(
   port,
   fetchImpl = fetch,
@@ -189,13 +222,13 @@ export async function probeDashboardPort(
     return false;
   }
 }
-
 export async function findReusableDashboardSession({
   path = sessionPath,
   startPort = preferredPort(),
   fetchImpl = fetch,
   expectedWorkspaceKey = workspaceKey,
   expectedBuildSignature = null,
+  expectedSnapshotState = "current",
 } = {}) {
   const session = await readDashboardSession(path);
   if (
@@ -204,7 +237,8 @@ export async function findReusableDashboardSession({
     session?.workspaceKey !== expectedWorkspaceKey ||
     typeof session?.token !== "string" ||
     session.token.length === 0 ||
-    (expectedBuildSignature !== null && session?.buildSignature !== expectedBuildSignature)
+    (expectedBuildSignature !== null && session?.buildSignature !== expectedBuildSignature) ||
+    (expectedSnapshotState !== null && session?.snapshotState !== expectedSnapshotState)
   ) {
     return null;
   }
@@ -214,7 +248,6 @@ export async function findReusableDashboardSession({
   ) {
     return session;
   }
-
   const ports = Array.from({ length: maxPortAttempts }, (_, index) => startPort + index).filter(
     (port) => port <= 65_535 && port !== session.port,
   );
@@ -226,7 +259,6 @@ export async function findReusableDashboardSession({
   const port = matches.find((candidate) => candidate !== null);
   return port === undefined ? null : { ...session, port };
 }
-
 async function latestModifiedAt(paths) {
   let latest = 0;
   for (const path of paths) {
@@ -246,15 +278,14 @@ async function latestModifiedAt(paths) {
   }
   return latest;
 }
-
-async function runWorkspaceBuild(filter) {
-  const command = process.platform === "win32" ? (process.env.ComSpec ?? "cmd.exe") : "corepack";
-  const args =
-    process.platform === "win32"
-      ? ["/d", "/s", "/c", `corepack pnpm --filter ${filter} build`]
-      : ["pnpm", "--filter", filter, "build"];
+async function runSqliteBuild(target) {
+  const frontend = target === "frontend";
+  const command = process.execPath;
+  const args = frontend
+    ? [resolve(workspaceRoot, "node_modules/vite/bin/vite.js"), "build"]
+    : [resolve(workspaceRoot, ".agents/dashboard/packages/local-runtime/scripts/build-sqlite-runtime.mjs")];
   const output = await new Promise((resolveBuild, rejectBuild) => {
-    const child = spawn(command, args, { cwd: workspaceRoot, windowsHide: true, stdio: "pipe" });
+    const child = spawn(command, args, { cwd: frontend ? resolve(workspaceRoot, ".agents/dashboard/apps/frontend") : packageRoot, windowsHide: true, stdio: "pipe" });
     let outputText = "";
     const appendOutput = (chunk) => {
       outputText = `${outputText}${chunk}`.slice(-8_000);
@@ -268,13 +299,12 @@ async function runWorkspaceBuild(filter) {
       if (code === 0) resolveBuild();
       else
         rejectBuild(
-          new Error(`Build ${filter} failed (${code}): ${formatLauncherError(outputText)}`),
+          new Error(`SQLite dashboard ${target} build failed (${code}): ${formatLauncherError(outputText)}`),
         );
     });
   });
   return output;
 }
-
 async function ensureFreshDashboardBuild() {
   const artifacts = [resolve(frontendRoot, "index.html"), sourceServer];
   const [sourcesModifiedAt, artifactsModifiedAt] = await Promise.all([
@@ -283,8 +313,8 @@ async function ensureFreshDashboardBuild() {
   ]);
   const forceRebuild = process.env.ZAIP_DASHBOARD_FORCE_REBUILD === "1";
   if (forceRebuild || artifactsModifiedAt < sourcesModifiedAt) {
-    await runWorkspaceBuild("@zaip-ai/dashboard-frontend");
-    await runWorkspaceBuild("@zaip-ai/dashboard-local-runtime");
+    await runSqliteBuild("frontend");
+    await runSqliteBuild("runtime");
   }
   const artifactFingerprint = await Promise.all(
     [...artifacts, resolve(packageRoot, "start-dashboard.mjs")].map(async (path) => {
@@ -294,7 +324,6 @@ async function ensureFreshDashboardBuild() {
   );
   return createHash("sha256").update(artifactFingerprint.join("|")).digest("hex");
 }
-
 export async function withLauncherLock(
   action,
   {
@@ -333,7 +362,6 @@ export async function withLauncherLock(
   }
   throw new Error("Timed out waiting for the ZAIP dashboard launcher lock");
 }
-
 export async function findAvailablePort(startPort = preferredPort()) {
   for (let port = startPort; port < Math.min(startPort + maxPortAttempts, 65_536); port += 1) {
     if (await isPortFree(port)) return port;
@@ -342,7 +370,6 @@ export async function findAvailablePort(startPort = preferredPort()) {
     `No free dashboard port found between ${startPort} and ${Math.min(startPort + maxPortAttempts - 1, 65_535)}`,
   );
 }
-
 export async function findAvailablePortWithFallback({
   preferred = preferredPort(),
   excludedPorts = [],
@@ -364,7 +391,6 @@ export async function findAvailablePortWithFallback({
     "No free dashboard port was found in the preferred, fallback, or ephemeral ranges",
   );
 }
-
 async function findEphemeralPort() {
   return new Promise((resolvePort, rejectPort) => {
     const server = createServer();
@@ -380,7 +406,6 @@ async function findEphemeralPort() {
     });
   });
 }
-
 export function browserLaunchCommands(
   target,
   platform = process.platform,
@@ -401,7 +426,6 @@ export function browserLaunchCommands(
   }
   return [[platform === "darwin" ? "open" : "xdg-open", [target]]];
 }
-
 export async function openBrowser(target, spawnImpl = spawn) {
   if (process.env.ZAIP_UI_NO_BROWSER === "1") return true;
   const commands = browserLaunchCommands(target);
@@ -431,9 +455,14 @@ export async function openBrowser(target, spawnImpl = spawn) {
   appendLauncherLog(`Could not dispatch the dashboard URL to the default browser: ${target}`);
   return false;
 }
-
 export async function startDashboardLaunchPage(port) {
   let redirectUrl = null;
+  let progress = {
+    percent: 4,
+    phase: "Iniciando o launcher local",
+    detail: "Abrindo a página de preparação.",
+  };
+  const connections = new Set();
   let resolveRedirectObserved;
   const redirectObserved = new Promise((resolveObserved) => {
     resolveRedirectObserved = resolveObserved;
@@ -446,6 +475,11 @@ export async function startDashboardLaunchPage(port) {
       response.end(JSON.stringify({ target: redirectUrl }));
       return;
     }
+    if (request.url?.startsWith("/api/v2/progress")) {
+      response.writeHead(200, { "Content-Type": "application/json; charset=utf-8" });
+      response.end(JSON.stringify(progress));
+      return;
+    }
     if (request.url?.startsWith(healthPath)) {
       response.writeHead(503, { "Content-Type": "application/json; charset=utf-8" });
       response.end(JSON.stringify({ kind: "zaip-dashboard-launcher", status: "starting" }));
@@ -460,40 +494,43 @@ export async function startDashboardLaunchPage(port) {
   <title>Dashboard Zaip AIOS</title>
   <style>
     :root{color-scheme:dark;font-family:Inter,system-ui,sans-serif;background:#010610;color:#f1f5f9}
-    *{box-sizing:border-box}body{margin:0;min-height:100vh;background:radial-gradient(circle at 50% 0,rgba(0,176,240,.07),transparent 42%),#010610}
-    main{padding:clamp(18px,2.4vw,38px)}header{display:flex;align-items:center;justify-content:space-between;margin-bottom:24px}h1{font-size:clamp(1.45rem,2.4vw,2.25rem);margin:8px 0 0}
-    .eyebrow,.line,.value,.action,.chart,.pill{display:block;position:relative;overflow:hidden;border-radius:999px;background:#172033}.eyebrow{width:110px;height:10px}.actions{display:flex;gap:10px}.action{width:48px;height:42px;border-radius:12px}
-    .kpis,.panels,.board{display:grid;gap:14px}.kpis{grid-template-columns:repeat(4,minmax(0,1fr))}.kpis article,.panels article,.board article{border:1px solid rgba(255,255,255,.08);border-radius:16px;background:linear-gradient(145deg,rgba(17,24,39,.86),rgba(10,14,23,.92))}
-    .kpis article{min-height:138px;padding:18px}.line{width:86%;height:10px;margin-top:12px}.value{width:42%;height:30px;margin-top:18px}.panels{grid-template-columns:1.7fr 1fr;margin-top:14px}.panels article{padding:18px}.chart{height:156px;margin-top:22px;border-radius:12px;background:repeating-linear-gradient(to bottom,rgba(51,65,85,.3) 0,rgba(51,65,85,.3) 1px,transparent 1px,transparent 38px)}
-    .board{grid-template-columns:repeat(5,minmax(210px,1fr));margin-top:18px;overflow:hidden}.board article{min-height:220px;padding:14px}.board h2{min-height:34px;margin:0 0 12px;color:#cbd5e1;font-size:.82rem}.card{min-height:92px;border:1px solid rgba(255,255,255,.06);border-radius:12px;padding:10px;background:rgba(2,6,23,.56)}.pill{width:52px;height:15px;margin-top:14px}
-    .eyebrow:after,.line:after,.value:after,.action:after,.chart:after,.pill:after{content:"";position:absolute;inset:0;background:linear-gradient(90deg,transparent,rgba(125,211,252,.12),transparent);animation:shine 1.35s ease-in-out infinite;transform:translateX(-100%)}
-    @keyframes shine{to{transform:translateX(100%)}}@media(max-width:860px){.kpis{grid-template-columns:repeat(2,1fr)}.panels{grid-template-columns:1fr}.board{overflow-x:auto}}
+    *{box-sizing:border-box}body{margin:0;background:#010610}.launch-overlay{position:fixed;inset:0;width:100vw;height:100vh;display:grid;place-items:center;padding:clamp(18px,5vw,72px);background:radial-gradient(circle at 50% 35%,rgba(0,176,240,.11),transparent 42%),#010610}
+    .progress{width:min(100%,760px);padding:clamp(24px,4vw,42px);border:1px solid rgba(125,211,252,.2);border-radius:20px;background:rgba(3,9,22,.94);box-shadow:0 24px 80px rgba(0,0,0,.45);backdrop-filter:blur(10px)}.progress strong,.progress span{display:block}.progress strong{font-size:clamp(1.05rem,2vw,1.35rem)}.progress span{color:#b6c6db;font-size:clamp(.88rem,1.5vw,1rem);margin-top:7px}.track{height:9px;margin-top:20px;border-radius:999px;background:#172033;overflow:hidden}.bar{height:100%;width:4%;border-radius:inherit;background:linear-gradient(90deg,#38bdf8,#818cf8);transition:width .35s ease}.handoff{display:none;margin-top:16px;color:#dbeafe}.handoff a{color:#7dd3fc;font-weight:700}
   </style>
 </head>
 <body>
-  <main aria-label="Preparando dashboard">
-    <header><div><span class="eyebrow"></span><h1>Dashboard Zaip AIOS</h1></div><div class="actions"><span class="action"></span><span class="action"></span><span class="action"></span></div></header>
-    <section class="kpis">${Array.from({ length: 4 }, () => '<article><span class="line"></span><span class="value"></span><span class="line"></span></article>').join("")}</section>
-    <section class="panels"><article><span class="line"></span><div class="chart"></div></article><article><span class="line"></span><div class="chart"></div></article></section>
-    <section class="board">${["Definição", "Planejamento", "Pronto para Executar", "Execução", "Verificação"].map((label) => `<article><h2>${label}</h2><div class="card"><span class="line"></span><span class="line"></span><span class="pill"></span></div></article>`).join("")}</section>
+  <main class="launch-overlay" aria-label="Preparando dashboard">
+    <section class="progress" aria-live="polite" role="status"><strong id="phase">Iniciando o launcher local</strong><span id="detail">Abrindo a página de preparação.</span><div class="track"><div class="bar" id="bar"></div></div><span class="handoff" id="handoff">O dashboard está pronto. Se ele não abrir automaticamente, <a id="handoff-link" href="#">abra o dashboard agora</a>.</span></section>
   </main>
   <script>
+    let handoffTarget=null;
+    function showHandoff(target){handoffTarget=target;const box=document.getElementById("handoff");const link=document.getElementById("handoff-link");link.href=target;box.style.display="block";document.getElementById("phase").textContent="Dashboard pronto";document.getElementById("detail").textContent="Concluindo a abertura da tela principal."}
+    async function updateProgress(){try{const r=await fetch("/api/v2/progress",{cache:"no-store"});const p=await r.json();if(!handoffTarget){document.getElementById("phase").textContent=p.phase;document.getElementById("detail").textContent=p.detail};document.getElementById("bar").style.width=Math.max(4,Math.min(100,Number(p.percent)||4))+"%"}catch{}}
     async function waitForDashboard(){
       try{
+        await updateProgress();
         const ready=await fetch("/api/v2/ready",{cache:"no-store"});
         const next=await ready.json();
-        if(next.target){location.replace(next.target);return}
+        if(next.target){showHandoff(next.target);setTimeout(()=>location.replace(next.target),0);return}
         const response=await fetch("${healthPath}",{cache:"no-store"});
         const payload=await response.json();
         if(response.ok&&payload.kind==="${runtimeKind}"){location.reload();return}
       }catch{}
       setTimeout(waitForDashboard,250)
     }
-    setTimeout(waitForDashboard,100)
+    updateProgress();setTimeout(waitForDashboard,100)
+    // A browser extension or a failed navigation must never leave a silent
+    // skeleton.  The visible link remains actionable while the temporary
+    // launcher server keeps serving this page through the handoff grace.
+    setTimeout(()=>{if(handoffTarget)showHandoff(handoffTarget)},4000)
   </script>
 </body>
 </html>`);
   });
+  server.on("connection", (connection) => {
+    connections.add(connection);
+    connection.once("close", () => connections.delete(connection));
+  });
   await new Promise((resolveListen, rejectListen) => {
     server.once("error", rejectListen);
     server.listen({ host, port }, resolveListen);
@@ -506,25 +543,52 @@ export async function startDashboardLaunchPage(port) {
     redirect: (target) => {
       redirectUrl = target;
     },
+    setProgress: (next) => {
+      progress = { ...progress, ...next, percent: Math.max(progress.percent, next.percent ?? progress.percent) };
+    },
     waitForRedirect: async (timeoutMs = 1_500) =>
       Promise.race([redirectObserved, delay(timeoutMs).then(() => false)]),
-    close: () =>
+    closeAfterHandoffGrace: (graceMs = 12_000) => {
+      const timer = setTimeout(() => {
+        void server.close();
+        server.closeAllConnections?.();
+        for (const connection of connections) connection.destroy();
+      }, graceMs);
+      timer.unref?.();
+    },
+    close: ({ forceAfterMs = 750 } = {}) =>
       new Promise((resolveClose, rejectClose) => {
-        server.close((error) => (error ? rejectClose(error) : resolveClose()));
+        let forceTimer = null;
+        const finish = (error) => {
+          if (forceTimer !== null) clearTimeout(forceTimer);
+          if (error) rejectClose(error);
+          else resolveClose();
+        };
+        server.close(finish);
+        // The preparation page polls while redirecting. A browser keep-alive
+        // or an interrupted polling request must not keep this transient
+        // server alive indefinitely after its handoff was issued.
+        forceTimer = setTimeout(() => {
+          server.closeAllConnections?.();
+          for (const connection of connections) connection.destroy();
+        }, forceAfterMs);
+        forceTimer.unref?.();
       }),
   };
 }
-
 async function redirectLaunchPage(launchPage, target) {
   launchPage.redirect(target);
   const redirected =
     process.env.ZAIP_UI_NO_BROWSER === "1" ? true : await launchPage.waitForRedirect();
-  await launchPage.close();
   if (!redirected && !(await openBrowser(target))) {
     throw new Error("Could not open the dashboard after the preparation page did not redirect.");
   }
+  // Do not tear down the preparation page merely because its ready poll was
+  // observed: that happens before location.replace and used to strand users
+  // on the skeleton when navigation was blocked.  Its watchdog/link remains
+  // available for a bounded grace period.
+  launchPage.closeAfterHandoffGrace();
 }
-
 async function assertRuntimeReady() {
   const serverPath = (await exists(sourceServer)) ? sourceServer : installedServer;
   if (!(await exists(serverPath))) {
@@ -539,53 +603,32 @@ async function assertRuntimeReady() {
   }
   return serverPath;
 }
-
 async function stopOwnedDashboard(session) {
-  if (!(await probeDashboardPort(session?.port, fetch, workspaceKey, false))) return true;
-  if (!Number.isInteger(session?.rootPid) || session.rootPid <= 0) return false;
-  await stopProcessTree(session.rootPid);
-  const deadline = Date.now() + 5_000;
-  while (Date.now() < deadline) {
-    if (!(await probeDashboardPort(session.port))) return true;
-    await delay(100);
-  }
-  return false;
-}
-
-async function stopProcessTree(pid) {
-  if (!Number.isInteger(pid) || pid <= 0 || pid === process.pid) return;
-  if (process.platform === "win32") {
-    await new Promise((resolveStop) => {
-      const killer = spawn("taskkill", ["/pid", String(pid), "/t", "/f"], {
-        stdio: "ignore",
-        windowsHide: true,
-      });
-      killer.once("error", () => resolveStop());
-      killer.once("exit", () => resolveStop());
-    });
-    return;
-  }
-  try {
-    process.kill(pid, "SIGTERM");
-  } catch {
-    // A stale recorded PID is already stopped.
-  }
+  return stopOwnedDashboardProcess(session, {
+    probeDashboardPort,
+    workspaceKey,
+    fetchImpl: fetch,
+    host,
+    packageRoot,
+    delay,
+  });
 }
-
-async function previousDashboardSessions() {
-  const session = await readDashboardSession();
-  const registryEntries = (await readPortRegistry()).filter((entry) => entry.status === "active");
-  const candidates = [session, ...registryEntries].filter(Boolean);
-  return candidates.filter(
-    (candidate, index) =>
-      Number.isInteger(candidate.port) &&
-      candidates.findIndex(
-        (entry) => entry.port === candidate.port && entry.rootPid === candidate.rootPid,
-      ) === index,
-  );
+export async function previousDashboardSessions({
+  sessionPath: candidateSessionPath = sessionPath,
+  registryPath: candidateRegistryPath = portRegistryPath,
+  probe = (port) => probeDashboardPort(port, fetch, workspaceKey, false),
+} = {}) {
+  return collectPreviousDashboardSessions({
+    candidateSessionPath,
+    candidateRegistryPath,
+    probe,
+    readDashboardSession,
+    readPortRegistry,
+    workspaceRoot,
+    workspaceKey,
+  });
 }
-
-async function startDashboardServer(serverPath, token, excludedPorts, initialPort = null) {
+async function startDashboardServer(serverPath, token, excludedPorts, initialPort = null, onProgress = () => {}) {
   const failures = [];
   for (let attempt = 1; attempt <= maxServerStartAttempts; attempt += 1) {
     const port =
@@ -593,7 +636,13 @@ async function startDashboardServer(serverPath, token, excludedPorts, initialPor
         ? initialPort
         : await findAvailablePortWithFallback({ excludedPorts: [...excludedPorts] });
     excludedPorts.add(port);
+    const dbPath = resolve(
+      sqliteReadModelDirectory,
+      `read-model-${port}-${process.pid}-${attempt}.sqlite`,
+    );
     let stderr = "";
+    let startupTelemetryBuffer = "";
+    let snapshotCache = null;
     const child = spawn(process.execPath, [serverPath], {
       cwd: packageRoot,
       env: {
@@ -602,6 +651,15 @@ async function startDashboardServer(serverPath, token, excludedPorts, initialPor
         ZAIP_UI_ROOT: frontendRoot,
         ZAIP_UI_TOKEN: token,
         ZAIP_SERVER_PORT: String(port),
+        NODE_COMPILE_CACHE: nodeCompileCacheDirectory,
+        NODE_NO_WARNINGS: "1",
+        ZAIP_DASHBOARD_LAUNCH_PROGRESS: "1",
+        ZAIP_SQLITE_PREFER_LAST_VALID_SEED: "1",
+        ZAIP_SQLITE_CACHE_DIR: sqliteSnapshotCacheDirectory,
+        // A retry or a fresh-port handoff never reuses a live SQLite file.
+        // Windows keeps an open read-only handle locked, so each child owns a
+        // generation identified by launcher PID, attempt and selected port.
+        ZAIP_SQLITE_DB_PATH: dbPath,
       },
       stdio: ["ignore", "ignore", "pipe"],
       windowsHide: true,
@@ -609,14 +667,50 @@ async function startDashboardServer(serverPath, token, excludedPorts, initialPor
     child.stderr?.setEncoding("utf8");
     child.stderr?.on("data", (chunk) => {
       stderr = `${stderr}${chunk}`.slice(-4_000);
+      startupTelemetryBuffer = `${startupTelemetryBuffer}${String(chunk)}`;
+      const lines = startupTelemetryBuffer.split("\n");
+      startupTelemetryBuffer = lines.pop() ?? "";
+      for (const line of lines) {
+        try {
+          const event = JSON.parse(line);
+          if (event?.event === "dashboard_sqlite_rebuild_progress")
+            onProgress({
+              percent: event.percent,
+              phase: "Configurando o banco SQLite local",
+              detail: "Esta é a instalação/atualização da cópia local descartável; nenhum servidor externo é instalado.",
+            });
+          if (event?.event === "dashboard_sqlite_startup_phase" && event.phase === "main_entered")
+            onProgress({ percent: 50, phase: "Lendo os registros do projeto", detail: "Preparando o read model SQLite local." });
+          if (event?.event === "dashboard_sqlite_read_model") snapshotCache = event.cache;
+          if (event?.event === "dashboard_sqlite_read_model")
+            onProgress({ percent: 82, phase: "Banco local pronto", detail: event.cache === "rebuilt" ? "O read model SQLite foi reconstruído para os dados atuais." : "Uma cópia local do read model foi preparada." });
+          if (event?.event === "dashboard_sqlite_startup_phase" && event.phase === "listening")
+            onProgress({ percent: 88, phase: "Iniciando a interface", detail: "Verificando saúde e disponibilidade dos dados." });
+        } catch {
+          // Only structured startup telemetry affects the user-facing progress.
+        }
+      }
     });
     try {
       await waitForDashboard(port, child);
-      return { child, port };
+      const timings = stripTerminalControlCodes(stderr)
+        .split("\n")
+        .filter(
+          (line) =>
+            line.includes('"event":"dashboard_sqlite_read_model"') ||
+            line.includes('"event":"dashboard_sqlite_startup_phase"'),
+        );
+      for (const timing of timings) appendLauncherLog(timing);
+      return { child, port, dbPath, snapshotCache };
     } catch (error) {
       await stopProcessTree(child.pid);
-      const detail = stderr.trim();
-      failures.push(`porta ${port}: ${error.message}${detail ? ` — ${detail}` : ""}`);
+      await removeGeneratedReadModel(dbPath);
+      const detail = stripTerminalControlCodes(stderr)
+        .split("\n")
+        .filter((line) => !line.includes("ExperimentalWarning") && !line.includes("node --trace-warnings"))
+        .join("\n")
+        .trim();
+      failures.push(`porta ${port}: ${error.message}${detail ? ` — ${formatLauncherError(detail, 600)}` : ""}`);
       appendLauncherLog(
         `Dashboard start attempt ${attempt} failed on port ${port}: ${error.message}`,
       );
@@ -628,6 +722,82 @@ async function startDashboardServer(serverPath, token, excludedPorts, initialPor
   );
 }
 
+async function removeGeneratedReadModel(candidate) {
+  if (typeof candidate !== "string") return false;
+  const resolvedCandidate = resolve(candidate);
+  const fromReadModelDirectory = relative(sqliteReadModelDirectory, resolvedCandidate);
+  const generatedName = /^read-model-\d+-\d+-\d+\.sqlite$/;
+  if (
+    fromReadModelDirectory === "" ||
+    fromReadModelDirectory.startsWith("..") ||
+    fromReadModelDirectory.includes("/") ||
+    fromReadModelDirectory.includes("\\") ||
+    !generatedName.test(fromReadModelDirectory)
+  )
+    return false;
+  for (let attempt = 1; attempt <= 20; attempt += 1) {
+    try {
+      await rm(resolvedCandidate, { force: true });
+      return true;
+    } catch (error) {
+      if (error?.code !== "EBUSY" && error?.code !== "EPERM") throw error;
+      if (attempt < 20) await delay(250);
+    }
+  }
+  appendLauncherLog(`Could not remove closed SQLite read model after retries: ${resolvedCandidate}`);
+  return false;
+}
+function refreshSnapshotSeedInBackground() {
+  const refreshPath = resolve(sqliteReadModelDirectory, `refresh-${process.pid}-${randomBytes(4).toString("hex")}.sqlite`);
+  const refreshStatusPath = join(sessionDirectory, "dashboard-sqlite-refresh.json");
+  const refreshLogPath = join(sessionDirectory, "dashboard-sqlite-refresh.log");
+  mkdirSync(sessionDirectory, { recursive: true });
+  const refreshLogDescriptor = openSync(refreshLogPath, "a");
+  let worker;
+  try {
+    worker = spawn(process.execPath, [resolve(packageRoot, "scripts/rebuild-sqlite-read-model.mjs")], {
+      cwd: workspaceRoot,
+      env: {
+        ...process.env,
+        ZAIP_SQLITE_DB_PATH: refreshPath,
+        ZAIP_SQLITE_PREFER_LAST_VALID_SEED: "0",
+        ZAIP_DASHBOARD_LAUNCH_PROGRESS: "0",
+        ZAIP_SQLITE_REFRESH_CLEANUP: "1",
+        ZAIP_SQLITE_CACHE_DIR: sqliteSnapshotCacheDirectory,
+      },
+      // A detached worker keeps its own append-only evidence file.  Pipes can
+      // disappear with a fast launcher exit and silently abort the refresh.
+      stdio: ["ignore", refreshLogDescriptor, refreshLogDescriptor],
+      detached: true,
+      windowsHide: true,
+    });
+  } finally {
+    closeSync(refreshLogDescriptor);
+  }
+  void writeJsonAtomic(refreshStatusPath, {
+    status: "running",
+    pid: worker.pid ?? null,
+    path: refreshPath,
+    cacheDirectory: sqliteSnapshotCacheDirectory,
+    startedAt: new Date().toISOString(),
+  }).catch(() => {});
+  worker.once("error", (error) => {
+    appendLauncherLog(`Background SQLite seed refresh failed to start: ${error.message}`);
+    void writeJsonAtomic(refreshStatusPath, { status: "failed", error: error.message, finishedAt: new Date().toISOString() }).catch(() => {});
+  });
+  worker.once("exit", (code) => {
+    const status = code === 0 ? "completed" : "failed";
+    appendLauncherLog(`Background SQLite seed refresh ${status} (${code ?? "unknown"}); inspect ${refreshLogPath}.`);
+    void writeJsonAtomic(refreshStatusPath, {
+      status,
+      exitCode: code ?? null,
+      logPath: refreshLogPath,
+      finishedAt: new Date().toISOString(),
+    }).catch(() => {});
+  });
+  worker.unref();
+  appendLauncherLog(`Started background SQLite seed refresh at ${refreshPath}; cache ${sqliteSnapshotCacheDirectory}; worker log ${refreshLogPath}.`);
+}
 async function writeLauncherStatus(status, message = "") {
   const path = process.env.ZAIP_LAUNCH_STATUS;
   if (!path) return;
@@ -635,74 +805,142 @@ async function writeLauncherStatus(status, message = "") {
   await writeFile(temporaryPath, `${status}\n${message}`.trimEnd(), "utf8");
   await rename(temporaryPath, path);
 }
-
+function phaseTiming(phase, startedAt, details = {}) {
+  appendLauncherLog(JSON.stringify({ event: "dashboard_sqlite_phase", phase, elapsed_ms: Date.now() - startedAt, launcher_pid: process.pid, ...details }));
+}
 async function main() {
   let ownedChild = null;
   let currentSession = null;
   let launchPage = null;
   const token = process.env.ZAIP_UI_TOKEN ?? randomBytes(24).toString("base64url");
-  // Keep the session observed before waiting.  If a different healthy session
-  // exists once this process owns the lock, it was produced by a concurrent
-  // launch and is already handed off to the browser.  Do not open a second
-  // preparation page or replace that healthy launch.
-  const observedSession = await readDashboardSession();
-  const observedRootPid = observedSession?.rootPid ?? null;
-
-  await withLauncherLock(async () => {
-    const concurrentSession = await findReusableDashboardSession();
-    if (concurrentSession !== null && concurrentSession.rootPid !== observedRootPid) {
-      appendLauncherLog(
-        `Coalesced dashboard launcher request with healthy concurrent session on port ${concurrentSession.port}.`,
-      );
-      await writeLauncherStatus("ok");
-      return;
-    }
-
-    const launchPort = await findAvailablePortWithFallback();
-    launchPage = await startDashboardLaunchPage(launchPort);
+  const launchStartedAt = Date.now();
+  // Bind the preparation page atomically on an ephemeral port before waiting
+  // for the launch lock.  Looking up a free port and binding it later lets a
+  // concurrent preparation page claim that port, which makes the runtime
+  // probe mistake its intentional 503 for a server failure.
+  launchPage = await startDashboardLaunchPage(0);
+  const launchPort = launchPage.port;
+  try {
     if (!(await openBrowser(dashboardUrl(launchPort, token)))) {
-      await launchPage.close();
-      launchPage = null;
       throw new Error("Could not open the dashboard preparation page in the default browser.");
     }
-
-    const buildSignature = await ensureFreshDashboardBuild();
-    const previousSessions = await previousDashboardSessions();
-    const excludedPorts = new Set([...previousSessions.map((session) => session.port), launchPort]);
-    const serverPath = await assertRuntimeReady();
-    const { child, port } = await startDashboardServer(serverPath, token, excludedPorts);
-    ownedChild = child;
-    try {
-      await redirectLaunchPage(launchPage, dashboardUrl(port, token));
-      launchPage = null;
-      currentSession = {
-        kind: runtimeKind,
-        workspace: workspaceRoot,
-        workspaceKey,
-        rootPid: process.pid,
-        serverPid: child.pid,
-        port,
+    launchPage.setProgress({
+      percent: 10,
+      phase: "Validando pré-requisitos locais",
+      detail: "Verificando Node.js 22 e o suporte a node:sqlite; isto não instala um banco de dados.",
+    });
+    await assertDashboardPrerequisites();
+    launchPage.setProgress({
+      percent: 18,
+      phase: "Preparando a sessão do dashboard",
+      detail: "Coordenando esta abertura local com segurança.",
+    });
+    await withLauncherLock(async () => {
+      phaseTiming("lock_acquired", launchStartedAt);
+      const buildStartedAt = Date.now();
+      launchPage.setProgress({
+        percent: 28,
+        phase: "Verificando os artefatos do dashboard",
+        detail: "Usando o build existente quando ele já está atualizado.",
+      });
+      const buildSignature = await ensureFreshDashboardBuild();
+      phaseTiming("build_complete", buildStartedAt, { build_signature: buildSignature });
+      // A second deliberate click must use the already healthy compatible
+      // runtime.  Build signature makes this safe across dashboard updates;
+      // an incompatible session continues through a replacement handoff.
+      const reusable = await findReusableDashboardSession({
+        expectedBuildSignature: buildSignature,
+        expectedSnapshotState: "current",
+      });
+      if (reusable !== null) {
+        appendLauncherLog(`Reused healthy compatible dashboard session on port ${reusable.port}, PID ${reusable.serverPid ?? "unknown"}.`);
+        await redirectLaunchPage(launchPage, dashboardUrl(reusable.port, reusable.token));
+        launchPage = null;
+        await writeLauncherStatus("ok");
+        return;
+      }
+      const previousSessions = await previousDashboardSessions();
+      const excludedPorts = new Set([
+        ...previousSessions.map((session) => session.port),
+        launchPort,
+      ]);
+      const serverPath = await assertRuntimeReady();
+      const readyStartedAt = Date.now();
+      launchPage.setProgress({
+        percent: 42,
+        phase: "Abrindo o banco local descartável",
+        detail: "Criando uma cópia privada do read model SQLite para esta sessão.",
+      });
+      const { child, port, dbPath, snapshotCache } = await startDashboardServer(
+        serverPath,
         token,
-        buildSignature,
-        createdAt: new Date().toISOString(),
-      };
-      await writeDashboardSession(currentSession);
-      await recordPortStatus(currentSession, "active");
-      const warnings = [];
-      for (const previous of previousSessions) {
-        const stopped = await stopOwnedDashboard(previous);
-        await recordPortStatus(previous, stopped ? "closed" : "close_failed");
-        if (!stopped) warnings.push(`não foi possível fechar a porta anterior ${previous.port}`);
+        excludedPorts,
+        null,
+        (progress) => launchPage?.setProgress(progress),
+      );
+      phaseTiming("server_ready", readyStartedAt, { server_pid: child.pid, port, db_path: dbPath });
+      ownedChild = child;
+      try {
+        launchPage.setProgress({
+          percent: 92,
+          phase: snapshotCache === "stale_seed" ? "Abrindo snapshot local validado" : "Dashboard pronto",
+          detail: snapshotCache === "stale_seed"
+            ? "Os dados canônicos estão sendo atualizados em segundo plano para a próxima abertura."
+            : "Validando saúde e dados iniciais antes de abrir a tela principal.",
+        });
+        if (snapshotCache === "stale_seed") await delay(350);
+        await redirectLaunchPage(launchPage, dashboardUrl(port, token, snapshotCache === "stale_seed"));
+        phaseTiming("handoff_complete", launchStartedAt, { server_pid: child.pid, port });
+        launchPage = null;
+        if (snapshotCache === "stale_seed")
+          refreshSnapshotSeedInBackground();
+        currentSession = {
+          kind: runtimeKind,
+          workspace: workspaceRoot,
+          workspaceKey,
+          rootPid: process.pid,
+          serverPid: child.pid,
+          port,
+          token,
+          dbPath,
+          buildSignature,
+          generationId: `${process.pid}-${child.pid}-${port}-${randomBytes(6).toString("hex")}`,
+          // Never pin subsequent clicks to a stale seed.  A completed
+          // background refresh is consumed by a fresh handoff on the next
+          // click, then the old updating generation is retired below.
+          snapshotState: snapshotCache === "stale_seed" ? "updating" : "current",
+          createdAt: new Date().toISOString(),
+        };
+        await writeDashboardSession(currentSession);
+        await recordPortStatus(currentSession, "active");
+        const warnings = [];
+        for (const previous of previousSessions) {
+          const status = await stopOwnedDashboard(previous);
+          await recordPortStatus(previous, status);
+          if (status === "closed") await removeGeneratedReadModel(previous.dbPath);
+          if (teardownWarning(status))
+            warnings.push(`não foi possível fechar a porta anterior ${previous.port}`);
+          else if (status === "skipped_unowned")
+            appendLauncherLog(
+              `Skipped teardown of port ${previous.port}: registered server PID does not own its live listener.`,
+            );
+        }
+        if (warnings.length > 0)
+          appendLauncherLog(
+            `Dashboard launched on port ${port}; prior-port cleanup: ${warnings.join("; ")}`,
+          );
+        await writeLauncherStatus("ok");
+      } catch (error) {
+        await stopProcessTree(child.pid);
+        if (currentSession !== null) await recordPortStatus(currentSession, "failed");
+        await clearOwnedDashboardSession();
+        throw error;
       }
-      await writeLauncherStatus(warnings.length > 0 ? "warning" : "ok", warnings.join("; "));
-    } catch (error) {
-      await stopProcessTree(child.pid);
-      if (currentSession !== null) await recordPortStatus(currentSession, "failed");
-      await clearOwnedDashboardSession();
-      throw error;
-    }
-  });
-
+    });
+  } catch (error) {
+    if (launchPage !== null) await launchPage.close().catch(() => {});
+    throw error;
+  }
   if (ownedChild === null) return;
   for (const signal of ["SIGINT", "SIGTERM"]) {
     process.once(signal, () => ownedChild?.kill(signal));
@@ -712,10 +950,12 @@ async function main() {
     ownedChild.once("exit", (code) => resolveExit(code ?? 0));
   });
   await clearOwnedDashboardSession();
-  if (currentSession !== null) await recordPortStatus(currentSession, "closed");
+  if (currentSession !== null) {
+    await recordPortStatus(currentSession, "closed");
+    await removeGeneratedReadModel(currentSession.dbPath);
+  }
   process.exitCode = exitCode;
 }
-
 function isPortFree(port) {
   return new Promise((resolvePort) => {
     const server = createServer();
@@ -724,7 +964,6 @@ function isPortFree(port) {
     server.listen({ host, port }, () => server.close(() => resolvePort(true)));
   });
 }
-
 async function waitForDashboard(port, child) {
   const deadline = Date.now() + startupTimeoutMs;
   while (Date.now() < deadline) {
@@ -735,7 +974,19 @@ async function waitForDashboard(port, child) {
       const response = await fetch(dashboardHealthUrl(port), { signal: AbortSignal.timeout(750) });
       const payload = await response.json().catch(() => null);
       if (response.ok && payload?.kind === runtimeKind && payload?.workspaceKey === workspaceKey) {
-        return;
+        const readiness = await fetch(`http://${host}:${port}/api/v2/ready`, {
+          signal: AbortSignal.timeout(750),
+          cache: "no-store",
+        });
+        if (readiness.ok) return;
+        if (readiness.status >= 500) {
+          const detail = await readiness.json().catch(() => null);
+          const unavailable = new Error(
+            `Dashboard data readiness returned ${readiness.status}: ${detail?.error ?? "projection unavailable"}`,
+          );
+          unavailable.retryable = false;
+          throw unavailable;
+        }
       }
       if (response.status >= 500) {
         const unavailable = new Error(
@@ -747,26 +998,22 @@ async function waitForDashboard(port, child) {
     } catch (error) {
       if (error?.retryable === false) throw error;
     }
-    await delay(250);
+    await delay(100);
   }
   throw new Error(`Timed out waiting for ${dashboardHealthUrl(port)}`);
 }
-
 function exists(path) {
   return access(path).then(
     () => true,
     () => false,
   );
 }
-
 function delay(milliseconds) {
   return new Promise((resolveDelay) => setTimeout(resolveDelay, milliseconds));
 }
-
 const isMain = process.argv[1]
   ? resolve(process.argv[1]) === fileURLToPath(import.meta.url)
   : false;
-
 if (isMain) {
   main().catch(async (error) => {
     const logMessage = error instanceof Error ? (error.stack ?? error.message) : String(error);