@bongos/core 1.21.174 → 1.21.176

package/scripts/bongos/ship-check.js

@@ -0,0 +1,89 @@
+#!/usr/bin/env node
+// scripts/bongos/ship-check.js — run every freshness/fitness check ship.js will run, in one command,
+// BEFORE you ship, and print the healing command for each stale thing.
+//
+// Why (task 1003548): a scan of 140 sessions found builders running these generators and checks by
+// hand 223 times in three days (fitness.js ×84, gen-repo-map ×41, copy-inventory ×42, gen-api-docs
+// ×16, linkify-refs ×13, docs-entropy ×12, gen-file-map ×9, gen-session-index ×6), one Bash call at
+// a time, because a ship that fails preflight costs a grader run. The last 30 days of session logs
+// name a stale generated file in roughly a quarter of all sessions. This is that sequence as one
+// call with one table. It CHANGES NOTHING: every step is a --check; the "fix" column is what to run.
+//
+// Usage:
+//   node scripts/bongos/ship-check.js            checks only (fast; no tests) — plus, when the branch changed a
+//                                             page, an ADVISORY render of it (render-check.js; never flips the exit;
+//                                             minutes on a big page — --no-render skips it)
+//   node scripts/bongos/ship-check.js --tests    also run the DB-free unit lane (npm test) and list failures
+//   node scripts/bongos/ship-check.js --json
+// Exit 1 when any check is stale/failing, 0 when everything is fresh.
+'use strict';
+const { spawnSync } = require('node:child_process');
+const fs = require('node:fs');
+const path = require('node:path');
+
+const REPO_ROOT = path.resolve(__dirname, '..', '..');
+
+// Each step: a label, the argv to run (node scripts run with THIS node), the command that heals it,
+// and how to read a non-zero exit. `optional` steps are skipped when their script is absent. An `advisory`
+// step is a signal, never a gate (ADR 0329, decision 3): a non-zero exit reads `warn` (3 = no browser reads `skipped`).
+// `onlyWith` names the flag that adds a step; `skipWith` the flag that leaves one out.
+const STEPS = [
+  { key: 'fitness', label: 'fitness.js (architecture + budgets + freshness gate)', argv: ['scripts/bongos/fitness.js'], fix: 'read the ✗ lines above; each names its fix' },
+  { key: 'repo-map', label: 'nested CLAUDE.md symbol blocks fresh', argv: ['scripts/bongos/gen-repo-map.js', '--check-block'], fix: 'node scripts/bongos/gen-repo-map.js' },
+  { key: 'session-index', label: 'CLAUDE.md §13 session snippet fresh', argv: ['scripts/bongos/gen-session-index.js', '--check-block'], fix: 'node scripts/bongos/gen-session-index.js' },
+  { key: 'file-map', label: 'docs/file-map.md skills/routines sections fresh + every module documented', argv: ['scripts/bongos/gen-file-map.js', '--check'], fix: 'node scripts/bongos/gen-file-map.js (+ a note in docs/file-map.notes.json for a new skill, or a modules/ entry in docs/file-map.md for a new module)' },
+  // task 1004866: the spec, reference and client are gitignored — these prove generation from the routes succeeds, nothing to commit.
+  { key: 'api-docs', label: 'API spec generates from the routes (valid OpenAPI 3.1)', argv: ['scripts/bongos/gen-api-docs.js', '--check'], fix: 'node scripts/bongos/gen-api-docs.js --check (fix the route it names; the stub docs/routes-permissions.md is the only committed output)' },
+  { key: 'api-client', label: 'typed API client generates from the routes', argv: ['scripts/bongos/gen-api-client.js', '--check'], fix: 'node scripts/bongos/gen-api-client.js --check' },
+  { key: 'copy-registry', label: 'docs/copy-registry.json fresh', argv: ['scripts/bongos/copy-inventory.js', '--check'], fix: 'node scripts/bongos/copy-inventory.js', optional: true },
+  { key: 'page-inventory', label: 'docs/page-inventory.json fresh (every page + its stable id)', argv: ['scripts/bongos/page-inventory.js', '--check'], fix: 'node scripts/bongos/page-inventory.js', optional: true },
+  // The page readings (task 1004315, ADR 0341 D3): files_hash only, no browser; the fix is the reader's own re-read.
+  { key: 'page-readings', label: 'docs/page-readings.json fresh (every page\'s reading matches its files)', argv: ['scripts/bongos/page-reader.js', '--check'], fix: 'node scripts/bongos/page-reader.js --stale', optional: true },
+  { key: 'linkify', label: 'no bare #NNN task refs in committed markdown', argv: ['scripts/bongos/linkify-refs.js', '--check'], fix: 'node scripts/bongos/linkify-refs.js', optional: true },
+  { key: 'skill-lint', label: 'SKILL.md frontmatter parses', argv: ['scripts/bongos/skill-lint.js'], fix: 'fix the ✗ lines (description: >- block scalars)' },
+  { key: 'render-fit', label: 'rendered text fit + sibling overlap on the pages this branch changed (advisory)', argv: ['scripts/bongos/render-check.js'], fix: 'look at the shots it names; fix the element, or say in the ship notes why it is right', advisory: true, optional: true, skipWith: '--no-render', slow: true },
+  { key: 'tests', label: 'DB-free unit lane (npm test)', argv: ['scripts/bongos/run-unit-tests.js'], fix: 'read the FAIL lines; compare against origin/main before calling any of them environmental', onlyWith: '--tests', slow: true },
+];
+
+function runStep(step, { cwd = REPO_ROOT } = {}) {
+  const script = path.join(cwd, step.argv[0]);
+  if (!fs.existsSync(script)) return { ...step, status: step.optional ? 'skipped' : 'missing', ms: 0, tail: `${step.argv[0]} not present` };
+  const t0 = Date.now();
+  const r = spawnSync(process.execPath, [script, ...step.argv.slice(1)], { cwd, encoding: 'utf8', timeout: step.slow ? 15 * 60 * 1000 : 5 * 60 * 1000, env: { ...process.env, GDS_QUIET: '1' } });
+  const out = ((r.stdout || '') + (r.stderr || '')).trim().split(/\r?\n/);
+  const failing = out.filter((l) => /^\s*(✗|FAIL|not ok|STALE|✘)/.test(l) || /STALE|is stale|would update|failed/i.test(l));
+  return { ...step, status: r.status === 0 ? 'ok' : !step.advisory ? 'fail' : r.status === 3 ? 'skipped' : 'warn', code: r.status, signal: r.signal, ms: Date.now() - t0, tail: (failing.length ? failing : out.slice(-4)).slice(0, 12).join('\n') };
+}
+
+function summarize(results) {
+  const stale = results.filter((r) => r.status === 'fail' || r.status === 'missing');
+  return { ok: stale.length === 0, stale: stale.map((r) => r.key), warned: results.filter((r) => r.status === 'warn').map((r) => r.key), results };
+}
+
+function format(summary) {
+  const lines = ['ship-check — what ship.js will trip on', ''];
+  for (const r of summary.results) {
+    const mark = r.status === 'ok' ? '✓' : r.status === 'skipped' ? '·' : r.status === 'warn' ? '!' : '✗';
+    lines.push(`${mark} ${r.label}  (${r.ms} ms)`);
+    if (r.status !== 'ok' && r.status !== 'skipped') {
+      for (const t of String(r.tail).split('\n')) lines.push(`    ${t}`);
+      lines.push(`    fix → ${r.fix}`);
+    }
+  }
+  lines.push('');
+  lines.push(summary.ok ? 'all fresh — ship.js preflight should pass; the grader and CI are the remaining gates.' : `${summary.stale.length} stale: ${summary.stale.join(', ')} — heal, commit, re-run.`);
+  if (summary.warned.length) lines.push(`advisory (a signal, never a gate): ${summary.warned.join(', ')}`);
+  return lines.join('\n');
+}
+
+function main() {
+  const argv = process.argv.slice(2);
+  const steps = STEPS.filter((s) => (!s.onlyWith || argv.includes(s.onlyWith)) && !(s.skipWith && argv.includes(s.skipWith)));
+  const results = steps.map((s) => runStep(s));
+  const summary = summarize(results);
+  console.log(argv.includes('--json') ? JSON.stringify(summary, null, 1) : format(summary));
+  process.exitCode = summary.ok ? 0 : 1;
+}
+
+module.exports = { STEPS, runStep, summarize, format };
+if (require.main === module) main();

