@zaip-ai/cli 1.3.2 → 1.3.4

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

@@ -0,0 +1,81 @@
+import { EventEmitter } from "node:events";
+import { describe, expect, it } from "vitest";
+
+import {
+  awaitOwnedDashboardExit,
+  createPhaseTimer,
+  presentLaunchFailure,
+} from "./start-dashboard-lifecycle.mjs";
+
+describe("dashboard launcher lifecycle", () => {
+  it("reports the existing failure state and closes the preparation page", () => {
+    const calls = [];
+    const launchPage = {
+      setFailure: (failure) => calls.push(["failure", failure]),
+      closeAfterFailureObservation: () => calls.push(["close"]),
+    };
+
+    expect(
+      presentLaunchFailure(
+        launchPage,
+        new Error("boom"),
+        (message, limit) => `${limit}:${message}`,
+      ),
+    ).toBeNull();
+    expect(calls).toEqual([
+      [
+        "failure",
+        {
+          percent: 100,
+          phase: "Não foi possível preparar o dashboard",
+          detail: "900:boom",
+        },
+      ],
+      ["close"],
+    ]);
+    expect(presentLaunchFailure(null, "unused", () => "unused")).toBeNull();
+  });
+
+  it("waits for the child exit before clearing the owned session", async () => {
+    const child = new EventEmitter();
+    const processRef = new EventEmitter();
+    const calls = [];
+    child.kill = (signal) => calls.push(["kill", signal]);
+    const completion = awaitOwnedDashboardExit({
+      child,
+      currentSession: { dbPath: "C:/tmp/dashboard.sqlite" },
+      clearOwnedDashboardSession: async () => calls.push(["clear"]),
+      recordPortStatus: async (_session, status) => calls.push(["status", status]),
+      removeGeneratedReadModel: async (path) => calls.push(["remove", path]),
+      processRef,
+    });
+
+    expect(calls).toEqual([]);
+    processRef.emit("SIGINT");
+    child.emit("exit", null);
+
+    await expect(completion).resolves.toBe(0);
+    expect(calls).toEqual([
+      ["kill", "SIGINT"],
+      ["clear"],
+      ["status", "closed"],
+      ["remove", "C:/tmp/dashboard.sqlite"],
+    ]);
+  });
+
+  it("records launcher phase timing with the same process identity", () => {
+    const entries = [];
+    createPhaseTimer((entry) => entries.push(JSON.parse(entry)), 42)("ready", 1_000, {
+      port: 4417,
+    });
+
+    expect(entries).toEqual([
+      expect.objectContaining({
+        event: "dashboard_sqlite_phase",
+        phase: "ready",
+        launcher_pid: 42,
+        port: 4417,
+      }),
+    ]);
+  });
+});

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

