@bongos/core 1.19.876 → 1.19.877

package/scripts/gds/autobongos-service.ps1

@@ -0,0 +1,129 @@
+# scripts/gds/autobongos-service.ps1 -- install the Autobongos runner so it
+# outlives the reboot (task 1003905, ADR 0307 section 5).
+#
+#   powershell -ExecutionPolicy Bypass -File scripts\gds\autobongos-service.ps1 install
+#   powershell -ExecutionPolicy Bypass -File scripts\gds\autobongos-service.ps1 status
+#   powershell -ExecutionPolicy Bypass -File scripts\gds\autobongos-service.ps1 start|stop|uninstall
+#
+# WHY TASK SCHEDULER AND NOT A REAL SERVICE. Windows services speak a protocol
+# (SCM handshakes, stop signals) that node does not, so every "node as a service"
+# route needs a third-party wrapper: nssm, winsw, node-windows. Each is a binary
+# to download, verify, update and explain -- a permanent dependency bought for one
+# machine. Task Scheduler is already on the box, runs at boot with no session,
+# survives sign-out, and restarts a crashed task natively. The one thing it does
+# not give is the Services panel, which nobody here needs.
+#
+# WHAT ACTUALLY KEEPS IT ALIVE IS THE INNER LOOP, and that is the important part
+# to understand before reading the RestartCount settings below. `--forever` never
+# returns: it backs off and probes instead of exiting (task 1003904), so the
+# scheduler's restart is the OUTER ring, for the cases the loop cannot survive at
+# all -- a reboot, a power cut, a node crash, an OOM kill. If this ring is doing
+# work regularly, something is wrong that the backoff should have absorbed, and
+# the run log will say so.
+#
+# UNPRIVILEGED ON PURPOSE. It runs as the logged-in user, not SYSTEM: the runner
+# needs that user's git credential, npm config and Claude session, and SYSTEM has
+# none of them. It is also the smaller blast radius for a process that spawns
+# workers with blanket bypassPermissions.
+
+[CmdletBinding()]
+param(
+  [Parameter(Position = 0)]
+  [ValidateSet('install', 'uninstall', 'start', 'stop', 'status')]
+  [string]$Action = 'status',
+
+  # The checkout to run from. Defaults to the repo this script lives in, so the
+  # common case needs no argument and cannot point at the wrong tree by typo.
+  [string]$RepoRoot,
+
+  [string]$TaskName = 'Autobongos'
+)
+
+$ErrorActionPreference = 'Stop'
+
+if (-not $RepoRoot) {
+  $RepoRoot = (Resolve-Path (Join-Path $PSScriptRoot '..\..')).Path
+}
+$LogDir = Join-Path $env:LOCALAPPDATA 'cloudbongos'
+$LogFile = Join-Path $LogDir 'autobongos.log'
+$Wrapper = Join-Path $RepoRoot 'scripts\gds\autobongos-service.cmd'
+
+function Assert-Prereqs {
+  if (-not (Test-Path (Join-Path $RepoRoot 'scripts\gds\autobongos-run.js'))) {
+    throw "No autobongos-run.js under $RepoRoot -- pass -RepoRoot <path to the checkout>."
+  }
+  foreach ($exe in @('node', 'git', 'claude')) {
+    if (-not (Get-Command $exe -ErrorAction SilentlyContinue)) {
+      # Named, not guessed at: a runner that starts without `claude` on PATH will
+      # spawn-fail every worker and look like a mysterious outage in the log.
+      throw "'$exe' is not on PATH for this user. The runner needs node, git and claude."
+    }
+  }
+}
+
+function Show-Status {
+  $t = Get-ScheduledTask -TaskName $TaskName -ErrorAction SilentlyContinue
+  if (-not $t) { Write-Host "not installed  (task '$TaskName' does not exist)"; return }
+  $info = Get-ScheduledTaskInfo -TaskName $TaskName
+  Write-Host "task       : $TaskName"
+  Write-Host "state      : $($t.State)"
+  Write-Host "last run   : $($info.LastRunTime)  (result $($info.LastTaskResult))"
+  Write-Host "next run   : $($info.NextRunTime)"
+  Write-Host "log        : $LogFile"
+  if (Test-Path $LogFile) {
+    Write-Host "log size   : $([math]::Round((Get-Item $LogFile).Length / 1KB)) KB"
+    Write-Host ''
+    Write-Host '--- last 15 lines ---'
+    Get-Content $LogFile -Tail 15
+  } else {
+    Write-Host 'log        : (not written yet)'
+  }
+  Write-Host ''
+  Write-Host 'The scheduler only says whether the PROCESS is up. Whether the runner'
+  Write-Host 'is actually working is the hall: it reads the heartbeat this posts.'
+}
+
+switch ($Action) {
+  'install' {
+    Assert-Prereqs
+    New-Item -ItemType Directory -Force -Path $LogDir | Out-Null
+
+    $action = New-ScheduledTaskAction -Execute $Wrapper -WorkingDirectory $RepoRoot
+    # AtStartup covers the cold reboot the done-when actually names. AtLogOn is
+    # NOT used: it would wait for someone to sign in, which is the one thing that
+    # must not be required.
+    $trigger = New-ScheduledTaskTrigger -AtStartup
+    $principal = New-ScheduledTaskPrincipal -UserId "$env:USERDOMAIN\$env:USERNAME" -LogonType S4U -RunLevel Limited
+    $settings = New-ScheduledTaskSettingsSet `
+      -AllowStartIfOnBatteries -DontStopIfGoingOnBatteries `
+      -StartWhenAvailable `
+      -RestartCount 999 -RestartInterval (New-TimeSpan -Minutes 1) `
+      -ExecutionTimeLimit ([TimeSpan]::Zero) `
+      -MultipleInstances IgnoreNew
+    # ExecutionTimeLimit ZERO = never kill it. The default is three days, and a
+    # daemon silently executed after three days is exactly the invisible death
+    # this whole task exists to prevent.
+    # MultipleInstances IgnoreNew = the scheduler will not start a second copy
+    # over a live one; the heartbeat file is the second guard, inside the runner.
+
+    Register-ScheduledTask -TaskName $TaskName -Action $action -Trigger $trigger `
+      -Principal $principal -Settings $settings -Force | Out-Null
+
+    Write-Host "installed '$TaskName' -- starts at boot, restarts on crash, logs to $LogFile"
+    Write-Host ''
+    Write-Host 'Start it now with:   .\scripts\gds\autobongos-service.ps1 start'
+    Write-Host 'Then confirm from the hall (/builders/gate) that it is checking in.'
+  }
+  'uninstall' {
+    Unregister-ScheduledTask -TaskName $TaskName -Confirm:$false -ErrorAction SilentlyContinue
+    Write-Host "removed '$TaskName'. The log at $LogFile is left in place."
+  }
+  'start'  { Start-ScheduledTask -TaskName $TaskName; Write-Host "started '$TaskName'" }
+  'stop'   {
+    Stop-ScheduledTask -TaskName $TaskName
+    Write-Host "stopped '$TaskName' -- but note this only stops the PROCESS on this machine."
+    Write-Host 'The durable way to stop the runner is the kill switch in the hall, which'
+    Write-Host 'survives a reboot and cannot be undone by anything running here.'
+  }
+  default  { Show-Status }
+}

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

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

