@bongos/core 1.19.1032 → 1.19.1034

package/scripts/gds/address-park-sweep.sh

@@ -31,7 +31,9 @@ DB="${PGDATABASE:-cloudbongos}"
 CORE_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"
 case "$CORE_DIR" in */node_modules/@bongos/core) INSTANCE_DIR="${INSTANCE_DIR:-${CORE_DIR%/node_modules/@bongos/core}}" ;; esac
 [ -n "${INSTANCE_DIR:-}" ] || { echo "set INSTANCE_DIR to the control plane's instance checkout — this sweep is not running from one"; exit 1; }
-APP_USER="${PROVISION_APP_USER:-$(stat -c %U "$INSTANCE_DIR" 2>/dev/null)}"
+# Owner by name: GNU stat spells it `-c %U`, BSD/macOS stat `-f %Su`, and each refuses the
+# other's flag, so GNU is asked first and BSD answers when it refuses (task 1004170).
+APP_USER="${PROVISION_APP_USER:-$(stat -c %U "$INSTANCE_DIR" 2>/dev/null || stat -f %Su "$INSTANCE_DIR" 2>/dev/null)}"
 if [ "$APP_USER" = root ] || ! [[ "$APP_USER" =~ ^[a-z_][a-z0-9_-]{0,31}$ ]]; then
   echo "cannot use '$APP_USER' as the app account — set PROVISION_APP_USER to the unprivileged account that owns $INSTANCE_DIR"; exit 1
 fi

package/scripts/gds/autobongos-run.js

@@ -49,6 +49,7 @@ const fence = require('../../modules/autonomy/fence.js');
 // where it would not be inside modules/ — which is exactly why fence.js takes the
 // hits as an argument instead of matching them itself.
 const { matchProtected } = require('../../src/bongos/permission-path-check');
+const { resolveEnv, envPrefix, LEGACY_ENV_PREFIXES } = require('../../src/instance-config');
 const cadence = require('../../modules/autonomy/cadence.js');
 
 const REPO_ROOT = path.resolve(__dirname, '..', '..');
@@ -94,6 +95,56 @@ function logPath() {
   try { return require('../../src/instance-config.js').configPath('autobongos-runs.jsonl'); }
   catch (_) { return path.join(REPO_ROOT, 'autobongos-runs.jsonl'); }
 }
