@bongos/core 1.21.175 → 1.21.177

package/scripts/bongos/deploy-divergence.js

@@ -0,0 +1,454 @@
+#!/usr/bin/env node
+// Compare what a live instance is SERVING against what is on main.
+//
+// WHO SEES A MERGE (tasks 1004682, 1004873; the wording lives in
+// modules/lifecycle/merge-reach.js): every instance, the hub included, gets a merge
+// only when a published core release carries it AND that instance's pin moves. The
+// publish lane cuts a release per merge (ADR 0161) only while the integration lane
+// is green; on the hub (cloudbongos.com) the pin move is owner-gated.
+// Two blanket claims have been wrong here: "Merging to main deploys nothing" (ADR
+// 0137, false since ADR 0161) and "the hub redeploys from main on every merge"
+// (never true — the hub pins a published core). Sessions repeated each to the owner.
+// So this script READS the hub's /version and says whether the live build includes
+// main's tip, and whether any release carries that tip yet, instead of a rule.
+//
+// Why it exists at all: between 2026-07-24 and 2026-08-03 a hundred and
+// seventy-one commits — including a whole governance permission system — sat on
+// main while cloudbongos.com served 1.18.17, every layer reported success, and
+// nobody noticed for ten days (blocker 1000097 / task 1002521). This script is
+// the comparison that was missing.
+//
+// Three independent gaps, all reported:
+//   1. UNRELEASED — commits on main since the last CORE_VERSION bump. No hosted
+//      project can take these at any pin, because no published version carries them.
+//   2. UNDEPLOYED — the live instance's coreVersion is behind the CORE_VERSION
+//      on main. A release exists that it has not picked up: on the hub, its
+//      redeploy is late or stuck; on a hosted project, its pin has not moved.
+//   3. SCHEMA BEHIND — live's /version reports schemaPending > 0: its database
+//      lacks migrations its running code ships (the 2026-07-04 502 outage
+//      shape; task 1002002). An instance too old to report it is not flagged.
+//
+// Usage:
+//   node scripts/bongos/deploy-divergence.js                  # check the instance this checkout talks to
+//   node scripts/bongos/deploy-divergence.js --url https://example.com
+//   node scripts/bongos/deploy-divergence.js --quiet          # only print on divergence
+//   node scripts/bongos/deploy-divergence.js --warn-only      # always exit 0 (for a non-blocking ship warning)
+//   node scripts/bongos/deploy-divergence.js --line [--timeout-ms N]
+//                                                         # ONE line, or nothing; always exit 0
+//                                                         # (the SessionStart shape — wired in .claude/settings.json)
+//
+// Exit codes: 0 aligned (or --warn-only), 1 diverged, 2 could not determine.
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { execSync } = require('node:child_process');
+
+const { API_BASE, arg, hasFlag } = require('./cli-lib');
+const { whoSeesAMerge, hubRule, releaseState, HOSTED_LINE } = require('../../modules/lifecycle/merge-reach.js');
+
+const REPO_ROOT = path.resolve(__dirname, '..', '..');
+const MODULE_API = path.join(REPO_ROOT, 'src', 'module-api.js');
+
+// Read CORE_VERSION by regex rather than require() — this runs in checkouts
+// (and CI) where loading the doorway would pull config/branding that may not
+// resolve, and we only ever want the literal.
+function coreVersionAt(ref) {
+  let src;
+  try {
+    src = ref
+      ? execSync(`git show ${ref}:src/module-api.js`, { cwd: REPO_ROOT, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'], maxBuffer: 64 * 1024 * 1024 })
+      : fs.readFileSync(MODULE_API, 'utf8');
+  } catch {
+    return null;
+  }
+  const m = src.match(/^const CORE_VERSION = '([^']+)'/m);
+  return m ? m[1] : null;
+}
+
+// 10s per call so one wedged git (index.lock contention, a slow filesystem)
+// cannot stall a caller indefinitely. This runs on the SessionStart path, where
+// the only other bounds were the fetch timeout and Claude Code's own hook
+// timeout — neither of which covers a hung execSync.
+const GIT_TIMEOUT_MS = 10000;
+
+function git(cmd, fallback = null) {
+  try {
+    return execSync(`git ${cmd}`, {
+      cwd: REPO_ROOT, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'],
+      maxBuffer: 64 * 1024 * 1024, timeout: GIT_TIMEOUT_MS,
+    }).trim();
+  } catch {
+    return fallback;
+  }
+}
+
+// The commit that last changed the CORE_VERSION literal, and how many commits
+// sit on top of it. Must be `-G` (any diff line matching the regex), NOT `-S`:
+// `-S` fires only when the number of occurrences changes, and a bump rewrites
+// the single existing line — so `-S` silently walks back to the commit that
+// first introduced the constant and reports every commit since as unreleased.
+// `--no-merges` is load-bearing, not a nicety: a bump lands on main VIA a merge,
+// so counting merges means the moment any release lands there is always ≥1
+// "unreleased" commit — the merge that landed the bump. This check exists
+// because a real gap hid for ten days behind layers that all reported success;
+// one that cries wolf after every single release earns exactly the same
+// scrolling-past it was added to prevent. Merge commits carry no content of
+// their own, so they are not unreleased work. (task 1002558)
+function unreleasedSince(mainRef) {
+  const bump = git(`log ${mainRef} -1 --format=%H -G"^const CORE_VERSION = " -- src/module-api.js`);
+  if (!bump) return null;
+  const count = git(`rev-list --count --no-merges ${bump}..${mainRef}`);
+  const withMerges = git(`rev-list --count ${bump}..${mainRef}`);
+  return {
+    bump,
+    bumpShort: bump.slice(0, 8),
+    bumpSubject: git(`log -1 --format=%s ${bump}`, ''),
+    bumpDate: git(`log -1 --format=%cs ${bump}`, ''),
+    count: count === null ? null : Number(count),
+    countWithMerges: withMerges === null ? null : Number(withMerges),
+  };
+}
+
+// Does the live build include commit `sha`? true / false, or null when this
+// checkout cannot tell (task 1004682). Two ways to know, tried in order:
+//   1. The /version commit is one this repo has (a box that runs this checkout
+//      directly) — plain ancestry.
+//   2. Otherwise the commit is the hub's OWN repo (it consumes the core as a
+//      published package — measured 2026-10-09: cloudbongos.com reports a commit
+//      core main does not contain, at the coreVersion main declares). Then: find the
+//      first CORE_VERSION bump on main at or after `sha` — the release that carries
+//      it — and compare the live coreVersion against it. No bump yet ⇒ not yet.
+// Both inputs reach git, so both are hex-or-nothing and the ref is a fixed name.
+function liveIncludes(live, sha, mainRef = resolveMainRef()) {
+  const want = typeof sha === 'string' && /^[0-9a-f]{7,40}$/i.test(sha) ? sha.toLowerCase() : null;
+  if (!live || !want || !/^(origin\/main|HEAD)$/.test(mainRef)) return null;
+  const liveCommit = typeof live.commit === 'string' && /^[0-9a-f]{40}$/i.test(live.commit) ? live.commit : null;
+  if (liveCommit && git(`cat-file -e ${liveCommit}`) !== null) {
+    return git(`merge-base --is-ancestor ${want} ${liveCommit}`) !== null;
+  }
+  if (!isPlausibleVersion(live.coreVersion)) return null;
+  if (git(`merge-base --is-ancestor ${want} ${mainRef}`) === null) return null; // not on main here yet
+  // `sha` itself may be the bump (a hand-cut release); otherwise the first bump after it.
+  const selfBump = git(`log -1 --format=%H -G"^const CORE_VERSION = " ${want} -- src/module-api.js`, '');
+  const after = git(`log --ancestry-path --reverse --format=%H -G"^const CORE_VERSION = " ${want}..${mainRef} -- src/module-api.js`, '');
+  const carrier = selfBump && selfBump.startsWith(want) ? selfBump : (after ? after.split('\n')[0].trim() : null);
+  if (!carrier) return false; // on main, but no release carries it yet
+  const carried = coreVersionAt(carrier);
+  return carried ? cmpSemver(live.coreVersion, carried) >= 0 : null;
+}
+
+// The sanitised reading the merge-reach sentence is built from. `live` may be a
+// raw /version body (ship-finish passes one), so it goes through the same filters
+// fetchLive applies before anything is interpolated.
+// Prefer origin/main — the released trunk — but fall back to HEAD in a checkout with
+// no remote (a box, a tarball). Shared by check() and hubReading() so both agree.
+function resolveMainRef() {
+  return git('rev-parse --verify --quiet origin/main') ? 'origin/main' : 'HEAD';
+}
+
+function hubReading({ target, live, sha, mainRef = resolveMainRef() } = {}) {
+  return {
+    host: safeHost(target || API_BASE),
+    liveShort: live ? safeCommitShort(live.commitShort) || safeCommitShort(typeof live.commit === 'string' ? live.commit.slice(0, 8) : null) : null,
+    includes: live ? liveIncludes(live, sha, mainRef) : null,
+  };
+}
+
+function cmpSemver(a, b) {
+  const pa = String(a).split('.').map(Number);
+  const pb = String(b).split('.').map(Number);
+  for (let i = 0; i < 3; i += 1) {
+    const d = (pa[i] || 0) - (pb[i] || 0);
+    if (d) return d < 0 ? -1 : 1;
+  }
+  return 0;
+}
+
+const DEFAULT_TIMEOUT_MS = 15000;
+
+// Strict semver — `1.19.69`, `2.0.0-rc.1`, `1.2.3+build.5`. Anchored, length-capped,
+// and deliberately narrower than anything we would ever publish, because this is
+// the filter standing between an unauthenticated network response and an agent's
+// context window (see the trust-boundary note in fetchLive).
+const SEMVER_RE = /^\d{1,6}\.\d{1,6}\.\d{1,6}(?:-[0-9A-Za-z.-]{1,32})?(?:\+[0-9A-Za-z.-]{1,32})?$/;
+const isPlausibleVersion = (v) => typeof v === 'string' && v.length <= 64 && SEMVER_RE.test(v);
+
+// commitShort is only ever displayed, never compared — but it comes from the same
+// untrusted response, so it gets the same treatment: hex or nothing.
+const safeCommitShort = (c) => (typeof c === 'string' && /^[0-9a-f]{4,40}$/i.test(c) ? c : null);
+
+// schemaPending is interpolated into the line too: a bounded non-negative integer or nothing.
+const safeCount = (n) => (Number.isInteger(n) && n >= 0 && n <= 100000 ? n : null);
+
+// The host is local config (API_BASE / --url), not a network response — but it is
+// still interpolated into injected text, so it is bounded and stripped of anything
+// that could read as prose rather than a hostname.
+function safeHost(target) {
+  const host = String(target).replace(/^https?:\/\//, '').replace(/\/+$/, '');
+  return /^[A-Za-z0-9.:_-]{1,120}$/.test(host) ? host : 'the configured instance';
+}
+
+async function fetchLive(base, timeoutMs = DEFAULT_TIMEOUT_MS) {
+  const url = `${String(base).replace(/\/+$/, '')}/version`;
+  const ctl = new AbortController();
+  const timer = setTimeout(() => ctl.abort(), timeoutMs);
+  try {
+    const res = await fetch(url, { signal: ctl.signal, headers: { accept: 'application/json' } });
+    if (!res.ok) return { url, error: `HTTP ${res.status}` };
+    const body = await res.json();
+    if (!body || !body.coreVersion) return { url, error: 'no coreVersion field in /version' };
+    // TRUST BOUNDARY. /version is an unauthenticated response from whatever
+    // API_BASE resolves to, and --line embeds this value in text injected
+    // straight into an agent's SessionStart context. Interpolating it raw would
+    // hand anyone who can answer as that host (a hostile GDS_API_BASE/OTB_API_BASE,
+    // DNS or host compromise, a compromised instance) a silent every-session
+    // prompt-injection channel. cmpSemver is no defence — it Number()-parses only
+    // the leading dot-segment, so "999.0.0 <instructions to the agent>" compares
+    // fine and would carry the whole string through.
+    //
+    // So: accept ONLY a strict semver, and treat anything else as unreadable.
+    // The caller already renders an unreadable /version as undetermined, which
+    // --line turns into silence — the fail-open path stays fail-open, while the
+    // CONTENT fails closed.
+    if (!isPlausibleVersion(body.coreVersion)) {
+      return { url, error: 'coreVersion in /version is not a plausible version string' };
+    }
+    return {
+      url,
+      coreVersion: String(body.coreVersion),
+      commitShort: safeCommitShort(body.commitShort),
+      // Full sha, hex-or-nothing: only ever handed to git (liveIncludes), never printed.
+      commit: typeof body.commit === 'string' && /^[0-9a-f]{40}$/i.test(body.commit) ? body.commit : null,
+      schemaPending: safeCount(body.schemaPending),
+    };
+  } catch (e) {
+    return { url, error: e.name === 'AbortError' ? `timed out after ${timeoutMs}ms` : (e.message || String(e)) };
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+// Is the automation that should have PREVENTED this divergence itself alive? (task 1003158)
+//
+// This script detects the SYMPTOM — live is behind main — and only ever at a moment a human is
+// already looking. What went unwatched is the auto-upgrade subscription itself: when it stopped,
+// nothing said so, and cloudbongos.com sat 36 releases behind for days. Reading the roster here means
+// a dead upgrader is reported in the same breath as the staleness it was supposed to prevent.
+//
+// Speaks ONLY when a subscription manifest is actually present. An ordinary core checkout has none by
+// design (ADR 0136 — it ships empty), and alarming about that every session is exactly the noise that
+// gets a real warning scrolled past. Present-but-broken, or present-and-subscribing-nothing, is the
+// signal worth having: someone meant to enroll instances here and none are being upgraded.
+function subscriptionHealth(dir = REPO_ROOT) {
+  try {
+    const uc = require('./update-channel');
+    const roster = uc.loadSubscriptions({ instanceDir: dir });
+    if (!roster.present) return null;
+    return uc.describeRoster(roster, { controlPlane: true });
+  } catch {
+    return null; // never let the health probe break the divergence check it rides along with
+  }
+}
+
+// withReach: compute the who-sees-a-merge reading (a few git calls). The SessionStart
+// --line never prints it, so it passes false and pays nothing for it.
+async function check({ base, timeoutMs = DEFAULT_TIMEOUT_MS, withReach = true } = {}) {
+  const target = base || arg('--url') || API_BASE;
+  const local = coreVersionAt(null);
+  if (!local) return { ok: false, undetermined: true, reason: 'could not read CORE_VERSION from src/module-api.js', target };
+
+  // Prefer origin/main — the released trunk — but fall back to HEAD in a
+  // checkout with no remote (a box, a tarball) so the check still says
+  // something useful instead of bailing.
+  const mainRef = resolveMainRef();
+  const onMain = coreVersionAt(mainRef) || local;
+  const unreleased = unreleasedSince(mainRef);
+  // Is main's latest merge in a release yet (task 1004873)? A release lands on main
+  // as a CORE_VERSION bump, so no work commit past the last bump means the tip is
+  // carried by the version main declares.
+  const tip = { short: git(`rev-parse --short=8 ${mainRef}`), version: unreleased && unreleased.count === 0 ? onMain : null };
+  const live = await fetchLive(target, timeoutMs);
+
+  const subscriptions = subscriptionHealth();
+
+  if (live.error) return { ok: false, undetermined: true, reason: `could not read ${live.url}: ${live.error}`, target, local, onMain, unreleased, tip, subscriptions };
+
+  const behind = cmpSemver(live.coreVersion, onMain) < 0;
+  const ahead = cmpSemver(live.coreVersion, onMain) > 0;
+  const hasUnreleased = !!(unreleased && unreleased.count > 0);
+  const schemaBehind = live.schemaPending > 0;
+  // "this merge", read from here, is main's tip: ship-finish runs this right after a land.
+  const reach = withReach ? hubReading({ target, live, sha: git(`rev-parse ${mainRef}`), mainRef }) : null;
+
+  return {
+    ok: !behind && !hasUnreleased && !schemaBehind,
+    target, local, onMain, mainRef, unreleased, tip, live, behind, ahead, hasUnreleased, schemaBehind, subscriptions, reach,
+  };
+}
+
+function report(r, { quiet = false } = {}) {
+  const say = (...a) => console.log(...a);
+
+  if (r.undetermined) {
+    console.error(`deploy-divergence: undetermined — ${r.reason}`);
+    return;
+  }
+  if (r.ok && quiet) return;
+
+  const host = String(r.target).replace(/^https?:\/\//, '');
+  say('');
+  say(`  Deploy divergence · ${host}`);
+  say('  ──────────────────────────────────────────────────────────');
+  say(`  live (serving)      ${r.live.coreVersion}${r.live.commitShort ? `  (instance commit ${r.live.commitShort})` : ''}`);
+  say(`  ${r.mainRef.padEnd(18)}  ${r.onMain}`);
+  // Only worth a line when a bump is in flight in this tree but not yet landed.
+  if (r.local !== r.onMain) say(`  working tree        ${r.local}  (not yet on ${r.mainRef})`);
+  if (r.unreleased) {
+    say(`  last bump           ${r.unreleased.bumpShort} ${r.unreleased.bumpDate} — ${r.unreleased.bumpSubject}`);
+  }
+  say('');
+
+  // Who sees a merge — the same two lines the ship card prints (merge-reach.js).
+  const reachBlock = () => {
+    say('');
+    for (const l of whoSeesAMerge(r.reach || { host: safeHost(r.target) })) say(`  ${l}`);
+    say('');
+  };
+
+  if (r.ok) {
+    say('  ✓ aligned — live matches main, and main carries no unreleased commits.');
+    reachBlock();
+    return;
+  }
+
+  if (r.hasUnreleased) {
+    // Say which number this is: work commits and with-merges differ a lot on a
+    // big window (93 vs 171 for 1.18.18), and an unlabelled figure invites the
+    // "~100 vs 171" disagreement that muddied blocker 1000097.
+    const u = r.unreleased;
+    const merges = u.countWithMerges != null && u.countWithMerges !== u.count
+      ? ` (${u.countWithMerges} counting merges)` : '';
+    say(`  ⚠ UNRELEASED — ${u.count} work commit${u.count === 1 ? '' : 's'}${merges} on ${r.mainRef} since the last CORE_VERSION bump.`);
+    say('    No instance, the hub included, can take these at ANY pin: no published version contains them yet.');
+    say('    The publish lane (ADR 0161) normally carries a merge within minutes; a gap that stays means it is disarmed,');
+    say('    red, or refused by its integration gate (scripts/bongos/publish-integration-gate.js) because integration on main is red.');
+  }
+  if (r.behind) {
+    say(`  ⚠ UNDEPLOYED — live is ${r.live.coreVersion}, main declares ${r.onMain}.`);
+    say('    A release exists that this instance has not picked up: its pin has not moved. On the hub that move is');
+    say('    owner-gated; on a hosted project it is its update channel or a core-upgrade (docs/recipes/upgrading-the-core.md).');
+  }
+  if (r.schemaBehind) {
+    const n = r.live.schemaPending;
+    say(`  ⚠ SCHEMA BEHIND — live's database is missing ${n} migration${n === 1 ? '' : 's'} its running code ships.`);
+    say('    The first query that touches them fails (the 2026-07-04 502 was this shape).');
+    say('    Fix: run migrate against that instance DB with PGDATABASE set (see docs/recipes/upgrading-the-core.md).');
+  }
+  if (r.ahead) {
+    say(`  note: live (${r.live.coreVersion}) is AHEAD of ${r.mainRef} (${r.onMain}) — this checkout is stale; fetch.`);
+  }
+  // The watcher's watcher: if this checkout carries a subscription roster and that roster is not
+  // healthy, the unattended upgrade is not going to close the gap above on its own.
+  if (r.subscriptions && r.subscriptions.level !== 'ok') {
+    say('');
+    say(`  ${r.subscriptions.level === 'alarm' ? '⚠ AUTO-UPGRADE' : 'note: auto-upgrade'} — ${r.subscriptions.message}`);
+    if (r.behind) say('    So the gap above will NOT close by itself.');
+  }
+  reachBlock();
+}
+
+// ONE line, for injecting into an agent's SessionStart context (task 1002713).
+// The full report() block is right for a ship card and far too heavy for every
+// session, so this compresses the same check() result to a single sentence.
+//
+// Returns null when there is nothing an agent must know: aligned, or the check
+// could not be determined at all. A SessionStart hook prints only a string, so
+// null IS the silence — an unreachable instance must never editorialize.
+function line(r) {
+  if (!r || r.undetermined || r.ok) return null;
+
+  const host = safeHost(r.target);
+  // Defence in depth: fetchLive already rejects a non-semver coreVersion, so a
+  // value reaching here is known-safe. Re-checking costs nothing and means a
+  // future caller that builds its own result object cannot reopen the hole.
+  const liveVer = isPlausibleVersion(r.live?.coreVersion) ? r.live.coreVersion : null;
+  const mainVer = isPlausibleVersion(r.onMain) ? r.onMain : null;
+
+  const parts = [];
+  if (r.behind && liveVer && mainVer) {
+    parts.push(`${host} is SERVING core ${liveVer}, but main declares ${mainVer}`);
+  } else if (r.ahead && liveVer && mainVer) {
+    // Live ahead of main is not "fine" — it means this checkout is stale, and an
+    // agent reading main would describe the wrong code as deployed.
+    parts.push(`${host} is SERVING core ${liveVer}, AHEAD of main's ${mainVer} — this checkout is behind`);
+  }
+  if (r.hasUnreleased) {
+    const n = r.unreleased.count;
+    parts.push(`${n} commit${n === 1 ? ' on main is' : 's on main are'} UNRELEASED (no version carries them)`);
+  }
+  // Whether main's latest merge is in a release yet — the first question behind
+  // "is my work live?" (task 1004873). Bounded by releaseState (injected text).
+  if (parts.length && r.tip) parts.push(releaseState({ tipShort: r.tip.short, version: r.tip.version }));
+  const versionParts = parts.length;
+  const pending = r.schemaBehind ? safeCount(r.live?.schemaPending) : null;
+  if (pending) {
+    parts.push(`its database is MISSING ${pending} migration${pending === 1 ? '' : 's'} the running code ships, so the first query that touches ${pending === 1 ? 'it' : 'them'} fails`);
+  }
+  if (!parts.length) return null;
+
+  const advice = [];
+  // Fixed vocabulary + the bounded host only (this line is injected context).
+  if (versionParts) advice.push(`${hubRule(host)}; ${HOSTED_LINE.charAt(0).toLowerCase()}${HOSTED_LINE.slice(1)} Never call work live until that instance's /version shows it.`);
+  if (pending) advice.push('Run migrate against that instance DB (PGDATABASE set) before anything else.');
+  return `Deploy state (read from ${host}/version): ${parts.join('; ')}. ${advice.join(' ')}`;
+}
+
+async function main() {
+  const quiet = hasFlag('--quiet');
+  const warnOnly = hasFlag('--warn-only');
+  // --line: the SessionStart shape. FAIL-OPEN — a divergence is context for the
+  // agent, and an unreachable instance is nothing at all; neither is a failure of
+  // the session this is injected into. So: swallow everything, exit 0 always.
+  //
+  // Note it sets exitCode and RETURNS rather than calling process.exit(). Exiting
+  // explicitly here raced libuv's teardown of the fetch socket and aborted the
+  // process on Windows/Node 24 (`Assertion failed: !(handle->flags &
+  // UV_HANDLE_CLOSING)`, exit 127) — the line printed correctly and the command
+  // still "failed", which is the one outcome a fail-open path must never produce.
+  // Natural exit is both clean and prompt (~180ms) because the check is the only
+  // work in flight.
+  if (hasFlag('--line')) {
+    const ms = Number(arg('--timeout-ms')) || DEFAULT_TIMEOUT_MS;
+    try {
+      // Shared across concurrent session starts (task 1003689): four sessions opened
+      // seconds apart asked this same question four times and all four timed out, which
+      // emits NO line — and silence from a truth-teller reads as "nothing to report".
+      const { cached } = require('./probe-cache.js');
+      const { value: one } = await cached('deploy-divergence-line', async () => line(await check({ timeoutMs: ms, withReach: false })));
+      if (one) console.log(one);
+    } catch { /* offline, no git, unreadable module-api — all silence */ }
+    process.exitCode = 0;
+    return undefined;
+  }
+  const r = await check();
+  report(r, { quiet });
+  // Same reason --line sets exitCode instead of calling process.exit: exiting
+  // explicitly here raced libuv's teardown of the fetch socket and aborted with
+  // `Assertion failed: !(handle->flags & UV_HANDLE_CLOSING)` → exit 127, so the
+  // documented 0/1/2 contract above was not actually what callers saw on
+  // Windows. Pre-dates task 1002713 (reproduced on clean origin/main); fixed
+  // here because it is this same exit path. The codes themselves are unchanged.
+  if (warnOnly) process.exitCode = 0;
+  else if (r.undetermined) process.exitCode = 2;
+  else process.exitCode = r.ok ? 0 : 1;
+  return undefined;
+}
+
+if (require.main === module) {
+  main().catch((e) => {
+    console.error('deploy-divergence: failed —', e.message || e);
+    process.exit(2);
+  });
+}
+
+module.exports = { check, report, line, coreVersionAt, unreleasedSince, cmpSemver, subscriptionHealth, liveIncludes, hubReading };

package/scripts/bongos/deploy-main-audit-gate.sh

@@ -0,0 +1,97 @@
+#!/bin/sh
+# scripts/bongos/deploy-main-audit-gate.sh — the SEC #863 / ADR 0043 deploy-side gate.
+#
+# Refuses a deploy when a builder BELOW Metic modified a permission-sensitive path in the
+# delta this deploy introduces. Run from the instance checkout root, AFTER the working tree
+# has been moved to the new commit and BEFORE anything is migrated or restarted.
+#
+#   OTB_DEPLOY_PREV_SHA="$(git rev-parse HEAD)"; export OTB_DEPLOY_PREV_SHA   # BEFORE the pull
+#   git reset --hard origin/main
+#   sh node_modules/@bongos/core/scripts/bongos/deploy-main-audit-gate.sh || exit 1
+#   ...migrate, restart...
+#
+# WHY THIS LIVES IN THE CORE (task 1001426). It used to live in the control-plane repo's
+# infra/, where a standalone instance checkout cannot reach it — and on cloudbongos.com it
+# was never wired into ~/deploy.sh at all, so the "poison never reaches prod" check had
+# never once run. Shipping it beside main-audit.js means every instance inherits the gate
+# with its pinned core, and there is no per-instance copy to drift.
+#
+# THE MARKER IS THE CHECKED-OUT HEAD, AND IT ADVANCES ONLY ON SUCCESS.
+# That is the substance of this task and the reason the restore below is in the GATE rather
+# than in each caller's deploy script. The gate can only audit what was pulled, so it runs
+# after the tree has already moved. Exiting non-zero and leaving it moved would mean the
+# next deploy computes OTB_DEPLOY_PREV_SHA from the POISONED commit, never re-audits that
+# delta, and finds the poison already checked out — the marker-bypass this gate exists to
+# close, reintroduced one layer up. So a refusal puts the tree back where it started.
+# Set OTB_GATE_NO_RESTORE=1 only when the caller restores it itself.
+#
+# STRICT IS OFF BY DEFAULT, AND THAT IS NOT LAZINESS. Rank resolution keys on github_login
+# only (#863-followup finding #6: display_name is builder-controlled, so keying it let one
+# builder alias another's rank). A deploy lane whose commits are authored under a human
+# display name ("Firstname Lastname") rather than the builder's github_login therefore
+# resolves to nothing, and OTB_AUDIT_STRICT=1 would block every deploy forever.
+# Non-strict still hard-blocks the incident class this was built for: a RESOLVED below-Metic
+# author touching a protected path. Turn strict on once the lane commits under logins.
+#
+# KNOWN LIMIT, stated because a gate nobody distrusts is worse than no gate: if the roster
+# cannot be read at all, every author is unresolved and non-strict passes. main-audit.js
+# announces that loudly on stderr (task 1001426 gave it a fallback and a voice — it used to
+# fail silently and return an empty map, so the gate reported a clean audit that never ran).
+# Availability is chosen over a hard stop deliberately: a database blip must not freeze
+# deploys. Read the stderr.
+
+set -eu
+
+# The range rides main-audit.js's --range flag, never an env var (task 1001441): a
+# shell cannot compute the instance's branded env prefix (<PREFIX>_AUDIT_RANGE), and
+# argv needs none. AUDIT_RANGE below is this script's own variable, not exported.
+AUDIT_RANGE=""
+if [ -n "${OTB_DEPLOY_PREV_SHA:-}" ]; then
+  AUDIT_RANGE="${OTB_DEPLOY_PREV_SHA}..HEAD"
+  echo "main audit: range ${AUDIT_RANGE} (exact deploy delta)"
+else
+  echo "main audit: OTB_DEPLOY_PREV_SHA not set — falling back to the wide window."
+  echo "  (Recommended: capture OTB_DEPLOY_PREV_SHA=\$(git rev-parse HEAD) BEFORE the pull;"
+  echo "   without it a poisoned commit buried under the window can escape, and a refusal"
+  echo "   cannot put the tree back.)"
+fi
+
+STRICT=""
+[ "${OTB_AUDIT_STRICT:-0}" = "1" ] && STRICT="--strict"
+
+# Prefer the installed core; fall back to an in-tree checkout (the core repo itself).
+MAIN_AUDIT="node_modules/@bongos/core/scripts/bongos/main-audit.js"
+[ -f "$MAIN_AUDIT" ] || MAIN_AUDIT="scripts/bongos/main-audit.js"
+if [ ! -f "$MAIN_AUDIT" ]; then
+  echo "X DEPLOY ABORTED: main-audit.js not found (looked in node_modules/@bongos/core and in-tree)."
+  echo "  A gate that cannot find its auditor must fail closed, not wave the deploy through."
+  exit 1
+fi
+
+if [ -n "$AUDIT_RANGE" ]; then set -- --range "$AUDIT_RANGE"; else set --; fi
+# ${1+"$@"}, not "$@": an empty "$@" under set -u is an unbound-variable error in
+# older /bin/sh (bash 3.2, macOS).
+if node "$MAIN_AUDIT" --verify-head --db ${STRICT} ${1+"$@"}; then
+  echo "OK main audit clean${STRICT:+ (strict)} — proceeding with deploy."
+  exit 0
+fi
+
+echo ""
+echo "X DEPLOY ABORTED (SEC #863): a below-Metic${STRICT:+ or unresolved} author modified a"
+echo "  permission-sensitive path in this deploy. Investigate and revert before deploying:"
+echo "      node $MAIN_AUDIT --range \"\${AUDIT_RANGE:-HEAD~200..HEAD}\" --revert"
+
+if [ -n "${OTB_DEPLOY_PREV_SHA:-}" ] && [ "${OTB_GATE_NO_RESTORE:-0}" != "1" ]; then
+  if git rev-parse --verify --quiet "${OTB_DEPLOY_PREV_SHA}^{commit}" >/dev/null; then
+    echo ""
+    echo "  restoring the checkout to ${OTB_DEPLOY_PREV_SHA} — the deployed marker advances only on success,"
+    echo "  so the NEXT deploy re-audits this same delta instead of treating it as already-reviewed."
+    git reset --hard "${OTB_DEPLOY_PREV_SHA}" >/dev/null
+  else
+    echo ""
+    echo "  ::WARNING:: cannot restore — ${OTB_DEPLOY_PREV_SHA} is not a commit in this checkout."
+    echo "  The tree is left at the REFUSED commit; the next deploy will not re-audit this delta."
+  fi
+fi
+
+exit 1

package/scripts/bongos/design-sync.js

@@ -0,0 +1,12 @@
+#!/usr/bin/env node
+'use strict';
+// design-sync.js — thin shim: the Claude Design sync CLI lives in the ui-design
+// module at modules/ui-design/scripts/design-sync.js (task 1003324, ADR 0197).
+//
+// WHY a shim rather than re-pointing every caller: `node scripts/bongos/<x>.js` is
+// the form the skills and recipes use, and the form claude-materialize rewrites to
+// `bongos exec scripts/bongos/<x>.js` when the core installs as a package — so this
+// path stays the stable, documented entry point. Flags pass straight through:
+//   node scripts/bongos/design-sync.js                 — build the token-preview bundle, print the manifest
+//   node scripts/bongos/design-sync.js --surface <id>  — limit to one surface
+require('../../modules/ui-design/scripts/design-sync.js');