@zaip-ai/cli 1.0.6 → 1.0.7

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

@@ -0,0 +1,81 @@
+import process from "node:process";
+import {
+  appendLauncherLog,
+  buildFrontend,
+  clearDashboardSession,
+  createSessionToken,
+  defaultApiPort,
+  defaultFrontendPort,
+  findAvailablePort,
+  host,
+  openBrowser,
+  readDashboardSession,
+  startFrontend,
+  startProjectionServer,
+  stopChildProcess,
+  stopDashboardSession,
+  waitForHttpOk,
+  workspaceRoot,
+  writeDashboardSession,
+} from "./runtime.mjs";
+
+async function main() {
+  const interactive = Boolean(process.stdout.isTTY || process.stderr.isTTY);
+  const stdio = interactive ? "inherit" : "ignore";
+  const previousSession = await readDashboardSession();
+  void buildFrontend({ stdio }).catch((error) => appendLauncherLog(String(error)));
+  const frontendPort = await findAvailablePort(
+    nextPort(
+      previousSession?.frontendPort,
+      preferredPort(process.env.ZAIP_FRONTEND_PORT, defaultFrontendPort),
+    ),
+  );
+  let apiPort = await findAvailablePort(
+    nextPort(previousSession?.apiPort, preferredPort(process.env.ZAIP_SERVER_PORT, defaultApiPort)),
+  );
+  if (apiPort === frontendPort) apiPort = await findAvailablePort(apiPort + 1);
+  const token = createSessionToken();
+  const projectionServer = await startProjectionServer({ port: apiPort, token, stdio });
+  const frontend = startFrontend({ port: frontendPort, apiPort, token, stdio });
+  const url = `http://${host}:${frontendPort}/?token=${encodeURIComponent(token)}`;
+
+  await writeDashboardSession({
+    kind: "dashboard-local-runtime",
+    workspace: workspaceRoot,
+    rootPid: process.pid,
+    frontendPort,
+    apiPort,
+    createdAt: new Date().toISOString(),
+    pids: [process.pid, projectionServer.pid, frontend.pid].filter(Number.isInteger),
+  });
+  await waitForHttpOk(`http://${host}:${frontendPort}/`);
+  openBrowser(url);
+  await stopDashboardSession(previousSession);
+
+  const stop = (code = 0) => {
+    stopChildProcess(frontend);
+    stopChildProcess(projectionServer);
+    void clearDashboardSession();
+    setTimeout(() => process.exit(code), 200);
+  };
+  frontend.once("exit", (code) => stop(code ?? 0));
+  projectionServer.once("exit", (code) => stop(code ?? 1));
+  process.once("SIGINT", () => stop(0));
+  process.once("SIGTERM", () => stop(0));
+}
+
+function preferredPort(value, fallback) {
+  const parsed = Number.parseInt(value ?? "", 10);
+  return Number.isInteger(parsed) && parsed > 0 && parsed <= 65_535 ? parsed : fallback;
+}
+
+function nextPort(previousPort, fallback) {
+  return Number.isInteger(previousPort) && previousPort > 0 ? previousPort + 1 : fallback;
+}
+
+main().catch((error) => {
+  const message = error instanceof Error ? (error.stack ?? error.message) : String(error);
+  appendLauncherLog(message);
+  process.stderr.write(`${message}\n`);
+  process.exitCode = 1;
+});

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

@@ -1,7 +1,17 @@
 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, writeFile } from "node:fs/promises";
+import {
+  access,
+  mkdir,
+  readdir,
+  readFile,
+  rename,
+  rm,
+  stat,
+  utimes,
+  writeFile,
+} from "node:fs/promises";
 import { createServer as createHttpServer } from "node:http";
 import { createServer } from "node:net";
 import { tmpdir } from "node:os";