package/scripts/gds/main-audit.js

@@ -251,6 +251,13 @@ function rowsToMap(rows) {
   return map;
 }
 
+// Where getBuildersRoster lives. It was carved out of src/bongos/db.js into the
+// lifecycle module (goal 1000010's per-domain db.js split) and this file was not
+// updated with it, so `--db` threw `db.getBuildersRoster is not a function` on every
+// run — for however long that carve has been landed. Kept as a named constant so the
+// next carve breaks a test (tests/main_audit_db_roster.mjs) rather than a deploy gate.
+const ROSTER_DB_MODULE = '../../modules/lifecycle/db.js';
+
 // API mode (default): for an Archon session / operator laptop. DB mode (--db):
 // for the droplet deploy gate, which has DB access but no GDS session — it reads
 // the roster straight from Postgres. db.js is lazy-required so importing this
@@ -258,13 +265,24 @@ function rowsToMap(rows) {
 async function fetchRankMap({ useDb = false } = {}) {
   if (useDb) {
     try {
-      const db = require('../../src/bongos/db.js');
+      const db = require(ROSTER_DB_MODULE);
+      if (typeof db.getBuildersRoster !== 'function') {
+        // The exact failure this file already shipped once, named rather than caught as a
+        // generic TypeError: a moved export reads identically to "no database" otherwise.
+        throw new Error(`${ROSTER_DB_MODULE} exports no getBuildersRoster — it has moved again`);
+      }
       const roster = await db.getBuildersRoster({ staleHours: 24 });
-      return rowsToMap(roster.builders || roster);
+      const map = rowsToMap(roster.builders || roster);
+      if (Object.keys(map).length) return map;
+      console.error('main-audit: --db roster read returned NO builders — falling through to the API/public roster.');
     } catch (e) {
-      console.error(`main-audit: --db roster read failed (${e.message})`);
-      return {};
+      console.error(`main-audit: --db roster read failed (${e.message}) — falling through to the API/public roster.`);
     }
+    // FALL THROUGH, do not return {}. Returning an empty map here is the vacuous green
+    // this file's own comment warns about twelve lines down: with no ranks, every author
+    // resolves to null, no blocker can ever fire, and the gate reports success for the
+    // reason it was built to prevent. A `--db` gate that cannot reach Postgres is better
+    // served by the public leaderboard than by silence.
   }
   try {
     const api = await cliClient({ allowUnauthenticated: true });
@@ -394,4 +412,8 @@ if (require.main === module) {
 module.exports = {
   analyzeCommits, resolveRank, parseCommits, rowsToMap,
   clampWindow, defaultRange, firstParentDepth, DEFAULT_WINDOW,
+  // Exported so a test can assert the address is LIVE without a database. The --db
+  // path was dead for as long as the db.js carve has been landed precisely because
+  // nothing checked that this require target still exports what it is called for.
+  ROSTER_DB_MODULE, fetchRankMap,
 };

package/scripts/gds/run-unit-tests.js

@@ -464,7 +464,12 @@ function main() {
       if (n) skipped.push({ name: displayName, n });
       console.log(`  ok    ${displayName}${n ? ` (${n} SKIPPED — not run on this platform)` : ''}`);
     } catch (err) {
-      const why = err.killed ? 'TIMEOUT' : `exit ${err.status}`;
+      // `exit null` on its own is unreadable, and it is what a HANG looks like here: the
+      // signal that ended the process is the whole diagnosis, so say it (task 1004052 —
+      // a test that hung for the full budget reported `exit null` and nothing else).
+      const why = err.killed
+        ? `TIMEOUT after ${perTestTimeout / 1000}s${err.signal ? `, ${err.signal}` : ''}`
+        : `exit ${err.status}${err.signal ? ` (${err.signal})` : ''}`;
       const stdoutText = (err.stdout ? err.stdout.toString() : '').trim();
       if (!err.killed && isCleanTeardownAbort(stdoutText, err.stderr ? err.stderr.toString() : '')) {
         console.log(`  ok    ${displayName} (clean verdict, then libuv teardown abort, ${why})`);
@@ -474,6 +479,16 @@ function main() {
       console.log(`  FAIL  ${displayName} (${why})`);
       // The actual failures first: the file's own FAIL lines, then its stdout
       // tail (the last failure's assertion detail + summary), both bounded.
+      // EMPTY STDOUT IS ITSELF THE CLUE, and it used to print as a blank gap. node:test
+      // buffers a file's whole report until the file finishes, so a suite that hangs
+      // mid-run emits NOTHING — which reads as "no detail available" when it actually
+      // means "it never got to the end". Name that, and name how to find the case.
+      if (!stdoutText) {
+        console.log('        (no output at all — node:test buffers a file\'s report until it finishes,');
+        console.log('         so this suite did not reach the end. To find which case: run it on the same');
+        console.log('         platform with each case writing its name to STDERR before it runs; stderr is');
+        console.log('         unbuffered, so the last name with no completion is the one that hung.)');
+      }
       const failLines = stdoutText ? stdoutText.split('\n').filter((l) => /\bFAIL\b/.test(l)).slice(0, 5) : [];
       for (const l of failLines) console.log(`      ${l.trim()}`);
       if (stdoutText) {

package/src/module-api.js

@@ -71,7 +71,7 @@ const { responsibilityFor, ROLE_RESPONSIBILITIES } = require('./role-responsibil
 // there. scripts/gds/bump-version.js still rewrites the literal below; it appends
 // the entry to that file. Look for a version's history there, not here.
 // ---------------------------------------------------------------------------
-const CORE_VERSION = '1.19.876'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
+const CORE_VERSION = '1.19.877'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
 
 // A namespaced logger so a module's log lines are attributable + consistent.
 // Usage: const log = api.logger('dev-box'); log.info('mounted');