@bongos/core 1.17.3 → 1.18.3

package/scripts/gds/ship.js

@@ -84,8 +84,22 @@ const GRADER_TIMEOUT_MS = 240_000; // 4 min — Opus on a big diff with Read too
 // feature worktree this script lives in. Falls back to two-levels-up if we
 // can't ask git (e.g. fresh clone with no `main` worktree set up yet).
 const REPO_ROOT = findMainWorktree(__dirname) || path.resolve(__dirname, '..', '..');
-const { playSound } = require(path.resolve(__dirname, '../../.claude/sounds/play.js'));
-const DROPLET = 'lars@104.236.254.243';
+// Sound playback is COSMETIC — the ship pipeline must NEVER depend on it. Guard
+// the require so a missing/broken player (e.g. .claude/sounds/ absent on a fresh
+// clone or after a re-seed) degrades to a silent no-op instead of crashing ship.js
+// at load. A cosmetic feature can't be allowed to break shipping (task 1002199).
+const { playSound } = (() => {
+  try {
+    return require(path.resolve(__dirname, '../../.claude/sounds/play.js'));
+  } catch {
+    return { playSound: () => {} };
+  }
+})();
+// The laptop-mode SSH deploy target is resolved at land time from config/deploy.json
+// ("sshTarget") or <PREFIX>_DEPLOY_SSH_TARGET — see resolveDeployTarget(). There is NO
+// hardcoded default: the core carries no deploy target of its own. The founder
+// instance's old game-box SSH target used to be baked in here, which post-migration
+// meant a laptop-mode ship deployed to the WRONG server (task 1002202).
 const BEHIND_MAIN_LIMIT = 5;
 
 // arg() — the =-aware flag-value parser now lives in cli-lib (the canonical
