@zaip-ai/cli 3.3.0 → 3.5.0

package/templates/.agents/dashboard/packages/local-runtime/src/sqlite-schema-dashboard-views.ts

@@ -1,4 +1,7 @@
+import { macroClassificationSql } from "./sqlite-schema-macro-classification.js";
+
 export const dashboardViewSql = `        CREATE VIEW vw_operations_work_list AS SELECT * FROM vw_entities;
+        ${macroClassificationSql}
         -- Full work summary retains historical activity coverage for internal
         -- entity summaries. It is not the Kanban population.
         CREATE VIEW vw_operations_work_summary AS
@@ -49,30 +52,18 @@ export const dashboardViewSql = `        CREATE VIEW vw_operations_work_list AS
           ), durations AS (
             SELECT entity_kind, entity_id, ROUND(SUM(duration_ms)) AS total_duration
             FROM entity_activity GROUP BY entity_kind, entity_id
-          ), macro_classification AS (
-            -- These are structural macro facts.  The narrowed-period first
-            -- fold filters the selected macros by activity, then retains their
-            -- canonical Task/rework classification instead of treating the
-            -- compact work-list row as an empty delivery.
-            SELECT 'spec' AS entity_kind, spec_id AS entity_id,
-              COUNT(DISTINCT task_id) AS task_count,
-              SUM(CASE WHEN work_type='rework' AND run_role='root' THEN 1 ELSE 0 END) AS rework_run_count
-            FROM activities WHERE spec_id IS NOT NULL GROUP BY spec_id
-            UNION ALL
-            SELECT 'prd' AS entity_kind, prd_id AS entity_id,
-              COUNT(DISTINCT task_id) AS task_count,
-              SUM(CASE WHEN work_type='rework' AND run_role='root' THEN 1 ELSE 0 END) AS rework_run_count
-            FROM activities WHERE prd_id IS NOT NULL GROUP BY prd_id
           )
           SELECT w.entity_kind, w.id, w.title, w.status, w.risk, w.occurred_at, w.occurred_day_sp,
             f.invocation_count, f.llm_call_count, d.total_duration,
             f.total_tokens, f.total_cost_usd, f.total_cost_brl,
             COALESCE(classification.task_count, 0) AS task_count,
-            COALESCE(classification.rework_run_count, 0) AS rework_run_count
+            COALESCE(classification.rework_run_count, 0) AS rework_run_count,
+            COALESCE(classification.task_ids_json, '[]') AS task_ids_json,
+            COALESCE(classification.completed_task_count, 0) AS completed_task_count
           FROM work_items w
           LEFT JOIN financial f ON f.entity_kind=w.entity_kind AND f.entity_id=w.id
           LEFT JOIN durations d ON d.entity_kind=w.entity_kind AND d.entity_id=w.id
-          LEFT JOIN macro_classification classification
+          LEFT JOIN vw_macro_classification classification
             ON classification.entity_kind=w.entity_kind AND classification.entity_id=w.id;
         -- Kanban is a lifecycle surface: it lists only canonical records.
         -- Telemetry-only identifiers remain Cost Monitor facts but cannot
