@yemi33/minions 0.1.2448 → 0.1.2449

package/engine/api/bridge.js

@@ -0,0 +1,787 @@
+/**
+ * engine/api/bridge.js — Constellation-bridge config + marker accessors.
+ *
+ * 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
+ * silently flipping bridge state on a typo'd `"enabled": "false"`.
+ */
+
+const path = require('path');
+const crypto = require('crypto');
+const shared = require('../core/shared');
+
+const {
+  MINIONS_DIR,
+  CONSTELLATION_BRIDGE_MARKER_PATH,
+  CONSTELLATION_BRIDGE_MARKER_SCHEMA_VERSION,
+  safeJson,
+  mutateJsonFileLocked,
+} = 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,
+  epoch: 64,
+});
+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);
+}
+
+/** Non-negative integer gauge (counts, byte sizes, PIDs) or undefined. */
+function _count(value) {
+  // Strictly a real number: Number(null) is 0 and Number('') is 0, so coercing
+  // here would turn a reserved managed spec's `pid: null` into a live-looking 0.
+  if (typeof value !== 'number' || !Number.isInteger(value) || value < 0) return undefined;
+  return value;
+}
+
+/**
+ * Non-negative fractional gauge (milliseconds, seconds) or undefined. Rounded
+ * to 3 decimals so float noise cannot make an otherwise-identical sample look
+ * like a content change to the entity versioner.
+ */
+function _gauge(value) {
+  if (typeof value !== 'number' || !Number.isFinite(value) || value < 0) return undefined;
+  return Math.round(value * 1000) / 1000;
+}
+
+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 _projectAuthor(author) {
+  const a = shared.normalizePrAuthorIdentity(author);
+  if (!a) return undefined;
+  const projected = _defined({
+    provider: _string(a.provider, SNAPSHOT_CAPS.shortLabel) || undefined,
+    id: _string(a.id, SNAPSHOT_CAPS.shortLabel) || undefined,
+    descriptor: _string(a.descriptor, SNAPSHOT_CAPS.id) || undefined,
+    login: _string(a.login, SNAPSHOT_CAPS.name) || undefined,
+    displayName: _string(a.displayName, SNAPSHOT_CAPS.name) || undefined,
+    url: _string(a.url, SNAPSHOT_CAPS.url) || undefined,
+  });
+  return Object.keys(projected).length ? projected : undefined;
+}
+
+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,
+    author: _projectAuthor(pr.author),
+    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),
+  });
+}
+
+/* ── Extended entity families (Mission Control) ────────────────────────────
+ *
+ * qa_run / pipeline / managed_process / engine_health widen the projection to
+ * the rest of Mission Control's surface. They follow the same rule as every
+ * projector above — each field is copied EXPLICITLY, never spread — and their
+ * sources are the highest-risk records in the engine: a managed-process record
+ * carries `cmd`, `args`, `cwd`, `log_path`, `healthcheck` and free-form
+ * `attrs` (credential-shaped env keys included); a QA run carries a free-text
+ * `summary` and artifact filesystem paths; a pipeline definition carries a
+ * 20 KB free-text `description`, per-stage task prompts and monitored-resource
+ * URLs. None of that may cross the bridge, so none of it is copied.
+ *
+ * OPT-IN, NOT DEFAULT-ON. The Constellation consumer validates `entities` with
+ * a `.strict()` Zod object (packages/shared/src/orchestrator-messages.ts), and
+ * its poller fails CLOSED on a schema error without falling back to the legacy
+ * per-endpoint projection. Emitting an unrequested new kind would therefore
+ * take Mission Control dark for every consumer that has not yet widened its
+ * schema. Callers ask for kinds explicitly; a caller that asks for nothing gets
+ * a byte-identical v1 snapshot. That keeps the additive-field compatibility
+ * rule in docs/constellation-bridge.md true for entity KINDS as well as fields,
+ * so BRIDGE_SNAPSHOT_PROTOCOL_VERSION still does not move.
+ *
+ * Every extended kind uses `id` as its identity field. That is the default
+ * branch of the consumer's getOrchestratorEntityId(), so adopting these kinds
+ * needs no per-kind identity mapping on the Constellation side.
+ */
+
+const EXTENDED_SNAPSHOT_KINDS = Object.freeze([
+  'qa_run',
+  'pipeline',
+  'managed_process',
+  'engine_health',
+]);
+
+// Mirrors packages/shared/src/orchestrator-messages.ts:
+//   ORCHESTRATOR_SNAPSHOT_MAX_ENTITIES_PER_KIND = 10_000
+//   device_summary: z.array(...).max(1)
+// Enforced here so an oversized list is truncated at the producer instead of
+// making the consumer reject the entire snapshot.
+const SNAPSHOT_MAX_ENTITIES_PER_KIND = 10000;
+const SNAPSHOT_SINGLETON_MAX_ENTITIES = 1;
+const SNAPSHOT_SINGLETON_KINDS = new Set(['device_summary', 'engine_health']);
+
+/**
+ * The exact field list each extended projector may emit, in emission order.
+ * This is the machine-readable form of the privacy boundary: a contract test
+ * compares it against the live projection in both directions, so widening a
+ * projection is always a visible diff in this constant.
+ */
+const SNAPSHOT_PROJECTED_FIELDS = Object.freeze({
+  qa_run: Object.freeze([
+    'id', 'runbookId', 'targetName', 'status', 'project', 'workItemId',
+    'artifactCount', 'createdAt', 'startedAt', 'completedAt',
+  ]),
+  pipeline: Object.freeze([
+    'id', 'title', 'status', 'stageCount', 'runCount',
+    'lastRunId', 'lastRunStatus', 'lastRunStartedAt', 'lastRunCompletedAt',
+  ]),
+  managed_process: Object.freeze([
+    'id', 'status', 'alive', 'healthy', 'pid', 'project', 'agent',
+    'workItemId', 'startedAt', 'lastHealthyAt', 'expiresAt',
+  ]),
+  engine_health: Object.freeze([
+    'id', 'state', 'pid', 'startedAt', 'lastTickAt', 'heartbeatAt',
+    'rss', 'heapUsed', 'heapTotal', 'heapSizeLimit', 'external',
+    'eventLoopLagP50', 'eventLoopLagP99', 'eventLoopLagMax',
+    'gcCount', 'gcPausesTotalMs', 'lastGcPauseMs', 'lastGcKind',
+    'uptimeSeconds', 'sampledAt',
+  ]),
+});
+
+/**
+ * Allowlist a caller's requested extended kinds. Unknown names, legacy kind
+ * names, and prototype-shaped strings are dropped rather than echoed, and the
+ * result is ordered by the registry so a given request always produces the
+ * same ETag variant and the same `entities` key order.
+ */
+function resolveSnapshotKinds(requested) {
+  const raw = typeof requested === 'string'
+    ? requested.split(',')
+    : (Array.isArray(requested) ? requested : []);
+  const asked = new Set();
+  for (const entry of raw) {
+    const name = _string(entry, SNAPSHOT_CAPS.shortLabel);
+    if (name) asked.add(name);
+  }
+  return EXTENDED_SNAPSHOT_KINDS.filter(kind => asked.has(kind));
+}
+
+function _projectQaRun(run) {
+  const id = _string(run.id, SNAPSHOT_CAPS.id);
+  if (!id) return null;
+  return _defined({
+    id,
+    runbookId: _string(run.runbookId, SNAPSHOT_CAPS.id) || undefined,
+    targetName: _string(run.targetName, SNAPSHOT_CAPS.name) || undefined,
+    status: _string(run.status, SNAPSHOT_CAPS.status, 'unknown'),
+    project: _string(run.project, SNAPSHOT_CAPS.project) || undefined,
+    workItemId: _string(run.workItemId, SNAPSHOT_CAPS.id) || undefined,
+    // Count only. Artifact records carry filesystem paths and agent-authored
+    // labels; the consumer fetches artifacts from Minions directly when a
+    // human opens the run.
+    artifactCount: _count(Array.isArray(run.artifacts) ? run.artifacts.length : 0),
+    createdAt: _isoTime(run.createdAt),
+    startedAt: _isoTime(run.startedAt),
+    completedAt: _isoTime(run.completedAt),
+  });
+}
+
+function _projectPipeline(pipeline) {
+  const id = _string(pipeline.id, SNAPSHOT_CAPS.id);
+  if (!id) return null;
+  const stages = Array.isArray(pipeline.stages) ? pipeline.stages : [];
+  const runs = Array.isArray(pipeline.runs) ? pipeline.runs : [];
+  // The API merges the last-5 runs oldest-first, so the newest is the tail.
+  const last = runs.length ? runs[runs.length - 1] : null;
+  const lastStatus = last ? _string(last.status, SNAPSHOT_CAPS.status) : null;
+  return _defined({
+    id,
+    // `title` is operator-authored bounded text, exactly like the title already
+    // projected for work_item / pr / plan / schedule. It is the one free-text
+    // class docs/constellation-bridge.md admits; the 20 KB `description`,
+    // per-stage task prompts and monitoredResources URLs are not.
+    title: _string(pipeline.title, SNAPSHOT_CAPS.title, id),
+    // A pipeline definition has no status of its own — its latest run's status
+    // is what an operator means by "how is this pipeline doing". An explicitly
+    // disabled pipeline outranks that: startRun refuses it, so a stale
+    // `completed` would misrepresent it as merely idle between runs.
+    status: pipeline.enabled === false ? 'disabled' : (lastStatus || 'idle'),
+    stageCount: _count(stages.length),
+    runCount: _count(runs.length),
+    lastRunId: last ? (_string(last.runId, SNAPSHOT_CAPS.id) || undefined) : undefined,
+    lastRunStatus: lastStatus || undefined,
+    lastRunStartedAt: last ? _isoTime(last.startedAt) : undefined,
+    lastRunCompletedAt: last ? _isoTime(last.completedAt) : undefined,
+  });
+}
+
+function _projectManagedProcess(spec) {
+  // The spec's name IS its identity; `id` (rather than `name`) keeps the
+  // consumer's default entity-id resolver working with no per-kind mapping.
+  const id = _string(spec.name, SNAPSHOT_CAPS.name);
+  if (!id) return null;
+  const alive = spec.alive === true;
+  const healthy = spec.healthy === true;
+  return _defined({
+    id,
+    status: !alive ? 'stopped' : (healthy ? 'healthy' : 'unhealthy'),
+    alive,
+    healthy,
+    pid: _count(spec.pid),
+    project: _string(spec.owner_project, SNAPSHOT_CAPS.project) || undefined,
+    agent: _string(spec.owner_agent, SNAPSHOT_CAPS.agent) || undefined,
+    workItemId: _string(spec.owner_wi, SNAPSHOT_CAPS.id) || undefined,
+    startedAt: _isoTime(spec.started_at),
+    lastHealthyAt: _isoTime(spec.last_health_at),
+    expiresAt: _isoTime(spec.ttl_expires_at),
+  });
+}
+
+/**
+ * Singleton health summary for the engine process: liveness plus the memory,
+ * event-loop and GC gauges sampled by the memoryBaseline tick phase. All
+ * numeric — the only string fields are the engine state and the GC kind, both
+ * closed vocabularies capped through _string().
+ */
+function _projectEngineHealth(engine, memory) {
+  const sample = memory && typeof memory === 'object' ? memory : {};
+  return _defined({
+    id: 'engine',
+    state: _string(engine.state, SNAPSHOT_CAPS.status, 'unknown'),
+    pid: Number.isInteger(engine.pid) && engine.pid > 0 ? engine.pid : null,
+    startedAt: _isoTime(engine.started_at || engine.startedAt),
+    // The engine has no persisted tick counter; lastTickAt is the observable
+    // tick signal, and it deliberately participates in the content hash so a
+    // consumer can see the engine ticking via changeVersion.
+    lastTickAt: _isoTime(engine.lastTickAt),
+    heartbeatAt: _isoTime(engine.heartbeat),
+    rss: _count(sample.rss),
+    heapUsed: _count(sample.heapUsed),
+    heapTotal: _count(sample.heapTotal),
+    heapSizeLimit: _count(sample.heapSizeLimit),
+    external: _count(sample.external),
+    eventLoopLagP50: _gauge(sample.eventLoopLagP50),
+    eventLoopLagP99: _gauge(sample.eventLoopLagP99),
+    eventLoopLagMax: _gauge(sample.eventLoopLagMax),
+    gcCount: _count(sample.gcCount),
+    gcPausesTotalMs: _gauge(sample.gcPausesTotalMs),
+    lastGcPauseMs: _gauge(sample.lastGcPauseMs),
+    lastGcKind: _string(sample.lastGcKind, SNAPSHOT_CAPS.shortLabel) || undefined,
+    uptimeSeconds: _gauge(sample.uptime),
+    sampledAt: _isoTime(sample.capturedAt),
+  });
+}
+
+/** Route one extended kind to its projector. */
+function _projectExtendedKind(kind, state, engine) {
+  switch (kind) {
+    case 'qa_run': return _projectList(state.qaRuns, _projectQaRun);
+    case 'pipeline': return _projectList(state.pipelines, _projectPipeline);
+    case 'managed_process': return _projectList(state.managedProcesses, _projectManagedProcess);
+    case 'engine_health': return [_projectEngineHealth(engine, state.memory)];
+    default: return [];
+  }
+}
+
+/* ── Snapshot ordering tokens (additive; NOT a protocolVersion bump) ───────
+ *
+ * `snapshotVersion` is a counter that is monotonically non-decreasing for the
+ * lifetime of one Minions process. It advances only when the *projected*
+ * content of at least one entity was added, removed, or modified, so a
+ * consumer can order two polls with an integer compare instead of diffing
+ * whole snapshots. Each entity additionally carries the `changeVersion` at
+ * which its own content hash last changed, so a consumer can skip re-applying
+ * entities it already mirrors.
+ *
+ * `epoch` identifies the process that owns the counter. The counter is
+ * in-memory, so it resets with the process; a consumer that sees a new `epoch`
+ * must discard its cached versions and take the full snapshot rather than
+ * mis-comparing numbers across the reset.
+ *
+ * All three fields are additive and optional, which per the compatibility rule
+ * in docs/constellation-bridge.md ("protocolVersion changes only for a
+ * breaking schema change. Additive optional fields do not require a version
+ * bump") means BRIDGE_SNAPSHOT_PROTOCOL_VERSION deliberately does NOT move.
+ *
+ * WHY THIS IS NOT BUILT ON THE `events` TABLE — which already backs this
+ * endpoint's HTTP ETag and keeps doing so, unchanged:
+ *   1. Its rows are payload-less for exactly the entities projected here. The
+ *      emitStateEvent calls in the work-item store, the pull-request store and
+ *      the dispatch queue pass a topic string only — no entity id, no
+ *      before/after payload — so a per-entity delta cannot be reconstructed
+ *      from them at all.
+ *   2. Emission is best-effort by hard contract: engine/persistence/db-events.js
+ *      swallows every SQLite failure (logging once per process) so that a state
+ *      writer can never throw from a cache-invalidation side effect. The id
+ *      sequence can therefore gap silently, and a consumer would be unable to
+ *      tell "nothing changed" apart from "the emit failed".
+ * Hashing the projected content is immune to both: it is exactly as correct as
+ * the projection itself, and it needs no database access.
+ */
+
+const SNAPSHOT_EPOCH = [
+  process.pid.toString(36),
+  Date.now().toString(36),
+  crypto.randomBytes(4).toString('hex'),
+].join('-').slice(0, SNAPSHOT_CAPS.epoch);
+
+/*
+ * Identity + content rules per entity kind. `volatile` fields are stamped from
+ * the snapshot's own generation time rather than describing the entity, so they
+ * are excluded from the content hash — otherwise every poll would look like a
+ * change and the counter would carry no signal at all.
+ */
+const ENTITY_VERSION_RULES = Object.freeze({
+  work_item: { identity: 'id', volatile: [] },
+  pr: { identity: 'id', volatile: [] },
+  plan: { identity: 'id', volatile: [] },
+  schedule: { identity: 'id', volatile: [] },
+  dispatch: { identity: 'id', volatile: [] },
+  agent_status: { identity: 'agent', volatile: [] },
+  device_summary: { identity: 'name', volatile: ['lastSeen', 'snapshotGeneratedAt'] },
+  qa_run: { identity: 'id', volatile: [] },
+  pipeline: { identity: 'id', volatile: [] },
+  managed_process: { identity: 'id', volatile: [] },
+  engine_health: { identity: 'id', volatile: [] },
+});
+// Fail-safe for a future entity kind whose rule was not registered above: `id`
+// with no volatile fields is correct for every kind projected today, so a miss
+// degrades to a slightly noisier version rather than crashing the snapshot.
+const DEFAULT_ENTITY_VERSION_RULE = Object.freeze({ identity: 'id', volatile: [] });
+
+let _snapshotVersion = 0;
+let _entityVersionLedger = new Map();
+
+function _canonical(value) {
+  if (Array.isArray(value)) return value.map(_canonical);
+  if (value && typeof value === 'object') {
+    const sorted = {};
+    for (const key of Object.keys(value).sort()) sorted[key] = _canonical(value[key]);
+    return sorted;
+  }
+  return value;
+}
+
+/** Stable hash of a projected entity's content, independent of key order. */
+function _contentHash(entity, volatileFields) {
+  const subject = { ...entity };
+  for (const field of volatileFields) delete subject[field];
+  return crypto.createHash('sha256').update(JSON.stringify(_canonical(subject))).digest('hex');
+}
+
+/**
+ * Stamp every projected entity with the version at which its content last
+ * changed, and advance the process-wide snapshot version when the ledger of
+ * (identity → content hash) pairs differs from the previous poll. Returns a
+ * new entities map; the inputs are not mutated. The ledger is rebuilt from the
+ * current snapshot on every call, so it stays bounded by the live entity count.
+ *
+ * A kind that is ABSENT from this snapshot is UNKNOWN, not empty: its ledger
+ * entries are carried forward untouched. Extended kinds are opt-in, so the same
+ * process serves both narrow polls (`bridge health`, an unwidened consumer) and
+ * wide ones. Rebuilding the ledger from only the present kinds would make every
+ * extended entity look newly-changed on the next wide poll and would advance
+ * snapshotVersion on every alternation — a phantom-change generator driven by
+ * who asked last, not by what changed.
+ */
+function _applyEntityVersions(entities) {
+  const candidate = _snapshotVersion + 1;
+  const ledger = new Map();
+  const versioned = {};
+  const presentKinds = new Set(Object.keys(entities));
+  let changed = false;
+
+  // Carry forward the kinds this snapshot did not report on.
+  for (const [key, entry] of _entityVersionLedger) {
+    if (!presentKinds.has(key.slice(0, key.indexOf('\u0000')))) ledger.set(key, entry);
+  }
+
+  for (const [kind, list] of Object.entries(entities)) {
+    const rule = ENTITY_VERSION_RULES[kind] || DEFAULT_ENTITY_VERSION_RULE;
+    versioned[kind] = _capEntities(kind, list).map((entity, index) => {
+      const identity = _string(entity[rule.identity], SNAPSHOT_CAPS.id) || `#${index}`;
+      const key = `${kind}\u0000${identity}`;
+      const hash = _contentHash(entity, rule.volatile);
+      const previous = _entityVersionLedger.get(key);
+      const unchanged = previous !== undefined && previous.hash === hash;
+      if (!unchanged) changed = true;
+      const changeVersion = unchanged ? previous.changeVersion : candidate;
+      ledger.set(key, { hash, changeVersion });
+      return { ...entity, changeVersion };
+    });
+  }
+
+  // Additions and modifications already flipped the flag above; a shrunk ledger
+  // is the remaining way the map can differ. Dropping an entity IS a change —
+  // this snapshot is a complete replacement, so a consumer has to unmirror it.
+  // Carried-forward entries are on both sides of this comparison, so an absent
+  // kind cannot masquerade as a removal.
+  if (!changed && ledger.size !== _entityVersionLedger.size) changed = true;
+
+  if (changed) _snapshotVersion = candidate;
+  _entityVersionLedger = ledger;
+  return versioned;
+}
+
+/**
+ * Truncate a kind's list to the ceiling the Constellation consumer enforces.
+ * Over-cap lists are rejected wholesale on the consumer side, so silently
+ * dropping the tail here degrades to "fewer entities" instead of "no snapshot".
+ * Callers supply the list already in their preferred order.
+ */
+function _capEntities(kind, list) {
+  const cap = SNAPSHOT_SINGLETON_KINDS.has(kind)
+    ? SNAPSHOT_SINGLETON_MAX_ENTITIES
+    : SNAPSHOT_MAX_ENTITIES_PER_KIND;
+  return list.length > cap ? list.slice(0, cap) : list;
+}
+
+/**
+ * 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.
+ *
+ * `options.extendedKinds` opts into the Mission Control entity families
+ * (EXTENDED_SNAPSHOT_KINDS). Omitting it yields a byte-identical v1 snapshot.
+ */
+function buildBridgeSnapshot(state = {}, options = {}) {
+  const extendedKinds = resolveSnapshotKinds(options && options.extendedKinds);
+  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 : [];
+
+  const entities = _applyEntityVersions({
+    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,
+    }],
+    ...Object.fromEntries(extendedKinds.map(kind => [kind, _projectExtendedKind(kind, state, engine)])),
+  });
+
+  return {
+    protocol: BRIDGE_SNAPSHOT_PROTOCOL,
+    protocolVersion: BRIDGE_SNAPSHOT_PROTOCOL_VERSION,
+    complete: true,
+    generatedAt,
+    minionsVersion,
+    snapshotVersion: _snapshotVersion,
+    epoch: SNAPSHOT_EPOCH,
+    engine: {
+      state: engineState,
+      pid: enginePid,
+    },
+    entities,
+  };
+}
+
+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,
+ * non-object, string "true", etc.) returns false.
+ */
+function isBridgeEnabled(config) {
+  return config?.engine?.constellationBridge?.enabled === true;
+}
+
+/**
+ * Read the cross-repo marker written by the Constellation agent. Returns
+ * `null` when the file is missing, unreadable, or schema-mismatched.
+ *
+ * Marker shape (see ENGINE_DEFAULTS.constellationBridge docstring):
+ *   { schemaVersion: 1, lastSeenAt: ISO8601,
+ *     agentVersion?: string, source?: 'constellation-agent' }
+ */
+function readBridgeMarker(markerPath = CONSTELLATION_BRIDGE_MARKER_PATH) {
+  const raw = safeJson(markerPath);
+  if (!raw || typeof raw !== 'object' || Array.isArray(raw)) return null;
+  if (raw.schemaVersion !== CONSTELLATION_BRIDGE_MARKER_SCHEMA_VERSION) return null;
+  if (typeof raw.lastSeenAt !== 'string') return null;
+  return {
+    schemaVersion: raw.schemaVersion,
+    lastSeenAt: raw.lastSeenAt,
+    agentVersion: typeof raw.agentVersion === 'string' ? raw.agentVersion : null,
+    source: typeof raw.source === 'string' ? raw.source : null,
+  };
+}
+
+/**
+ * Flip `config.engine.constellationBridge.enabled` atomically via
+ * mutateJsonFileLocked. Returns `{ previous: bool, current: bool }`.
+ * `configPath` override exists for unit tests.
+ */
+function setBridgeEnabled(enabled, configPath = CONFIG_PATH) {
+  const next = enabled === true;
+  let previous = false;
+  mutateJsonFileLocked(configPath, (cfg) => {
+    if (!cfg || typeof cfg !== 'object' || Array.isArray(cfg)) return cfg;
+    cfg.engine = cfg.engine || {};
+    cfg.engine.constellationBridge = cfg.engine.constellationBridge || {};
+    previous = cfg.engine.constellationBridge.enabled === true;
+    cfg.engine.constellationBridge.enabled = next;
+    return cfg;
+  });
+  return { previous, current: next };
+}
+
+/**
+ * Human-readable relative age string (e.g. "12s ago", "3m ago", "2h ago").
+ * Caps at "1d+ ago" — anything older than the bridge polling cadence is
+ * already actionable as "stale".
+ */
+function formatRelativeAge(isoTimestamp, nowMs = Date.now()) {
+  const t = Date.parse(isoTimestamp);
+  if (!Number.isFinite(t)) return '(unknown)';
+  const deltaSec = Math.max(0, Math.round((nowMs - t) / 1000));
+  if (deltaSec < 60) return `${deltaSec}s ago`;
+  if (deltaSec < 3600) return `${Math.round(deltaSec / 60)}m ago`;
+  if (deltaSec < 86400) return `${Math.round(deltaSec / 3600)}h ago`;
+  return '1d+ ago';
+}
+
+/**
+ * Compose the small stable projection the Constellation bridge consumes
+ * from `/api/status`. Kept narrow on purpose: full /api/status is large,
+ * unstable, and may surface unrelated local state. New fields go behind
+ * a deliberate schema version bump.
+ */
+function projectStatusForBridge(statusJson) {
+  if (!statusJson || typeof statusJson !== 'object') return null;
+  const dispatch = statusJson.dispatch || {};
+  const queueCount = (arr) => (Array.isArray(arr) ? arr.length : 0);
+  return {
+    engineState: statusJson.control?.state ?? null,
+    enginePid: statusJson.control?.pid ?? null,
+    minionsVersion: statusJson.version ?? null,
+    agentCount: Array.isArray(statusJson.agents) ? statusJson.agents.length : null,
+    activeAgentCount: Array.isArray(statusJson.agents)
+      ? statusJson.agents.filter(a => a && a.status && a.status !== 'idle').length
+      : null,
+    dispatchPending: queueCount(dispatch.pending),
+    dispatchActive: queueCount(dispatch.active),
+    dispatchCompleted: queueCount(dispatch.completed),
+    projectCount: Array.isArray(statusJson.projects) ? statusJson.projects.length : null,
+  };
+}
+
+module.exports = {
+  isBridgeEnabled,
+  readBridgeMarker,
+  setBridgeEnabled,
+  formatRelativeAge,
+  buildBridgeSnapshot,
+  projectSnapshotHealthForBridge,
+  projectStatusForBridge,
+  resolveSnapshotKinds,
+  BRIDGE_SNAPSHOT_PROTOCOL,
+  BRIDGE_SNAPSHOT_PROTOCOL_VERSION,
+  EXTENDED_SNAPSHOT_KINDS,
+  SNAPSHOT_PROJECTED_FIELDS,
+  SNAPSHOT_MAX_ENTITIES_PER_KIND,
+  SNAPSHOT_SINGLETON_MAX_ENTITIES,
+  CONSTELLATION_BRIDGE_MARKER_PATH,
+  CONSTELLATION_BRIDGE_MARKER_SCHEMA_VERSION,
+};