@bongos/core 1.21.175 → 1.21.177

package/scripts/bongos/audit-rank-roles.js

@@ -0,0 +1,131 @@
+#!/usr/bin/env node
+// scripts/bongos/audit-rank-roles.js — does the live builder roster hold ONLY the
+// four live ranks? (task 1002873)
+//
+// WHY. `migrations/023`'s CHECK on `builders.rank` still admits twelve legacy
+// values beyond the four live ranks. `governance_002_seed_and_backfill.sql`
+// backfills roles with an INNER JOIN from `builders.rank` to the four seeded
+// `governance_roles`, so a builder sitting on a legacy rank gets NO role row and
+// resolves to ZERO permissions: admitted by threshold under `requireRank`, locked
+// out of everything under the resolver. They are not told why, and nothing about
+// their account looks wrong.
+//
+// That divergence is deliberate — ADR 0151 chose fail-closed, and
+// `tests/governance_parity.mjs` asserts it is strictly a tightening. What was
+// missing is the VERIFICATION. governance_002's comment says "none exist today —
+// verified", a point-in-time manual check that nothing re-runs; the parity test
+// is DB-free by necessity (the unit gate has no Postgres) and says so in the
+// repo; and R114's live proof ran on a scratch DB holding only the four seeded
+// rank-roles, so the production roster was never queried.
+//
+// THIS IS THE RE-RUNNABLE HALF, and it is deliberately NOT fatal at boot. Idea
+// 1000622 records that trap: an assertion that throws on startup turns a data
+// problem on one instance into an outage. This is a standalone read-only script
+// for a by-hand or deploy-time caller — it exits 1 so a caller can act, and nothing
+// in the server's boot path requires it. The SCHEDULED run is in-process: the
+// server's daily-checks poller (task 1004878) reads the roster straight from its
+// database and files the same idea, so it needs no CLI session.
+//
+// It reports rather than repairs, and that is a decision, not an omission:
+// rewriting somebody's rank is an authority change, and it belongs to an operator
+// who can see who the account is — not to a sweep.
+//
+//   node scripts/bongos/audit-rank-roles.js [--json] [--file-idea]
+//
+// Exit codes:
+//   0  every builder holds a live rank
+//   1  at least one builder holds a rank the governance backfill cannot match
+//   2  could not read the roster (no session / network / route absent)
+//
+// `--file-idea` is what makes this a SURFACE rather than another thing nobody
+// runs — spawning capture.js so idea
+// filing has one implementation. Without it a nightly deterministic run that exits
+// 1 reports into a log nobody reads, which is the exact criticism this task makes
+// of the status quo.
+
+const path = require('node:path');
+const { spawnSync } = require('node:child_process');
+const fs = require('node:fs');
+const os = require('node:os');
+const { cliClient, requireSession, cliExit } = require('./cli-lib');
+const { LIVE_RANK_LADDER } = require('../../src/bongos/db-kernel.js');
+
+// The pure half lives in modules/autonomy/rank-roles.js (task 1004878), shared with
+// the server's daily check (modules/autonomy/pollers/daily-checks.js) so the two
+// cannot disagree about what an offender is. This wrapper defaults the ladder.
+const rankRoles = require('../../modules/autonomy/rank-roles.js');
+
+const findRanksWithoutRoles = (rows, liveRanks = LIVE_RANK_LADDER) => rankRoles.findRanksWithoutRoles(rows, liveRanks);
+const { summarize } = rankRoles;
+
+// Spawn capture.js rather than POSTing here, so idea filing keeps one
+// implementation. Best-effort: a failure to
+// file must not turn a successful audit into a crash — the exit code and stdout
+// still carry the finding.
+function fileIdea(offenders) {
+  const { title, bodyMd } = rankRoles.ideaFor(offenders);
+  const tmp = path.join(os.tmpdir(), `rank-roles-audit-${process.pid}.md`);
+  try {
+    fs.writeFileSync(tmp, bodyMd, 'utf8');
+    const r = spawnSync(
+      process.execPath,
+      [path.join(__dirname, 'capture.js'), title, '--kind', 'bug', '--body-file', tmp],
+      { encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'], timeout: 60_000 }
+    );
+    if (r.status !== 0) console.error('audit-rank-roles: capture.js failed to file the idea — the exit code above still carries the finding.');
+  } catch (e) {
+    console.error(`audit-rank-roles: could not file the idea (${(e && e.message) || e}) — the exit code above still carries the finding.`);
+  } finally {
+    try { fs.rmSync(tmp, { force: true }); } catch (_) { /* best-effort */ }
+  }
+}
+
+async function main() {
+  const json = process.argv.includes('--json');
+  await requireSession();
+  const api = await cliClient();
+  const r = await api.request('GET', '/builders/roster');
+  if (!r.ok) {
+    console.error(`audit-rank-roles: could not read the roster (HTTP ${r.status}).`);
+    console.error('  Needs a session with builder.roster.read. Nothing was checked — do NOT read this as a pass.');
+    return cliExit(2);
+  }
+  // The roster query has no WHERE on `builders`, so this covers every row,
+  // INACTIVE ONES INCLUDED. That matters: a deactivated builder on a legacy rank
+  // is exactly the row a future CHECK-narrowing migration would fail to apply over.
+  const rows = (r.data && (r.data.builders || r.data.roster || r.data)) || [];
+  const offenders = findRanksWithoutRoles(rows);
+  const histogram = summarize(rows);
+
+  if (json) {
+    console.log(JSON.stringify({ checked: rows.length, live_ranks: LIVE_RANK_LADDER, histogram, offenders }, null, 2));
+    return cliExit(offenders.length ? 1 : 0);
+  }
+
+  console.log(`audit-rank-roles: ${rows.length} builder row(s) checked against the live ladder [${LIVE_RANK_LADDER.join(', ')}]`);
+  for (const [rank, n] of histogram) console.log(`  ${String(rank).padEnd(12)} ${n}`);
+  if (!offenders.length) {
+    console.log('\n✓ every builder holds a live rank — the governance backfill can match all of them.');
+    return cliExit(0);
+  }
+  console.log(`\n✗ ${offenders.length} builder(s) hold a rank with no matching governance role.`);
+  console.log('  They resolve to ZERO permissions: admitted by rank threshold, refused by the resolver,');
+  console.log('  and nothing tells them why (ADR 0151 fail-closed).');
+  for (const o of offenders) {
+    console.log(`  - builder ${o.id}${o.github_login ? ` (${o.github_login})` : ''} rank=${o.rank === null ? '(none)' : o.rank} status=${o.status || '?'}`);
+  }
+  console.log('\n  This is a BUILDER NEED, not an outage: move each to a live rank with the normal');
+  console.log('  rank-change path so the governance role rotates in the same transaction.');
+  console.log('  Deliberately not repaired here — changing a rank is an authority decision.');
+  if (process.argv.includes('--file-idea')) fileIdea(offenders);
+  return cliExit(1);
+}
+
+if (require.main === module) {
+  main().catch((err) => {
+    console.error('audit-rank-roles:', (err && err.message) || err);
+    cliExit(2);
+  });
+}
+
+module.exports = { findRanksWithoutRoles, summarize };

package/scripts/bongos/audit-replay.sh

@@ -0,0 +1,205 @@
+#!/usr/bin/env bash
+# scripts/bongos/audit-replay.sh — V3.R52 (#271).
+#
+# Given a builder_id and a date range, reconstruct chronologically EVERY
+# trace of what that builder did against the city. The point is the
+# forensic question: "If someone went rogue, can we tell?"
+#
+# Tables walked (each contributes timestamped rows):
+#   - claims          (CLAIM + CLAIM_END events per task; outcome carries
+#                     the disposition: shipped / abandoned / partial / expired)
+#   - credit_log      (drachmae awards / debits)
+#   - cost_log        (API + infra spend they logged)
+#   - session_logs    (claim-scoped session boundaries + outcome)
+#   - audit_log       (HTTP writes — V3.R35 #256)
+#
+# Two modes:
+#   1. ON THE DROPLET (psql against the local Unix socket — fast, no auth).
+#   2. FROM A LAPTOP via SSH (the script self-hops; you need lars@<droplet>).
+#      Triggered if the local PG socket isn't reachable.
+#
+# Usage:
+#   bash scripts/bongos/audit-replay.sh <builder_id> <start_iso> <end_iso>
+#
+# Example:
+#   bash scripts/bongos/audit-replay.sh 1 2026-05-20T00:00:00Z 2026-05-28T23:59:59Z
+#
+# Output: TSV columns: when_utc, kind, detail. Sorted chronologically.
+# See docs/recipes/audit-replay.md for the recipe + how to extend.
+
+set -euo pipefail
+
+BUILDER_ID="${1:-}"
+START="${2:-}"
+END="${3:-}"
+
+if [ -z "$BUILDER_ID" ] || [ -z "$START" ] || [ -z "$END" ]; then
+  cat <<USAGE >&2
+usage: $0 <builder_id> <start_iso> <end_iso>
+
+  builder_id   the id from the builders table (e.g. 1 for example-owner)
+  start_iso    inclusive lower bound, RFC3339/ISO 8601 (e.g. 2026-05-20T00:00:00Z)
+  end_iso      inclusive upper bound, same shape
+
+example:
+  $0 1 2026-05-20T00:00:00Z 2026-05-28T23:59:59Z
+
+see docs/recipes/audit-replay.md
+USAGE
+  exit 2
+fi
+
+# Validate the SHAPE of all three before they go anywhere. Below, these are
+# interpolated into a remote command string for the SSH re-invocation, where a
+# value carrying a single quote would break out of its quoting. Quote-escaping
+# that is fiddly and easy to get subtly wrong; these arguments are an integer id
+# and two ISO 8601 timestamps, so pinning the shape removes the question instead
+# of answering it — and it catches an operator's typo before a round trip, which
+# is the more common failure by far. (Raised by review on task 1003869.)
+if ! printf '%s' "$BUILDER_ID" | grep -qE '^[0-9]+$'; then
+  echo "REFUSING: builder_id '$BUILDER_ID' is not a positive integer." >&2
+  exit 2
+fi
+for ts in "$START" "$END"; do
+  if ! printf '%s' "$ts" | grep -qE '^[0-9]{4}-[0-9]{2}-[0-9]{2}([T ][0-9]{2}:[0-9]{2}:[0-9]{2}(\.[0-9]+)?(Z|[+-][0-9]{2}:?[0-9]{2})?)?$'; then
+    echo "REFUSING: '$ts' is not an ISO 8601 timestamp (e.g. 2026-05-20T00:00:00Z)." >&2
+    exit 2
+  fi
+done
+
+# Decide local vs remote. The droplet's Postgres listens on a Unix socket
+# under /var/run/postgresql; if we can stat it, we're already on the droplet.
+# The remote target for the re-invocation below. SOURCED FROM THE ENV, never baked in:
+# a portable core carries no instance topology, and this ran with customer-zero's droplet
+# hardcoded until task 1003869. Set BONGOS_AUDIT_HOST=<user>@<host> (or run the script on
+# the database host itself, where the socket check below short-circuits the SSH leg).
+DROPLET="${BONGOS_AUDIT_HOST:-}"
+PG_SOCKET="/var/run/postgresql"
+
+# Database + role: explicit env wins, else the branding-pack resolver (task
+# 1002757 — the founder DB/unix-user pair was baked in as runtime args). The
+# role defaults to the CURRENT unix user (peer auth), matching migrate.sh.
+# Resolved BEFORE any SSH re-invocation: the remote side has no repo to
+# resolve from, so the value rides the wire in GDS_AUDIT_DB.
+AUDIT_DB="${GDS_AUDIT_DB:-${PGDATABASE:-}}"
+if [ -z "$AUDIT_DB" ]; then
+  SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]:-$0}")" 2>/dev/null && pwd || true)"
+  [ -n "$SCRIPT_DIR" ] && AUDIT_DB="$(node -e "process.stdout.write(require(process.argv[1]).instanceDbName() || '')" "$SCRIPT_DIR/../../src/bongos/pool" 2>/dev/null || true)"
+fi
+if [ -z "$AUDIT_DB" ]; then
+  echo "audit-replay: cannot determine the database — set GDS_AUDIT_DB or PGDATABASE (refusing a baked-in default, task 1002757)." >&2
+  exit 2
+fi
+
+if [ ! -S "$PG_SOCKET/.s.PGSQL.5432" ]; then
+  # Re-invoke ourselves on the droplet. The script doesn't depend on any
+  # repo file at runtime, so we ship the script body over stdin to avoid a
+  # rsync step. Quoting on the SSH side preserves the timestamp args; the
+  # locally-resolved DB name rides along (no repo on the remote side).
+  if [ -z "$DROPLET" ]; then
+    echo "audit-replay: no local Postgres socket at $PG_SOCKET, and no remote host to fall back to." >&2
+    echo "  Set BONGOS_AUDIT_HOST=<user>@<host> to re-invoke there, or run this on the database host." >&2
+    exit 2
+  fi
+  exec ssh -o ConnectTimeout=10 "$DROPLET" \
+    "GDS_AUDIT_DB='$AUDIT_DB' bash -s -- '$BUILDER_ID' '$START' '$END'" < "$0"
+fi
+
+# From here down: running where Postgres is reachable on the Unix socket.
+
+PSQL_ARGS=(-h "$PG_SOCKET" -d "$AUDIT_DB" -t -A -F $'\t' --no-psqlrc)
+[ -n "${GDS_AUDIT_PG_USER:-}" ] && PSQL_ARGS+=(-U "$GDS_AUDIT_PG_USER")
+
+q() {
+  PGOPTIONS='--client-min-messages=warning' psql "${PSQL_ARGS[@]}" -c "$1"
+}
+
+# Single UNION ALL so the chronological sort is one operation. The leading
+# timestamp column normalises to ISO-8601 UTC so the textual sort is the
+# chronological sort.
+SQL=$(cat <<SQL
+WITH range AS (
+  SELECT '${START}'::timestamptz AS lo, '${END}'::timestamptz AS hi
+),
+all_events AS (
+  -- CLAIM (claim row born)
+  SELECT to_char(c.claimed_at AT TIME ZONE 'UTC', 'YYYY-MM-DD"T"HH24:MI:SS"Z"') AS when_utc,
+         'CLAIM' AS kind,
+         ('task=' || c.task_id || ' claim_id=' || c.id ||
+          ' worktree=' || COALESCE(c.worktree_name, '-')) AS detail
+    FROM claims c, range
+   WHERE c.builder_id = ${BUILDER_ID}
+     AND c.claimed_at BETWEEN range.lo AND range.hi
+
+  UNION ALL
+  -- CLAIM_END (released — outcome distinguishes shipped vs abandoned, etc.)
+  SELECT to_char(c.released_at AT TIME ZONE 'UTC', 'YYYY-MM-DD"T"HH24:MI:SS"Z"') AS when_utc,
+         'CLAIM_END' AS kind,
+         ('task=' || c.task_id || ' claim_id=' || c.id ||
+          ' outcome=' || COALESCE(c.outcome, '-')) AS detail
+    FROM claims c, range
+   WHERE c.builder_id = ${BUILDER_ID}
+     AND c.released_at IS NOT NULL
+     AND c.released_at BETWEEN range.lo AND range.hi
+
+  UNION ALL
+  -- CREDIT (drachmae movement)
+  SELECT to_char(cl.recorded_at AT TIME ZONE 'UTC', 'YYYY-MM-DD"T"HH24:MI:SS"Z"') AS when_utc,
+         'CREDIT' AS kind,
+         ('delta=' || cl.delta || ' reason=' || cl.reason ||
+          ' task=' || COALESCE(cl.task_id::text, '-')) AS detail
+    FROM credit_log cl, range
+   WHERE cl.builder_id = ${BUILDER_ID}
+     AND cl.recorded_at BETWEEN range.lo AND range.hi
+
+  UNION ALL
+  -- COST (spend they logged; co.task_id may be NULL for infra-level entries)
+  SELECT to_char(co.recorded_at AT TIME ZONE 'UTC', 'YYYY-MM-DD"T"HH24:MI:SS"Z"') AS when_utc,
+         'COST' AS kind,
+         ('category=' || co.category || ' usd=' || co.amount_usd ||
+          ' source=' || COALESCE(co.source, '-') ||
+          ' task=' || COALESCE(co.task_id::text, '-')) AS detail
+    FROM cost_log co
+    JOIN claims c2 ON c2.task_id = co.task_id AND c2.builder_id = ${BUILDER_ID}
+    , range
+   WHERE co.recorded_at BETWEEN range.lo AND range.hi
+   GROUP BY co.id, co.recorded_at, co.category, co.amount_usd, co.source, co.task_id
+
+  UNION ALL
+  -- SESSION_START
+  SELECT to_char(sl.started_at AT TIME ZONE 'UTC', 'YYYY-MM-DD"T"HH24:MI:SS"Z"') AS when_utc,
+         'SESSION_START' AS kind,
+         ('claim_id=' || COALESCE(sl.claim_id::text, '-') ||
+          ' task=' || COALESCE(sl.task_id::text, '-')) AS detail
+    FROM session_logs sl, range
+   WHERE sl.builder_id = ${BUILDER_ID}
+     AND sl.started_at BETWEEN range.lo AND range.hi
+
+  UNION ALL
+  -- SESSION_END
+  SELECT to_char(sl.ended_at AT TIME ZONE 'UTC', 'YYYY-MM-DD"T"HH24:MI:SS"Z"') AS when_utc,
+         'SESSION_END' AS kind,
+         ('claim_id=' || COALESCE(sl.claim_id::text, '-') ||
+          ' outcome=' || COALESCE(sl.outcome, '-')) AS detail
+    FROM session_logs sl, range
+   WHERE sl.builder_id = ${BUILDER_ID}
+     AND sl.ended_at BETWEEN range.lo AND range.hi
+
+  UNION ALL
+  -- HTTP write
+  SELECT to_char(al.recorded_at AT TIME ZONE 'UTC', 'YYYY-MM-DD"T"HH24:MI:SS"Z"') AS when_utc,
+         'HTTP_' || al.method AS kind,
+         ('route=' || al.route ||
+          ' status=' || al.response_status ||
+          ' ip=' || COALESCE(al.ip, '-')) AS detail
+    FROM audit_log al, range
+   WHERE al.builder_id = ${BUILDER_ID}
+     AND al.recorded_at BETWEEN range.lo AND range.hi
+)
+SELECT when_utc, kind, detail
+  FROM all_events
+ ORDER BY when_utc, kind;
+SQL
+)
+
+q "$SQL"

