@bongos/core 1.21.4 → 1.21.6

package/src/bongos/auth-admission.js

@@ -132,6 +132,69 @@ async function recentShipsForRollup(builderId) {
   }));
 }
 
+// Each craft by its own work, for the hub's profile tiles (task 1004440 /
+// WA6.RP10, goal 1000095). Until now the rollup said "Roles" from the declared
+// preference alone and counted only shipped tasks, so an artist or an ideator who
+// had done real work read on the hub as an engineer with nothing shipped.
+//
+// A craft is EARNED when this builder holds credits in it — the same rule the
+// local profile uses to show a role (src/bongos/role-stats.js, task 1004433),
+// read through the same ports. This is a kernel file, so it reads those ports
+// by key rather than importing role-stats (ADR 0091 §1). For each earned craft it
+// sends that craft's headline counts; an unearned craft sends nothing at all.
+// Counts and sums only: no idea title, no page wording, no task list.
+//
+// `disciplines` becomes the earned crafts, in the builder's preferred order;
+// with nothing earned (or no economy module to ask) it falls back to the declared
+// preference, exactly as before. A port that cannot be asked leaves its numbers
+// null ("could not ask"), never 0. Never throws: a failed read drops its craft's
+// numbers, not the report.
+const ROLLUP_CRAFTS = Object.freeze(['engineer', 'artist', 'ideator']);
+const countOrNull = (v) => (Number.isInteger(v) && v >= 0 ? v : null);
+async function readCraftRollup(builderId, { shipped = 0, preferred = [] } = {}) {
+  const fallback = { counts: null, disciplines: Array.isArray(preferred) ? preferred : [] };
+  try {
+    const reward = seams.resolveOptional('reward');
+    const byCraftMap = reward && typeof reward.creditsByCraft === 'function'
+      ? await reward.creditsByCraft([builderId]) : null;
+    const byCraft = byCraftMap ? byCraftMap.get(String(builderId)) : null;
+    if (!byCraft) return fallback;
+    const prefCrafts = fallback.disciplines
+      .map((d) => (typeof reward.craftForPreference === 'function' ? reward.craftForPreference(d) : d))
+      .filter((c) => ROLLUP_CRAFTS.includes(c));
+    const earned = [...prefCrafts, ...ROLLUP_CRAFTS]
+      .filter((c, i, a) => a.indexOf(c) === i && Number(byCraft[c]) > 0);
+    if (!earned.length) return fallback;
+    const ask = async (port) => {
+      const fn = seams.resolveOptional(port);
+      if (typeof fn !== 'function') return null;
+      try { return (await fn(builderId)) || null; } catch { return null; }
+    };
+    const [artist, ideator] = await Promise.all([
+      earned.includes('artist') ? ask('copy-desk.artistStats') : null,
+      earned.includes('ideator') ? ask('ideas.ideatorStats') : null,
+    ]);
+    const credits = (c) => countOrNull(Math.round(Number(byCraft[c])));
+    const counts = {};
+    if (earned.includes('engineer')) counts.engineer = { shipped: countOrNull(shipped), credits: credits('engineer') };
+    if (earned.includes('artist')) {
+      counts.artist = { pages_approved: countOrNull(artist && artist.pages_approved), credits: credits('artist') };
+    }
+    if (earned.includes('ideator')) {
+      counts.ideator = {
+        filed: countOrNull(ideator && ideator.filed),
+        full_ideas: countOrNull(ideator && ideator.full_ideas),
+        ratified: countOrNull(ideator && ideator.ratified),
+        credits: credits('ideator'),
+      };
+    }
+    return { counts, disciplines: earned };
+  } catch (err) {
+    log.info('[auth] craft rollup read failed (non-blocking):', err.message);
+    return fallback;
+  }
+}
+
 // Best-effort cross-project activity rollup to the hub (ADR 0141 §4): report this
 // builder's descriptive talent snapshot (credits, ships, karma, rank, disciplines,
 // and since task 1002803 their last few shipped works) for the cross-project