package/scripts/bongos/ship-deploy-target.js

@@ -0,0 +1,393 @@
+// scripts/bongos/ship-deploy-target.js — deploy-mode + deploy-target resolution, the gh helpers and push-path selection.
+//
+// Carved out of scripts/bongos/ship.js by task 1003205 (goal 1000079, the R03
+// de-monolith plan) — a STRUCTURAL move, not a rewrite: the code below is the
+// original ship.js lines 639-989 unchanged. ship.js remains the facade that
+// re-exports every name and owns the CLI entry point, so the ship contract and
+// every flag are untouched, and the other scripts that import from it are too.
+
+'use strict';
+
+const { spawnSync } = require('node:child_process');
+const fs = require('node:fs');
+const path = require('node:path');
+const { loadSessionSync } = require('./cli-lib');
+// The two env overrides below resolve through the branded prefix — <PREFIX>_DEPLOY_MODE /
+// <PREFIX>_PUSH_VIA_SERVER (BONGOS_ on a vanilla instance) — with the legacy OTB_ spelling
+// still honoured and warned about (task 1001441, R61 follow-up).
+const { resolveEnv } = require('../../src/instance-config');
+const { argvOk, argvOut } = require('./ship-git.js');
+const { REPO_ROOT } = require('./ship-state.js');
+
+// ---------- CI deploy mode (#679, ADR 0042) ----------
+//
+// Two ways the confirmed→shipped land can run, chosen by a SINGLE committed
+// switch (config/deploy.json `mode`, env <PREFIX>_DEPLOY_MODE overrides):
+//
+//   '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 machine holds the prod key. ship pushes the branch, opens a
+//      PR, and enables GitHub auto-merge; once required checks pass, GitHub
+//      merges to main and .github/workflows/deploy-prod.yml deploys from
+//      Actions. ship then CONFIRMS the deploy landed (PR merged + the
+//      deploy-prod workflow run succeeded for the merge commit + public
+//      healthz 200) so the synchronous "deploy-confirmed" UX is preserved
+//      without the key. This is what lets a Windows/Chromebook builder with no
+//      main checkout and no droplet key land their own work.
+//
+// parseDeployMode is pure (env string + raw config file contents → mode) and
+// exported so the test can assert the precedence + the safe default without
+// touching fs/env. The default is 'laptop' precisely so this code is INERT
+// until the deliberate, atomic cutover (config flip + GitHub arming together).
+function parseDeployMode(envVal, configRaw) {
+  const fromEnv = String(envVal || '').trim().toLowerCase();
+  if (fromEnv === 'ci' || fromEnv === 'laptop') return fromEnv;
+  if (configRaw) {
+    try {
+      const m = String(JSON.parse(configRaw).mode || '').trim().toLowerCase();
+      if (m === 'ci' || m === 'laptop') return m;
+    } catch (_) {
+      /* malformed config → fall through to the safe default */
+    }
+  }
+  return 'laptop';
+}
+
+// effectiveDeployMode — credential- and protection-aware adjustment of the parsed
+// mode (pure; exported for the regression test). The 'laptop' land path pushes
+// main + SSHes the droplet FROM THIS MACHINE, so it requires a local GitHub push
+// credential. A machine without one — a fresh/stale local clone that can't
+// even `git pull` (token-less origin, ADR 0053) — physically cannot run it;
+// it must ship via the 'ci' server-mediated publish path instead
+// (pushVia()==='server', ADR 0055), which lets the GDS server push with its own
+// credential. So when the parsed mode is 'laptop' but the machine can't push
+// locally AND the mode was NOT pinned by an explicit <PREFIX>_DEPLOY_MODE, fall back to
+// 'ci' rather than strand every ship at merge. This is the scootermack 2026-06-22
+// case: a checkout left at the pre-cutover 'laptop' default that can't pull
+// forward to 'ci', so it kept attempting a push it had no credential for. An
+// explicit env override always wins (tests/staging may force 'laptop'). Mirrors
+// pushVia()'s existing credential-awareness — the asymmetry (pushVia smart,
+// resolveDeployMode blind) WAS the bug. (task 1449)
+//
+// Second input, same shape (task 1002629): a machine WITH push credentials but a
+// branch-PROTECTED main also cannot run the laptop land — GitHub refuses the
+// direct `git push origin main` no matter whose credential it is. When task
+// 1002619 armed protection (required `unit` check), every ship resolved 'laptop'
+// and pushed into the wall, stranding graded-PASS tasks at confirmed (tasks
+// 1002608/1002609; learning 1000177). mainProtected must be STRICTLY true to
+// trigger — null/undefined means the probe couldn't answer (no gh, offline, no
+// permission) and keeps today's behavior rather than rerouting on a guess.
+function effectiveDeployMode(mode, { canPushLocally, envForced, mainProtected } = {}) {
+  if (mode === 'laptop' && !envForced && !canPushLocally) return 'ci';
+  if (mode === 'laptop' && !envForced && mainProtected === true) return 'ci';
+  return mode;
+}
+
+// mainIsProtected — true/false when GitHub answers, null when it can't. The
+// `gh api` resolves {owner}/{repo} from the checkout's origin; any failure
+// (gh missing, offline, non-200) is null = unknown, which effectiveDeployMode
+// treats as "no change". Same spawn discipline as ghAvailableAndAuthed().
+function mainIsProtected() {
+  try {
+    const r = spawnSync('gh', ['api', 'repos/{owner}/{repo}/branches/main', '--jq', '.protected'], {
+      encoding: 'utf8',
+      shell: process.platform === 'win32',
+      windowsHide: true,
+      timeout: 15000,
+    });
+    if (!r || r.error || r.status !== 0) return null;
+    const out = String(r.stdout || '').trim();
+    if (out === 'true') return true;
+    if (out === 'false') return false;
+    return null;
+  } catch (_) {
+    return null;
+  }
+}
+
+function resolveDeployMode() {
+  const configRaw = readDeployConfigRaw();
+  const envMode = resolveEnv('DEPLOY_MODE');
+  const mode = parseDeployMode(envMode, configRaw);
+  const envForced = ['ci', 'laptop'].includes(
+    String(envMode || '').trim().toLowerCase()
+  );
+  // Probe `gh` ONLY when it can change the answer (resolved 'laptop', no env
+  // override) — the happy 'ci' path and an env-pinned mode spawn no extra gh,
+  // keeping the documented spawn discipline (the line-1019 note). The protection
+  // probe runs only when the credential check kept us on 'laptop' (a
+  // credential-less machine already falls back without it).
+  if (mode === 'laptop' && !envForced) {
+    const canPushLocally = ghAvailableAndAuthed();
+    const mainProtected = canPushLocally ? mainIsProtected() : null;
+    const effective = effectiveDeployMode(mode, { canPushLocally, envForced, mainProtected });
+    if (effective === 'ci' && mainProtected === true) {
+      console.log('  deploy mode: main is branch-protected (direct pushes refused) — landing via the ci PR path');
+    }
+    return effective;
+  }
+  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;
+  }
+}
+
+// readSessionApiBase — the signed-in session's persisted api_base (the instance the
+// CLI is actually pointed at), or null when not signed in / unreadable. This is the
+// session's OWN value only — deliberately NOT readSessionToken().apiBase, which
+// already folds in the env override + branding default; resolveInstanceBase orders
+// that precedence itself so it stays pure over its injected inputs.
+function readSessionApiBase() {
+  try {
+    const s = loadSessionSync();
+    return (s && typeof s.api_base === 'string' && s.api_base.trim()) ? s.api_base.trim() : null;
+  } catch (_) {
+    return null;
+  }
+}
+
+// resolveInstanceBase — the ORIGIN of the instance this ship is landing on, used by
+// the ci-land deployed-version probe (/version), the /healthz re-probe, the ci
+// PR-body deploy note, and the manual-confirm curl guidance. Precedence mirrors the
+// CLI's own base resolution: <PREFIX>_API_BASE env → the signed-in session's
+// api_base → branding publicOrigin → null (unknowable). There is NO hardcoded
+// founder host — 5 sites here baked in `https://example.com`, so a ci-land /
+// manual-confirm on a migrated instance pointed the builder at the WRONG box; the
+// ci-land/guidance sibling of resolveDeployTarget()'s laptop-mode fix (task 1002232
+// ⊃ task 1002202). Pure over its injected inputs (env / sessionApiBase / branding)
+// so the precedence is unit-tested without fs/env/network; the defaults read the
+// real session file + brand pack.
+function resolveInstanceBase({
+  env = process.env,
+  sessionApiBase = readSessionApiBase(),
+  branding = safeBranding(),
+} = {}) {
+  const ic = require('../../src/instance-config');
+  const trim = (s) => (typeof s === 'string' && s.trim() ? s.trim().replace(/\/+$/, '') : null);
+  const envBase = trim(ic.resolveEnv('API_BASE', { env }));
+  if (envBase) return envBase;
+  const sess = trim(sessionApiBase);
+  if (sess) return sess;
+  const origin = branding && branding.domains && branding.domains.publicOrigin;
+  return trim(origin);
+}
+
+// deployedVersionUrl — the instance's /version endpoint, or null when no instance
+// origin is resolvable (then fetchDeployedVersion is a no-op). Derived from
+// resolveInstanceBase — no hardcoded host (task 1002232).
+function deployedVersionUrl() {
+  const base = resolveInstanceBase();
+  return base ? `${base}/version` : 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 =
+// parse `gh ... --json` stdout to an object/array (null on any failure).
+function ghArgvOk(args, opts = {}) {
+  return argvOk('gh', args, opts);
+}
+
+function ghJson(args, opts = {}) {
+  const out = argvOut('gh', args, opts);
+  if (out == null) return null;
+  try { return JSON.parse(out); } catch (_) { return null; }
+}
+
+// Pure argv builders for the PR land path — exported + tested so the untrusted
+// value_summary is proven to ride as ONE literal argv element (never a shell
+// string), exactly like buildMergeArgv.
+function buildPrCreateArgv(branch, title, body) {
+  return ['pr', 'create', '--head', branch, '--base', 'main', '--title', title, '--body', body];
+}
+
+// --merge keeps the project's --no-ff merge-commit convention (architecture.md
+// branch-cleanup note); --auto arms GitHub to merge the instant required checks
+// pass + branch protection is satisfied; --delete-branch mirrors the laptop
+// path's origin-branch cleanup.
+function buildPrMergeArgv(branch) {
+  return ['pr', 'merge', '--auto', '--merge', '--delete-branch', branch];
+}
+
+// Pure: did the prod-deploy workflow finish successfully for the merge commit?
+// `runs` is the parsed `gh run list --json headSha,status,conclusion` array.
+function deployRunSucceeded(runs, mergeSha) {
+  if (!mergeSha) return false;
+  return (runs || []).some(
+    (r) => r && r.headSha === mergeSha && r.status === 'completed' && r.conclusion === 'success'
+  );
+}
+
+// Pure: does the prod /version endpoint (#858) report it's running the commit we
+// just merged? 'match' = commit-pinned confirmation; 'mismatch' = prod is on a
+// different commit (e.g. a later deploy already superseded ours — still fine, our
+// run succeeded); 'unknown' = /version absent or unparseable (older prod / blip)
+// → caller falls back to the deploy-run + healthz signal. Compares on the shorter
+// length so a short vs full sha still matches. Exported + tested.
+function deployedCommitStatus(versionBody, mergeSha) {
+  if (!versionBody || !mergeSha) return 'unknown';
+  const c = String(versionBody.commit || '');
+  if (!/^[0-9a-f]{7,40}$/i.test(c)) return 'unknown';
+  const n = Math.min(c.length, String(mergeSha).length);
+  return c.slice(0, n).toLowerCase() === String(mergeSha).slice(0, n).toLowerCase()
+    ? 'match'
+    : 'mismatch';
+}
+
+// Fetch + parse the prod /version JSON (#858). null on any failure — never throws.
+// Default target is the resolved instance origin (no hardcoded host — task 1002232);
+// null when none is resolvable, in which case the probe is skipped.
+function fetchDeployedVersion(url = deployedVersionUrl()) {
+  if (!url) return null; // no resolvable instance origin → nothing to probe
+  // stdio override DISCARDS stderr (a curl progress/error line must not pollute
+  // the JSON parse) — the documented per-caller difference from ghJson.
+  const out = argvOut('curl', ['-fsS', '--max-time', '10', url], { stdio: ['ignore', 'pipe', 'ignore'] });
+  if (out == null) return null;
+  try { return JSON.parse(out); } catch (_) { return null; }
+}
+
+// ciLand — the 'ci' deploy-mode analogue of the laptop merge+SSH block. Pushes
+// the branch, ensures a PR exists, enables auto-merge, then confirms the deploy
+// actually landed. Returns true ONLY when prod is confirmed live on the merge
+// commit — so the caller flips the task to shipped exactly as the laptop path
+// does. Any earlier exit leaves the task at confirmed with a clear next step.
+// pushVia — which publish path ship uses in 'ci' mode (ADR 0055 / task 1025):
+//   'local'  — this machine pushes the branch + opens the PR with git + gh
+//              (laptop: gh present + authenticated). Today's behaviour.
+//   'server' — this machine has NO GitHub push credential (no gh, a
+//              credential-less origin). ship uploads a thin branch bundle to the
+//              GDS, which pushes + opens the PR + auto-merges with the SERVER's
+//              credential. This machine holds nothing (#919 model preserved).
+// Override with <PREFIX>_PUSH_VIA_SERVER=1 (force server) / =0 (force local) for tests.
+function ghAvailableAndAuthed() {
+  try {
+    const a = spawnSync('gh', ['auth', 'status'], {
+      stdio: 'ignore',
+      shell: process.platform === 'win32',
+      windowsHide: true,
+      timeout: 15000,
+    });
+    return !!a && !a.error && a.status === 0;
+  } catch (_) {
+    return false;
+  }
+}
+
+function pushVia() {
+  const o = String(resolveEnv('PUSH_VIA_SERVER') || '').trim();
+  if (o === '1') return 'server';
+  if (o === '0') return 'local';
+  // No explicit override: a machine that can run an authenticated gh (laptop)
+  // takes the local path; everything else goes server-mediated.
+  return ghAvailableAndAuthed() ? 'local' : 'server';
+}
+
+// broadcastHandledByServer — task 1045: on the server-mediated publish path the
+// SERVER posts the Discord ship-broadcast after it confirms the deploy (it holds
+// the webhook secrets; the local machine does NOT — ADR 0053). So ship.js must NOT
+// also post locally there, or this machine would either double-post (impossible — no
+// secret) or, as before, fail silently. True only when the publish actually goes server-side:
+// ci deploy mode AND this machine has no GitHub push credential (pushVia 'server').
+// The laptop path (pushVia 'local') keeps posting locally, exactly as today. Pure
+// w.r.t. its inputs (env + committed deploy.json) + exported so the gate is tested.
+function broadcastHandledByServer() {
+  return resolveDeployMode() === 'ci' && pushVia() === 'server';
+}
+
+// shouldBailOnFetchFailure — autoMerge's decision when `git fetch origin main`
+// fails. A credential-less checkout (private origin, no creds —
+// ADR 0053) CANNOT fetch origin, and that is FINE for the server-mediated
+// publish path (ADR 0055): ciLandServer bundles against this machine's LOCAL
+// origin/main and the SERVER tops up main with its own credential. So a fetch
+// failure is fatal ONLY when we are NOT taking that path — otherwise such a
+// machine can never reach ciLand and strands every ship at confirmed (the bug task 1027
+// surfaced: ADR 0055 shipped the server path but left this fetch guard in front
+// of it). Pure + exported for the regression test (no git, no network).
+// NOTE: callers must still guard the pushVia() gh-probe behind `!fetchedMain` so
+// the happy path (fetch ok) spawns no extra gh and laptop behavior is unchanged.
+function shouldBailOnFetchFailure(fetchedMain, deployMode, via) {
+  if (fetchedMain) return false;
+  const serverPublish = deployMode === 'ci' && via === 'server';
+  return !serverPublish;
+}
+
+module.exports = {
+  broadcastHandledByServer,
+  buildPrCreateArgv,
+  buildPrMergeArgv,
+  deployRunSucceeded,
+  deployedCommitStatus,
+  effectiveDeployMode,
+  fetchDeployedVersion,
+  ghArgvOk,
+  ghJson,
+  mainIsProtected,
+  parseDeployMode,
+  pushVia,
+  readDeployConfigRaw,
+  resolveDeployMode,
+  resolveDeployTarget,
+  resolveInstanceBase,
+  safeBranding,
+  shouldBailOnFetchFailure,
+};

package/scripts/bongos/ship-escalation.js

@@ -0,0 +1,167 @@
+'use strict';
+//
+// scripts/bongos/ship-escalation.js — the exit for a no-artifact close (task 1003950)
+//
+// THE DEAD END THIS REPLACES. A task that is legitimately artifact-free — an ops
+// verification, a DB-only close, or one whose premise turned out to be already-done —
+// could not be closed by any builder below archon, and the two documented paths pointed
+// at each other:
+//
+//     ship.js NNNN --allow-empty   → implies --skip-grade → 403 task.confirm.grade_bypass
+//                                  → "re-run WITHOUT --skip-grade and use --regrade"
+//     ship.js NNNN --regrade       → "Nothing to grade: the committed diff is empty"
+//                                  → "if this task is DELIBERATELY artifact-free, use --allow-empty"
+//
+// Neither exit is reachable at metic. The task parks at `completed` with the claim
+// released — the strand shape the reconciler cannot heal (no branch, no diff, and
+// `completed` sits BEFORE the confirm gate the reconciler sweeps from). Reproduced live
+// 2026-09-16 on task 1003822.
+//
+// WHAT THIS DOES, AND DELIBERATELY DOES NOT DO. It does not move the gate. The owner
+// decision recorded on task 1003950 scoped this to the third of the three shapes the
+// bug offered — "give the refusal a working escalation that does not require the builder
+// to know an archon personally" — because `task.confirm.grade_bypass` is `system: true`
+// in modules/government/catalog.js, one of the four trust-boundary keys ADR 0157 names
+// in its escalation-chain argument. Lowering or forking it is a governance migration and
+// an ADR, filed as task 1004010; grading the NOTES instead of the diff is task 1004011.
+//
+// So the close stays archon-gated. What stops is the LOOP: the refusal now files the
+// escalation on the builder's behalf and terminates, instead of returning them to a flag
+// that will send them back here.
+//
+// IDEMPOTENT BY TASK, not by run — the same reasoning artifact-audit.js carries.
+// POST /blockers dedupes on (source, source_ref), so a builder who re-runs --allow-empty
+// three times while waiting gets ONE blocker, not three. A check that spams is a check
+// that gets muted, and this one is aimed at the surface a person actually reads.
+
+const NO_ARTIFACT_SOURCE = 'no-artifact-close';
+const { postWithAsk } = require('./ask.js');
+
+// One blocker per task. Deliberately NOT keyed on the builder or the run: two builders
+// hitting the same stuck task should land on the same blocker, not race to file two.
+function escalationSourceRef(taskId) {
+  return `${NO_ARTIFACT_SOURCE}:${taskId}`;
+}
+
+function escalationTitle(taskId, title) {
+  const t = String(title || '').slice(0, 90);
+  return `No-artifact close needs an archon: task ${taskId}${t ? ` — ${t}` : ''}`;
+}
+
+// Pure so the wording is unit-testable without git or network. The body has to carry
+// enough for the archon to make the call WITHOUT re-interviewing the builder — that is
+// the whole point of filing it rather than telling them to go find someone.
+function escalationBody({ taskId, title, floor, summary, notes, builder }) {
+  const reason = [summary, notes].filter(Boolean).join('\n\n');
+  const lines = [
+    `Task **${taskId}** is claimed to be legitimately artifact-free and cannot be closed by its builder.`,
+    '',
+    `- **Task:** ${title || '(untitled)'}`,
+    `- **Declared by:** ${builder || 'the claim holder'} (ran \`ship.js ${taskId} --allow-empty\`)`,
+    `- **Blocked on:** \`task.confirm.grade_bypass\`${floor ? ` (floor: ${floor})` : ''}`,
+    '',
+    '### Why it is stuck',
+    '',
+    'The committed diff is empty and the working tree is clean, so the subagent grader has',
+    'nothing to read. Confirming without a passing grade is archon-gated, and the builder',
+    'holds no route past it. Left alone the task parks at `completed` with the claim',
+    'released — the strand shape the publish reconciler cannot heal, because `completed`',
+    'sits before the `confirmed` gate it sweeps from.',
+    '',
+    '### The reason the builder gave',
+    '',
+    reason || '_(none given — the ship carried no --summary or --notes)_',
+    '',
+    '### What is being asked of you',
+    '',
+    'Decide whether this task is genuinely artifact-free. That claim is the thing worth',
+    'checking here; the absent diff is not evidence either way.',
+    '',
+    `- If yes: \`POST /api/bongos/tasks/${taskId}/confirm\`, or run \`node scripts/bongos/ship.js ${taskId} --allow-empty\` yourself.`,
+    '- If no: the work was never done, or never committed — release the claim back to `ready` and say so here.',
+    '',
+    'Filed automatically by the ship path (task 1003950). Re-running `--allow-empty` will',
+    'not file a second copy.',
+  ];
+  return lines.join('\n');
+}
+
+// The card the archon answers (task 1004704): the escalation as an ask, so the
+// review queue shows one short question instead of the body above. The body
+// still carries everything; the card is what a person answers at a glance.
+function escalationAsk(taskId) {
+  return {
+    question: `Close task ${taskId} with no code to grade?`,
+    options: [
+      { key: 'close', label: 'Close it', result: 'It closes as done, without a grade.', act: 'go ahead' },
+      { key: 'return', label: 'Send it back', result: 'The claim is released and the task returns to ready.', act: 'need more' },
+    ],
+    recommend: { key: 'close', why: 'The builder says no code was needed; read their reason first.' },
+    waits_on: 'lead:release',
+    if_nobody_answers: 'The task stays at completed and its builder is not paid.',
+  };
+}
+
+// The terminating refusal. THE ONE INVARIANT: these lines must never send the builder to
+// --regrade, because --regrade on an empty diff sends them straight back to --allow-empty.
+// That mutual advice IS the bug (task 1003950). Pure + exported so a test can assert the
+// loop stays closed rather than trusting a reviewer to notice it reopening.
+function noArtifactRefusalLines({ taskId, floor, escalation }) {
+  const lines = [
+    '',
+    'This task has no artifact to grade, and confirming without a passing grade is',
+    `permission-gated: task.confirm.grade_bypass${floor ? ` (floor: ${floor})` : ''}.`,
+    'This is an authorization wall, not a verdict on your work.',
+    '',
+  ];
+  if (escalation && escalation.filed) {
+    lines.push(`Escalated for you: blocker ${escalation.id} is now on the archon review queue,`);
+    lines.push('carrying this task, the reason you gave, and what is being asked. You do not');
+    lines.push('need to know an archon personally, and there is nothing further to re-run.');
+  } else if (escalation && escalation.reason === 'already-filed') {
+    lines.push('Already escalated: a blocker for this task is open on the archon review queue.');
+    lines.push('Re-running will not speed it up. Nothing further to do here.');
+  } else {
+    // Fail-open: the close is still blocked, so the builder must not be told it worked.
+    const why = escalation && escalation.reason ? ` (${escalation.reason})` : '';
+    lines.push(`Could not file the escalation automatically${why}.`);
+    lines.push('File it by hand so this does not sit silently — post a blocker naming this task,');
+    lines.push('with an ask (check the card first: node scripts/bongos/ask.js check <file>):');
+    lines.push('    node scripts/bongos/api.js POST /blockers --body-file <path-to-json>');
+  }
+  lines.push('');
+  lines.push(`Your claim on task ${taskId} is unchanged. Do NOT re-run with --regrade:`);
+  lines.push('the diff is empty, so a re-grade has nothing to read and will point you back here.');
+  return lines;
+}
+
+// Best-effort by design: a failure to file must not turn a blocked close into a crash,
+// but it must also never read as success — noArtifactRefusalLines prints the manual
+// fallback when `filed` is false.
+async function fileNoArtifactEscalation({ taskId, title, floor, summary, notes, builder }, { call } = {}) {
+  const post = call || require('./cli-lib').apiCall;
+  let r;
+  try {
+    r = await postWithAsk((body) => post('POST', '/api/bongos/blockers', body), {
+      title: escalationTitle(taskId, title),
+      body_md: escalationBody({ taskId, title, floor, summary, notes, builder }),
+      source: NO_ARTIFACT_SOURCE,
+      source_ref: escalationSourceRef(taskId),
+    }, escalationAsk(taskId));
+  } catch (err) {
+    return { filed: false, reason: `POST /blockers threw: ${err && err.message}` };
+  }
+  if (!r || !r.ok) return { filed: false, reason: `POST /blockers -> ${r && r.status}` };
+  if (r.data && r.data.skipped) return { filed: false, reason: 'already-filed' };
+  return { filed: true, id: r.data && r.data.blocker && r.data.blocker.id };
+}
+
+module.exports = {
+  NO_ARTIFACT_SOURCE,
+  escalationSourceRef,
+  escalationTitle,
+  escalationBody,
+  escalationAsk,
+  noArtifactRefusalLines,
+  fileNoArtifactEscalation,
+};