+// countWorkedSince — how many tasks this runner has worked since an epoch-second
+// mark. Reads the run log, because that is the only record that survives a
+// restart, and the cap it feeds has to hold across one (a runner that forgets
+// its count on every crash has no cap at all).
+//
+// BOUNDED ON BOTH AXES, because this runs every iteration of a loop that never
+// exits and the log only grows. It reads the TAIL rather than the file, and it
+// scans BACKWARDS and stops at the first row older than the mark — the rows that
+// can possibly count are the newest ones, so the common case touches a handful
+// of lines whatever the log's size.
+//
+// A torn or missing log counts as zero rather than refusing: the fence and the
+// gauge are the gates, this is a bound on top of them, and a bound that bricks
+// the runner when its own log is unreadable is worse than one that occasionally
+// allows an extra task.
+const WORKED_SCAN_TAIL_BYTES = 1024 * 1024;
+const NEWLINE = String.fromCharCode(10);
+
+function countWorkedSince(sinceEpochS) {
+  if (!Number.isFinite(sinceEpochS) || sinceEpochS <= 0) return 0;
+  let text;
+  try {
+    const p = logPath();
+    const { size } = fs.statSync(p);
+    const from = Math.max(0, size - WORKED_SCAN_TAIL_BYTES);
+    const fd = fs.openSync(p, 'r');
+    try {
+      const buf = Buffer.alloc(Math.min(size, WORKED_SCAN_TAIL_BYTES));
+      fs.readSync(fd, buf, 0, buf.length, from);
+      text = buf.toString('utf8');
+    } finally { fs.closeSync(fd); }
+    // A tail read can land mid-line; drop the first partial one.
+    if (from > 0) text = text.slice(text.indexOf(NEWLINE) + 1);
+  } catch (_) { return 0; }
+
+  const lines = text.split(NEWLINE);
+  let n = 0;
+  for (let i = lines.length - 1; i >= 0; i--) {
+    const line = lines[i];
+    if (!line.trim()) continue;
+    let row;
+    try { row = JSON.parse(line); } catch (_) { continue; }   // a torn line costs one row, not the count
+    const at = Date.parse(row.at);
+    if (!Number.isFinite(at)) continue;
+    if (at / 1000 < sinceEpochS) break;   // the log is append-ordered: nothing older can count
+    if (row.event === 'worked') n += 1;
+  }
+  return n;
+}
+
 function record(entry) {
   const row = { at: new Date().toISOString(), ...entry };
   try {
@@ -156,11 +207,18 @@ async function pickTask(goals, deps = {}) {
 // own required vars), to reach the instance (BONGOS_API_BASE), and to be told it
 // is a subagent. It does NOT need a git push credential — the road to main is the
 // server-mediated pipeline (ADR 0307 §6) — so none is passed.
+function claudeBinEnvNames() {
+  return [...new Set([envPrefix(), ...LEGACY_ENV_PREFIXES].map((p) => `${p}_CLAUDE_BIN`)), 'CLAUDE_BIN'];
+}
+
 const WORKER_ENV_ALLOW = [
   'PATH', 'HOME', 'SHELL', 'LANG', 'LC_ALL', 'TZ', 'TMPDIR', 'USER', 'LOGNAME',
   'SystemRoot', 'windir', 'COMSPEC', 'PATHEXT', 'USERPROFILE', 'APPDATA', 'LOCALAPPDATA', 'TEMP', 'TMP',
   'BONGOS_API_BASE', 'CLOUDBONGOS_API_BASE',
-  'OTB_CLAUDE_BIN', 'CLAUDE_BIN',
+  // Every spelling resolveWorkerBin below can read (task 1001441): the branded
+  // <PREFIX>_CLAUDE_BIN, the legacy ones, and the unprefixed CLAUDE_BIN. A name
+  // missing here would be set on the host and silently absent in the worker.
+  ...claudeBinEnvNames(),
   'XDG_CONFIG_HOME',
   // THE WORKER'S OWN CREDENTIAL, and it has to be here (task 1003907, found by
   // running it). On a desktop, the claude CLI authenticates from the credential
@@ -207,7 +265,7 @@ const MAX_WORKER_OUTPUT = 8 * 1024 * 1024;   // a misbehaving worker must not gr
 // laid-out install should still run, and a corrupted schema surfaces as a failed
 // worker rather than as a refusal to start at all.
 function resolveWorkerBin(env = process.env, platform = process.platform) {
-  const override = env.OTB_CLAUDE_BIN || env.CLAUDE_BIN;
+  const override = resolveEnv('CLAUDE_BIN', { env }) || env.CLAUDE_BIN;
   if (override) return { bin: override, shell: platform === 'win32' && /\.(cmd|bat)$/i.test(override) };
   if (platform !== 'win32') return { bin: 'claude', shell: false };
   for (const dir of String(env.PATH || env.Path || '').split(path.delimiter)) {
@@ -342,6 +400,36 @@ async function iteration(opts, deps = {}) {
     return log({ event: 'hold', go: false, unknown: !!g.decision.unknown, reason: g.decision.reason, sleep_until: g.decision.sleepUntil ?? null });
   }
 
+  // 1b. A DERIVED gauge buys a BOUNDED amount of work (task 1004178).
+  //
+  // `derived` means the last real reading's window had already reset, so the
+  // baseline is a retired observation rather than a measurement. That is sound
+  // for the FIVE-hour window, which turns over during a night. It does nothing
+  // for the SEVEN-day one, which does not — so the weekly pace check, the thing
+  // the module's notes call what actually binds a heavy week, is simply absent
+  // on a derived reading. A stale weekly figure cannot substitute: usage only
+  // grows, so an under-reported value makes the check more permissive, and that
+  // is the wrong direction to be wrong in.
+  //
+  // So the bound is a task count, not a percentage: on one derived window, do
+  // AUTOBONGOS_DERIVED_TASK_CAP tasks and then hold until a real reading exists.
+  // A terminal session writes one; the owner opening a terminal in the morning
+  // is what lifts it. Default 2 — each worker is wall-clock bounded at 90
+  // minutes, so two of them is well inside a five-hour window even at worst, and
+  // the cap only has to be small enough that being wrong is survivable.
+  if (g.decision.derived) {
+    const cap = Number(process.env.AUTOBONGOS_DERIVED_TASK_CAP ?? 2);
+    const since = Number(g.decision.derivedSince) || 0;
+    const done = countWorkedSince(since);
+    if (Number.isFinite(cap) && cap >= 0 && done >= cap) {
+      return log({
+        event: 'hold', go: false, unknown: false, derived: true, worked_since_derived: done,
+        reason: `derived gauge: ${done} task(s) already done since the window reset and the cap is ${cap} — holding for a real reading (a terminal session writes one)`,
+        sleep_until: null,
+      });
+    }
+  }
+
   // 2. Pick — from the ALLOWLISTED goals, never from what the command line asked
   // for. gate.goals is already the intersection.
   const picked = await pick(gate.goals, deps.pickDeps || {});
@@ -798,7 +886,7 @@ if (require.main === module) {
 
 module.exports = {
   readArgv, pickTask, iteration, record, logPath, spawnWorker, workerEnv, WORKER_ENV_ALLOW, resolveWorkerBin,
-  worktreeName, readFence, reconcileLeftoverClaims, pollSignals, waitOrJump, forever, CLAIM_PREFIX,
+  worktreeName, readFence, reconcileLeftoverClaims, pollSignals, waitOrJump, forever, CLAIM_PREFIX, countWorkedSince,
   heartbeatPath, writeHeartbeat, readHeartbeat, pidAlive, anotherRunnerIsAlive, HEARTBEAT_STALE_MS,
   isRunnerTree, RUNNER_TREE_RE, postHeartbeat, RUNNER_STARTED_AT,
 };

package/scripts/gds/backfill-cost.js

@@ -12,23 +12,28 @@
 //
 // If no path is given, the script searches for the ledger in the
 // expected locations (current art/iterations/, sibling worktrees, or
-// $OTB_COST_LEDGER env var).
+// $<PREFIX>_COST_LEDGER env var — BONGOS_COST_LEDGER on a vanilla instance, the
+// legacy OTB_COST_LEDGER still read).
 
 const fs = require('node:fs');
 const path = require('node:path');
 const { cliClient, requireSession, fmtUsd } = require('./cli-lib');
+const { resolveEnv, envPrefix } = require('../../src/instance-config');
 // Cost-attribution audit carved into modules/economy/cost-classify.js (BV1.R77 /
 // ADR 0093 §1-2). A CLI may require a module directly (the memory/grading-carve
 // precedent — grade-smoke.js requires modules/grading/grader).
 const { auditCostAttribution, formatAuditReport } = require('../../modules/economy/cost-classify');
 
-const KNOWN_LEDGER_PATHS = [
-  process.env.OTB_COST_LEDGER,
+// The places a ledger is looked for, env override first. A function so the test can
+// hand it an env; resolved once below for the CLI.
+const knownLedgerPaths = (env = process.env) => [
+  resolveEnv('COST_LEDGER', { env }),
   path.resolve(__dirname, '../../art/iterations/cost_ledger.jsonl'),
   // Two historical absolute-path fallbacks (under the old Desktop folder name)
   // were dropped after the project-folder rename. Pass the ledger path as a CLI
-  // arg or set OTB_COST_LEDGER to point at any non-default location.
+  // arg or set <PREFIX>_COST_LEDGER to point at any non-default location.
 ];
+const KNOWN_LEDGER_PATHS = knownLedgerPaths();
 
 function findLedger(argPath) {
   const candidates = argPath ? [argPath, ...KNOWN_LEDGER_PATHS] : KNOWN_LEDGER_PATHS;
@@ -106,7 +111,7 @@ async function main() {
 
   const ledgerPath = findLedger(argPath);
   if (!ledgerPath) {
-    console.error('No cost_ledger.jsonl found. Pass a path or set OTB_COST_LEDGER.');
+    console.error(`No cost_ledger.jsonl found. Pass a path or set ${envPrefix()}_COST_LEDGER.`);
     console.error('Searched:');
     for (const p of KNOWN_LEDGER_PATHS) if (p) console.error(`  - ${p}`);
     process.exit(2);
@@ -159,7 +164,13 @@ async function main() {
   process.exit(failed > 0 ? 1 : 0);
 }
 
-main().catch((err) => {
-  console.error('backfill-cost.js failed:', err);
-  process.exit(1);
-});
+// Run only when invoked directly: requiring this file (the test does, for
+// knownLedgerPaths) must never start a backfill.
+if (require.main === module) {
+  main().catch((err) => {
+    console.error('backfill-cost.js failed:', err);
+    process.exit(1);
+  });
+}
+
+module.exports = { knownLedgerPaths };

package/scripts/gds/baseline-staleness.js

@@ -40,7 +40,7 @@
 //     anybody's diff. Hard-failing a PR because ambient debt turned eight weeks old
 //     punishes whoever pushed next and gets the gate disabled. The audit asked for
 //     "the repeatable, SCHEDULED version" of its own manual review, and the patrol
-//     is that: history-wide, time-based, filed for adjudication (ADR 0162).
+//     is that: history-wide, time-based, filed for adjudication (ADR 0158 §2).
 //
 // AGE COMES FROM GIT, NOT FROM A STORED TIMESTAMP. A `since:` field in the JSON
 // would be faster and hermetic, and it would also be the thing that silently

package/scripts/gds/claim.js

@@ -225,8 +225,8 @@ function captureHeadSha() {
 // origin/main. The completion cards + skills are CLI-script features that ride
 // the LOCAL checkout, not the deployed server — a worktree branched from a stale
 // main silently lacks them (the root cause behind the missing cards in session
-// 1c1e12d7: claimed/shipped task 1274 on old scripts). Mirrors ship.js's
-// TOOLING_PATHS preflight, but as a NUDGE — claiming on old scripts is fine, you
+// 1c1e12d7: claimed/shipped task 1274 on old scripts). Mirrors the ship's
+// TOOLING_PATHSPECS preflight (ship-preflight-steps.js), but as a NUDGE — claiming on old scripts is fine, you
 // just miss features. Strictly best-effort + fail-open (never break/slow a claim).
 const STALE_TOOLING_DIRS = ['scripts/gds', 'src/bongos', '.claude/skills'];
 function warnIfToolingStale() {

package/scripts/gds/credential-presence.js

@@ -0,0 +1,281 @@
+#!/usr/bin/env node
+// scripts/gds/credential-presence.js — which credentials does this HOST hold? Names and
+// presence only, never a value (task 1002880, from idea 1000630).
+//
+// Run ON THE HOST, as the user that can read the instance's env files (usually via sudo):
+//   node scripts/gds/credential-presence.js                 # reads /etc/<configDir>/*.env
+//   node scripts/gds/credential-presence.js --etc /etc/example --json
+//
+// WHY. The owner was asked to create GitHub credentials at least three times, and each
+// time the credential already existed — nothing could answer "what does this instance
+// need, what is set, what is missing". docs/credentials.md is the written half (what each
+// credential is for, where it lives, who may hold it); this is the one-command half, run
+// where the values actually live. doctor.js cannot do it: it runs on a builder's laptop,
+// which never sees the host's env files, and that is by design.
+//
+// THE ONE RULE: A VALUE NEVER LEAVES THE FILE. The report says set / empty / missing and
+// the NAME of the variable that satisfied each row — never the value, never a prefix,
+// never a length. tests/credential_presence.mjs asserts no fragment of any value reaches
+// the output. If this is ever surfaced over HTTP it must be Archon-gated, and it still
+// returns names only.
+//
+// Deeper than presence: `node scripts/gds/publish-credential-check.js` (task 1002733)
+// probes whether the publish credential can actually read the Actions API. This file
+// does not call GitHub — presence is the question it answers, offline.
+//
+// Exit: 0 = every REQUIRED row is satisfied · 1 = a required row is missing ·
+// 2 = an env file this host should have could not be read (the answer is unknown).
+
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { resolveEnv, envPrefix, configDirName, configPath, LEGACY_ENV_PREFIXES } = require('../../src/instance-config');
+const { arg, hasFlag, cliExit } = require('./cli-lib');
+
+// ---- the inventory -------------------------------------------------------------------
+//
+// One row per credential this instance's HOST may hold. `names` are the env var(s) that
+// must ALL be non-empty for the row to count as set; `prefixed` names resolve through the
+// instance's own env prefix (and its legacy spellings) the way the server reads them.
+// Rows sharing a `group` are alternatives: the group is satisfied when any member is.
+// `file` is the env file the value lives in on a control-plane host:
+//   web.env    — the web tier (the cloudbongos.service EnvironmentFile)
+//   box.env    — the control-plane runners; deliberately unreadable by the web tier
+//                (InaccessiblePaths=, task 1004176 / ADR 0327 §5)
+//   spaces.env — the offsite-backup timer
+// `need`: required (the instance is broken without it) · recommended (a named feature
+// is off without it) · optional.
+//
+// Every name here is documented in docs/credentials.md; the test fails if either side
+// gains a name the other lacks. Non-host credentials (GitHub Actions secrets, a
+// builder's own machine) are in the doc only — no host sweep can see them.
+const CREDENTIALS = [
+  {
+    id: 'github-sign-in', group: 'sign-in', file: 'web.env', need: 'required',
+    names: ['GITHUB_CLIENT_ID', 'GITHUB_CLIENT_SECRET'], prefixed: true,
+    purpose: 'GitHub OAuth app that signs builders in (src/bongos/auth-config.js)',
+  },
+  {
+    id: 'hub-federation', group: 'sign-in', file: 'web.env', need: 'required',
+    names: ['HUB_ORIGIN', 'HUB_CLIENT_ID', 'HUB_CLIENT_SECRET', 'HUB_PUBLIC_KEY'], prefixed: true,
+    purpose: 'sign-in federated through the Cloud Bongos hub instead of an own GitHub app (ADR 0141 §4)',
+  },
+  {
+    id: 'publish-app', group: 'publish', file: 'web.env', need: 'required',
+    names: ['GITHUB_APP_ID', 'GITHUB_APP_PRIVATE_KEY'],
+    purpose: 'GitHub App the server publishes builder branches and PRs with (modules/lifecycle/github-push.js); preferred',
+  },
+  {
+    id: 'publish-pat', group: 'publish', file: 'web.env', need: 'required',
+    names: ['GITHUB_PUSH_TOKEN'],
+    purpose: 'fine-grained PAT fallback for the same publish path, kept for cutover',
+  },
+  {
+    id: 'repo-pin', file: 'web.env', need: 'required',
+    names: ['GITHUB_OWNER', 'GITHUB_REPO'], prefixed: true, notSecret: true,
+    purpose: "which GitHub repo this instance is — mandatory where the core runs from node_modules, which has no git remote to read (src/bongos/repo-info.js)",
+  },
+  {
+    id: 'secret-box-key', file: 'web.env', need: 'required',
+    names: ['BUILDER_SECRET_KEY'], keyFile: 'builder-secret.key',
+    purpose: "master key encrypting builders' stored AI keys and GitHub tokens (src/bongos/secret-box.js); the key file in the service user's config dir also counts",
+  },
+  {
+    id: 'database-password', file: 'web.env', need: 'optional',
+    names: ['PGPASSWORD'],
+    purpose: "the instance's own Postgres role (src/bongos/pool.js); absent means local peer auth",
+  },
+  {
+    id: 'database-url', file: 'web.env', need: 'optional',
+    names: ['DATABASE_URL'],
+    purpose: 'a full Postgres connection string, when the database is not local',
+  },
+  {
+    id: 'discord-bot', file: 'web.env', need: 'recommended',
+    names: ['DISCORD_BOT_TOKEN'],
+    purpose: 'the Discord bot (modules/discord); also readable from discord-bot.json in the config dir',
+  },
+  {
+    id: 'discord-oauth', file: 'web.env', need: 'optional',
+    names: ['DISCORD_CLIENT_ID', 'DISCORD_CLIENT_SECRET'],
+    purpose: 'linking a Discord account at sign-in (src/bongos/auth-discord.js)',
+  },
+  {
+    id: 'discord-ship-news', file: 'web.env', need: 'optional',
+    names: ['DISCORD_SHIP_NEWS_WEBHOOK'],
+    purpose: '#ship-news posts (scripts/discord/lib.js); discord-webhooks.json in the config dir also works',
+  },
+  {
+    id: 'prelaunch-password', file: 'web.env', need: 'optional',
+    names: ['PRELAUNCH_PASSWORD'], legacyNames: ['STEALTH_PASSWORD'],
+    purpose: 'the pre-launch site password (src/bongos/prelaunch-gate.js); STEALTH_PASSWORD is the deprecated alias',
+  },
+  {
+    id: 'metrics-token', file: 'web.env', need: 'optional',
+    names: ['METRICS_TOKEN'],
+    purpose: 'bearer token for a remote Prometheus scrape of /metrics (src/bongos/metrics.js)',
+  },
+  {
+    id: 'hub-signing-key', file: 'web.env', need: 'optional',
+    names: ['HUB_SIGNING_KEY'], prefixed: true,
+    purpose: 'the HUB only: signs the assertions federated instances verify (modules/platform-identity/hub-keys.js)',
+  },
+  {
+    id: 'digitalocean', file: 'box.env', need: 'recommended',
+    names: ['DO_API_TOKEN'],
+    purpose: 'creates and destroys project servers (scripts/gds/do-api.js, provisioning); control plane only',
+  },
+  {
+    id: 'cloudflare', file: 'box.env', need: 'recommended',
+    names: ['CLOUDFLARE_API_TOKEN'],
+    purpose: 'DNS records for project addresses (scripts/gds/provision-net.js); control plane only',
+  },
+  {
+    id: 'offsite-backup', file: 'spaces.env', need: 'optional',
+    names: ['SPACES_KEY', 'SPACES_SECRET', 'SPACES_BUCKET'],
+    // The same file also carries the region, the endpoint and the age RECIPIENT the dumps
+    // are encrypted to. None is a secret (a recipient is a public key), so none is swept.
+    purpose: 'the weekly offsite copy of the database dumps (scripts/gds/db-backup-offsite.sh)',
+  },
+];
+
+const ENV_FILES = ['web.env', 'box.env', 'spaces.env'];
+
+// ---- pure core ------------------------------------------------------------------------
+
+// parseEnvFile(text) → { NAME: value } for a systemd EnvironmentFile: KEY=VALUE lines,
+// `#` comments, blank lines, optional surrounding quotes. Values are held only long enough
+// to test for emptiness; nothing returned by the report functions below contains one.
+function parseEnvFile(text) {
+  const out = {};
+  for (const raw of String(text || '').split(/\r?\n/)) {
+    const line = raw.trim();
+    if (!line || line.startsWith('#')) continue;
+    const eq = line.indexOf('=');
+    if (eq <= 0) continue;
+    const key = line.slice(0, eq).trim().replace(/^export\s+/, '');
+    let value = line.slice(eq + 1).trim();
+    if (value.length >= 2 && (value[0] === '"' || value[0] === "'") && value[value.length - 1] === value[0]) {
+      value = value.slice(1, -1);
+    }
+    if (/^[A-Za-z_][A-Za-z0-9_]*$/.test(key)) out[key] = value;
+  }
+  return out;
+}
+
+// Every spelling a name answers to, in the order the server tries them.
+function spellingsOf(name, row, prefix) {
+  if (row.prefixed) return [...new Set([prefix, ...LEGACY_ENV_PREFIXES])].map((p) => `${p}_${name}`);
+  return [name, ...(row.legacyNames || [])];
+}
+
+// checkRow(row, env, { prefix, keyFileExists }) → { state, satisfiedBy, missing }
+// state: 'set' | 'empty' | 'missing'. satisfiedBy / missing are variable NAMES.
+function checkRow(row, env, { prefix = envPrefix(), keyFileExists = false } = {}) {
+  const satisfiedBy = [];
+  const missing = [];
+  let anyEmpty = false;
+  for (const name of row.names) {
+    const spellings = spellingsOf(name, row, prefix);
+    const value = row.prefixed ? resolveEnv(name, { env, prefix, warn: () => {} }) : spellings.map((s) => env[s]).find((v) => v);
+    if (value) {
+      satisfiedBy.push(spellings.find((s) => env[s] === value) || spellings[0]);
+    } else {
+      if (spellings.some((s) => s in env)) anyEmpty = true;
+      missing.push(spellings[0]);
+    }
+  }
+  if (missing.length && row.keyFile && keyFileExists) {
+    return { state: 'set', satisfiedBy: [`${row.keyFile} (key file)`], missing: [] };
+  }
+  const state = missing.length === 0 ? 'set' : anyEmpty ? 'empty' : 'missing';
+  return { state, satisfiedBy, missing };
+}
+
+// sweep({ files, prefix, keyFileExists }) → { rows, groups, unreadable, ok }
+// files: { 'web.env': { env } | { error } } — the parsed files, or why one could not be read.
+function sweep({ files, prefix = envPrefix(), keyFileExists = false, credentials = CREDENTIALS }) {
+  const unreadable = Object.entries(files).filter(([, f]) => f.error).map(([name, f]) => ({ file: name, error: f.error }));
+  const rows = credentials.map((row) => {
+    const f = files[row.file];
+    if (!f || f.error) return { ...pick(row), state: 'unknown', satisfiedBy: [], missing: [] };
+    return { ...pick(row), ...checkRow(row, f.env, { prefix, keyFileExists }) };
+  });
+  // A group is satisfied when any member is; its members are not individually required.
+  const groups = {};
+  for (const r of rows) {
+    if (!r.group) continue;
+    groups[r.group] = groups[r.group] || { satisfied: false, unknown: false, members: [] };
+    groups[r.group].members.push(r.id);
+    if (r.state === 'set') groups[r.group].satisfied = true;
+    if (r.state === 'unknown') groups[r.group].unknown = true;
+  }
+  const requiredMissing = rows.filter((r) => r.need === 'required' && r.state !== 'set' && r.state !== 'unknown'
+    && !(r.group && groups[r.group].satisfied));
+  const ok = requiredMissing.length === 0 && unreadable.length === 0;
+  return { rows, groups, unreadable, requiredMissing: requiredMissing.map((r) => r.id), ok };
+}
+
+function pick(row) {
+  return { id: row.id, file: row.file, need: row.need, group: row.group || null, purpose: row.purpose, notSecret: !!row.notSecret };
+}
+
+// format(result) → the human report. Built only from ids, names, states and the fixed
+// purpose text — never from a parsed value.
+function format(result, { etc } = {}) {
+  const mark = { set: '✓', empty: '!', missing: '✗', unknown: '?' };
+  const lines = [`Credential presence — names only, never values (${etc || 'env files'})`, ''];
+  for (const file of ENV_FILES) {
+    const rows = result.rows.filter((r) => r.file === file);
+    if (!rows.length) continue;
+    const bad = result.unreadable.find((u) => u.file === file);
+    lines.push(`  ${file}${bad ? `  — could not read: ${bad.error}` : ''}`);
+    for (const r of rows) {
+      const grp = r.group ? result.groups[r.group] : null;
+      const covered = grp && grp.satisfied && r.state !== 'set' ? ` (not needed: another ${r.group} option is set)` : '';
+      const detail = r.state === 'set' ? `via ${r.satisfiedBy.join(', ')}`
+        : r.state === 'unknown' ? 'file unreadable'
+        : `${r.state === 'empty' ? 'set but EMPTY' : 'not set'}: ${r.missing.join(', ')}`;
+      lines.push(`    ${mark[r.state]} ${r.id.padEnd(20)} ${r.need.padEnd(11)} ${detail}${covered}`);
+    }
+    lines.push('');
+  }
+  if (result.requiredMissing.length) lines.push(`REQUIRED and missing: ${result.requiredMissing.join(', ')} — see docs/credentials.md for what each is and where it comes from.`);
+  if (result.unreadable.length) lines.push('Some env files could not be read, so this answer is incomplete — rerun as a user that can read them (usually sudo).');
+  if (result.ok) lines.push('Every required credential is present.');
+  lines.push('Deeper check of the publish credential (can it read Actions?): node scripts/gds/publish-credential-check.js');
+  return lines.join('\n');
+}
+
+// readFiles(etc) → the `files` shape sweep() takes, read from <etc>/<name>.
+function readFiles(etc, { fsImpl = fs } = {}) {
+  const files = {};
+  for (const name of ENV_FILES) {
+    const p = path.join(etc, name);
+    try {
+      files[name] = { env: parseEnvFile(fsImpl.readFileSync(p, 'utf8')) };
+    } catch (e) {
+      // An absent spaces.env just means offsite backups were never set up; an absent
+      // web.env means this is not the host (or the wrong --etc).
+      files[name] = e.code === 'ENOENT' && name !== 'web.env' ? { env: {} } : { error: e.code || e.message };
+    }
+  }
+  return files;
+}
+
+module.exports = { CREDENTIALS, ENV_FILES, parseEnvFile, checkRow, sweep, format, readFiles };
+
+if (require.main === module) {
+  const etcArg = arg('--etc');
+  const etc = etcArg && etcArg !== true ? etcArg : path.join('/etc', configDirName());
+  const files = readFiles(etc);
+  const keyArg = arg('--secret-key-file');
+  const keyFile = keyArg && keyArg !== true ? keyArg : configPath('builder-secret.key');
+  let keyFileExists = false;
+  try { keyFileExists = fs.statSync(keyFile).isFile(); } catch (_) { /* absent */ }
+  const result = sweep({ files, keyFileExists });
+  if (hasFlag('--json')) console.log(JSON.stringify({ etc, ...result }, null, 2));
+  else console.log(format(result, { etc }));
+  cliExit(result.unreadable.length ? 2 : result.ok ? 0 : 1);
+}

package/scripts/gds/db-backup-nightly.sh

@@ -131,7 +131,10 @@ pg_dump \
 # A SIGKILL mid-stream leaves a .partial that the next run will overwrite.
 mv "$OUT.partial" "$OUT"
 
-BYTES=$(stat -c '%s' "$OUT")
+# Size in bytes via POSIX `wc -c`, not `stat -c '%s'`: that is GNU-only, and BSD/macOS
+# stat refuses it outright, so every run on a Mac died here (task 1004170). tr drops the
+# padding BSD wc prints in front of the number.
+BYTES=$(wc -c < "$OUT" | tr -d '[:space:]')
 echo "[$(date -u +%FT%TZ)] gds-db-backup: wrote ${OUT} (${BYTES} bytes)"
 
 # Completeness guard (incident 2026-07-02, task 1711; task 1003925). pipefail already
@@ -190,7 +193,9 @@ ATTACH_OUT="${BACKUP_DIR}/${DB_NAME}-attachments-${TS}.tar.gz"
 ATTACH_GLOB="${DB_NAME}-attachments-${D}${D}${D}${D}-${D}${D}-${D}${D}T${D}${D}${D}${D}${D}${D}Z.tar.gz"
 
 if [ -d "$ATTACH_DIR" ]; then
-  ATTACH_COUNT=$(find "$ATTACH_DIR" -maxdepth 1 -type f | wc -l)
+  # Every count here goes through tr for the same reason as BYTES: BSD wc pads it, which
+  # put "pruned        1 dump(s)" in a Mac's log where Linux writes "pruned 1 dump(s)".
+  ATTACH_COUNT=$(find "$ATTACH_DIR" -maxdepth 1 -type f | wc -l | tr -d '[:space:]')
   if [ "$ATTACH_COUNT" -gt 0 ]; then
     if tar -czf "$ATTACH_OUT.partial" -C "$ATTACH_DIR" . 2>/dev/null; then
       mv "$ATTACH_OUT.partial" "$ATTACH_OUT"
@@ -215,7 +220,7 @@ fi
 PRUNED=$(find "$BACKUP_DIR" -maxdepth 1 -type f \
     \( -name "$DUMP_GLOB" -o -name "$ATTACH_GLOB" \) \
     -mtime +"${RETENTION_DAYS}" \
-    -print -delete | wc -l)
+    -print -delete | wc -l | tr -d '[:space:]')
 
 if [ "$PRUNED" -gt 0 ]; then
   echo "[$(date -u +%FT%TZ)] gds-db-backup: pruned ${PRUNED} dump(s) older than ${RETENTION_DAYS}d"
@@ -223,5 +228,5 @@ fi
 
 # ---- emit a one-line summary for journald + monitoring ---------------------
 
-REMAINING=$(find "$BACKUP_DIR" -maxdepth 1 -type f -name "$DUMP_GLOB" | wc -l)
+REMAINING=$(find "$BACKUP_DIR" -maxdepth 1 -type f -name "$DUMP_GLOB" | wc -l | tr -d '[:space:]')
 echo "[$(date -u +%FT%TZ)] gds-db-backup: ok · ${REMAINING} dump(s) retained · ${BYTES} bytes latest"

package/scripts/gds/db-backup-offsite.sh

@@ -169,7 +169,9 @@ if [ -z "$LATEST" ]; then
 fi
 
 BASENAME=$(basename "$LATEST")
-BYTES=$(stat -c '%s' "$LATEST")
+# Sizes via POSIX `wc -c`, never GNU-only `stat -c '%s'`, which BSD/macOS stat refuses
+# (task 1004170). tr drops the padding BSD wc prints in front of the number.
+BYTES=$(wc -c < "$LATEST" | tr -d '[:space:]')
 
 # ---- encrypt before it leaves the box ---------------------------------------
 #
@@ -189,7 +191,7 @@ fi
 
 # A zero-byte or missing ciphertext would upload happily and restore to nothing.
 # Checked here rather than trusted, because the failure is silent for a month.
-ENC_BYTES=$(stat -c '%s' "$ENC")
+ENC_BYTES=$(wc -c < "$ENC" | tr -d '[:space:]')
 if [ "$ENC_BYTES" -lt 1 ]; then
   echo "ERROR: encryption produced an empty file — refusing to upload it as a backup." >&2
   exit 2

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

@@ -42,9 +42,13 @@
 
 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
-  OTB_AUDIT_RANGE="${OTB_DEPLOY_PREV_SHA}..HEAD"; export OTB_AUDIT_RANGE
-  echo "main audit: range ${OTB_AUDIT_RANGE} (exact deploy delta)"
+  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;"
@@ -64,7 +68,10 @@ if [ ! -f "$MAIN_AUDIT" ]; then
   exit 1
 fi
 
-if node "$MAIN_AUDIT" --verify-head --db ${STRICT}; then
+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
@@ -72,7 +79,7 @@ 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 \"\${OTB_AUDIT_RANGE:-HEAD~200..HEAD}\" --revert"
+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