@bongos/core 1.19.332 → 1.19.334

package/modules/grading/grader.js

@@ -82,1294 +82,12 @@ const path = require('node:path');
 const fs = require('node:fs');
 const { spawn } = require('node:child_process');
 
-const RUBRIC = JSON.parse(
-  fs.readFileSync(path.join(__dirname, 'grader-rubric.json'), 'utf8')
-);
+const { ASSUMED_BUILDER_MODEL, DEFAULT_GRADER_MODEL, DEFAULT_SHOTS, FALLTHROUGH_CONFIDENCE, RUBRIC, THRESHOLD, V1, V3, VERSION, api, generatedProvenance, permissionPathPrePass, routeRankPrePass, workers } = require('./grader-config.js');
+const { clamp, isTrivialDiff, median, r1, selectGraderModel, workerModelFor } = require('./grader-model.js');
+const { buildPrompt, extractJson } = require('./grader-prompt.js');
+const { aggregateShots, changeMagnitude, hasPanelEvidence, isSubstantiveIssue, serverSideGuards, validateAndScore } = require('./grader-score.js');
+const { buildContextBundle, diffAddedLinesByFile, extractAssistantResult, extractCostUsd, runOneShot, runSubagent, runSubagentCached } = require('./grader-subagent.js');
 
-// V4 = the active panel-based gate. V3 / V1 are kept under their fields for
-// the two paths that still read them: V3 = the trivial-diff multi-shot grader
-// (ship.js #513), V1 = the audit-ships.js retroactive deterministic path. The
-// v2 binding + its rubric block were dead (no reader) and removed in task 466.
-const V4 = RUBRIC.v4;
-const V3 = RUBRIC.v3;
-const V1 = RUBRIC.v1;
-const THRESHOLD = V4.threshold;
-const VERSION = V4.version;
-const LOW_CONFIDENCE = V4.low_confidence_threshold;
-// DEFAULT_SHOTS is kept for the v3 multi-shot path (still exported for
-// diagnostics); v4 doesn't use shots — it uses workers.
-const DEFAULT_SHOTS = V3.shots || 3;
-const ASSUMED_BUILDER_MODEL = V4.assumed_builder_model || 'claude-fable-5';
-const DEFAULT_GRADER_MODEL = V4.default_model || 'claude-sonnet-5';
-const FALLTHROUGH_CONFIDENCE = V4.fallthrough_confidence ?? 0.3;
-// task 1002660: per-worker model tier overrides (rubric-configured). The
-// Quality worker was 41% of panel spend with 75% nit findings — its cq/economy
-// judgment doesn't need the full cross-model tier. Keys are worker kinds;
-// values are model ids. workerModelFor guards the cross-model invariant.
-const WORKER_MODEL_TIERS = V4.worker_model_tiers || {};
-const workers = require('./grader-workers');
-const generatedProvenance = require('./generated-provenance'); // task 1002795
-// Carved into modules/grading/ (BV1.R73 / ADR 0091 §1+§4): the two deterministic
-// trust classifiers are KERNEL (KERNEL_FILES, R70) — reached through the doorway,
-// never a deep core require. The worker panel + extract-json are intra-module.
-const api = require('../../src/module-api');
-const routeRankCheck = api.routeRankCheck;
-const permissionPathCheck = api.permissionPathCheck;
-
-// Deterministic pre-pass: the sub-Metic permission-path gate (SEC #863). Runs
-// ONLY when the change set touches a permission-sensitive path AND the builder
-// rank resolves below Metic — otherwise null (zero cost / no finding). Like the
-// route-rank pre-pass, the result is a pseudo-worker appended to the panel so
-// aggregatePanel's any-fail gate hard-fails a sub-Metic ship of protected code
-// with no gate-logic change. builderRank comes from the caller's live /me read
-// (ship.js) or req.builder.rank (server); unknown rank fails OPEN here (the
-// post-push main audit, which reads the real author rank from the DB, owns the
-// unknown/dishonest case).
-function permissionPathPrePass(changedFiles, builderRank) {
-  const result = permissionPathCheck.checkPermissionPaths({ changedFiles, builderRank });
-  if (!result.hardFail) return null;
-  return { findings: result.findings, workerResult: permissionPathCheck.toWorkerResult(result) };
-}
-
-// Deterministic pre-pass: the route-rank invariant (#475 / C7). Runs ONLY when
-// a src/bongos/routes/ file is in the change set (zero cost otherwise). Returns
-// the findings (fed to the Hacker worker as input) plus a pseudo-worker result
-// appended to the panel so aggregatePanel's any-fail gate handles it directly.
-// Shared verbatim by gradeSubagent (ship-time) and conductor-dispatch.js
-// (mid-flight) so the route-parsing logic lives in exactly one place.
-function routeRankPrePass(changedFiles) {
-  const touched = (changedFiles || []).some((f) => routeRankCheck.ROUTE_FILE_RE.test(f));
-  if (!touched) return null;
-  const result = routeRankCheck.checkRouteRanks();
-  return { findings: result.findings, workerResult: routeRankCheck.toWorkerResult(result) };
-}
-
-function r1(n) {
-  return Math.round(Number(n) * 10) / 10;
-}
-
-function clamp(n, lo, hi) {
-  return Math.max(lo, Math.min(hi, n));
-}
-
-function median(arr) {
-  const v = arr.filter((n) => Number.isFinite(n)).slice().sort((a, b) => a - b);
-  if (v.length === 0) return null;
-  const mid = Math.floor(v.length / 2);
-  return v.length % 2 ? r1(v[mid]) : r1((v[mid - 1] + v[mid]) / 2);
-}
-
-// ---------- v4.1: trivial-diff fast-path (#513) ----------
-//
-// The #506 post-mortem: a +1/-1 welcome-copy tweak ran the full 4-worker
-// adversarial Opus/Sonnet panel — disproportionate cost for a one-word change.
-// isTrivialDiff classifies a change as "copy/docs only, small, and touching no
-// logic path". ship.js routes those to a SINGLE generalist grader shot instead
-// of the panel ("lighter, not skipped" — the 1-shot still scores ff+cq+economy
-// +confidence so the server gate applies, and the deterministic scanner + smoke
-// + route-rank checks run regardless). Everything else keeps the full panel.
-//
-// Deliberately conservative — defaults to "not trivial" (full panel) whenever
-// in doubt (missing diffStats, zero files, any logic-path file, oversized diff).
-const TRIVIAL_MAX_FILES = 3;
-const TRIVIAL_MAX_LINES = 30;
-// Copy/docs/front-end surfaces eligible for the lighter single-shot grade.
-// (Both web surfaces moved under modules/<key>/public/: the status dashboard to
-// modules/status-ui/public/ in BV1.R84 and the hall to modules/hall-ui/public/ in
-// BV1.R85.)
-const TRIVIAL_PATH_RE = /(?:^|\/)[^/]+\.md$|^docs\/|^public\/|^modules\/hall-ui\/public\/|^modules\/status-ui\/public\//;
-// Logic / infra / test surfaces that force the full panel even on a tiny diff —
-// these are where a subtle one-liner can do real damage, so they never qualify.
-const LOGIC_PATH_RE = /^src\/|^scripts\/|^migrations\/|^server\.js$|^tests\/|^\.claude\//;
-// Executable code AND config are NEVER trivial, even under public*/ (#513
-// Hacker). A copy tweak and an XSS / client-authz regression are
-// indistinguishable to a path+size heuristic, and the builders-hall + game
-// front-ends carry auth flows and game logic — so any code extension forces the
-// full adversarial panel. Config/data files (.json/.yaml/.env/…) are excluded
-// too: a client-side config change is security-relevant and shouldn't get the
-// lighter shot. Only genuinely static content (markdown, CSS/HTML, images,
-// plain text) takes the single shot.
-// HTML and SVG are executable in a browser (inline <script>, on* handlers,
-// <svg onload>), so they are NOT "static" for grading purposes — a small
-// edit could introduce client-side XSS that only the full panel's Hacker
-// would catch. Excluded alongside code + config (#513 Hacker).
-const NON_TRIVIAL_EXT_RE = /\.(?:js|mjs|cjs|jsx|ts|tsx|py|sh|bash|rb|go|sql|json|ya?ml|toml|ini|env|html?|svg)$|(?:^|\/)\.env(?:\.|$)/;
-
-function isTrivialDiff({ changedFiles, diffStats } = {}) {
-  if (!diffStats || typeof diffStats !== 'object') return false;
-  const files = Array.isArray(changedFiles) ? changedFiles.filter(Boolean) : [];
-  if (files.length === 0) return false;
-  const fc = Number(diffStats.files_changed);
-  const lines = (Number(diffStats.lines_added) || 0) + (Number(diffStats.lines_removed) || 0);
-  // Cap on BOTH the shortstat count and the actual file-list length — a rename
-  // can disagree between the two, so take the stricter of the two (#513 nit).
-  if (!Number.isFinite(fc) || fc <= 0 || fc > TRIVIAL_MAX_FILES) return false;
-  if (files.length > TRIVIAL_MAX_FILES) return false;
-  if (lines <= 0 || lines > TRIVIAL_MAX_LINES) return false;
-  // Every changed file must be a copy/docs path, none in a logic path, and none
-  // an executable-code or config file (those always get the full panel).
-  return files.every((f) =>
-    TRIVIAL_PATH_RE.test(f) && !LOGIC_PATH_RE.test(f) && !NON_TRIVIAL_EXT_RE.test(f));
-}
-
-// ---------- v3: cross-family model selection (ADR 0024) ----------
-
-// Returns the grader model given the builder's model — a DIFFERENT model from
-// the builder is the cross-model adversarial guarantee (ADR 0024). With no
-// builderModel the caller assumes the owner-top-model builder (CLAUDE.md §2),
-// resolving to the default grader — the path selectGraderModel({}) takes.
-//
-// task 1002659 (Claude 5 refresh): top-tier builders (fable/mythos, opus)
-// grade on the current mid tier; sonnet/haiku builders grade on the tier
-// above. #117's throw-on-unknown is reversed: the throw fired INSIDE the
-// grade step, stranding any ship whose builder id lacked an opus/sonnet/haiku
-// substring (claude-fable-5 was exactly that) — a worse failure than the
-// misconfiguration it guarded. Unknown ids now warn loudly and grade on
-// DEFAULT_GRADER_MODEL; the id still reaches signals.builder_model_assumed,
-// so /grader-health can spot the drift.
-function selectGraderModel({ builderModel } = {}) {
-  const bm = (builderModel || ASSUMED_BUILDER_MODEL).toLowerCase();
-  if (bm.includes('fable') || bm.includes('mythos')) return 'claude-sonnet-5';
-  if (bm.includes('opus')) return 'claude-sonnet-5';
-  if (bm.includes('sonnet')) return 'claude-opus-5';
-  if (bm.includes('haiku')) return 'claude-opus-5';
-  console.error(
-    `selectGraderModel: unrecognized builder model ${JSON.stringify(builderModel)} — ` +
-    `no 'fable'/'mythos'/'opus'/'sonnet'/'haiku' token; grading on the default ` +
-    `${DEFAULT_GRADER_MODEL} (cross-model unverifiable — task 1002659, was a #117 throw)`
-  );
-  return DEFAULT_GRADER_MODEL;
-}
-
-// task 1002660: resolve one worker's model — the rubric tier override when one
-// exists, else the panel's cross-model pick. The override is refused (falls
-// back to graderModel) when it lands on the BUILDER's own family: tiering is
-// a cost lever, never a hole in the ADR 0024 cross-model guarantee.
-const MODEL_FAMILY_TOKENS = ['fable', 'mythos', 'opus', 'sonnet', 'haiku'];
-function workerModelFor(kind, graderModel, builderModel) {
-  const tier = WORKER_MODEL_TIERS[kind];
-  if (!tier) return graderModel;
-  const bm = String(builderModel || ASSUMED_BUILDER_MODEL).toLowerCase();
-  const tierFamily = MODEL_FAMILY_TOKENS.find((t) => String(tier).toLowerCase().includes(t));
-  if (tierFamily && bm.includes(tierFamily)) return graderModel;
-  return tier;
-}
-
-// ---------- v3: prompt builder (default-fail framing) ----------
-
-// The instance's project name, injected into the grader's identity line so a
-// non-OTB Cloud Bongos instance is graded against ITS OWN project, never a
-// hardcoded "Off the Boats" (ADR 0062 §3/§5; the branding contract's
-// llmProjectName field). Reached through the doorway like every other host-
-// context read in this module — never a deep core require. Resolved once at
-// module load (the brand is a per-process singleton); falls back to a neutral
-// phrase if branding fails to resolve so the gate never crashes on a config error.
-const LLM_PROJECT = (() => {
-  try { return api.branding().llmProjectName || 'this project'; }
-  catch { return 'this project'; }
-})();
-
-const PROMPT_HEADER = `You are an adversarial code-review subagent for the ${LLM_PROJECT} project. You are reviewing one shipped change to decide whether it deserves to ship.
-
-Your job is to FIND WHAT IS WRONG with this change. **The default verdict is FAIL.** To return a PASS, you must affirmatively conclude — after a careful read of the diff and (using your Read tool) the relevant post-merge files — that no material problems remain.
-
-Begin by hunting for these specific failure modes. When you find one, CITE the diff line or name the failing acceptance criterion:
-
-- TODOs, FIXMEs, "for now", "temporary" or "stub" comments left in shipped code.
-- Hardcoded shortcuts: assuming one builder, one user, one project root, one tenant, one environment, or one identity. Look for literal "lars", "lars589", absolute /Users paths, hardcoded ports, hardcoded IDs.
-- Scope gaps: acceptance criteria in the description that the diff DOES NOT satisfy. Read the description's "Acceptance" section line by line.
-- Demo / dummy / mock code that lies: returns a fixed value, fakes a successful result, mocks at the wrong layer, or pretends to call something it doesn't.
-- Missing tests for new logic: any non-trivial new function, route handler, branch, or aggregation that ships without a covering test.
-- Broken invariants: methodology rules in CLAUDE.md, cross-verified Python/JS autotile lookups, ground-vs-object cell split per ADR 0012, the "every change is backed by a claimed GDS task" rule, the trust-boundary rule per ADR 0016 ("server-enforced permissions"), the no-hardcoded-Archon-identity rule per V3.R12 #236.
-- Dead code: helpers, exports, branches, or files added but never called from anywhere in the post-merge tree. Use Read on the receiving site if unsure.
-- Reads/writes outside the declared touches[]: if the diff edits files the task didn't claim, that's a scope creep — call it out.
-
-You return three scores (0-10), notes, an issues array, and a confidence value:
-
-1. functional_fidelity (0-10): did the diff implement what the description scoped? 10 = every acceptance criterion satisfied by code or explicitly out-of-scope per the description. 6 = mostly there with one NAMED gap. Below 6 = scope gaps, broken acceptance criteria, or demo code that lies.
-2. code_quality (0-10): is the code well-written for THIS codebase? 10 = production-quality, would-merge-without-comment. 6 = ships but with a clear improvement a reviewer would suggest. Below 6 = broken style, dead code, broken invariants, missing tests where warranted.
-3. economy (0-10, ADVISORY): is the change as small and simple as the task warrants? 10 = minimal and focused. 6 = a bit more than necessary. Below 6 = bloated, speculative abstraction, duplicated logic.
-
-**The hard gate** (applied downstream, you do not enforce it yourself; just score honestly): functional_fidelity >= 6 AND code_quality >= 6 AND confidence >= 0.4. Below 6 on either axis is a FAIL. Economy is advisory only.
-
-**For every issue you list:** include severity (blocker | major | minor | nit), the file path, and a one-line summary that quotes the offending diff line or names the failing acceptance criterion. Vague summaries like "code quality could be better" are not acceptable — be specific or omit it.
-
-**Sanity checks:**
-- A PASS with no issues[] entries is suspicious. If you found nothing material wrong, briefly say WHY in notes_md: which acceptance criteria you verified, which files you Read, which could-have-gone-wrong didn't.
-- A FAIL with no issues[] entries is invalid. At least one concrete issue must explain the verdict.
-- A score below 6 with no issue at severity major or blocker is inconsistent — name the major problem.
-
-**Confidence:** 0-1, your self-reported confidence in your two scores. If you cannot judge (description too vague to grade against, diff too large to fit comfortably in context, key context missing), set confidence LOW (< 0.4). Low confidence falls through to manual confirm — be honest about uncertainty rather than guessing.
-
-Return ONLY JSON matching this schema — no prose before or after, no markdown fences:
-{
-  "functional_fidelity": <number 0-10>,
-  "code_quality":        <number 0-10>,
-  "economy":             <number 0-10>,
-  "notes_md":            <string>,
-  "confidence":          <number 0-1>,
-  "issues": [{"severity": "blocker"|"major"|"minor"|"nit", "file": <path>, "summary": <string>}, ...]
-}
-
-You have a Read tool. Spend reads checking that removed code is unreferenced elsewhere, that new helpers match surrounding style, that the diff's value_summary matches what the diff actually does, and that acceptance criteria you can't verify from the diff alone are actually satisfied in the post-merge file. Do not run tests, do not edit files, do not call the network.`;
-
-function buildPrompt({ task, valueSummary, diff, changedFiles, diffStats, generatedProvenance: prov = null }) {
-  const t = task || {};
-  const desc = (t.description || '(no description)').trim();
-  const title = (t.title || '(no title)').trim();
-  const vs = (valueSummary || '(no value summary)').trim();
-  const files = Array.isArray(changedFiles) ? changedFiles : [];
-  const diffText = (diff || '(empty diff)').trim();
-
-  const lines = [];
-  lines.push(PROMPT_HEADER);
-  lines.push('');
-  lines.push('---');
-  lines.push('## Task');
-  lines.push('');
-  lines.push(`**ID:** ${t.id ?? '(unknown)'}`);
-  lines.push(`**Title:** ${title}`);
-  lines.push(`**Kind:** ${t.kind ?? 'unclassified'}  ·  **Discipline:** ${t.discipline ?? 'unclassified'}`);
-  lines.push(`**Estimated effort:** ${t.est_minutes != null ? `${t.est_minutes} min` : '(not estimated)'}  — use this to judge whether the diff size is proportionate to the work scoped.`);
-  if (t.version_id) lines.push(`**Version:** ${t.version_id}`);
-  lines.push('');
-  lines.push('**Description:**');
-  lines.push('');
-  lines.push(desc);
-  lines.push('');
-  lines.push('---');
-  lines.push('## Builder\'s value summary');
-  lines.push('');
-  lines.push(vs);
-  lines.push('');
-  lines.push('---');
-  lines.push(`## Changed files (${files.length})`);
-  lines.push('');
-  for (const f of files) lines.push(`- ${f}`);
-  if (files.length === 0) lines.push('(no files changed — this is suspicious)');
-  lines.push('');
-  lines.push('You can Read any of these files to see their post-merge state.');
-  lines.push('');
-  lines.push('---');
-  lines.push('## Diff size (for the economy axis)');
-  lines.push('');
-  if (diffStats && typeof diffStats === 'object') {
-    const fc = diffStats.files_changed ?? '?';
-    const la = diffStats.lines_added ?? '?';
-    const lr = diffStats.lines_removed ?? '?';
-    lines.push(`- files changed: ${fc}`);
-    lines.push(`- lines added: ${la}`);
-    lines.push(`- lines removed: ${lr}`);
-    lines.push('');
-    lines.push('Weigh this against the task description, kind, and estimated effort above when scoring economy. A diff much larger than the scoped work warrants — or one padded with speculative abstraction, duplication, or dead code — should score low on economy.');
-  } else {
-    lines.push('(diff stats unavailable — score economy from the diff itself.)');
-  }
-  lines.push('');
-  lines.push('---');
-  lines.push('## Unified diff');
-  lines.push('');
-  lines.push('```diff');
-  lines.push(diffText);
-  lines.push('```');
-  lines.push('', ...(prov ? [generatedProvenance.provenanceSection(prov)].filter(Boolean) : [])); // task 1002795 — the trivial path is where a docs-only ship lands
-  lines.push('Now grade. Default-fail unless your read of the diff and post-merge files turns up no material problems. Output ONLY the JSON object — nothing before or after it.');
-  return lines.join('\n');
-}
-
-// ---------- v3: per-shot validator (same as v2 logic) ----------
-
-// Tries to extract a JSON object from a subagent response. The subagent is
-// instructed to return ONLY JSON, but in practice models sometimes wrap it
-// in markdown fences or add a line of prose. Be tolerant.
-// #79 (#380, completed #493): robust JSON extraction now lives in the shared
-// leaf module so grader.js AND every worker module use ONE implementation.
-// Re-exported here for back-compat (validateAndScore + tests use
-// grader.extractJson).
-const { extractJson } = require('./grader-workers/extract-json');
-
-function isNum(n) {
-  return Number.isFinite(n);
-}
-
-// #1002653 corroboration helpers for validateAndScore's null-ff lens branch.
-// A worker entry is untrusted input — w.issues may be any shape. Absent issues
-// on an errored worker is the normal outage shape (treated as none); a truthy
-// NON-ARRAY issues is malformed and must DISQUALIFY corroboration (fail-closed
-// schema_error downstream), never TypeError into a 500 on grade submission.
-const isNarcErroredClean = (w) => {
-  if (!w || w.kind !== 'narc' || !w.error) return false;
-  const issues = w.issues == null ? [] : w.issues;
-  if (!Array.isArray(issues)) return false;
-  return !issues.some((i) => i && (i.severity === 'blocker' || i.severity === 'major'));
-};
-const isNarcHealthy = (w) => !!w && w.kind === 'narc' && !w.error;
-
-// task 1002658 (ADR 0164): a SUBSTANTIVE issue is one a real panel emits — a
-// known severity + a non-empty summary. The old plausibility guard counted raw
-// issues[].length, so one fabricated `{}` defeated it; substance-counting
-// closes that lazy-forgery class using only the submitted body itself.
-const ISSUE_SEVERITIES = new Set(['blocker', 'major', 'minor', 'nit']);
-function isSubstantiveIssue(it) {
-  return !!it && typeof it === 'object'
-    && ISSUE_SEVERITIES.has(String(it.severity || '').toLowerCase())
-    && typeof it.summary === 'string' && it.summary.trim().length > 0;
-}
-
-// task 1002658 (ADR 0164): does the submitted signals block carry the full
-// per-worker shape a real panel run produces — ≥3 workers, each with a kind
-// and a legal verdict (or an error tag)? Client-forgeable like every
-// grade-time input (the ADR's documented honor-system residual for Metic+);
-// its job is separating "the panel ran and unanimously found nothing" (the
-// guard's confirmed false-positive class) from "no evidence at all".
-const WORKER_VERDICTS = new Set(['pass', 'concerns', 'fail']);
-function hasPanelEvidence(signals) {
-  const ws = Array.isArray(signals?.workers) ? signals.workers : null;
-  if (!ws || ws.length < 3) return false;
-  return ws.every((w) => !!w && typeof w === 'object'
-    && typeof w.kind === 'string' && w.kind.trim().length > 0
-    && (WORKER_VERDICTS.has(String(w.verdict || '').toLowerCase()) || !!w.error));
-}
-
-// Validates ONE shot's subagent JSON and produces a per-shot grade-result.
-// Never throws — malformed inputs produce a passed=false result with notes_md.
-// The downstream aggregateShots collapses N of these into a final verdict.
-function validateAndScore(rawSubagent, meta = {}) {
-  const parsed =
-    typeof rawSubagent === 'string' ? extractJson(rawSubagent) : rawSubagent;
-
-  const signals = {
-    grader_kind: 'subagent',
-    grader_version: VERSION,
-    model: meta.model || DEFAULT_GRADER_MODEL,
-    threshold: THRESHOLD,
-    ...meta,
-  };
-
-  if (!parsed || typeof parsed !== 'object') {
-    return {
-      score: 0,
-      passed: false,
-      threshold: THRESHOLD,
-      grader_kind: 'subagent',
-      grader_version: VERSION,
-      rubric_scores: {},
-      signals: { ...signals, parse_error: true },
-      notes_md: `Subagent grader ${VERSION}: could not parse subagent output as JSON.`,
-      issues: [],
-    };
-  }
-
-  // #1002653: Number(null) === 0, so an errored ADVISORY Narc forwarding an
-  // EXPLICIT ff:null fabricated "FAIL — functional_fidelity below 6" at
-  // (0+cq)/2. Explicit null = the lens did not run (the #395 confidence
-  // precedent): gate/score on the axes that ran. A bare null is NOT enough —
-  // a prompt-injected Narc emitting null must stay fail-closed — so the branch
-  // needs POSITIVE corroboration: workers[] carries an errored
-  // no-substantive-finding Narc (#473 missing-signal semantics) and no healthy
-  // Narc. Empty/narc-less/absent workers, ABSENT ff, and every other shape
-  // fall through to the fail-closed schema_error below. Quality has no such
-  // branch — gating lens, absence stays fail-closed.
-  // Trust note: workers[] is client-supplied like every SR-9 grade input — a
-  // forger gains nothing here they cannot get by sending ff:9 directly; the
-  // server-derivable-signals redesign is tracked separately (SR-9 residual).
-  const metaWorkers = Array.isArray(meta.workers) ? meta.workers : null;
-  const narcMissingSignal = !!metaWorkers &&
-    metaWorkers.some(isNarcErroredClean) && !metaWorkers.some(isNarcHealthy);
-  const ffExplicitNull = parsed.functional_fidelity === null;
-  const ffLensUnavailable = ffExplicitNull && narcMissingSignal;
-  const ff = ffExplicitNull ? null : Number(parsed.functional_fidelity);
-  const cq = Number(parsed.code_quality);
-  const economyRaw = Number(parsed.economy);
-  const economy =
-    isNum(economyRaw) && economyRaw >= 0 && economyRaw <= 10 ? economyRaw : null;
-  // MAS Phase 2.5 (#423): security_score (from Hacker, Phase 2.1) and
-  // efficiency_score (from Efficiency Monger, Phase 2.2). Both ADVISORY —
-  // recorded in rubric_scores but do not independently gate the ship. Same
-  // back-compat shape as economy: out-of-range / non-numeric / missing →
-  // recorded as null, no penalty. Older callers that don't forward these
-  // fields grade exactly as before.
-  const securityRaw = Number(parsed.security_score);
-  const securityScore =
-    isNum(securityRaw) && securityRaw >= 0 && securityRaw <= 10 ? securityRaw : null;
-  const efficiencyRaw = Number(parsed.efficiency_score);
-  const efficiencyScore =
-    isNum(efficiencyRaw) && efficiencyRaw >= 0 && efficiencyRaw <= 10 ? efficiencyRaw : null;
-  // Treat null/undefined confidence as ABSENT, not as 0. Number(null) === 0,
-  // and isNum(0) === true — a naive `isNum(Number(parsed.confidence))` check
-  // would accept null as a valid low-confidence signal and FAIL the ship for
-  // a missing field. The MAS Phase 1 self-ship (#395) hit this exactly when
-  // aggregateShots forwarded a null top-level confidence to the server's
-  // validateAndScore. Explicit null-check first; coerce only when present.
-  const confidence = parsed.confidence == null
-    ? null
-    : isNum(Number(parsed.confidence)) ? Number(parsed.confidence) : null;
-  const issues = Array.isArray(parsed.issues)
-    ? parsed.issues.filter((it) => it && typeof it === 'object').slice(0, 50)
-    : [];
-  const notesFromSubagent = typeof parsed.notes_md === 'string' ? parsed.notes_md : '';
-
-  signals.confidence = confidence;
-  signals.issue_count = issues.length;
-  if (ffLensUnavailable) signals.ff_lens_unavailable = true;
-
-  if ((!ffLensUnavailable && (!isNum(ff) || ff < 0 || ff > 10)) || !isNum(cq) || cq < 0 || cq > 10) {
-    return {
-      score: 0,
-      passed: false,
-      threshold: THRESHOLD,
-      grader_kind: 'subagent',
-      grader_version: VERSION,
-      rubric_scores: {},
-      signals: { ...signals, schema_error: true },
-      notes_md: `Subagent grader ${VERSION}: subagent returned scores outside [0,10] or non-numeric. Got functional_fidelity=${parsed.functional_fidelity}, code_quality=${parsed.code_quality}.`
-        + (ffExplicitNull && !narcMissingSignal
-          ? ' Explicit null functional_fidelity without a corroborated Narc outage in signals.workers is fail-closed.'
-          : ''),
-      issues,
-    };
-  }
-
-  const ffR = ffLensUnavailable ? null : r1(clamp(ff, 0, 10));
-  const cqR = r1(clamp(cq, 0, 10));
-  const economyR = economy != null ? r1(clamp(economy, 0, 10)) : null;
-  const securityR = securityScore != null ? r1(clamp(securityScore, 0, 10)) : null;
-  const efficiencyR = efficiencyScore != null ? r1(clamp(efficiencyScore, 0, 10)) : null;
-  const economyPenalty =
-    economyR != null ? Math.max(0, (THRESHOLD - economyR) / 2) : 0;
-  const cqEffective = economyR != null ? r1(clamp(cqR - economyPenalty, 0, 10)) : cqR;
-  // With the ff lens out, the score reflects only the axis that ran — never a
-  // blend with a synthetic 0 (the fabricated 4.5/10) or a synthetic threshold.
-  const blended = ffLensUnavailable ? cqR : r1((ffR + cqR) / 2);
-
-  // confidence must be present (not null) for a PASS. A subagent that omits
-  // confidence entirely silently bypassed the low-confidence gate under the
-  // old `confidence != null && confidence < LOW_CONFIDENCE` check — null made
-  // lowConfidence=false and let high ff/cq scores through unchecked (#489 / #56).
-  // Distinguishing "absent" from "low" gives a clear verdict message and leaves
-  // the aggregateShots #395 fix intact: shots that omit confidence now FAIL here,
-  // so aggregateShots can never reach unanimousPASS with a null confidenceMedian.
-  const confidenceAbsent = confidence === null;
-  const lowConfidence = !confidenceAbsent && confidence < LOW_CONFIDENCE;
-  // ffR is null when the lens is unavailable — it must not fail the gate
-  // (null < THRESHOLD is true via JS coercion), and must not appear in the
-  // verdict's below-threshold branches.
-  const ffBelow = !ffLensUnavailable && ffR < THRESHOLD;
-  const bothPass = !ffBelow && cqR >= THRESHOLD;
-  const passed = bothPass && !lowConfidence && !confidenceAbsent;
-
-  const verdict = passed
-    ? 'PASS'
-    : confidenceAbsent
-      ? 'FAIL — confidence absent'
-      : lowConfidence
-        ? 'FAIL — low confidence'
-        : bothPass
-          ? 'FAIL'
-          : ffBelow && cqR < THRESHOLD
-            ? `FAIL — both axes below ${THRESHOLD}`
-            : ffBelow
-              ? `FAIL — functional_fidelity below ${THRESHOLD}`
-              : `FAIL — code_quality below ${THRESHOLD}`;
-
-  const notesLines = [];
-  notesLines.push(`Shot ${signals.shot_index != null ? signals.shot_index : '?'} (${signals.model}) — ${verdict}`);
-  notesLines.push(`  ff=${ffLensUnavailable ? 'n/a (lens unavailable)' : `${ffR}/10`}  cq=${cqR}/10${economyR != null ? `  econ=${economyR}/10 (advisory)` : ''}  conf=${confidence ?? '?'}`);
-  if (notesFromSubagent) {
-    notesLines.push('');
-    notesLines.push(notesFromSubagent.trim());
-  }
-
-  return {
-    score: blended,
-    passed,
-    threshold: THRESHOLD,
-    grader_kind: 'subagent',
-    grader_version: VERSION,
-    rubric_scores: {
-      functional_fidelity: ffR,
-      code_quality: cqR,
-      economy: economyR,
-      code_quality_effective: cqEffective,
-      security_score: securityR,
-      efficiency_score: efficiencyR,
-    },
-    signals,
-    notes_md: notesLines.join('\n'),
-    issues,
-  };
-}
-
-// ---------- server-authoritative grade guards (SR-9 / SR-18 / F1 / G5) ----------
-//
-// THE FINDING (SR-9 / SR-18): POST /api/gds/tasks/:id/grade trusts the client.
-// validateAndScore only shape-validates the numbers — `passed` is computed from
-// the CLIENT's submitted scores. The real adversarial panel + the deterministic
-// route-rank / permission-path pre-passes run CLIENT-SIDE in scripts/gds/ship.js;
-// the server never re-runs them. So a builder can POST
-// {functional_fidelity:10, code_quality:10, confidence:1, issues:[]} to self-pass.
-// AND the credit/achievement side-effects (net-negative "Subtractor" bonus,
-// shipper badges) are driven by client-supplied signals.diff_stats +
-// committed_files the server never re-derives (SR-18).
-//
-// WHAT THE SERVER CAN AND CAN'T DO (the boundary — see report):
-//   * The web tier is checked out at `main`. The builder's feature-branch
-//     commits are NOT on the server at grade time (they only arrive when the
-//     task merges to main). So the server CANNOT independently re-derive the
-//     committed diff at the claimed head_sha. The diff, diff_stats, and
-//     committed_files in the request body remain CLIENT-SUPPLIED.
-//   * BUT the server DOES know the caller's LIVE, authoritative rank
-//     (req.builder.rank, read fresh from the DB per request — ADR 0016). So the
-//     deterministic permission-path pre-pass can run with a TRUSTED rank against
-//     the (client-supplied) committed_files — strictly raising the bar.
-//   * The route-rank pre-pass reads the route files in the server's OWN
-//     checkout (fs) — fully server-authoritative, independent of any client
-//     input. (NB: it audits `main`, not the feature branch — the post-push main
-//     audit owns feature-branch route changes. Re-running here still hard-fails
-//     a forged pass while `main` already carries an ungated write route.)
-//
-// THE GUARD (additive, fail-toward-reject-only): serverSideGuards re-runs the
-// two deterministic pre-passes server-side and applies plausibility/bounding
-// checks. It can ONLY downgrade a client PASS to a non-pass (hard FAIL or
-// manual-confirm); it NEVER upgrades a fail, never relaxes the existing gate,
-// and is a no-op on a client that already reported not-passed. A legitimate
-// honest grade is unaffected.
-//
-// The Archon / GRADER_BYPASS paths do not flow through /grade's passed-gate the
-// way an ordinary ship does (they confirm via /tasks/:id/confirm, which is a
-// separate route), so this guard does not touch them — see the route comment.
-
-// Plausibility threshold: a client PASS that reports NO issues on a NON-TRIVIAL
-// diff is not a credible adversarial-panel verdict — the panel is default-fail
-// and every worker must enumerate concrete issues before a pass; a clean pass on
-// a large diff with an empty issues[] is the exact shape of a forged
-// {ff:10,cq:10,issues:[]} self-pass (SR-9). We don't reject it outright (a small
-// honest change can legitimately have no issues) — we DOWNGRADE it to
-// manual-confirm so a human lands it via /confirm. Thresholds mirror the
-// trivial-diff fast-path's spirit (a change past these sizes is "real work"):
-//   - more than this many changed files, OR
-//   - more than this many added+removed lines
-// makes an empty-issues PASS implausible-as-automatic and forces manual-confirm.
-const IMPLAUSIBLE_PASS_MAX_FILES = TRIVIAL_MAX_FILES;   // 3 — same "small change" bar
-const IMPLAUSIBLE_PASS_MAX_LINES = TRIVIAL_MAX_LINES;   // 30
-
-// Re-derive the size of the change from the submitted committed_files +
-// diff_stats. Both are client-supplied (see boundary note) — we take the
-// STRICTER (larger) of the file-list length and the shortstat files_changed so a
-// forger can't shrink one to dodge the plausibility bar while the other betrays
-// a large diff. Returns { files, lines } with NaN coerced to 0.
-function changeMagnitude({ committedFiles, diffStats } = {}) {
-  const listLen = Array.isArray(committedFiles)
-    ? committedFiles.filter((f) => typeof f === 'string' && f.trim()).length
-    : 0;
-  const statFiles = diffStats && Number.isFinite(Number(diffStats.files_changed))
-    ? Number(diffStats.files_changed)
-    : 0;
-  const files = Math.max(listLen, statFiles);
-  const lines =
-    (Number(diffStats?.lines_added) || 0) + (Number(diffStats?.lines_removed) || 0);
-  return { files, lines };
-}
-
-// serverSideGuards — the server-authoritative hardening layer (SR-9 / SR-18).
-//
-// Inputs:
-//   gradeResult  — the output of validateAndScore on the SUBMITTED body. Its
-//                  `passed` is computed from the client's numbers. We may
-//                  override it (downgrade only).
-//   committedFiles — client-supplied list of committed paths (or null).
-//   builderRank  — the caller's LIVE rank (req.builder.rank — SERVER-KNOWN,
-//                  authoritative). Drives the permission-path pre-pass.
-//   diffStats    — client-supplied { files_changed, lines_added, lines_removed }
-//                  (gradeResult.signals.diff_stats if not passed explicitly).
-//   routesDir    — optional override for tests; defaults to the live routes dir.
-//
-// Returns a NEW grade-result (never mutates the input). When a guard trips, the
-// returned result has passed=false and a `server_guard` block in signals naming
-// every triggered guard + the residual notes. When no guard trips, the input is
-// returned with a passed-through `server_guard: { applied: [...], ok: true }`
-// audit marker so the trail shows the guards RAN (and found nothing) rather than
-// being silently absent.
-//
-// CONTRACT: downgrade-only. If the client already reported not-passed, we leave
-// it not-passed (no resurrection). We only ever flip true→false.
-function serverSideGuards(gradeResult, { committedFiles, builderRank, diffStats, routesDir } = {}) {
-  const base = gradeResult || {};
-  const ds = diffStats || base.signals?.diff_stats || null;
-  const guardsTripped = [];        // [{ guard, severity, summary }]
-  const extraIssues = [];          // surfaced into the result's issues[]
-  let downgradeTo = null;          // 'fail' | 'concerns' | null
-
-  // The guards only have teeth on a CLIENT PASS — a non-pass is already
-  // blocked/fallen-through by the existing gate, and downgrade-only means we
-  // never touch it. We still RUN the deterministic checks (their findings are a
-  // useful audit signal even on a fail) but only let them flip the verdict when
-  // base.passed === true.
-  const clientPassed = base.passed === true;
-
-  // --- Guard 1: deterministic pre-passes, server-side (SR-9 / F1) ---
-  // route-rank: reads the server's own route files (fs) — server-authoritative.
-  // permission-path: runs with the TRUSTED live rank against the (client) files.
-  // Either hard-fail flips a client PASS to a hard FAIL regardless of submitted
-  // scores — this is the core "re-run the deterministic checks server-side"
-  // hardening. A non-hardFail (e.g. an unclassified READ route → 'concerns') is
-  // recorded but does NOT block here: the client-side panel's Hacker already
-  // adjudicates read-route intent, and a server-side downgrade-to-concerns on a
-  // read route would be a behavior change with no SR-9 security value.
-  let routeRank = null;
-  try {
-    routeRank = routeRankCheck.checkRouteRanks(routesDir ? { routesDir } : {});
-  } catch (_) { routeRank = null; /* fs error → no server-side route finding; client panel + main audit still gate */ }
-  const permPath = permissionPathCheck.checkPermissionPaths({ changedFiles: committedFiles || [], builderRank });
-
-  if (routeRank && routeRank.hardFail) {
-    guardsTripped.push({ guard: 'route_rank', severity: 'blocker',
-      summary: 'server-side route-rank pre-pass hard-failed (an ungated write route exists) — a client PASS cannot override this (SR-9)' });
-    for (const f of routeRank.findings.filter((x) => x.severity === 'blocker')) {
-      extraIssues.push({ severity: 'blocker', file: f.file, summary: `[server route-rank] ${f.summary}`, worker: 'server-route-rank' });
-    }
-    if (clientPassed) downgradeTo = 'fail';
-  }
-  if (permPath && permPath.hardFail) {
-    guardsTripped.push({ guard: 'permission_path', severity: 'blocker',
-      summary: `server-side permission-path pre-pass hard-failed: rank '${builderRank}' is below Metic and the submitted committed_files touch protected machinery — a client PASS cannot override this (SR-9 / SEC #863)` });
-    for (const f of permPath.findings) {
-      extraIssues.push({ severity: 'blocker', file: f.file, summary: `[server permission-path] ${f.summary}`, worker: 'server-permission-path' });
-    }
-    if (clientPassed) downgradeTo = 'fail';
-  }
-
-  // --- Guard 1b: vacuous permission-path input (task 1002646 / report 1000021 G-1) ---
-  // The pre-pass above pairs the SERVER-known rank with CLIENT-supplied
-  // committed_files, so omitting the list (or sending []) made the sub-floor
-  // protected-path check pass VACUOUSLY — zero files, zero hits, hardFail:false —
-  // a trusted-rank check applied to an untrusted, omittable diff. The server
-  // still cannot re-derive the feature-branch diff at grade time (boundary note
-  // above; the task-1002645 published tip is recorded at ci-land, AFTER the
-  // grade), but it can refuse to treat "no input" as "no hits": a caller below
-  // the registry's lowest floor submitting NO file list makes the check
-  // UNPROVABLE → fail closed. Honest ships are unaffected (ship.js always sends
-  // the real committed list — task 878 — and a floor-clearing rank never enters
-  // this branch). The dishonest-LIST case (a sub-floor caller sending an
-  // innocuous list while touching protected paths) stays owned by gate-review CI
-  // + the post-push main audit, which read the REAL diff. Unknown rank keeps
-  // failing open at this layer (isBelowFloor → false) — the main audit reads the
-  // real author rank from the DB and owns that case, exactly as for the pre-pass.
-  const submittedFileCount = Array.isArray(committedFiles)
-    ? committedFiles.filter((f) => typeof f === 'string' && f.trim()).length
-    : 0;
-  if (permissionPathCheck.isBelowFloor(builderRank) && submittedFileCount === 0) {
-    // Resolve the floor label from the registry at runtime (the D-16/N-3
-    // stale-string rule) — never a hardcoded rank name.
-    const floorRank = Object.keys(permissionPathCheck.RANK_TIER)
-      .find((r) => permissionPathCheck.RANK_TIER[r] === permissionPathCheck.MIN_TIER) || 'the floor';
-    guardsTripped.push({ guard: 'permission_path_unprovable', severity: 'blocker',
-      summary: `rank '${builderRank}' is below the protected-path floor ('${floorRank}') and the grade submitted no committed_files — the permission-path check cannot run on an empty list, so a client PASS cannot stand (fail closed; task 1002646 / SR-9). Remedy: re-run the ship — ship.js submits the real committed file list; a genuinely file-less (DB-only) change needs a ${floorRank}+ builder to land it via /tasks/:id/confirm.` });
-    extraIssues.push({ severity: 'blocker', file: '(grade)', summary:
-      `[server permission-path] no committed_files submitted by a rank below the '${floorRank}' floor — the protected-path check is unprovable and fails closed (task 1002646)`, worker: 'server-permission-path' });
-    if (clientPassed) downgradeTo = 'fail';
-  }
-
-  // --- Guard 2: implausible client verdict (SR-9 / task 1002658, ADR 0164) ---
-  // Redesigned around what the submitted body itself can prove. The old form
-  // (raw issues.length === 0) was defeated by one fabricated `{}` AND fired on
-  // every honest unanimous zero-issue panel PASS (its only in-sample firings —
-  // eval 2-for-2, tasks 1002643 ×2 and 1002663 — were ALL false positives).
-  // Now: count only SUBSTANTIVE issues; a padded issues[] (entries but no
-  // substance) is the forgery signature and trips regardless of evidence; a
-  // genuinely empty issues[] trips only when the body ALSO lacks the full
-  // per-worker panel shape — a real panel that ran and unanimously found
-  // nothing is waived with an audit marker instead of a manual-confirm. The
-  // magnitude inputs remain client-supplied; the binding authority on the real
-  // diff is land-time (gate-review CI + post-push main audit) — ADR 0164.
-  const rawIssueCount = Array.isArray(base.issues) ? base.issues.length : 0;
-  const substantiveIssueCount = (Array.isArray(base.issues) ? base.issues : [])
-    .filter(isSubstantiveIssue).length;
-  const paddedIssues = rawIssueCount > 0 && substantiveIssueCount === 0;
-  const panelEvidence = hasPanelEvidence(base.signals);
-  const { files: changeFiles, lines: changeLines } = changeMagnitude({ committedFiles, diffStats: ds });
-  const nonTrivial = changeFiles > IMPLAUSIBLE_PASS_MAX_FILES || changeLines > IMPLAUSIBLE_PASS_MAX_LINES;
-  let implausiblePassWaived = null;
-  if (clientPassed && nonTrivial && substantiveIssueCount === 0 && (paddedIssues || !panelEvidence)) {
-    const shape = paddedIssues
-      ? `issues[] holds ${rawIssueCount} entr${rawIssueCount === 1 ? 'y' : 'ies'} with no substance (no known severity + summary) — the padded-issues forgery signature`
-      : 'empty issues[] with no per-worker panel evidence in signals';
-    guardsTripped.push({ guard: 'implausible_pass', severity: 'major',
-      summary: `client PASS on a non-trivial diff (${changeFiles} file(s), ${changeLines} line(s) > ${IMPLAUSIBLE_PASS_MAX_FILES}/${IMPLAUSIBLE_PASS_MAX_LINES}): ${shape} — not a credible default-fail panel verdict → manual-confirm (SR-9 / ADR 0164)` });
-    extraIssues.push({ severity: 'major', file: '(grade)', summary:
-      `[server plausibility] a passing grade with no substantive findings and no panel evidence on a ${changeFiles}-file / ${changeLines}-line change must be human-confirmed via /confirm`, worker: 'server-plausibility' });
-    if (downgradeTo !== 'fail') downgradeTo = 'concerns';
-  } else if (clientPassed && nonTrivial && rawIssueCount === 0 && panelEvidence) {
-    implausiblePassWaived = 'panel_evidence';
-  }
-
-  // --- 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
-  // make them server-authoritative without the feature-branch diff (residual,
-  // see report), but we CAN strip an OBVIOUSLY-FORGED net-negative claim:
-  // diff_stats that claims a net-negative (removed > added) while the submitted
-  // committed_files list is large is internally inconsistent with a real
-  // simplification, and is the cheap way to farm the Subtractor bonus. When the
-  // signals are internally implausible we NEUTRALIZE the net-negative reward by
-  // zeroing lines_removed in the forwarded diff_stats (so awardNetNegativeBonus
-  // sees removed<=added → bonus 0) WITHOUT altering the displayed/audited stats.
-  // Conservative: only fires on the inconsistent shape; an honest net-negative
-  // simplification (few files, removed>added) is untouched.
-  let sanitizedSignals = base.signals;
-  const claimsNetNegative =
-    ds && (Number(ds.lines_removed) || 0) > (Number(ds.lines_added) || 0);
-  const NET_NEGATIVE_MAX_FILES = 25; // a "simplification" touching >25 files is implausibly broad
-  if (claimsNetNegative && changeFiles > NET_NEGATIVE_MAX_FILES) {
-    guardsTripped.push({ guard: 'forged_net_negative', severity: 'minor',
-      summary: `net-negative diff_stats (removed ${ds.lines_removed} > added ${ds.lines_added}) across ${changeFiles} files is implausibly broad for a simplification — net-negative bonus neutralized (SR-18)` });
-    // Clone signals + zero the credit-driving field WITHOUT mutating the input
-    // or the displayed diff_stats audit value (we add a sibling marker instead).
-    sanitizedSignals = {
-      ...(base.signals || {}),
-      diff_stats: { ...ds, lines_removed: Number(ds.lines_added) || 0 },
-      diff_stats_reported: ds, // preserve what the client claimed for the audit trail
-    };
-  }
-
-  // No guard tripped (or only audit-level findings on a non-pass) → return the
-  // input with a passed-through audit marker so the trail shows guards ran.
-  if (downgradeTo == null && guardsTripped.length === 0 && sanitizedSignals === base.signals) {
-    return {
-      ...base,
-      signals: {
-        ...(base.signals || {}),
-        server_guard: {
-          applied: ['route_rank', 'permission_path', 'permission_path_unprovable', 'implausible_pass', 'forged_net_negative'],
-          ok: true,
-          tripped: [],
-          // task 1002658 / ADR 0164: the audit trail records WHY a zero-issue
-          // pass on a non-trivial diff stood (panel evidence), so /grade-audit
-          // can distinguish waived from never-evaluated.
-          ...(implausiblePassWaived ? { implausible_pass_waived: implausiblePassWaived } : {}),
-        },
-      },
-    };
-  }
-
-  // Build the downgraded result. Downgrade-only: if base wasn't passing we keep
-  // it not-passing; we never resurrect. Map the panel verdict onto the v3
-  // server gate the same way aggregatePanel does (fail → confidence 0; concerns
-  // → FALLTHROUGH_CONFIDENCE below the low-confidence cap; pass left as-is).
-  const newPassed = clientPassed && downgradeTo == null;
-  const forwardedConfidence =
-    downgradeTo === 'fail'
-      ? 0
-      : downgradeTo === 'concerns'
-        ? FALLTHROUGH_CONFIDENCE
-        : (base.signals?.confidence ?? null);
-
-  const guardNote = guardsTripped.length
-    ? `\n\nServer-authoritative guards (SR-9 / SR-18) ${downgradeTo ? `DOWNGRADED this grade to ${downgradeTo.toUpperCase()}` : 'flagged'}:\n`
-      + guardsTripped.map((g) => `  [${g.severity}] ${g.guard}: ${g.summary}`).join('\n')
-    : '';
-
-  return {
-    ...base,
-    passed: newPassed,
-    issues: [...(base.issues || []), ...extraIssues],
-    signals: {
-      ...sanitizedSignals,
-      // confidence drives the server-side gate alignment (validateAndScore on the
-      // 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'],
-        ok: guardsTripped.length === 0,
-        downgraded_to: downgradeTo,
-        client_passed: clientPassed,
-        tripped: guardsTripped,
-        // task 1002614 (map P-2): a permission_path trip is an AUTHORIZATION
-        // refusal of the builder's rank over protected paths — not a verdict on
-        // the code. Named here so clients render it as a wall, not a quality
-        // FAIL the builder should fix-and-retry (the envelope used to teach
-        // exactly that wrong lesson). route_rank stays a code finding.
-        // task 1002646: permission_path_unprovable is the same wall — the rank
-        // floor refusing an unverifiable diff — so it renders the same way.
-        authorization_refusal: guardsTripped.some((g) => g.guard === 'permission_path' || g.guard === 'permission_path_unprovable'),
-        ...(implausiblePassWaived ? { implausible_pass_waived: implausiblePassWaived } : {}),
-      },
-    },
-    notes_md: `${base.notes_md || ''}${guardNote}`,
-  };
-}
-
-// ---------- v3: multi-shot aggregation ----------
-
-// Collapses N per-shot grade-results into the final v3 grade-result.
-// Pass requires unanimous PASS on all shots; anything else (any FAIL, any
-// error, any disagreement) → not passed. Issues are deduped across shots
-// by (file, summary). Displayed rubric_scores use the median across shots
-// so the trend dashboard stays one-number-per-task.
-function aggregateShots(shotResults, meta = {}) {
-  const N = shotResults.length;
-  const verdicts = shotResults.map((s) => ({
-    passed: s.passed,
-    ff: s.rubric_scores?.functional_fidelity ?? null,
-    cq: s.rubric_scores?.code_quality ?? null,
-    economy: s.rubric_scores?.economy ?? null,
-    cq_effective: s.rubric_scores?.code_quality_effective ?? null,
-    confidence: s.signals?.confidence ?? null,
-    model: s.signals?.model ?? null,
-    run_ms: s.signals?.run_ms ?? null,
-    shot_index: s.signals?.shot_index ?? null,
-    notes_md: s.notes_md,
-    issues: s.issues || [],
-    error:
-      s.signals?.parse_error
-        ? 'parse_error'
-        : s.signals?.schema_error
-          ? 'schema_error'
-          : s.signals?.subprocess_error || null,
-  }));
-
-  const ff = median(verdicts.map((v) => v.ff));
-  const cq = median(verdicts.map((v) => v.cq));
-  const economy = median(verdicts.map((v) => v.economy));
-  const cqEffective = median(verdicts.map((v) => v.cq_effective));
-  const blended = ff != null && cq != null ? r1((ff + cq) / 2) : 0;
-  // Top-level aggregated confidence = median of per-shot confidences. Without
-  // this, ship.js forwards a null top-level confidence to /tasks/:id/grade,
-  // and the server's validateAndScore (re-running on the POST body) hits the
-  // Number(null)=0 trap → FAIL even though every shot independently passed.
-  // Caught on the MAS Phase 1 self-ship (#395).
-  //
-  // Computed UNROUNDED (no r1()) — confidence sits near a 0.4 gate cap so
-  // rounding to one decimal could nudge a borderline value across the cap
-  // in either direction. Per-shot confidences are already 0-1 floats.
-  const confVals = verdicts
-    .map((v) => v.confidence)
-    .filter((n) => Number.isFinite(n))
-    .sort((a, b) => a - b);
-  const confidenceMedian = confVals.length === 0
-    ? null
-    : confVals.length % 2
-      ? confVals[(confVals.length - 1) / 2]
-      : (confVals[confVals.length / 2 - 1] + confVals[confVals.length / 2]) / 2;
-
-  // Dedupe issues across shots by (file, summary). Keep first-seen severity.
-  const seen = new Set();
-  const issues = [];
-  for (const v of verdicts) {
-    for (const it of v.issues) {
-      if (!it || typeof it !== 'object') continue;
-      const key = `${it.file ?? ''}::${(it.summary ?? '').trim()}`;
-      if (seen.has(key)) continue;
-      seen.add(key);
-      issues.push(it);
-    }
-  }
-
-  const passCount = verdicts.filter((v) => v.passed === true).length;
-  const failCount = verdicts.filter((v) => v.passed === false && !v.error).length;
-  const errorCount = verdicts.filter((v) => v.error).length;
-  const allPassed = N > 0 && passCount === N;
-
-  let verdict;
-  let passed;
-  let aggregationKind;
-  if (errorCount > 0) {
-    passed = false;
-    verdict = `FAIL — ${errorCount}/${N} shot(s) errored`;
-    aggregationKind = 'errored';
-  } else if (allPassed) {
-    passed = true;
-    verdict = `PASS — ${N}/${N} shots unanimous`;
-    aggregationKind = 'unanimous_pass';
-  } else if (passCount === 0) {
-    passed = false;
-    verdict = `FAIL — ${failCount}/${N} shots`;
-    aggregationKind = 'unanimous_fail';
-  } else {
-    passed = false;
-    verdict = `FAIL — ${passCount} pass, ${failCount} fail (no unanimous pass)`;
-    aggregationKind = 'disagreement';
-  }
-
-  const lines = [];
-  lines.push(`Subagent grader ${VERSION} (multi-shot, ${N}× shots) — ${verdict}`);
-  lines.push(`  functional_fidelity (median): ${ff ?? '?'}/10`);
-  lines.push(`  code_quality (median):        ${cq ?? '?'}/10`);
-  if (economy != null) {
-    lines.push(`  economy (advisory, median):   ${economy}/10`);
-  }
-  lines.push(`  blended (median):             ${blended}/10  (threshold ${THRESHOLD}, both axes must clear on EVERY shot)`);
-  lines.push('');
-  lines.push('Per-shot:');
-  for (let i = 0; i < verdicts.length; i++) {
-    const v = verdicts[i];
-    const status = v.error ? 'ERROR' : v.passed === true ? 'PASS' : 'FAIL';
-    const ffStr = v.ff != null ? `${v.ff}` : '?';
-    const cqStr = v.cq != null ? `${v.cq}` : '?';
-    const confStr = v.confidence != null ? `  conf=${v.confidence}` : '';
-    const errStr = v.error ? `  (${v.error})` : '';
-    lines.push(`  shot[${i}] ${status}  ff=${ffStr}  cq=${cqStr}${confStr}  ${v.model ?? '?'}${errStr}`);
-  }
-  if (issues.length > 0) {
-    lines.push('');
-    lines.push(`Issues (${issues.length} unique across shots):`);
-    for (const it of issues.slice(0, 20)) {
-      const sev = String(it.severity || '?').padEnd(7);
-      const file = String(it.file || '?');
-      const summary = String(it.summary || '').replace(/\s+/g, ' ').trim();
-      lines.push(`  [${sev}] ${file} — ${summary}`);
-    }
-    if (issues.length > 20) {
-      lines.push(`  ... ${issues.length - 20} more (full set in signals.shots[].issues)`);
-    }
-  }
-
-  // #486 (ADR 0028 path 1): sum each shot's own subprocess cost (envelope
-  // total_cost_usd) so the trivial-diff path reports panel_cost_usd the same way
-  // the full panel does. The single-shot trivial path is the common case here.
-  const panelCostUsd = shotResults.reduce((s, r) => s + (Number(r.cost_usd) || 0), 0);
-
-  return {
-    score: blended,
-    passed,
-    threshold: THRESHOLD,
-    grader_kind: 'subagent-multishot',
-    grader_version: VERSION,
-    panel_cost_usd: panelCostUsd, // #486: panel's own API spend (USD)
-    rubric_scores: {
-      functional_fidelity: ff,
-      code_quality: cq,
-      economy,
-      code_quality_effective: cqEffective,
-    },
-    signals: {
-      grader_kind: 'subagent-multishot',
-      grader_version: VERSION,
-      threshold: THRESHOLD,
-      // Top-level confidence = median across shots. ship.js forwards this to
-      // POST /tasks/:id/grade so the server-side re-validation has a real
-      // number rather than null (see Number(null)=0 fix in validateAndScore).
-      confidence: confidenceMedian,
-      shots: verdicts,
-      shot_count: N,
-      pass_count: passCount,
-      fail_count: failCount,
-      error_count: errorCount,
-      shot_aggregation: aggregationKind,
-      ...meta,
-    },
-    notes_md: lines.join('\n'),
-    issues,
-  };
-}
-
-// ---------- v3: subagent subprocess invoker ----------
-
-// Unchanged from v2 — spawns `claude -p --print --model <model> --output-
-// format json` with stdin = prompt. The v3 caller varies `model` per shot
-// via opts.model (set by gradeSubagent below).
-function runSubagent({ prompt, opts = {} }) {
-  return new Promise((resolve, reject) => {
-    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';
-
-    const args = [
-      '-p',
-      '--print',
-      '--model', model,
-      '--output-format', 'json',
-      '--tools', 'Read',
-      '--disable-slash-commands',
-      '--permission-mode', 'bypassPermissions',
-    ];
-
-    const startedAt = Date.now();
-    const child = spawn(bin, args, {
-      cwd,
-      stdio: ['pipe', 'pipe', 'pipe'],
-      // On Windows the `claude` CLI is a `claude.cmd` shim that Node's spawn
-      // can't launch without a shell (ENOENT -> SUBAGENT_SPAWN_FAILED, observed
-      // on #662). Route through cmd.exe on win32 only; Mac/Linux keep
-      // shell:false (the default, and the proven-working path). args carry no
-      // user input (the prompt goes in via stdin), so shell injection is a
-      // non-issue. windowsHide suppresses the transient console window.
-      shell: process.platform === 'win32',
-      windowsHide: true,
-      // MAS Phase 3 (#427): mark this child as a subagent so the Conductor
-      // UserPromptSubmit hook (.claude/hooks/conductor.js) bails instead of
-      // injecting advisory context into the grader worker's prompt. Any
-      // subagent we spawn inherits this flag and is likewise suppressed.
-      env: { ...process.env, OTB_SUBAGENT: '1' },
-    });
-
-    let stdout = '';
-    let stderr = '';
-    let timedOut = false;
-
-    const killTimer = setTimeout(() => {
-      timedOut = true;
-      try { child.kill('SIGTERM'); } catch (_) {}
-      setTimeout(() => { try { child.kill('SIGKILL'); } catch (_) {} }, 5_000);
-    }, timeoutMs);
-
-    child.stdout.on('data', (b) => { stdout += b.toString('utf8'); });
-    child.stderr.on('data', (b) => { stderr += b.toString('utf8'); });
-
-    child.on('error', (err) => {
-      clearTimeout(killTimer);
-      reject(Object.assign(new Error(`subagent spawn failed: ${err.message}`), {
-        code: 'SUBAGENT_SPAWN_FAILED',
-        cause: err,
-      }));
-    });
-
-    child.on('close', (exitCode) => {
-      clearTimeout(killTimer);
-      const runMs = Date.now() - startedAt;
-      if (timedOut) {
-        return reject(Object.assign(new Error(`subagent timed out after ${timeoutMs}ms`), {
-          code: 'SUBAGENT_TIMEOUT',
-          run_ms: runMs,
-          stdout,
-          stderr,
-        }));
-      }
-      if (exitCode !== 0) {
-        return reject(Object.assign(new Error(`subagent exited with code ${exitCode}`), {
-          code: 'SUBAGENT_NONZERO_EXIT',
-          exit_code: exitCode,
-          run_ms: runMs,
-          stdout,
-          stderr,
-        }));
-      }
-      resolve({ stdout, stderr, run_ms: runMs, exit_code: exitCode, cost_usd: extractCostUsd(stdout) });
-    });
-
-    child.stdin.write(prompt, 'utf8');
-    child.stdin.end();
-  });
-}
-
-// ---------- task 1002660: shared context bundle ----------
-//
-// ~90% of panel cost was fixed re-exploration: four subprocesses each spending
-// agentic Read turns re-opening the same changed files. Read them ONCE here
-// and hand every worker the post-change contents inline (fenced, untrusted),
-// so a worker's Read tool is only needed for files beyond the bundle.
-const CONTEXT_BUNDLE_MAX_FILES = 24;
-const CONTEXT_BUNDLE_MAX_TOTAL_CHARS = 120_000;
-const CONTEXT_BUNDLE_MAX_FILE_CHARS = 16_000;
-// Binary-ish extensions never worth inlining (the diff already names them).
-const CONTEXT_BUNDLE_SKIP_RE = /\.(?:png|jpe?g|gif|webp|ico|svgz|woff2?|ttf|eot|zip|gz|tgz|tar|pdf|mp[34]|wav|ogg|bin|exe|dll|node)$/i;
-
-// Added lines per file, from the unified diff. Only lines long enough to be a
-// meaningful fingerprint (a bare `}` or `});` matches anywhere) — used to prove
-// a truncated bundle prefix actually SHOWS the change (task 1002905).
-const BUNDLE_EVIDENCE_MIN_CHARS = 12;
-function diffAddedLinesByFile(diff) {
-  const byFile = new Map();
-  let cur = null;
-  let prevWasOldHeader = false;
-  for (const line of String(diff || '').split('\n')) {
-    // A '+++ ' header only counts right after its '--- ' partner: a content line
-    // reading '++ x' arrives as '+++ x' and must not be mistaken for a header.
-    if (prevWasOldHeader && line.startsWith('+++ ')) {
-      prevWasOldHeader = false;
-      const p = line.slice(4).trim().replace(/^b\//, '');
-      cur = p === '/dev/null' ? null : p;
-      continue;
-    }
-    prevWasOldHeader = line.startsWith('--- ');
-    if (prevWasOldHeader || line.startsWith('diff --git')) continue;
-    if (!cur || !line.startsWith('+')) continue;
-    const t = line.slice(1).trim();
-    if (t.length < BUNDLE_EVIDENCE_MIN_CHARS) continue;
-    if (!byFile.has(cur)) byFile.set(cur, []);
-    byFile.get(cur).push(t);
-  }
-  return byFile;
-}
-
-// Pure-ish (fs reads only, injectable): returns { files: [{file, content,
-// truncated, chars_total}], skipped: [file...], total_chars } for the post-change
-// contents of changedFiles under cwd. Deleted/unreadable files land in skipped —
-// their absence from the bundle is visible, never silent.
-//
-// Security (panel hacker finding, task 1002660): changedFiles is builder-
-// controlled and git commits symlinks, so a naive readFileSync would follow a
-// committed link OUT of the repo (SSH keys, session tokens) and inject the
-// target into worker prompts + the stored grade. lstat-refuse symlinks and
-// non-files, and require the resolved path to stay under cwd (containment) —
-// a refused entry lands in skipped, visible like every other exclusion.
-function buildContextBundle({ changedFiles, cwd, diff, fsImpl = fs } = {}) {
-  const files = [];
-  const skipped = [];
-  let total = 0;
-  const root = path.resolve(cwd || process.cwd());
-  // task 1002905: the fabricated all-blocker FAIL. A file over the per-file cap
-  // is truncated from the HEAD, so on a large file (ship.js: 250k chars) a change
-  // at char 62k lands entirely outside the bundle — and the prompt presents what
-  // IS bundled as "the post-change contents". A worker then searches the prefix,
-  // doesn't find the new code, and reports it as absent (5 blockers, every claim
-  // exactly the pre-change state). A prefix that contains none of the change is
-  // worse than no bundle at all, so refuse it: skipped[] already tells the worker
-  // to Read the file.
-  const addedByFile = diffAddedLinesByFile(diff);
-  for (const rel of (Array.isArray(changedFiles) ? changedFiles : [])) {
-    if (files.length >= CONTEXT_BUNDLE_MAX_FILES || total >= CONTEXT_BUNDLE_MAX_TOTAL_CHARS) {
-      skipped.push(rel);
-      continue;
-    }
-    if (CONTEXT_BUNDLE_SKIP_RE.test(rel)) { skipped.push(rel); continue; }
-    let content;
-    try {
-      const abs = path.resolve(root, rel);
-      if (abs !== root && !abs.startsWith(root + path.sep)) { skipped.push(rel); continue; }
-      const st = fsImpl.lstatSync(abs);
-      if (!st.isFile() || st.isSymbolicLink()) { skipped.push(rel); continue; }
-      content = fsImpl.readFileSync(abs, 'utf8');
-    } catch (_) { skipped.push(rel); continue; } // deleted by the diff, or unreadable
-    const charsTotal = content.length;
-    let truncated = false;
-    if (content.length > CONTEXT_BUNDLE_MAX_FILE_CHARS) {
-      content = content.slice(0, CONTEXT_BUNDLE_MAX_FILE_CHARS);
-      truncated = true;
-    }
-    if (truncated) {
-      const added = addedByFile.get(rel);
-      if (added && added.length && !added.some((a) => content.includes(a))) { skipped.push(rel); continue; }
-    }
-    if (total + content.length > CONTEXT_BUNDLE_MAX_TOTAL_CHARS) { skipped.push(rel); continue; }
-    total += content.length;
-    files.push({ file: rel, content, truncated, chars_total: charsTotal });
-  }
-  return { files, skipped, total_chars: total };
-}
-
-// System 5 (task 1359): an OPT-IN cached path around runSubagent. When the caller
-// supplies a `cache` spec (from llm-cache.makeCacheSpec), a hit replays the stored
-// result at cost_usd:0 (so $0 flows naturally into extractCostUsd → session-cost);
-// a miss runs the untouched runSubagent and stores a clean (exit 0) result. With
-// no cache spec it's exactly runSubagent — the default path is never altered. The
-// llm-cache reaches us through the doorway (BV1.R73: it's shared infra core also
-// uses, so a module can't own it); if it's somehow absent the path degrades to an
-// ordinary uncached run, exactly as the old lazy-require catch did.
-async function runSubagentCached({ prompt, opts = {}, cache = null }) {
-  if (!cache || !cache.key) return runSubagent({ prompt, opts });
-  const llmCache = api.llmCache;
-  if (!llmCache) return runSubagent({ prompt, opts });
-  return llmCache.withCache(cache, () => runSubagent({ prompt, opts }));
-}
-
-// #486 (ADR 0028 path 1): the `claude -p --output-format json` envelope reports
-// the subprocess's own dollar cost in `total_cost_usd` (verified present:
-// {type, ..., total_cost_usd, usage, modelUsage}). We were parsing only
-// `env.result` (extractAssistantResult) and silently discarding that cost — the
-// single biggest reason cost_log's `api` category sat at $0.60 across the whole
-// project (#482 audit F1). Pull it out so the panel's spend can be logged
-// (category=api, source=grader). Returns null on non-JSON / partial output, so
-// a cost signal never fabricates a number it doesn't have.
-function extractCostUsd(rawStdout) {
-  try {
-    const env = JSON.parse(rawStdout);
-    if (env && typeof env.total_cost_usd === 'number' && env.total_cost_usd >= 0) {
-      return env.total_cost_usd;
-    }
-  } catch (_) { /* non-JSON or partial stdout — no cost signal */ }
-  return null;
-}
-
-function extractAssistantResult(rawStdout) {
-  try {
-    const env = JSON.parse(rawStdout);
-    if (env && typeof env.result === 'string') return env.result;
-    if (env && typeof env === 'object' && 'functional_fidelity' in env) return env;
-    return rawStdout;
-  } catch (_) {
-    return rawStdout;
-  }
-}
-
-// Run one shot end-to-end: build the prompt (caller did this), spawn the
-// subagent at the requested model, parse + validate. Returns a per-shot
-// grade-result; subprocess failures become passed=false per-shot results so
-// aggregateShots can still produce a final verdict.
-async function runOneShot({ prompt, model, shotIndex, runOpts }) {
-  try {
-    const { stdout, run_ms, exit_code, cost_usd } = await runSubagent({
-      prompt,
-      opts: { ...runOpts, model },
-    });
-    const assistantResult = extractAssistantResult(stdout);
-    const scored = validateAndScore(assistantResult, {
-      run_ms,
-      exit_code,
-      raw_chars: stdout.length,
-      model,
-      shot_index: shotIndex,
-    });
-    // #486 (ADR 0028 path 1): carry this shot's own subprocess cost so the
-    // trivial-diff path (gradeSubagentV3MultiShot → aggregateShots) can sum it
-    // into panel_cost_usd just like the full panel does.
-    scored.cost_usd = cost_usd ?? null;
-    return scored;
-  } catch (err) {
-    return {
-      score: 0,
-      passed: false,
-      threshold: THRESHOLD,
-      grader_kind: 'subagent',
-      grader_version: VERSION,
-      rubric_scores: {},
-      signals: {
-        grader_kind: 'subagent',
-        grader_version: VERSION,
-        model,
-        threshold: THRESHOLD,
-        shot_index: shotIndex,
-        run_ms: err.run_ms ?? null,
-        exit_code: err.exit_code ?? null,
-        subprocess_error: err.code || 'UNKNOWN',
-        stderr_tail: (err.stderr || '').slice(-500),
-      },
-      notes_md: `Shot ${shotIndex}: subprocess failed (${err.code || 'UNKNOWN'}: ${err.message}).`,
-      issues: [],
-    };
-  }
-}
-
-// ---------- v4: panel aggregation (MAS Phase 2.0) ----------
-
-// Collapses N per-worker WorkerResults into the final v4 grade-result.
-//
-// Gate logic:
-//   - Any worker `fail`               → overall FAIL (a real finding blocks).
-//   - Else any worker errored         → overall FALLTHROUGH (manual-confirm) —
-//                                        a crash is missing signal, not a
-//                                        finding, so it must not hard-block
-//                                        on infra flakiness (#126).
-//   - Else any worker `concerns`      → overall FALLTHROUGH (manual-confirm).
-//   - All workers `pass`              → overall PASS.
-//
-// Server-compat forwarding:
-//   The grade POST shape (ff, cq, economy, confidence, issues) is preserved
-//   so the server's existing validateAndScore re-validation aligns with the
-//   panel's verdict. We achieve this by setting the forwarded confidence:
-//     pass     → median worker confidence (server's gate also passes)
-//     concerns → FALLTHROUGH_CONFIDENCE (below LOW_CONFIDENCE → server fails)
-//     fail     → 0 + a failing axis preserved at < threshold (server fails)
-//
-// rubric_scores:
-//   Each axis is the median across workers that reported it (Narc reports
-//   functional_fidelity; Quality reports code_quality + economy). Preserves
-//   the trend dashboard's one-number-per-task contract.
-//
-// signals.workers[] carries the full per-worker audit trail.
 function aggregatePanel(workerResults, meta = {}) {
   const N = workerResults.length;