@zaip-ai/cli 1.3.8 → 1.4.2

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

@@ -1,20 +1,9 @@
 import { spawn } from "node:child_process";
 import { createHash, randomBytes } from "node:crypto";
 import { appendFileSync, mkdirSync } from "node:fs";
-import {
-  access,
-  mkdir,
-  readdir,
-  readFile,
-  rename,
-  rm,
-  stat,
-  utimes,
-  writeFile,
-} from "node:fs/promises";
-import { createServer } from "node:net";
+import { mkdir, readdir, readFile, rename, rm, stat, utimes, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
-import { dirname, join, relative, resolve, win32 } from "node:path";
+import { dirname, join, resolve, win32 } from "node:path";
 import process from "node:process";
 import { fileURLToPath } from "node:url";
 import { collectPreviousDashboardSessions } from "./start-dashboard-history.mjs";
@@ -25,14 +14,23 @@ import {
   presentLaunchFailure,
   writeLauncherStatus,
 } from "./start-dashboard-lifecycle.mjs";
-import { assertDashboardPrerequisites } from "./start-dashboard-prerequisites.mjs";
+import { assertDashboardPrerequisites, exists } from "./start-dashboard-prerequisites.mjs";
 import {
+  isKnownDashboardLauncher,
   isProcessAlive,
   stopOwnedDashboardProcess,
   stopProcessTree,
   teardownWarning,
 } from "./start-dashboard-processes.mjs";
-import { refreshIsRunning, startSeedRefresh } from "./start-dashboard-refresh.mjs";
+import {
+  assertInstalledDashboardArtifacts,
+  isDashboardSourceWorkspace as hasDashboardSourceWorkspace,
+  dashboardServerPathForWorkspace as selectDashboardServerPath,
+} from "./start-dashboard-runtime-selection.mjs";
+import {
+  isPortFree,
+  startDashboardServer as launchDashboardServer,
+} from "./start-dashboard-server.mjs";
 
 export {
   isAncestorProcess,
@@ -53,15 +51,22 @@ export const workspaceKey = createHash("sha256")
   .slice(0, 16);
 export const sessionDirectory = join(tmpdir(), "zaip-aios", `dashboard-sqlite-${workspaceKey}`);
 export const sessionPath = join(sessionDirectory, "dashboard-sqlite-session.json");
+// This small, token-free record is the observable ownership contract while a
+// dashboard is still preparing.  It deliberately does not replace the active
+// runtime session, so a newer click can take priority without losing the PID
+// needed to stop the older runtime.
+export const launchPath = join(sessionDirectory, "dashboard-sqlite-launch.json");
+const claimLockPath = join(sessionDirectory, "dashboard-sqlite-claim.lock");
+const claimLockTimeoutMs = 5_000;
+const claimLockStaleMs = 30_000;
 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 durable and independent of temporary SQLite generations.
-const sqliteSnapshotCacheDirectory = join(sqliteReadModelDirectory, "cache");
-// Node's bytecode cache is disposable acceleration beside private SQLite generations.
-const nodeCompileCacheDirectory = join(sqliteReadModelDirectory, "node-compile-cache");
+const sqliteReadModelDirectory = resolve(workspaceRoot, ".local", "sqlite");
+const sqliteReadModelPath = join(sqliteReadModelDirectory, "zaip-aios-dashboard.sqlite");
+// Bytecode is disposable session data, separate from the persistent database.
+const nodeCompileCacheDirectory = join(sessionDirectory, "node-compile-cache");
 const installedServer = resolve(packageRoot, "server.mjs");
 const sourceServer = resolve(packageRoot, "dist/server.cjs");
 const healthPath = "/api/v2/health";
@@ -183,6 +188,103 @@ export async function readDashboardSession(path = sessionPath) {
 export async function writeDashboardSession(session, path = sessionPath) {
   await writeJsonAtomic(path, session);
 }
+export async function claimDashboardLaunch(
+  { launchPort, token },
+  {
+    path = launchPath,
+    lockPath = claimLockPath,
+    stopProcessTreeImpl = stopProcessTree,
+    isProcessAliveImpl = isProcessAlive,
+    isKnownDashboardLauncherImpl = isKnownDashboardLauncher,
+    delayImpl = delay,
+  } = {},
+) {
+  await mkdir(sessionDirectory, { recursive: true });
+  // This lock is deliberately short: it serializes only ownership transfer,
+  // never the SQLite build. A later click therefore observes and cancels the
+  // immediately preceding claim rather than a stale common predecessor.
+  const claimDeadline = Date.now() + claimLockTimeoutMs;
+  while (true) {
+    try {
+      await mkdir(lockPath);
+      await writeFile(join(lockPath, "owner"), String(process.pid), "utf8");
+      break;
+    } catch (error) {
+      if (error?.code !== "EEXIST") throw error;
+      const details = await stat(lockPath).catch(() => null);
+      const ownerPid = Number.parseInt(
+        await readFile(join(lockPath, "owner"), "utf8").catch(() => ""),
+        10,
+      );
+      if (Number.isInteger(ownerPid) && ownerPid > 0 && !(await isProcessAliveImpl(ownerPid))) {
+        await rm(lockPath, { recursive: true, force: true });
+        continue;
+      }
+      if (details !== null && Date.now() - details.mtimeMs > claimLockStaleMs) {
+        await rm(lockPath, { recursive: true, force: true });
+        continue;
+      }
+      if (Date.now() >= claimDeadline)
+        throw new Error("Timed out waiting for the dashboard ownership claim lock.");
+      await delayImpl(25);
+    }
+  }
+  try {
+    const previous = await readDashboardSession(path);
+    const claim = {
+      kind: "zaip-dashboard-sqlite-launch",
+      workspace: workspaceRoot,
+      workspaceKey,
+      launcherPid: process.pid,
+      launchPort,
+      // Only a non-secret correlation id is persisted for diagnostics.
+      claimId: createHash("sha256").update(`${token}:${process.pid}`).digest("hex").slice(0, 16),
+      state: "preparing",
+      claimedAt: new Date().toISOString(),
+      statusPath: process.env.ZAIP_LAUNCH_STATUS ?? null,
+    };
+    await writeJsonAtomic(path, claim);
+    if (
+      previous?.kind === claim.kind &&
+      previous?.workspaceKey === workspaceKey &&
+      Number.isInteger(previous?.launcherPid) &&
+      previous.launcherPid > 0 &&
+      previous.launcherPid !== process.pid
+    ) {
+      // A claim replacement is also an active cancellation boundary.  Do not
+      // merely fence stale cleanup while its expensive SQLite build continues.
+      if (!(await isKnownDashboardLauncherImpl(previous.launcherPid, packageRoot))) {
+        // The PID may have exited or been reused by an unrelated process. Its
+        // record is stale; never kill it and let this claim continue.
+        return claim;
+      }
+      if (typeof previous.statusPath === "string" && previous.statusPath.startsWith(tmpdir()))
+        await writeFile(
+          previous.statusPath,
+          "cancelled\nSuperseded by a newer dashboard click.",
+          "utf8",
+        ).catch(() => {});
+      await stopProcessTreeImpl(previous.launcherPid);
+      const deadline = Date.now() + 5_000;
+      while ((await isProcessAliveImpl(previous.launcherPid)) && Date.now() < deadline)
+        await delayImpl(50);
+      if (await isProcessAliveImpl(previous.launcherPid))
+        throw new Error(
+          "Could not stop the superseded dashboard launcher before starting a new session.",
+        );
+    }
+    return claim;
+  } finally {
+    await rm(lockPath, { recursive: true, force: true });
+  }
+}
+export async function isCurrentDashboardLaunch(claim) {
+  const current = await readDashboardSession(launchPath);
+  return current?.kind === claim.kind && current?.claimId === claim.claimId;
+}
+export async function clearDashboardLaunch(claim) {
+  if (await isCurrentDashboardLaunch(claim)) await rm(launchPath, { force: true });
+}
 async function writeJsonAtomic(path, value) {
   const directory = dirname(path);
   await mkdir(directory, { recursive: true });
@@ -269,11 +371,31 @@ export async function findReusableDashboardSession({
     session?.workspaceKey !== expectedWorkspaceKey ||
     typeof session?.token !== "string" ||
     session.token.length === 0 ||
-    (expectedBuildSignature !== null && session?.buildSignature !== expectedBuildSignature) ||
-    (expectedSnapshotState !== null && session?.snapshotState !== expectedSnapshotState)
+    (expectedBuildSignature !== null && session?.buildSignature !== expectedBuildSignature)
   ) {
     return null;
   }
+  // Session metadata is written before the serving process finishes promoting
+  // a stale seed. Trust a state transition only after the owned server itself
+  // reports it; never reuse an unknown or still-updating generation as current.
+  if (expectedSnapshotState !== null && session.snapshotState !== expectedSnapshotState) {
+    if (!Number.isInteger(session.port)) return null;
+    try {
+      const response = await fetchImpl(dashboardHealthUrl(session.port), {
+        signal: AbortSignal.timeout(500),
+      });
+      const payload = await response.json();
+      if (
+        !response.ok ||
+        payload?.kind !== runtimeKind ||
+        payload?.workspaceKey !== expectedWorkspaceKey ||
+        payload?.snapshot_state !== expectedSnapshotState
+      )
+        return null;
+    } catch {
+      return null;
+    }
+  }
   if (
     Number.isInteger(session.port) &&
     (await probeDashboardPort(session.port, fetchImpl, expectedWorkspaceKey))
@@ -292,9 +414,14 @@ export async function findReusableDashboardSession({
   return port === undefined ? null : { ...session, port };
 }
 
-async function backgroundRefreshIsRunning() {
-  return refreshIsRunning(join(sessionDirectory, "dashboard-sqlite-refresh.json"), isProcessAlive);
+export function requestBackgroundProjectionRefresh(session, fetchImpl = fetch) {
+  return fetchImpl(`http://${host}:${session.port}/api/v2/refresh-projection`, {
+    method: "POST",
+    headers: { "x-zaip-session": session.token },
+    signal: AbortSignal.timeout(750),
+  }).catch(() => undefined);
 }
+
 export async function latestModifiedAt(paths, excludedSourcePaths = []) {
   let latest = 0;
   for (const path of paths) {
@@ -435,31 +562,22 @@ export async function refreshDashboardBuildTargets({
   return { artifacts: Object.values(targets).flatMap((target) => target.artifacts), builtTargets };
 }
 async function ensureFreshDashboardBuild(onProgress = () => {}) {
-  // npm consumers receive a ready-to-run server and frontend bundle. They do
-  // not receive development-only esbuild, so never turn the first dashboard
-  // click into a pnpm-install requirement when that packaged runtime exists.
-  const buildTool = resolve(workspaceRoot, "node_modules/esbuild");
-  if (!(await exists(buildTool))) {
+  if (!(await hasDashboardSourceWorkspace(workspaceRoot))) {
     const packagedArtifacts = [installedServer, resolve(frontendRoot, "index.html")];
-    if (
-      await Promise.all(packagedArtifacts.map((path) => exists(path))).then((entries) =>
-        entries.every(Boolean),
-      )
-    ) {
-      buildProgress(
-        onProgress,
-        39,
-        "Usando runtime empacotado",
-        "O pacote npm já inclui o dashboard pronto; nenhuma instalação de desenvolvimento é necessária.",
-      );
-      const signature = await Promise.all(
-        [...packagedArtifacts, resolve(packageRoot, "start-dashboard.mjs")].map(async (path) => {
-          const details = await stat(path);
-          return `${path}:${details.size}:${details.mtimeMs}`;
-        }),
-      );
-      return createHash("sha256").update(signature.join("|")).digest("hex");
-    }
+    await assertInstalledDashboardArtifacts(packagedArtifacts);
+    buildProgress(
+      onProgress,
+      39,
+      "Usando runtime empacotado",
+      "O pacote npm já inclui o dashboard pronto; nenhuma instalação de desenvolvimento é necessária.",
+    );
+    const signature = await Promise.all(
+      [...packagedArtifacts, resolve(packageRoot, "start-dashboard.mjs")].map(async (path) => {
+        const details = await stat(path);
+        return `${path}:${details.size}:${details.mtimeMs}`;
+      }),
+    );
+    return createHash("sha256").update(signature.join("|")).digest("hex");
   }
   const { artifacts } = await refreshDashboardBuildTargets({ onProgress });
   const artifactFingerprint = await Promise.all(
@@ -470,6 +588,16 @@ async function ensureFreshDashboardBuild(onProgress = () => {}) {
   );
   return createHash("sha256").update(artifactFingerprint.join("|")).digest("hex");
 }
+export async function isDashboardSourceWorkspace(root = workspaceRoot) {
+  return hasDashboardSourceWorkspace(root);
+}
+export async function dashboardServerPathForWorkspace({
+  root = workspaceRoot,
+  sourcePath = sourceServer,
+  installedPath = installedServer,
+} = {}) {
+  return selectDashboardServerPath({ root, sourcePath, installedPath });
+}
 export async function withLauncherLock(
   action,
   {
@@ -478,6 +606,7 @@ export async function withLauncherLock(
     timeoutMs = lockTimeoutMs,
     staleAfterMs = staleLockMs,
     onWait = () => {},
+    newestClickWins = false,
   } = {},
 ) {
   await mkdir(directory, { recursive: true });
@@ -485,6 +614,9 @@ export async function withLauncherLock(
   while (Date.now() < deadline) {
     try {
       await mkdir(path);
+      const lockOwner = `${process.pid}-${randomBytes(8).toString("hex")}`;
+      const lockOwnerPath = join(path, "owner");
+      await writeFile(lockOwnerPath, lockOwner, { encoding: "utf8", mode: 0o600 });
       const heartbeatIntervalMs = Math.max(lockHeartbeatFloorMs, Math.floor(staleAfterMs / 3));
       const heartbeat = setInterval(() => {
         const now = new Date();
@@ -495,10 +627,20 @@ export async function withLauncherLock(
         return await action();
       } finally {
         clearInterval(heartbeat);
-        await rm(path, { recursive: true, force: true });
+        // Fencing prevents a superseded owner from deleting the newer click's
+        // lock directory in its finally block.
+        if ((await readFile(lockOwnerPath, "utf8").catch(() => "")) === lockOwner)
+          await rm(path, { recursive: true, force: true });
       }
     } catch (error) {
       if (error?.code !== "EEXIST") throw error;
+      if (newestClickWins) {
+        // The previous holder checks its launch claim at every expensive
+        // boundary.  Replacing the directory lets the latest executable click
+        // proceed immediately instead of presenting a waiting screen.
+        await rm(path, { recursive: true, force: true });
+        continue;
+      }
       const lockStat = await stat(path).catch(() => null);
       if (lockStat !== null && Date.now() - lockStat.mtimeMs > staleAfterMs) {
         await rm(path, { recursive: true, force: true });
@@ -512,7 +654,7 @@ export async function withLauncherLock(
 }
 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;
+    if (await isPortFree(host, port)) return port;
   }
   throw new Error(
     `No free dashboard port found between ${startPort} and ${Math.min(startPort + maxPortAttempts - 1, 65_535)}`,
@@ -528,7 +670,7 @@ export async function findAvailablePortWithFallback({
   );
   for (const startPort of fallbackStarts) {
     for (let port = startPort; port < Math.min(startPort + maxPortAttempts, 65_536); port += 1) {
-      if (!excluded.has(port) && (await isPortFree(port))) return port;
+      if (!excluded.has(port) && (await isPortFree(host, port))) return port;
     }
   }
   for (let attempt = 0; attempt < 5; attempt += 1) {
@@ -630,10 +772,7 @@ async function redirectLaunchPage(launchPage, target) {
   launchPage.closeAfterHandoffGrace();
 }
 async function assertRuntimeReady() {
-  const serverPath =
-    (await exists(resolve(workspaceRoot, "node_modules/esbuild"))) && (await exists(sourceServer))
-      ? sourceServer
-      : installedServer;
+  const serverPath = await dashboardServerPathForWorkspace();
   if (!(await exists(serverPath))) {
     throw new Error(
       "Dashboard server bundle is missing; run the ZAIP release build or reinstall ZAIP-AIOS",
@@ -677,167 +816,30 @@ async function startDashboardServer(
   excludedPorts,
   initialPort = null,
   onProgress = () => {},
+  onChildStarted = () => {},
 ) {
-  const failures = [];
-  for (let attempt = 1; attempt <= maxServerStartAttempts; attempt += 1) {
-    const port =
-      attempt === 1 && Number.isInteger(initialPort)
-        ? 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: {
-        ...process.env,
-        ZAIP_WORKSPACE: workspaceRoot,
-        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,
-    });
-    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);
-      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);
-      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}`,
-      );
-      if (error.retryable === false) break;
-    }
-  }
-  throw new Error(
-    `Não foi possível iniciar o dashboard após os fallbacks. ${failures.join(" | ")}`,
-  );
-}
-
-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;
-}
-async function refreshSnapshotSeedInBackground() {
-  const refreshStatusPath = join(sessionDirectory, "dashboard-sqlite-refresh.json");
-  const refreshLogPath = join(sessionDirectory, "dashboard-sqlite-refresh.log");
-  return startSeedRefresh({
-    appendLog: appendLauncherLog,
-    cacheDirectory: sqliteSnapshotCacheDirectory,
-    isRunning: backgroundRefreshIsRunning,
-    isProcessAlive,
-    lockPath: join(sessionDirectory, "dashboard-sqlite-refresh.lock"),
+  return launchDashboardServer({
+    serverPath,
+    token,
+    excludedPorts,
+    initialPort,
+    onProgress,
+    onChildStarted,
+    maxAttempts: maxServerStartAttempts,
+    dbPath: sqliteReadModelPath,
     packageRoot,
-    randomBytes,
-    refreshLogPath,
-    refreshStatusPath,
-    sqliteDirectory: sqliteReadModelDirectory,
-    stopProcessTree,
     workspaceRoot,
-    writeJsonAtomic,
+    frontendRoot,
+    compileCacheDirectory: nodeCompileCacheDirectory,
+    findPort: findAvailablePortWithFallback,
+    waitForDashboard,
+    stopProcessTree,
+    sanitize: stripTerminalControlCodes,
+    formatError: formatLauncherError,
+    appendLog: appendLauncherLog,
   });
 }
+
 async function main() {
   let ownedChild = null;
   let currentSession = null;
@@ -851,6 +853,25 @@ async function main() {
   // probe mistake its intentional 503 for a server failure.
   launchPage = await startDashboardLaunchPage(0);
   const launchPort = launchPage.port;
+  const launchClaim = await claimDashboardLaunch({ launchPort, token });
+  let browserClosed = false;
+  void launchPage.waitForBrowserDeparture().then(() => {
+    if (launchPage === null) return;
+    browserClosed = true;
+    if (ownedChild !== null) void stopProcessTree(ownedChild.pid);
+  });
+  const assertCurrentLaunch = async () => {
+    if (browserClosed) {
+      const closed = new Error("The dashboard browser was closed during preparation.");
+      closed.code = "ZAIP_DASHBOARD_BROWSER_CLOSED";
+      throw closed;
+    }
+    if (!(await isCurrentDashboardLaunch(launchClaim))) {
+      const replacement = new Error("Dashboard launch was superseded by a newer executable click.");
+      replacement.code = "ZAIP_DASHBOARD_SUPERSEDED";
+      throw replacement;
+    }
+  };
   try {
     if (!(await openBrowser(dashboardUrl(launchPort, token)))) {
       throw new Error("Could not open the dashboard preparation page in the default browser.");
@@ -862,6 +883,7 @@ async function main() {
         "Verificando Node.js 22 e o suporte a node:sqlite; isto não instala um banco de dados.",
     });
     await assertDashboardPrerequisites(workspaceRoot);
+    await assertCurrentLaunch();
     launchPage.setProgress({
       percent: 18,
       phase: "Preparando a sessão do dashboard",
@@ -870,6 +892,7 @@ async function main() {
     let reportedLockWait = false;
     await withLauncherLock(
       async () => {
+        await assertCurrentLaunch();
         phaseTiming("lock_acquired", launchStartedAt);
         const buildStartedAt = Date.now();
         launchPage.setProgress({
@@ -880,42 +903,16 @@ async function main() {
         const buildSignature = await ensureFreshDashboardBuild((progress) =>
           launchPage?.setProgress(progress),
         );
+        await assertCurrentLaunch();
         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(
-              `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;
-          }
-        }
         const previousSessions = await previousDashboardSessions();
+        // The current executable is authoritative.  Retire every verified
+        // previous owner before allocating the new generation, never reuse it.
+        for (const previous of previousSessions) {
+          const status = await stopOwnedDashboard(previous);
+          await recordPortStatus(previous, status);
+        }
+        await assertCurrentLaunch();
         const excludedPorts = new Set([
           ...previousSessions.map((session) => session.port),
           launchPort,
@@ -925,7 +922,7 @@ async function main() {
         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.",
+          detail: "Abrindo o banco SQLite persistente deste workspace.",
         });
         const { child, port, dbPath, snapshotCache } = await startDashboardServer(
           serverPath,
@@ -933,6 +930,9 @@ async function main() {
           excludedPorts,
           null,
           (progress) => launchPage?.setProgress(progress),
+          (child) => {
+            ownedChild = child;
+          },
         );
         phaseTiming("server_ready", readyStartedAt, {
           server_pid: child.pid,
@@ -949,7 +949,7 @@ async function main() {
                 : "Dashboard pronto",
             detail:
               snapshotCache === "stale_seed"
-                ? "Os dados canônicos estão sendo atualizados em segundo plano para a próxima abertura."
+                ? "Os dados canônicos estão sendo atualizados em segundo plano nesta sessão."
                 : "Validando saúde e dados iniciais antes de abrir a tela principal.",
           });
           if (snapshotCache === "stale_seed") await delay(350);
@@ -957,9 +957,9 @@ async function main() {
             launchPage,
             dashboardUrl(port, token, snapshotCache === "stale_seed"),
           );
+          await assertCurrentLaunch();
           phaseTiming("handoff_complete", launchStartedAt, { server_pid: child.pid, port });
           launchPage = null;
-          if (snapshotCache === "stale_seed") await refreshSnapshotSeedInBackground();
           currentSession = {
             kind: runtimeKind,
             workspace: workspaceRoot,
@@ -971,19 +971,20 @@ async function main() {
             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.
+            // The serving process owns the stale-seed refresh and promotes it
+            // into this session, so a later click can reuse the current
+            // generation after the health state flips.
             snapshotState: snapshotCache === "stale_seed" ? "updating" : "current",
             createdAt: new Date().toISOString(),
           };
+          await assertCurrentLaunch();
           await writeDashboardSession(currentSession);
+          await writeJsonAtomic(launchPath, { ...launchClaim, state: "ready", port });
           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")
@@ -1004,6 +1005,7 @@ async function main() {
         }
       },
       {
+        newestClickWins: true,
         onWait: () => {
           if (reportedLockWait) return;
           reportedLockWait = true;
@@ -1016,6 +1018,13 @@ async function main() {
       },
     );
   } catch (error) {
+    if (
+      error?.code === "ZAIP_DASHBOARD_SUPERSEDED" ||
+      error?.code === "ZAIP_DASHBOARD_BROWSER_CLOSED"
+    ) {
+      await writeLauncherStatus("cancelled").catch(() => {});
+      return;
+    }
     launchPage = presentLaunchFailure(launchPage, error, formatLauncherError);
     throw error;
   }
@@ -1025,16 +1034,8 @@ async function main() {
     currentSession,
     clearOwnedDashboardSession,
     recordPortStatus,
-    removeGeneratedReadModel,
-  });
-}
-function isPortFree(port) {
-  return new Promise((resolvePort) => {
-    const server = createServer();
-    server.unref();
-    server.once("error", () => resolvePort(false));
-    server.listen({ host, port }, () => server.close(() => resolvePort(true)));
   });
+  await clearDashboardLaunch(launchClaim);
 }
 async function waitForDashboard(port, child) {
   // A cold SQLite read model has no meaningful fixed duration: canonical
@@ -1075,12 +1076,6 @@ async function waitForDashboard(port, child) {
     await delay(100);
   }
 }
-function exists(path) {
-  return access(path).then(
-    () => true,
-    () => false,
-  );
-}
 function delay(milliseconds) {
   return new Promise((resolveDelay) => setTimeout(resolveDelay, milliseconds));
 }