@@ -27,8 +37,12 @@ const frontendRoot = resolve(workspaceRoot, ".agents/dashboard/apps/frontend/dis
 const installedServer = resolve(packageRoot, "server.mjs");
 const sourceServer = resolve(packageRoot, "dist/server.js");
 const healthPath = "/api/v2/health";
-const lockTimeoutMs = 10_000;
+// 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.
+const lockTimeoutMs = 120_000;
 const staleLockMs = 30_000;
+const lockHeartbeatFloorMs = 10;
 const startupTimeoutMs = 12_000;
 const maxServerStartAttempts = 4;
 const maxPortHistory = 50;
@@ -66,9 +80,16 @@ export function appendLauncherLog(message) {
 }
 
 export function stripTerminalControlCodes(value) {
+  const escapeCode = String.fromCharCode(27);
+  const bell = String.fromCharCode(7);
+  const operatingSystemCommand = new RegExp(
+    `${escapeCode}\\][^${bell}]*(?:${bell}|${escapeCode}\\\\)`,
+    "g",
+  );
+  const controlSequenceIntroducer = new RegExp(`${escapeCode}\\[[0-?]*[ -/]*[@-~]`, "g");
   return String(value)
-    .replace(/\u001B\][^\u0007]*(?:\u0007|\u001B\\)/g, "")
-    .replace(/\u001B\[[0-?]*[ -/]*[@-~]/g, "")
+    .replace(operatingSystemCommand, "")
+    .replace(controlSequenceIntroducer, "")
     .replace(/\r/g, "")
     .trim();
 }
@@ -245,7 +266,10 @@ async function runWorkspaceBuild(filter) {
     child.once("error", rejectBuild);
     child.once("exit", (code) => {
       if (code === 0) resolveBuild();
-      else rejectBuild(new Error(`Build ${filter} failed (${code}): ${formatLauncherError(outputText)}`));
+      else
+        rejectBuild(
+          new Error(`Build ${filter} failed (${code}): ${formatLauncherError(outputText)}`),
+        );
     });
   });
   return output;