@@ -752,9 +766,13 @@ function buildMergeArgv(branch, valueSummary) {
 // Two ways the confirmed→shipped land can run, chosen by a SINGLE committed
 // switch (config/deploy.json `mode`, env OTB_DEPLOY_MODE overrides):
 //
-//   'laptop' (default) — the operator's machine merges to main locally and
-//      SSHes `~/deploy.sh` on the droplet. Today's behavior, byte-for-byte.
-//      Requires the droplet SSH key, so only the operator can land.
+//   'laptop' (default) — the operator's machine merges to main locally and, IFF a
+//      deploy target is configured (config/deploy.json "sshTarget" or
+//      <PREFIX>_DEPLOY_SSH_TARGET, resolveDeployTarget()), SSHes `~/deploy.sh` on it.
+//      The core carries NO target of its own, so by default this is a merge-to-main
+//      with no SSH deploy — a change reaches a live instance via package-core +
+//      `bongos upgrade` (pin-bump), NOT an SSH deploy (ADR 0108). When a target IS
+//      set it requires that host's SSH key, so only the operator can land.
 //
 //   'ci' — NO builder box holds the prod key. ship pushes the branch, opens a
 //      PR, and enables GitHub auto-merge; once required checks pass, GitHub
@@ -805,12 +823,7 @@ function effectiveDeployMode(mode, { canPushLocally, envForced } = {}) {
 }
 
 function resolveDeployMode() {
-  let configRaw = null;
-  try {
-    configRaw = fs.readFileSync(path.join(REPO_ROOT, 'config', 'deploy.json'), 'utf8');
-  } catch (_) {
-    /* no config file → safe default */
-  }
+  const configRaw = readDeployConfigRaw();
   const mode = parseDeployMode(process.env.OTB_DEPLOY_MODE, configRaw);
   const envForced = ['ci', 'laptop'].includes(
     String(process.env.OTB_DEPLOY_MODE || '').trim().toLowerCase()
@@ -824,6 +837,63 @@ function resolveDeployMode() {
   return mode;
 }
 
+// readDeployConfigRaw — raw contents of config/deploy.json (or null if absent /
+// unreadable). One reader shared by resolveDeployMode (the mode switch) and
+// resolveDeployTarget (the SSH target) so they never diverge on where the file is.
+function readDeployConfigRaw() {
+  try {
+    return fs.readFileSync(path.join(REPO_ROOT, 'config', 'deploy.json'), 'utf8');
+  } catch (_) {
+    return null; // no config file → callers apply their safe default
+  }
+}
+
+// safeBranding — the instance brand pack, or null if it can't be read. Guarded the
+// same way ship.js guards the sound player (line ~91): a deploy must never crash
+// because the brand file is missing on a fresh / re-seeded checkout.
+function safeBranding() {
+  try {
+    return require('../../src/branding').branding();
+  } catch (_) {
+    return null;
+  }
+}
+
+// resolveDeployTarget — WHERE a laptop-mode ship SSHes `~/deploy.sh`, and which
+// /healthz it re-probes when deploy.sh's own health check races the restart window.
+// Pure (env + raw config + branding → target) and exported so the precedence and the
+// safe "no target" default are unit-tested without touching fs/env/network.
+//
+// There is deliberately NO hardcoded default. The founder instance's old game-box
+// SSH target was baked in here, so a laptop-mode ship from a migrated
+// checkout SSHed the WRONG server (task 1002202). The core carries no deploy target
+// of its own — under the standalone model a core change reaches a live instance via
+// package-core + `bongos upgrade` (pin-bump), not an SSH deploy (ADR 0108). An
+// instance whose OWN checkout is its live server opts back into laptop-SSH deploy by
+// setting the target:
+//   config/deploy.json  → { "sshTarget": "user@host", "healthzUrl": "https://…/healthz" }
+//   env                 → <PREFIX>_DEPLOY_SSH_TARGET, <PREFIX>_DEPLOY_HEALTHZ_URL
+// healthzUrl, when unset, falls back to the instance's own publicOrigin + /healthz
+// (never a hardcoded host); null when even that is unknown (re-probe then skipped).
+function resolveDeployTarget({ env = process.env, configRaw = null, branding = null } = {}) {
+  const ic = require('../../src/instance-config');
+  let cfg = {};
+  if (configRaw) {
+    try { cfg = JSON.parse(configRaw) || {}; } catch (_) { cfg = {}; }
+  }
+  const str = (v) => (typeof v === 'string' && v.trim() ? v.trim() : null);
+
+  const sshTarget = ic.resolveEnv('DEPLOY_SSH_TARGET', { env }) || str(cfg.sshTarget) || null;
+
+  let healthzUrl = ic.resolveEnv('DEPLOY_HEALTHZ_URL', { env }) || str(cfg.healthzUrl) || null;
+  const publicOrigin = branding && branding.domains && branding.domains.publicOrigin;
+  if (!healthzUrl && str(publicOrigin)) {
+    try { healthzUrl = new URL('/healthz', publicOrigin).toString(); }
+    catch (_) { /* malformed origin → leave healthzUrl null */ }
+  }
+  return { sshTarget, healthzUrl };
+}
+
 // gh runners — mirror gitArgvOk/gitOk but for the GitHub CLI. No shell, ever:
 // branch names + DB-sourced value_summary reach `gh` as literal argv elements
 // (same injection discipline as #681). ghArgvOk = boolean side-effect; ghJson =
@@ -2119,26 +2189,48 @@ async function autoMerge(taskId, valueSummary, { dbOnly = false } = {}) {
       return false;
     }
 
-    console.log('  triggering deploy on droplet...');
-    // Quote ~/deploy.sh so the LOCAL shell doesn't tilde-expand it to
-    // /Users/<mac-user>/deploy.sh before ssh transmits the command. With
-    // the quotes, ssh sends the literal `~/deploy.sh` and the REMOTE shell
-    // expands it to /home/lars/deploy.sh. (Matches /merge-mode SKILL.md:81.)
-    if (!shellOk(`ssh -o ConnectTimeout=10 ${DROPLET} "~/deploy.sh"`)) {
-      // task 984 / idea 180: ~/deploy.sh's internal /healthz curl can race the
-      // service-restart window (Node not yet bound) and exit non-zero even though
-      // the deploy succeeded — which used to false-fail the ship and force a
-      // needless /merge-mode. Before concluding failure, re-probe the public
-      // /healthz with backoff (curl's own --retry; cross-platform, no sleep).
-      // --retry-all-errors retries connection-refused during the bind window;
-      // -f makes a non-200 an error so a 502/503 also retries. If it comes up
-      // within the window the deploy really succeeded; only then-still-down fails.
-      console.log('  auto-merge: ~/deploy.sh returned non-zero — re-probing /healthz with backoff before concluding...');
-      if (shellOk('curl -fsS --max-time 10 --retry 5 --retry-delay 3 --retry-all-errors https://amazonprimea.com/healthz -o /dev/null')) {
-        console.log('  auto-merge: /healthz 200 on re-probe — deploy actually succeeded (deploy.sh raced the restart window). Proceeding.');
-      } else {
-        console.log('  auto-merge: deploy failed (/healthz never returned 200 after retries); task stays at confirmed');
-        return false;
+    // Deploy step. The core carries NO deploy target of its own — under the
+    // standalone model a core change reaches a live instance via package-core +
+    // `bongos upgrade` (pin-bump), NOT an SSH deploy (ADR 0108). So unless an
+    // instance whose own checkout IS its live server has configured a target
+    // (config/deploy.json "sshTarget" or <PREFIX>_DEPLOY_SSH_TARGET), the land is
+    // complete at "merged + pushed to main" and the SSH deploy is skipped. (This
+    // used to SSH a hardcoded target — the founder instance's old game box, i.e. the
+    // WRONG server post-migration. task 1002202.)
+    const { sshTarget, healthzUrl } = resolveDeployTarget({
+      configRaw: readDeployConfigRaw(),
+      branding: safeBranding(),
+    });
+    if (!sshTarget) {
+      console.log('  merged + pushed to main. No deploy target configured, so no SSH deploy —');
+      console.log('  expected for the core. To publish to a live instance run the standalone release');
+      console.log('  flow: package-core → bongos upgrade (pin-bump), per ADR 0108. (Not an SSH deploy.)');
+    } else {
+      console.log(`  triggering deploy on ${sshTarget}...`);
+      // Quote ~/deploy.sh so the LOCAL shell doesn't tilde-expand it before ssh
+      // transmits the command; with the quotes ssh sends the literal `~/deploy.sh`
+      // and the REMOTE shell expands it. (Matches /merge-mode SKILL.md:81.)
+      if (!shellOk(`ssh -o ConnectTimeout=10 ${sshTarget} "~/deploy.sh"`)) {
+        // task 984 / idea 180: ~/deploy.sh's internal /healthz curl can race the
+        // service-restart window (Node not yet bound) and exit non-zero even though
+        // the deploy succeeded — which used to false-fail the ship and force a
+        // needless /merge-mode. Before concluding failure, re-probe the CONFIGURED
+        // /healthz with backoff (curl's own --retry; cross-platform, no sleep) —
+        // never a hardcoded host. --retry-all-errors retries connection-refused
+        // during the bind window; -f makes a non-200 an error so a 502/503 also
+        // retries. If it comes up within the window the deploy really succeeded.
+        if (healthzUrl) {
+          console.log('  auto-merge: ~/deploy.sh returned non-zero — re-probing /healthz with backoff before concluding...');
+          if (shellOk(`curl -fsS --max-time 10 --retry 5 --retry-delay 3 --retry-all-errors ${JSON.stringify(healthzUrl)} -o /dev/null`)) {
+            console.log('  auto-merge: /healthz 200 on re-probe — deploy actually succeeded (deploy.sh raced the restart window). Proceeding.');
+          } else {
+            console.log('  auto-merge: deploy failed (/healthz never returned 200 after retries); task stays at confirmed');
+            return false;
+          }
+        } else {
+          console.log('  auto-merge: ~/deploy.sh returned non-zero and no healthzUrl configured to re-probe; task stays at confirmed');
+          return false;
+        }
       }
     }
 
@@ -3538,7 +3630,9 @@ module.exports = {
   gitArgvOk, buildMergeArgv, sanitizeGitHubRefs,
   // #679 / ADR 0042: CI deploy mode — pure helpers exported for the regression
   // test (mode precedence/safe-default, no-shell PR argv, deploy-run match).
-  parseDeployMode, buildPrCreateArgv, buildPrMergeArgv, deployRunSucceeded,
+  // task 1002202: resolveDeployTarget — SSH target / healthz precedence + the safe
+  // "no target" default (the core has none), exported for the same reason.
+  parseDeployMode, resolveDeployTarget, buildPrCreateArgv, buildPrMergeArgv, deployRunSucceeded,
   // task 1049 (B): pure CI-land outcome classifier — a timed-out-but-armed PR is
   // 'pending' (success), not failure. Exported so the semantics are unit-tested.
   classifyLandOutcome,

package/scripts/gds/upgrade.js

@@ -295,6 +295,91 @@ async function pollHealth(healthUrl, deps = {}) {
   }
 }
 
+// ---- integrity-pin verification (task 1002216 / audit H8, finding F1) --------
+// The packager (package-core.js) computes tree_sha256 = canonicalTreeHash over the
+// redacted core files (+ the two synthesized files) and records it, the per-file
+// hashes, AND the exact tarball bytes' sha256 in a side-car manifest — stating a
+// consumer "verifies an install by recomputing it from the unpacked tree." Until now
+// nothing on the CONSUME side did: `bongos upgrade` compared only the version STRING,
+// so a corrupted / truncated / swapped tarball whose package.json still read the target
+// version installed silently — the R88-class failure this goal exists to prevent.
+// The three functions below close that gap: recompute the pin over the INSTALLED tree
+// and assert it equals the TRUSTED reference manifest.
+
+// Read + parse a manifest JSON; null on any failure (missing / unparseable).
+function readManifest(file, fsImpl = fs) {
+  try { return JSON.parse(fsImpl.readFileSync(file, 'utf8')); } catch { return null; }
+}
+
+// Resolve the trusted reference pin for this bump:
+//   • VENDORED — the committed side-car `vendor/<artifact>-<v>.manifest.json` (carries
+//     tree_sha256 + files[] + the exact tarball.sha256). It lives OUTSIDE the tarball
+//     (version-controlled in the consumer repo), so it detects a swapped/corrupted
+//     tarball. This is the strong reference.
+//   • REGISTRY / no side-car — the inner manifest `<core>/.bongos-core.json` that ships
+//     INSIDE the package (tree_sha256 + files[], no tarball.*). Self-referential (a full
+//     swap regenerates it too), so it is a self-consistency check backing npm's own
+//     registry integrity rather than an independent one — flagged `strong:false`.
+function resolveReferenceManifest({ instanceDir, coreDir, targetVersion }, fsImpl = fs) {
+  const sidecarPath = path.join(instanceDir, 'vendor', `${ARTIFACT}-${targetVersion}.manifest.json`);
+  const sidecar = readManifest(sidecarPath, fsImpl);
+  if (sidecar && sidecar.tree_sha256) {
+    const tgz = path.join(instanceDir, 'vendor', `${ARTIFACT}-${targetVersion}.tgz`);
+    return { manifest: sidecar, tgzPath: fsImpl.existsSync(tgz) ? tgz : null, source: 'vendored side-car manifest', strong: true };
+  }
+  const inner = readManifest(path.join(coreDir, '.bongos-core.json'), fsImpl);
+  if (inner && inner.tree_sha256) return { manifest: inner, tgzPath: null, source: 'installed inner manifest', strong: false };
+  return { manifest: null, tgzPath: null, source: null, strong: false };
+}
+
+// Recompute the integrity pin over the installed core tree and compare to `referenceManifest`.
+// Reuses the PACKAGER's exact hash functions (canonicalTreeHash / sha256hex) so the consume-side
+// recompute can never drift from the produce-side pin. Returns { ran, ok, checks, problems };
+// ran=false ⇒ the manifest carried no pin to check against.
+function verifyInstalledPin({ coreDir, referenceManifest, tgzPath }, deps = {}) {
+  const fsImpl = deps.fs || fs;
+  const pc = deps.packageCore || require('./package-core');
+  const checks = [];
+  const problems = [];
+  if (!referenceManifest || !referenceManifest.tree_sha256) return { ran: false, ok: false, checks, problems };
+
+  // (a) exact tarball bytes (vendored path only) — the strongest single check: the bytes
+  //     npm actually installs, hashed and compared to the externally-held pin.
+  const tb = referenceManifest.tarball;
+  if (tgzPath && tb && tb.sha256 && fsImpl.existsSync(tgzPath)) {
+    const got = pc.sha256hex(fsImpl.readFileSync(tgzPath));
+    const ok = got === tb.sha256;
+    checks.push({ name: 'tarball.sha256', ok });
+    if (!ok) problems.push(`vendored tarball bytes sha256 ${got.slice(0, 12)}… ≠ pinned ${String(tb.sha256).slice(0, 12)}…`);
+  }
+
+  // (b) installed tree — recompute each pinned file's sha256 from the unpacked tree, rebuild
+  //     the canonical tree hash (using the manifest's already-canonical modes), assert equality.
+  //     Catches partial extraction, post-install corruption, or a registry package that diverged.
+  const files = Array.isArray(referenceManifest.files) ? referenceManifest.files : [];
+  if (files.length) {
+    const recomputed = [];
+    let missing = 0, changed = 0;
+    for (const f of files) {
+      const abs = path.join(coreDir, ...String(f.path).split('/')); // POSIX manifest path → native
+      let buf;
+      try { buf = fsImpl.readFileSync(abs); } catch { missing++; problems.push(`missing installed file: ${f.path}`); continue; }
+      const sha = pc.sha256hex(buf);
+      if (sha !== f.sha256) { changed++; problems.push(`content mismatch: ${f.path}`); }
+      recomputed.push({ path: f.path, mode: f.mode, sha256: sha });
+    }
+    const treeHash = pc.canonicalTreeHash(recomputed);
+    const ok = missing === 0 && changed === 0 && treeHash === referenceManifest.tree_sha256;
+    checks.push({ name: 'tree_sha256', ok, missing, changed, file_count: files.length });
+    if (!ok && missing === 0 && changed === 0) {
+      problems.push(`recomputed tree_sha256 ${treeHash.slice(0, 12)}… ≠ pinned ${String(referenceManifest.tree_sha256).slice(0, 12)}…`);
+    }
+  }
+
+  const ran = checks.length > 0;
+  return { ran, ok: ran && problems.length === 0, checks, problems };
+}
+
 // Auto-rollback (task 2149): a bump failed AFTER the pin was moved — an install or migrate
 // error, or a failed post-restart health check. Revert the code pin to the pre-upgrade
 // snapshot, reinstall the previous core, restart, re-verify health, and record the reversal
@@ -390,6 +475,18 @@ async function runUpgrade(opts, deps = {}) {
   log(`  ✓ pre-flight: ${mods.note}`);
   if (!mods.ok) return { ok: false, error: `module pre-check failed: ${mods.blocking.map((b) => b.key).join(', ')} incompatible with core ${targetVersion}` };
 
+  // 1b. mandatory post-restart health check (audit H9 / task 1002222, finding F5). A bump that
+  //     brings the new core live via a managed restart (--service / --restart-cmd) MUST confirm it
+  //     actually serves — an upgrade that can't be health-checked can't be reported as a success.
+  //     Enforced here in PRE-FLIGHT, before anything is mutated, so there is nothing to roll back:
+  //     if this bump will restart the service and the check isn't explicitly opted out, a
+  //     --health-url is required. (No managed restart ⇒ nothing is brought live here ⇒ the check
+  //     does not apply; the operator restarts + verifies separately.)
+  const willRestart = !!(opts.service || opts.restartCmd);
+  if (!dryRun && opts.healthCheck !== false && willRestart && !opts.healthUrl) {
+    return { ok: false, error: 'post-restart health check is mandatory for a bump that restarts the service, but no --health-url was given.\n  Pass --health-url <url> to confirm the new core serves after restart, or --no-health-check to explicitly skip the confirmation.' };
+  }
+
   // 2. bump the pin. Two mutually exclusive core sources (ADR 0134, task 2090):
   //    REGISTRY (--registry): pin @bongos/core@<version> + ensure the env-fed .npmrc, so
   //      the `npm install` below pulls the PRIVATE package from the registry (needs NPM_TOKEN).
@@ -429,6 +526,38 @@ async function runUpgrade(opts, deps = {}) {
   }
   log('  ✓ npm install');
 
+  // 3b. verify the integrity pin (audit H8 / task 1002216, finding F1). Recompute tree_sha256 over
+  //     the freshly-installed core (+ the exact vendored tarball bytes) and assert it matches the
+  //     TRUSTED reference manifest — the pin the packager produced but the consume side never
+  //     re-checked. Runs BEFORE migrate so a corrupted core can never touch the DB. A MISMATCH is
+  //     fatal → rollback (like an install/migrate failure). A MISSING reference (no side-car AND no
+  //     inner manifest) can't be verified: a warning by default, fatal only with --require-pin.
+  if (!opts.skipPinVerify) {
+    const coreDir = path.join(instanceDir, 'node_modules', CORE_PKG);
+    const ref = (deps.resolveReferenceManifest || resolveReferenceManifest)({ instanceDir, coreDir, targetVersion }, fsImpl);
+    if (!ref.manifest) {
+      const msg = `integrity pin: no reference manifest (looked for vendor/${ARTIFACT}-${targetVersion}.manifest.json and ${CORE_PKG}/.bongos-core.json) — cannot verify this install`;
+      if (opts.requirePin) {
+        const error = `${msg} (--require-pin)`;
+        if (rollbackOnFailure && snapshot) { const rb = await doRollback('integrity pin unverifiable (--require-pin)'); return { ok: false, error, fromVersion, toVersion: targetVersion, rolledBack: true, rollback: rb }; }
+        return { ok: false, error, fromVersion };
+      }
+      err(`  ! ${msg} — pass --require-pin to treat this as fatal.`);
+    } else {
+      const pin = (deps.verifyInstalledPin || verifyInstalledPin)({ coreDir, referenceManifest: ref.manifest, tgzPath: ref.tgzPath }, deps);
+      if (!pin.ok) {
+        const detail = pin.problems.slice(0, 6).join('; ') + (pin.problems.length > 6 ? `; +${pin.problems.length - 6} more` : '');
+        const error = `integrity pin MISMATCH (${ref.source}) — installed core does not match its pin: ${detail}`;
+        if (rollbackOnFailure && snapshot) {
+          const rb = await doRollback('integrity pin mismatch');
+          return { ok: false, error, fromVersion, toVersion: targetVersion, rolledBack: true, rollback: rb };
+        }
+        return { ok: false, error, fromVersion };
+      }
+      log(`  ✓ integrity pin verified (${pin.checks.map((c) => c.name).join(' + ')}) against the ${ref.source}${ref.strong ? '' : ' — self-consistency check; npm registry integrity is the primary guard'}`);
+    }
+  } else log('  • integrity-pin verify skipped (--skip-pin-verify)');
+
   // 4. migrate (additive core_* migrations).
   if (!opts.skipMigrate) {
     const mig = runMigrate(instanceDir, run);
@@ -472,11 +601,17 @@ async function runUpgrade(opts, deps = {}) {
   log(`  ${versionOk ? '✓' : '!'} installed core version: ${installed || '(unknown)'}${versionOk ? '' : ` (expected ${targetVersion})`}`);
 
   let healthOk = null;
-  if (opts.healthUrl) {
+  if (opts.healthCheck === false) {
+    log('  • post-restart health check skipped (--no-health-check) — success is NOT confirmed against a live endpoint.');
+  } else if (opts.healthUrl) {
     const h = await pollHealth(opts.healthUrl, deps);
     healthOk = h.ok;
     if (h.ok) log(`  ✓ health ${opts.healthUrl} → ${h.status}${h.attempts > 1 ? ` (ready after ${h.attempts} tries)` : ''}`);
     else err(`  ! health ${opts.healthUrl} not ready after ${h.attempts} tr${h.attempts === 1 ? 'y' : 'ies'}: ${h.error || 'status ' + h.status}`);
+  } else {
+    // Reachable only when NO managed restart happened (pre-flight requires a URL when one will):
+    // the new core is installed on disk, but nothing was brought live here to health-check.
+    log('  • no managed restart + no --health-url — new core installed but not confirmed serving; restart the instance + health-check it to complete the bump.');
   }
 
   // A failed post-restart health check means the new core is serving broken — auto-revert (task
@@ -514,6 +649,9 @@ function parseArgs(argv) {
     skipMigrate: hasFlag('--skip-migrate', argv),
     skipMaterialize: hasFlag('--skip-materialize', argv),
     skipRegenDocs: hasFlag('--skip-regen-docs', argv),
+    skipPinVerify: hasFlag('--skip-pin-verify', argv), // task 1002216: opt out of the post-install integrity-pin check
+    requirePin: hasFlag('--require-pin', argv), // task 1002216: a MISSING reference manifest becomes fatal (not just a warning)
+    healthCheck: !hasFlag('--no-health-check', argv), // task 1002222: post-restart health check is ON by default (finding F5/H9)
     rollbackOnFailure: !hasFlag('--no-rollback-on-failure', argv), // ADR 0100: auto-revert ON by default (task 2149)
   };
 }
@@ -533,16 +671,19 @@ async function main(argv = process.argv.slice(2)) {
       '  --instance <dir>     consumer instance root (default: cwd)',
       '  --service <unit>     systemd unit to restart after applying',
       '  --restart-cmd <cmd>  explicit restart command (overrides --service)',
-      '  --health-url <url>   poll after restart (~30s) until 2xx; still-failing is a warning',
+      '  --health-url <url>   poll after restart (~30s) until 2xx; a still-failing check fails the bump (auto-rollback). REQUIRED for a bump that restarts the service, unless --no-health-check.',
+      '  --no-health-check    explicitly skip the post-restart health confirmation (default: the check is ON — a bump that restarts the service must confirm it serves)',
       '  --skip-migrate       do not run `npm run migrate`',
       '  --skip-materialize   do not refresh .claude/',
       '  --skip-regen-docs    do not regenerate the OpenAPI spec + typed client from the new core',
-      '  --no-rollback-on-failure  do NOT auto-revert on a failed install/migrate/health check (default: auto-rollback ON)',
+      '  --skip-pin-verify    do not verify the integrity pin (tree_sha256 + tarball.sha256) after install',
+      '  --require-pin        treat a MISSING reference manifest as fatal (default: warn — a MISMATCH is always fatal)',
+      '  --no-rollback-on-failure  do NOT auto-revert on a failed install/pin-verify/migrate/health check (default: auto-rollback ON)',
       '  --dry-run            show the plan; change nothing',
       '  --force              skip the clean-tree + same-version guards',
       '',
-      'Full bump: pre-flight → bump pin → npm install → migrate → materialize .claude → regen API docs+client → restart → verify.',
-      'On a failure after the pin moves (install/migrate/health), auto-rollback reverts the pin, reinstalls the previous core, restarts, and records a rolled_back ledger row (the DB is not rolled back — core migrations are additive).',
+      'Full bump: pre-flight → bump pin → npm install → verify integrity pin → migrate → materialize .claude → regen API docs+client → restart → verify.',
+      'On a failure after the pin moves (install/pin-verify/migrate/health), auto-rollback reverts the pin, reinstalls the previous core, restarts, and records a rolled_back ledger row (the DB is not rolled back — core migrations are additive).',
     ].join('\n') + '\n');
     return 0;
   }
@@ -560,6 +701,7 @@ module.exports = {
   runUpgrade, parseArgs, main, rollback,
   versionFromTgzPath, versionFromDep, readInstalledCoreVersion, readPinnedCoreVersion, writePin, writeRegistryPin, restorePin,
   vendorTarball, gitTreeClean, preflightModules, npmInstall, runMigrate, regenerateApiArtifacts, restartService, recordLedger, pollHealth,
+  readManifest, resolveReferenceManifest, verifyInstalledPin, // task 1002216 (audit H8) — integrity-pin verification
   CORE_PKG, ARTIFACT,
 };
 

package/scripts/hall-preview/server.js

@@ -19,6 +19,8 @@
 //                  window.__MODULES__ (verifies moduleOn() gating)
 //   --empty        serve every fixture with its arrays emptied — the
 //                  empty-state screenshot pass
+//   --rank archon  override the /me fixture's builder.rank so the Archon-gated
+//                  pages (watch, harbor, gate) render their content in preview
 //
 // Browse http://builders.localhost:<port>/ — Chromium resolves *.localhost,
 // and the `builders.` host prefix exercises the real subdomain serving path.
@@ -39,6 +41,11 @@ function arg(name) {
 }
 const PORT = Number(arg('--port')) || 4600;
 const EMPTY = process.argv.includes('--empty');
+// --rank: view the hall as a different rank — the /me fixture's builder.rank is
+// overridden in the response, so the Archon-gated pages (watch, harbor, gate)
+// render their real content instead of the sealed notice. Preview-only theatre:
+// the real pages are server-gated (requireArchonPage / ADR 0016).
+const RANK_OVERRIDE = arg('--rank');
 const MODULES_OFF = String(arg('--modules-off') || '').split(',').map((s) => s.trim()).filter(Boolean);
 // --modules-on: force-report modules as enabled — a dev box's local config
 // often lacks prod's instance modules (provisioning, dev-box), and their
@@ -68,6 +75,10 @@ const FIXTURE_FALLBACKS = [
   [/^goals\/\d+\/requests$/, 'goals__requests'],
   [/^goals\/\d+$/, 'goals__detail'],
   [/^tasks\/\d+$/, 'tasks__detail'],
+  // the #/idea/N + #/blocker/N deep-link overlay (task-detail.js) — one record
+  // fixture serves any id so the overlay seam assertion renders real content.
+  [/^inbox\/\d+$/, 'inbox__detail'],
+  [/^blockers\/\d+$/, 'blockers__detail'],
   [/^analytics\/builder\/\d+$/, 'analytics__builder'],
   [/^builders\/\d+\/active-claims$/, 'builders__active-claims'],
 ];
@@ -134,7 +145,13 @@ app.use((req, res, next) => {
     console.log(`  no fixture: ${apiPath}  (add scripts/hall-preview/fixtures/${apiPath.replace(/\//g, '__')}.json)`);
     return res.status(404).json({ error: { code: 'no_fixture', message: apiPath } });
   }
-  res.json(EMPTY ? emptied(fix) : fix);
+  let payload = EMPTY ? emptied(fix) : fix;
+  if (RANK_OVERRIDE && apiPath === 'me') {
+    payload = JSON.parse(JSON.stringify(payload));
+    if (payload.builder) payload.builder.rank = RANK_OVERRIDE;
+    else if ('rank' in payload) payload.rank = RANK_OVERRIDE;
+  }
+  res.json(payload);
 });
 
 // The hall pages, pre-auth-gate, through the real seams: boot-time stamped

package/scripts/migrate.sh

@@ -110,6 +110,16 @@ apply_migration() {
     >/dev/null
 }
 
+# --- Forward-safety notice (task 1002223 / audit H10) ---------------------
+# `bongos upgrade` auto-rollback reverts the code pin but NOT the DB — safe only if core migrations
+# are forward-safe (the PREVIOUS code still runs on the new schema). Surface — never block — any
+# UNACKNOWLEDGED forward-unsafe core migration so an operator knows a rollback past it would strand
+# old code on new schema. Fail-closed enforcement is the unit gate (tests/migrations_forward_safe.mjs);
+# here it is advisory (`|| true`) so a lint hiccup can NEVER break a deploy.
+if [ -f "$CORE_ROOT/scripts/gds/lint-migrations.js" ]; then
+  node "$CORE_ROOT/scripts/gds/lint-migrations.js" --warn --dir "$CORE_ROOT/migrations" || true
+fi
+
 # Build the ordered migration list and apply it as ONE numeric sequence by
 # filename stem, regardless of directory:
 #   $CORE_ROOT/migrations/*.sql              — core: schema + platform-universal seeds (EVERY instance).