@@ -207,46 +198,16 @@ export const dashboardViewSql = `        CREATE VIEW vw_operations_work_list AS
             overview.latest_task_created_at
           FROM vw_first_fold_overview_all_time overview;
         CREATE VIEW vw_first_fold_spec_status_all_time AS
-          WITH counts AS (
-            SELECT CASE
-              WHEN status='cancelled' THEN 'cancelled'
-              WHEN status='failed' THEN 'failed'
-              WHEN status='blocked' THEN 'blocked'
-              WHEN status IN ('delivered','completed') THEN 'completed'
-              WHEN status='ready' THEN 'ready'
-              WHEN status='draft' THEN 'planning'
-              WHEN status='verifying' THEN 'verifying'
-              WHEN status IN ('active','executing') THEN 'executing'
-              ELSE 'planning'
-            END AS stage, COUNT(*) AS entity_count
-            FROM spec_summary GROUP BY stage
-          ), total AS (SELECT SUM(entity_count) AS entity_count FROM counts)
-          SELECT counts.stage, counts.entity_count,
-            CASE WHEN total.entity_count=0 THEN 0.0 ELSE CAST(counts.entity_count AS REAL)/total.entity_count END AS entity_percentage
-          FROM counts CROSS JOIN total;
+          SELECT COALESCE(c.stage, 'planning') AS stage, COUNT(*) AS entity_count
+          FROM work_items w LEFT JOIN canonical_work_items c ON c.entity_kind=w.entity_kind AND c.id=w.id
+          WHERE w.entity_kind='spec' GROUP BY COALESCE(c.stage, 'planning');
         CREATE VIEW vw_first_fold_prd_status_all_time AS
-          WITH counts AS (
-            SELECT CASE
-              WHEN status='cancelled' THEN 'cancelled'
-              WHEN status='failed' THEN 'failed'
-              WHEN status='blocked' THEN 'blocked'
-              WHEN status IN ('delivered','completed') THEN 'completed'
-              WHEN status='ready' THEN 'ready'
-              WHEN status='draft' THEN 'definition'
-              WHEN status='verifying' THEN 'verifying'
-              WHEN status IN ('active','executing') THEN 'executing'
-              ELSE 'definition'
-            END AS stage, COUNT(*) AS entity_count
-            FROM prd_summary GROUP BY stage
-          ), total AS (SELECT SUM(entity_count) AS entity_count FROM counts)
-          SELECT counts.stage, counts.entity_count,
-            CASE WHEN total.entity_count=0 THEN 0.0 ELSE CAST(counts.entity_count AS REAL)/total.entity_count END AS entity_percentage
-          FROM counts CROSS JOIN total;
+          SELECT COALESCE(c.stage, 'definition') AS stage, COUNT(*) AS entity_count
+          FROM work_items w LEFT JOIN canonical_work_items c ON c.entity_kind=w.entity_kind AND c.id=w.id
+          WHERE w.entity_kind='prd' GROUP BY COALESCE(c.stage, 'definition');
         CREATE VIEW vw_first_fold_spec_classification_all_time AS
           WITH rollup AS (
-            SELECT s.id, COUNT(DISTINCT a.task_id) AS task_count,
-              SUM(CASE WHEN a.work_type='rework' AND a.run_role='root' THEN 1 ELSE 0 END) AS rework_run_count
-            FROM spec_summary s LEFT JOIN activities a ON a.spec_id=s.id GROUP BY s.id
+            SELECT task_count, rework_run_count FROM vw_macro_classification WHERE entity_kind='spec'
           ), counts AS (
             SELECT CASE WHEN rework_run_count>0 THEN 'rework' WHEN task_count>0 THEN 'structured' ELSE 'empty' END AS classification,
               COUNT(*) AS entity_count
@@ -257,9 +218,7 @@ export const dashboardViewSql = `        CREATE VIEW vw_operations_work_list AS
           FROM counts CROSS JOIN total;
         CREATE VIEW vw_first_fold_prd_classification_all_time AS
           WITH rollup AS (
-            SELECT p.id, COUNT(DISTINCT a.task_id) AS task_count,
-              SUM(CASE WHEN a.work_type='rework' AND a.run_role='root' THEN 1 ELSE 0 END) AS rework_run_count
-            FROM prd_summary p LEFT JOIN activities a ON a.prd_id=p.id GROUP BY p.id
+            SELECT task_count, rework_run_count FROM vw_macro_classification WHERE entity_kind='prd'
           ), counts AS (
             SELECT CASE WHEN rework_run_count>0 THEN 'rework' WHEN task_count>0 THEN 'structured' ELSE 'empty' END AS classification,
               COUNT(*) AS entity_count

package/templates/.agents/dashboard/packages/local-runtime/src/sqlite-schema-macro-classification.ts

@@ -0,0 +1,48 @@
+// Structural membership exists before a Task has any Run.
+// Keep drafts in known_tasks to suppress historical fallback, then filter
+// structural links. Materialization avoids repeated JSON payload scans.
+export const macroClassificationSql = `CREATE VIEW vw_macro_classification AS
+          WITH known_tasks AS MATERIALIZED (SELECT id, status, spec_id, change_id FROM canonical_work_items WHERE entity_kind='task'),
+          canonical_tasks AS (SELECT * FROM known_tasks WHERE status<>'draft'),
+          task_change_links AS MATERIALIZED (
+            SELECT t.id AS task_id, COALESCE(c.source_spec_id, CASE WHEN c.source_type='spec' THEN c.source_id END) AS spec_id,
+              COALESCE(c.source_prd_id, CASE WHEN c.source_type='prd' THEN c.source_id END) AS prd_id FROM canonical_tasks t JOIN canonical_changes c ON t.change_id=c.id
+            UNION
+            SELECT t.id, COALESCE(c.source_spec_id, CASE WHEN c.source_type='spec' THEN c.source_id END),
+              COALESCE(c.source_prd_id, CASE WHEN c.source_type='prd' THEN c.source_id END) FROM canonical_changes c CROSS JOIN json_each(c.task_ids_json) j JOIN canonical_tasks t ON t.id=j.value
+          ), task_links AS (
+            SELECT 'spec' AS entity_kind, t.spec_id AS entity_id, t.id AS task_id FROM canonical_tasks t WHERE t.spec_id IS NOT NULL
+            UNION
+            SELECT 'spec', spec_id, task_id FROM task_change_links
+            UNION
+            SELECT 'prd', prd_id, task_id FROM task_change_links
+            UNION
+            SELECT 'prd', s.prd_id, t.id FROM canonical_tasks t
+              LEFT JOIN task_change_links l ON l.task_id=t.id
+              JOIN canonical_work_items s ON s.entity_kind='spec' AND s.id=COALESCE(t.spec_id,l.spec_id)
+              WHERE s.prd_id IS NOT NULL AND l.prd_id IS NULL
+            UNION
+            SELECT 'spec', spec_id, task_id FROM activities a WHERE spec_id IS NOT NULL AND task_id IS NOT NULL
+              AND NOT EXISTS (SELECT 1 FROM known_tasks t WHERE t.id=a.task_id)
+            UNION
+            SELECT 'prd', prd_id, task_id FROM activities a WHERE prd_id IS NOT NULL AND task_id IS NOT NULL
+              AND NOT EXISTS (SELECT 1 FROM known_tasks t WHERE t.id=a.task_id)
+          ), tasks AS (
+            SELECT l.entity_kind, l.entity_id, COUNT(DISTINCT l.task_id) AS task_count,
+              json_group_array(DISTINCT l.task_id) AS task_ids_json,
+              COUNT(DISTINCT CASE WHEN t.status='completed' THEN l.task_id END) AS completed_task_count
+            FROM task_links l LEFT JOIN known_tasks t ON t.id=l.task_id
+            GROUP BY l.entity_kind, l.entity_id
+          ), rework AS (
+            SELECT 'spec' AS entity_kind, spec_id AS entity_id, COUNT(*) AS rework_run_count
+              FROM activities WHERE spec_id IS NOT NULL AND work_type='rework' AND run_role='root' GROUP BY spec_id
+            UNION ALL
+            SELECT 'prd', prd_id, COUNT(*) FROM activities
+              WHERE prd_id IS NOT NULL AND work_type='rework' AND run_role='root' GROUP BY prd_id
+          )
+          SELECT w.entity_kind, w.id AS entity_id, COALESCE(t.task_count, 0) AS task_count,
+            COALESCE(r.rework_run_count, 0) AS rework_run_count,
+            COALESCE(t.task_ids_json, '[]') AS task_ids_json, COALESCE(t.completed_task_count, 0) AS completed_task_count
+          FROM work_items w LEFT JOIN tasks t ON t.entity_kind=w.entity_kind AND t.entity_id=w.id
+          LEFT JOIN rework r ON r.entity_kind=w.entity_kind AND r.entity_id=w.id
+          WHERE w.entity_kind IN ('spec','prd');`;

package/templates/.agents/dashboard/packages/local-runtime/src/sqlite-summary-cursor.ts

@@ -0,0 +1,15 @@
+export function encodeSummaryCursor(occurredAt: string, id: string): string {
+  return encodeURIComponent(JSON.stringify([occurredAt, id]));
+}
+
+export function parseSummaryCursor(cursor: string | null): [string, string] | null {
+  if (cursor === null) return null;
+  try {
+    const parsed = JSON.parse(decodeURIComponent(cursor));
+    return Array.isArray(parsed) && typeof parsed[0] === "string" && typeof parsed[1] === "string"
+      ? [parsed[0], parsed[1]]
+      : null;
+  } catch {
+    return null;
+  }
+}

package/templates/.agents/dashboard/packages/local-runtime/src/sqlite-token-active-allocation.ts

@@ -0,0 +1,46 @@
+import { saoPauloDay } from "./sqlite-calendar.js";
+
+export type TemporalInterval = { activityRowId: string; startMs: number; endMs: number };
+
+/**
+ * Splits every observed interval at every activity boundary and São Paulo day
+ * boundary. Each elementary segment is divided equally among the token-active
+ * activities covering it, making the materialized fact additive by activity,
+ * day, and every parent dimension.
+ */
+export function allocateAttributedTokenActiveMs(intervals: readonly TemporalInterval[]) {
+  const boundaries = new Set<number>();
+  for (const interval of intervals) {
+    boundaries.add(interval.startMs);
+    boundaries.add(interval.endMs);
+    for (let cursor = interval.startMs; cursor < interval.endMs; ) {
+      const nextDay =
+        Date.parse(`${saoPauloDay(new Date(cursor).toISOString())}T03:00:00.000Z`) + 86_400_000;
+      if (nextDay >= interval.endMs) break;
+      boundaries.add(nextDay);
+      cursor = nextDay;
+    }
+  }
+  const points = [...boundaries].sort((left, right) => left - right);
+  const allocated = new Map<string, { activityRowId: string; day: string; value: number }>();
+  for (let index = 0; index < points.length - 1; index += 1) {
+    const startMs = points[index]!;
+    const endMs = points[index + 1]!;
+    const active = intervals.filter(
+      (interval) => interval.startMs < endMs && interval.endMs > startMs,
+    );
+    if (active.length === 0 || endMs <= startMs) continue;
+    const share = (endMs - startMs) / active.length;
+    const day = saoPauloDay(new Date(startMs).toISOString());
+    for (const interval of active) {
+      const key = `${interval.activityRowId}:${day}`;
+      const previous = allocated.get(key);
+      allocated.set(key, {
+        activityRowId: interval.activityRowId,
+        day,
+        value: (previous?.value ?? 0) + share,
+      });
+    }
+  }
+  return [...allocated.values()];
+}

package/templates/.agents/dashboard/packages/local-runtime/src/sqlite-work-stages.ts

@@ -0,0 +1,60 @@
+import type { CanonicalChange, CanonicalEntity } from "./sqlite-read-model-canonical.js";
+
+/** Derive display stages from persisted lifecycle facts, never from live invocation guesses. */
+export function deriveCanonicalWorkStages(
+  entities: Map<string, CanonicalEntity>,
+  changes: readonly CanonicalChange[],
+): void {
+  const children = new Map<string, Set<string>>();
+  const changesById = new Map(changes.map((change) => [change.id, change]));
+  const changesByTask = new Map<string, CanonicalChange>();
+  for (const change of changes)
+    for (const taskId of change.taskIds) {
+      if (!changesByTask.has(taskId)) changesByTask.set(taskId, change);
+    }
+  const link = (kind: string, id: string | null, taskId: string) => {
+    if (id === null) return;
+    const key = `${kind}:${id}`;
+    const ids = children.get(key) ?? new Set<string>();
+    ids.add(taskId);
+    children.set(key, ids);
+  };
+  for (const task of entities.values()) {
+    if (task.kind !== "task" || task.status === "draft") continue;
+    const change = changesById.get(task.changeId ?? "") ?? changesByTask.get(task.id);
+    const specId =
+      task.specId ??
+      change?.sourceSpecId ??
+      (change?.sourceType === "spec" ? change.sourceId : null);
+    const prdId =
+      change?.sourcePrdId ??
+      (change?.sourceType === "prd" ? change.sourceId : null) ??
+      (specId ? (entities.get(`spec:${specId}`)?.prdId ?? null) : null);
+    link("spec", specId, task.id);
+    link("prd", prdId, task.id);
+  }
+  for (const entity of entities.values()) {
+    if (entity.kind !== "spec" && entity.kind !== "prd") continue;
+    const status = entity.status;
+    if (status === "delivered" || status === "completed") entity.stage = "completed";
+    else if (
+      status === "blocked" ||
+      status === "failed" ||
+      status === "cancelled" ||
+      status === "ready" ||
+      status === "verifying"
+    )
+      entity.stage = status;
+    else if (status === "draft") entity.stage = entity.kind === "prd" ? "definition" : "planning";
+    else if (status === "active" || status === "executing") {
+      const tasks = [...(children.get(`${entity.kind}:${entity.id}`) ?? [])].map((id) =>
+        entities.get(`task:${id}`),
+      );
+      entity.stage =
+        tasks.length > 0 &&
+        tasks.every((t) => t?.status === "verifying" || t?.status === "completed")
+          ? "verifying"
+          : "executing";
+    }
+  }
+}

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

@@ -2,6 +2,7 @@ export async function collectPreviousDashboardSessions({
   candidateSessionPath,
   candidateRegistryPath,
   probe,
+  inspectOwnership,
   readDashboardSession,
   readPortRegistry,
   workspaceRoot,
@@ -34,7 +35,10 @@ export async function collectPreviousDashboardSessions({
   }
   const reachable = await Promise.all(
     [...latestByPort.values()].map(async (candidate) =>
-      (await probe(candidate.port)) ? candidate : null,
+      (await probe(candidate.port)) &&
+      (await inspectOwnership(candidate, { workspaceRoot, workspaceKey }))
+        ? candidate
+        : null,
     ),
   );
   return reachable.filter(Boolean);

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

@@ -7,6 +7,7 @@ import {
   host,
   requestBackgroundProjectionRefresh,
   workspaceKey,
+  workspaceRoot,
 } from "./start-dashboard.mjs";
 
 const temporaryDirectories = [];
@@ -23,7 +24,12 @@ describe("dashboard launch claims", () => {
     const path = join(directory, "dashboard-launch.json");
     await writeFile(
       path,
-      JSON.stringify({ kind: "zaip-dashboard-sqlite-launch", workspaceKey, launcherPid: 1234 }),
+      JSON.stringify({
+        kind: "zaip-dashboard-sqlite-launch",
+        workspaceKey,
+        workspace: workspaceRoot,
+        launcherPid: 1234,
+      }),
     );
     const stops = [];
     await expect(

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

@@ -1,6 +1,21 @@
 import { createServer as createHttpServer } from "node:http";
+import { basename } from "node:path";
 
-export async function createDashboardLaunchPage({ port, host, runtimeKind, healthPath, delay }) {
+const escapeHtml = (text) =>
+  String(text).replace(
+    /[&<>"']/g,
+    (character) =>
+      ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&#39;" })[character],
+  );
+
+export async function createDashboardLaunchPage({
+  port,
+  host,
+  runtimeKind,
+  healthPath,
+  delay,
+  workspaceRoot = "",
+}) {
   let redirectUrl = null;
   let failure = null;
   let progress = {
@@ -81,7 +96,7 @@ export async function createDashboardLaunchPage({ port, host, runtimeKind, healt
 </head>
 <body>
   <main class="launch-overlay" aria-label="Preparando dashboard" aria-busy="true">
-    <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><span class="activity" id="activity" aria-hidden="true">Atividade em andamento.</span><div class="track" id="track" role="progressbar" aria-label="Preparação em andamento" aria-valuemin="0" aria-valuemax="100" aria-valuenow="4" aria-valuetext="Iniciando o launcher local"><div class="bar" id="bar"></div></div><ol class="steps" id="steps" aria-label="Etapas de preparação"><li data-state="active">Iniciando o launcher local</li></ol><span class="handoff" id="handoff">O dashboard está pronto. Abrindo a tela principal automaticamente…</span><span class="failure" id="failure" role="alert"></span></section>
+    <section class="progress" aria-live="polite" role="status"><div aria-label="Workspace" style="margin-bottom:20px;overflow-wrap:anywhere"><strong>${escapeHtml(basename(workspaceRoot))}</strong><span>${escapeHtml(workspaceRoot)}</span></div><strong id="phase">Iniciando o launcher local</strong><span id="detail">Abrindo a página de preparação.</span><span class="activity" id="activity" aria-hidden="true">Atividade em andamento.</span><div class="track" id="track" role="progressbar" aria-label="Preparação em andamento" aria-valuemin="0" aria-valuemax="100" aria-valuenow="4" aria-valuetext="Iniciando o launcher local"><div class="bar" id="bar"></div></div><ol class="steps" id="steps" aria-label="Etapas de preparação"><li data-state="active">Iniciando o launcher local</li></ol><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,lastProgressPercent=4,compilationStartedAt=null,compilationDetail="",compilationTicker=null,activeStepKey="",activeStepStartedAt=Date.now();

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

@@ -0,0 +1,65 @@
+import { resolve } from "node:path";
+import { listeningProcessId, processCommandLine } from "./start-dashboard-processes.mjs";
+
+const normalized = (value) =>
+  process.platform === "win32" ? resolve(value).toLowerCase() : resolve(value);
+
+export function dashboardCommandMatches(command, workspace) {
+  if (typeof command !== "string" || typeof workspace !== "string") return false;
+  const args = [...command.matchAll(/"([^"]*)"|'([^']*)'|([^\s\0]+)/g)].map(
+    (match) => match[1] ?? match[2] ?? match[3],
+  );
+  const root = resolve(workspace, ".agents/dashboard/packages/local-runtime");
+  const expected = ["server.mjs", "dist/server.cjs", "dist/server.js"].map((file) =>
+    normalized(resolve(root, file)),
+  );
+  // Our launcher spawns Node with exactly one script argument. A foreign
+  // script mentioning the runtime path later in its arguments is not owned.
+  return typeof args[1] === "string" && expected.includes(normalized(args[1]));
+}
+
+/** A recorded PID is only a hint. Prove the listener, executable and HTTP identity together. */
+export async function inspectDashboardOwnership(
+  session,
+  {
+    workspaceRoot,
+    workspaceKey,
+    host = "127.0.0.1",
+    fetchImpl = fetch,
+    listeningProcessIdImpl = listeningProcessId,
+    processCommandLineImpl = processCommandLine,
+  } = {},
+) {
+  if (
+    session?.workspace !== workspaceRoot ||
+    session?.workspaceKey !== workspaceKey ||
+    !Number.isInteger(session?.serverPid) ||
+    session.serverPid <= 0 ||
+    !Number.isInteger(session?.port) ||
+    session.port <= 0 ||
+    session.port > 65535
+  )
+    return null;
+  const listener = await listeningProcessIdImpl(session.port, host);
+  if (
+    listener !== session.serverPid ||
+    !dashboardCommandMatches(await processCommandLineImpl(listener), workspaceRoot)
+  )
+    return null;
+  try {
+    const response = await fetchImpl(`http://${host}:${session.port}/api/v2/health`, {
+      signal: AbortSignal.timeout(1500),
+    });
+    const health = await response.json();
+    if (
+      health?.kind !== "zaip-dashboard-sqlite-runtime" ||
+      health.workspaceKey !== workspaceKey ||
+      health.workspace !== workspaceRoot ||
+      health.server_pid !== listener
+    )
+      return null;
+    return health;
+  } catch {
+    return null;
+  }
+}

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

@@ -0,0 +1,72 @@
+import { resolve } from "node:path";
+import { describe, expect, it } from "vitest";
+import {
+  dashboardCommandMatches,
+  inspectDashboardOwnership,
+} from "./start-dashboard-ownership.mjs";
+import { stopOwnedDashboardProcess } from "./start-dashboard-processes.mjs";
+
+const workspace = resolve("fixture dashboard");
+const command = `node "${resolve(workspace, ".agents/dashboard/packages/local-runtime/dist/server.cjs")}"`;
+const session = { workspace, workspaceKey: "key", serverPid: 12345, rootPid: 111, port: 4417 };
+const health = {
+  kind: "zaip-dashboard-sqlite-runtime",
+  workspace,
+  workspaceKey: "key",
+  server_pid: 12345,
+};
+const options = {
+  workspaceRoot: workspace,
+  workspaceKey: "key",
+  listeningProcessIdImpl: async () => 12345,
+  processCommandLineImpl: async () => command,
+  fetchImpl: async () => new Response(JSON.stringify(health)),
+};
+describe("dashboard ownership", () => {
+  it("requires an exact runtime argument including workspaces containing spaces", () => {
+    expect(dashboardCommandMatches(command, workspace)).toBe(true);
+    expect(
+      dashboardCommandMatches(
+        `node unrelated.js "${resolve(workspace, ".agents/dashboard/packages/local-runtime/dist/server.cjs")}"`,
+        workspace,
+      ),
+    ).toBe(false);
+    expect(dashboardCommandMatches(command + ".foreign", workspace + "-other")).toBe(false);
+    expect(dashboardCommandMatches(`node "${workspace}/unrelated.js"`, workspace)).toBe(false);
+  });
+  it("accepts a live owned server even while degraded", async () => {
+    expect(
+      await inspectDashboardOwnership(session, {
+        ...options,
+        fetchImpl: async () =>
+          new Response(JSON.stringify({ ...health, status: "degraded" }), { status: 503 }),
+      }),
+    ).toMatchObject(health);
+  });
+  it.each([
+    { listeningProcessIdImpl: async () => 999 },
+    { processCommandLineImpl: async () => "node unrelated.js" },
+    {
+      fetchImpl: async () =>
+        new Response(JSON.stringify({ ...health, workspace: workspace + "-other" })),
+    },
+    { fetchImpl: async () => new Response(JSON.stringify({ ...health, server_pid: 999 })) },
+    { fetchImpl: async () => new Response(JSON.stringify({ ...health, workspaceKey: "other" })) },
+  ])("rejects mismatched evidence %#", async (override) => {
+    expect(await inspectDashboardOwnership(session, { ...options, ...override })).toBeNull();
+  });
+  it("does not kill a reused PID that now listens on the same port", async () => {
+    const killed = [];
+    const result = await stopOwnedDashboardProcess(session, {
+      ...options,
+      host: "127.0.0.1",
+      packageRoot: resolve(workspace, ".agents/dashboard/packages/local-runtime"),
+      probeDashboardPort: async () => true,
+      delay: async () => {},
+      processCommandLineImpl: async () => "node foreign-server.js",
+      stopProcessTreeImpl: async (pid) => killed.push(pid),
+    });
+    expect(result).toBe("skipped_unowned");
+    expect(killed).toEqual([]);
+  });
+});

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

@@ -1,6 +1,8 @@
 import { spawn } from "node:child_process";
 import { readFile } from "node:fs/promises";
+import { resolve } from "node:path";
 import process from "node:process";
+import { inspectDashboardOwnership } from "./start-dashboard-ownership.mjs";
 
 export function teardownWarning(status) {
   return status === "close_failed";
@@ -23,10 +25,12 @@ export async function stopOwnedDashboardProcess(
     fetchImpl,
     host,
     packageRoot,
+    workspaceRoot = resolve(packageRoot, "../../../.."),
     delay,
     listeningProcessIdImpl = listeningProcessId,
     isProcessAliveImpl = isProcessAlive,
     stopProcessTreeImpl = stopProcessTree,
+    processCommandLineImpl = processCommandLine,
   },
 ) {
   const initiallyReachable = await probeDashboardPort(
@@ -41,6 +45,15 @@ export async function stopOwnedDashboardProcess(
   // a transient runtime response) can never be persisted as closed.
   if (!initiallyReachable && listenerPid === null) return "closed";
   if (!registeredListenerMatches(session, listenerPid)) return "skipped_unowned";
+  const ownershipOptions = {
+    workspaceRoot,
+    workspaceKey,
+    host,
+    fetchImpl,
+    listeningProcessIdImpl,
+    processCommandLineImpl,
+  };
+  if (!(await inspectDashboardOwnership(session, ownershipOptions))) return "skipped_unowned";
   // The server PID is the ownership boundary.  Killing the recorded launcher
   // root with taskkill /t can also terminate a newly handed-off generation on
   // Windows when the old launcher process tree is still being reaped.  The
@@ -64,7 +77,11 @@ export async function stopOwnedDashboardProcess(
     // Windows can report taskkill complete before the listener disappears.
     // Retry only while the original registered server PID is still listening;
     // a reused or foreign PID remains protected by the ownership check above.
-    if (listenerStillMatches && Date.now() - lastTeardownAttemptAt >= 500) {
+    if (
+      listenerStillMatches &&
+      Date.now() - lastTeardownAttemptAt >= 500 &&
+      (await inspectDashboardOwnership(session, ownershipOptions))
+    ) {
       await stopProcessTreeImpl(session.serverPid);
       if (rootIsKnownLauncher) await stopProcessTreeImpl(session.rootPid);
       lastTeardownAttemptAt = Date.now();
@@ -88,17 +105,23 @@ export async function listeningProcessId(port, host = "127.0.0.1") {
 
 export async function isKnownDashboardLauncher(pid, packageRoot) {
   if (!Number.isInteger(pid) || pid <= 0) return false;
-  const command =
-    process.platform === "win32"
-      ? await commandOutput("powershell.exe", [
-          "-NoProfile",
-          "-Command",
-          `(Get-CimInstance Win32_Process -Filter 'ProcessId=${pid}' -ErrorAction SilentlyContinue).CommandLine`,
-        ])
-      : await readFile(`/proc/${pid}/cmdline`, "utf8").catch(() => "");
+  const command = await processCommandLine(pid);
   return command.includes("start-dashboard") && command.includes(packageRoot);
 }
 
+export async function processCommandLine(pid) {
+  if (!Number.isInteger(pid) || pid <= 0) return "";
+  return process.platform === "win32"
+    ? await commandOutput("powershell.exe", [
+        "-NoProfile",
+        "-Command",
+        `(Get-CimInstance Win32_Process -Filter 'ProcessId=${pid}' -ErrorAction SilentlyContinue).CommandLine`,
+      ])
+    : process.platform === "linux"
+      ? await readFile(`/proc/${pid}/cmdline`, "utf8").catch(() => "")
+      : await commandOutput("ps", ["-p", String(pid), "-o", "command="]);
+}
+
 export async function isAncestorProcess(ancestorPid, descendantPid, parentOf = processParentId) {
   if (!Number.isInteger(ancestorPid) || !Number.isInteger(descendantPid)) return false;
   const visited = new Set();