@zaip-ai/cli 2.2.0 → 2.6.0

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

@@ -1,9 +1,88 @@
-import { spawn } from "node:child_process";
+import {
+  dashboardHealthUrl,
+  dashboardUrl,
+  findAvailablePortWithFallback,
+  openBrowser,
+  preferredPort,
+} from "./start-dashboard-navigation.mjs";
+
+export {
+  browserLaunchCommands,
+  dashboardHealthUrl,
+  dashboardUrl,
+  findAvailablePort,
+  findAvailablePortWithFallback,
+  openBrowser,
+  preferredPort,
+} from "./start-dashboard-navigation.mjs";
+
+import {
+  dashboardServerPathForWorkspace,
+  ensureFreshDashboardBuild,
+} from "./start-dashboard-build.mjs";
+import {
+  appendLauncherLog,
+  formatLauncherError,
+  stripTerminalControlCodes,
+} from "./start-dashboard-logging.mjs";
+import {
+  claimLockPath,
+  claimLockStaleMs,
+  claimLockTimeoutMs,
+  frontendRoot,
+  healthPath,
+  host,
+  launchPath,
+  lockHeartbeatFloorMs,
+  lockPath,
+  lockTimeoutMs,
+  maxPortAttempts,
+  maxPortHistory,
+  maxServerStartAttempts,
+  nodeCompileCacheDirectory,
+  packageRoot,
+  portRegistryPath,
+  runtimeKind,
+  sessionDirectory,
+  sessionPath,
+  sqliteReadModelPath,
+  staleLockMs,
+  workspaceKey,
+  workspaceRoot,
+} from "./start-dashboard-paths.mjs";
+
+export {
+  dashboardServerPathForWorkspace,
+  inspectDashboardBuildTarget,
+  isDashboardSourceWorkspace,
+  latestModifiedAt,
+  refreshDashboardBuildTargets,
+} from "./start-dashboard-build.mjs";
+export {
+  appendLauncherLog,
+  formatLauncherError,
+  stripTerminalControlCodes,
+} from "./start-dashboard-logging.mjs";
+export {
+  dashboardBuildTargets,
+  defaultPort,
+  host,
+  launcherLogPath,
+  launchPath,
+  lockPath,
+  maxPortAttempts,
+  portRegistryPath,
+  runtimeKind,
+  sessionDirectory,
+  sessionPath,
+  workspaceKey,
+  workspaceRoot,
+} from "./start-dashboard-paths.mjs";
+
 import { createHash, randomBytes } from "node:crypto";