@@ -285,9 +309,16 @@ export async function withLauncherLock(
   while (Date.now() < deadline) {
     try {
       await mkdir(path);
+      const heartbeatIntervalMs = Math.max(lockHeartbeatFloorMs, Math.floor(staleAfterMs / 3));
+      const heartbeat = setInterval(() => {
+        const now = new Date();
+        void utimes(path, now, now).catch(() => {});
+      }, heartbeatIntervalMs);
+      heartbeat.unref?.();
       try {
         return await action();
       } finally {
+        clearInterval(heartbeat);
         await rm(path, { recursive: true, force: true });
       }
     } catch (error) {
@@ -402,8 +433,19 @@ export async function openBrowser(target, spawnImpl = spawn) {
 }
 
 export async function startDashboardLaunchPage(port) {
+  let redirectUrl = null;
+  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(healthPath)) {
       response.writeHead(503, { "Content-Type": "application/json; charset=utf-8" });
       response.end(JSON.stringify({ kind: "zaip-dashboard-launcher", status: "starting" }));
@@ -438,6 +480,9 @@ export async function startDashboardLaunchPage(port) {
   <script>
     async function waitForDashboard(){
       try{
+        const ready=await fetch("/api/v2/ready",{cache:"no-store"});
+        const next=await ready.json();
+        if(next.target){location.replace(next.target);return}
         const response=await fetch("${healthPath}",{cache:"no-store"});
         const payload=await response.json();
         if(response.ok&&payload.kind==="${runtimeKind}"){location.reload();return}
@@ -458,6 +503,11 @@ export async function startDashboardLaunchPage(port) {
   const listeningPort = typeof address === "object" && address !== null ? address.port : port;
   return {
     port: listeningPort,
+    redirect: (target) => {
+      redirectUrl = target;
+    },
+    waitForRedirect: async (timeoutMs = 1_500) =>
+      Promise.race([redirectObserved, delay(timeoutMs).then(() => false)]),
     close: () =>
       new Promise((resolveClose, rejectClose) => {
         server.close((error) => (error ? rejectClose(error) : resolveClose()));
@@ -465,6 +515,16 @@ export async function startDashboardLaunchPage(port) {
   };
 }
 
+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.");
+  }
+}
+
 async function assertRuntimeReady() {
   const serverPath = (await exists(sourceServer)) ? sourceServer : installedServer;
   if (!(await exists(serverPath))) {
@@ -580,49 +640,41 @@ 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 buildSignature = await ensureFreshDashboardBuild();
-    const reusable = await findReusableDashboardSession({ expectedBuildSignature: buildSignature });
-    if (reusable !== null) {
-      await writeDashboardSession(reusable);
-      await recordPortStatus(reusable, "active");
-      if (!(await openBrowser(dashboardUrl(reusable.port, reusable.token)))) {
-        throw new Error(
-          "O dashboard está saudável, mas nenhuma opção conseguiu abrir o navegador padrão.",
-        );
-      }
+    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 previousSessions = await previousDashboardSessions();
-    const excludedPorts = new Set(previousSessions.map((session) => session.port));
-    const token = process.env.ZAIP_UI_TOKEN ?? randomBytes(24).toString("base64url");
-    const launchPort = await findAvailablePortWithFallback({ excludedPorts: [...excludedPorts] });
+    const launchPort = await findAvailablePortWithFallback();
     launchPage = await startDashboardLaunchPage(launchPort);
     if (!(await openBrowser(dashboardUrl(launchPort, token)))) {
       await launchPage.close();
       launchPage = null;
-      throw new Error("Não foi possível abrir a preparação do dashboard no navegador padrão.");
+      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();
-    await launchPage.close();
-    launchPage = null;
-    const { child, port } = await startDashboardServer(
-      serverPath,
-      token,
-      excludedPorts,
-      launchPort,
-    );
+    const { child, port } = await startDashboardServer(serverPath, token, excludedPorts);
     ownedChild = child;
     try {
-      if (port !== launchPort && !(await openBrowser(dashboardUrl(port, token)))) {
-        throw new Error(
-          "O dashboard iniciou em uma porta alternativa, mas não foi possível abrir essa URL.",
-        );
-      }
+      await redirectLaunchPage(launchPage, dashboardUrl(port, token));
+      launchPage = null;
       currentSession = {
         kind: runtimeKind,
         workspace: workspaceRoot,

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

@@ -0,0 +1,378 @@
+import { EventEmitter } from "node:events";
+import { mkdir, mkdtemp, readFile, rm, utimes } from "node:fs/promises";
+import { createServer } from "node:net";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, describe, expect, it } from "vitest";
+import {
+  browserLaunchCommands,
+  findAvailablePort,
+  findAvailablePortWithFallback,
+  findReusableDashboardSession,
+  formatLauncherError,
+  host,
+  openBrowser,
+  probeDashboardPort,
+  readPortRegistry,
+  recordPortStatus,
+  runtimeKind,
+  startDashboardLaunchPage,
+  stripTerminalControlCodes,
+  withLauncherLock,
+  workspaceKey,
+  workspaceRoot,
+  writeDashboardSession,
+} from "./start-dashboard.mjs";
+
+const temporaryDirectories = [];
+
+afterEach(async () => {
+  await Promise.all(
+    temporaryDirectories.splice(0).map((path) => rm(path, { recursive: true, force: true })),
+  );
+});
+
+describe("dashboard executable session", () => {
+  it("removes terminal control sequences from launcher diagnostics", () => {
+    const colored = "\u001B[31mMissing export\u001B[0m\r\n";
+
+    expect(stripTerminalControlCodes(colored)).toBe("Missing export");
+  });
+
+  it("keeps the beginning and end of an oversized launcher error", () => {
+    const message = `imported-symbol${"x".repeat(100)}missing-export`;
+
+    expect(formatLauncherError(message, 40)).toContain("imported-symbol");
+    expect(formatLauncherError(message, 40)).toContain("missing-export");
+  });
+
+  it("starts a new runtime instead of reusing a healthy session", async () => {
+    const source = await readFile(new URL("./start-dashboard.mjs", import.meta.url), "utf8");
+    expect(source).not.toContain("const reusable = await findReusableDashboardSession");
+    expect(source).toContain("const previousSessions = await previousDashboardSessions();");
+    expect(source).toContain(
+      "const excludedPorts = new Set([...previousSessions.map((session) => session.port), launchPort]);",
+    );
+  });
+
+  it("opens preparation before checking freshness and keeps it through server health", async () => {
+    const source = await readFile(new URL("./start-dashboard.mjs", import.meta.url), "utf8");
+    const lock = source.indexOf("await withLauncherLock(async () => {");
+    const preparation = source.indexOf("launchPage = await startDashboardLaunchPage(launchPort);");
+    const freshness = source.indexOf("const buildSignature = await ensureFreshDashboardBuild();");
+    const server = source.indexOf(
+      "const { child, port } = await startDashboardServer(serverPath, token, excludedPorts);",
+    );
+    const redirectAfterServer = source.indexOf(
+      "await redirectLaunchPage(launchPage, dashboardUrl(port, token));",
+    );
+
+    expect(lock).toBeGreaterThan(-1);
+    expect(preparation).toBeGreaterThan(lock);
+    expect(preparation).toBeLessThan(freshness);
+    expect(server).toBeGreaterThan(freshness);
+    expect(redirectAfterServer).toBeGreaterThan(server);
+  });
+
+  it("tears down prior owned sessions only after the new browser handoff", async () => {
+    const source = await readFile(new URL("./start-dashboard.mjs", import.meta.url), "utf8");
+    const redirect = source.indexOf(
+      "await redirectLaunchPage(launchPage, dashboardUrl(port, token));",
+    );
+    const teardown = source.indexOf("for (const previous of previousSessions)");
+
+    expect(redirect).toBeGreaterThan(-1);
+    expect(teardown).toBeGreaterThan(redirect);
+    expect(source).toContain("const stopped = await stopOwnedDashboard(previous);");
+  });
+
+  it("does not force a rebuild from the Windows executable", async () => {
+    const source = await readFile(
+      new URL("../windows-launcher/Program.cs", import.meta.url),
+      "utf8",
+    );
+
+    expect(source).not.toContain("ZAIP_DASHBOARD_FORCE_REBUILD");
+  });
+
+  it("dispatches Windows URLs through the registered protocol handler", () => {
+    const target = "http://127.0.0.1:4317/?token=local-session-token";
+    const commands = browserLaunchCommands(target, "win32", {
+      SystemRoot: "C:\\Windows",
+      ComSpec: "C:\\Windows\\System32\\cmd.exe",
+    });
+
+    expect(commands).toEqual([
+      ["C:\\Windows\\System32\\rundll32.exe", ["url.dll,FileProtocolHandler", target]],
+      ["C:\\Windows\\System32\\cmd.exe", ["/d", "/c", "start", "", target]],
+    ]);
+  });
+
+  it("falls back to another browser command when the first option fails", async () => {
+    let calls = 0;
+    const spawnImpl = () => {
+      calls += 1;
+      const child = new EventEmitter();
+      child.unref = () => {};
+      queueMicrotask(() => child.emit(calls === 1 ? "error" : "spawn", new Error("failed")));
+      return child;
+    };
+
+    await expect(openBrowser("http://127.0.0.1:4317", spawnImpl)).resolves.toBe(true);
+    expect(calls).toBe(2);
+  });
+
+  it("serves an immediate dashboard skeleton while the runtime starts", async () => {
+    const launchPage = await startDashboardLaunchPage(0);
+    try {
+      const page = await fetch(`http://${host}:${launchPage.port}/?token=temporary`);
+      const health = await fetch(`http://${host}:${launchPage.port}/api/v2/health`);
+
+      expect(page.status).toBe(200);
+      await expect(page.text()).resolves.toContain("Pronto para Executar");
+      expect(health.status).toBe(503);
+      await expect(health.json()).resolves.toEqual({
+        kind: "zaip-dashboard-launcher",
+        status: "starting",
+      });
+
+      launchPage.redirect("http://127.0.0.1:4317/?token=reused-session");
+      const ready = await fetch(`http://${host}:${launchPage.port}/api/v2/ready`);
+      await expect(ready.json()).resolves.toEqual({
+        target: "http://127.0.0.1:4317/?token=reused-session",
+      });
+      await expect(launchPage.waitForRedirect(10)).resolves.toBe(true);
+    } finally {
+      await launchPage.close();
+    }
+  });
+
+  it("reuses a healthy session owned by the same workspace", async () => {
+    const directory = await temporaryDirectory();
+    const path = join(directory, "dashboard-session.json");
+    const session = {
+      kind: runtimeKind,
+      workspace: workspaceRoot,
+      workspaceKey,
+      rootPid: 1234,
+      port: 4317,
+      token: "local-session-token",
+      createdAt: new Date().toISOString(),
+    };
+    await writeDashboardSession(session, path);
+
+    const reusable = await findReusableDashboardSession({
+      path,
+      fetchImpl: async () =>
+        new Response(JSON.stringify({ kind: runtimeKind, workspaceKey }), { status: 200 }),
+    });
+
+    expect(reusable).toEqual(session);
+  });
+
+  it("does not claim a health endpoint from another workspace", async () => {
+    const directory = await temporaryDirectory();
+    const path = join(directory, "dashboard-session.json");
+    await writeDashboardSession(
+      {
+        kind: runtimeKind,
+        workspace: workspaceRoot,
+        workspaceKey,
+        rootPid: 1234,
+        port: 4317,
+        token: "local-session-token",
+      },
+      path,
+    );
+
+    const reusable = await findReusableDashboardSession({
+      path,
+      fetchImpl: async () =>
+        new Response(JSON.stringify({ kind: runtimeKind, workspaceKey: "other-workspace" }), {
+          status: 200,
+        }),
+    });
+
+    expect(reusable).toBeNull();
+  });
+
+  it("does not reuse a session built from an older dashboard version", async () => {
+    const directory = await temporaryDirectory();
+    const path = join(directory, "dashboard-session.json");
+    await writeDashboardSession(
+      {
+        kind: runtimeKind,
+        workspace: workspaceRoot,
+        workspaceKey,
+        rootPid: 1234,
+        port: 4317,
+        token: "local-session-token",
+        buildSignature: "older-build",
+      },
+      path,
+    );
+
+    await expect(
+      findReusableDashboardSession({
+        path,
+        expectedBuildSignature: "current-build",
+        fetchImpl: async () =>
+          new Response(JSON.stringify({ kind: runtimeKind, workspaceKey }), { status: 200 }),
+      }),
+    ).resolves.toBeNull();
+  });
+
+  it("recognizes an unavailable runtime only for safe cleanup", async () => {
+    const fetchImpl = async () =>
+      new Response(JSON.stringify({ kind: runtimeKind, workspaceKey, status: "unavailable" }), {
+        status: 503,
+      });
+
+    await expect(probeDashboardPort(4317, fetchImpl)).resolves.toBe(false);
+    await expect(probeDashboardPort(4317, fetchImpl, workspaceKey, false)).resolves.toBe(true);
+  });
+
+  it("skips an occupied preferred port without stopping its owner", async () => {
+    const blocker = createServer();
+    await new Promise((resolveListen) => blocker.listen({ host, port: 0 }, resolveListen));
+    const blockedPort = blocker.address().port;
+
+    const selectedPort = await findAvailablePort(blockedPort);
+
+    expect(selectedPort).not.toBe(blockedPort);
+    expect(blocker.listening).toBe(true);
+    await new Promise((resolveClose) => blocker.close(resolveClose));
+  });
+
+  it("selects a new port when the previously recorded port must not be reused", async () => {
+    const previousPort = await findAvailablePort(20_000);
+    const selectedPort = await findAvailablePortWithFallback({
+      preferred: previousPort,
+      excludedPorts: [previousPort],
+    });
+
+    expect(selectedPort).not.toBe(previousPort);
+  });
+
+  it("persists active and closed dashboard ports per workspace", async () => {
+    const directory = await temporaryDirectory();
+    const path = join(directory, "dashboard-ports.json");
+    const session = {
+      rootPid: 1234,
+      serverPid: 5678,
+      port: 4317,
+      createdAt: "2026-07-15T00:00:00.000Z",
+    };
+
+    await recordPortStatus(session, "active", path);
+    await expect(readPortRegistry(path)).resolves.toEqual([
+      expect.objectContaining({ port: 4317, rootPid: 1234, status: "active" }),
+    ]);
+
+    await recordPortStatus(session, "closed", path);
+    await expect(readPortRegistry(path)).resolves.toEqual([
+      expect.objectContaining({ port: 4317, rootPid: 1234, status: "closed" }),
+    ]);
+  });
+
+  it("recovers an abandoned launcher lock", async () => {
+    const directory = await temporaryDirectory();
+    const path = join(directory, "dashboard-launcher.lock");
+    await mkdir(path);
+    const old = new Date(Date.now() - 31_000);
+    await utimes(path, old, old);
+
+    const result = await withLauncherLock(async () => "recovered", {
+      directory,
+      path,
+      timeoutMs: 1_000,
+      staleAfterMs: 30_000,
+    });
+
+    expect(result).toBe("recovered");
+  });
+
+  it("waits for a concurrent launcher handoff instead of timing out after ten seconds", async () => {
+    const directory = await temporaryDirectory();
+    const path = join(directory, "dashboard-launcher.lock");
+    let releaseFirst;
+    const firstEntered = new Promise((resolveFirst) => {
+      releaseFirst = resolveFirst;
+    });
+    const first = withLauncherLock(
+      async () => {
+        releaseFirst();
+        await new Promise((resolveRelease) => setTimeout(resolveRelease, 40));
+        return "first";
+      },
+      { directory, path, timeoutMs: 1_000 },
+    );
+
+    await firstEntered;
+    const second = withLauncherLock(async () => "second", {
+      directory,
+      path,
+      timeoutMs: 1_000,
+    });
+
+    await expect(Promise.all([first, second])).resolves.toEqual(["first", "second"]);
+  });
+
+  it("does not steal a live lock whose action outlasts the stale threshold", async () => {
+    const directory = await temporaryDirectory();
+    const path = join(directory, "dashboard-launcher.lock");
+    let releaseFirst;
+    const firstEntered = new Promise((resolveFirst) => {
+      releaseFirst = resolveFirst;
+    });
+    const first = withLauncherLock(
+      async () => {
+        releaseFirst();
+        await new Promise((resolveRelease) => setTimeout(resolveRelease, 100));
+        return "first";
+      },
+      { directory, path, timeoutMs: 1_000, staleAfterMs: 30 },
+    );
+
+    await firstEntered;
+    await new Promise((resolveWait) => setTimeout(resolveWait, 50));
+    const second = withLauncherLock(async () => "second", {
+      directory,
+      path,
+      timeoutMs: 1_000,
+      staleAfterMs: 30,
+    });
+
+    await expect(Promise.all([first, second])).resolves.toEqual(["first", "second"]);
+  });
+
+  it("coalesces a click that observes a newly handed-off healthy session", async () => {
+    const source = await readFile(new URL("./start-dashboard.mjs", import.meta.url), "utf8");
+    const observed = source.indexOf("const observedRootPid = observedSession?.rootPid ?? null;");
+    const lock = source.indexOf("await withLauncherLock(async () => {");
+    const coalesced = source.indexOf("Coalesced dashboard launcher request");
+    const preparation = source.indexOf("launchPage = await startDashboardLaunchPage(launchPort);");
+
+    expect(observed).toBeGreaterThan(-1);
+    expect(observed).toBeLessThan(lock);
+    expect(coalesced).toBeGreaterThan(lock);
+    expect(preparation).toBeGreaterThan(coalesced);
+    expect(source).toContain('await writeLauncherStatus("ok");');
+  });
+
+  it("gives the Windows wrapper margin beyond the bounded Node launcher wait", async () => {
+    const source = await readFile(
+      new URL("../windows-launcher/Program.cs", import.meta.url),
+      "utf8",
+    );
+
+    expect(source).toContain("DateTime.UtcNow.AddSeconds(135)");
+    expect(source).toContain("mais de 135 segundos");
+  });
+});
+
+async function temporaryDirectory() {
+  const path = await mkdtemp(join(tmpdir(), "zaip-dashboard-launcher-test-"));
+  temporaryDirectories.push(path);
+  return path;
+}

package/templates/.agents/dashboard/packages/local-runtime/tsconfig.json

@@ -0,0 +1,8 @@
+{
+  "extends": "../../../../tsconfig.base.json",
+  "compilerOptions": {
+    "noEmit": true,
+    "types": ["node"]
+  },
+  "include": ["src/**/*.ts"]
+}

package/templates/.agents/dashboard/packages/ui/package.json

@@ -0,0 +1,18 @@
+{
+  "name": "@zaip-ai/dashboard-ui",
+  "version": "1.0.0",
+  "private": true,
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "scripts": {
+    "clean": "node ../../../../scripts/clean.mjs",
+    "test": "vitest run --passWithNoTests",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "react": "19.2.7",
+    "react-dom": "19.2.7"
+  }
+}