@yemi33/minions 0.1.2379 → 0.1.2380

package/engine/ado-status.js

@@ -14,7 +14,7 @@
  *
  * Output: JSON to stdout. Exit 0 on success, 1 on error/not-found.
  *
- * Cached (default): reads pull-requests.json maintained by the engine (~3 min stale).
+ * Cached (default): reads engine-maintained SQL state (~3 min stale).
  * Live (--live):    makes fresh ADO API calls — use when engine isn't running or you
  *                   just pushed and need up-to-the-moment build status.
  */
@@ -23,7 +23,7 @@
 
 const path = require('path');
 const shared = require('./shared');
-const { safeJson, safeJsonArr, projectPrPath, getProjects, MINIONS_DIR } = shared;
+const { safeJson, readPullRequests, getProjects, MINIONS_DIR } = shared;
 
 // ── Arg parsing ──────────────────────────────────────────────────────────────
 
@@ -56,7 +56,7 @@ const prNumber = parseInt(prNumberArg, 10);
 
 function findInCache(projects) {
   for (const project of projects) {
-    const prs = safeJsonArr(projectPrPath(project));
+    const prs = readPullRequests(project);
     shared.normalizePrRecords(prs, project);
     const pr = prs.find(p => p.prNumber === prNumber || p.id === shared.getCanonicalPrId(project, prNumber) || shared.getPrDisplayId(p) === `PR-${prNumber}`);
     if (!pr) continue;
@@ -104,7 +104,7 @@ async function main() {
   if (!live) {
     const result = findInCache(projects);
     if (result) { console.log(JSON.stringify(result, null, 2)); return; }
-    console.error(`PR #${prNumber} not found in cached pull-requests.json`);
+    console.error(`PR #${prNumber} not found in the cached PR store`);
     console.error('Tip: try --live for a fresh ADO API call, or check the PR number is correct.');
     process.exit(1);
   }
@@ -133,7 +133,7 @@ async function main() {
     return;
   }
 
-  console.error(`PR #${prNumber} not found (tried live ADO API and cached pull-requests.json).`);
+  console.error(`PR #${prNumber} not found (tried live ADO API and the cached PR store).`);
   process.exit(1);
 }
 

package/engine/ado.js

@@ -279,7 +279,7 @@ function repairAdoProjectConfig(project, purpose, prs = null) {
   const missingBefore = getMissingAdoProjectConfigFields(project);
   if (missingBefore.length === 0) return false;
 
-  const trackedPrs = prs || shared.safeJsonArr(shared.projectPrPath(project));
+  const trackedPrs = prs || shared.readPullRequests(project);
   for (const candidate of collectAdoRepairCandidates(project, trackedPrs)) {
     const repairs = {};
     if (!project.adoOrg && candidate.adoOrg) repairs.adoOrg = candidate.adoOrg;
@@ -1199,7 +1199,7 @@ async function forEachActivePr(config, token, callback) {
     }
 
     if (projectUpdated > 0) {
-      mutateJsonFileLocked(shared.projectPrPath(project), (currentPrs) => {
+      shared.mutatePullRequests(project, (currentPrs) => {
         // Merge back only fields changed by callbacks; preserve concurrent disk updates.
         for (const { before, after } of updatedRecords) {
           const updatedPrNumber = shared.getPrNumber(after);
@@ -1244,9 +1244,9 @@ async function forEachActivePr(config, token, callback) {
     }
   }
 
-  // BUG-C2 — Also poll manually-linked ADO PRs from central pull-requests.json.
+  // BUG-C2 — Also poll manually linked ADO PRs from the central PR store.
   // Mirror of engine/github.js:540-633. Without this block, any ADO PR enrolled
-  // into central pull-requests.json via the dashboard attach UI or
+  // into the central PR store via the dashboard attach UI or
   // lifecycle.enrollPrFromCanonicalId is never polled (status, build, review,
   // comments, abandoned-reconciliation all freeze permanently).
   //
@@ -1272,8 +1272,7 @@ async function forEachActivePr(config, token, callback) {
   //      in that project's per-project file, so the project loop will really see
   //      them. Blindly skipping all project-compatible IDs caused a permanent
   //      orphan when the record lived in the central file (#328).
-  const centralPath = path.join(shared.MINIONS_DIR, 'pull-requests.json');
-  const centralPrs = shared.safeJsonArr(centralPath);
+  const centralPrs = shared.readPullRequests('central');
   const configuredAdoProjects = projects.filter(p => !isGitHubProject(p) && p.adoOrg && p.adoProject);
 
   const activeCentral = centralPrs.filter(pr => {
@@ -1287,7 +1286,7 @@ async function forEachActivePr(config, token, callback) {
     // polled (fix for #328).
     const owningProject = configuredAdoProjects.find(p => shared.isPrCompatibleWithProject(p, { id: pr.id }, ''));
     if (owningProject) {
-      const projectPrs = shared.safeJsonArr(shared.projectPrPath(owningProject));
+      const projectPrs = shared.readPullRequests(owningProject);
       if (projectPrs.some(p => p.id === pr.id)) return false; // present in per-project file → project loop handles it
     }
     return true;
@@ -1353,7 +1352,7 @@ async function forEachActivePr(config, token, callback) {
   }
 
   if (centralUpdated > 0) {
-    mutateJsonFileLocked(centralPath, (currentPrs) => {
+    shared.mutatePullRequests('central', (currentPrs) => {
       for (const { before, after } of updatedCentralRecords) {
         const idx = currentPrs.findIndex(p => p.id === after.id);
         if (idx >= 0) {
@@ -1457,7 +1456,7 @@ async function pollPrStatus(config) {
         }
         // F6 (P-f6commentedit): drop the comment-edit dedup map on merge/abandon
         // — no further re-dispatch path can fire from this PR, so keeping it
-        // around would only bloat pull-requests.json.
+        // around would only bloat the PR store.
         if (pr.humanFeedback && pr.humanFeedback.editsSeen) {
           delete pr.humanFeedback.editsSeen;
         }
@@ -1911,7 +1910,7 @@ async function pollPrStatus(config) {
     // review status flipped, etc.) is dropped via clearPrNoOpFixAttempt. The
     // dispatch gate already ignores these stale records (isPrNoOpFixCausePaused
     // re-validates the fingerprint), but without this sweep they linger in
-    // pull-requests.json forever — bloating the file and confusing the
+    // PR store forever — bloating the registry and confusing the
     // dashboard `pr-paused-chip`. Runs AFTER all live-field updates so the
     // fingerprint comparison uses post-poll PR state.
     try {
@@ -2160,7 +2159,7 @@ async function pollPrHumanComments(config) {
 
 /**
  * Reconcile PRs: find active ADO PRs created by the minions that aren't tracked
- * in pull-requests.json, and add them. Matches PRs to work items by branch name.
+ * in the PR store, and add them. Matches PRs to work items by branch name.
  */
 async function reconcilePrs(config) {
   // #3758 — inert when no project actually uses ADO.
@@ -2207,18 +2206,15 @@ async function reconcilePrs(config) {
 
     if (adoPrs.length === 0) continue;
 
-    const prPath = shared.projectPrPath(project);
-    const existingPrs = shared.safeJsonArr(prPath);
+    const existingPrs = shared.readPullRequests(project);
     shared.normalizePrRecords(existingPrs, project);
     const existingIds = new Set(existingPrs.map(p => p.id));
     let projectAdded = 0;
     let metadataUpdated = 0;
 
     // Load work items to match branches to work item IDs
-    const wiPath = shared.projectWorkItemsPath(project);
-    const workItems = shared.safeJsonArr(wiPath);
-    const centralWiPath = path.join(shared.MINIONS_DIR, 'work-items.json');
-    const centralItems = shared.safeJsonArr(centralWiPath);
+    const workItems = shared.readWorkItems(project);
+    const centralItems = shared.readWorkItems('central');
     const allItems = [...workItems, ...centralItems];
 
     let projectUpdated = 0;
@@ -2251,9 +2247,9 @@ async function reconcilePrs(config) {
             log('warn', `ADO: invalid sourceRefName "${branch.slice(0, 64)}" for PR ${prId}: ${refErr.message}`);
           }
         }
-        // PR already tracked — write link to pr-links.json if we can extract an ID
+        // PR already tracked — write a PR link if we can extract an ID
         if (confirmedItemId) {
-          shared.upsertPullRequestRecord(prPath, existing || {
+          shared.upsertPullRequestRecord(project, existing || {
             id: prId,
             prNumber: adoPr.pullRequestId,
             title: (adoPr.title || `PR #${adoPr.pullRequestId}`).slice(0, 120),
@@ -2312,7 +2308,7 @@ async function reconcilePrs(config) {
         sourcePlan: linkedItem?.sourcePlan || '',
         itemType: linkedItem?.itemType || '',
       };
-      const upserted = shared.upsertPullRequestRecord(prPath, entry, { project, itemId: confirmedItemId });
+      const upserted = shared.upsertPullRequestRecord(project, entry, { project, itemId: confirmedItemId });
       existingPrs.push(upserted.record || entry);
       existingIds.add(prId);
       projectAdded++;
@@ -2331,7 +2327,7 @@ async function reconcilePrs(config) {
     const backfilled = shared.backfillPrPrdItems(existingPrs, shared.getPrLinks());
 
     if (projectAdded > 0 || projectUpdated > 0 || backfilled > 0 || metadataUpdated > 0) {
-      mutateJsonFileLocked(prPath, (currentPrs) => {
+      shared.mutatePullRequests(project, (currentPrs) => {
         // Merge reconciled PRs into the locked copy by ID
         for (const pr of existingPrs) {
           const idx = currentPrs.findIndex(p => p.id === pr.id);
@@ -2905,7 +2901,7 @@ async function reconcileAbandonedPrs(config) {
     // log line is honest about what we left behind.
     let pending = 0;
     for (const project of projects) {
-      const prs = shared.safeJsonArr(shared.projectPrPath(project));
+      const prs = shared.readPullRequests(project);
       pending += prs.filter(pr =>
         pr.status === shared.PR_STATUS.ABANDONED && !pr._reconciliation404Confirmed
       ).length;
@@ -2926,8 +2922,7 @@ async function reconcileAbandonedPrs(config) {
       continue;
     }
 
-    const prPath = shared.projectPrPath(project);
-    const prs = shared.safeJsonArr(prPath);
+    const prs = shared.readPullRequests(project);
     const abandonedPrs = prs.filter(pr =>
       pr.status === shared.PR_STATUS.ABANDONED
       && !pr._reconciliation404Confirmed
@@ -3010,7 +3005,7 @@ async function reconcileAbandonedPrs(config) {
 
     if (updates.length > 0) {
       const reconciledAt = ts();
-      shared.mutatePullRequests(prPath, (currentPrs) => {
+      shared.mutatePullRequests(project, (currentPrs) => {
         for (const upd of updates) {
           const pr = currentPrs.find(p => shared.getPrNumber(p) === upd.prNumber);
           if (!pr) continue;

package/engine/agent-worker-pool.js

@@ -112,6 +112,7 @@ const _leaseContexts = new Map(); // dispatchId → mutable session-only context
 // toward `_poolSize` so a burst of concurrent acquireWorker calls can't
 // overshoot the configured pool size while spawns are still in flight.
 let _reserved = 0;
+let _draining = false;
 
 function _occupied() {
   return _free.length + _busy.size + _reserved;
@@ -169,6 +170,11 @@ async function _reuseWorker(worker, req) {
     await worker.newSession({ mcpServers: req.mcpServers, model: req.model, effort: req.effort, cwd: req.cwd });
     _trace(`dispatch=${req.dispatchId} reuse: worker=${worker.id} sessionId=${worker.sessionId}`);
     _reserved--;
+    if (_draining) {
+      try { worker.close(); } catch { /* already torn down */ }
+      req.reject(new Error('agent-worker-pool: draining'));
+      return;
+    }
     req.resolve(worker);
   } catch (err) {
     _reserved--;
@@ -185,6 +191,11 @@ async function _respawnWorker(stale, req) {
   try {
     const worker = await _bootWorker(req);
     _reserved--;
+    if (_draining) {
+      try { worker.close(); } catch { /* already torn down */ }
+      req.reject(new Error('agent-worker-pool: draining'));
+      return;
+    }
     req.resolve(worker);
   } catch (err) {
     _reserved--;
@@ -197,6 +208,11 @@ async function _spawnFreshWorker(req) {
   try {
     const worker = await _bootWorker(req);
     _reserved--;
+    if (_draining) {
+      try { worker.close(); } catch { /* already torn down */ }
+      req.reject(new Error('agent-worker-pool: draining'));
+      return;
+    }
     req.resolve(worker);
   } catch (err) {
     _reserved--;
@@ -299,6 +315,7 @@ async function acquireWorker({
   dispatchId, cwd, model, effort, mcpServers, hermeticDirs, processEnv, sessionContext,
 } = {}) {
   if (!dispatchId) throw new Error('agent-worker-pool.acquireWorker: dispatchId is required');
+  if (_draining) throw new Error('agent-worker-pool: draining');
   if (_busy.has(dispatchId) || _leaseContexts.has(dispatchId)) {
     throw new Error(
       `agent-worker-pool.acquireWorker: dispatchId ${dispatchId} already has an active worker ` +
@@ -329,13 +346,20 @@ async function acquireWorker({
       _pump();
     });
 
+    if (_draining) throw new Error('agent-worker-pool: draining');
+    _busy.set(dispatchId, worker);
     await _applyHermeticDirs(worker, hermeticDirs);
     if (worker.killed) throw new Error('agent-worker-pool: worker died during acquisition');
+    if (_draining) throw new Error('agent-worker-pool: draining');
   } catch (err) {
+    if (_busy.get(dispatchId) === worker) _busy.delete(dispatchId);
     _clearLeaseContext(dispatchId);
+    if (worker) {
+      try { worker.close(); } catch { /* already torn down */ }
+      _pump();
+    }
     throw err;
   }
-  _busy.set(dispatchId, worker);
 
   return {
     dispatchId,
@@ -381,13 +405,42 @@ function release(dispatchId) {
     _pump();
     return true;
   }
+  if (_draining) {
+    try { worker.close(); } catch { /* already torn down */ }
+    _trace(`dispatch=${dispatchId} release: draining, worker=${worker.id} closed`);
+    return true;
+  }
   _free.push(worker);
   _trace(`dispatch=${dispatchId} release: worker=${worker.id} returned to free set`);
   _pump();
   return true;
 }
 
+function beginDrain() {
+  if (_draining) return;
+  _draining = true;
+  for (const req of _queue.splice(0)) {
+    try { req.reject(new Error('agent-worker-pool: draining')); } catch { /* already settled */ }
+  }
+  for (const worker of _free.splice(0)) {
+    try { worker.close(); } catch { /* already torn down */ }
+  }
+}
+
+function isDraining() {
+  return _draining;
+}
+
+function isDrained() {
+  return _busy.size === 0 && _reserved === 0;
+}
+
+function getActiveLeaseIds() {
+  return [..._busy.keys()];
+}
+
 function shutdown() {
+  _draining = true;
   for (const req of _queue.splice(0)) {
     _clearLeaseContext(req.dispatchId);
     try { req.reject(new Error('agent-worker-pool: shutdown')); } catch { /* swallow */ }
@@ -408,6 +461,10 @@ module.exports = {
   release,
   setPoolSize,
   getPoolSize,
+  beginDrain,
+  isDraining,
+  isDrained,
+  getActiveLeaseIds,
   shutdown,
   DEFAULT_POOL_SIZE,
   // Exposed for unit tests; engine code MUST go through the public API.

package/engine/bridge.js

@@ -1,11 +1,10 @@
 /**
  * engine/bridge.js — Constellation-bridge config + marker accessors.
  *
- * Pure helpers for the `minions bridge ...` subcommand and any future
- * code that wants to inspect or mutate the read-only Constellation bridge
- * surface. The bridge polling logic itself lives in the Constellation
- * repo (P-wi1-bridge-readonly) — this file owns ONLY the on/off flag, the
- * marker-file contract, and atomic config writes for the toggle.
+ * Pure helpers for the `minions bridge ...` subcommand and the versioned
+ * metadata snapshot consumed by Constellation. Minions remains authoritative:
+ * the Constellation agent polls the local dashboard and mirrors only the
+ * allowlisted projection returned by buildBridgeSnapshot().
  *
  * Strict semantics: only the literal boolean `true` enables the bridge.
  * Mirror this check on the Constellation reader to avoid truthy coercion
@@ -24,6 +23,258 @@ const {
 } = shared;
 
 const CONFIG_PATH = path.join(MINIONS_DIR, 'config.json');
+const BRIDGE_SNAPSHOT_PROTOCOL = 'minions.constellation.snapshot';
+const BRIDGE_SNAPSHOT_PROTOCOL_VERSION = 1;
+
+const SNAPSHOT_CAPS = Object.freeze({
+  id: 128,
+  status: 128,
+  agent: 128,
+  title: 512,
+  project: 128,
+  url: 2048,
+  timestamp: 64,
+  shortLabel: 128,
+  branch: 255,
+  name: 128,
+});
+const INACTIVE_AGENT_STATUSES = new Set(['idle', 'available', 'sleeping']);
+
+function _string(value, max, fallback = null) {
+  if (typeof value !== 'string') return fallback;
+  const trimmed = value.trim();
+  if (!trimmed) return fallback;
+  return trimmed.slice(0, max);
+}
+
+function _isoTime(value) {
+  if (value === null || value === undefined || value === '') return undefined;
+  const ms = typeof value === 'number' ? value : Date.parse(String(value));
+  if (!Number.isFinite(ms)) return undefined;
+  return new Date(ms).toISOString().slice(0, SNAPSHOT_CAPS.timestamp);
+}
+
+function _defined(obj) {
+  return Object.fromEntries(Object.entries(obj).filter(([, value]) => value !== undefined));
+}
+
+function _projectList(items, projector) {
+  if (!Array.isArray(items)) return [];
+  const projected = [];
+  for (const item of items) {
+    if (!item || typeof item !== 'object') continue;
+    const value = projector(item);
+    if (value) projected.push(value);
+  }
+  return projected;
+}
+
+function _projectWorkItem(item) {
+  const id = _string(item.id, SNAPSHOT_CAPS.id);
+  if (!id) return null;
+  return _defined({
+    id,
+    title: _string(item.title, SNAPSHOT_CAPS.title, id),
+    type: _string(item.type, SNAPSHOT_CAPS.shortLabel) || undefined,
+    priority: _string(item.priority, SNAPSHOT_CAPS.shortLabel) || undefined,
+    status: _string(item.status, SNAPSHOT_CAPS.status, 'unknown'),
+    project: _string(item.project, SNAPSHOT_CAPS.project) || undefined,
+    agent: _string(item.agent, SNAPSHOT_CAPS.agent) || undefined,
+    createdBy: _string(item.createdBy, SNAPSHOT_CAPS.shortLabel) || undefined,
+    created: _isoTime(item.created),
+    dispatched_to: _string(item.dispatched_to, SNAPSHOT_CAPS.agent) || undefined,
+    dispatched_at: _isoTime(item.dispatched_at),
+    completedAt: _isoTime(item.completedAt || item.completed_at),
+  });
+}
+
+function _projectPullRequest(pr) {
+  const id = _string(pr.id, SNAPSHOT_CAPS.id);
+  const prNumber = Number(pr.prNumber);
+  const url = _string(pr.url, SNAPSHOT_CAPS.url);
+  if (!id || !url || !Number.isInteger(prNumber) || prNumber < 0) return null;
+  return _defined({
+    id,
+    prNumber,
+    title: _string(pr.title, SNAPSHOT_CAPS.title, id),
+    agent: _string(pr.agent, SNAPSHOT_CAPS.agent) || undefined,
+    branch: _string(pr.branch, SNAPSHOT_CAPS.branch) || undefined,
+    reviewStatus: _string(pr.reviewStatus, SNAPSHOT_CAPS.status, 'unknown'),
+    status: _string(pr.status, SNAPSHOT_CAPS.status, 'unknown'),
+    url,
+    created: _isoTime(pr.created),
+    lastReviewedAt: _isoTime(pr.lastReviewedAt),
+    lastPushedAt: _isoTime(pr.lastPushedAt),
+    lastDispatchedAt: _isoTime(pr.lastDispatchedAt),
+    mergeStatus: _string(pr.mergeStatus || pr.mergeStateStatus, SNAPSHOT_CAPS.shortLabel) || undefined,
+    mergeable: typeof pr.mergeable === 'boolean' ? pr.mergeable : undefined,
+    isDraft: typeof pr.isDraft === 'boolean' ? pr.isDraft : undefined,
+    behindBy: Number.isInteger(pr.behindBy) && pr.behindBy >= 0 ? pr.behindBy : undefined,
+  });
+}
+
+function _projectPlan(plan) {
+  const id = _string(plan.id || plan.file, SNAPSHOT_CAPS.id);
+  if (!id) return null;
+  return _defined({
+    id,
+    title: _string(plan.title || plan.summary || plan.plan_summary, SNAPSHOT_CAPS.title, id),
+    status: _string(plan.status, SNAPSHOT_CAPS.status, plan.archived ? 'archived' : 'unknown'),
+    agent: _string(plan.agent || plan.generatedBy || plan.generated_by, SNAPSHOT_CAPS.agent) || undefined,
+    project: _string(plan.project, SNAPSHOT_CAPS.project) || undefined,
+    createdAt: _isoTime(plan.createdAt || plan.generatedAt || plan.generated_at),
+    updatedAt: _isoTime(plan.updatedAt),
+  });
+}
+
+function _projectSchedule(schedule) {
+  const id = _string(schedule.id, SNAPSHOT_CAPS.id);
+  if (!id) return null;
+  return _defined({
+    id,
+    title: _string(schedule.title, SNAPSHOT_CAPS.title, id),
+    status: _string(schedule.status, SNAPSHOT_CAPS.status,
+      schedule.enabled === false ? 'disabled' : 'enabled'),
+    type: _string(schedule.type, SNAPSHOT_CAPS.shortLabel, 'schedule'),
+    project: _string(schedule.project, SNAPSHOT_CAPS.project) || undefined,
+    agent: _string(schedule.agent, SNAPSHOT_CAPS.agent) || undefined,
+    nextRun: _isoTime(schedule.nextRun),
+    lastRun: _isoTime(schedule.lastRun || schedule._lastRun || schedule._lastCompletedAt),
+  });
+}
+
+function _projectDispatch(entry, status) {
+  const id = _string(entry.id, SNAPSHOT_CAPS.id);
+  if (!id) return null;
+  const meta = entry.meta && typeof entry.meta === 'object' ? entry.meta : {};
+  const metaItem = meta.item && typeof meta.item === 'object' ? meta.item : {};
+  const metaProject = meta.project && typeof meta.project === 'object' ? meta.project : {};
+  return _defined({
+    id,
+    agent: _string(entry.agent, SNAPSHOT_CAPS.agent, 'unassigned'),
+    status: _string(entry.status, SNAPSHOT_CAPS.status, status),
+    type: _string(entry.type, SNAPSHOT_CAPS.shortLabel) || undefined,
+    project: _string(entry.project || metaProject.name, SNAPSHOT_CAPS.project) || undefined,
+    workItemId: _string(entry.workItemId || metaItem.id, SNAPSHOT_CAPS.id) || undefined,
+    prId: _string(entry.prId || entry.pr_id, SNAPSHOT_CAPS.id) || undefined,
+    startedAt: _isoTime(entry.startedAt || entry.started_at),
+    completedAt: _isoTime(entry.completedAt || entry.completed_at),
+    outcome: _string(entry.outcome || entry.result, SNAPSHOT_CAPS.shortLabel) || undefined,
+  });
+}
+
+function _projectDispatchQueue(dispatch) {
+  if (!dispatch || typeof dispatch !== 'object') return [];
+  const projected = [];
+  for (const [bucket, status] of [
+    ['pending', 'queued'],
+    ['active', 'active'],
+    ['review', 'review'],
+    ['completed', 'completed'],
+  ]) {
+    const entries = bucket === 'completed' && Array.isArray(dispatch[bucket])
+      ? dispatch[bucket].slice(-20)
+      : dispatch[bucket];
+    projected.push(..._projectList(entries, entry => _projectDispatch(entry, status)));
+  }
+  return projected;
+}
+
+function _projectAgent(agent) {
+  const id = _string(agent.id || agent.agent, SNAPSHOT_CAPS.agent);
+  if (!id) return null;
+  return _defined({
+    agent: id,
+    status: _string(agent.status, SNAPSHOT_CAPS.status, 'unknown'),
+    project: _string(agent.project, SNAPSHOT_CAPS.project) || undefined,
+    currentTaskId: _string(agent.currentTaskId || agent.currentDispatchId, SNAPSHOT_CAPS.id) || undefined,
+    currentTaskTitle: _string(agent.currentTaskTitle || agent.currentTask, SNAPSHOT_CAPS.title) || undefined,
+    updatedAt: _isoTime(agent.updatedAt || agent.lastActionAt),
+  });
+}
+
+/**
+ * Build the complete metadata-only state projection consumed by Constellation.
+ * Every field is copied explicitly so free-text task descriptions, prompts,
+ * completion reports, diffs, comments, paths, logs, and credentials cannot
+ * cross the bridge accidentally.
+ */
+function buildBridgeSnapshot(state = {}) {
+  const generatedAt = _isoTime(state.generatedAt) || new Date().toISOString();
+  const engine = state.control && typeof state.control === 'object' ? state.control : {};
+  const workItems = _projectList(state.workItems, _projectWorkItem);
+  const pullRequests = _projectList(state.pullRequests, _projectPullRequest);
+  const plans = _projectList(state.plans, _projectPlan);
+  const schedules = _projectList(state.schedules, _projectSchedule);
+  const agents = _projectList(state.agents, _projectAgent);
+  const dispatches = _projectDispatchQueue(state.dispatch);
+  const activeAgents = agents.filter(agent => !INACTIVE_AGENT_STATUSES.has(agent.status.toLowerCase())).length;
+  const minionsVersion = _string(state.minionsVersion, SNAPSHOT_CAPS.shortLabel);
+  const engineState = _string(engine.state, SNAPSHOT_CAPS.status, 'unknown');
+  const enginePid = Number.isInteger(engine.pid) && engine.pid > 0 ? engine.pid : null;
+  const projects = Array.isArray(state.projects) ? state.projects : [];
+
+  return {
+    protocol: BRIDGE_SNAPSHOT_PROTOCOL,
+    protocolVersion: BRIDGE_SNAPSHOT_PROTOCOL_VERSION,
+    complete: true,
+    generatedAt,
+    minionsVersion,
+    engine: {
+      state: engineState,
+      pid: enginePid,
+    },
+    entities: {
+      work_item: workItems,
+      pr: pullRequests,
+      plan: plans,
+      schedule: schedules,
+      dispatch: dispatches,
+      agent_status: agents,
+      device_summary: [{
+        name: 'Minions',
+        status: engineState,
+        lastSeen: generatedAt,
+        agentCount: agents.length,
+        activeAgentCount: activeAgents,
+        workItemCount: workItems.length,
+        pullRequestCount: pullRequests.length,
+        planCount: plans.length,
+        scheduleCount: schedules.length,
+        dispatchCount: dispatches.length,
+        projectCount: projects.length,
+        protocolVersion: BRIDGE_SNAPSHOT_PROTOCOL_VERSION,
+        minionsVersion,
+        snapshotGeneratedAt: generatedAt,
+        enginePid,
+      }],
+    },
+  };
+}
+
+function projectSnapshotHealthForBridge(snapshot) {
+  if (!snapshot || typeof snapshot !== 'object') return null;
+  if (snapshot.protocol !== BRIDGE_SNAPSHOT_PROTOCOL) return null;
+  if (snapshot.protocolVersion !== BRIDGE_SNAPSHOT_PROTOCOL_VERSION) return null;
+  if (snapshot.complete !== true || !snapshot.entities || typeof snapshot.entities !== 'object') return null;
+  const entities = snapshot.entities;
+  const summary = Array.isArray(entities.device_summary) ? entities.device_summary[0] || {} : {};
+  const count = key => (Array.isArray(entities[key]) ? entities[key].length : 0);
+  return {
+    protocolVersion: snapshot.protocolVersion,
+    minionsVersion: snapshot.minionsVersion ?? null,
+    engineState: snapshot.engine?.state ?? null,
+    enginePid: snapshot.engine?.pid ?? null,
+    agentCount: count('agent_status'),
+    activeAgentCount: summary.activeAgentCount ?? null,
+    workItemCount: count('work_item'),
+    pullRequestCount: count('pr'),
+    planCount: count('plan'),
+    scheduleCount: count('schedule'),
+    dispatchCount: count('dispatch'),
+    projectCount: summary.projectCount ?? null,
+  };
+}
 
 /**
  * Strict check: `true` ⇔ bridge enabled. Any other shape (missing field,
@@ -118,7 +369,11 @@ module.exports = {
   readBridgeMarker,
   setBridgeEnabled,
   formatRelativeAge,
+  buildBridgeSnapshot,
+  projectSnapshotHealthForBridge,
   projectStatusForBridge,
+  BRIDGE_SNAPSHOT_PROTOCOL,
+  BRIDGE_SNAPSHOT_PROTOCOL_VERSION,
   CONSTELLATION_BRIDGE_MARKER_PATH,
   CONSTELLATION_BRIDGE_MARKER_SCHEMA_VERSION,
 };