package/scripts/bongos/autobongos-digest.js

@@ -0,0 +1,123 @@
+#!/usr/bin/env node
+'use strict';
+
+// scripts/bongos/autobongos-digest.js — read the night without opening a log
+// (task 1003906, ADR 0307).
+//
+//   node scripts/bongos/autobongos-digest.js              # since midnight, local
+//   node scripts/bongos/autobongos-digest.js --since 24h  # a rolling window
+//   node scripts/bongos/autobongos-digest.js --json       # the structured shape
+//   node scripts/bongos/autobongos-digest.js --all        # the whole log
+//
+// The decision logic is modules/autonomy/digest.js and has no I/O; this half
+// finds the two files it reads and prints the result. Exit 0 always, including on
+// an empty night: a digest is a report, and a non-zero exit would make a cron
+// wrapper treat "nothing happened" as a failure.
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const digest = require('../../modules/autonomy/digest.js');
+
+const REPO_ROOT = path.resolve(__dirname, '..', '..');
+
+function arg(flag, argv) {
+  const i = argv.indexOf(flag);
+  return i >= 0 ? argv[i + 1] : null;
+}
+
+function logPath() {
+  if (process.env.AUTOBONGOS_LOG_FILE) return process.env.AUTOBONGOS_LOG_FILE;
+  try { return require('../../src/instance-config.js').configPath('autobongos-runs.jsonl'); }
+  catch (_) { return path.join(REPO_ROOT, 'autobongos-runs.jsonl'); }
+}
+
+function gaugePath() {
+  if (process.env.AUTOBONGOS_GAUGE_FILE) return process.env.AUTOBONGOS_GAUGE_FILE;
+  try { return require('../../src/instance-config.js').configPath('autobongos-gauge.json'); }
+  catch (_) { return path.join(REPO_ROOT, 'autobongos-gauge.json'); }
+}
+
+// readRows — an append-only JSONL, and a single unparseable line must not cost
+// the whole night. A JSONL written by a process that can be killed mid-write has
+// a torn last line more often than never.
+function readRows(file) {
+  let text;
+  try { text = fs.readFileSync(file, 'utf8'); }
+  catch (_) { return { rows: [], missing: true, skipped: 0 }; }
+  const rows = [];
+  let skipped = 0;
+  for (const line of text.split('\n')) {
+    const t = line.trim();
+    if (!t) continue;
+    try { rows.push(JSON.parse(t)); } catch (_) { skipped += 1; }
+  }
+  return { rows, missing: false, skipped };
+}
+
+function readGaugeFile(file) {
+  try { return JSON.parse(fs.readFileSync(file, 'utf8')); }
+  catch (_) { return null; }
+}
+
+// sinceMs — `--since 24h|90m|3d`, or midnight LOCAL by default.
+//
+// Local rather than UTC because the question is "what happened last night" and
+// night is a local idea; a UTC midnight cut would split an owner's evening in
+// half depending on where they live.
+function sinceMs(spec, now = new Date()) {
+  if (!spec) {
+    const d = new Date(now);
+    d.setHours(0, 0, 0, 0);
+    return d.getTime();
+  }
+  const m = /^(\d+(?:\.\d+)?)\s*([hmd])$/i.exec(String(spec).trim());
+  if (!m) return null;
+  const mult = { h: 3600e3, m: 60e3, d: 86400e3 }[m[2].toLowerCase()];
+  return now.getTime() - Number(m[1]) * mult;
+}
+
+function main(argv) {
+  const all = argv.includes('--all');
+  const asJson = argv.includes('--json');
+  const now = new Date();
+  const from = all ? null : sinceMs(arg('--since', argv), now);
+  if (!all && from === null) {
+    console.error('autobongos-digest: --since wants a span like 24h, 90m or 3d.');
+    return 2;
+  }
+
+  const lf = logPath();
+  const { rows, missing, skipped } = readRows(lf);
+  const inWindow = all ? rows : rows.filter((r) => {
+    const t = Date.parse(r && r.at);
+    return Number.isFinite(t) ? t >= from : true;   // an undated row is kept, not silently dropped
+  });
+
+  const d = digest.buildDigest(inWindow, {
+    gauge: readGaugeFile(gaugePath()),
+    nowEpochS: Math.floor(now.getTime() / 1000),
+    sinceMs: all ? null : from,
+    untilMs: now.getTime(),
+  });
+
+  if (asJson) { console.log(JSON.stringify(d, null, 2)); return 0; }
+
+  console.log('');
+  console.log(digest.renderDigest(d));
+  // Both of these are about the DIGEST's own reliability, so they sit outside the
+  // five questions rather than being folded into them.
+  if (missing) {
+    console.log('');
+    console.log(`  No run log at ${lf} — the runner has not written one here yet.`);
+  }
+  if (skipped) console.log(`  (${skipped} unreadable line(s) in the log were skipped.)`);
+  console.log('');
+  return 0;
+}
+
+if (require.main === module) {
+  process.exit(main(process.argv.slice(2)));
+}
+
+module.exports = { main, sinceMs, readRows, logPath, gaugePath };

