@bongos/core 1.19.1033 → 1.19.1035

package/docs/recipes/packaging-the-core.md

@@ -46,7 +46,7 @@ If the no-leak gate fails, it names the file + the residual literal. Fix the red
 
 Two standing gates keep "a published core boots clean from a bare install" honest (task [#1002221](https://example.com/builders#/task/1002221), audit H1/H2):
 
-- **`node scripts/gds/run-unit-tests.js --integration`** — the integration-smoke gate. Runs the heavier integration set (longer per-test budget), including [`tests/consumer_layout_boot.mjs`](../../tests/consumer_layout_boot.mjs), which packages the core, `npm install`s the `.tgz`, and boots `/healthz` from the real consumer layout. Run it per release / on a schedule in an env that provides the services (network, and — for the deeper DB leg tracked as a follow-up — Postgres). The default `run-unit-tests.js` (no flag) stays the fast DB-free unit gate and *excludes* this set.
+- **`node scripts/gds/run-unit-tests.js --integration`** — the integration-smoke gate. Runs the heavier integration set (longer per-test budget), including [`tests/consumer_layout_boot.mjs`](../../tests/consumer_layout_boot.mjs), which packages the core, `npm install`s the `.tgz`, and boots `/healthz` from the real consumer layout. Since task 1002863 it also carries the database half: it installs the unpacked package from its **own shipped lockfile** with `npm ci`, runs `npm run migrate` from the consumer onto a brand-new **empty** database (and onto a second one with every optional module switched on), then boots the installed server against the first and reads a sentinel row back through `GET /api/bongos/public/versions`. It creates and drops those databases itself, so it needs a Postgres whose role may `CREATE DATABASE`; without one it prints SKIP lines, except under `CI=true`, where a missing Postgres fails the run. The `integration` job of [`.github/workflows/integration.yml`](../../.github/workflows/integration.yml) runs this set on every push to `main` (not per PR — a cost decision recorded in that file). The default `run-unit-tests.js` (no flag) stays the fast DB-free unit gate and *excludes* this set.
 - **[`tests/pruned_lockfile_integrity.mjs`](../../tests/pruned_lockfile_integrity.mjs)** — a network-free unit guard (runs in the default gate every PR) that rebuilds the shipped pruned lockfile and asserts every registry package keeps a **well-formed, verbatim `integrity` hash**. This is the exact R88 regression (redaction once blanked those base64 hashes → `npm ci` could no longer verify) caught before a consumer's install ever fails.
 
 ## Consume + pin it (the R85 side)

package/modules/autonomy/cadence.js

@@ -50,6 +50,30 @@ const CLASSES = ['progress', 'quiet', 'stopped', 'transient', 'systemic', 'unwor
 // Only these advance the failure count toward `probing`.
 const COUNTS_AS_FAILURE = new Set(['transient', 'systemic']);
 
+// WORKER_RAN_FLOOR_S — below this, a worker did not do any work (task 1004179).
+//
+// A real Claude Code session that read a brief, touched a repo and produced a
+// verdict does not finish in seconds. The observed broken shape was 2s with no
+// cost recorded at all. The floor is generous on purpose: it only has to
+// separate "the process died on startup" from "a session ran", and being wrong
+// in the permissive direction costs one extra iteration, while being wrong in
+// the strict direction would call a fast legitimate run breakage.
+const WORKER_RAN_FLOOR_S = 30;
+
+// workerNeverRan — the supervisor already decided the worker FAILED; this asks
+// whether it ever started. Both conditions are required: a worker that burned
+// real time or real tokens and then failed DID run and met something, which is
+// a different fact that this must not swallow.
+function workerNeverRan(row = {}) {
+  if (row.outcome !== 'worker_failed') return false;
+  if (row.spawn_error) return true;   // it could not even be launched
+  const cost = Number(row.cost_usd);
+  const spentNothing = !Number.isFinite(cost) || cost <= 0;
+  const dur = Number(row.duration_s);
+  const tooFast = Number.isFinite(dur) && dur < WORKER_RAN_FLOOR_S;
+  return spentNothing && tooFast;
+}
+
 // SYSTEMIC_MARKERS — substrings that mean waiting will not help.
 //
 // A heuristic over an error string, which is a thing to be uneasy about, so the
@@ -86,6 +110,33 @@ function classifyEvent(row = {}) {
     // counting it as such would hold a broken runner at full speed indefinitely.
     if (row.verified === true) return { class: 'progress', detail: 'a task shipped and the ledger confirms it' };
     if (row.ledger_shape === 'undetermined') return { class: 'transient', detail: 'the ledger could not be read back' };
+    // DID THE WORKER ACTUALLY RUN? (task 1004179, found by the 1003907 proof run.)
+    //
+    // Everything below this line assumes a worker that ran and met a real
+    // obstacle — a grader refusal, a red main, a task it could not finish. That
+    // is genuinely quiet: the machine is fine, a blocker was filed, the task is
+    // out of the pool, and moving to the next one is right.
+    //
+    // A worker that never got going is the opposite, and it was landing in the
+    // same bucket. On the Windows host every worker exited in ~2s with "worker
+    // output was not JSON" because its argv was corrupted; each run filed a
+    // blocker, parked a task, and was classed `quiet` — which neither trips nor
+    // forgives the failure count. consecutive_failures stayed 0, the mode stayed
+    // `full`, and the runner would have worked through the entire allowlisted
+    // goal at one task per five minutes, parking every one of them, while the
+    // hall showed it alive and allowed to work. It got through one task before a
+    // human stopped it.
+    //
+    // The queue-vs-runner distinction this module already draws is the same one:
+    // `unworkable_queue` is a healthy machine with nothing it can do, and must
+    // never escalate. A worker that cannot start is a BROKEN machine with plenty
+    // it should be doing, and must.
+    if (workerNeverRan(row)) {
+      return {
+        class: looksSystemic(reason) ? 'systemic' : 'transient',
+        detail: `the worker never ran (${row.outcome || 'worker_failed'}${Number.isFinite(Number(row.duration_s)) ? `, ${row.duration_s}s` : ''}, no cost recorded): ${String(row.reason || '').slice(0, 200)}`,
+      };
+    }
     // It ran, it did not ship. Not breakage — a blocker was filed and the task is
     // out of the pool — but not progress either. Quiet keeps the runner at full
     // speed so it moves on to the next task, which is the right response.
@@ -273,4 +324,5 @@ function shouldJumpWait(before, after) {
 module.exports = {
   CLASSES, COUNTS_AS_FAILURE, SYSTEMIC_MARKERS, DEFAULTS, START,
   looksSystemic, classifyEvent, nextCadence, signalFingerprint, shouldJumpWait,
+  workerNeverRan, WORKER_RAN_FLOOR_S,
 };

package/modules/autonomy/db.js

@@ -44,6 +44,24 @@ async function lastAutonomyHead(routine) {
   return rows[0]?.head_sha || null;
 }
 
+// The recent autonomy-gate decisions, newest first — the off-box answer to "did the
+// routine fire, and what did it decide" (task 1002669). Every precheck writes a row
+// here, every SKIP included, so the table is the whole record; before this read
+// existed, finding out needed an SSH session on the host (blocker 1000106). `routine`
+// null means every routine. The (routine, created_at DESC) index serves both shapes.
+async function readAutonomyRuns({ routine = null, limit = 20 } = {}) {
+  const { rows } = await pool.query(
+    `SELECT id, routine, decision, reason, head_sha, claimable_count, enabled, created_at
+       FROM autonomy_runs
+      WHERE ($1::text IS NULL OR routine = $1)
+      ORDER BY created_at DESC, id DESC
+      LIMIT $2`,
+    [routine, limit]
+  );
+  // bigserial ids arrive as strings from node-postgres; keep them strings on purpose.
+  return rows.map((r) => ({ ...r, id: String(r.id) }));
+}
+
 // ── the Autobongos fence (task 1003908, ADR 0307 §6) ─────────────────────────
 //
 // These back the one control surface the runner host cannot write to. Everything
@@ -162,6 +180,7 @@ async function readRunnerHeartbeats(builderId) {
 module.exports = {
   recordAutonomyRun,
   lastAutonomyHead,
+  readAutonomyRuns,
   recordRunnerHeartbeat,
   readRunnerHeartbeats,
   readFence,

package/modules/autonomy/routes/autonomy.js

@@ -42,6 +42,16 @@ const { validateOrRespond } = api;
 //
 // rank: archon — autonomy is an ops control surface, and a precheck records an
 // autonomy_runs row + git-fetches. Keep it archon-scoped (ADR 0016).
+// ?limit for GET /autonomy/runs: an integer 1..100, else the default 20. Clamped rather
+// than refused — a read an operator types by hand should answer, not argue.
+const RUNS_DEFAULT_LIMIT = 20;
+const RUNS_MAX_LIMIT = 100;
+function runsLimit(raw) {
+  const n = Number.parseInt(String(raw ?? ''), 10);
+  if (!Number.isFinite(n)) return RUNS_DEFAULT_LIMIT;
+  return Math.min(RUNS_MAX_LIMIT, Math.max(1, n));
+}
+
 module.exports = function buildAutonomyRouter() {
   const router = express.Router();
 
@@ -58,6 +68,24 @@ module.exports = function buildAutonomyRouter() {
     }
   });
 
+  // The gate's past decisions — did a routine fire, and what did it decide, and why
+  // (task 1002669). READ-ONLY and behind the SAME atom as the precheck above
+  // (`autonomy.precheck`, Metic+): whoever may ask the gate the question may read its
+  // past answers, and a new atom would need a migration for no change in audience.
+  // Adds no gate anywhere — pure observability over rows the precheck already writes.
+  // ?routine=<name> narrows to one routine; ?limit=1..100 (default 20), newest first.
+  router.get('/autonomy/runs', auth.requireBuilder, auth.requirePermission('autonomy.precheck'), async (req, res) => {
+    const routine = typeof req.query.routine === 'string' && req.query.routine ? req.query.routine.slice(0, 64) : null;
+    const limit = runsLimit(req.query.limit);
+    try {
+      const runs = await db.readAutonomyRuns({ routine, limit });
+      res.json({ routine, limit, runs });
+    } catch (err) {
+      log.error('[gds] GET /autonomy/runs', err);
+      res.fail('autonomy_runs_unreadable', { status: 503, message: 'could not read the autonomy decisions' });
+    }
+  });
+
   // ── the Autobongos fence (task 1003908, ADR 0307 §6) ───────────────────────
   //
   // These four routes ARE the fence. Everything the unattended runner is allowed

package/modules/government/catalog.js

@@ -108,7 +108,7 @@ const PERMISSIONS = [
   // owner holds: the catalog's own invariant forbids granting a system key to metic,
   // so this cannot be delegated downward by a custom rank. The web tier still gains
   // no shell - the route only QUEUES an intent the control-plane runner drains.
-  { key: 'core.pin.move', system: true, floor: 'archon', guards: 'POST /provisioning/instances/:id/core-upgrade — gate 3 of the release pipeline (ADR 0293)' },
+  { key: 'core.pin.move', system: true, floor: 'archon', guards: 'POST /provisioning/instances/:id/core-upgrade — gate 3 of the release pipeline (ADR 0293); also the reads GET /core-update (the upgrade banner) and GET /core-upgrades (the upgrade ledger, task 1002669)' },
   // autonomy.fence.manage (task 1003908, ADR 0307 §6) — THE AUTOBONGOS KILL
   // SWITCH and the allowlist of goals an unattended runner may work. system:true
   // + archon for core.pin.move's reason, in a slightly sharper form: this decides
@@ -253,7 +253,7 @@ const PERMISSIONS = [
   { key: 'security.report.adjudicate', system: false, floor: 'metic', guards: 'GET /security/reports, POST /security/reports/:id/{confirm,dispute,fix,link-fix}, /security/docs CRUD (ADR 0157, was archon)' },
   { key: 'provisioning.fleet.manage', system: false, floor: 'metic', guards: 'GET /provisioning/fleet[/cost-ledger], POST .../force-teardown (ADR 0157, was archon)' },
   { key: 'box.fleet.manage', system: false, floor: 'metic', scope: 'any', resource: 'box', verb: 'manage', guards: 'GET /boxes[/cost-ledger], POST /boxes/:b/close, PATCH .../block (ADR 0157, was archon)' },
-  { key: 'autonomy.precheck', system: false, floor: 'metic', guards: 'GET /autonomy/precheck — unsupervised-runner gate (ADR 0157, was archon)' },
+  { key: 'autonomy.precheck', system: false, floor: 'metic', guards: 'GET /autonomy/precheck — unsupervised-runner gate (ADR 0157, was archon); also GET /autonomy/runs, the gate\'s past decisions (task 1002669)' },
   { key: 'discord.channels.manage', system: false, floor: 'metic', guards: 'GET /discord/channels/plan, POST .../reconcile (ADR 0157, was archon)' },
   // Metic by the discord.channels.manage analogue — configuring a project-wide
   // social surface — rather than archon. The blast radius is bounded by the OTHER

package/modules/government/protected-surfaces.json

@@ -59,6 +59,7 @@
     { "glob": "modules/grading/grader-prompt.js", "group": "pipeline", "why": "task 1004024. Carved out of grader.js: the deterministic permission-path pre-pass, the server-side score guards a model cannot talk past, the subagent spawn and the prompt. grader.js alone protected the facade and none of the gate." },
     { "glob": "modules/grading/grader-score.js", "group": "pipeline", "why": "task 1004024. Carved out of grader.js: the deterministic permission-path pre-pass, the server-side score guards a model cannot talk past, the subagent spawn and the prompt. grader.js alone protected the facade and none of the gate." },
     { "glob": "modules/grading/grader-subagent.js", "group": "pipeline", "why": "task 1004024. Carved out of grader.js: the deterministic permission-path pre-pass, the server-side score guards a model cannot talk past, the subagent spawn and the prompt. grader.js alone protected the facade and none of the gate." },
+    { "glob": "modules/grading/grade-engine.js", "group": "pipeline", "why": "task 1002839. The central grading engine every work-type is graded through: it runs the deterministic route-rank and permission-path pre-passes and applies the deterministic veto, so editing it can switch off the protected-path gate for every grade at once." },
     { "glob": "modules/grading/grader-workers/", "group": "pipeline", "why": "the adversarial panel (Narc/Hacker/Quality/Efficiency) — blunting these blunts the gate" },
     { "glob": "modules/grading/grader-rubric.json", "group": "pipeline", "why": "the grader's scoring rubric (ADR 0058)" },
     { "glob": "scripts/gds/ship.js", "group": "pipeline", "why": "the ship lifecycle driver" },

package/modules/grading/grade-engine.js

@@ -0,0 +1,267 @@
+// modules/grading/grade-engine.js — the central grading engine: ONE named
+// pipeline every work-type is graded through, and the registry a work-type's
+// grader registers into (ADR 0089 §1, task 1002839).
+//
+// WHY. ADR 0089 decided the grader is a central, work-type-parameterized engine:
+// the orchestration, the deterministic security pre-passes, the gate and the
+// persisted record are written once, and a work-type contributes only what is
+// genuinely its own — its judges, the evidence they read, and how their verdicts
+// combine. Until this file that pipeline existed only as the body of
+// gradeSubagent, hard-wired to the code panel, so a second work-type had no way
+// in. The stages below are the same ones, in the same order, now named.
+//
+// THE PIPELINE (PIPELINE_STAGES, in order):
+//   select     resolve the work-type: an explicit key, else task.discipline, else
+//              task.kind, else the default (the code panel).
+//   pre_pass   the deterministic route-rank + permission-path checks. ENGINE-OWNED
+//              and zero-LLM: a work-type cannot skip, reorder or soften them.
+//   evidence   the work-type gathers what its judges read (code: the post-change
+//              file bundle + generated-file provenance, read once).
+//   fan_out    every judge runs independently, in parallel.
+//   aggregate  the work-type combines its judges' verdicts (code: aggregatePanel).
+//   gate       ENGINE-OWNED deterministic veto: a pre-pass that hard-failed fails
+//              the grade whatever the aggregate said — no verdict, from any model,
+//              upgrades a fail over a protected path (ADR 0016 / 0043 / 0080). For
+//              the code panel it never fires, because aggregatePanel already fails
+//              on a deterministic fail; it is what makes the guarantee hold for a
+//              work-type whose aggregate does not.
+//   persist    shape the record the lifecycle stores: per-judge signals, cost, and
+//              the run meta. Grading owns no table (ADR 0091 §4) — the write itself
+//              stays db.applyGrade behind POST /tasks/:id/grade, where
+//              serverSideGuards re-runs the same pre-passes on authoritative data.
+//
+// THE REGISTRY HAS TWO DOORS, because ADR 0083 forbids one module requiring
+// another. The grading module's own work-types register directly
+// (registerWorkType — the code panel does, from grader.js). Any other module
+// contributes one as a provider on the kernel seam port `grader.workType.<key>`,
+// through the doorway — the only door it has. resolveWorkType reads both, local
+// first, so a seam reset (tests do one) can never lose the default.
+//
+// REPLAY. replayRecorded re-runs aggregate + gate over a grade's PERSISTED
+// per-judge signals — zero model calls. It is how a change to either stage is
+// proven against real recorded grades before it touches the live gate
+// (scripts/gds/grade-replay.js, tests/grade_engine_replay.mjs).
+
+'use strict';
+
+const api = require('../../src/module-api');
+const { ASSUMED_BUILDER_MODEL, permissionPathPrePass, routeRankPrePass } = require('./grader-config.js');
+const { selectGraderModel } = require('./grader-model.js');
+const { extractAssistantResult, runSubagentCached } = require('./grader-subagent.js');
+
+const PIPELINE_STAGES = Object.freeze(['select', 'pre_pass', 'evidence', 'fan_out', 'aggregate', 'gate', 'persist']);
+
+const WORK_TYPE_PORT_PREFIX = 'grader.workType.';
+const WORK_TYPE_KEY_RE = /^[a-z][a-z0-9_-]{0,39}$/;
+// What a work-type must supply. gatherEvidence and recordEvidence are optional
+// (a work-type whose judges read only the task + diff needs neither).
+const REQUIRED_HOOKS = Object.freeze(['resolveJudges', 'modelFor', 'runJudge', 'aggregate', 'unavailable']);
+// The pseudo-judge kinds the deterministic pre-passes produce. Replay rebuilds
+// the pre-pass results from them so its gate judges what the live gate judged.
+const DETERMINISTIC_KINDS = Object.freeze(['route-rank', 'permission-path']);
+
+const local = new Map(); // key -> work-type registered directly by this module
+let defaultKey = null;
+
+function workTypePort(key) {
+  return `${WORK_TYPE_PORT_PREFIX}${key}`;
+}
+
+// Refuse a malformed work-type at REGISTRATION, not on the first ship that
+// resolves it — a missing hook would otherwise surface as a TypeError mid-grade.
+function validateWorkType(def) {
+  if (!def || typeof def !== 'object') throw new TypeError('grade engine: a work-type must be an object');
+  if (typeof def.key !== 'string' || !WORK_TYPE_KEY_RE.test(def.key)) {
+    throw new TypeError(`grade engine: work-type key ${JSON.stringify(def.key)} must match ${WORK_TYPE_KEY_RE}`);
+  }
+  const missing = REQUIRED_HOOKS.filter((h) => typeof def[h] !== 'function');
+  for (const h of ['gatherEvidence', 'recordEvidence']) {
+    if (def[h] != null && typeof def[h] !== 'function') missing.push(h);
+  }
+  if (missing.length) throw new TypeError(`grade engine: work-type '${def.key}' is missing hook(s): ${missing.join(', ')}`);
+  return def;
+}
+
+// Register one of THIS module's work-types. Idempotent for the same definition
+// (grader.js is required from several places); a second, different definition
+// for a key is a wiring bug and throws, like a duplicate seam provider.
+function registerWorkType(def, { isDefault = false } = {}) {
+  validateWorkType(def);
+  const held = local.get(def.key);
+  if (held && held !== def) throw new Error(`grade engine: work-type '${def.key}' is already registered`);
+  local.set(def.key, def);
+  if (isDefault) defaultKey = def.key;
+  return def;
+}
+
+// A work-type contributed by another module through the seam, or null. An
+// invalid contribution is refused loudly and treated as absent, so a broken
+// module degrades to the default grader instead of crashing every grade.
+function seamWorkType(key) {
+  const port = workTypePort(key);
+  if (!api.hasProvider(port)) return null;
+  const def = api.resolve(port);
+  try {
+    validateWorkType(def);
+  } catch (err) {
+    console.error(`grade engine: ignoring invalid work-type on port ${port}: ${err.message}`);
+    return null;
+  }
+  return def.key === key ? def : null;
+}
+
+function lookup(key) {
+  if (typeof key !== 'string' || !key) return null;
+  return local.get(key) || seamWorkType(key);
+}
+
+// select — explicit key, then the task's discipline, then its kind, then the
+// default. Never throws once a default is registered: an unknown or mistyped
+// key grades on the default rather than stranding the ship (the task 1002659
+// posture — a grade step that throws strands the ship).
+function resolveWorkType({ workType, task } = {}) {
+  if (workType && typeof workType === 'object') return validateWorkType(workType);
+  const t = task || {};
+  for (const key of [workType, t.discipline, t.kind]) {
+    const def = lookup(key);
+    if (def) return def;
+  }
+  const def = defaultKey ? local.get(defaultKey) : null;
+  if (!def) throw new Error('grade engine: no default work-type registered (modules/grading/grader.js registers the code panel)');
+  return def;
+}
+
+// Every work-type the engine can currently resolve, sorted — local and seam.
+function listWorkTypes() {
+  const keys = new Set(local.keys());
+  for (const port of api.listPorts()) {
+    if (!port.startsWith(WORK_TYPE_PORT_PREFIX)) continue;
+    const key = port.slice(WORK_TYPE_PORT_PREFIX.length);
+    if (seamWorkType(key)) keys.add(key);
+  }
+  return [...keys].sort();
+}
+
+// pre_pass — both deterministic checks, in this order, for every work-type. Each
+// is null (zero cost) when its trigger is absent; the rest of the pipeline sees
+// only the ones that ran.
+function runPrePasses({ changedFiles, builderRank }) {
+  return [routeRankPrePass(changedFiles), permissionPathPrePass(changedFiles, builderRank)].filter(Boolean);
+}
+
+// gate — the deterministic veto. Downgrade-only: it can turn a non-fail into a
+// fail, never the reverse, and it returns the aggregate UNTOUCHED when there is
+// nothing to enforce (always, for the code panel).
+function applyDeterministicGate(result, prePasses) {
+  const failed = prePasses.filter((p) => p && p.workerResult && p.workerResult.verdict === 'fail');
+  if (!failed.length) return result;
+  const signals = (result && result.signals) || {};
+  if (result && result.passed !== true && signals.panel_outcome === 'fail') return result;
+  const kinds = failed.map((p) => p.workerResult.kind);
+  return {
+    ...result,
+    passed: false,
+    signals: { ...signals, panel_outcome: 'fail', confidence: 0, deterministic_veto: kinds },
+    notes_md: `${(result && result.notes_md) || ''}\n\nGrade engine — DETERMINISTIC VETO: ${kinds.join(', ')} hard-failed, so this grade FAILS whatever the judges said (ADR 0016 / 0043 / 0080: no verdict may upgrade a fail over a protected path).`,
+  };
+}
+
+// persist — append the run meta to the record's signals. Appended AFTER
+// aggregate and gate, so the key order is exactly what aggregatePanel produced
+// when it was handed the meta directly.
+function persist(result, meta) {
+  return { ...result, signals: { ...(result.signals || {}), ...meta } };
+}
+
+// The model call every judge makes: runSubagent wrapped in the content-addressed
+// LLM cache (System 5) — the same prompt + model replays at $0. Absent llm-cache,
+// a plain run. `taskType` is part of the cache key, so a work-type keeps its own.
+function cachedModelCall(taskType) {
+  return ({ prompt, opts }) => runSubagentCached({
+    prompt,
+    opts,
+    cache: api.llmCache
+      ? api.llmCache.makeCacheSpec({ prompt, model: opts?.model, task_type: taskType })
+      : null,
+  });
+}
+
+// The whole pipeline for one grade. `deps.runSubagent` replaces the model call
+// (tests; production never passes it). Returns the work-type's grade-result.
+async function runGrade(input = {}, deps = {}) {
+  const { task, valueSummary, diff, changedFiles, diffStats, judges, builderModel, builderRank, priorRound, runOpts = {} } = input;
+
+  // select
+  const wt = resolveWorkType({ workType: input.workType, task });
+
+  // #943: bypass / disabled short-circuit — BEFORE resolving judges or spawning
+  // anything. Spawning into an outage/bypass window is what manufactured the
+  // "FAIL · 0/10" false verdict in session 1659.
+  if (runOpts.bypass === true || process.env.GRADER_BYPASS_ENABLED === '1') {
+    const reason = runOpts.bypass === true ? 'bypass_requested' : 'grader_bypass_enabled';
+    return wt.unavailable({
+      reason,
+      note: 'Grader bypassed before worker spawn (GRADER_BYPASS_ENABLED / runOpts.bypass) — no panel ran. Land via manual-confirm (/confirm).',
+      meta: { builder_model_assumed: builderModel || ASSUMED_BUILDER_MODEL, bypassed: true },
+    });
+  }
+  const panel = wt.resolveJudges(judges);
+  const graderModel = selectGraderModel({ builderModel });
+
+  // pre_pass
+  const prePasses = runPrePasses({ changedFiles, builderRank });
+  const deterministicFindings = prePasses.flatMap((p) => p.findings);
+
+  // evidence
+  const ctx = { task, valueSummary, diff, changedFiles, diffStats, builderModel, builderRank, priorRound, runOpts, graderModel, deterministicFindings };
+  const evidence = wt.gatherEvidence ? await wt.gatherEvidence(ctx) : {};
+
+  // fan_out
+  const runSubagentFn = deps.runSubagent || cachedModelCall(wt.cacheTaskType || `grade_${wt.key}`);
+  const startedAt = Date.now();
+  const results = await Promise.all(panel.map((judge) => wt.runJudge(judge, {
+    ...ctx,
+    evidence,
+    model: wt.modelFor(judge, graderModel, builderModel),
+    runSubagentFn,
+    extractAssistantResultFn: extractAssistantResult,
+  })));
+  // The deterministic checks join as pseudo-judges, after the model judges, so
+  // an aggregate's any-fail rule sees them like any other verdict.
+  for (const p of prePasses) results.push(p.workerResult);
+  const totalMs = Date.now() - startedAt;
+
+  // aggregate → gate → persist
+  const gated = applyDeterministicGate(wt.aggregate(results, {}), prePasses);
+  return persist(gated, {
+    builder_model_assumed: builderModel || ASSUMED_BUILDER_MODEL,
+    grader_model: graderModel,
+    total_ms: totalMs,
+    ...(wt.recordEvidence ? wt.recordEvidence(evidence, ctx) : {}),
+  });
+}
+
+// Re-run aggregate + gate over a grade's persisted per-judge signals
+// (signals.workers — the deterministic pseudo-judges included). Pure: no model
+// call, no I/O. The pre-pass results are rebuilt from the recorded pseudo-judges,
+// so the gate judges exactly what the live run's gate judged.
+function replayRecorded({ signals, workType } = {}) {
+  const wt = resolveWorkType({ workType });
+  const judges = Array.isArray(signals && signals.workers) ? signals.workers : [];
+  const prePasses = judges
+    .filter((w) => w && w.model === 'deterministic' && DETERMINISTIC_KINDS.includes(w.kind))
+    .map((w) => ({ findings: w.issues || [], workerResult: w }));
+  return applyDeterministicGate(wt.aggregate(judges, {}), prePasses);
+}
+
+module.exports = {
+  PIPELINE_STAGES,
+  WORK_TYPE_PORT_PREFIX,
+  applyDeterministicGate,
+  listWorkTypes,
+  registerWorkType,
+  replayRecorded,
+  resolveWorkType,
+  runGrade,
+  workTypePort,
+};

package/modules/grading/grader-subagent.js

@@ -19,9 +19,10 @@ function runSubagent({ prompt, opts = {} }) {
     const timeoutMs = opts.timeoutMs ?? 240_000;
     const cwd = opts.cwd ?? process.cwd();
     const model = opts.model ?? DEFAULT_GRADER_MODEL;
-    // Env escape hatch (OTB_CLAUDE_BIN / CLAUDE_BIN) for installs where the CLI
-    // isn't named `claude` on PATH — covers any OS, not just Windows.
-    const bin = opts.claudeBin ?? process.env.OTB_CLAUDE_BIN ?? process.env.CLAUDE_BIN ?? 'claude';
+    // Env escape hatch (<PREFIX>_CLAUDE_BIN — BONGOS_ on a vanilla instance, the
+    // legacy OTB_ still read — then the unprefixed CLAUDE_BIN) for installs where the
+    // CLI isn't named `claude` on PATH — covers any OS, not just Windows.
+    const bin = opts.claudeBin ?? api.resolveEnv('CLAUDE_BIN') ?? process.env.CLAUDE_BIN ?? 'claude';
 
     // THE PERMISSION MODE IS ROOT-DEPENDENT (task 1003574). `bypassPermissions` maps
     // to --dangerously-skip-permissions, and the CLI REFUSES that when euid is 0:

package/modules/grading/grader-workers/index.js

@@ -87,8 +87,22 @@ const TRANSIENT_WORKER_ERRORS = new Set([
 // errored no-finding Quality — the tag is the diagnosis, not the trigger).
 // The pattern is the API's exact sentence, so a diff that merely mentions the
 // phrase cannot trip it.
-const PROMPT_TOO_LONG_RE = /prompt is too long: the request is ~?\d+ tokens/i;
+//
+// task 1003648: the separator is NOT a colon. The line the CLI really prints —
+// stored verbatim on task 1003298's grade row — is
+//   "Prompt is too long · the request is ~251248 tokens (limit 200000) ..."
+// and the colon form above was a paraphrase, so the tag never fired on a real
+// overflow: it was filed as SUBAGENT_NONZERO_EXIT and retried as if transient.
+// Any short run of non-word characters between the halves matches both.
+const PROMPT_TOO_LONG_RE = /prompt is too long\W{1,5}the request is ~?\d+ tokens/i;
 const PROMPT_TOO_LONG = 'PROMPT_TOO_LONG';
+// The numbers in that same sentence, recorded so a bounded row says how far
+// over the window it was. Absent from a line that does not carry them.
+const OVERFLOW_NUMBERS_RE = /the request is ~?(\d+) tokens \(limit (\d+)\)/i;
+function overflowNumbers(said) {
+  const m = OVERFLOW_NUMBERS_RE.exec(String(said || ''));
+  return m ? { request_tokens: Number(m[1]), window_tokens: Number(m[2]) } : {};
+}
 
 // #467: per-worker subagent timeout. The global 240s applied to EVERY worker,
 // which timed out the Read-heavy ones (Narc walks ACs + reads files — hence
@@ -195,13 +209,14 @@ async function runWorker(worker, { task, valueSummary, diff, changedFiles, diffS
   // builder response for a delta-aware re-grade; every worker renders it via
   // the shared scaffold. contextBundle (task 1002660) likewise: the post-change
   // file contents read once by the caller, rendered by the shared scaffold.
-  const prompt = worker.buildPrompt({ task, valueSummary, diff, changedFiles, diffStats, deterministicFindings, priorRound, contextBundle });
+  const promptInputs = { task, valueSummary, diff, changedFiles, diffStats, deterministicFindings, priorRound, contextBundle };
+  const prompt = worker.buildPrompt(promptInputs);
 
   // One subagent attempt → verdict. Pulled out so #465 can re-run it once on a
   // transient error without duplicating the spawn/parse/verdict plumbing.
   // #467: per-worker timeout (Read-heavy workers get longer; see the map above).
   const timeoutMs = timeoutForWorker(worker, runOpts);
-  async function attempt() {
+  async function attempt(promptText) {
     let raw = null;
     let runMs = null;
     let costUsd = null;
@@ -209,9 +224,10 @@ async function runWorker(worker, { task, valueSummary, diff, changedFiles, diffS
     // task 1003313: the WHY behind subprocessError. Null on a clean run.
     let exitCode = null;
     let stderrTail = null;
+    let overflow = null; // task 1003648: the refusal's own numbers, on a PROMPT_TOO_LONG only
     const t0 = Date.now();
     try {
-      const { stdout, run_ms, cost_usd } = await runSubagentFn({ prompt, opts: { ...runOpts, model, timeoutMs } });
+      const { stdout, run_ms, cost_usd } = await runSubagentFn({ prompt: promptText, opts: { ...runOpts, model, timeoutMs } });
       runMs = run_ms;
       // #486 (ADR 0028 path 1): runSubagent attaches the `claude -p` envelope's
       // total_cost_usd. Carry it out so aggregatePanel can sum the panel's own
@@ -232,7 +248,10 @@ async function runWorker(worker, { task, valueSummary, diff, changedFiles, diffS
       // the #467 budget signal, never a refusal.
       if (err.code !== 'SUBAGENT_TIMEOUT') {
         const said = String(err.stderr || '').trim() || String(err.stdout || '');
-        if (PROMPT_TOO_LONG_RE.test(said)) subprocessError = PROMPT_TOO_LONG;
+        if (PROMPT_TOO_LONG_RE.test(said)) {
+          subprocessError = PROMPT_TOO_LONG;
+          overflow = overflowNumbers(said);
+        }
       }
     }
     const parsed = subprocessError
@@ -243,18 +262,47 @@ async function runWorker(worker, { task, valueSummary, diff, changedFiles, diffS
       run_ms: runMs,
       subprocess_error: subprocessError,
     });
-    return { verdict, runMs, costUsd, exitCode, stderrTail };
+    return { verdict, runMs, costUsd, exitCode, stderrTail, overflow };
   }
 
-  let { verdict, runMs, costUsd, exitCode, stderrTail } = await attempt();
   // #465: retry ONCE on a transient error (the freshest attempt wins, even if it
   // also errored — one retry only). A real verdict or a SUBAGENT_TIMEOUT is
   // never retried. NB (#486): the freshest attempt's cost wins; a transient
   // first attempt's spend is not added (slight, rare undercount).
-  let retried = false;
-  if (TRANSIENT_WORKER_ERRORS.has(verdict.error)) {
-    retried = true;
-    ({ verdict, runMs, costUsd, exitCode, stderrTail } = await attempt());
+  async function attemptWithRetry(promptText) {
+    const first = await attempt(promptText);
+    if (!TRANSIENT_WORKER_ERRORS.has(first.verdict.error)) return { ...first, retried: false };
+    return { ...(await attempt(promptText)), retried: true };
+  }
+
+  let { verdict, runMs, costUsd, exitCode, stderrTail, overflow, retried } = await attemptWithRetry(prompt);
+
+  // task 1003648 — a prompt too big for this worker's model window degrades
+  // instead of failing outright. The CLI measures the real window and the real
+  // overhead (its own system prompt, tool definitions and auto-loaded context —
+  // ~150k tokens of task 1003298's 251k-token refusal), so the refusal is the
+  // authoritative "does not fit"; the one part of the prompt that can go without
+  // losing any evidence is the post-change file bundle, because the worker can
+  // Read those files itself. So: retry ONCE without it. The diff, the task and the
+  // prior round all stay — the retried worker reviews the same change, it just
+  // fetches the files instead of being handed them. If even that does not fit,
+  // the worker stays PROMPT_TOO_LONG: an explicit lens-unavailable, never a score.
+  // No bundle to drop → nothing smaller to try, so no second refusal is spent.
+  let promptBounded = null;
+  const bundledFiles = contextBundle && Array.isArray(contextBundle.files) ? contextBundle.files : [];
+  if (verdict.error === PROMPT_TOO_LONG && bundledFiles.length > 0) {
+    // Generated-file provenance is verified, trusted text — it stays.
+    const smaller = worker.buildPrompt({ ...promptInputs, contextBundle: { ...contextBundle, files: [] } });
+    promptBounded = {
+      reason: PROMPT_TOO_LONG,
+      bundle_dropped: true,
+      bundle_files: bundledFiles.length,
+      prompt_chars: prompt.length,
+      retry_prompt_chars: smaller.length,
+      ...(overflow || {}),
+    };
+    ({ verdict, runMs, costUsd, exitCode, stderrTail, overflow, retried } = await attemptWithRetry(smaller));
+    promptBounded.retry_error = verdict.error ?? null;
   }
 
   return {
@@ -277,6 +325,14 @@ async function runWorker(worker, { task, valueSummary, diff, changedFiles, diffS
     ...(verdict.error && stderrTail ? { stderr_tail: stderrTail } : {}),
     // Narc-specific (carried opaquely; aggregatePanel doesn't need to know):
     ...(verdict.ac_checklist ? { ac_checklist: verdict.ac_checklist } : {}),
+    // task 1002903: the severity gate's marker. Rebuilding the row field by field
+    // used to drop it, so a stored grade could not say which low score was the
+    // one no finding backed — only the worker's prose did. Omitted when absent,
+    // so an ordinary worker row keeps its exact shape.
+    ...(verdict.policy_downgrade ? { policy_downgrade: verdict.policy_downgrade } : {}),
+    // task 1003648: present only when the first prompt overflowed the window and
+    // a smaller one was tried, so an ordinary row keeps its exact shape.
+    ...(promptBounded ? { prompt_bounded: promptBounded } : {}),
   };
 }