@zaip-ai/cli 1.0.8 → 1.3.1

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, closeSync, mkdirSync, openSync } from "node:fs";
+import { appendFileSync, mkdirSync } from "node:fs";
 import {
   access,
   mkdir,
@@ -12,18 +12,20 @@ import {
   utimes,
   writeFile,
 } from "node:fs/promises";
-import { createServer as createHttpServer } from "node:http";
 import { createServer } from "node:net";
 import { tmpdir } from "node:os";
 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 { createDashboardLaunchPage } from "./start-dashboard-launch-page.mjs";
 import {
+  isProcessAlive,
   stopOwnedDashboardProcess,
   stopProcessTree,
   teardownWarning,
 } from "./start-dashboard-processes.mjs";
+import { refreshIsRunning, startSeedRefresh } from "./start-dashboard-refresh.mjs";
 
 export {
   isAncestorProcess,
@@ -38,7 +40,10 @@ export const maxPortAttempts = 25;
 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}:dashboard-sqlite`).digest("hex").slice(0, 16);
+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");
@@ -46,20 +51,15 @@ 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.
+// Keep the immutable seed cache durable and independent of temporary SQLite generations.
 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.
+// Node's bytecode cache is disposable acceleration beside private SQLite generations.
 const nodeCompileCacheDirectory = join(sqliteReadModelDirectory, "node-compile-cache");
 const installedServer = resolve(packageRoot, "server.mjs");
 const sourceServer = resolve(packageRoot, "dist/server.cjs");
 const healthPath = "/api/v2/health";
-// 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 lockTimeoutMs = 210_000;
 const staleLockMs = 30_000;
 const lockHeartbeatFloorMs = 10;
 // A cold immutable seed can legitimately take ~176 s on a busy Windows
@@ -259,6 +259,10 @@ export async function findReusableDashboardSession({
   const port = matches.find((candidate) => candidate !== null);
   return port === undefined ? null : { ...session, port };
 }
+
+async function backgroundRefreshIsRunning() {
+  return refreshIsRunning(join(sessionDirectory, "dashboard-sqlite-refresh.json"), isProcessAlive);
+}
 async function latestModifiedAt(paths) {
   let latest = 0;
   for (const path of paths) {
@@ -283,9 +287,18 @@ async function runSqliteBuild(target) {
   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")];
+    : [
+        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: frontend ? resolve(workspaceRoot, ".agents/dashboard/apps/frontend") : packageRoot, 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);
@@ -299,7 +312,9 @@ async function runSqliteBuild(target) {
       if (code === 0) resolveBuild();
       else
         rejectBuild(
-          new Error(`SQLite dashboard ${target} build failed (${code}): ${formatLauncherError(outputText)}`),
+          new Error(
+            `SQLite dashboard ${target} build failed (${code}): ${formatLauncherError(outputText)}`,
+          ),
         );
     });
   });
@@ -331,6 +346,7 @@ export async function withLauncherLock(
     path = lockPath,
     timeoutMs = lockTimeoutMs,
     staleAfterMs = staleLockMs,
+    onWait = () => {},
   } = {},
 ) {
   await mkdir(directory, { recursive: true });
@@ -357,6 +373,7 @@ export async function withLauncherLock(
         await rm(path, { recursive: true, force: true });
         continue;
       }
+      onWait();
       await delay(100);
     }
   }
@@ -424,7 +441,12 @@ export function browserLaunchCommands(
       ],
     ];
   }
-  return [[platform === "darwin" ? "open" : "xdg-open", [target]]];
+  return platform === "darwin"
+    ? [["open", [target]]]
+    : [
+        ["xdg-open", [target]],
+        ["gio", ["open", target]],
+      ];
 }
 export async function openBrowser(target, spawnImpl = spawn) {
   if (process.env.ZAIP_UI_NO_BROWSER === "1") return true;
@@ -455,126 +477,8 @@ 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;
-  });
-  const server = createHttpServer((request, response) => {
-    response.setHeader("Cache-Control", "no-store");
-    if (request.url?.startsWith("/api/v2/ready")) {
-      if (redirectUrl !== null) resolveRedirectObserved(true);
-      response.writeHead(200, { "Content-Type": "application/json; charset=utf-8" });
-      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" }));
-      return;
-    }
-    response.writeHead(200, { "Content-Type": "text/html; charset=utf-8" });
-    response.end(`<!doctype html>
-<html lang="pt-BR">
-<head>
-  <meta charset="utf-8">
-  <meta name="viewport" content="width=device-width,initial-scale=1">
-  <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;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 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){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)
-    }
-    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);
-  });
-  server.unref();
-  const address = server.address();
-  const listeningPort = typeof address === "object" && address !== null ? address.port : port;
-  return {
-    port: listeningPort,
-    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)]),
-    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) => {
-        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?.();
-      }),
-  };
+export function startDashboardLaunchPage(port) {
+  return createDashboardLaunchPage({ port, host, runtimeKind, healthPath, delay });
 }
 async function redirectLaunchPage(launchPage, target) {
   launchPage.redirect(target);
@@ -628,7 +532,13 @@ export async function previousDashboardSessions({
     workspaceKey,
   });
 }
