@yemi33/minions 0.1.2448 → 0.1.2449

package/docs/dev-composite-workflow.md

@@ -1,101 +0,0 @@
-# Dev composite branch + dev-dashboard workflow
-
-This documents the recurring "rebuild the composite branch from all my open PRs and
-relaunch the dev dashboard" workflow. It exists because the flow is otherwise
-reconstructed from `git reflog` every time. The [`rebuild-composite`](../.claude/skills/rebuild-composite/SKILL.md)
-skill and [`scripts/rebuild-composite.ps1`](../scripts/rebuild-composite.ps1) automate it.
-
-## What the composite branch is
-
-`composite/calebt-prs` is a throwaway integration branch: `origin/main` plus every
-one of an operator's currently-open PRs merged on top, so the whole in-flight set can
-be exercised together in one running dev instance. It is **rebuilt from scratch each
-time** (hard reset to `origin/main`, then re-merge each open PR) — never fast-forwarded
-and never pushed. Because of the hard reset, **anything committed only to
-`composite/calebt-prs` is discarded on the next rebuild**; durable changes (like this
-doc, the skill, and the script) must land on `main` via a normal PR.
-
-## The rebuild flow
-
-1. Confirm you are on `composite/calebt-prs` and note any dirty tracked files.
-2. Stash dirty tracked edits (see "Rogue dev edits" below) — do **not** discard them.
-3. `git fetch origin --prune`.
-4. Enumerate the operator's open PRs against `main`:
-   `gh pr list --repo <owner/repo> --state open --author <login> --base main --json number,headRefName`.
-5. `git reset --hard origin/main`.
-6. Merge each PR's head branch (`origin/<headRefName>`) in ascending PR-number order
-   with `git merge --no-edit`. Resolve conflicts, then `git commit --no-edit`.
-7. `node --check` the touched `.js` files.
-8. Relaunch the dev dashboard (see "Relaunching the dev dashboard").
-
-## Recurring merge conflicts
-
-Two conflicts have recurred on essentially every rebuild. Both are **clean additive**
-conflicts (two branches append to the same spot); the resolution is always "keep both
-sides". The canonical resolutions:
-
-### `bin/minions.js` (from the `agent rekey` PR, e.g. #412)
-
-`main` adds an `else if (cmd === 'state')` command block; the PR adds an
-`else if (cmd === 'agent')` block at the same location. **Keep both** — the `state`
-block first, then the `agent` block, then continue to the existing `doctor` block.
-Simply delete the three conflict markers (`<<<<<<<`, `|||||||`/`=======`, `>>>>>>>`);
-no lines between the sides need to be dropped.
-
-### `dashboard/slim/styles.css` (from the slim-ux Engine-embed PR, e.g. #896)
-
-`main` has the `#slim-settings-modal` block; the PR adds `.slim-engine-embed,` to the
-front of the `.slim-*-embed` selector group. **Keep both** — the settings-modal block,
-then `.slim-engine-embed,`, then the existing `.slim-work-embed, …` group.
-
-> **Strongly recommended: `git rerere`.** These resolutions are byte-identical every
-> rebuild. Enabling `git config rerere.enabled true` records each resolution once and
-> replays it automatically on every subsequent rebuild, so the conflicts resolve
-> themselves. The rerere cache lives in `.git/` and therefore survives the hard reset.
-
-Stop and resolve manually only when a **new** conflict (any other path) appears.
-
-## Relaunching the dev dashboard
-
-`--dev` mode runs the current checkout **as** the runtime root (`MINIONS_HOME = checkout`)
-with the dashboard on port **7332** (default) so it coexists with a global install on
-7331. See `bin/minions.js` (`--dev` / `--dev-port`).
-
-Rebuild is not a compile step — the dashboard SPA is reassembled at startup — so
-"rebuild + relaunch" is just a dev restart:
-
-```powershell
-node bin/minions.js --dev restart   # or: npm run dev
-```
-
-### Restart-under-load gotchas
-
-When the box is saturated (e.g. the dev fleet is running the full test suite), the
-`--dev restart` health verifier can **fast-fail**: the freshly spawned engine can't
-write its pid file inside the verifier's short window, so it is reported
-`state=stopped, pid=none`, the partial stack is torn down, and `engine/stop-intent.json`
-is set — which then blocks the next start, creating a loop. A **stray orphaned
-`dashboard.js`** from an earlier attempt independently trips the verifier's
-duplicate-daemon check.
-
-Reliable recovery:
-
-1. Stop any stray `engine.js` / `dashboard.js` / `supervisor.js` daemons (leave
-   `dispatch-*` agent processes and their worktree children alone — those are detached
-   agents that reattach on the next start).
-2. Delete `engine/stop-intent.json`.
-3. Confirm nothing is listening on the dev port.
-4. Start with `node bin/minions.js --dev start` — from a clean state this is more
-   reliable than `restart` under load.
-5. Verify: `GET http://localhost:7332/api/status` returns HTTP 200.
-
-The engine itself boots fine under load (a foreground `node engine.js` stays healthy);
-the fragility is only in the restart verifier's fast-fail path.
-
-## Rogue dev edits
-
-Because `--dev` uses the checkout as the runtime root, the dev fleet's own agents
-sometimes edit **tracked** files in place (e.g. `dashboard/js/settings.js`, docs, even
-reverting `README.md`). These show up as dirty tracked files before a rebuild. This is
-expected, not corruption — stash them (with a dated message) rather than discarding, so
-nothing is lost, then rebuild.