@@ -162,26 +225,45 @@ async function reportActivityRollup({ builderId, githubId = null }) {
     const row = b.rows[0];
     const ghId = githubId ?? row.github_id;
     if (!/^\d+$/.test(String(ghId ?? ''))) return;
-    const shipped = await pool.query('SELECT count(*)::int AS n FROM tasks WHERE shipped_by = $1', [builderId]);
+    // SHIPPED works only (task 1004440): a count with no status filter also
+    // counted work that was handed back after shipping. The same predicate as the
+    // instance's own profile (lifecycle countShippedTasksForBuilder).
+    const shipped = await pool.query(
+      `SELECT count(*)::int AS n FROM tasks WHERE shipped_by = $1 AND status = 'shipped'`,
+      [builderId],
+    );
+    const shippedCount = shipped.rows[0] ? shipped.rows[0].n : 0;
     const recentShips = await recentShipsForRollup(builderId);
-    await fetch(`${idp.origin}/api/bongos/sso/activity/rollup`, {
+    const craft = await readCraftRollup(builderId, { shipped: shippedCount, preferred: row.preferred_disciplines });
+    const body = {
+      client_id: idp.clientId,
+      client_secret: idp.clientSecret,
+      github_id: ghId,
+      credits: Number(row.total_credits) || 0,
+      tasks_shipped: shippedCount,
+      karma: Number(row.karma) || 0,
+      rank: row.rank || null,
+      disciplines: craft.disciplines,
+      recent_ships: recentShips,
+    };
+    if (craft.counts) body.crafts = craft.counts;
+    const send = (payload) => fetch(`${idp.origin}/api/bongos/sso/activity/rollup`, {
       method: 'POST',
       headers: {
         'Content-Type': 'application/json', Accept: 'application/json', 'User-Agent': userAgent(),
         'Bongos-Report-As-Of': asOf,
       },
-      body: JSON.stringify({
-        client_id: idp.clientId,
-        client_secret: idp.clientSecret,
-        github_id: ghId,
-        credits: Number(row.total_credits) || 0,
-        tasks_shipped: shipped.rows[0] ? shipped.rows[0].n : 0,
-        karma: Number(row.karma) || 0,
-        rank: row.rank || null,
-        disciplines: Array.isArray(row.preferred_disciplines) ? row.preferred_disciplines : [],
-        recent_ships: recentShips,
-      }),
+      body: JSON.stringify(payload),
     });
+    const res = await send(body);
+    // A hub older than `crafts` validates the body strictly and refuses the
+    // unknown field with a 400, which would lose the whole report. So a refused
+    // report that carried crafts goes again once without them: the totals still
+    // land, and the craft numbers arrive once that hub upgrades.
+    if (body.crafts && res && res.status === 400) {
+      const { crafts: _unsent, ...older } = body;
+      await send(older);
+    }
   } catch (err) {
     log.info('[auth] hub activity rollup failed (non-blocking):', err.message);
   }

package/src/bongos/db-kernel.js

@@ -55,7 +55,7 @@ async function getBuilderById(id) {
   // AFTER INSERT triggers on credit_log + karma_log respectively.
   const { rows } = await pool.query(
     `SELECT id, github_id, github_login, display_name, avatar_url, total_credits, karma, created_at, rank,
-            status, deactivated_at, reactivated_at, deactivated_reason, preferred_disciplines, system_role,
+            status, deactivated_at, reactivated_at, deactivated_reason, preferred_disciplines, main_discipline, system_role,
             anthropic_email, anthropic_user_id, monthly_budget_usd
        FROM builders WHERE id = $1`,
     [id]

package/src/bongos/module-rechecks.js

@@ -0,0 +1,77 @@
+'use strict';
+
+// src/bongos/module-rechecks.js — the module versions that are waiting on, or
+// going through, a RE-CHECK, for the governor's docket (task 1004523, goal
+// 1000125; collector: modules/government/docket.js, decision: ADR 0362).
+//
+// WHY. The Governor City's Release building carries "1 flagged for a re-check".
+// The assessment ledger (core_265 `module_assessment_signals`, ADR 0343) already
+// records it: each version's parts are measured as rows, the CURRENT row per
+// (version, part) is the newest, and two current states mean a governor has a
+// re-check to look at — a Security gate that FAILED (the version should not be
+// offered until someone asks for it to be checked again; asking is
+// POST /store/modules/:key/versions/:version/reassess, `module.assessment.rerun`)
+// and a part still PENDING (a re-check is running). Nothing read this ledger for
+// that question before; this is the one query, served only to the docket.
+//
+// Core, not a module: the store and its assessment tables are core
+// (src/bongos/module-store.js), so the contribution is registered from the core
+// modules route factory on the kernel seam.
+
+const RECHECK_LIMIT = 50;
+
+// Current signal per (version, part), then the versions with a failed Security
+// gate or any part still pending. Bounded. The DISTINCT ON is served by core_265's
+// idx_module_assessment_signals_current (version_id, part, measured_at DESC, id
+// DESC) — the same column order as the ORDER BY, so it walks the index rather than
+// sorting the table (pinned in tests/governor_docket.mjs). The table grows with
+// module publishes and re-checks, not with builders or requests.
+async function listModuleRechecks({ limit = RECHECK_LIMIT, db = null } = {}) {
+  const exec = db || require('./pool').pool; // lazy, so a DB-free test can load this file
+  const { rows } = await exec.query(
+    `WITH current AS (
+       SELECT DISTINCT ON (s.version_id, s.part)
+              s.version_id, s.part, s.outcome, s.reason, s.measured_at
+         FROM module_assessment_signals s
+        ORDER BY s.version_id, s.part, s.measured_at DESC, s.id DESC
+     )
+     SELECT v.id AS version_id, v.module_key, v.version,
+            bool_or(c.part = 'security' AND c.outcome = 'failed') AS security_failed,
+            array_agg(c.part ORDER BY c.part) FILTER (WHERE c.outcome = 'pending') AS pending_parts,
+            max(c.measured_at) AS measured_at
+       FROM current c
+       JOIN store_module_versions v ON v.id = c.version_id
+      GROUP BY v.id, v.module_key, v.version
+     HAVING bool_or(c.part = 'security' AND c.outcome = 'failed')
+         OR bool_or(c.outcome = 'pending')
+      ORDER BY max(c.measured_at) DESC
+      LIMIT $1`,
+    [limit],
+  );
+  return rows;
+}
+
+// One version as a docket matter. Pure. A failed gate needs a governor who may
+// ask for a re-check; a pending part is a re-check already moving.
+function moduleRecheckMatter(r, mayRerun) {
+  const failed = r.security_failed === true;
+  const pending = Array.isArray(r.pending_parts) ? r.pending_parts.filter(Boolean) : [];
+  return {
+    id: r.version_id,
+    rule: 'rule',
+    state: failed ? (mayRerun ? 'needs' : 'moving') : 'moving',
+    title: failed
+      ? `${r.module_key} ${r.version} failed its security check`
+      : `${r.module_key} ${r.version} is being checked again`,
+    short: failed ? `re-check ${r.module_key}` : `checking ${r.module_key}`,
+    where: failed ? 'release · modules · flagged for a re-check' : `release · modules · ${pending.join(', ') || 'a part'} pending`,
+    opened_at: r.measured_at,
+    deadline: null,
+    proposer: null,
+    tally: null,
+    href: '/modules',
+    ref: { type: 'module_version', id: r.version_id },
+  };
+}
+
+module.exports = { listModuleRechecks, moduleRecheckMatter, RECHECK_LIMIT };

package/src/bongos/route-rank-check.js

@@ -278,6 +278,9 @@ const GOVERNMENT_PINS = {
   // task 1004427: the genesis charter + legislation choice — an amendment by
   // another door, so the same atom as proposing one.
   'POST /government/board/charter': 'perm:board.item.open',
+  // task 1004523: the governor's docket — every matter awaiting a governor. The
+  // coarse gate is the room's; each source inside is scoped to its own atom.
+  'GET /government/docket': 'perm:board.vote.cast',
 };
 
 // Module-scoped privileged-rank pins: a privileged route that lives in a FEATURE

package/src/bongos/routes/core-update.js

@@ -90,12 +90,72 @@ function upgradesLimit(raw) {
   return Math.min(100, Math.max(1, n));
 }
 
+// The governor's docket (task 1004523, modules/government/docket.js): a newer
+// core stands at Release as a matter — "taking it is your call". Contributed on
+// the kernel seam because the read is core's (a module cannot require it), and
+// shown only to a viewer holding `core.pin.move`, GET /core-update's own atom (the
+// running version is a vulnerability-window disclosure, ADR 0043). Same
+// readCoreUpdate the banner uses: TTL-cached, never throws; `no_answer` from the
+// registry reads as unavailable, never as "up to date".
+function coreUpdateDocketMatters(update) {
+  if (!update || update.reading !== 'ok') throw new Error('core_update_no_answer');
+  if (!update.behind) return [];
+  return [{
+    id: String(update.latest),
+    rule: 'decide',
+    state: 'needs',
+    title: `Take core ${update.latest} (running ${update.running})`,
+    short: `core ${update.latest}`,
+    where: 'release · core update',
+    opened_at: null,
+    deadline: null,
+    proposer: null,
+    tally: null,
+    href: '/settings#software-update',
+    ref: { type: 'core_version', id: String(update.latest) },
+  }];
+}
+// The running core, or null when it cannot be named. Read lazily and fail-soft,
+// the same way the two routes below read it per request.
+function runningCoreVersion() {
+  try { return require('../../module-api').CORE_VERSION; } catch { return null; }
+}
+function contributeCoreUpdateToDocket(read = readCoreUpdate) {
+  seams.contribute('governor.docket', {
+    source: 'core_update',
+    building: 'release',
+    gate: { permission: 'core.pin.move' },
+    read: async () => coreUpdateDocketMatters(await read({ running: runningCoreVersion() })),
+  });
+}
+
+// This hall's own update rule, from the provisioning module when it runs (task 1004535):
+// the rule set on /deploy, which the runner and the sweep already follow (ADR 0357: the
+// /deploy row beats the sweep's roster file, which lives in the box's own checkout and is
+// not this server's to read). No module, no row, or a failed read → null, and the readers
+// fall back to the platform default exactly as before.
+function storedSelfChannel() {
+  const read = seams.resolveOptional('provisioning.selfUpdateChannel');
+  return typeof read === 'function' ? read() : null;
+}
+
+// { channel, source } — WHICH rule the answer was computed under, so the page can say so:
+// 'deploy' (the project's stored rule) or 'default' (none could be read). Never throws.
+async function resolveChannel(selfChannel) {
+  let channel = null;
+  try { channel = (await selfChannel()) || null; } catch { channel = null; }
+  return { channel, source: channel ? 'deploy' : 'default' };
+}
+
 function buildCoreUpdateRouter({
+  coreUpdate = readCoreUpdate,
+  selfChannel = storedSelfChannel,
   upgrades = readCoreUpgrades,
   softwareUpdate = readSoftwareUpdate,
   canUpdate = holdsCorePin,
   doorInputs = () => ({ provisioning: provisioningEnabled(), idp: safeIdpConfig() }),
 } = {}) {
+  contributeCoreUpdateToDocket();
   const router = express.Router();
 
   router.get(
@@ -115,7 +175,8 @@ function buildCoreUpdateRouter({
       try { running = require('../../module-api').CORE_VERSION; } catch { /* version unknown */ }
       // No `deploy_url` any more (task 1004296): the banner on a hall without a door of its
       // own links to Settings → Software update, and the hand-off lives on GET /software-update.
-      res.json({ ok: true, update: await readCoreUpdate({ running }) });
+      const { channel, source } = await resolveChannel(selfChannel);
+      res.json({ ok: true, update: { ...(await coreUpdate({ running, channel })), channel_source: source } });
     }, { errorCode: 'core_update_failed', message: false }),
   );
 
@@ -146,7 +207,11 @@ function buildCoreUpdateRouter({
     asyncHandler('GET /software-update', async (req, res) => {
       let running = null;
       try { running = require('../../module-api').CORE_VERSION; } catch { /* version unknown */ }
-      const [update, can] = await Promise.all([softwareUpdate({ running }), canUpdate(req)]);
+      // canUpdate does not depend on the rule, so it runs beside the rule read, not after it.
+      const [update, can] = await Promise.all([
+        resolveChannel(selfChannel).then(async ({ channel, source }) => ({ ...(await softwareUpdate({ running, channel })), channel_source: source })),
+        canUpdate(req),
+      ]);
       res.json({ ok: true, update, door: updateDoor(doorInputs()), can_update: can === true });
     }, { errorCode: 'software_update_failed', message: false }),
   );
@@ -156,3 +221,4 @@ function buildCoreUpdateRouter({
 
 module.exports = buildCoreUpdateRouter;
 module.exports.hubDeployUrl = hubDeployUrl;
+module.exports.coreUpdateDocketMatters = coreUpdateDocketMatters;

package/src/bongos/routes/modules.js

@@ -77,6 +77,8 @@ const modulesLib = require('../../modules');
 // server process.
 const moduleCli = require('../../../scripts/gds/module');
 const moduleSubmissions = require('../module-submissions');
+const moduleRechecks = require('../module-rechecks');
+const seams = require('../../module-seams');
 const moduleArtifact = require('../../../scripts/gds/module-artifact');
 const moduleAssessVersion = require('../../../scripts/gds/module-assess-version');
 const { checkEntitlement, listEntitlements, grantEntitlement, recordAcquired } = require('../module-entitlements');
@@ -160,7 +162,22 @@ const HOWTO_CACHE_MAX = 200;
 // list bounded.
 const STORE_LATEST_MAX_KEYS = 200;
 
+// The governor's docket (task 1004523, ADR 0362): module versions flagged for, or
+// going through, a re-check stand at Release. Shown only to a viewer holding
+// `module.assessment.rerun`, the atom of the reassess route below, the one act
+// a governor can take on one (there is no assessment read route to borrow from).
+function contributeModuleRechecksToDocket() {
+  seams.contribute('governor.docket', {
+    source: 'module_rechecks',
+    building: 'release',
+    gate: { permission: 'module.assessment.rerun' },
+    read: async (ctx) => (await moduleRechecks.listModuleRechecks())
+      .map((r) => moduleRechecks.moduleRecheckMatter(r, ctx.has('module.assessment.rerun'))),
+  });
+}
+
 module.exports = function buildModulesRouter() {
+  contributeModuleRechecksToDocket();
   const router = express.Router();
   // Checked how-tos by "key@version:tarball_sha256". Per router, so a test's fresh
   // router starts empty.

package/src/bongos/serve-internal.js

@@ -941,6 +941,16 @@ function mountInternalSurfaces(app) {
   // statically, and a comment in that gap drops the regex out of the map, which
   // makes the page test as UNGATED while looking gated here. Prose goes above.
   const BOARD_ROOM_PAGE_RE = /^\/builders\/board-room(?:\.html)?\/?$/;
+  // /city — the Governor City's home (task 1004524, goal 1000125). Gated on the
+  // `board.vote.cast` atom, like the Board Room, because that is the atom its one
+  // governed read (GET /government/docket) checks: the page's reach equals the
+  // right to read what it draws, so no holder is refused a city they could read
+  // and no one else is served its shell. Its two goal reads are requireBuilder,
+  // a wider floor.
+  //
+  // NB as at PROJECT_SETTINGS_PAGE_RE: nothing between the `=` and the literal
+  // (tests/hall_page_gate_map.mjs parses this file statically). Prose goes above.
+  const CITY_PAGE_RE = /^\/builders\/city(?:\.html)?\/?$/;
   // /deploy — the owner's deploy door (task 1003159, ADR 0293). Gated on the
   // `core.pin.move` atom, the same key its preview and its move both check, so the
   // shell's reach equals the right to press the button. Archon-floor and system:true,
@@ -1023,6 +1033,10 @@ function mountInternalSurfaces(app) {
     if (BOARD_ROOM_PAGE_RE.test(norm)) {
       return gdsAuth.requireBoardVotePage(req, res, next);
     }
+    // task 1004524: the Governor City, on the docket's own atom (see CITY_PAGE_RE).
+    if (CITY_PAGE_RE.test(norm)) {
+      return gdsAuth.requireBoardVotePage(req, res, next);
+    }
     // ADR 0293: the deploy door, on the same atom its two routes check.
     if (DEPLOY_PAGE_RE.test(norm)) {
       return gdsAuth.requireCorePinPage(req, res, next);

package/src/bongos/software-update.js

@@ -18,8 +18,9 @@
 //
 // THE CHANNEL RULE IS NOT RESTATED HERE, as in core-update.js: `resolveChannelTarget` is the
 // upgrade runner's own function, so this never offers a version the runner would refuse.
-// No channel is passed, exactly as the banner passes none: an instance does not store its
-// own channel, and the runner's default is what it would get.
+// The channel is the project's own update rule when the route can read it (the rule set on
+// /deploy, via the provisioning.selfUpdateChannel seam — task 1004535), else the runner's
+// default. The banner (core-update.js) is handed the same rule, so the two cannot disagree.
 //
 // A READING, NEVER A GUESS. `reading` is 'ok' only when the registry answered; "up to date"
 // is `offered: null` on an ok reading and nothing else. Notes that could not be read say so,

package/src/module-api.js

@@ -75,7 +75,7 @@ const { responsibilityFor, ROLE_RESPONSIBILITIES } = require('./role-responsibil
 // MAJOR (see allowBoxScope below): passes the request through untouched.
 function deprecatedNoopMiddleware(_req, _res, next) { next(); }
 
-const CORE_VERSION = '1.21.4'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
+const CORE_VERSION = '1.21.6'; // 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('discord'); log.info('mounted');

package/tests/activity_rollup_order_db.mjs

@@ -74,7 +74,9 @@ const same = (actual, expected, msg) => { assert.deepEqual(actual, expected, msg
 
 try {
   for (const f of ['platform_identity_005_builder_activity.sql', 'platform_identity_012_recent_ships.sql',
-    'platform_identity_022_activity_snapshots.sql', 'platform_identity_026_activity_reported_as_of.sql']) {
+    'platform_identity_022_activity_snapshots.sql', 'platform_identity_026_activity_reported_as_of.sql',
+    // upsertActivity also writes crafts (029, task 1004440): 42703 without it.
+    'platform_identity_029_activity_crafts.sql']) {
     await q(migrationSql(f));
   }
   await q(migrationSql('platform_identity_026_activity_reported_as_of.sql')); // idempotent: replays cleanly

package/tests/activity_snapshots_db.mjs

@@ -99,6 +99,8 @@ try {
   await q(migrationSql('platform_identity_022_activity_snapshots.sql'));
   // upsertActivity also writes reported_as_of (task 1004268) — same reason as 012 above.
   await q(migrationSql('platform_identity_026_activity_reported_as_of.sql'));
+  // ...and each craft's counts (029, task 1004440), same reason again.
+  await q(migrationSql('platform_identity_029_activity_crafts.sql'));
   await cleanup();
 
   // 1 — the writer snapshots the LIVE row, and only when it changed.

package/tests/autobongos_grade_cap.mjs

@@ -0,0 +1,125 @@
+// tests/autobongos_grade_cap.mjs — the grade cap for one autonomous run (task 1004536).
+//
+// Owner rule, 2026-10-02: a task that fails the grade twice goes to the owner
+// instead of being retried — the first grade plus at most ONE re-grade per
+// worker run. The worker prompt already asked for this and was ignored (task
+// 1004512 spent $63.81 over three rounds), so the cap is enforced in ship.js,
+// where the panel spend happens, and read back by the supervisor.
+
+import assert from 'node:assert/strict';
+import { test } from 'node:test';
+import { createRequire } from 'node:module';
+import { spawnSync } from 'node:child_process';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const require = createRequire(import.meta.url);
+const cap = require('../scripts/gds/autobongos-grade-cap.js');
+const REPO = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+
+const fail = { passed: false, score: 5.6, signals: { panel_outcome: 'fail' } };
+const pass = { passed: true, score: 8.1, signals: { panel_outcome: 'pass' } };
+const outage = { passed: false, score: 0, signals: { panel_outcome: 'unavailable' } };
+
+function tmpLedger() {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'grade-cap-'));
+  return path.join(dir, 'run.jsonl');
+}
+function ledgerWith(grades, taskId = 4242) {
+  const file = tmpLedger();
+  const env = { [cap.LEDGER_ENV]: file };
+  for (const g of grades) assert.equal(cap.recordGradeOutcome({ taskId, grade: g, env }), true);
+  return { file, env };
+}
+
+test('the cap is the first grade plus ONE re-grade', () => {
+  assert.equal(cap.GRADE_CAP, 2);
+});
+
+test('one failed grade leaves room for exactly one re-grade', () => {
+  const { env } = ledgerWith([fail]);
+  assert.equal(cap.checkGradeCap({ taskId: 4242, env }).ok, true);
+});
+
+test('a third grade attempt after two FAILs is refused, and says to hand it to the owner', () => {
+  const { env } = ledgerWith([fail, fail]);
+  const r = cap.checkGradeCap({ taskId: 4242, env });
+  assert.equal(r.ok, false);
+  assert.equal(r.state.exhausted, true);
+  assert.match(r.lines.join('\n'), /cannot_complete/);
+});
+
+test('a grader-UNAVAILABLE outcome does not count toward the two', () => {
+  const { env, file } = ledgerWith([fail, outage, outage]);
+  const r = cap.checkGradeCap({ taskId: 4242, env });
+  assert.equal(r.ok, true, 'an outage is not a quality verdict — the panel never ran');
+  const s = cap.gradeCapState(cap.readLedger(file), 4242);
+  assert.equal(s.graded, 1);
+  assert.equal(s.outages, 2);
+  assert.equal(s.exhausted, false);
+});
+
+test('a second round that PASSED is not refused — its merge leg still has to run', () => {
+  const { env } = ledgerWith([fail, pass]);
+  assert.equal(cap.checkGradeCap({ taskId: 4242, env }).ok, true);
+});
+
+test('rounds are counted per task, and a human ship (no ledger) is never capped', () => {
+  const { env } = ledgerWith([fail, fail], 1111);
+  assert.equal(cap.checkGradeCap({ taskId: 4242, env }).ok, true, 'another task\'s fails are not this one\'s');
+  assert.deepEqual(cap.checkGradeCap({ taskId: 4242, env: {} }), { ok: true, active: false });
+  assert.equal(cap.recordGradeOutcome({ taskId: 4242, grade: fail, env: {} }), false, 'nothing is written without a ledger');
+});
+
+test('a torn or missing ledger reads as empty rather than throwing', () => {
+  assert.deepEqual(cap.readLedger(path.join(os.tmpdir(), 'no-such-ledger-1004536.jsonl')), []);
+  const file = tmpLedger();
+  fs.writeFileSync(file, '{"task_id":4242,"passed":false,"outage":false}\n{"task_id":42');
+  assert.equal(cap.readLedger(file).length, 1);
+});
+
+test('server attempts: an outage is every GATING worker erroring; the advisory narc does not decide it', () => {
+  const w = (kind, error) => ({ kind, verdict: error ? null : 'fail', error, severities: [] });
+  assert.equal(cap.attemptIsOutage({ workers: [w('narc', null), w('quality', 'X'), w('hacker', 'X'), w('efficiency', 'X')] }), true);
+  assert.equal(cap.attemptIsOutage({ workers: [w('narc', 'X'), w('quality', null), w('hacker', 'X'), w('efficiency', 'X')] }), false, 'one gating worker ran: a real verdict');
+  assert.equal(cap.attemptIsOutage({ workers: [] }), false, 'an unknown shape is counted, never a free round');
+});
+
+test('server attempts: only rounds newer than the pre-run baseline belong to this run', () => {
+  const attempts = [
+    { attempted_at: '2026-10-01T00:00:00Z', passed: false, workers: [] },
+    { attempted_at: '2026-10-02T00:00:00Z', passed: false, workers: [] },
+  ];
+  const baseline = cap.newestAttemptAt(attempts.slice(0, 1));
+  const rows = cap.roundsFromAttempts(attempts, 4242, baseline);
+  assert.equal(rows.length, 1);
+  assert.equal(cap.newestAttemptAt([]), null);
+  assert.equal(cap.roundsFromAttempts(attempts, 4242, null).length, 2);
+});
+
+test('readServerAttempts: unreadable is null (unknown), never graded is [] (a real zero)', async () => {
+  assert.equal(await cap.readServerAttempts({}, 4242), null);
+  assert.equal(await cap.readServerAttempts({ tasks: { getTasksId: async () => ({ ok: false, status: 502 }) } }, 4242), null);
+  assert.deepEqual(await cap.readServerAttempts({ tasks: { getTasksId: async () => ({ ok: true, data: { task: {}, grade: null } }) } }, 4242), []);
+});
+
+// The early refusal (the courtesy half): ship.js, with any flag. It must refuse BEFORE a
+// session is loaded or a panel started — the panel spend is what the cap saves.
+for (const flags of [['--regrade'], [], ['--skip-grade']]) {
+  test(`ship.js ${flags.join(' ') || '(plain re-ship)'} refuses a third grade in an autonomous run`, () => {
+    const { env } = ledgerWith([fail, fail]);
+    const home = fs.mkdtempSync(path.join(os.tmpdir(), 'grade-cap-home-'));
+    const res = spawnSync(process.execPath, [path.join(REPO, 'scripts', 'gds', 'ship.js'), '4242', ...flags], {
+      cwd: REPO,
+      encoding: 'utf8',
+      timeout: 30000,
+      // No session and a dead API base: if the refusal did NOT fire first, the
+      // run fails some other way and the assertions below say so.
+      env: { ...process.env, ...env, HOME: home, USERPROFILE: home, XDG_CONFIG_HOME: home, BONGOS_API_BASE: 'http://127.0.0.1:9' },
+    });
+    assert.equal(res.status, cap.REFUSED_EXIT, `expected the cap's exit code; stderr:\n${res.stderr}`);
+    assert.match(res.stderr, /graded 2 time\(s\) in this autonomous run/);
+  });
+}