@@ -19,6 +19,12 @@ 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 {
+  awaitOwnedDashboardExit,
+  createPhaseTimer,
+  presentLaunchFailure,
+  writeLauncherStatus,
+} from "./start-dashboard-lifecycle.mjs";
 import {
   isProcessAlive,
   stopOwnedDashboardProcess,
@@ -62,18 +68,66 @@ const healthPath = "/api/v2/health";
 const lockTimeoutMs = 210_000;
 const staleLockMs = 30_000;
 const lockHeartbeatFloorMs = 10;
-// A cold immutable seed can legitimately take ~176 s on a busy Windows
-// volume. Keep the immediate preparation page and fresh-port handoff, but do
-// not kill that one-time canonical build before it can populate the cache.
-const startupTimeoutMs = 180_000;
 const maxServerStartAttempts = 4;
 const maxPortHistory = 50;
-const dashboardSourceRoots = [
-  resolve(workspaceRoot, ".agents/dashboard/apps/frontend/src"),
-  resolve(workspaceRoot, ".agents/dashboard/modules"),
-  resolve(workspaceRoot, ".agents/dashboard/packages/ui/src"),
-  resolve(packageRoot, "src"),
-];
+// Keep each build invalidation scoped to the artifact it can actually change.
+// The runtime bundle includes the server-side dashboard modules, workspace
+// packages, settings and build scripts. Browser-only changes never rebuild it.
+export const dashboardBuildTargets = {
+  frontend: {
+    artifacts: [resolve(frontendRoot, "index.html")],
+    sourceRoots: [
+      resolve(workspaceRoot, ".agents/dashboard/apps/frontend/src"),
+      resolve(workspaceRoot, ".agents/dashboard/apps/frontend/public"),
+      resolve(workspaceRoot, ".agents/dashboard/apps/frontend/index.html"),
+      resolve(workspaceRoot, ".agents/dashboard/modules/operations/src"),
+      resolve(workspaceRoot, ".agents/dashboard/modules/cost-monitor/src"),
+      resolve(workspaceRoot, ".agents/dashboard/modules/traceability/src"),
+      resolve(workspaceRoot, ".agents/dashboard/modules/operations/src/contracts.ts"),
+      resolve(workspaceRoot, ".agents/dashboard/modules/cost-monitor/src/contracts.ts"),
+      resolve(workspaceRoot, ".agents/dashboard/modules/traceability/src/contracts.ts"),
+      resolve(workspaceRoot, ".agents/dashboard/packages/contracts/src"),
+      resolve(workspaceRoot, ".agents/dashboard/packages/ui/src"),
+      resolve(workspaceRoot, ".agents/dashboard/apps/frontend/vite.config.ts"),
+      resolve(workspaceRoot, ".agents/dashboard/apps/frontend/package.json"),
+      resolve(workspaceRoot, ".agents/dashboard/apps/frontend/tsconfig.json"),
+      resolve(workspaceRoot, "tsconfig.base.json"),
+      resolve(workspaceRoot, "pnpm-lock.yaml"),
+      resolve(workspaceRoot, "README.md"),
+    ],
+    excludedSourcePaths: ["/server/"],
+  },
+  runtime: {
+    artifacts: [
+      sourceServer,
+      resolve(packageRoot, "dist/server.js"),
+      resolve(packageRoot, "dist/sqlite-read-model.cjs"),
+      installedServer,
+    ],
+    sourceRoots: [
+      resolve(packageRoot, "src"),
+      resolve(packageRoot, "scripts"),
+      resolve(packageRoot, "package.json"),
+      resolve(packageRoot, "tsconfig.json"),
+      resolve(workspaceRoot, ".agents/dashboard/modules/operations/src"),
+      resolve(workspaceRoot, ".agents/dashboard/modules/cost-monitor/src"),
+      resolve(workspaceRoot, ".agents/dashboard/modules/traceability/src"),
+      resolve(workspaceRoot, ".agents/dashboard/packages/contracts/src"),
+      resolve(workspaceRoot, ".agents/dashboard/packages/data-export/src"),
+      resolve(workspaceRoot, "packages/core/src"),
+      resolve(workspaceRoot, "packages/costs/src"),
+      resolve(workspaceRoot, "packages/decisions/src"),
+      resolve(workspaceRoot, "packages/lifecycle-manifests/src"),
+      resolve(workspaceRoot, "packages/specs/src"),
+      resolve(workspaceRoot, "packages/tasks/src"),
+      resolve(workspaceRoot, "package.json"),
+      resolve(workspaceRoot, "pnpm-workspace.yaml"),
+      resolve(workspaceRoot, "pnpm-lock.yaml"),
+      resolve(workspaceRoot, "tsconfig.base.json"),
+    ],
+    excludedSourcePaths: ["/react/"],
+  },
+};
 export function preferredPort(value = process.env.ZAIP_SERVER_PORT) {
   const parsed = Number.parseInt(value ?? "", 10);
   return Number.isInteger(parsed) && parsed > 0 && parsed <= 65_535 ? parsed : defaultPort;
@@ -263,25 +317,40 @@ export async function findReusableDashboardSession({
 async function backgroundRefreshIsRunning() {
   return refreshIsRunning(join(sessionDirectory, "dashboard-sqlite-refresh.json"), isProcessAlive);
 }
-async function latestModifiedAt(paths) {
+export async function latestModifiedAt(paths, excludedSourcePaths = []) {
   let latest = 0;
   for (const path of paths) {
     const details = await stat(path).catch(() => null);
     if (details === null) continue;
-    latest = Math.max(latest, details.mtimeMs);
-    if (!details.isDirectory()) continue;
+    if (!details.isDirectory()) {
+      if (isBuildInputPath(path, excludedSourcePaths)) latest = Math.max(latest, details.mtimeMs);
+      continue;
+    }
+    // Retain included directory mtimes so removing or renaming a source file
+    // after a build still invalidates its artifact. Excluded trees stay out.
+    if (isBuildInputPath(path, excludedSourcePaths)) latest = Math.max(latest, details.mtimeMs);
     const entries = await readdir(path, { withFileTypes: true }).catch(() => []);
     latest = Math.max(
       latest,
       await latestModifiedAt(
         entries
-          .filter((entry) => !new Set(["dist", "node_modules", ".turbo"]).has(entry.name))
+          .filter((entry) => isBuildInputPath(join(path, entry.name), excludedSourcePaths))
           .map((entry) => join(path, entry.name)),
+        excludedSourcePaths,
       ),
     );
   }
   return latest;
 }
+function isBuildInputPath(path, excludedSourcePaths) {
+  const normalized = path.replaceAll("\\", "/");
+  const name = normalized.slice(normalized.lastIndexOf("/") + 1);
+  if (new Set(["dist", "node_modules", ".turbo"]).has(name)) return false;
+  if (/\.(?:test|spec)\.[cm]?[jt]sx?$/.test(name)) return false;
+  return !excludedSourcePaths.some(
+    (excluded) => normalized.includes(excluded) || normalized.endsWith(excluded.slice(0, -1)),
+  );
+}
 async function runSqliteBuild(target) {
   const frontend = target === "frontend";
   const command = process.execPath;
@@ -320,17 +389,75 @@ async function runSqliteBuild(target) {
   });
   return output;
 }
-async function ensureFreshDashboardBuild() {
-  const artifacts = [resolve(frontendRoot, "index.html"), sourceServer];
-  const [sourcesModifiedAt, artifactsModifiedAt] = await Promise.all([
-    latestModifiedAt(dashboardSourceRoots),
-    latestModifiedAt(artifacts),
-  ]);
-  const forceRebuild = process.env.ZAIP_DASHBOARD_FORCE_REBUILD === "1";
-  if (forceRebuild || artifactsModifiedAt < sourcesModifiedAt) {
-    await runSqliteBuild("frontend");
-    await runSqliteBuild("runtime");
+export async function inspectDashboardBuildTarget(target) {
+  const artifactStats = await Promise.all(
+    target.artifacts.map(async (path) => ({ path, details: await stat(path).catch(() => null) })),
+  );
+  const missingArtifacts = artifactStats
+    .filter(({ details }) => details === null)
+    .map(({ path }) => path);
+  const artifactsModifiedAt = Math.min(
+    ...artifactStats.map(({ details }) => details?.mtimeMs ?? 0),
+  );
+  const sourcesModifiedAt = await latestModifiedAt(target.sourceRoots, target.excludedSourcePaths);
+  return { artifactsModifiedAt, missingArtifacts, sourcesModifiedAt };
+}
+function buildProgress(onProgress, percent, phase, detail) {
+  onProgress({ percent, phase, detail });
+}
+export async function refreshDashboardBuildTargets({
+  targets = dashboardBuildTargets,
+  forceRebuild = process.env.ZAIP_DASHBOARD_FORCE_REBUILD === "1",
+  inspectTarget = inspectDashboardBuildTarget,
+  runBuild = runSqliteBuild,
+  onProgress = () => {},
+} = {}) {
+  const builtTargets = [];
+  for (const [name, target] of Object.entries(targets)) {
+    buildProgress(
+      onProgress,
+      name === "frontend" ? 30 : 35,
+      `Verificando ${name === "frontend" ? "a interface" : "o runtime local"}`,
+      "Conferindo somente as dependências que geram este artefato.",
+    );
+    const state = await inspectTarget(target);
+    const needsBuild =
+      forceRebuild ||
+      state.missingArtifacts.length > 0 ||
+      state.artifactsModifiedAt < state.sourcesModifiedAt;
+    if (!needsBuild) {
+      buildProgress(
+        onProgress,
+        name === "frontend" ? 33 : 39,
+        `${name === "frontend" ? "Interface" : "Runtime local"} já está atualizado`,
+        "O artefato existente corresponde às dependências verificadas.",
+      );
+      continue;
+    }
+    const reason = forceRebuild
+      ? "A atualização foi solicitada explicitamente."
+      : state.missingArtifacts.length > 0
+        ? "Um artefato necessário está ausente."
+        : "Uma dependência deste artefato foi modificada.";
+    buildProgress(
+      onProgress,
+      name === "frontend" ? 33 : 39,
+      `Atualizando ${name === "frontend" ? "a interface" : "o runtime local"}`,
+      reason,
+    );
+    await runBuild(name);
+    builtTargets.push(name);
+    buildProgress(
+      onProgress,
+      name === "frontend" ? 35 : 42,
+      `${name === "frontend" ? "Interface" : "Runtime local"} atualizado`,
+      "O artefato foi gerado com as dependências atuais.",
+    );
   }
+  return { artifacts: Object.values(targets).flatMap((target) => target.artifacts), builtTargets };
+}
+async function ensureFreshDashboardBuild(onProgress = () => {}) {
+  const { artifacts } = await refreshDashboardBuildTargets({ onProgress });
   const artifactFingerprint = await Promise.all(
     [...artifacts, resolve(packageRoot, "start-dashboard.mjs")].map(async (path) => {
       const details = await stat(path);
@@ -481,6 +608,11 @@ export function startDashboardLaunchPage(port) {
   return createDashboardLaunchPage({ port, host, runtimeKind, healthPath, delay });
 }
 async function redirectLaunchPage(launchPage, target) {
+  launchPage.setProgress({
+    percent: 100,
+    phase: "Dashboard pronto",
+    detail: "A tela principal está pronta para abrir.",
+  });
   launchPage.redirect(target);
   const redirected =
     process.env.ZAIP_UI_NO_BROWSER === "1" ? true : await launchPage.waitForRedirect();
@@ -699,30 +831,13 @@ async function refreshSnapshotSeedInBackground() {
     writeJsonAtomic,
   });
 }
-async function writeLauncherStatus(status, message = "") {
-  const path = process.env.ZAIP_LAUNCH_STATUS;
-  if (!path) return;
-  const temporaryPath = `${path}.${process.pid}.tmp`;
-  await writeFile(temporaryPath, `${status}\n${message}`.trimEnd(), "utf8");
-  await rename(temporaryPath, path);
-}
-function phaseTiming(phase, startedAt, details = {}) {
-  appendLauncherLog(
-    JSON.stringify({
-      event: "dashboard_sqlite_phase",
-      phase,
-      elapsed_ms: Date.now() - startedAt,
-      launcher_pid: process.pid,
-      ...details,
-    }),
-  );
-}
 async function main() {
   let ownedChild = null;
   let currentSession = null;
   let launchPage = null;
   const token = process.env.ZAIP_UI_TOKEN ?? randomBytes(24).toString("base64url");
   const launchStartedAt = Date.now();
+  const phaseTiming = createPhaseTimer(appendLauncherLog, process.pid);
   // Bind the preparation page atomically on an ephemeral port before waiting
   // for the launch lock.  Looking up a free port and binding it later lets a
   // concurrent preparation page claim that port, which makes the runtime
@@ -755,7 +870,9 @@ async function main() {
           phase: "Verificando os artefatos do dashboard",
           detail: "Usando o build existente quando ele já está atualizado.",
         });
-        const buildSignature = await ensureFreshDashboardBuild();
+        const buildSignature = await ensureFreshDashboardBuild((progress) =>
+          launchPage?.setProgress(progress),
+        );
         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;
@@ -892,31 +1009,17 @@ async function main() {
       },
     );
   } catch (error) {
-    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;
-    }
+    launchPage = presentLaunchFailure(launchPage, error, formatLauncherError);
     throw error;
   }
   if (ownedChild === null) return;
-  for (const signal of ["SIGINT", "SIGTERM"]) {
-    process.once(signal, () => ownedChild?.kill(signal));
-  }
-  const exitCode = await new Promise((resolveExit, rejectExit) => {
-    ownedChild.once("error", rejectExit);
-    ownedChild.once("exit", (code) => resolveExit(code ?? 0));
+  process.exitCode = await awaitOwnedDashboardExit({
+    child: ownedChild,
+    currentSession,
+    clearOwnedDashboardSession,
+    recordPortStatus,
+    removeGeneratedReadModel,
   });
-  await clearOwnedDashboardSession();
-  if (currentSession !== null) {
-    await recordPortStatus(currentSession, "closed");
-    await removeGeneratedReadModel(currentSession.dbPath);
-  }
-  process.exitCode = exitCode;
 }
 function isPortFree(port) {
   return new Promise((resolvePort) => {
@@ -927,8 +1030,10 @@ function isPortFree(port) {
   });
 }
 async function waitForDashboard(port, child) {
-  const deadline = Date.now() + startupTimeoutMs;
-  while (Date.now() < deadline) {
+  // A cold SQLite read model has no meaningful fixed duration: canonical
+  // history and host disk speed both affect it. Keep request timeouts below,
+  // but wait for an observable failure instead of a wall-clock cutoff.
+  while (true) {
     if (child.exitCode !== null) {
       throw new Error(`Dashboard server exited before becoming healthy (${child.exitCode})`);
     }
@@ -962,11 +1067,6 @@ async function waitForDashboard(port, child) {
     }
     await delay(100);
   }
-  // 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(

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

@@ -1,5 +1,5 @@
 import { EventEmitter } from "node:events";
-import { mkdir, mkdtemp, readFile, rm, utimes } from "node:fs/promises";
+import { mkdir, mkdtemp, readFile, rm, utimes, writeFile } from "node:fs/promises";
 import { createServer } from "node:net";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
@@ -12,13 +12,16 @@ import {
   findReusableDashboardSession,
   formatLauncherError,
   host,
+  inspectDashboardBuildTarget,
   isAncestorProcess,
   isProcessAlive,
+  latestModifiedAt,
   openBrowser,
   previousDashboardSessions,
   probeDashboardPort,
   readPortRegistry,
   recordPortStatus,
+  refreshDashboardBuildTargets,
   registeredListenerMatches,
   runtimeKind,
   stopOwnedDashboardProcess,
@@ -92,11 +95,143 @@ describe("dashboard executable session", () => {
     expect(excludedPorts).toContain("launchPort,");
   });
 
+  it("checks directed build inputs, including missing roots and every required artifact", async () => {
+    const directory = await mkdtemp(join(tmpdir(), "zaip-dashboard-build-inputs-"));
+    temporaryDirectories.push(directory);
+    const inputDirectory = join(directory, "input");
+    const artifactDirectory = join(directory, "artifacts");
+    const source = join(inputDirectory, "source.ts");
+    const testSource = join(inputDirectory, "source.test.ts");
+    const removedSource = join(inputDirectory, "removed-source.ts");
+    const excludedDirectory = join(inputDirectory, "excluded");
+    const excludedSource = join(excludedDirectory, "shared.ts");
+    const olderArtifact = join(artifactDirectory, "older-artifact.js");
+    const newerArtifact = join(artifactDirectory, "newer-artifact.js");
+    await Promise.all([mkdir(inputDirectory), mkdir(artifactDirectory)]);
+    await Promise.all([
+      writeFile(source, "source"),
+      writeFile(testSource, "test"),
+      writeFile(removedSource, "removed"),
+      mkdir(excludedDirectory),
+      writeFile(olderArtifact, "older"),
+      writeFile(newerArtifact, "newer"),
+    ]);
+    await writeFile(excludedSource, "excluded");
+    const now = Date.now();
+    await Promise.all([
+      utimes(source, new Date(now), new Date(now)),
+      utimes(olderArtifact, new Date(now - 5_000), new Date(now - 5_000)),
+      utimes(newerArtifact, new Date(now + 5_000), new Date(now + 5_000)),
+      utimes(testSource, new Date(now + 10_000), new Date(now + 10_000)),
+      utimes(excludedSource, new Date(now + 10_000), new Date(now + 10_000)),
+    ]);
+
+    await expect(latestModifiedAt([join(directory, "missing-root")])).resolves.toBe(0);
+    await expect(latestModifiedAt([inputDirectory], ["/excluded/"])).resolves.toBeLessThan(
+      now + 5_000,
+    );
+    await expect(
+      inspectDashboardBuildTarget({
+        artifacts: [olderArtifact, newerArtifact, join(directory, "missing-artifact.js")],
+        sourceRoots: [source, join(directory, "missing-root")],
+      }),
+    ).resolves.toMatchObject({
+      artifactsModifiedAt: 0,
+      missingArtifacts: [join(directory, "missing-artifact.js")],
+      sourcesModifiedAt: expect.any(Number),
+    });
+    await expect(
+      inspectDashboardBuildTarget({
+        artifacts: [olderArtifact, newerArtifact],
+        sourceRoots: [source],
+      }),
+    ).resolves.toMatchObject({
+      artifactsModifiedAt: expect.any(Number),
+      missingArtifacts: [],
+      sourcesModifiedAt: expect.any(Number),
+    });
+    const state = await inspectDashboardBuildTarget({
+      artifacts: [olderArtifact, newerArtifact],
+      sourceRoots: [source],
+    });
+    expect(state.artifactsModifiedAt).toBeLessThan(state.sourcesModifiedAt);
+    await rm(removedSource);
+    const stateAfterRemoval = await inspectDashboardBuildTarget({
+      artifacts: [olderArtifact, newerArtifact],
+      sourceRoots: [inputDirectory],
+    });
+    expect(stateAfterRemoval.artifactsModifiedAt).toBeLessThan(stateAfterRemoval.sourcesModifiedAt);
+  });
+
+  it("keeps factual build milestones wired to the preparation page", async () => {
+    const source = await readFile(new URL("./start-dashboard.mjs", import.meta.url), "utf8");
+
+    expect(source).toContain("export const dashboardBuildTargets = {");
+    expect(source).toContain('resolve(workspaceRoot, "packages/core/src")');
+    expect(source).toContain('resolve(workspaceRoot, "packages/costs/src")');
+    expect(source).toContain('resolve(workspaceRoot, "packages/decisions/src")');
+    expect(source).toContain('resolve(workspaceRoot, "packages/lifecycle-manifests/src")');
+    expect(source).toContain('resolve(workspaceRoot, "packages/specs/src")');
+    expect(source).toContain('resolve(workspaceRoot, "packages/tasks/src")');
+    expect(source).toContain(
+      'resolve(workspaceRoot, ".agents/dashboard/packages/data-export/src")',
+    );
+    expect(source).toContain('resolve(workspaceRoot, ".agents/dashboard/packages/contracts/src")');
+    expect(source).toContain('resolve(workspaceRoot, "pnpm-lock.yaml")');
+    expect(source).toContain('resolve(packageRoot, "scripts")');
+    expect(source).toContain('excludedSourcePaths: ["/server/"]');
+    expect(source).toContain('excludedSourcePaths: ["/react/"]');
+    expect(source).toContain("if (/\\.(?:test|spec)\\.[cm]?[jt]sx?$/.test(name)) return false;");
+    expect(source).toContain("state.missingArtifacts.length > 0");
+    expect(source).toContain("Conferindo somente as dependências que geram este artefato.");
+    expect(source).toContain("launchPage?.setProgress(progress)");
+    expect(source).toContain("percent: 100,");
+  });
+
+  it("builds only the stale target and honors missing artifacts and an explicit force", async () => {
+    const targets = {
+      frontend: { artifacts: ["frontend-artifact"], sourceRoots: [] },
+      runtime: { artifacts: ["runtime-artifact"], sourceRoots: [] },
+    };
+    const fresh = { artifactsModifiedAt: 20, missingArtifacts: [], sourcesModifiedAt: 10 };
+    const stale = { artifactsModifiedAt: 10, missingArtifacts: [], sourcesModifiedAt: 20 };
+    const missing = {
+      artifactsModifiedAt: 0,
+      missingArtifacts: ["missing"],
+      sourcesModifiedAt: 10,
+    };
+    const verify = async (states, forceRebuild, expected) => {
+      const calls = [];
+      const progress = [];
+      const result = await refreshDashboardBuildTargets({
+        targets,
+        forceRebuild,
+        inspectTarget: async (target) => states[target.artifacts[0]],
+        runBuild: async (target) => calls.push(target),
+        onProgress: (event) => progress.push(event),
+      });
+      expect(calls).toEqual(expected);
+      expect(result.builtTargets).toEqual(expected);
+      expect(progress.every((event) => typeof event.phase === "string")).toBe(true);
+    };
+
+    await verify({ "frontend-artifact": fresh, "runtime-artifact": stale }, false, ["runtime"]);
+    await verify({ "frontend-artifact": stale, "runtime-artifact": fresh }, false, ["frontend"]);
+    await verify({ "frontend-artifact": fresh, "runtime-artifact": fresh }, false, []);
+    await verify({ "frontend-artifact": missing, "runtime-artifact": fresh }, false, ["frontend"]);
+    await verify({ "frontend-artifact": fresh, "runtime-artifact": fresh }, true, [
+      "frontend",
+      "runtime",
+    ]);
+  });
+
   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(");
     const preparation = source.indexOf("launchPage = await startDashboardLaunchPage(0);");
-    const freshness = source.indexOf("const buildSignature = await ensureFreshDashboardBuild();");
+    const freshness = source.indexOf(
+      "const buildSignature = await ensureFreshDashboardBuild((progress) =>",
+    );
     const server = source.indexOf(
       "const { child, port, dbPath, snapshotCache } = await startDashboardServer(",
     );
@@ -109,7 +244,7 @@ describe("dashboard executable session", () => {
     expect(redirectAfterServer).toBeGreaterThan(server);
   });
 
-  it("reports readiness failures as actionable without retrying a build storm", async () => {
+  it("reports real readiness failures without imposing a wall-clock limit on a cold rebuild", async () => {
     const source = await readFile(new URL("./start-dashboard.mjs", import.meta.url), "utf8");
     const wait = source.slice(
       source.indexOf("async function waitForDashboard"),
@@ -117,7 +252,8 @@ describe("dashboard executable session", () => {
     );
     expect(wait).toContain("Dashboard data readiness returned ${readiness.status}");
     expect(wait).toContain("unavailable.retryable = false;");
-    expect(wait).toContain("timedOut.retryable = false;");
+    expect(wait).toContain("while (true)");
+    expect(wait).not.toContain("startupTimeoutMs");
     expect(wait).toContain("if (error?.retryable === false) throw error;");
     expect(wait).toContain("await delay(100);");
   });
@@ -611,7 +747,7 @@ describe("dashboard executable session", () => {
     const preparation = source.indexOf("launchPage = await startDashboardLaunchPage(0);");
     const lock = source.indexOf("await withLauncherLock(");
     const buildSignature = source.indexOf(
-      "const buildSignature = await ensureFreshDashboardBuild();",
+      "const buildSignature = await ensureFreshDashboardBuild((progress) =>",
     );
     const reusable = source.indexOf("const reusable = await findReusableDashboardSession({");
 
@@ -624,8 +760,13 @@ describe("dashboard executable session", () => {
     expect(source).toContain(
       'snapshotState: snapshotCache === "stale_seed" ? "updating" : "current",',
     );
-    expect(source).toContain("launchPage.setFailure({");
-    expect(source).toContain("launchPage.closeAfterFailureObservation();");
+    expect(source).toContain("presentLaunchFailure(launchPage, error, formatLauncherError)");
+    const lifecycleSource = await readFile(
+      new URL("./start-dashboard-lifecycle.mjs", import.meta.url),
+      "utf8",
+    );
+    expect(lifecycleSource).toContain("launchPage.setFailure({");
+    expect(lifecycleSource).toContain("launchPage.closeAfterFailureObservation();");
     expect(source).toContain('await writeLauncherStatus("ok");');
   });
 
@@ -640,15 +781,15 @@ describe("dashboard executable session", () => {
     expect(beforeLock).not.toContain("findAvailablePortWithFallback(");
   });
 
-  it("gives the Windows wrapper margin beyond the bounded Node launcher wait", async () => {
+  it("keeps the Windows wrapper alive until Node reports success or a real failure", async () => {
     const source = await readFile(
       new URL("../windows-launcher/Program.cs", import.meta.url),
       "utf8",
     );
 
-    expect(source).toContain("DateTime.UtcNow.AddSeconds(420)");
-    expect(source).toContain("lock window (210 s)");
-    expect(source).toContain("bounded 180 s server");
+    expect(source).toContain("while (true)");
+    expect(source).toContain("process.HasExited");
+    expect(source).not.toContain("AddSeconds(420)");
   });
 });