@bongos/core 1.19.732 → 1.19.734

package/modules/agents/lib/spend-ceiling.js

@@ -0,0 +1,170 @@
+'use strict';
+
+// modules/agents/lib/spend-ceiling.js — the per-payer MONTHLY SPEND CEILING
+// (task 1003884).
+//
+// WHY THIS IS NOT fire-budget.js, and must never become it. That file is a
+// sliding-window ceiling on how OFTEN a builder may fire, and its own header says
+// what it is not: "A CEILING, NOT A BUDGET. This bounds the blast radius of a
+// loop; it does not decide what agents may cost... Do not grow this into a budget
+// — a ceiling that silently became the accounting would be a second, wrong answer
+// to 'what did agents cost'." This file is the other half it deferred to: it reads
+// the REAL accounting, `agents_runs.cost_usd`, which the grade port bills through
+// the shared LLM cost cache, and refuses a fire when the payer has spent their
+// month.
+//
+// The two bound different things and neither substitutes for the other:
+//
+//   fire-budget   10 fires/hour/BUILDER    bounds a runaway loop, in real time
+//   spend-ceiling $N/month/PAYER           bounds the BILL, off the real ledger
+//
+// A rate ceiling cannot bound a bill (ten fires an hour is ~$650/month/builder),
+// and a spend ceiling cannot bound a loop (it reads spend that has already landed).
+// Both run, in that order, on every fire.
+//
+// ─────────────────────────────────────────────────────────────────────────────
+// IT FAILS CLOSED, AND THAT IS THE WHOLE POINT.
+//
+// The prior art is task 1001393, which was filed because the autonomy spend-brake
+// was structurally BLIND: gatherSignals() read month-to-date spend from a database
+// that was unreachable from where the spender ran, so the precheck FAILED OPEN and
+// the brake never tripped once. A spend guard that answers "I don't know" with
+// "go ahead" is not a guard. So every one of these refuses:
+//
+//   • no cap configured, or a cap that is not a positive finite number
+//     — an unbounded ceiling is the defect above, wearing a cap's name;
+//   • no payer to bill — an unattributable spend is what the ledger exists to
+//     prevent, the same fail-closed reading fire-budget gives an unidentified
+//     caller;
+//   • the ledger read THREW — the exact failure 1001393 named. "The database is
+//     unreachable" is the moment a ceiling matters most, not least;
+//   • the payer has spent at or past the cap.
+//
+// ─────────────────────────────────────────────────────────────────────────────
+// THE KNOWN OVERSHOOT, stated rather than hidden. A fire is checked BEFORE it
+// runs and its cost lands AFTER it finishes (a pending run carries cost_usd NULL),
+// so fires already in flight are invisible to this read. The overshoot is
+// therefore bounded by concurrent-fires × ~$0.90 — and what bounds the concurrent
+// count is fire-budget. That is the second reason both exist: each one's blind
+// spot is the other's window.
+//
+// Requires nothing (ADR 0083): the pool is passed in, the clock is injected, and
+// the cap comes from env — so the whole file is testable without a database.
+
+// The default is deliberately SMALL. A default cap is the number that applies to
+// an instance whose owner never thought about this, and for them the right answer
+// is "enough to try it, not enough to hurt". At the historian exemplar's ~$0.90 a
+// fire that is roughly 27 fires a month. An instance that means to spend more says
+// so with one env var; an instance that meant to spend nothing was never going to
+// be saved by a generous default.
+const DEFAULT_CAP_USD = 25;
+
+// Calendar month, UTC. It matches the window agents_001's spend index was built
+// for ("What did agents cost this month?") and the $/month cap fire-budget's
+// header defers to — and a calendar month is the unit a bill arrives in, which is
+// the unit an owner reasons about.
+function monthStartUtc(at) {
+  const d = new Date(at);
+  return new Date(Date.UTC(d.getUTCFullYear(), d.getUTCMonth(), 1));
+}
+
+function envNumber(name, fallback) {
+  const raw = process.env[name];
+  if (raw === undefined || raw === '') return fallback;
+  const n = Number(raw);
+  return Number.isFinite(n) && n > 0 ? n : fallback;
+}
+
+// WHO PAYS for one fire, given the project's setting and who asked. PURE.
+//
+// Two settings map to a payer directly; `none` — and anything unset, misspelled,
+// or from a newer core — attributes to the PROJECT, because that is who the money
+// actually came from. `none` is not a third kind of payer, it is the owner not
+// having said, and its real consequence lands at config load: src/modules.js
+// refuses to enable a metered module on an OPEN-door instance whose owner has not
+// said. On a closed-door instance the module keeps working and the project's own
+// ceiling bounds it, which is today's behaviour made explicit rather than changed.
+//
+// AN EVENT FIRE HAS NO CALLER, so `builder` cannot apply to one: nobody asked for
+// it and there is nobody to bill. It falls to the project, which is the only
+// honest answer — and never to "no payer", which would make an event fire the one
+// unbounded path through this file.
+function payerFor(spendPayer, requestedByBuilderId) {
+  if (spendPayer === 'builder' && requestedByBuilderId !== null && requestedByBuilderId !== undefined) {
+    return { payer_kind: 'builder', payer_builder_id: requestedByBuilderId };
+  }
+  return { payer_kind: 'project', payer_builder_id: null };
+}
+
+function createSpendCeiling({
+  capUsd = envNumber('BONGOS_AGENTS_SPEND_CAP_USD', DEFAULT_CAP_USD),
+  now = () => Date.now(),
+} = {}) {
+  return {
+    capUsd,
+
+    /**
+     * May this payer spend right now?
+     *
+     * Unlike fire-budget.check this records NOTHING: the ledger row the spawn
+     * writes is the record, and a ceiling that also kept its own tally would be
+     * the second, disagreeing answer this module is careful not to have.
+     *
+     * @returns {{ok: boolean, spentUsd: number|null, capUsd: number, remainingUsd: number, reason: string|null}}
+     */
+    async check(pool, payer) {
+      const cap = Number(capUsd);
+      const deny = (reason) => ({ ok: false, spentUsd: null, capUsd: cap, remainingUsd: 0, reason });
+
+      if (!Number.isFinite(cap) || cap <= 0) return deny('no_spend_cap_configured');
+      const kind = payer && payer.payer_kind;
+      if (kind !== 'project' && kind !== 'builder') return deny('no_payer');
+      const builderId = payer.payer_builder_id ?? null;
+      if (kind === 'builder' && builderId === null) return deny('no_payer');
+      if (!pool || typeof pool.query !== 'function') return deny('ledger_unreadable');
+
+      const since = monthStartUtc(now());
+      let spent;
+      try {
+        // Summed BY PAYER, so a builder-paid instance gives each builder their own
+        // month and a project-paid one sums the instance. Rows written before
+        // agents_002 carry no payer_kind and match neither, which is the
+        // conservative direction: nobody is charged for spend that was not
+        // attributed to them.
+        const { rows } = await pool.query(
+          `SELECT COALESCE(SUM(cost_usd), 0) AS spent
+             FROM agents_runs
+            WHERE cost_usd IS NOT NULL
+              AND created_at >= $1
+              AND payer_kind = $2
+              AND payer_builder_id IS NOT DISTINCT FROM $3`,
+          [since, kind, builderId],
+        );
+        const raw = rows && rows[0] ? rows[0].spent : undefined;
+        // NOT `Number(raw)` alone. Number(null) is 0, so a sum that came back as
+        // SQL NULL — a shape COALESCE should make impossible, and would therefore
+        // only appear if this query or that table changed under us — would read
+        // as "this payer has spent nothing" and admit the fire. That is the
+        // fail-OPEN direction wearing a plausible number, which is the whole
+        // failure mode task 1001393 was filed about, so an absent value is
+        // rejected BEFORE it can be coerced into a permissive one.
+        spent = (raw === null || raw === undefined) ? Number.NaN : Number(raw);
+      } catch (_) {
+        // THE 1001393 CASE. An unreadable ledger is the one this file exists for.
+        return deny('ledger_unreadable');
+      }
+      // A sum that is not a number is the same "I don't know" as a throw, and gets
+      // the same answer. NUMERIC comes back as a string from pg, so this catches a
+      // genuinely unparseable value, not the ordinary one.
+      if (!Number.isFinite(spent) || spent < 0) return deny('ledger_unreadable');
+
+      const remaining = cap - spent;
+      if (remaining <= 0) {
+        return { ok: false, spentUsd: spent, capUsd: cap, remainingUsd: 0, reason: 'spend_cap_reached' };
+      }
+      return { ok: true, spentUsd: spent, capUsd: cap, remainingUsd: remaining, reason: null };
+    },
+  };
+}
+
+module.exports = { createSpendCeiling, payerFor, monthStartUtc, DEFAULT_CAP_USD };