-import { appendFileSync, mkdirSync } from "node:fs";
-import { mkdir, readdir, readFile, rename, rm, stat, utimes, writeFile } from "node:fs/promises";
+import { mkdir, readFile, rename, rm, stat, utimes, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
-import { dirname, join, resolve, win32 } from "node:path";
+import { dirname, join, resolve } from "node:path";
 import process from "node:process";
 import { fileURLToPath } from "node:url";
 import { collectPreviousDashboardSessions } from "./start-dashboard-history.mjs";
@@ -22,15 +101,7 @@ import {
   stopProcessTree,
   teardownWarning,
 } from "./start-dashboard-processes.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";
+import { startDashboardServer as launchDashboardServer } from "./start-dashboard-server.mjs";
 
 export {
   isAncestorProcess,
@@ -39,144 +110,19 @@ export {
   stopOwnedDashboardProcess,
   teardownWarning,
 } from "./start-dashboard-processes.mjs";
-export const host = "127.0.0.1";
-export const defaultPort = 4417;
-export const maxPortAttempts = 25;
-export const runtimeKind = "zaip-dashboard-sqlite-runtime";
-const packageRoot = dirname(fileURLToPath(import.meta.url));
-export const workspaceRoot = resolve(packageRoot, "../../../..");
-export const workspaceKey = createHash("sha256")
-  .update(`${workspaceRoot}:dashboard-sqlite`)
-  .digest("hex")
-  .slice(0, 16);
-export const 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", "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";
+
 // Keep the preparation lock through a full build so concurrent clicks coalesce safely.
-const lockTimeoutMs = 210_000;
-const staleLockMs = 30_000;
-const lockHeartbeatFloorMs = 10;
-const maxServerStartAttempts = 4;
-const maxPortHistory = 50;
+
 // 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;
-}
-export function dashboardHealthUrl(port) {
-  return `http://${host}:${port}${healthPath}`;
-}
-export function dashboardUrl(port, token, snapshotUpdating = false) {
-  return `http://${host}:${port}/?token=${encodeURIComponent(token)}${snapshotUpdating ? "&snapshot=updating" : ""}`;
-}
-export function appendLauncherLog(message) {
-  try {
-    mkdirSync(sessionDirectory, { recursive: true });
-    appendFileSync(
-      launcherLogPath,
-      `[${new Date().toISOString()}] ${stripTerminalControlCodes(message)}\n`,
-      "utf8",
-    );
-  } catch {
-    // Best-effort diagnostics must not hide the launcher failure.
-  }
-}
-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(operatingSystemCommand, "")
-    .replace(controlSequenceIntroducer, "")
-    .replace(/\r/g, "")
-    .trim();
-}
-export function formatLauncherError(value, maximumLength = 3_600) {
-  const message = stripTerminalControlCodes(value);
-  if (message.length <= maximumLength) return message;
-  const firstHalf = Math.floor(maximumLength / 2);
-  const lastHalf = maximumLength - firstHalf;
-  return `${message.slice(0, firstHalf)}\n\n… detalhes reduzidos; consulte o log temporário …\n\n${message.slice(-lastHalf)}`;
-}
 
 export async function readDashboardSession(path = sessionPath) {
   try {
@@ -413,7 +359,6 @@ export async function findReusableDashboardSession({
   const port = matches.find((candidate) => candidate !== null);
   return port === undefined ? null : { ...session, port };
 }
-
 export function requestBackgroundProjectionRefresh(session, fetchImpl = fetch) {
   return fetchImpl(`http://${host}:${session.port}/api/v2/refresh-projection`, {
     method: "POST",
@@ -422,182 +367,6 @@ export function requestBackgroundProjectionRefresh(session, fetchImpl = fetch) {
   }).catch(() => undefined);
 }
 
-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;
-    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) => 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;
-  const args = frontend
-    ? [resolve(workspaceRoot, "node_modules/vite/bin/vite.js"), "build"]
-    : [
-        resolve(
-          workspaceRoot,
-          ".agents/dashboard/packages/local-runtime/scripts/build-sqlite-runtime.mjs",
-        ),
-      ];
-  const output = await new Promise((resolveBuild, rejectBuild) => {
-    const child = spawn(command, args, {
-      cwd: frontend ? resolve(workspaceRoot, ".agents/dashboard/apps/frontend") : packageRoot,
-      windowsHide: true,
-      stdio: "pipe",
-    });
-    let outputText = "";
-    const appendOutput = (chunk) => {
-      outputText = `${outputText}${chunk}`.slice(-8_000);
-    };
-    child.stdout?.setEncoding("utf8");
-    child.stdout?.on("data", appendOutput);
-    child.stderr?.setEncoding("utf8");
-    child.stderr?.on("data", appendOutput);
-    child.once("error", rejectBuild);
-    child.once("exit", (code) => {
-      if (code === 0) resolveBuild();
-      else
-        rejectBuild(
-          new Error(
-            `SQLite dashboard ${target} build failed (${code}): ${formatLauncherError(outputText)}`,
-          ),
-        );
-    });
-  });
-  return output;
-}
-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 = () => {}) {
-  if (!(await hasDashboardSourceWorkspace(workspaceRoot))) {
-    const packagedArtifacts = [installedServer, resolve(frontendRoot, "index.html")];
-    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(
-    [...artifacts, resolve(packageRoot, "start-dashboard.mjs")].map(async (path) => {
-      const details = await stat(path);
-      return `${path}:${details.size}:${details.mtimeMs}`;
-    }),
-  );
-  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,
   {
@@ -652,104 +421,7 @@ export async function withLauncherLock(
   }
   throw new Error("Timed out waiting for the ZAIP dashboard launcher lock");
 }
-export async function findAvailablePort(startPort = preferredPort()) {
-  for (let port = startPort; port < Math.min(startPort + maxPortAttempts, 65_536); port += 1) {
-    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)}`,
-  );
-}
-export async function findAvailablePortWithFallback({
-  preferred = preferredPort(),
-  excludedPorts = [],
-} = {}) {
-  const excluded = new Set(excludedPorts.filter(Number.isInteger));
-  const fallbackStarts = [preferred, defaultPort + 1_000, defaultPort + 4_000].filter(
-    (port, index, ports) => port <= 65_535 && ports.indexOf(port) === index,
-  );
-  for (const startPort of fallbackStarts) {
-    for (let port = startPort; port < Math.min(startPort + maxPortAttempts, 65_536); port += 1) {
-      if (!excluded.has(port) && (await isPortFree(host, port))) return port;
-    }
-  }
-  for (let attempt = 0; attempt < 5; attempt += 1) {
-    const ephemeralPort = await findEphemeralPort();
-    if (!excluded.has(ephemeralPort)) return ephemeralPort;
-  }
-  throw new Error(
-    "No free dashboard port was found in the preferred, fallback, or ephemeral ranges",
-  );
-}
-async function findEphemeralPort() {
-  return new Promise((resolvePort, rejectPort) => {
-    const server = createServer();
-    server.unref();
-    server.once("error", rejectPort);
-    server.listen({ host, port: 0 }, () => {
-      const address = server.address();
-      const port = typeof address === "object" && address !== null ? address.port : null;
-      server.close(() => {
-        if (Number.isInteger(port)) resolvePort(port);
-        else rejectPort(new Error("The operating system did not allocate an ephemeral port"));
-      });
-    });
-  });
-}
-export function browserLaunchCommands(
-  target,
-  platform = process.platform,
-  environment = process.env,
-) {
-  if (platform === "win32") {
-    const systemRoot = environment.SystemRoot ?? "C:\\Windows";
-    return [
-      [
-        win32.resolve(systemRoot, "System32", "rundll32.exe"),
-        ["url.dll,FileProtocolHandler", target],
-      ],
-      [
-        environment.ComSpec ?? win32.resolve(systemRoot, "System32", "cmd.exe"),
-        ["/d", "/c", "start", "", target],
-      ],
-    ];
-  }
-  return platform === "darwin"
-    ? [["open", [target]]]
-    : [
-        ["xdg-open", [target]],
-        ["gio", ["open", target]],
-      ];
-}
-export async function openBrowser(target, spawnImpl = spawn) {
-  if (process.env.ZAIP_UI_NO_BROWSER === "1") return true;
-  const commands = browserLaunchCommands(target);
-  for (const [command, args] of commands) {
-    const launched = await new Promise((resolveLaunch) => {
-      let settled = false;
-      const settle = (value) => {
-        if (settled) return;
-        settled = true;
-        resolveLaunch(value);
-      };
-      try {
-        const browser = spawnImpl(command, args, {
-          detached: true,
-          stdio: "ignore",
-          windowsHide: true,
-        });
-        browser.once("spawn", () => settle(true));
-        browser.once("error", () => settle(false));
-        browser.unref();
-      } catch {
-        settle(false);
-      }
-    });
-    if (launched) return true;
-  }
-  appendLauncherLog(`Could not dispatch the dashboard URL to the default browser: ${target}`);
-  return false;
-}
+
 export function startDashboardLaunchPage(port) {
   return createDashboardLaunchPage({ port, host, runtimeKind, healthPath, delay });
 }
@@ -839,7 +511,6 @@ async function startDashboardServer(
     appendLog: appendLauncherLog,
   });
 }
-
 async function main() {
   let ownedChild = null;
   let currentSession = null;

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

@@ -42,7 +42,7 @@ afterEach(async () => {
 
 describe("dashboard executable session", () => {
   it("imports teardown bindings for the launcher implementation", async () => {
-    const source = await readFile(new URL("./start-dashboard.mjs", import.meta.url), "utf8");
+    const source = await readLauncherComposition();
 
     expect(source).toContain("stopProcessTree,");
     expect(source).toContain("teardownWarning,");
@@ -56,7 +56,7 @@ describe("dashboard executable session", () => {
   });
 
   it("shows preparation before validating dashboard prerequisites", async () => {
-    const source = await readFile(new URL("./start-dashboard.mjs", import.meta.url), "utf8");
+    const source = await readLauncherComposition();
 
     expect(source).toContain('from "./start-dashboard-prerequisites.mjs";');
     expect(source).toContain("await assertDashboardPrerequisites(workspaceRoot);");
@@ -74,7 +74,7 @@ describe("dashboard executable session", () => {
   });
 
   it("makes the newest executable click replace a healthy runtime instead of reusing it", async () => {
-    const source = await readFile(new URL("./start-dashboard.mjs", import.meta.url), "utf8");
+    const source = await readLauncherComposition();
     expect(source).toContain("newestClickWins: true,");
     expect(source).toContain("const previousSessions = await previousDashboardSessions();");
     expect(source).toContain("await stopOwnedDashboard(previous);");
@@ -157,7 +157,7 @@ describe("dashboard executable session", () => {
   });
 
   it("keeps factual build milestones wired to the preparation page", async () => {
-    const source = await readFile(new URL("./start-dashboard.mjs", import.meta.url), "utf8");
+    const source = await readLauncherComposition();
 
     expect(source).toContain("export const dashboardBuildTargets = {");
     expect(source).toContain('resolve(workspaceRoot, "packages/core/src")');
@@ -219,7 +219,7 @@ describe("dashboard executable session", () => {
   });
 
   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 source = await readLauncherComposition();
     const lock = source.indexOf("await withLauncherLock(");
     const preparation = source.indexOf("launchPage = await startDashboardLaunchPage(0);");
     const freshness = source.indexOf(
@@ -238,7 +238,7 @@ describe("dashboard executable session", () => {
   });
 
   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 source = await readLauncherComposition();
     const wait = source.slice(
       source.indexOf("async function waitForDashboard"),
       source.indexOf("function exists"),
@@ -263,7 +263,7 @@ describe("dashboard executable session", () => {
   });
 
   it("uses the official persistent database without reusing a previous runtime", async () => {
-    const source = await readFile(new URL("./start-dashboard.mjs", import.meta.url), "utf8");
+    const source = await readLauncherComposition();
     expect(source).toContain(
       'const sqliteReadModelDirectory = resolve(workspaceRoot, ".local", "sqlite");',
     );
@@ -305,7 +305,7 @@ describe("dashboard executable session", () => {
   });
 
   it("tears down prior owned sessions before the newest generation starts", async () => {
-    const source = await readFile(new URL("./start-dashboard.mjs", import.meta.url), "utf8");
+    const source = await readLauncherComposition();
     const server = source.indexOf(
       "const { child, port, dbPath, snapshotCache } = await startDashboardServer(",
     );
@@ -388,7 +388,7 @@ describe("dashboard executable session", () => {
   });
 
   it("publishes ok only after Node observed both health and readiness", async () => {
-    const source = await readFile(new URL("./start-dashboard.mjs", import.meta.url), "utf8");
+    const source = await readLauncherComposition();
     const wait = source.slice(
       source.indexOf("async function waitForDashboard"),
       source.indexOf("function exists"),
@@ -402,7 +402,7 @@ describe("dashboard executable session", () => {
   });
 
   it("records prior-port cleanup warnings while still publishing an ok handoff", async () => {
-    const source = await readFile(new URL("./start-dashboard.mjs", import.meta.url), "utf8");
+    const source = await readLauncherComposition();
     const cleanup = source.indexOf("const status = await stopOwnedDashboard(previous);");
     const warning = source.indexOf("Dashboard launched on port ${port}; prior-port cleanup:");
     const success = source.indexOf('await writeLauncherStatus("ok");', cleanup);
@@ -731,7 +731,7 @@ describe("dashboard executable session", () => {
   });
 
   it("opens preparation before the newest-click lock and then starts a new generation", async () => {
-    const source = await readFile(new URL("./start-dashboard.mjs", import.meta.url), "utf8");
+    const source = await readLauncherComposition();
     const preparation = source.indexOf("launchPage = await startDashboardLaunchPage(0);");
     const lock = source.indexOf("await withLauncherLock(");
     const buildSignature = source.indexOf(
@@ -757,7 +757,7 @@ describe("dashboard executable session", () => {
   });
 
   it("binds preparation atomically instead of reserving a probe-selected port", async () => {
-    const source = await readFile(new URL("./start-dashboard.mjs", import.meta.url), "utf8");
+    const source = await readLauncherComposition();
     const preparationStart = source.indexOf("launchPage = await startDashboardLaunchPage(0);");
     const lock = source.indexOf("await withLauncherLock(async () => {");
     const beforeLock = source.slice(preparationStart, lock);
@@ -784,3 +784,13 @@ async function temporaryDirectory() {
   temporaryDirectories.push(path);
   return path;
 }
+
+async function readLauncherComposition() {
+  return (
+    await Promise.all(
+      ["start-dashboard.mjs", "start-dashboard-build.mjs", "start-dashboard-paths.mjs"].map(
+        (path) => readFile(new URL(`./${path}`, import.meta.url), "utf8"),
+      ),
+    )
+  ).join("\n");
+}

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

@@ -1,6 +1,6 @@
 {
   "name": "@zaip-ai/dashboard-ui",
-  "version": "2.2.0",
+  "version": "2.6.0",
   "private": true,
   "type": "module",
   "exports": {