@zaip-ai/cli 1.0.8 → 1.3.1

package/templates/.agents/dashboard/packages/local-runtime/src/sqlite-snapshot-cache.ts

@@ -0,0 +1,129 @@
+import { randomUUID } from "node:crypto";
+import { copyFile, mkdir, readdir, rename, rm, stat } from "node:fs/promises";
+import { dirname, join, resolve } from "node:path";
+import { DatabaseSync } from "node:sqlite";
+
+export async function pruneSnapshotCache(directory: string, activePath: string): Promise<void> {
+  const entries = await readdir(directory, { withFileTypes: true }).catch(() => []);
+  const stale = await Promise.all(
+    entries
+      .filter(
+        (entry) =>
+          entry.isFile() &&
+          entry.name.endsWith(".sqlite") &&
+          resolve(directory, entry.name) !== activePath,
+      )
+      .map(async (entry) => ({
+        path: resolve(directory, entry.name),
+        mtime: (await stat(resolve(directory, entry.name))).mtimeMs,
+      })),
+  );
+  for (const entry of stale.sort((a, b) => b.mtime - a.mtime).slice(1))
+    await rm(entry.path, { force: true }).catch(() => {});
+  for (const entry of entries) {
+    if (!entry.isFile() || !entry.name.includes(".sqlite.") || !entry.name.includes(".tmp"))
+      continue;
+    const candidate = resolve(directory, entry.name);
+    if (Date.now() - (await stat(candidate)).mtimeMs > 60_000)
+      await rm(candidate, { force: true }).catch(() => {});
+  }
+}
+
+export function readSnapshotFileCount(
+  path: string,
+  fingerprint: string,
+  schemaVersion: string,
+  hasRequiredPayloads: (database: DatabaseSync) => boolean,
+): number | null {
+  try {
+    const database = new DatabaseSync(path, { readOnly: true });
+    const value = (key: string) =>
+      (
+        database.prepare("SELECT value FROM zaip_vw_read_model_metadata WHERE key = ?").get(key) as
+          | { value?: string }
+          | undefined
+      )?.value;
+    const files = Number(value("source_file_count") ?? 0);
+    const result =
+      value("source_fingerprint") === fingerprint &&
+      value("schema_version") === schemaVersion &&
+      hasRequiredPayloads(database)
+        ? files
+        : null;
+    database.close();
+    return result;
+  } catch {
+    return null;
+  }
+}
+
+export async function mostRecentCompatibleSnapshot(
+  directory: string,
+  schemaVersion: string,
+  hasRequiredPayloads: (database: DatabaseSync) => boolean,
+): Promise<{ path: string; files: number } | null> {
+  const entries = await readdir(directory, { withFileTypes: true }).catch(() => []);
+  const candidates = await Promise.all(
+    entries
+      .filter((entry) => entry.isFile() && entry.name.endsWith(".sqlite"))
+      .map(async (entry) => ({
+        path: join(directory, entry.name),
+        mtime: (await stat(join(directory, entry.name))).mtimeMs,
+      })),
+  );
+  for (const candidate of candidates.sort((left, right) => right.mtime - left.mtime)) {
+    const files = readCompatibleSnapshotFileCount(
+      candidate.path,
+      schemaVersion,
+      hasRequiredPayloads,
+    );
+    if (files !== null) return { path: candidate.path, files };
+  }
+  return null;
+}
+
+function readCompatibleSnapshotFileCount(
+  path: string,
+  schemaVersion: string,
+  hasRequiredPayloads: (database: DatabaseSync) => boolean,
+): number | null {
+  try {
+    const database = new DatabaseSync(path, { readOnly: true });
+    const value = (key: string) =>
+      (
+        database.prepare("SELECT value FROM zaip_vw_read_model_metadata WHERE key = ?").get(key) as
+          | { value?: string }
+          | undefined
+      )?.value;
+    const files = Number(value("source_file_count") ?? 0);
+    const result =
+      value("schema_version") === schemaVersion && hasRequiredPayloads(database) ? files : null;
+    database.close();
+    return result;
+  } catch {
+    return null;
+  }
+}
+
+export function installLegacyViewAliases(database: DatabaseSync): void {
+  const views = database
+    .prepare("SELECT name FROM sqlite_master WHERE type = 'view' AND name LIKE 'zaip_vw_%'")
+    .all() as Array<{ name: string }>;
+  for (const { name } of views) {
+    const alias = name.slice("zaip_vw_".length);
+    const quoted = (identifier: string) => `"${identifier.replaceAll('"', '""')}"`;
+    database.exec(`CREATE TEMP VIEW ${quoted(alias)} AS SELECT * FROM main.${quoted(name)}`);
+  }
+}
+
+export async function materializeSnapshot(source: string, destination: string): Promise<void> {
+  await mkdir(dirname(destination), { recursive: true });
+  const temporaryPath = `${destination}.${process.pid}.${randomUUID()}.tmp`;
+  await copyFile(source, temporaryPath);
+  try {
+    await rename(temporaryPath, destination);
+  } catch (error) {
+    await rm(temporaryPath, { force: true });
+    throw error;
+  }
+}