package/scripts/bongos/autobongos-grade-cap.js

@@ -0,0 +1,187 @@
+'use strict';
+
+// scripts/bongos/autobongos-grade-cap.js — the grade cap for ONE autonomous run
+// (task 1004536).
+//
+// THE RULE (owner, 2026-10-02): a task that fails the grade twice goes to the
+// owner instead of being retried. In one worker run a task gets its first grade
+// plus at most ONE re-grade. Evidence for why: grader-refusal loops were 48% of
+// all Autobongos spend for zero ships — task 1004512 cost $63.81 over three grade
+// rounds, task 1003564 $13.74. The worker prompt already said "return
+// cannot_complete if the grader refuses", and the worker ignored it. A prompt
+// line is not a limit.
+//
+// WHERE IT IS ENFORCED — one boundary, one courtesy:
+//   1. THE BOUNDARY is the supervisor (autobongos-run.js), and its count comes
+//      from the SERVER: every graded round is POSTed to /tasks/:id/grade and
+//      appended to `grade_attempts` (an append-only table the worker has no write
+//      path to). The supervisor notes the newest attempt before spawning, counts
+//      the rounds after it (roundsFromAttempts), kills a worker still running
+//      once two graded FAILs exist, and ends the run as needs_human whatever the
+//      worker's verdict says. Nothing on the worker's machine — env, files —
+//      feeds this count, so a worker cannot erase it. (A round the worker never
+//      POSTs cannot advance the task either, so it is not a way around the cap.)
+//   2. THE COURTESY is ship.js refusing to START a third grade (checkGradeCap at
+//      its entry, before any flag is read). The worker's own process holds that
+//      check's inputs — a run ledger named in env — so it is NOT the boundary; a
+//      worker could clear the variable. It exists because it is free and it stops
+//      an honest-but-stubborn worker before a third panel is paid for, rather
+//      than up to one supervisor poll later.
+//
+// The local ledger is ACTIVE ONLY when AUTOBONGOS_GRADE_LEDGER is set, which only
+// the supervisor does. A human running ship.js by hand is never capped.
+//
+// A GRADER OUTAGE DOES NOT COUNT. `signals.panel_outcome === 'unavailable'` means
+// the panel could not run (#943) — no findings, nothing to fix, not a quality
+// verdict. Counting it would hand a task to the owner because the grader was down.
+
+const fs = require('fs');
+const path = require('path');
+
+const LEDGER_ENV = 'AUTOBONGOS_GRADE_LEDGER';
+// The first grade + ONE re-grade. Not configurable on purpose: a cap the worker
+// could raise through env would be a cap it could talk its way past.
+const GRADE_CAP = 2;
+// ship.js's exit code for a capped run. Distinct from 1 (generic) and 2 (usage /
+// refused input) so a supervisor or a test can tell the cap from any other stop.
+const REFUSED_EXIT = 6;
+
+function ledgerPathFromEnv(env = process.env) {
+  const p = env[LEDGER_ENV];
+  return p && String(p).trim() ? String(p).trim() : null;
+}
+
+// isOutage — the grader never ran. Mirrors the #943 test the ship card and
+// ship-grade-steps use (signals.panel_outcome === 'unavailable').
+function isOutage(grade) {
+  return !!(grade && grade.signals && grade.signals.panel_outcome === 'unavailable');
+}
+
+// readLedger — every row, oldest first. A missing or unreadable file is an empty
+// ledger; a malformed line is skipped rather than fatal.
+function readLedger(file) {
+  if (!file) return [];
+  let raw = '';
+  try { raw = fs.readFileSync(file, 'utf8'); } catch (_) { return []; }
+  const rows = [];
+  for (const line of raw.split(/\r?\n/)) {
+    if (!line.trim()) continue;
+    try { rows.push(JSON.parse(line)); } catch (_) { /* skip a torn line */ }
+  }
+  return rows;
+}
+
+// gradeCapState — pure over ledger rows: how many GRADED rounds (outages
+// excluded) this task has had in the run, and whether the cap is reached.
+function gradeCapState(rows, taskId) {
+  const mine = (rows || []).filter((r) => r && String(r.task_id) === String(taskId));
+  const graded = mine.filter((r) => !r.outage);
+  const fails = graded.filter((r) => r.passed !== true);
+  const passed = graded.some((r) => r.passed === true);
+  return {
+    graded: graded.length,
+    fails: fails.length,
+    outages: mine.length - graded.length,
+    passed,
+    capped: graded.length >= GRADE_CAP,
+    // The run should be handed to the owner: the cap is reached and none passed.
+    exhausted: !passed && fails.length >= GRADE_CAP,
+  };
+}
+
+// checkGradeCap — may ship.js start a grade for this task? `{ ok: true }` when no
+// ledger is in play (a human ship) or the cap has room.
+function checkGradeCap({ taskId, env = process.env } = {}) {
+  const file = ledgerPathFromEnv(env);
+  if (!file) return { ok: true, active: false };
+  const state = gradeCapState(readLedger(file), taskId);
+  // `exhausted`, not `capped`: a task whose second round PASSED still needs
+  // ship.js to resume its merge leg, and that must not be refused.
+  if (!state.exhausted) return { ok: true, active: true, state };
+  return {
+    ok: false, active: true, state,
+    lines: [
+      `Ship refused: task ${taskId} has already been graded ${state.graded} time(s) in this autonomous run — the cap is the first grade plus ONE re-grade (task 1004536).`,
+      'A task that fails the grade twice goes to the owner instead of being retried.',
+      'Stop now and return cannot_complete, quoting the grader\'s findings — the supervisor files the blocker.',
+      '(A GRADER UNAVAILABLE outcome is an outage and was not counted.)',
+    ],
+  };
+}
+
+// recordGradeOutcome — append one graded round. Best-effort: a write failure
+// must never fail the ship that just graded.
+function recordGradeOutcome({ taskId, grade, env = process.env, now = () => new Date().toISOString() } = {}) {
+  const file = ledgerPathFromEnv(env);
+  if (!file || !grade) return false;
+  const row = {
+    task_id: Number(taskId),
+    at: now(),
+    passed: grade.passed === true,
+    outage: isOutage(grade),
+    score: grade.score ?? null,
+  };
+  try {
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    fs.appendFileSync(file, `${JSON.stringify(row)}\n`);
+    return true;
+  } catch (_) { return false; }
+}
+
+// ── the server's count (the boundary) ───────────────────────────────────────────
+//
+// `GET /tasks/:id?include=grade,grade_attempts` serves each recorded round as
+// { attempted_at, passed, workers: [{ kind, verdict, error, severities }] }.
+// The grader's own outage test (#943, grader.js) is "every GATING worker failed
+// to run"; the Narc is advisory (#481), so it is left out of that test the same
+// way. A round with no gating workers listed is not called an outage — it is
+// counted, because an unknown shape must not silently buy another round.
+const ADVISORY_KINDS = new Set(['narc']);
+function attemptIsOutage(attempt) {
+  const ws = Array.isArray(attempt && attempt.workers) ? attempt.workers : [];
+  const gating = ws.filter((w) => w && !ADVISORY_KINDS.has(w.kind));
+  return gating.length > 0 && gating.every((w) => w.error != null && w.error !== '');
+}
+
+// newestAttemptAt — the baseline, read BEFORE the worker starts. Rounds are
+// counted by being newer than this server timestamp, so the supervisor's own
+// clock never enters the comparison.
+function newestAttemptAt(attempts) {
+  let newest = null;
+  for (const a of attempts || []) {
+    const t = Date.parse(a && a.attempted_at);
+    if (Number.isFinite(t) && (newest === null || t > newest)) newest = t;
+  }
+  return newest;
+}
+
+// roundsFromAttempts — the server's rounds after the baseline, in ledger-row
+// shape so gradeCapState reads both sources the same way.
+function roundsFromAttempts(attempts, taskId, afterMs = null) {
+  const out = [];
+  for (const a of attempts || []) {
+    const t = Date.parse(a && a.attempted_at);
+    if (!Number.isFinite(t) || (afterMs !== null && t <= afterMs)) continue;
+    out.push({ task_id: Number(taskId), at: a.attempted_at, passed: a.passed === true, outage: attemptIsOutage(a) });
+  }
+  return out;
+}
+
+// readServerAttempts — the task's recorded rounds, or null when unreadable. Null
+// is "unknown", never "zero": the caller falls back to the local ledger.
+async function readServerAttempts(api, taskId) {
+  try {
+    if (!api || !api.tasks || typeof api.tasks.getTasksId !== 'function') return null;
+    const r = await api.tasks.getTasksId({ id: Number(taskId), query: { include: 'grade,grade_attempts' } });
+    if (!r || !r.ok || !r.data) return null;
+    const grade = r.data.grade;
+    if (!grade) return [];                       // never graded: a real zero
+    return Array.isArray(grade.attempts) ? grade.attempts : null;
+  } catch (_) { return null; }
+}
+
+module.exports = {
+  LEDGER_ENV, GRADE_CAP, REFUSED_EXIT,
+  ledgerPathFromEnv, isOutage, readLedger, gradeCapState, checkGradeCap, recordGradeOutcome,
+  attemptIsOutage, newestAttemptAt, roundsFromAttempts, readServerAttempts,
+};