@yemi33/minions 0.1.1984 → 0.1.1986

package/docs/README.md

@@ -15,6 +15,7 @@ Architecture, design proposals, and lifecycle references for people working on t
 
 - [command-center.md](command-center.md) — Command Center (CC) chat panel: persistent Sonnet sessions, `--resume` semantics, system-prompt invalidation, and per-tab session storage.
 - [completion-reports.md](completion-reports.md) — Canonical schema for the per-spawn completion JSON: trust nonce, `failure_class` enum, `noop` semantics, `retryable` / `needs_rerun` shape, and the artifacts array.
+- [constellation-bridge.md](constellation-bridge.md) — Read-only cross-repo bridge: `engine.constellationBridge.enabled` flag, marker-file contract, and the `minions bridge` subcommand for local debugging.
 - [copilot-cli-schema.md](copilot-cli-schema.md) — Behavior and schema reference for the GitHub Copilot CLI adapter (capability flags, stdin vs `-p`, model discovery, effort levels).
 - [design-state-storage.md](design-state-storage.md) — Design proposal evaluating five database options for replacing Minions' file-based JSON state; recommends `node:sqlite` as the medium-term target.
 - [kb-sweep.md](kb-sweep.md) — Knowledge-base consolidation sweep (hash dedup → LLM batch dedup/reclassify → per-entry compress) and the detached runner that keeps it alive across `minions restart`.
@@ -39,6 +40,7 @@ Operational runbooks for engine operators and fleet maintainers.
 - [human-vs-automated.md](human-vs-automated.md) — Quick reference table of which features humans start, run, decide, and recover, and the two human approval gates.
 - [kb-sweep.md](kb-sweep.md) — Knowledge-base sweep runbook: how `engine/kb-sweep.js` consolidates `notes/inbox/` into `knowledge/` and survives `minions restart`.
 - [onboarding.md](onboarding.md) — First-30-minutes walkthrough for a new operator: install, init, dispatch a first work item, watch it land.
+- [security.md](security.md) — Threat model: single-user/loopback deployment assumptions, dashboard Origin gate, data-flow trust boundaries, secret handling, and known residual risks (CSRF sweep, prompt injection, log-redactor audit).
 
 ---
 

package/docs/constellation-bridge.md