package/templates/.agents/dashboard/packages/local-runtime/src/sqlite-snapshot-install.test.ts

@@ -0,0 +1,26 @@
+import { mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, describe, expect, it } from "vitest";
+import { activateStagedSqliteSnapshot } from "./sqlite-snapshot-install.js";
+
+const temporaryDirectories: string[] = [];
+
+afterEach(async () => {
+  await Promise.all(
+    temporaryDirectories.splice(0).map((directory) => rm(directory, { recursive: true })),
+  );
+});
+
+describe("SQLite snapshot handoff", () => {
+  it("renames the validated stage synchronously during the close/reopen handoff", async () => {
+    const directory = await mkdtemp(join(tmpdir(), "zaip-snapshot-install-"));
+    temporaryDirectories.push(directory);
+    const staged = join(directory, "next.sqlite");
+    const destination = join(directory, "read-model.sqlite");
+    await writeFile(staged, "next-generation");
+
+    expect(activateStagedSqliteSnapshot(staged, destination)).toBeUndefined();
+    await expect(readFile(destination, "utf8")).resolves.toBe("next-generation");
+  });
+});

package/templates/.agents/dashboard/packages/local-runtime/src/sqlite-snapshot-install.ts

@@ -0,0 +1,28 @@
+import { renameSync } from "node:fs";
+import { copyFile, mkdir, rm } from "node:fs/promises";
+import { dirname } from "node:path";
+
+export async function stageSqliteSnapshot(
+  source: string,
+  destination: string,
+  validate: (path: string) => unknown,
+) {
+  await mkdir(dirname(destination), { recursive: true });
+  const staged = `${destination}.${process.pid}.refresh.tmp`;
+  await copyFile(source, staged);
+  try {
+    validate(staged);
+    return staged;
+  } catch (error) {
+    await rm(staged, { force: true });
+    throw error;
+  }
+}
+
+/**
+ * Called after the old connection is closed. Keep the handoff in this tick so
+ * no request can observe a closed SQLite handle between close and replacement.
+ */
+export function activateStagedSqliteSnapshot(staged: string, destination: string) {
+  renameSync(staged, destination);
+}

package/templates/.agents/dashboard/packages/local-runtime/src/sqlite-snapshot-seed.test.ts