-async function startDashboardServer(serverPath, token, excludedPorts, initialPort = null, onProgress = () => {}) {
+async function startDashboardServer(
+  serverPath,
+  token,
+  excludedPorts,
+  initialPort = null,
+  onProgress = () => {},
+) {
   const failures = [];
   for (let attempt = 1; attempt <= maxServerStartAttempts; attempt += 1) {
     const port =
@@ -677,15 +587,31 @@ async function startDashboardServer(serverPath, token, excludedPorts, initialPor
             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.",
+              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." });
+            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." });
+            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." });
+            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.
         }
@@ -707,10 +633,15 @@ async function startDashboardServer(serverPath, token, excludedPorts, initialPor
       await removeGeneratedReadModel(dbPath);
       const detail = stripTerminalControlCodes(stderr)
         .split("\n")
-        .filter((line) => !line.includes("ExperimentalWarning") && !line.includes("node --trace-warnings"))
+        .filter(
+          (line) =>
+            !line.includes("ExperimentalWarning") && !line.includes("node --trace-warnings"),
+        )
         .join("\n")
         .trim();
-      failures.push(`porta ${port}: ${error.message}${detail ? ` — ${formatLauncherError(detail, 600)}` : ""}`);
+      failures.push(
+        `porta ${port}: ${error.message}${detail ? ` — ${formatLauncherError(detail, 600)}` : ""}`,
+      );
       appendLauncherLog(
         `Dashboard start attempt ${attempt} failed on port ${port}: ${error.message}`,
       );
@@ -744,59 +675,29 @@ async function removeGeneratedReadModel(candidate) {
       if (attempt < 20) await delay(250);
     }
   }
-  appendLauncherLog(`Could not remove closed SQLite read model after retries: ${resolvedCandidate}`);
+  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`);
+async function refreshSnapshotSeedInBackground() {
   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,
+  return startSeedRefresh({
+    appendLog: appendLauncherLog,
     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(() => {});
+    isRunning: backgroundRefreshIsRunning,
+    isProcessAlive,
+    lockPath: join(sessionDirectory, "dashboard-sqlite-refresh.lock"),
+    packageRoot,
+    randomBytes,
+    refreshLogPath,
+    refreshStatusPath,
+    sqliteDirectory: sqliteReadModelDirectory,
+    stopProcessTree,
+    workspaceRoot,
+    writeJsonAtomic,
   });
-  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;
@@ -806,7 +707,15 @@ async function writeLauncherStatus(status, message = "") {
   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 }));
+  appendLauncherLog(
+    JSON.stringify({
+      event: "dashboard_sqlite_phase",
+      phase,
+      elapsed_ms: Date.now() - startedAt,
+      launcher_pid: process.pid,
+      ...details,
+    }),
+  );
 }
 async function main() {
   let ownedChild = null;
@@ -827,7 +736,8 @@ async function main() {
     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.",
+      detail:
+        "Verificando Node.js 22 e o suporte a node:sqlite; isto não instala um banco de dados.",
     });
     await assertDashboardPrerequisites();
     launchPage.setProgress({
@@ -835,110 +745,162 @@ async function main() {
       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,
-        excludedPorts,
-        null,
-        (progress) => launchPage?.setProgress(progress),
-      );
-      phaseTiming("server_ready", readyStartedAt, { server_pid: child.pid, port, db_path: dbPath });
-      ownedChild = child;
-      try {
+    let reportedLockWait = false;
+    await withLauncherLock(
+      async () => {
+        phaseTiming("lock_acquired", launchStartedAt);
+        const buildStartedAt = Date.now();
         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.",
+          percent: 28,
+          phase: "Verificando os artefatos do dashboard",
+          detail: "Usando o build existente quando ele já está atualizado.",
         });
-        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")
+        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;
+        }
+        // A stale seed is still a valid read-only dashboard while its one
+        // canonical refresh runs. Reuse it instead of turning repeated clicks
+        // into competing full SQLite rebuilds and private server generations.
+        if (await backgroundRefreshIsRunning()) {
+          const updating = await findReusableDashboardSession({
+            expectedBuildSignature: buildSignature,
+            expectedSnapshotState: "updating",
+          });
+          if (updating !== null) {
             appendLauncherLog(
-              `Skipped teardown of port ${previous.port}: registered server PID does not own its live listener.`,
+              `Reused updating dashboard session on port ${updating.port}; canonical seed refresh is already running.`,
             );
+            await redirectLaunchPage(launchPage, dashboardUrl(updating.port, updating.token, true));
+            launchPage = null;
+            await writeLauncherStatus("ok");
+            return;
+          }
         }
-        if (warnings.length > 0)
-          appendLauncherLog(
-            `Dashboard launched on port ${port}; prior-port cleanup: ${warnings.join("; ")}`,
+        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,
+          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"),
           );
-        await writeLauncherStatus("ok");
-      } catch (error) {
-        await stopProcessTree(child.pid);
-        if (currentSession !== null) await recordPortStatus(currentSession, "failed");
-        await clearOwnedDashboardSession();
-        throw error;
-      }
-    });
+          phaseTiming("handoff_complete", launchStartedAt, { server_pid: child.pid, port });
+          launchPage = null;
+          if (snapshotCache === "stale_seed") await 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;
+        }
+      },
+      {
+        onWait: () => {
+          if (reportedLockWait) return;
+          reportedLockWait = true;
+          launchPage?.setProgress({
+            percent: 22,
+            phase: "Aguardando outra abertura do dashboard",
+            detail: "A outra sessão está concluindo o carregamento local antes desta continuar.",
+          });
+        },
+      },
+    );
   } catch (error) {
-    if (launchPage !== null) await launchPage.close().catch(() => {});
+    if (launchPage !== null) {
+      launchPage.setFailure({
+        percent: 100,
+        phase: "Não foi possível preparar o dashboard",
+        detail: formatLauncherError(error instanceof Error ? error.message : String(error), 900),
+      });
+      launchPage.closeAfterFailureObservation();
+      launchPage = null;
+    }
     throw error;
   }
   if (ownedChild === null) return;
@@ -1000,7 +962,11 @@ async function waitForDashboard(port, child) {
     }
     await delay(100);
   }
-  throw new Error(`Timed out waiting for ${dashboardHealthUrl(port)}`);
+  // A cold read-model timeout is not a port collision. Retrying would start
+  // up to four more full builds and exceed the launcher deadline.
+  const timedOut = new Error(`Timed out waiting for ${dashboardHealthUrl(port)}`);
+  timedOut.retryable = false;
+  throw timedOut;
 }
 function exists(path) {
   return access(path).then(