@@ -0,0 +1,94 @@
+# Constellation bridge
+
+Minions ships a small read-only surface that the [Constellation](https://office.visualstudio.com/DefaultCollection/ISS/_git/constellation) dashboard polls to project Minions engine state (agents, dispatch queue, PR pipeline) into its HUD. This page documents the Minions-side of that contract.
+
+> **The bridge polling logic itself lives in the Constellation repo** (`packages/agent/src/bridges/`). Minions only owns the on/off flag, the marker-file contract, and the `minions bridge` subcommand for local debugging.
+
+## Quick start
+
+```bash
+minions bridge status     # Show enabled flag + last-seen Constellation agent
+minions bridge health     # Probe http://127.0.0.1:7331/api/status and print the projection
+minions bridge enable     # Set engine.constellationBridge.enabled = true
+minions bridge disable    # Set engine.constellationBridge.enabled = false
+```
+
+## Config flag
+
+```json
+{
+  "engine": {
+    "constellationBridge": {
+      "enabled": false
+    }
+  }
+}
+```
+
+Default: `false`. The flag is backfilled into existing configs on `minions init` (including the implicit init that runs on every `minions update`).
+
+**Strict semantics.** Only the literal boolean `true` enables the bridge. Any missing, malformed, or non-boolean value (e.g. the string `"true"`, the number `1`, `null`) is treated as **disabled**. The Constellation-side reader MUST mirror this check — no truthy coercion — so a typo'd `"enabled": "false"` does not silently turn the bridge on.
+
+Toggle without editing JSON by hand:
+
+```bash
+minions bridge enable
+minions bridge disable
+```
+
+Both subcommands write `~/.minions/config.json` atomically via `mutateJsonFileLocked`, so concurrent edits from the engine/dashboard cannot tear the file.
+
+## Marker-file contract
+
+The Constellation agent's bridge writes a marker file on every successful poll. Minions reads it with `minions bridge status` so a local operator can verify the bridge is alive and Constellation is talking to it.
+
+- **Path:** `~/.minions/engine/constellation-bridge.json` (exposed as `CONSTELLATION_BRIDGE_MARKER_PATH` in `engine/shared.js`).
+- **Owner:** the Constellation agent. The Minions engine **never** writes this file — it is a one-way breadcrumb from Constellation → Minions.
+
+### Schema (`schemaVersion: 1`)
+
+```json
+{
+  "schemaVersion": 1,
+  "lastSeenAt": "2026-05-19T04:41:23.123Z",
+  "agentVersion": "0.2.3",
+  "source": "constellation-agent"
+}
+```
+
+| Field           | Required | Notes                                                                    |
+| --------------- | -------- | ------------------------------------------------------------------------ |
+| `schemaVersion` | yes      | Must equal `1`. Any other value causes Minions to ignore the marker entirely (treated as no-marker, same as a missing file). New fields are added behind a deliberate version bump. |
+| `lastSeenAt`    | yes      | ISO-8601 UTC timestamp of the last successful poll.                      |
+| `agentVersion`  | no       | Constellation agent semver string, surfaced in `bridge status`.         |
+| `source`        | no       | Free-form identifier, expected `"constellation-agent"` today.            |
+
+Writers MUST use an atomic-replace pattern (`write to tmp + rename`) so a partial write never leaves Minions reading a half-baked JSON blob.
+
+## `minions bridge health`
+
+`bridge health` performs a synchronous probe of the Minions dashboard's `GET /api/status` endpoint and prints a **curated subset** — the same fields the Constellation bridge would project into its own data model. This is intentionally small: full `/api/status` is large, unstable, and may expose unrelated local state.
+
+Sample output:
+
+```text
+bridge: dashboard reachable on http://127.0.0.1:7331
+  projection (same fields the Constellation bridge would read):
+    engineState: running
+    enginePid: 1234
+    minionsVersion: 0.1.1984
+    agentCount: 5
+    activeAgentCount: 2
+    dispatchPending: 1
+    dispatchActive: 2
+    dispatchCompleted: 14
+    projectCount: 3
+```
+
+If the dashboard is not listening, `bridge health` prints `dashboard not running on :7331 — start it with \`minions dash\`` and exits 1. Use this exit code to gate scripted health checks.
+
+## Cross-repo coordination
+
+The Constellation-side PR ([P-wi1-bridge-readonly](https://office.visualstudio.com/DefaultCollection/ISS/_git/constellation)) lands independently of this Minions PR. The Minions side merges first with the default `enabled: false`, then the Constellation side lights up bridge polling. Operators flip the flag to `true` only after both sides are deployed.
+
+The Constellation agent's bridge reads `~/.minions/config.json` directly (no Minions HTTP API call) so config edits propagate without waiting for the engine to restart.

package/docs/security.md

@@ -0,0 +1,177 @@
+# Minions Security Model
+
+This document records the threat model for Minions today. It is intentionally
+narrow: it describes what the engine and dashboard are designed to protect
+against, what they are **not** designed to protect against, and the residual
+risks an operator should know about. It is the source of truth for "is X a
+vulnerability or a documented assumption?" questions.
+
+If you are implementing a change that touches authentication, the dashboard
+HTTP surface, secret handling, or the agent prompt boundary, read this first
+and update it in the same PR if the model changes.
+
+## 1. Deployment model
+
+Minions is designed as a **single-user, localhost-only, single-tenant**
+developer tool:
+
+- One human operator runs `minions start` on a workstation (or a remote DevBox
+  they treat as their own workstation). Agents dispatched by the engine run as
+  the same OS user as the engine and dashboard.
+- The dashboard binds `127.0.0.1` only (see
+  [`dashboard.js`](../dashboard.js) — `server.listen(PORT, '127.0.0.1', ...)`)
+  and is **not** intended to be reachable from any other host.
+- Configuration, runtime state, secrets, project worktrees, and agent output
+  all live on the same machine under `MINIONS_DIR` and the operator's git
+  worktrees.
+
+**Multi-tenant deployment is explicitly out of scope.** Minions is not a
+hosted service. The engine, dashboard, agents, MCP helpers, and any tools the
+operator invokes from the same shell session form one trust domain. Anything
+that could allow a second human to share that trust domain — exposing the
+dashboard port, mirroring `MINIONS_DIR` to another user, running the engine as
+a service account read by multiple operators — is unsupported and not
+defended against here.
+
+## 2. Dashboard threat model
+
+The dashboard (`dashboard.js`, port 7331) is the only HTTP surface in the
+system. Its threat model:
+
+### In scope (intentional, not vulnerabilities)
+
+- **Loopback bind.** The dashboard binds `127.0.0.1` only; no LAN, container,
+  or VPN client can reach it. Operators who tunnel the port elsewhere (SSH
+  port forward, `ngrok`, etc.) opt out of this assumption and inherit
+  responsibility for whatever auth gate they place in front.
+- **Same-user process access.** Any process running as the same OS user as
+  the engine (other agent runtimes, MCP helpers, `curl` from a terminal,
+  `minions` CLI subcommands) can call `/api/*`. This is intentional — it is
+  how `minions dispatch`, the Copilot/Claude runtimes, and operator scripts
+  drive the engine. We do not attempt to authenticate same-user callers.
+- **No authentication gate.** There is no login, no session cookie, no
+  per-user ACL. The single-user assumption above is the entire authn story.
+  Adding authn would not increase security in the single-user model; it would
+  only break local CLI/MCP tooling.
+
+### Residual risks defended today
+
+- **Cross-origin browser requests / CSRF / DNS rebinding.** A browser tab the
+  operator visits could in principle issue requests to `http://127.0.0.1:7331`.
+  The dashboard defends against this with:
+  - An **Origin gate** on mutating methods (`POST`/`PUT`/`PATCH`/`DELETE`)
+    and CORS preflights — see `dashboard.js` ~3677–3730 and
+    `shared.isAllowedOrigin` / `shared.buildSecurityHeaders` in
+    [`engine/shared.js`](../engine/shared.js). Requests whose `Origin` (or
+    `Referer`, if `Origin` is absent) is not in the local allowlist are
+    rejected with HTTP 403. Callers without an `Origin` header at all
+    (Node `http.request`, `curl` without `-H Origin`, CLI tooling) are
+    allowed through to preserve local automation.
+  - Baseline **security headers** (CSP, `X-Content-Type-Options`,
+    `Referrer-Policy`, clickjacking protections) applied to every response
+    via `shared.buildSecurityHeaders()`.
+
+### Residual risks tracked elsewhere
+
+- **CSRF hardening sweep.** A broader hardening pass — deny-by-default CORS,
+  `Sec-Fetch-Site: same-origin` enforcement on mutating endpoints, and an
+  optional bearer-token gate as a secondary defense — is **deferred to a
+  separate plan** (`D-f8-csrf` in
+  `prd/security-fix-plan-from-weekly-review-2026-05-18.json`, open question
+  `Q-csrf-followup`). This document does not gate that work; if and when the
+  CSRF follow-up plan ships, update §2 to reflect the new posture.
+
+### Recommended hardening (if F8 ever moves from docs to code)
+
+If we revisit this assumption — e.g. the dashboard ever serves more than one
+operator, or we want defense-in-depth beyond Origin checks — the recommended
+shape is:
+
+1. Reject mutating requests whose `Origin` / `Sec-Fetch-Site` is not
+   `same-origin`, instead of the current allowlist + missing-header pass-through.
+2. Switch CORS to deny-by-default and explicitly opt specific endpoints in.
+3. Add an optional bearer token (operator-supplied via env) as a secondary
+   gate; require it on mutating endpoints when set.
+4. Document the resulting break in CLI/MCP tooling and provide a token
+   injection path for it.
+
+## 3. Data flow trust boundaries
+
+Minions reads from several sources with very different trust levels. The
+engine and dashboard treat them differently on purpose:
+
+| Source | Trust | Examples | Handling |
+|---|---|---|---|
+| **Operator config** | Trusted | `config.json`, `projects/`, `notes.md`, `notes/inbox/*` authored by the human, `pinned.md` | Read as-is. The operator is assumed to control these files. |
+| **Agent output** | Semi-trusted | Completion reports, fenced `completion` blocks, learnings notes, PR comments authored by the shared `gh` identity | Schema-validated; completion JSON is gated by the per-spawn nonce (`MINIONS_COMPLETION_NONCE`, see [`completion-reports.md`](completion-reports.md) → "Trust boundary"). Reports without a valid nonce are rejected with `failure_class: 'completion-nonce-mismatch'`. |
+| **External APIs** | Untrusted | GitHub REST/GraphQL responses, Azure DevOps REST responses, GitHub/ADO PR comment bodies, CI/run logs | Validated and shape-checked before persistence. Strings sourced from these responses are never passed as raw arguments to shells or `git`; see F2 (gh shell-injection fix) and F7 (`git log` execFile conversion) in the same security plan. |
+| **Agent-controlled paths** | Untrusted | Paths supplied to dashboard endpoints by agents (e.g. `/api/agent-output`) | Normalized through `shared.sanitizePath` to constrain to the expected root; see F4 in the same plan. |
+
+The agent-output trust boundary deserves emphasis: completion reports are the
+single most powerful signal an agent can emit (they advance work-item status,
+mark PRs reviewed, trigger merges). The nonce gate exists specifically so a
+report written by an unrelated process — or by a stale dispatch from a
+previous tick — cannot be silently consumed. Anything in the report body
+itself remains agent-controlled and is treated as such (no `eval`, no shell
+interpolation, schema-validated fields only).
+
+## 4. Secret management
+
+- **PATs and API tokens live in environment variables only.** GitHub tokens
+  (`GH_TOKEN`, `COPILOT_GITHUB_TOKEN`), Azure DevOps PATs, and any
+  runtime-specific credentials are read from the engine's process
+  environment. They are not persisted to `config.json`, work-item state,
+  PR metadata, or any other on-disk JSON Minions owns.
+- **Tokens are never intentionally logged.** Engine code that shells out to
+  `gh` or the ADO CLI threads the token via per-call `GH_TOKEN=...`
+  environment injection (see `engine/gh-token.js`), so the value never
+  appears on a command line or in `live-output.log`.
+- **The log redactor is best-effort, not authoritative.** A best-effort
+  redactor scrubs token-shaped strings from logs and agent output, but its
+  coverage has **not** been formally audited (deferred as `D-f9`, open
+  question `Q-f9-log-redactor`). Treat redaction as a defense-in-depth nicety,
+  not a guarantee — do not rely on it to keep a leaked token out of an
+  uploaded log bundle. If a token may have appeared in output, rotate it.
+
+## 5. Known limitations
+
+These are accepted limitations of the current model. They are documented
+rather than fixed because (a) they are out of scope for the single-user
+threat model, (b) they are tracked under other items, or (c) a fix would
+break operator workflows we want to preserve.
+
+- **No authentication gate on the dashboard.** Intentional — see §2. The
+  single-user UX (and `minions` CLI, MCP integrations, and operator scripts
+  that POST to `/api/*` without juggling a token) depends on this. Revisit
+  only if the deployment model in §1 changes.
+- **Prompt-injection surface from PR comments and inbox notes.** Agent
+  prompts splice in human-authored content (pinned notes, `notes/inbox/*`,
+  PR comment bodies, `pendingHumanFeedback`) without a fenced delimiter
+  separating "instructions" from "data." A malicious PR comment author
+  could attempt to steer an agent that reads the comment thread. Mitigation
+  (F5 — delimited untrusted content blocks) is **blocked on an open
+  question** (`Q-f5-delimiter`) about which delimiter token to standardize
+  on. Until F5 lands, operators should treat external PR comment threads
+  as a low-but-nonzero injection surface.
+- **Temp-file predictability.** Per-dispatch temp paths can be predictable
+  in some shells, opening a narrow TOCTOU window for a same-user process to
+  race the engine. Tracked as **F6** in this same security plan
+  (`P-f6-tmp-toctou`); the fix moves dispatch temp dirs to per-spawn unique
+  paths with restrictive permissions.
+- **Log redactor coverage is unaudited.** See §4 and `D-f9` /
+  `Q-f9-log-redactor`. Until the audit lands, treat any log bundle that
+  might contain agent output, CI logs, or `live-output.log` excerpts as
+  potentially containing tokens, and rotate accordingly.
+- **CSRF hardening sweep is deferred.** See §2. Origin gate + security
+  headers are in place today; the broader sweep (deny-by-default CORS,
+  `Sec-Fetch-Site` enforcement, optional bearer token) is `D-f8-csrf` /
+  `Q-csrf-followup`.
+
+---
+
+**Updating this doc:** If you change the dashboard's bind address, add or
+remove an authn/authz mechanism, change how completion reports are trusted,
+change how secrets are read, or land any of F5 / F6 / F9 / the CSRF
+follow-up, update the relevant section here in the same PR. Keep the
+"in-scope vs residual vs deferred" split — it is the part reviewers come
+back to.

package/engine/ado-git-auth.js

@@ -0,0 +1,206 @@
+/**
+ * engine/ado-git-auth.js — W-mpcuc8i80003a7b3
+ *
+ * Inject a per-invocation Authorization: Bearer <token> http.extraHeader into
+ * git ops that touch an ADO origin. Solves the headless-dispatch failure mode
+ * where Git Credential Manager falls back to a TTY prompt (because the engine
+ * has no terminal) and emits:
+ *
+ *   fatal: could not read Username for 'https://office.visualstudio.com'
+ *
+ * The token is sourced via the existing `engine/ado-token.js#acquireAdoTokenSync`
+ * helper (az CLI first, azureauth fallback). We cache it for 30 minutes and
+ * back off acquisition retries for 10 minutes on failure so we don't hammer
+ * az / azureauth on every git op during an outage.
+ *
+ * Public API:
+ *   - getAdoGitExtraArgs(project, opts?) → string[]
+ *       Sync. Returns `['-c', 'http.<scope>.extraHeader=Authorization: Bearer <token>']`
+ *       for ADO projects, `[]` for everything else (GitHub/local/null). Plumbed
+ *       into shared.shellSafeGit via `opts.gitExtraArgs`.
+ *   - invalidateAdoTokenCache()
+ *       Drops the cached token so the next getAdoGitExtraArgs() re-acquires.
+ *       Used by runAdoGit on auth failure to handle mid-dispatch token expiry.
+ *   - isAdoAuthFailure(err) → boolean
+ *       Pure. Matches credential/auth-specific phrases against err.message,
+ *       err.stdout, err.stderr. Deliberately NARROW — does not match bare
+ *       "fatal: unable to access" since that also fires for DNS/TLS/proxy.
+ *   - runAdoGit(project, gitArgs, opts) → Promise<string>
+ *       Async wrapper around shellSafeGit. On ADO auth failure, invalidates
+ *       cache, re-acquires, retries ONCE in the same dispatch. Redacts the
+ *       bearer token from rethrown error messages so the token never lands in
+ *       logs / inbox alerts / completion reports.
+ *
+ * Argv-vs-env tradeoff: putting `-c http.extraHeader=Authorization: Bearer X`
+ * in argv is visible via process listing. The simpler alternative
+ * `GIT_CONFIG_COUNT=1 GIT_CONFIG_KEY_0=... GIT_CONFIG_VALUE_0=...` hides the
+ * token from `ps`. We chose argv to match the documented manual-verification
+ * recipe (matches the task spec) and explicitly redact on error rethrow.
+ * Migrate to env-form if argv exposure becomes a real concern.
+ */
+
+const shared = require('./shared');
+const adoToken = require('./ado-token');
+const { log } = shared;
+
+const TOKEN_TTL_MS = 30 * 60 * 1000;     // 30 min — matches gh-token cadence
+const ACQUIRE_BACKOFF_MS = 10 * 60 * 1000; // 10 min — same backoff as gh-token
+const ACQUIRE_TIMEOUT_MS = 30000;        // 30s — generous for slow IWA/broker auth
+
+let _cached = null;       // { token, expiresAt }
+let _backoffUntil = 0;    // epoch ms — no acquire attempts before this
+
+// Credential/auth patterns. Narrow on purpose: do NOT include bare
+// "fatal: unable to access" — that also fires for DNS, TLS, and proxy errors
+// which are correctly classified elsewhere (NETWORK_ERROR, retryable).
+const ADO_AUTH_PATTERNS = [
+  /could not read Username/i,
+  /could not read Password/i,
+  /Authentication failed/i,
+  /terminal prompts disabled/i,
+  /TF40081\d/i,                          // Azure DevOps auth error family
+  /HTTP\s*4(?:01|03)\b/i,                // explicit 401/403 in error text
+];
+
+function isAdoProject(project) {
+  return !!(project && project.repoHost === 'ado');
+}
+
+// Scope the header to the ADO host so a misconfigured remote pointing at
+// another host (e.g. github.com on a misclassified project) doesn't leak the
+// bearer token. Falls back to the unscoped `http.extraHeader` key when we
+// can't compute a host (still safe — git only sends extraHeader on HTTP/S
+// transfers, and the engine only invokes ado-git-auth for ADO projects).
+function _resolveScopeUrl(project) {
+  try {
+    if (!project || !project.adoOrg) return null;
+    const base = shared.getAdoOrgBase(project);
+    if (typeof base !== 'string' || !base.startsWith('http')) return null;
+    const m = base.match(/^(https?:\/\/[^/]+)/);
+    return m ? `${m[1]}/` : null;
+  } catch (_e) {
+    return null;
+  }
+}
+
+function _buildHeaderArgs(token, scopeUrl) {
+  const key = scopeUrl ? `http.${scopeUrl}.extraHeader` : 'http.extraHeader';
+  return ['-c', `${key}=Authorization: Bearer ${token}`];
+}
+
+function _acquireToken(opts = {}) {
+  const exec = opts.acquireAdoTokenSync || adoToken.acquireAdoTokenSync;
+  const result = exec({ timeout: opts.timeout || ACQUIRE_TIMEOUT_MS });
+  return result && result.token ? String(result.token) : null;
+}
+
+function getAdoGitExtraArgs(project, opts = {}) {
+  if (!isAdoProject(project)) return [];
+  const now = Date.now();
+  if (_cached && _cached.expiresAt > now) {
+    return _buildHeaderArgs(_cached.token, _resolveScopeUrl(project));
+  }
+  if (now < _backoffUntil) return [];
+  try {
+    const token = _acquireToken(opts);
+    if (!token) {
+      _backoffUntil = now + ACQUIRE_BACKOFF_MS;
+      log('warn', `ado-git-auth: acquireAdoTokenSync returned empty token; backing off ${ACQUIRE_BACKOFF_MS / 1000}s`);
+      return [];
+    }
+    _cached = { token, expiresAt: now + TOKEN_TTL_MS };
+    return _buildHeaderArgs(token, _resolveScopeUrl(project));
+  } catch (e) {
+    _backoffUntil = now + ACQUIRE_BACKOFF_MS;
+    const firstLine = String(e && e.message || e).split('\n')[0];
+    log('warn', `ado-git-auth: token acquire failed (${firstLine}); backing off ${ACQUIRE_BACKOFF_MS / 1000}s`);
+    return [];
+  }
+}
+
+function invalidateAdoTokenCache() {
+  _cached = null;
+}
+
+function isAdoAuthFailure(err) {
+  if (!err || typeof err !== 'object') return false;
+  const parts = [
+    err.message,
+    typeof err.stdout === 'string' ? err.stdout : '',
+    typeof err.stderr === 'string' ? err.stderr : '',
+  ].filter(Boolean).join('\n');
+  if (!parts) return false;
+  return ADO_AUTH_PATTERNS.some((p) => p.test(parts));
+}
+
+function _redactBearer(s) {
+  if (typeof s !== 'string') return s;
+  return s.replace(/Authorization:\s*Bearer\s+[A-Za-z0-9._\-]+/gi, 'Authorization: Bearer [REDACTED]');
+}
+
+function _redactErrorInPlace(err) {
+  if (!err || typeof err !== 'object') return err;
+  if (err.message) err.message = _redactBearer(err.message);
+  if (typeof err.stdout === 'string') err.stdout = _redactBearer(err.stdout);
+  if (typeof err.stderr === 'string') err.stderr = _redactBearer(err.stderr);
+  return err;
+}
+
+async function runAdoGit(project, gitArgs, opts = {}) {
+  const { acquireAdoTokenSync, _runGit, ...callerOpts } = opts;
+  const runGit = _runGit || shared.shellSafeGit;
+  const baseExtra = Array.isArray(callerOpts.gitExtraArgs) ? callerOpts.gitExtraArgs : [];
+  const adoOpts = { acquireAdoTokenSync };
+
+  const firstExtra = baseExtra.concat(getAdoGitExtraArgs(project, adoOpts));
+  const firstOpts = firstExtra.length ? { ...callerOpts, gitExtraArgs: firstExtra } : callerOpts;
+  try {
+    return await runGit(gitArgs, firstOpts);
+  } catch (err) {
+    if (!isAdoProject(project) || !isAdoAuthFailure(err)) {
+      throw _redactErrorInPlace(err);
+    }
+    // Token may have expired mid-dispatch — refresh and retry exactly once.
+    invalidateAdoTokenCache();
+    _backoffUntil = 0; // give the retry a chance to actually hit the token source
+    const refreshedExtra = getAdoGitExtraArgs(project, adoOpts);
+    if (!refreshedExtra.length) {
+      throw _redactErrorInPlace(err);
+    }
+    const retryExtra = baseExtra.concat(refreshedExtra);
+    try {
+      return await runGit(gitArgs, { ...callerOpts, gitExtraArgs: retryExtra });
+    } catch (err2) {
+      throw _redactErrorInPlace(err2);
+    }
+  }
+}
+
+// ── Test seams ──────────────────────────────────────────────────────────────
+
+function _setTokenForTest(token) {
+  if (token == null) { _cached = null; _backoffUntil = 0; return; }
+  _cached = { token: String(token), expiresAt: Date.now() + TOKEN_TTL_MS };
+  _backoffUntil = 0;
+}
+
+function _clearTokenCache() {
+  _cached = null;
+  _backoffUntil = 0;
+}
+
+function _isBackedOff() { return Date.now() < _backoffUntil; }
+
+module.exports = {
+  getAdoGitExtraArgs,
+  invalidateAdoTokenCache,
+  isAdoAuthFailure,
+  runAdoGit,
+  isAdoProject,
+  _setTokenForTest,
+  _clearTokenCache,
+  _isBackedOff,
+  TOKEN_TTL_MS,
+  ACQUIRE_BACKOFF_MS,
+  ADO_AUTH_PATTERNS,
+};

package/engine/bridge.js

@@ -0,0 +1,124 @@
+/**
+ * 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.
+ *
+ * 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');
+
+/**
+ * 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,
+  projectStatusForBridge,
+  CONSTELLATION_BRIDGE_MARKER_PATH,
+  CONSTELLATION_BRIDGE_MARKER_SCHEMA_VERSION,
+};