@@ -0,0 +1,116 @@
+import { copyFile, mkdir, mkdtemp, readdir, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { DatabaseSync } from "node:sqlite";
+import { afterEach, describe, expect, it } from "vitest";
+import { hasRequiredFirstFoldPayloads } from "./sqlite-first-fold-persistence.js";
+import { rebuildSqliteReadModel, SqliteReadModelFileSystem } from "./sqlite-read-model.js";
+
+const roots: string[] = [];
+
+afterEach(async () => {
+  await Promise.all(roots.splice(0).map((root) => rm(root, { recursive: true, force: true })));
+});
+
+describe("SQLite snapshot seed publication", () => {
+  it("skips a newer incomplete seed and materializes the prior complete cache", async () => {
+    const root = await mkdtemp(join(tmpdir(), "zaip-snapshot-seed-"));
+    roots.push(root);
+    const task = join(root, ".agents", "records", "tasks", "task.md");
+    await mkdir(join(root, ".agents", "records", "tasks"), { recursive: true });
+    await mkdir(join(root, ".agents", "config"), { recursive: true });
+    await writeFile(join(root, ".agents", "config", "project.yaml"), "zaip:\n  enabled: true\n");
+    await writeFile(task, "# original\n");
+    await expect(rebuildSqliteReadModel(root)).resolves.toMatchObject({ cache: "rebuilt" });
+    const cacheDirectory = join(root, ".local", "dashboard-sqlite", "cache");
+    const completeName = (await readdir(cacheDirectory)).find((name) => name.endsWith(".sqlite"));
+    expect(completeName).toBeDefined();
+    if (completeName === undefined) throw new Error("Expected a complete SQLite seed");
+    const incomplete = join(cacheDirectory, "v67-ff5-incomplete-newest.sqlite");
+    await copyFile(join(cacheDirectory, completeName), incomplete);
+    const incompleteDatabase = new DatabaseSync(incomplete);
+    incompleteDatabase
+      .prepare("DELETE FROM zaip_aios_activities WHERE payload_type='first_fold_all_time_cache'")
+      .run();
+    incompleteDatabase.close();
+    await writeFile(task, "# changed canonically\n");
+    const previousPath = process.env.ZAIP_SQLITE_DB_PATH;
+    const previousSeed = process.env.ZAIP_SQLITE_PREFER_LAST_VALID_SEED;
+    try {
+      process.env.ZAIP_SQLITE_DB_PATH = join(root, ".local", "dashboard-sqlite", "next.sqlite");
+      process.env.ZAIP_SQLITE_PREFER_LAST_VALID_SEED = "1";
+      await expect(rebuildSqliteReadModel(root)).resolves.toMatchObject({
+        cache: "stale_seed",
+        files: 2,
+      });
+      const served = new SqliteReadModelFileSystem(root);
+      try {
+        expect(served.firstFoldAllTime()).toBeDefined();
+        expect(served.firstFoldBoardAllTime()).toBeDefined();
+      } finally {
+        served.close();
+      }
+    } finally {
+      if (previousPath === undefined) delete process.env.ZAIP_SQLITE_DB_PATH;
+      else process.env.ZAIP_SQLITE_DB_PATH = previousPath;
+      if (previousSeed === undefined) delete process.env.ZAIP_SQLITE_PREFER_LAST_VALID_SEED;
+      else process.env.ZAIP_SQLITE_PREFER_LAST_VALID_SEED = previousSeed;
+    }
+  });
+
+  it("rejects a seed whose board payload is truncated below canonical work", async () => {
+    const root = await mkdtemp(join(tmpdir(), "zaip-snapshot-truncated-"));
+    roots.push(root);
+    await mkdir(join(root, ".agents", "records", "tasks"), { recursive: true });
+    await mkdir(join(root, ".agents", "config"), { recursive: true });
+    await writeFile(join(root, ".agents", "config", "project.yaml"), "zaip:\n  enabled: true\n");
+    await writeFile(
+      join(root, ".agents", "records", "tasks", "task.md"),
+      "---\nid: TASK-SEED-POPULATION\ntitle: Seed population\nstatus: ready\nrisk: standard\ncreated_at: 2026-08-01T12:00:00.000Z\n---\n# Seed population\n",
+    );
+    await rebuildSqliteReadModel(root);
+    const seed = join(
+      root,
+      ".local",
+      "dashboard-sqlite",
+      "cache",
+      (await readdir(join(root, ".local", "dashboard-sqlite", "cache"))).find((name) =>
+        name.endsWith(".sqlite"),
+      ) ?? "missing.sqlite",
+    );
+    const database = new DatabaseSync(seed);
+    try {
+      database
+        .prepare(
+          "UPDATE zaip_aios_activities SET payload_json=json_set(payload_json, '$.pages.task', json('[]')) WHERE payload_type='first_fold_all_time_board_cache'",
+        )
+        .run();
+      expect(hasRequiredFirstFoldPayloads(database)).toBe(false);
+    } finally {
+      database.close();
+    }
+  });
+
+  it("accepts a complete monthly payload when historical work was recorded on rebuild day", async () => {
+    const root = await mkdtemp(join(tmpdir(), "zaip-snapshot-monthly-day-"));
+    roots.push(root);
+    await mkdir(join(root, ".agents", "records", "tasks"), { recursive: true });
+    await mkdir(join(root, ".agents", "config"), { recursive: true });
+    await writeFile(join(root, ".agents", "config", "project.yaml"), "zaip:\n  enabled: true\n");
+    await writeFile(
+      join(root, ".agents", "records", "tasks", "historical-task.md"),
+      "---\nid: TASK-SEED-HISTORICAL\ntitle: Historical seed task\nstatus: ready\nrisk: standard\ncreated_at: 2026-07-01T12:00:00.000Z\n---\n# Historical seed task\n",
+    );
+    await rebuildSqliteReadModel(root);
+    const cacheDirectory = join(root, ".local", "dashboard-sqlite", "cache");
+    const seedName = (await readdir(cacheDirectory)).find((name) => name.endsWith(".sqlite"));
+    expect(seedName).toBeDefined();
+    if (seedName === undefined) throw new Error("Expected a complete SQLite seed");
+    const database = new DatabaseSync(join(cacheDirectory, seedName), { readOnly: true });
+    try {
+      expect(hasRequiredFirstFoldPayloads(database)).toBe(true);
+    } finally {
+      database.close();
+    }
+  });
+});

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

@@ -0,0 +1,146 @@
+import { createServer as createHttpServer } from "node:http";
+
+export async function createDashboardLaunchPage({ port, host, runtimeKind, healthPath, delay }) {
+  let redirectUrl = null;
+  let failure = 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;
+  });
+  let resolveFailureObserved;
+  const failureObserved = new Promise((resolveObserved) => {
+    resolveFailureObserved = resolveObserved;
+  });
+  const server = createHttpServer((request, response) => {
+    response.setHeader("Cache-Control", "no-store");
+    if (request.url?.startsWith("/api/v2/ready")) {
+      if (redirectUrl !== null) resolveRedirectObserved(true);
+      if (failure !== null) resolveFailureObserved(true);
+      response.writeHead(failure === null ? 200 : 503, {
+        "Content-Type": "application/json; charset=utf-8",
+      });
+      response.end(JSON.stringify({ target: redirectUrl, failure }));
+      return;
+    }
+    if (request.url?.startsWith("/api/v2/progress")) {
+      if (failure !== null) resolveFailureObserved(true);
+      response.writeHead(200, { "Content-Type": "application/json; charset=utf-8" });
+      response.end(JSON.stringify({ ...progress, failure }));
+      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:not(.handoff):not(.failure){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{position:relative;height:9px;margin-top:20px;border-radius:999px;background:#172033;overflow:hidden}.track::after{content:"";position:absolute;inset:0;background:linear-gradient(90deg,transparent 0%,rgba(224,242,254,.14) 35%,rgba(224,242,254,.8) 50%,rgba(224,242,254,.14) 65%,transparent 100%);transform:translateX(-100%);animation:launch-activity 1.35s ease-in-out infinite;pointer-events:none}.progress.terminal-failure .track::after{animation:none;transform:none;background:rgba(254,202,202,.2)}.bar{position:relative;z-index:1;height:100%;width:4%;border-radius:inherit;background:linear-gradient(90deg,#38bdf8,#818cf8);transition:width .35s ease}@keyframes launch-activity{to{transform:translateX(100%)}}@media (prefers-reduced-motion:reduce){.track::after{animation:none;transform:none;background:linear-gradient(90deg,transparent 0%,rgba(224,242,254,.2) 50%,transparent 100%)}}.handoff,.failure{display:none;margin-top:16px;color:#dbeafe}.failure{color:#fecaca}
+  </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" id="track" aria-label="Preparação em andamento"><div class="bar" id="bar"></div></div><span class="handoff" id="handoff">O dashboard está pronto. Abrindo a tela principal automaticamente…</span><span class="failure" id="failure" role="alert"></span></section>
+  </main>
+  <script>
+    let handoffTarget=null,progressRequestInFlight=false,terminalFailure=false;
+    function showHandoff(target){handoffTarget=target;document.getElementById("handoff").style.display="block";document.getElementById("phase").textContent="Dashboard pronto";document.getElementById("detail").textContent="Concluindo a abertura da tela principal."}
+    function showFailure(next){terminalFailure=true;clearInterval(progressPoll);document.getElementById("phase").textContent=next.phase;document.getElementById("detail").textContent="A preparação não foi concluída. Consulte a mensagem abaixo para agir.";document.getElementById("bar").style.width="100%";document.getElementById("handoff").style.display="none";document.getElementById("failure").textContent=next.detail;document.getElementById("failure").style.display="block";document.querySelector(".progress").classList.add("terminal-failure")}
+    async function updateProgress(){if(progressRequestInFlight||terminalFailure)return terminalFailure;progressRequestInFlight=true;try{const r=await fetch("/api/v2/progress",{cache:"no-store",signal:AbortSignal.timeout(1000)});const p=await r.json();if(terminalFailure)return true;if(p.failure){showFailure(p.failure);return true}if(!handoffTarget){document.getElementById("phase").textContent=p.phase;document.getElementById("detail").textContent=p.detail};if(!terminalFailure)document.getElementById("bar").style.width=Math.max(4,Math.min(100,Number(p.percent)||4))+"%"}catch{}finally{progressRequestInFlight=false}return terminalFailure}
+    const progressPoll=setInterval(updateProgress,250);
+    async function waitForDashboard(){try{if(await updateProgress())return;const ready=await fetch("/api/v2/ready",{cache:"no-store",signal:AbortSignal.timeout(1000)});const next=await ready.json();if(next.failure){showFailure(next.failure);return}if(next.target){showHandoff(next.target);clearInterval(progressPoll);setTimeout(()=>location.replace(next.target),0);return}const response=await fetch("${healthPath}",{cache:"no-store",signal:AbortSignal.timeout(1000)});const payload=await response.json();if(response.ok&&payload.kind==="${runtimeKind}"){clearInterval(progressPoll);location.reload();return}}catch{}setTimeout(waitForDashboard,250)}
+    updateProgress();setTimeout(waitForDashboard,100)
+    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),
+      };
+    },
+    setFailure: (next) => {
+      failure = { phase: next.phase, detail: next.detail };
+      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?.();
+    },
+    closeAfterFailureObservation: (graceMs = 12_000) => {
+      server.ref();
+      return Promise.race([failureObserved, delay(graceMs)]).then(
+        () =>
+          new Promise((resolveClosed) => {
+            setTimeout(() => {
+              server.closeAllConnections?.();
+              for (const connection of connections) connection.destroy();
+              void server.close(() => resolveClosed());
+            }, 250);
+          }),
+      );
+    },
+    close: ({ forceAfterMs = 750 } = {}) =>
+      new Promise((resolveClose, rejectClose) => {
+        if (!server.listening) {
+          resolveClose();
+          return;
+        }
+        let forceTimer = null;
+        const finish = (error) => {
+          if (forceTimer !== null) clearTimeout(forceTimer);
+          if (error) rejectClose(error);
+          else resolveClose();
+        };
+        server.close(finish);
+        forceTimer = setTimeout(() => {
+          server.closeAllConnections?.();
+          for (const connection of connections) connection.destroy();
+        }, forceAfterMs);
+        forceTimer.unref?.();
+      }),
+  };
+}

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