package/docs/visual-evidence-ci.md

@@ -1,103 +0,0 @@
-# PR visual evidence CI
-
-The OPG GitHub workflow captures matched dashboard screenshots for pull requests that change visual dashboard inputs. It compares live base and head checkouts; it never compares a committed demo image with a live PR.
-
-## Triggering
-
-`Visual evidence capture` runs automatically when a PR changes:
-
-- `dashboard/**`
-- `dashboard-build.js`
-- `docs/capture-demos.js`
-- `test/seed-demo-data.js`
-
-Add the `visual-evidence` label to opt in a visual change outside that list. Removing the label removes the opt-in. Backend, test-only, prose-only, and documentation-only PRs do not start browsers unless explicitly labeled.
-
-## Capture contract
-
-The capture workflow:
-
-1. Resolves the exact PR, repository, base, and head tuple from the trusted `pull_request_target` event and records it with the workflow run ID and attempt. The request builder comes from the exact `github.workflow_sha` revision, so an older PR base that predates the controller records a `controller-not-on-base` opt-out instead of failing the plan.
-2. Captures and uploads BEFORE in a base-only job.
-3. Starts the separate head job only after BEFORE has been uploaded, then runs the untrusted dashboard in a capability-dropped container with a read-only root/source/controller and one writable marker-owned state mount. The trusted host owns the browser and AFTER output.
-4. Seeds marker-owned state directories with the same deterministic demo fixture.
-5. Starts each checkout on the same port and captures it with the base branch's canonical [`capture-demos.js`](capture-demos.js).
-6. Uses Chromium at 1400x900, dark theme, `en-US`, UTC, reduced motion, and a fixed browser time.
-7. Requires the same ten non-empty PNG names on both sides.
-
-Startup, fixture, and capture logs are retained with the images. Partial output is never presented as a successful comparison: a failed AFTER side fails the run, and a failed BEFORE side degrades the run to an explicitly-labelled AFTER-only publication (see [Degraded AFTER-only runs](#degraded-after-only-runs)).
-
-## Artifacts and PR summary
-
-GitHub Actions stores five artifacts keyed by PR number and full head SHA:
-
-- capture-request metadata
-- BEFORE PNG set
-- AFTER PNG set
-- BEFORE logs and `result.json`
-- AFTER logs and `result.json`
-
-Artifacts expire after **14 days**. Each upload replaces its same-run name on a rerun, so a later attempt refreshes all five artifacts instead of colliding with the prior attempt. The trusted publisher creates or updates one `github-actions[bot]` comment with BEFORE/AFTER artifact links. All publisher jobs serialize globally through GitHub Actions' multi-entry concurrency queue before mutating PR comments, so a newly queued publisher does not replace an already-pending publication. Each publisher also checks the authoritative workflow-run order before changing comments. Older runs and attempts are suppressed even when a newer opt-out run left no summary. Results for an obsolete head are suppressed when a current result exists; an already-posted result is marked stale when its head no longer matches. If the current PR diff no longer requests visual evidence, the old bot summary is removed.
-
-## Degraded AFTER-only runs
-
-`capture-before` checks out `github.event.pull_request.base.sha` and runs the **base branch's** seed and capture code, not the pull request's. A defect already merged to `main` therefore breaks the BEFORE side of every PR opened against that base — including the PR that repairs the base, which could otherwise never show a green check.
-
-The BEFORE side is consequently non-blocking:
-
-- `capture-before` carries `continue-on-error: true` and is named `Capture BEFORE (base, non-blocking)`, the same convention `pr-tests.yml` uses for its non-blocking `perf-tests` job. The failure surfaces as a warning annotation plus a job summary that names the base SHA and states the run is AFTER-only; it does not present a blocking red check on the PR.
-- `Upload BEFORE screenshots` uses `if-no-files-found: warn`, so a crashed capture that wrote zero PNGs is reported once by the capture step instead of raising a second hard error. `Upload BEFORE capture logs` deliberately stays `if-no-files-found: error` — the logs directory is always written and is what makes the failure diagnosable.
-- `capture-after` is gated on `!cancelled() && needs.plan.outputs.capture == 'true'` instead of a successful `capture-before`, so the head-side capture still runs and uploads. The plan gate is re-asserted directly because it is no longer inherited through a green BEFORE job, and `!cancelled()` keeps a run superseded by `cancel-in-progress` from spending a full Docker and Playwright capture.
-
-The publisher degrades in step. When the run concludes successfully and the BEFORE PNG set is the *only* missing artifact, `assessArtifacts` returns `status: 'after-only'` and the bot comment is titled **"Visual evidence: AFTER only (BEFORE capture failed)"**. It states that this is not a BEFORE/AFTER comparison, renders the BEFORE cell as `capture failed - no screenshots`, and links the BEFORE logs for diagnosis. Any other gap — a missing AFTER set, missing BEFORE logs, duplicate artifacts, or a genuinely failed run — still reports the full failure summary. A reviewer is never handed a half-capture presented as a matched pair.
-
-Nothing about the security posture changes: the controller and base checkout still run from the trusted base ref with `persist-credentials: false`, `Verify exact base checkout` is unchanged, and untrusted head code gains no execution privileges.
-
-## Security boundary
-
-The workflow definition and capture-request builder run from the exact trusted `github.workflow_sha` revision through `pull_request_target`; detection and capture execution remain pinned to the PR's trusted base SHA. If that historical base does not contain the controller, detection suppresses both browser jobs while the trusted workflow revision still records the opt-out request artifact. Neither planning path loads controller code from the untrusted head. The workflow has only `contents: read` and `pull-requests: read`, checkout credentials are not persisted, and no write-capable token is available. BEFORE and AFTER use separate runners, and AFTER cannot start until the immutable BEFORE artifact has uploaded. The head dashboard runs without the Actions process environment, host process namespace, controller checkout, screenshot output, or Docker socket; its source/controller mounts and container root are read-only. The sole writable bind mount is marker-owned `/state`, and the container runs as the host UID:GID that owns it. Secret-shaped variables and GitHub Actions control-file variables are removed from host capture child processes.
-
-Comment publication happens later in `visual-evidence-publish.yml`, triggered by `workflow_run`. That job checks out only the repository default branch and requires a `pull_request_target` run from the trusted base repository. It downloads and parses only the trusted plan job's capture-request JSON, then binds its repository, workflow, stable run ID, PR, base, head repository, base branch, and full head SHA to the live run before writing. A request retained from an earlier attempt is valid for a selective rerun of that same run ID, while metadata claiming a future attempt is rejected. The run's `head_sha` is the captured PR head; publication does not depend on the optional `workflow_run.pull_requests` association. Screenshot and log artifacts remain link-only and are never downloaded or executed by the publisher.
-
-## Base-controller failure mode
-
-Because the seeder (`test/seed-demo-data.js`) and Playwright controller (`docs/capture-demos.js`) always execute from the base checkout, a break in either one is only observable once it is on `main`: every subsequent BEFORE capture fails, for every PR, and no change on a PR branch can repair it — the PR's own copy is never executed. Both files are also visual paths, so even a PR that fixes them triggers the broken capture. Since `capture-before` is non-blocking, the visible symptom is that every PR degrades to an AFTER-only publication (see [Degraded AFTER-only runs](#degraded-after-only-runs)) until the fix lands. Recovery is to land the fix on `main` (admin bypass) and then push to the affected PRs so a fresh `pull_request_target` event picks up a base SHA that contains it. `test/unit/visual-evidence-ci.test.js` runs the seeder's full seeding body so this class of break fails PR Tests before it can reach `main`.
-
-## Local reproduction
-
-Start from a trusted checkout of the base branch, never the pull request/head checkout. Resolve the exact full base and head SHAs independently, then use two disposable worktrees and keep output outside both:
-
-```bash
-BASE_WORKTREE=../visual-base
-HEAD_WORKTREE=../visual-head
-OUTPUT_ROOT=../visual-output
-git worktree add --detach "$BASE_WORKTREE" <full-base-sha>
-git worktree add --detach "$HEAD_WORKTREE" <full-head-sha>
-test "$(git -C "$BASE_WORKTREE" rev-parse HEAD)" = "<full-base-sha>"
-test "$(git -C "$HEAD_WORKTREE" rev-parse HEAD)" = "<full-head-sha>"
-npm --prefix "$BASE_WORKTREE" ci --ignore-scripts
-npm --prefix "$BASE_WORKTREE" exec -- playwright install chromium
-node "${BASE_WORKTREE}/.github/scripts/run-visual-evidence.js" \
-  --dashboard-runtime docker \
-  --controller-root "$BASE_WORKTREE" \
-  --base-root "$BASE_WORKTREE" \
-  --head-root "$HEAD_WORKTREE" \
-  --base-sha <full-base-sha> \
-  --head-sha <full-head-sha> \
-  --output-root "$OUTPUT_ROOT"
-```
-
-The PNGs land in `../visual-output/{before,after}` and logs in `../visual-output/logs`. Docker is the default dashboard runtime so neither dashboard checkout executes in the host Node process. The host still executes the runner, fixture seeder, and Playwright controller, all from the exact base worktree; the runner verifies that controller checkout against `--base-sha` before mutating output. `--dashboard-runtime process` is an explicit opt-in for code you trust. The output root must be new, empty, or carry the runner's `.minions-visual-evidence-output` ownership marker, and it must not overlap either checkout or the controller in either direction. Reruns clear only the known generated subdirectories beneath a valid marker-owned root. Remove the disposable worktrees with the normal `git worktree remove` command after inspection.
-
-## Complementary in-description embeds (agent-authored)
-
-The CI workflow above is one of **two** complementary visual-evidence surfaces; it is not the only one:
-
-- **`Visual evidence capture` (this workflow)** — an automated, sandboxed BEFORE/AFTER comparison posted by `github-actions[bot]`. It is untouched by the agent flow and remains the trusted comparison of record.
-- **Agent-embedded screenshots (additive, W-mrz1yc79)** — when a Minions dispatch makes a meaningful **visual/UI change** (dashboard pages, slim-ux, Settings, work-item/PR/plan views, badges, layout/CSS), the agent proactively captures screenshots and embeds them directly in the PR **description** (`![view (after)](url)`), rather than relying only on the bot. Backend-only, engine-logic, text/prose-only, analysis, and docs changes get no screenshots.
-
-The agent embed path does **not** replace or modify the CI workflow — the two coexist. Mechanics the agent uses (full recipe in `playbooks/_pr-description-audit.md` → "Screenshot handling"):
-
-- **GitHub:** raw PNGs are saved under `agents/<id>/screenshots/` (never `git add`ed), published as assets on a dedicated per-PR prerelease (`gh release create pr-<num>-visual … --prerelease`, or `gh release upload … --clobber` on re-dispatch), and embedded via each asset's `browser_download_url`. This works on private repos and never commits PNGs to the source branch. The upload uses a per-command `GH_TOKEN` for the repo owner's account (`opg-microsoft` → `yemishin_microsoft`, `yemi33` → `yemi33`) and never runs `gh auth switch`.
-- **Azure DevOps:** `PUT /pullRequests/<id>/attachments/<filename>` with the PNG bytes, then reference the returned URL.
-- **Degrade gracefully:** if the dev server won't start, the route 404s, Playwright is unavailable, or the upload fails, the agent skips without failing the work item and records the reason under `meta.descriptionAudit`.

package/engine/bridge.js

@@ -1,379 +0,0 @@
-/**
- * engine/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 shared = require('./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,
-});
-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,
- * 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,
-  BRIDGE_SNAPSHOT_PROTOCOL,
-  BRIDGE_SNAPSHOT_PROTOCOL_VERSION,
-  CONSTELLATION_BRIDGE_MARKER_PATH,
-  CONSTELLATION_BRIDGE_MARKER_SCHEMA_VERSION,
-};