package/modules/agents/migrations/agents_002_payer.sql

@@ -0,0 +1,87 @@
+-- agents_002_payer.sql — WHO PAYS for a fire (task 1003884).
+--
+-- agents_001 recorded what a fire COST (`cost_usd`, billed through the shared LLM
+-- cost cache) and who ASKED for it (`requested_by_builder_id`). It did not record
+-- who is on the HOOK for it, and those are not the same question: with
+-- `spend_payer: project` the instance pays for a fire a stranger requested, and
+-- with `spend_payer: builder` the requester does. Without the answer stored, a
+-- per-payer ceiling has nothing to sum and a change to the setting would silently
+-- re-interpret every historical row.
+--
+-- WHY IT IS STORED AND NOT DERIVED. `payer_kind` is derivable TODAY from the
+-- project's setting plus `requested_by_builder_id` — and that is exactly the trap.
+-- The setting is a live knob an owner may flip; deriving would make last month's
+-- bill change when they do, and a ledger whose past moves is not a ledger. The
+-- run records the answer that was true when it fired, the same reason `model`
+-- stores the concrete model id rather than the tier that resolved it.
+--
+-- THE VOCABULARY IS TWO WORDS, AND 'none' IS NOT ONE OF THEM. The project setting
+-- has a third value (`none` — the owner has never said), but a RUN always has a
+-- real payer: `none` attributes to the project, because that is who the money
+-- actually came from. `none` does its work at config load instead, where
+-- src/modules.js refuses to ENABLE a module that meters spend on an instance whose
+-- join door is `open` and whose owner has not said who pays.
+--
+-- Module migrations are ADDITIVE and NAMESPACED (ADR 0083 §Decision #5): every
+-- object is agents_-prefixed, there is no down-migration, and the filename is
+-- agents_-prefixed (ADR 0108 §5). Idempotent: safe to re-run.
+
+BEGIN;
+
+-- 'project' (whoever runs the instance) | 'builder' (the caller who spent it).
+ALTER TABLE agents_runs ADD COLUMN IF NOT EXISTS payer_kind text;
+-- WHICH builder, when the payer is one. ON DELETE SET NULL matches
+-- requested_by_builder_id: deleting a person must not erase what the instance
+-- spent, and `payer_kind` survives to say the bill had an owner.
+ALTER TABLE agents_runs ADD COLUMN IF NOT EXISTS payer_builder_id bigint
+  REFERENCES builders(id) ON DELETE SET NULL;
+
+-- Idempotent constraint adds: ADD CONSTRAINT has no IF NOT EXISTS, so each is
+-- guarded by its own catalog lookup rather than by a re-runnable DDL form.
+DO $$
+BEGIN
+  -- The closed vocabulary, for the same fail-closed reason every other enum in
+  -- agents_001 is text + CHECK: an unwired payer name is refused, never stored.
+  IF NOT EXISTS (SELECT 1 FROM pg_constraint WHERE conname = 'agents_runs_payer_kind_chk') THEN
+    ALTER TABLE agents_runs ADD CONSTRAINT agents_runs_payer_kind_chk
+      CHECK (payer_kind IS NULL OR payer_kind IN ('project', 'builder'));
+  END IF;
+
+  -- A builder payer must NAME the builder; a project payer must name none. Either
+  -- half missing would leave a row that says it is attributed while being
+  -- unsummable — the shape a per-payer ceiling silently reads as zero.
+  IF NOT EXISTS (SELECT 1 FROM pg_constraint WHERE conname = 'agents_runs_payer_ref_chk') THEN
+    ALTER TABLE agents_runs ADD CONSTRAINT agents_runs_payer_ref_chk
+      CHECK (
+        payer_kind IS NULL
+        OR (payer_kind = 'builder' AND payer_builder_id IS NOT NULL)
+        OR (payer_kind = 'project' AND payer_builder_id IS NULL)
+      );
+  END IF;
+
+  -- THE INVARIANT THE TASK ASKS FOR: a run that cost money says who pays. A
+  -- no-go costs nothing and needs no payer (agents_001 already forbids it a
+  -- cost), and a pending run has no cost yet.
+  --
+  -- NOT VALID, deliberately. The constraint binds every INSERT and UPDATE from
+  -- here on, but does not scan rows written before this column existed — a
+  -- self-hosted instance that already ran agents has history that predates the
+  -- concept, and failing its migration to punish it for that would be the wrong
+  -- trade. Those rows stay honestly un-attributed; the ceiling sums by payer and
+  -- so counts none of them, which is the conservative direction (it never credits
+  -- a payer with spend that was someone else's).
+  IF NOT EXISTS (SELECT 1 FROM pg_constraint WHERE conname = 'agents_runs_cost_needs_payer_chk') THEN
+    ALTER TABLE agents_runs ADD CONSTRAINT agents_runs_cost_needs_payer_chk
+      CHECK (cost_usd IS NULL OR cost_usd = 0 OR payer_kind IS NOT NULL) NOT VALID;
+  END IF;
+END $$;
+
+-- "What has this payer spent this month?" — the ceiling's only read, and it is on
+-- the invoke hot path. Partial on cost_usd for the same reason
+-- agents_runs_spend_idx is: a row that cost nothing contributes nothing to a
+-- spend sum and would only dilute the scan.
+CREATE INDEX IF NOT EXISTS agents_runs_payer_spend_idx
+  ON agents_runs (payer_kind, payer_builder_id, created_at DESC)
+  WHERE cost_usd IS NOT NULL;
+
+COMMIT;

package/modules/agents/module.json

@@ -1,11 +1,12 @@
 {
   "key": "agents",
   "title": "Agents (declarative agent registry)",
-  "description": "Declarative agent definitions (.claude/agents/*.md) reconciled at deploy into a DB-backed registry (agents_definitions) plus a per-fire ledger (agents_runs) — BONGOS-V1 goal 1000038, Phase 1. Files-are-source: agents-sync upserts file-sourced definitions and never clobbers an instance-authored db row, and stamps author_rank from the author's LIVE DB rank because a committed file cannot grant authority (ADR 0016). Spawns consume the EXISTING `grade` port (runSubagentCached), which is fixed read-only, so v1 agents are observe-and-report only — no write principals — and every fire bills through the shared LLM cost cache. default:false: shipped is not enabled, and an instance opts in per ADR 0083.",
+  "description": "Declarative agent definitions (.claude/agents/*.md) reconciled at deploy into a DB-backed registry (agents_definitions) plus a per-fire ledger (agents_runs) — BONGOS-V1 goal 1000038, Phase 1. Files-are-source: agents-sync upserts file-sourced definitions and never clobbers an instance-authored db row, and stamps author_rank from the author's LIVE DB rank because a committed file cannot grant authority (ADR 0016). Spawns consume the EXISTING `grade` port (runSubagentCached), which is fixed read-only, so v1 agents are observe-and-report only — no write principals — and every fire bills through the shared LLM cost cache. default:false: shipped is not enabled, and an instance opts in per ADR 0083. spend.requiresPayer (task 1003884): a fire spends real money for whoever called it (~$0.90, and POST /agents/:name/invoke answers 202 without waiting), so the core refuses to ENABLE this module on an instance whose join door is `open` with no payer configured — an account created seconds ago would otherwise spend the instance's money with nobody to bill. Every run then records its payer beside cost_usd (agents_002_payer.sql) and a per-payer monthly ceiling fails closed when it is exhausted OR unreadable (lib/spend-ceiling.js) — distinct from lib/fire-budget.js, which stays a rate ceiling.",
   "coreVersion": "^1.19.0",
   "default": false,
   "maintenance": { "status": "core-maintained" },
   "contributes": { "routes": ["agents"], "migrations": true },
+  "spend": { "requiresPayer": true },
   "provides": [],
   "consumes": ["grade"]
 }

package/modules/agents/routes/agents.js

@@ -81,6 +81,7 @@ const authoring = require('../lib/authoring');
 const { gateFor } = require('../lib/gate');
 const { createAnswerHold } = require('../lib/answer-hold');
 const { createFireBudget } = require('../lib/fire-budget');
+const { createSpendCeiling, payerFor } = require('../lib/spend-ceiling');
 const { spawnAgent } = require('../spawn');
 
 const log = api.logger('agents');
@@ -90,6 +91,28 @@ const log = api.logger('agents');
 // per-router for the opposite reason — it is a delivery buffer, and a split one
 // only means an answer is collected where it was produced.
 const fireBudget = createFireBudget();
+// ONE INSTANCE, module-level, for the reason fire-budget's header gives about two
+// call sites each building their own: two ceilings look identical in review and
+// are not one ceiling. This one holds no state — it reads the ledger every time —
+// so the singleton is about the CAP being one number, not about a shared bucket.
+const spendCeiling = createSpendCeiling();
+
+// The project's `spend_payer` policy, read through branding (src/branding.js maps
+// <PREFIX>_SPEND_PAYER onto project.spendPayer). Read per request rather than
+// memoized here because branding already memoizes for the process — a second copy
+// would only add a way for the two to disagree.
+function projectSpendPayer() {
+  try {
+    const pack = api.branding ? api.branding() : null;
+    return (pack && pack.project && pack.project.spendPayer) || null;
+  } catch (_) {
+    // An unreadable pack is NOT an unbounded fire: payerFor treats a null policy
+    // as the project paying, and the ceiling then bounds the project. The
+    // fail-closed reading of an unreadable posture is src/modules.js's job, and it
+    // makes it once, at config load.
+    return null;
+  }
+}
 
 // The columns the serializer needs. Spelled out rather than `SELECT *` so that a
 // column added later (an author's email, a raw credential) cannot reach a
@@ -541,6 +564,42 @@ module.exports = function agentsRoutes() {
       });
     }
     try {
+      // THE SPEND CEILING, after the rate ceiling and before anything is read or
+      // written. The two are deliberately separate refusals with separate codes:
+      // 429 says "too fast, try later", 402 says "this month's money is gone",
+      // and an operator who cannot tell those apart cannot tell a runaway loop
+      // from a budget that is simply too small. See ../lib/spend-ceiling.js.
+      //
+      // It FAILS CLOSED — including when the ledger cannot be read, which is the
+      // exact defect task 1001393 was filed about.
+      //
+      // INSIDE the try, unlike the synchronous rate ceiling above it. This is the
+      // first `await` in the handler, and express 4 does not catch a rejected
+      // async handler — an unhandled rejection is a process-level crash that takes
+      // every other in-flight request with it, which is the same hazard the
+      // detached `done` promise below is careful about. check() is written not to
+      // throw; the try is what makes that a property of the route rather than a
+      // promise the ceiling has to keep forever.
+      const spendPayer = projectSpendPayer();
+      const payer = payerFor(spendPayer, req.builder.id);
+      const room = await spendCeiling.check(api.pool, payer);
+      if (!room.ok) {
+        return res.fail('spend_cap_reached', {
+          status: 402,
+          message: room.reason === 'spend_cap_reached'
+            ? `agent spend for this ${payer.payer_kind} has reached its $${room.capUsd} monthly cap — each fire spends real money`
+            : `agent fires are refused because the spend ceiling could not be established (${room.reason}) — a ceiling that cannot be read must not be assumed`,
+          details: {
+            scope: 'agent-spend',
+            reason: room.reason,
+            payer_kind: payer.payer_kind,
+            cap_usd: room.capUsd,
+            // null whenever the refusal was a failure to READ the ledger, which
+            // is the honest answer: a number here would claim a sum we do not have.
+            spent_usd: room.spentUsd,
+          },
+        });
+      }
       const { rows } = await api.pool.query(
         `SELECT ${COLUMNS}, persona FROM agents_definitions WHERE name = $1`, [name]
       );
@@ -554,7 +613,7 @@ module.exports = function agentsRoutes() {
       // call — the reason it can stay synchronous while the go path cannot.
       if (gate.decision !== 'go') {
         const skipped = await spawnAgent({
-          definition, trigger, gate, requestedByBuilderId: req.builder.id,
+          definition, trigger, gate, requestedByBuilderId: req.builder.id, spendPayer,
         }, {});
         return res.fail('agent_refused', {
           status: 409,
@@ -572,6 +631,7 @@ module.exports = function agentsRoutes() {
         trigger,
         gate,
         requestedByBuilderId: req.builder.id,
+        spendPayer,
       }, {
         // Wrap the port's runner to keep the reply, which spawnAgent does not
         // return — it records what a fire DID, not what it said.
@@ -669,3 +729,4 @@ module.exports.serializeRun = serializeRun;
 // The module-level ceiling, exported so a test can reset it between cases —
 // a singleton otherwise carries one case's spend into the next.
 module.exports.fireBudget = fireBudget;
+module.exports.spendCeiling = spendCeiling;

package/modules/agents/spawn.js

@@ -34,6 +34,7 @@
 // happened, and "the agent didn't run" then has two causes nobody can tell apart.
 
 const api = require('../../src/module-api');
+const { payerFor } = require('./lib/spend-ceiling');
 
 // tier → concrete model id. The mapping is BRANDING, not a constant here: an
 // instance retunes its own tiers, and the DB constraint already limits the
@@ -53,8 +54,20 @@ function resolveModel(tier, brandingModels) {
 
 // The insert shape for one fire, decided BEFORE anything spawns. Pure, so the
 // schema's invariants can be tested without a database.
-function plannedRow({ definition = {}, trigger = {}, gate = {}, model = null, requestedByBuilderId = null } = {}) {
+function plannedRow({
+  definition = {}, trigger = {}, gate = {}, model = null, requestedByBuilderId = null,
+  // The project's `spend_payer` policy as it stands AT THIS FIRE. Passed in rather
+  // than read here so this stays pure, and stamped into the row rather than
+  // derived later so a flip of the setting cannot rewrite what last month cost
+  // (agents_002_payer.sql says why at length).
+  spendPayer = null,
+} = {}) {
   const go = gate.decision === 'go';
+  // WHO PAYS — recorded on EVERY row, including a no-go. A refusal costs nothing
+  // and the schema forbids it a cost, but it is still a fire somebody would have
+  // been billed for, and a ledger that attributes only the expensive half cannot
+  // answer "what would this have cost us".
+  const payer = payerFor(spendPayer, requestedByBuilderId);
   return {
     definition_id: definition.id ?? null,
     agent_name: definition.name || null,
@@ -71,6 +84,11 @@ function plannedRow({ definition = {}, trigger = {}, gate = {}, model = null, re
     // never be re-read through today's tier mapping.
     model: go ? model : null,
     requested_by_builder_id: requestedByBuilderId ?? null,
+    // Distinct from requested_by_builder_id above, and the distinction is the
+    // point: that field is who ASKED, these are who is on the HOOK. They are the
+    // same person only when the project put the bill on its builders.
+    payer_kind: payer.payer_kind,
+    payer_builder_id: payer.payer_builder_id,
   };
 }
 
@@ -135,14 +153,14 @@ async function finishRun(pool, id, patch) {
 // agent's bad day.
 async function spawnAgent({
   definition, input = null, trigger = {}, gate = { decision: 'go' },
-  requestedByBuilderId = null, cache = null,
+  requestedByBuilderId = null, cache = null, spendPayer = null,
 } = {}, deps = {}) {
   const pool = deps.pool || api.pool;
   const now = deps.now || (() => Date.now());
   const brandingModels = deps.brandingModels || (api.branding && api.branding().models) || {};
   const model = resolveModel(definition && definition.model_tier, brandingModels);
 
-  const row = plannedRow({ definition, trigger, gate, model, requestedByBuilderId });
+  const row = plannedRow({ definition, trigger, gate, model, requestedByBuilderId, spendPayer });
   let runId = null;
   try {
     runId = await insertRun(pool, row);

package/modules/grading/dead-feature-claim.js

@@ -0,0 +1,121 @@
+// modules/grading/dead-feature-claim.js — does a panel finding say, in its own
+// words, that the shipped code does not run at all? (task 1002665)
+//
+// WHY. On the task 1002648 ship the Quality worker found that the new PATCH
+// needs_migration path threw at runtime — a TASK_SETTER_COLUMNS allowlist gap —
+// and wrote "the feature is entirely non-operational". It then filed that at
+// severity `nit`, the grade PASSed, and the dead feature merged to main. The
+// finding TEXT was right; the SEVERITY was miscalibrated, and severity is the
+// only channel a reader's attention follows.
+//
+// Two things had to be true for that to merge, and this module addresses the
+// first. (1) Nothing re-read the finding's own claim against its own severity.
+// (2) Severity has no vote in the gate at all: `passed` in grader-score.js is
+// `bothPass && !lowConfidence && …`, computed from the rubric SCORES — a major
+// or blocker issue does not by itself stop a passing grade. So a severity floor
+// alone would not have gated this ship, which is why grader-score.js pairs this
+// classifier with a server-side guard rather than relying on the raised severity
+// to do the work. The row that asked for this proposed the floor on its own; the
+// floor on its own is decoration.
+//
+// SCOPE, deliberately narrow. This matches only ABSOLUTE claims about the
+// submitted change: always-throws, never-runs, non-operational. It does NOT
+// match conditional defects ("would throw on a null id") — those are ordinary
+// findings the scores already judge — and it does not match the word
+// "unreachable", which the originating row suggested: a reviewer writes "the old
+// branch is now unreachable" to PRAISE a dead-code deletion, and that reading is
+// at least as common as the damning one. A false positive here costs a builder a
+// manual-confirm round, so the phrase list stays at claims that have no innocent
+// reading, and the suppressors below drop the two framings that do.
+
+'use strict';
+
+// Absolute claims of runtime-deadness. Each must be unambiguous ON ITS OWN — if
+// a phrase has an innocent reading in ordinary review prose, it does not belong
+// here, it belongs in the scores.
+const DEAD_CLAIM_PATTERNS = [
+  /\bnon-?operational\b/i,
+  /\b(?:always|unconditionally) throws?\b/i,
+  /\bthrows? (?:at runtime|on every (?:call|invocation|request))\b/i,
+  /\bnever (?:executes|runs|fires|gets called)\b/i,
+  /\b(?:can|will) never (?:run|execute|be (?:called|reached))\b/i,
+  /\bdoes ?n[o']?t work at all\b/i,
+  /\b(?:completely|entirely|totally) (?:broken|dead|inoperable)\b/i,
+  /\bdead on arrival\b/i,
+];
+
+// A claim about code the change REMOVED or FIXED, or a hypothetical, is the
+// opposite of a dead-feature report — it is the reviewer describing what the
+// diff cured. These read within a short window BEFORE the matched phrase,
+// because that is where the framing sits in English ("this used to always
+// throw", "no longer non-operational", "would always throw if the id were null").
+const SUPPRESSORS = [
+  /\bused to\b/i,
+  /\bno longer\b/i,
+  /\bpreviously\b/i,
+  /\bbefore this (?:change|diff|fix|patch)\b/i,
+  /\bwas\b/i,
+  /\bwould\b/i,
+  /\bif\b/i,
+  /\bprevents?\b/i,
+  /\bavoids?\b/i,
+  /\bfix(?:e[sd])?\b/i,
+];
+
+// How far back a suppressor counts. One clause, not one paragraph: read too far
+// and an unrelated "fixed" earlier in a multi-sentence summary silences a real
+// claim; read too little and "this would always throw" trips.
+const SUPPRESSOR_WINDOW = 40;
+
+// Does `text` assert that the submitted code does not run at all? Returns the
+// matched phrase (truthy, and useful in the audit trail) or null. Pure.
+function deadFeatureClaim(text) {
+  const s = typeof text === 'string' ? text : '';
+  if (!s) return null;
+  for (const re of DEAD_CLAIM_PATTERNS) {
+    const m = re.exec(s);
+    if (!m) continue;
+    const before = s.slice(Math.max(0, m.index - SUPPRESSOR_WINDOW), m.index);
+    if (SUPPRESSORS.some((sup) => sup.test(before))) continue;
+    return m[0];
+  }
+  return null;
+}
+
+// The same question asked of one issues[] entry. Only `summary` carries the
+// worker's prose — `severity`/`file` are enumerated fields — so this reads that
+// and nothing else, which keeps a file PATH containing an unlucky word (say,
+// `always-throws.test.js`) from raising a severity.
+function issueClaimsRuntimeDead(issue) {
+  if (!issue || typeof issue !== 'object') return null;
+  return deadFeatureClaim(issue.summary);
+}
+
+// Severities in ascending order of gravity; anything at or above `major` needs no
+// floor, and an unrecognised severity is treated as below it (fail-closed: an
+// unknown label must not buy an exemption).
+const AT_LEAST_MAJOR = new Set(['major', 'blocker']);
+
+// Raise a runtime-dead finding to `major`, preserving what the worker reported.
+// Returns a NEW array when anything changed, the input array otherwise, so a
+// caller can cheaply tell whether the floor fired.
+function applyDeadFeatureFloor(issues) {
+  if (!Array.isArray(issues)) return issues;
+  let changed = false;
+  const out = issues.map((it) => {
+    const claim = issueClaimsRuntimeDead(it);
+    if (!claim) return it;
+    if (AT_LEAST_MAJOR.has(String(it.severity || '').toLowerCase())) return it;
+    changed = true;
+    return {
+      ...it,
+      severity: 'major',
+      severity_reported: it.severity,
+      severity_floor: 'runtime_dead',
+      severity_floor_claim: claim,
+    };
+  });
+  return changed ? out : issues;
+}
+
+module.exports = { deadFeatureClaim, issueClaimsRuntimeDead, applyDeadFeatureFloor };

package/modules/grading/grader-score.js

@@ -14,6 +14,7 @@ const fs = require('node:fs');
 const { DEFAULT_GRADER_MODEL, FALLTHROUGH_CONFIDENCE, LOW_CONFIDENCE, THRESHOLD, VERSION, permissionPathCheck, routeRankCheck } = require('./grader-config.js');
 const { TRIVIAL_MAX_FILES, TRIVIAL_MAX_LINES, clamp, median, r1 } = require('./grader-model.js');
 const { extractJson } = require('./grader-prompt.js');
+const { issueClaimsRuntimeDead } = require('./dead-feature-claim.js');
 
 function isNum(n) {
   return Number.isFinite(n);
@@ -480,6 +481,35 @@ function serverSideGuards(gradeResult, { committedFiles, builderRank, diffStats,
     implausiblePassWaived = 'panel_evidence';
   }
 
+  // --- Guard 2b: a finding that says the change does not run (task 1002665) ---
+  // On the task 1002648 ship the Quality worker wrote that the new code path was
+  // "entirely non-operational", filed it at `nit`, and the grade PASSed — the
+  // dead feature merged to main and was caught only because the builder happened
+  // to read the finding prose. Severity alone cannot fix that, because severity
+  // has no vote here: `passed` is computed from the rubric SCORES, so a major or
+  // blocker issue does not stop a passing grade by itself. This is the vote.
+  //
+  // Re-derived server-side from the submitted summaries rather than trusting the
+  // client's `severity_floor` marker — same posture as Guard 1, and the worker's
+  // floor is the honest-panel half of the same rule.
+  //
+  // It downgrades to CONCERNS, not fail: the classifier reads a model's prose, so
+  // a false positive should cost a human glance through manual-confirm rather
+  // than a hard FAIL and a paid re-grade. That is still enough to close the hole
+  // — 1002648 merged automatically, and a concerns verdict does not.
+  const deadClaims = (base.issues || [])
+    .map((it) => ({ it, claim: issueClaimsRuntimeDead(it) }))
+    .filter((x) => x.claim);
+  if (clientPassed && deadClaims.length) {
+    const { it, claim } = deadClaims[0];
+    const where = it.file ? ` in ${it.file}` : '';
+    guardsTripped.push({ guard: 'runtime_dead_finding', severity: 'major',
+      summary: `a ${it.severity_reported || it.severity || '?'}-severity finding${where} asserts the change does not run ("${claim}") — a passing grade over a self-reported dead feature must be human-confirmed` });
+    extraIssues.push({ severity: 'major', file: it.file || '(grade)', worker: 'server-runtime-dead', summary:
+      `[server runtime-dead] the panel's own words say this does not run ("${claim}"); severity was reported as ${it.severity_reported || it.severity || '?'}` });
+    if (downgradeTo !== 'fail') downgradeTo = 'concerns';
+  }
+
   // --- Guard 3: bound the credit/achievement signals (SR-18) ---
   // The net-negative "Subtractor" bonus + shipper badges key off client-supplied
   // signals.diff_stats + committed_files the server can't re-derive. We can't
@@ -517,7 +547,7 @@ function serverSideGuards(gradeResult, { committedFiles, builderRank, diffStats,
       signals: {
         ...(base.signals || {}),
         server_guard: {
-          applied: ['route_rank', 'permission_path', 'permission_path_unprovable', 'implausible_pass', 'forged_net_negative'],
+          applied: ['route_rank', 'permission_path', 'permission_path_unprovable', 'implausible_pass', 'runtime_dead_finding', 'forged_net_negative'],
           ok: true,
           tripped: [],
           // task 1002658 / ADR 0164: the audit trail records WHY a zero-issue
@@ -556,7 +586,7 @@ function serverSideGuards(gradeResult, { committedFiles, builderRank, diffStats,
       // body already ran; this is the authoritative post-hoc adjustment).
       confidence: forwardedConfidence,
       server_guard: {
-        applied: ['route_rank', 'permission_path', 'permission_path_unprovable', 'implausible_pass', 'forged_net_negative'],
+        applied: ['route_rank', 'permission_path', 'permission_path_unprovable', 'implausible_pass', 'runtime_dead_finding', 'forged_net_negative'],
         ok: guardsTripped.length === 0,
         downgraded_to: downgradeTo,
         client_passed: clientPassed,

package/modules/grading/grader-workers/worker-verdict.js

@@ -9,6 +9,8 @@
 // (the audit's explicit warning). Behavior-neutral: the objects produced here
 // are identical (same keys, same order, same values) to the inlined copies.
 
+const { applyDeadFeatureFloor } = require('../dead-feature-claim.js');
+
 // The { verdict:'fail', scores:{}, confidence:0, ... } shape every error
 // short-circuit returns. `issues` defaults to [] (the subprocess_error and
 // parse_error paths) and is the parsed issues array on the schema_error path
@@ -19,13 +21,21 @@ function failResult({ notesMd, error, issues = [] }) {
 
 // The three identical extractions every worker does after the parse guard:
 // confidence (null-tolerant), the bounded issues array, and the subagent notes.
+//
+// The issues array also passes the runtime-dead floor (task 1002665): a worker
+// that writes "the feature is entirely non-operational" and files it at `nit`
+// has contradicted itself, and on the task 1002648 ship that contradiction is
+// what let a dead feature merge. Raising it HERE, at the one place all four
+// workers parse their own output, means the worker's own downstream logic —
+// applySeverityGatePolicy below, which asks whether a fail is backed by a
+// major/blocker — sees the corrected severity rather than the reported one.
 function parseCommon(parsed) {
   const conf = parsed.confidence == null
     ? null
     : Number.isFinite(Number(parsed.confidence)) ? Number(parsed.confidence) : null;
-  const issues = Array.isArray(parsed.issues)
+  const issues = applyDeadFeatureFloor(Array.isArray(parsed.issues)
     ? parsed.issues.filter((i) => i && typeof i === 'object').slice(0, 50)
-    : [];
+    : []);
   const notesFromSubagent = typeof parsed.notes_md === 'string' ? parsed.notes_md : '';
   return { conf, issues, notesFromSubagent };
 }