@@ -0,0 +1,165 @@
+import { connect } from "node:net";
+import { chromium } from "@playwright/test";
+import { describe, expect, it } from "vitest";
+import { host, startDashboardLaunchPage } from "./start-dashboard.mjs";
+
+describe("dashboard launch page", () => {
+  it("serves an accessible active progress overlay and an automatic handoff 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);
+      const html = await page.text();
+      expect(html).toContain('class="launch-overlay"');
+      expect(html).toContain("position:fixed;inset:0;width:100vw;height:100vh");
+      expect(html).toContain("display:grid;place-items:center");
+      expect(html).toContain('aria-live="polite" role="status"');
+      expect(html).toContain('aria-label="Preparação em andamento"');
+      expect(html).toContain("animation:launch-activity 1.35s ease-in-out infinite");
+      expect(html).toContain("@media (prefers-reduced-motion:reduce)");
+      expect(html).toContain("O dashboard está pronto. Abrindo a tela principal automaticamente…");
+      expect(html).not.toContain("abra o dashboard agora");
+      expect(html).not.toContain('id="handoff-link"');
+      expect(html).toContain("function showHandoff(target)");
+      const progress = await fetch(`http://${host}:${launchPage.port}/api/v2/progress`);
+      await expect(progress.json()).resolves.toMatchObject({
+        phase: "Iniciando o launcher local",
+        percent: expect.any(Number),
+      });
+      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",
+        failure: null,
+      });
+      await expect(launchPage.waitForRedirect(10)).resolves.toBe(true);
+    } finally {
+      await launchPage.close();
+    }
+  });
+
+  it("keeps the handoff hidden until a real handoff target exists while progress polling continues", async () => {
+    const launchPage = await startDashboardLaunchPage(0);
+    const browser = await chromium.launch();
+    try {
+      const page = await browser.newPage();
+      await page.route("**/api/v2/ready", (route) =>
+        route.fulfill({ contentType: "application/json", body: JSON.stringify({ target: null }) }),
+      );
+      await page.route("**/api/v2/health", () => new Promise(() => {}));
+      await page.goto(`http://${host}:${launchPage.port}/?token=temporary`);
+
+      await expect
+        .poll(() =>
+          page.locator("#handoff").evaluate((element) => getComputedStyle(element).display),
+        )
+        .toBe("none");
+      launchPage.setProgress({ percent: 64, phase: "Atualizando progresso independente" });
+      await expect
+        .poll(() => page.locator("#phase").textContent())
+        .toBe("Atualizando progresso independente");
+
+      await page.evaluate(() => window.showHandoff("http://127.0.0.1:4417/?token=ready"));
+      await expect
+        .poll(() =>
+          page.locator("#handoff").evaluate((element) => getComputedStyle(element).display),
+        )
+        .toBe("block");
+    } finally {
+      await browser.close();
+      await launchPage.close();
+    }
+  });
+
+  it("publishes a durable preparation failure without returning a false ready target", async () => {
+    const launchPage = await startDashboardLaunchPage(0);
+    const browser = await chromium.launch();
+    try {
+      launchPage.setFailure({
+        percent: 100,
+        phase: "Não foi possível preparar o dashboard",
+        detail: "A verificação local falhou.",
+      });
+      const ready = await fetch(`http://${host}:${launchPage.port}/api/v2/ready`);
+      expect(ready.status).toBe(503);
+      await expect(ready.json()).resolves.toEqual({
+        target: null,
+        failure: {
+          phase: "Não foi possível preparar o dashboard",
+          detail: "A verificação local falhou.",
+        },
+      });
+
+      const page = await browser.newPage();
+      await page.goto(`http://${host}:${launchPage.port}/?token=temporary`);
+      await expect
+        .poll(() => page.locator("#failure").textContent())
+        .toBe("A verificação local falhou.");
+      await expect
+        .poll(() =>
+          page.locator("#failure").evaluate((element) => getComputedStyle(element).display),
+        )
+        .toBe("block");
+      await expect
+        .poll(() =>
+          page.locator("#handoff").evaluate((element) => getComputedStyle(element).display),
+        )
+        .toBe("none");
+      await expect
+        .poll(() => page.locator("#phase").textContent())
+        .toBe("Não foi possível preparar o dashboard");
+      await expect
+        .poll(() => page.locator("#detail").textContent())
+        .toBe("A preparação não foi concluída. Consulte a mensagem abaixo para agir.");
+      await expect
+        .poll(() =>
+          page
+            .locator(".progress")
+            .evaluate((element) => element.classList.contains("terminal-failure")),
+        )
+        .toBe(true);
+      await expect
+        .poll(() =>
+          page
+            .locator("#track")
+            .evaluate((element) => getComputedStyle(element, "::after").animationName),
+        )
+        .toBe("none");
+      await expect
+        .poll(() => page.locator("#bar").evaluate((element) => getComputedStyle(element).width))
+        .not.toBe("4px");
+
+      await launchPage.closeAfterFailureObservation(0);
+      await expect
+        .poll(() => page.locator("#failure").textContent())
+        .toBe("A verificação local falhou.");
+    } finally {
+      await browser.close();
+      await launchPage.close();
+    }
+  });
+
+  it("bounds launch-page shutdown when a browser connection never finishes polling", async () => {
+    const launchPage = await startDashboardLaunchPage(0);
+    const connection = connect({ host, port: launchPage.port });
+    await new Promise((resolveConnected, rejectConnected) => {
+      connection.once("connect", resolveConnected);
+      connection.once("error", rejectConnected);
+    });
+    const closed = new Promise((resolveClosed) => connection.once("close", resolveClosed));
+    const startedAt = Date.now();
+    await launchPage.close({ forceAfterMs: 20 });
+    await closed;
+
+    expect(Date.now() - startedAt).toBeLessThan(500);
+    expect(connection.destroyed).toBe(true);
+  });
+});