@bongos/core 1.17.0

package/modules/grading/grader.js

@@ -0,0 +1,1790 @@
+// GDS-V3 task #410 (MAS Phase 2.0) — Quality grader v4 (worker panel).
+//
+// Phase 2.0 of the Multi-Agent System (ADR 0024). v3 was a 3-shot generalist
+// (one prompt, 3 parallel runs, unanimous PASS). v4 trades sampling-variance
+// for lens-specialization: 3 specialist workers replace the 3 shots. Each
+// worker is a distinct prompt focused on one axis; gate is unanimous PASS
+// across the GATING workers (any gating fail blocks; any gating concerns falls
+// through). The Narc (functional_fidelity) is ADVISORY since #481 — its
+// concerns never block and its fail downgrades to manual-confirm; see
+// aggregatePanel.
+//
+// Phase 2.0 ships 2 of the 3 planned workers (narc + quality); 2.1 adds
+// hacker (security), 2.2 adds efficiency_monger. The framework is the
+// load-bearing change here — adding workers later is a one-line plug-in.
+//
+// ## Phase 1 (v3) carry-overs that remain true in v4
+//
+//   1. CROSS-FAMILY. Default grader model is Sonnet 4.6; the assumed builder
+//      is Opus. selectGraderModel() flips the model based on the builder's
+//      model when known. Each worker inherits the same selection.
+//   2. DEFAULT-FAIL FRAMING. Each worker's prompt is independently default-
+//      fail, and each must enumerate concrete issues before any pass verdict.
+//
+// ## What's new in v4
+//
+//   3. WORKER PANEL. gradeSubagent runs DEFAULT_PANEL (narc + quality) in
+//      parallel; aggregatePanel applies the gate. Each worker has its own
+//      prompt, parser, scoring, and per-worker pass/concerns/fail verdict.
+//   4. STRUCTURED VERDICTS. pass | concerns | fail (not just pass/fail).
+//      'concerns' falls through to the manual-confirm path the same way
+//      low-confidence did in v3.
+//   5. SERVER-COMPAT FORWARDING. The grade POST body still uses the v3
+//      shape (ff, cq, economy, confidence, issues) so the server's
+//      validateAndScore re-validation runs cleanly. The panel's verdict
+//      drives the forwarded confidence so the server's gate aligns:
+//         pass     → forward median confidence (server passes)
+//         concerns → forward 0.3 (server fails on low-conf → fallthrough)
+//         fail     → forward 0 + the failing worker's worst score
+//
+// ## Surface (v4)
+//
+//   gradeSubagent({task, valueSummary, diff, changedFiles, diffStats,
+//                  workers?, builderModel, runOpts})
+//       → end-to-end panel grade-result. workers? defaults to DEFAULT_PANEL
+//       (narc + quality). Wraps subprocess failures so resolveClaim/applyGrade
+//       can always write task_grades.
+//
+//   aggregatePanel(workerResults, meta)
+//       → final grade-result from per-worker WorkerResults. Applies the
+//       any-fail / any-concerns / all-pass gate. Outputs are server-
+//       compatible with the v3 grade POST shape.
+//
+//   selectGraderModel({builderModel})
+//       → unchanged from v3.
+//
+// ## v3 surface (kept exported for diagnostics + back-compat)
+//
+//   buildPrompt({...}) — the v3 generalist default-fail prompt. NOT used by
+//   the v4 panel; kept for explicit single-prompt diagnostic callers.
+//
+//   validateAndScore(rawSubagent, meta) — v3 per-shot validator. Workers
+//   have their own (more specific) validators; this remains exported for
+//   the legacy single-shot diagnostics path and for tests.
+//
+//   aggregateShots(shotResults, meta) — v3 multi-shot aggregator. Same
+//   reasoning: kept for diagnostic callers.
+//
+//   runSubagent({prompt, opts}) / runOneShot(...) — subprocess plumbing,
+//   unchanged from v3. Workers spawn via runSubagent through the workers
+//   module (which receives it via dependency injection to avoid a circular
+//   require).
+//
+// ## Legacy v1 (still exported)
+//
+//   gradeDeterministic(...) — v1 deterministic path, kept for
+//   scripts/gds/audit-ships.js (retroactive audit). NOT invoked at ship time.
+
+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')
+);
+
+// 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-opus-4-7';
+const DEFAULT_GRADER_MODEL = V4.default_model || 'claude-sonnet-4-6';
+const FALLTHROUGH_CONFIDENCE = V4.fallthrough_confidence ?? 0.3;
+const workers = require('./grader-workers');
+// 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 family from
+// the builder is the cross-family adversarial guarantee. With no builderModel
+// the caller is assuming the default Opus builder (CLAUDE.md §2), so it resolves
+// through the opus branch to Sonnet — that is the legitimate default path the
+// live callers (selectGraderModel({})) take.
+//
+// #117: an EXPLICITLY-supplied model we don't recognize is a misconfiguration,
+// not a default. We used to silently fall back to Sonnet, which would mask a
+// future model family (one whose id lacks 'opus'/'sonnet'/'haiku') and quietly
+// grade it on the wrong cross-family assumption. Throw loudly instead so the
+// caller fixes the input rather than getting a silently-wrong grader model.
+function selectGraderModel({ builderModel } = {}) {
+  const bm = (builderModel || ASSUMED_BUILDER_MODEL).toLowerCase();
+  if (bm.includes('opus')) return 'claude-sonnet-4-6';
+  if (bm.includes('sonnet')) return 'claude-opus-4-7';
+  if (bm.includes('haiku')) return 'claude-opus-4-7';
+  throw new Error(
+    `selectGraderModel: unrecognized builder model ${JSON.stringify(builderModel)} — ` +
+    `expected an id containing 'opus', 'sonnet', or 'haiku'. Refusing to silently ` +
+    `fall back to a default grader model (#117).`
+  );
+}
+
+// ---------- 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 }) {
+  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('');
+  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);
+}
+
+// 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: [],
+    };
+  }
+
+  const ff = 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 (!isNum(ff) || !isNum(cq) || ff < 0 || ff > 10 || 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}.`,
+      issues,
+    };
+  }
+
+  const ffR = 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;
+  const blended = 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;
+  const bothPass = ffR >= THRESHOLD && cqR >= THRESHOLD;
+  const passed = bothPass && !lowConfidence && !confidenceAbsent;
+
+  const verdict = passed
+    ? 'PASS'
+    : confidenceAbsent
+      ? 'FAIL — confidence absent'
+      : lowConfidence
+        ? 'FAIL — low confidence'
+        : bothPass
+          ? 'FAIL'
+          : ffR < THRESHOLD && cqR < THRESHOLD
+            ? `FAIL — both axes below ${THRESHOLD}`
+            : ffR < THRESHOLD
+              ? `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=${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 2: implausible client verdict (SR-9) ---
+  // A client PASS with an empty issues[] on a non-trivial diff is not a credible
+  // default-fail panel verdict. Downgrade to manual-confirm (a human lands it via
+  // /confirm) rather than auto-confirm + auto-credit. Only escalates the verdict
+  // (never de-escalates a Guard-1 hard FAIL).
+  const issueCount = Array.isArray(base.issues) ? base.issues.length : 0;
+  const { files: changeFiles, lines: changeLines } = changeMagnitude({ committedFiles, diffStats: ds });
+  const nonTrivial = changeFiles > IMPLAUSIBLE_PASS_MAX_FILES || changeLines > IMPLAUSIBLE_PASS_MAX_LINES;
+  if (clientPassed && issueCount === 0 && nonTrivial) {
+    guardsTripped.push({ guard: 'implausible_pass', severity: 'major',
+      summary: `client PASS with empty issues[] on a non-trivial diff (${changeFiles} file(s), ${changeLines} line(s) > ${IMPLAUSIBLE_PASS_MAX_FILES}/${IMPLAUSIBLE_PASS_MAX_LINES}) is not a credible default-fail panel verdict → manual-confirm (SR-9)` });
+    extraIssues.push({ severity: 'major', file: '(grade)', summary:
+      `[server plausibility] a passing grade with no enumerated issues on a ${changeFiles}-file / ${changeLines}-line change must be human-confirmed via /confirm`, worker: 'server-plausibility' });
+    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
+  // 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', 'implausible_pass', 'forged_net_negative'], ok: true, tripped: [] },
+      },
+    };
+  }
+
+  // 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', 'implausible_pass', 'forged_net_negative'],
+        ok: guardsTripped.length === 0,
+        downgraded_to: downgradeTo,
+        client_passed: clientPassed,
+        tripped: guardsTripped,
+      },
+    },
+    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();
+  });
+}
+
+// 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;
+
+  // Score axes — median across workers that reported each. Reuses the
+  // module-level median() helper (rounded to one decimal).
+  const ff = median(workerResults.map((w) => w.scores?.functional_fidelity));
+  const cq = median(workerResults.map((w) => w.scores?.code_quality));
+  const economy = median(workerResults.map((w) => w.scores?.economy));
+  // Phase 2.1 (#416): Hacker reports security_score. Added to rubric_scores
+  // for the audit trail and trend dashboard; not directly server-gated
+  // (Hacker's verdict still flows through the existing confidence-forwarding).
+  const security = median(workerResults.map((w) => w.scores?.security_score));
+  // Phase 2.2 (#421): Efficiency Monger reports efficiency_score. Same
+  // additive treatment as security_score.
+  const efficiencyScore = median(workerResults.map((w) => w.scores?.efficiency_score));
+
+  const economyPenalty =
+    economy != null ? Math.max(0, (THRESHOLD - economy) / 2) : 0;
+  const cqEffective = cq != null && economy != null ? r1(clamp(cq - economyPenalty, 0, 10)) : cq;
+  const blended = ff != null && cq != null ? r1((ff + cq) / 2) : 0;
+
+  // Verdict counts.
+  const passCount = workerResults.filter((w) => w.verdict === 'pass').length;
+  const concernsCount = workerResults.filter((w) => w.verdict === 'concerns').length;
+  // A crashed worker sets verdict='fail' as a DEFAULT in its computeVerdict()
+  // subprocess_error / parse_error / schema_error early returns (see each
+  // worker module) — that is MISSING SIGNAL, not a substantive finding, and
+  // those early returns bail before any issues are extracted (error set ⟹ no
+  // findings). Treat such a worker as "missing signal" so it counts ONLY toward
+  // errorCount; otherwise the errorCount fall-through below is unreachable dead
+  // code (#473 grader catch).
+  //
+  // DEFENSE-IN-DEPTH (#473 Hacker [major]): the above invariant is the load-
+  // bearing claim. Rather than trust it blindly, a worker is "missing signal"
+  // only if it errored AND surfaced NO blocking/major issue. So even if a future
+  // worker ever set both `error` and a real finding, that finding still blocks
+  // (counts as a substantive fail) instead of being reclassified as a flake.
+  const hasSubstantiveIssue = (w) =>
+    (w.issues || []).some((i) => i.severity === 'blocker' || i.severity === 'major');
+  const isMissingSignal = (w) => !!w.error && !hasSubstantiveIssue(w);
+  const failCount = workerResults.filter((w) => w.verdict === 'fail' && !isMissingSignal(w)).length;
+  // NOTE (#473/#589): signals.error_count counts only isMissingSignal workers — i.e. a worker that
+  // errored AND surfaced no blocking issue. A worker that errored but still raised a blocker/major
+  // is a real finding, so it counts in fail_count (above), NOT here. This is a deliberate semantic
+  // change from the old "all w.error" meaning; keep error_count = missing-signal-only.
+  const errorCount = workerResults.filter((w) => isMissingSignal(w)).length;
+
+  // V3.R85 (#481): the Narc (functional_fidelity) is ADVISORY in the gate —
+  // Lars's call 2026-05-30 after #303, where over-literal acceptance-criteria
+  // objections from this one lens repeatedly blocked ships that Quality,
+  // Hacker, and Efficiency all cleared. The Narc keeps its lens (scores +
+  // issues are still recorded and displayed), but its weight in the GATE drops:
+  //   - a Narc 'concerns'  → advisory only; never blocks.
+  //   - a Narc-only 'fail' → downgrades to manual-confirm (CONCERNS), not a
+  //     hard panel FAIL — so a genuine functional gap still surfaces and pauses
+  //     for a human, but isn't an automatic rejection.
+  //   - Quality / Hacker / Efficiency keep their hard veto unchanged.
+  // The raw counts above are untouched, so the audit trail + dashboards still
+  // see every worker's real verdict.
+  //
+  // DEFENSE-IN-DEPTH (#481 Hacker [major]): a worker is advisory ONLY if it
+  // carries no blocker-severity issue. So even if a future change routed a
+  // gating finding through an advisory kind (e.g. the deterministic route-rank
+  // pre-pass — today kind='route-rank', NOT advisory — or any relabel), a
+  // blocker-severity finding can never be silently downgraded to manual-confirm.
+  // This mirrors the isMissingSignal defense-in-depth (#473): a real finding
+  // always blocks. Over-literal Narc objections are major/minor, never blocker,
+  // so the loosening still bites where intended.
+  const ADVISORY_WORKERS = new Set(['narc']);
+  const hasBlocker = (w) => (w.issues || []).some((i) => i.severity === 'blocker');
+  const isAdvisory = (w) => ADVISORY_WORKERS.has(w.kind) && !hasBlocker(w);
+  // If the panel were somehow advisory-only, fall back to gating on everyone so
+  // a lone Narc still counts (defensive — the default panel always has 3+
+  // gating workers).
+  const nonAdvisory = workerResults.filter((w) => !isAdvisory(w));
+  const gating = nonAdvisory.length ? nonAdvisory : workerResults;
+  const gatingFail = gating.filter((w) => w.verdict === 'fail' && !isMissingSignal(w)).length;
+  const gatingError = gating.filter((w) => isMissingSignal(w)).length;
+  const gatingConcerns = gating.filter((w) => w.verdict === 'concerns').length;
+  const gatingAllPass = gating.length > 0 && gating.every((w) => w.verdict === 'pass');
+  // #574 (idea 130): the Hacker (security lens) is the ONE worker whose absence
+  // must not soften the gate. A diff crafted to RELIABLY crash the Hacker
+  // (adversarial content → parse_error/SUBAGENT_TIMEOUT) would otherwise convert
+  // the outcome from auto-block to lenient manual-confirm. Detect a gating Hacker
+  // that produced no signal (missing-signal = errored AND no substantive finding;
+  // a Hacker that errored but still raised a blocker is handled by gatingFail).
+  const securityLensErrored = gating.some((w) => w.kind === 'hacker' && isMissingSignal(w));
+  // #943: TOTAL grader outage — EVERY gating worker is missing-signal (its
+  // subprocess failed to spawn / timed out / produced unparseable output). With
+  // no quality signal at all, the panel has not actually GRADED anything; this
+  // is an infra/outage condition, NOT a 0/10 quality rejection. Distinguished
+  // from the partial-error case (some gating workers errored, others reported)
+  // so callers (ship.js) can present "grader unavailable" instead of a FAIL.
+  const gatingErrorAll = gating.length > 0 && gating.every((w) => isMissingSignal(w));
+  // Advisory-worker outcomes — never a hard block. Uses isAdvisory so a Narc
+  // that DID raise a blocker is treated as gating (in `nonAdvisory`), not here.
+  const advisoryFail = workerResults.some((w) => isAdvisory(w) && w.verdict === 'fail' && !isMissingSignal(w));
+  const advisoryConcerns = workerResults.some((w) => isAdvisory(w) && w.verdict === 'concerns');
+
+  // Confidence — median for pass, fallthrough for concerns, 0 for fail.
+  // (Drives the server-side gate; see file header.) Computed UNROUNDED —
+  // confidence sits near the 0.4 gate cap so the module-level median()
+  // helper (which rounds via r1()) would risk nudging a borderline value
+  // across the boundary. Inlined for that one-decimal-precision reason.
+  const confVals = workerResults
+    .map((w) => w.confidence)
+    .filter((n) => Number.isFinite(n))
+    .slice()
+    .sort((a, b) => a - b);
+  const medianConf = confVals.length === 0
+    ? null
+    : confVals.length % 2
+      ? confVals[(confVals.length - 1) / 2]
+      : (confVals[confVals.length / 2 - 1] + confVals[confVals.length / 2]) / 2;
+
+  let verdict;
+  let panelOutcome;
+  let forwardedConfidence;
+  // Gate on the GATING (non-advisory) workers. The Narc, when advisory, can at
+  // most push the panel to CONCERNS (manual-confirm) — never PASS-block-free
+  // nor hard-FAIL.
+  const advisoryNote = advisoryFail
+    ? ' — narc (advisory) flagged a functional-fidelity failure: confirm only after a human checks the scope is met'
+    : '';
+  if (gatingFail > 0) {
+    // A substantive failure from a GATING worker hard-blocks (errored gating
+    // workers, if any, are noted but the real failure is what governs).
+    verdict = (gatingError > 0
+      ? `FAIL — ${gatingFail}/${N} gating worker(s) failed, ${gatingError}/${N} errored`
+      : `FAIL — ${gatingFail}/${N} gating worker(s) failed`) + advisoryNote;
+    panelOutcome = 'fail';
+    forwardedConfidence = 0;
+  } else if (gatingErrorAll) {
+    // #943: EVERY gating worker failed to run — a total grader outage (the
+    // grader subprocess couldn't spawn / timed out across the board, e.g. the
+    // `claude` CLI 401s in a desktop session, or an API outage). There is NO
+    // quality signal, so this is NOT a quality rejection — it is "the grader
+    // could not run". A distinct 'unavailable' outcome (vs the partial-error
+    // 'concerns' below) lets ship.js present it as "grader unavailable" rather
+    // than the misleading "FAIL · 0/10" that reached the builder in session
+    // 1659. passed stays false → routes to manual-confirm (never auto-pass).
+    const erroredKinds = gating.filter((w) => w.error).map((w) => w.kind);
+    verdict =
+      `GRADER UNAVAILABLE — all ${gatingError}/${gating.length} gating worker(s) failed to run (${erroredKinds.join(', ')}); no quality signal was produced. This is an infra/outage condition, NOT a quality rejection — manual-confirm available.` +
+      advisoryNote;
+    panelOutcome = 'unavailable';
+    forwardedConfidence = FALLTHROUGH_CONFIDENCE;
+  } else if (securityLensErrored) {
+    // #574 (idea 130): the security lens (Hacker) went dark while the rest of the
+    // panel ran — the adversarial signature. Unlike other lenses, a missing
+    // Hacker HARD-BLOCKS rather than falling through to manual-confirm: a diff
+    // engineered to reliably crash the Hacker (parse_error/SUBAGENT_TIMEOUT) would
+    // otherwise downgrade an auto-block into "await Archon", quietly removing the
+    // one lens that catches injected XSS / client-authz regressions. Errored
+    // workers are already auto-retried once (#465), so a Hacker still dark here has
+    // failed twice — treat that as a FAIL, not flakiness. (The all-errored infra
+    // outage is the 'unavailable' case above (#943); a real Hacker blocker is the
+    // gatingFail case above — both take precedence over this branch.) Re-run the
+    // grader once the diff/grader is healthy to clear it.
+    const otherErrored = gating.filter((w) => w.error && w.kind !== 'hacker').map((w) => w.kind);
+    verdict =
+      `FAIL — ⚠ SECURITY LENS MISSING: the Hacker (security) worker errored and produced no signal; security is non-optional, so a reliably-missing Hacker hard-blocks (re-run the grader once healthy)` +
+      (otherErrored.length ? ` — also errored: ${otherErrored.join(', ')}` : '') +
+      advisoryNote;
+    panelOutcome = 'fail';
+    forwardedConfidence = 0;
+  } else if (gatingError > 0) {
+    // #126: a GATING worker that crashed (parse_error / SUBAGENT_TIMEOUT /
+    // subprocess error) produced NO signal — missing information, not a
+    // finding. With no substantive failures (and at least one gating worker
+    // that DID report), fall through to manual-confirm rather than hard-FAIL on
+    // infrastructure flakiness. Name the errored workers. The security (Hacker)
+    // lens is NOT among them here — a missing Hacker is hard-blocked by the
+    // securityLensErrored branch above (#574). An errored ADVISORY worker (Narc)
+    // is not counted here: its lens is advisory, so its absence doesn't gate.
+    // (The all-errored total-outage case is handled above, #943.)
+    const erroredKinds = gating.filter((w) => w.error).map((w) => w.kind);
+    verdict =
+      `CONCERNS — ${gatingError}/${N} gating worker(s) errored (${erroredKinds.join(', ')}), none failed (manual-confirm available)` +
+      advisoryNote;
+    panelOutcome = 'concerns';
+    forwardedConfidence = FALLTHROUGH_CONFIDENCE;
+  } else if (gatingConcerns > 0 || advisoryFail) {
+    // Gating-worker concerns, OR an advisory Narc 'fail' (downgraded here from a
+    // hard block) → manual-confirm.
+    const reasons = [];
+    if (gatingConcerns > 0) reasons.push(`${gatingConcerns}/${N} gating worker(s) flagged concerns`);
+    if (advisoryFail) reasons.push('narc (advisory) flagged a functional-fidelity failure');
+    verdict = `CONCERNS — ${reasons.join('; ')} (manual-confirm available)`;
+    panelOutcome = 'concerns';
+    forwardedConfidence = FALLTHROUGH_CONFIDENCE;
+  } else if (gatingAllPass) {
+    // Every gating worker passed. A Narc 'concerns' here is advisory only.
+    verdict = `PASS — ${gating.length}/${gating.length} gating worker(s) cleared${advisoryConcerns ? ' (narc advisory: concerns)' : ''}`;
+    panelOutcome = 'pass';
+    forwardedConfidence = medianConf;
+  } else {
+    // Should be unreachable (no fail/concerns and not all gating pass implies an
+    // unknown verdict) but be defensive.
+    verdict = `FAIL — unknown verdict state (pass=${passCount} concerns=${concernsCount} fail=${failCount} of ${N})`;
+    panelOutcome = 'fail';
+    forwardedConfidence = 0;
+  }
+
+  const passed = panelOutcome === 'pass';
+
+  // Dedupe issues by (worker kind, file, summary) — intentional. If Narc and
+  // Quality both flag the same (file, summary), the two appear separately
+  // because they are independent confirmations from different lenses; merging
+  // would erase that signal.
+  const seen = new Set();
+  const issues = [];
+  for (const w of workerResults) {
+    for (const it of (w.issues || [])) {
+      if (!it || typeof it !== 'object') continue;
+      const key = `${w.kind}::${it.file ?? ''}::${(it.summary ?? '').trim()}`;
+      if (seen.has(key)) continue;
+      seen.add(key);
+      issues.push({ ...it, worker: w.kind });
+    }
+  }
+
+  // Build display notes.
+  const lines = [];
+  lines.push(`Subagent grader ${VERSION} (panel of ${N}: ${workerResults.map((w) => w.kind).join(', ')}) — ${verdict}`);
+  if (ff != null) lines.push(`  functional_fidelity (Narc):  ${ff}/10`);
+  if (cq != null) lines.push(`  code_quality (Quality):      ${cq}/10`);
+  if (economy != null) lines.push(`  economy (Quality, adv.):     ${economy}/10`);
+  if (security != null) lines.push(`  security_score (Hacker):     ${security}/10`);
+  if (efficiencyScore != null) lines.push(`  efficiency_score (EffMng):   ${efficiencyScore}/10`);
+  lines.push(`  blended:                     ${blended}/10  (threshold ${THRESHOLD}, gating workers must PASS; narc advisory — #481)`);
+  lines.push(`  forwarded confidence:       ${forwardedConfidence ?? '?'}  (panel: ${panelOutcome})`);
+  lines.push('');
+  lines.push('Per-worker:');
+  for (const w of workerResults) {
+    const status = w.error ? 'ERROR' : w.verdict.toUpperCase();
+    const scores = Object.entries(w.scores || {})
+      .filter(([_, v]) => Number.isFinite(v))
+      .map(([k, v]) => `${k.split('_').map((p) => p[0]).join('')}=${v}`)
+      .join(' ');
+    const confStr = w.confidence != null ? `  conf=${w.confidence}` : '';
+    const errStr = w.error ? `  (${w.error})` : '';
+    const retryStr = w.retried ? '  (retried — #465)' : '';
+    lines.push(`  ${w.kind.padEnd(10)} ${status.padEnd(8)} ${scores}${confStr}  ${w.model ?? '?'}${errStr}${retryStr}`);
+  }
+  if (issues.length > 0) {
+    lines.push('');
+    lines.push(`Issues (${issues.length} unique across workers):`);
+    for (const it of issues.slice(0, 30)) {
+      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} (${it.worker}) — ${summary}`);
+    }
+    if (issues.length > 30) {
+      lines.push(`  ... ${issues.length - 30} more (full set in signals.workers[].issues)`);
+    }
+  }
+
+  // #486 (ADR 0028 path 1): sum each worker's own subprocess cost (from its
+  // `claude -p` envelope total_cost_usd). Workers that errored / never produced
+  // a JSON envelope contribute null → 0. The deterministic route-rank pseudo-
+  // worker has no subprocess and no cost_usd, so it's naturally excluded.
+  const panelCostUsd = workerResults.reduce((s, w) => s + (Number(w.cost_usd) || 0), 0);
+
+  return {
+    // server-compat top-level
+    score: blended,
+    passed,
+    threshold: THRESHOLD,
+    grader_kind: 'subagent-panel',
+    grader_version: VERSION,
+    // #486: the panel's own API spend (USD), for cost_log (source=grader).
+    panel_cost_usd: panelCostUsd,
+    // rubric_scores keep the v3 keys so the trend dashboard + audit-ships
+    // legacy v1 entry-points continue to read them. Phase 2.1 added
+    // security_score; Phase 2.2 adds efficiency_score. Both additive —
+    // consumers that don't know about them just ignore the fields.
+    rubric_scores: {
+      functional_fidelity: ff,
+      code_quality: cq,
+      economy,
+      code_quality_effective: cqEffective,
+      security_score: security,
+      efficiency_score: efficiencyScore,
+    },
+    signals: {
+      grader_kind: 'subagent-panel',
+      grader_version: VERSION,
+      threshold: THRESHOLD,
+      // forwardedConfidence drives the server-side gate alignment
+      confidence: forwardedConfidence,
+      panel_outcome: panelOutcome,
+      workers: workerResults,
+      worker_count: N,
+      pass_count: passCount,
+      concerns_count: concernsCount,
+      fail_count: failCount,
+      error_count: errorCount,
+      panel_cost_usd: panelCostUsd, // #486: mirror into signals for the audit trail
+      ...meta,
+    },
+    notes_md: lines.join('\n'),
+    issues,
+  };
+}
+
+// #943: synthesize the distinct "grader unavailable / bypassed" result WITHOUT
+// spawning any worker. Same shape as aggregatePanel's return so every consumer
+// (buildGradePayload, the server's validateAndScore re-run, ship.js's
+// printGradeOutcome) works unchanged. ff/cq are null (nothing was graded) and
+// the forwarded confidence is FALLTHROUGH_CONFIDENCE, so the server gate treats
+// it as manual-confirm — never an auto-pass, never an auto-credit. panel_outcome
+// carries the 'unavailable' tag so ship.js presents "grader unavailable" rather
+// than a misleading "FAIL · 0/10". `reason` is recorded for the audit trail.
+function graderUnavailableResult({ reason, note, meta = {} } = {}) {
+  const notes = [
+    `Subagent grader ${VERSION} — GRADER UNAVAILABLE (${reason}).`,
+    note || 'The grader did not run — this is an infra/outage/bypass condition, NOT a quality rejection. Manual-confirm available.',
+  ].join('\n');
+  return {
+    score: 0,
+    passed: false,
+    threshold: THRESHOLD,
+    grader_kind: 'subagent-panel',
+    grader_version: VERSION,
+    panel_cost_usd: 0,
+    rubric_scores: {
+      functional_fidelity: null,
+      code_quality: null,
+      economy: null,
+      code_quality_effective: null,
+      security_score: null,
+      efficiency_score: null,
+    },
+    signals: {
+      grader_kind: 'subagent-panel',
+      grader_version: VERSION,
+      threshold: THRESHOLD,
+      confidence: FALLTHROUGH_CONFIDENCE,
+      panel_outcome: 'unavailable',
+      grader_unavailable_reason: reason,
+      workers: [],
+      worker_count: 0,
+      pass_count: 0,
+      concerns_count: 0,
+      fail_count: 0,
+      error_count: 0,
+      panel_cost_usd: 0,
+      ...meta,
+    },
+    notes_md: notes,
+    issues: [],
+  };
+}
+
+// End-to-end v4 grader. Runs the worker panel through the cross-family
+// grader model and returns the panel-aggregated grade-result.
+//
+// workers: defaults to DEFAULT_PANEL (narc + quality). An array of worker
+//   kinds (strings) like ['narc', 'quality']. Phase 2.1/2.2 will extend.
+// builderModel: the model the builder used. Defaults to ASSUMED_BUILDER_MODEL
+//   (Opus, per CLAUDE.md §2). Drives selectGraderModel — workers pick the
+//   cross-family alternative.
+async function gradeSubagent({ task, valueSummary, diff, changedFiles, diffStats, workers: workerKinds, builderModel, builderRank, runOpts = {} }) {
+  // #943: bypass / disabled short-circuit — BEFORE resolving the panel or
+  // spawning any worker. When the grader is globally bypassed (the
+  // GRADER_BYPASS_ENABLED killswitch, ADR 0041) or a caller explicitly disables
+  // it (runOpts.bypass), do NOT spawn the panel. Spawning into an outage/bypass
+  // window is exactly what manufactured the "FAIL · 0/10" false-verdict in
+  // session 1659 — the bypass was honored only DOWNSTREAM of the spawn. Return
+  // the distinct 'unavailable' outcome so the result reads as "grader bypassed",
+  // never a quality 0/10.
+  if (runOpts.bypass === true || process.env.GRADER_BYPASS_ENABLED === '1') {
+    const reason = runOpts.bypass === true ? 'bypass_requested' : 'grader_bypass_enabled';
+    return graderUnavailableResult({
+      reason,
+      note: 'Grader bypassed before worker spawn (GRADER_BYPASS_ENABLED / runOpts.bypass) — no panel ran. Land via manual-confirm (/confirm).',
+      meta: { builder_model_assumed: builderModel || ASSUMED_BUILDER_MODEL, bypassed: true },
+    });
+  }
+  const panel = workers.resolvePanel(workerKinds ?? workers.DEFAULT_PANEL);
+  const graderModel = selectGraderModel({ builderModel });
+
+  // Deterministic route-rank pre-pass — its findings feed the Hacker as input;
+  // its pseudo-worker result is appended to the panel below.
+  const routeRank = routeRankPrePass(changedFiles);
+  // Deterministic permission-path pre-pass (SEC #863) — a sub-Metic diff that
+  // touches the rank/permission/ship-grade/deploy machinery hard-fails.
+  const permPath = permissionPathPrePass(changedFiles, builderRank);
+  const deterministicFindings = [
+    ...(routeRank ? routeRank.findings : []),
+    ...(permPath ? permPath.findings : []),
+  ];
+
+  const startedAt = Date.now();
+  const workerPromises = panel.map((worker) => workers.runWorker(worker, {
+    task,
+    valueSummary,
+    diff,
+    changedFiles,
+    diffStats,
+    model: graderModel,
+    runOpts,
+    runSubagentFn: runSubagent,
+    extractAssistantResultFn: extractAssistantResult,
+    deterministicFindings: deterministicFindings.length ? deterministicFindings : null,
+  }));
+  const workerResults = await Promise.all(workerPromises);
+  // Append the deterministic checks as pseudo-workers so the any-fail gate
+  // treats a write-route 'unknown' OR a sub-Metic permission-path edit as a
+  // hard block with no gate-logic change.
+  if (routeRank) workerResults.push(routeRank.workerResult);
+  if (permPath) workerResults.push(permPath.workerResult);
+  const totalMs = Date.now() - startedAt;
+
+  return aggregatePanel(workerResults, {
+    builder_model_assumed: builderModel || ASSUMED_BUILDER_MODEL,
+    grader_model: graderModel,
+    total_ms: totalMs,
+  });
+}
+
+// ---------- v3 multi-shot path (kept exported for explicit diagnostics) ----------
+//
+// Same shape as the original v3 gradeSubagent; renamed so the public name
+// (gradeSubagent) points at the v4 panel. Useful for re-running a single
+// generalist prompt N times for diagnostic comparison against the panel.
+async function gradeSubagentV3MultiShot({ task, valueSummary, diff, changedFiles, diffStats, shots = DEFAULT_SHOTS, builderModel, runOpts = {} }) {
+  const prompt = buildPrompt({ task, valueSummary, diff, changedFiles, diffStats });
+  const graderModel = selectGraderModel({ builderModel });
+  const N = Math.max(1, Math.trunc(shots));
+
+  const startedAt = Date.now();
+  const shotPromises = [];
+  for (let i = 0; i < N; i++) {
+    shotPromises.push(runOneShot({ prompt, model: graderModel, shotIndex: i, runOpts }));
+  }
+  const shotResults = await Promise.all(shotPromises);
+  const totalMs = Date.now() - startedAt;
+
+  return aggregateShots(shotResults, {
+    builder_model_assumed: builderModel || ASSUMED_BUILDER_MODEL,
+    grader_model: graderModel,
+    total_ms: totalMs,
+  });
+}
+
+// =========================================================================
+// Legacy v1 (deterministic) — kept for scripts/gds/audit-ships.js only.
+// =========================================================================
+
+function scoreEstActualBand(actualMinutes, estMinutes) {
+  if (!Number.isFinite(actualMinutes) || actualMinutes <= 0) return 5;
+  if (!Number.isFinite(estMinutes) || estMinutes <= 0) return 6;
+  const ratio = actualMinutes / estMinutes;
+  if (ratio >= 0.5 && ratio <= 2.0) return 10;
+  if (ratio < 0.5) {
+    if (ratio <= 0.1) return 0;
+    return r1(10 * ((ratio - 0.1) / 0.4));
+  }
+  if (ratio > 2.0) {
+    if (ratio >= 10) return 0;
+    return r1(10 * (1 - (ratio - 2.0) / 8.0));
+  }
+  return 5;
+}
+
+function scoreValueSummary(valueSummary) {
+  const s = (valueSummary || '').trim();
+  if (s.length === 0) return 0;
+  if (s.length < 40) return 5;
+  if (s.length < 120) return 8;
+  return /\b(add|fix|update|remove|refactor|wire|land|migrate|enable|disable|introduce|deprecate|ship|deploy|prevent|capture|gate|allocate|carry|expose|surface)\b/i.test(s)
+    ? 10
+    : 8;
+}
+
+function scoreDiffHygiene(diffStats) {
+  if (!diffStats) return 5;
+  const files = Number(diffStats.files_changed) || 0;
+  const added = Number(diffStats.lines_added) || 0;
+  const removed = Number(diffStats.lines_removed) || 0;
+  if (files === 0 || added + removed === 0) return 0;
+  if (files > 50) return 5;
+  return 10;
+}
+
+function scoreScannerSmoke(verification) {
+  if (!verification) return 5;
+  return verification.scanner_clean && verification.smoke_clean ? 10 : 5;
+}
+
+function scoreScopingSignal(scopingConfidence) {
+  if (scopingConfidence == null) return 6;
+  const c = Number(scopingConfidence);
+  if (c <= 0) return 2;
+  if (c === 1) return 4;
+  if (c === 2) return 6;
+  if (c === 3) return 7;
+  if (c === 4) return 8;
+  return 10;
+}
+
+function scoreLocNetNegative(diffStats) {
+  if (!diffStats) return 5;
+  const added = Number(diffStats.lines_added) || 0;
+  const removed = Number(diffStats.lines_removed) || 0;
+  if (removed > added) return 10;
+  if (removed === added) return 5;
+  return 0;
+}
+
+function scoreLearningRow(learningRow) {
+  if (!learningRow) return 0;
+  const body = (learningRow.body_md || '').trim();
+  if (body.length > 100) return 10;
+  if (body.length > 0) return 5;
+  return 0;
+}
+
+function scoreArtRubricAvg(value) {
+  if (!Number.isFinite(value)) return null;
+  return clamp(r1(value), 0, 10);
+}
+
+function blendWeightsForKind(kind) {
+  const blended = {};
+  for (const [name, def] of Object.entries(V1.weights.common)) {
+    blended[name] = def.weight;
+  }
+  const kindBonus = V1.weights.kind_specific[kind];
+  if (kindBonus) {
+    for (const [name, def] of Object.entries(kindBonus)) {
+      if (name === 'loc_net_negative' && 'diff_hygiene' in blended) delete blended.diff_hygiene;
+      if (name === 'learning_row' && 'diff_hygiene' in blended) delete blended.diff_hygiene;
+      blended[name] = def.weight;
+    }
+  }
+  const total = Object.values(blended).reduce((a, b) => a + b, 0);
+  for (const k of Object.keys(blended)) blended[k] = blended[k] / total;
+  return blended;
+}
+
+// Legacy v1 entry. Renamed from `grade()` in V3.R18 (#209). Now ONLY
+// called from scripts/gds/audit-ships.js (retroactive #204 audit). The
+// runtime ship path uses gradeSubagent (v3 multi-shot).
+function gradeDeterministic({ task, verification, actualMinutes, valueSummary, learningRow }) {
+  const kind = task?.kind || 'unclassified';
+  const weights = blendWeightsForKind(kind);
+  const rubricScores = {};
+  const signals = {
+    kind,
+    est_minutes: task?.est_minutes ?? null,
+    actual_minutes: actualMinutes ?? null,
+    scoping_confidence: task?.scoping_confidence ?? null,
+    scanner_clean: verification?.scanner_clean ?? null,
+    smoke_clean: verification?.smoke_clean ?? null,
+    diff_stats: verification?.diff_stats ?? null,
+    art_rubric_avg: verification?.art_rubric_avg ?? null,
+    value_summary_chars: (valueSummary || '').trim().length,
+  };
+
+  if ('est_actual_band' in weights) {
+    rubricScores.est_actual_band = scoreEstActualBand(actualMinutes, task?.est_minutes);
+  }
+  if ('value_summary' in weights) {
+    rubricScores.value_summary = scoreValueSummary(valueSummary);
+  }
+  if ('diff_hygiene' in weights) {
+    rubricScores.diff_hygiene = scoreDiffHygiene(verification?.diff_stats);
+  }
+  if ('scanner_smoke' in weights) {
+    rubricScores.scanner_smoke = scoreScannerSmoke(verification);
+  }
+  if ('scoping_signal' in weights) {
+    rubricScores.scoping_signal = scoreScopingSignal(task?.scoping_confidence);
+  }
+  if ('loc_net_negative' in weights) {
+    rubricScores.loc_net_negative = scoreLocNetNegative(verification?.diff_stats);
+  }
+  if ('learning_row' in weights) {
+    rubricScores.learning_row = scoreLearningRow(learningRow);
+  }
+  if ('art_rubric_avg' in weights) {
+    const s = scoreArtRubricAvg(verification?.art_rubric_avg);
+    if (s == null) {
+      const w = weights.art_rubric_avg;
+      delete weights.art_rubric_avg;
+      const remaining = Object.values(weights).reduce((a, b) => a + b, 0);
+      if (remaining > 0) {
+        for (const k of Object.keys(weights)) weights[k] = weights[k] / remaining;
+      }
+    } else {
+      rubricScores.art_rubric_avg = s;
+    }
+  }
+
+  let score = 0;
+  for (const [name, w] of Object.entries(weights)) {
+    if (rubricScores[name] != null) score += rubricScores[name] * w;
+  }
+  score = r1(clamp(score, 0, 10));
+
+  const threshold = V1.threshold;
+  const passed = score >= threshold;
+
+  const lines = [];
+  lines.push(`Auto-grader ${V1.version} (deprecated) — task_kind=${kind}.`);
+  lines.push(`Score ${score}/10 vs threshold ${threshold} → ${passed ? 'PASS' : 'FAIL'}.`);
+  lines.push('');
+  lines.push('Per-criterion:');
+  for (const [name, w] of Object.entries(weights)) {
+    const s = rubricScores[name];
+    if (s == null) continue;
+    const contrib = r1(s * w);
+    lines.push(`  - ${name.padEnd(20)} ${String(s).padStart(4)}/10  × ${w.toFixed(2)} = ${contrib}`);
+  }
+
+  return {
+    score,
+    passed,
+    threshold,
+    grader_kind: 'auto',
+    grader_version: V1.version,
+    rubric_scores: rubricScores,
+    signals,
+    notes_md: lines.join('\n'),
+  };
+}
+
+module.exports = {
+  // v4 surface (active panel-based gate)
+  aggregatePanel,
+  gradeSubagent,                  // panel by default
+  graderUnavailableResult,        // #943: distinct grader-unavailable / bypassed result (no spawn)
+  isTrivialDiff,                  // #513: copy/docs fast-path classifier
+  WORKERS: workers,               // registry re-export
+  routeRankPrePass,               // deterministic route-rank pre-pass (#475)
+  permissionPathPrePass,          // deterministic sub-Metic permission-path gate (SEC #863)
+  serverSideGuards,               // SR-9 / SR-18: server-authoritative grade hardening (downgrade-only)
+  changeMagnitude,                // SR-9 helper: file/line magnitude from committed_files + diff_stats
+  FALLTHROUGH_CONFIDENCE,
+  // v3 surface (kept exported for diagnostics + tests)
+  buildPrompt,
+  selectGraderModel,
+  validateAndScore,
+  aggregateShots,
+  runSubagent,
+  runSubagentCached,              // System 5 (task 1359): opt-in content-addressed cached path
+  runOneShot,
+  gradeSubagentV3MultiShot,       // explicit v3 multi-shot diagnostic path
+  extractJson,
+  extractAssistantResult,
+  extractCostUsd,                 // #486: parse total_cost_usd from the envelope
+  THRESHOLD,
+  VERSION,
+  DEFAULT_GRADER_MODEL,
+  DEFAULT_SHOTS,
+  ASSUMED_BUILDER_MODEL,
+  // legacy v1 (audit-ships.js only)
+  gradeDeterministic,
+  scoreEstActualBand,
+  scoreValueSummary,
+  scoreDiffHygiene,
+  scoreScannerSmoke,
+  scoreScopingSignal,
+  scoreLocNetNegative,
+  scoreLearningRow,
+  scoreArtRubricAvg,
+  blendWeightsForKind,
+  RUBRIC,
+};