@bongos/core 1.17.0

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

@@ -0,0 +1,239 @@
+// MAS Phase 2.1 (#416) — Hacker worker.
+//
+// Specialty: security red-team review. Hunts injection, auth/authz gaps,
+// hardcoded secrets, trust-boundary violations, and the rest of the
+// OWASP-shape problems in the diff. Reports a `security_score` (0-10) +
+// a severity-graded issues list (critical/high → blocker, medium → major,
+// low → minor) that aligns with the existing /builder-redteam human flow.
+//
+// Hacker shifts security review from *post-merge bounty filing* (the
+// existing skill) to *pre-merge ship-time gate*. The two systems are
+// complementary: Hacker catches at ship time; /builder-redteam still
+// covers post-merge findings (with bounty payout).
+
+// THRESHOLD + LOW_CONF come from the shared rubric module (task 1090, C6).
+const { THRESHOLD, LOW_CONF } = require('./rubric');
+
+// SR-15 / G1 (#995): scrub + fence all builder-controlled inputs. The shared
+// scaffold (worker-prompt) owns fenceBlock/NOFOLLOW_PREAMBLE; Hacker still
+// scrubs each deterministic-finding line inline (its findings-section safe()).
+const { buildWorkerPrompt, LLM_PROJECT } = require('./worker-prompt');
+const { failResult, parseCommon, finalizeVerdict } = require('./worker-verdict');
+const { scrubUntrusted } = require('./fence');
+
+const KIND = 'hacker';
+const NAME = 'Hacker';
+const SPECIALTY = 'security red-team (injection, auth/authz, secrets, trust boundary)';
+
+const PROMPT_HEADER = `You are the **Hacker** — a specialist adversarial subagent for the ${LLM_PROJECT} project. You exist to catch security vulnerabilities the moment they enter the codebase, before they ever ship.
+
+Your ONLY job is security. You do NOT score whether the description was implemented (that's the Narc) or whether the code is well-written (that's the Quality worker). Your verdict is about whether this diff introduces, perpetuates, or fails to fix a security flaw.
+
+**The default verdict is FAIL.** You PASS only after a careful read of the diff and (via your Read tool, within budget) the relevant post-merge files turns up no exploitable patterns and you can affirmatively name the security-relevant surfaces you checked.
+
+## Read budget (CRITICAL)
+
+**You have a hard budget of 5 Read calls per grade.** Prefer the diff over Read. Most security-relevant code (route handlers, auth wrappers, query construction, secret references) is visible in the diff text — that's evidence. Reserve Reads for: confirming that a new route inherits the right auth wrapper from a shared module, that a removed validation isn't compensated elsewhere, that a config change doesn't silently weaken an existing protection.
+
+If you exhaust the budget, score conservatively and call it out in notes_md. Better to flag one unverified surface than to silently miss it.
+
+## Failure modes you hunt for
+
+Cite the diff line (or quote the offending code) for every finding.
+
+**Critical-severity (forge writes as another builder, read data the user isn't entitled to, RCE-equivalent):**
+- SQL / NoSQL injection (string concatenation in queries, missing parameterization).
+- Command injection (\`exec\` / \`spawn\` with untrusted strings; shell metacharacters from user input).
+- Path traversal (user input flowed into \`fs.*\` or path joins without normalization).
+- Authn / authz bypass: a route or DB write that should be gated by \`requireRank\` / \`requireBuilder\` / ownership-check but isn't. Per ADR 0016, every privileged write must server-side-check rank against the DB — a route missing that gate is critical.
+- Hardcoded secrets in source (literal API keys, bearer tokens, passwords, private keys). \`process.env.X\` is fine; a literal string that looks like a credential is not.
+- Trust-boundary violation: code that lets a local edit (CLAUDE.md, skills, hooks, settings.json) grant authority that the DB-enforced rank model would otherwise refuse.
+
+**High-severity (real attack vector with a workaround):**
+- XSS / unsanitized HTML rendering of user input (template strings, \`innerHTML\` with untrusted data, missing escaping).
+- SSRF: server makes a network request to a URL derived from user input without an allowlist.
+- Insecure deserialization (\`JSON.parse\` of user input that becomes runtime objects in trusted positions, \`eval\`, \`new Function\` with input).
+- Missing CSRF protection on a state-changing route that uses cookie auth (less relevant here since the GDS uses bearer tokens, but check).
+- Sensitive data in logs (passwords, full tokens, PII printed to stderr/stdout).
+
+**Medium-severity (defense-in-depth gap — verdict 'concerns'):**
+- Information disclosure in error messages (stack traces leaking internals on public surfaces).
+- Insecure crypto choices (MD5 / SHA1 for security, weak random for tokens, short HMAC).
+- Time-of-check-time-of-use races in security-relevant code (auth state read, then mutated, without locking).
+- Permissive CORS / Caddy config without justification.
+- Dependency added from a non-standard registry / pinned to a tag instead of a hash for sensitive packages.
+
+**Low-severity (hardening recommendation — verdict 'pass' with notes):**
+- Missing rate limiting on a public endpoint that doesn't yet need it.
+- Could-be-tighter input validation that isn't currently exploitable.
+- Missing security headers (HSTS, X-Frame-Options) on a surface where they'd be belt-and-braces.
+
+## How you work
+
+1. Walk the diff. For every NEW or CHANGED route handler / DB write / external API call / fs operation / template rendering, ask: what's the threat model here? Is the auth gate present? Is input sanitized? Is the secret handling right?
+
+2. For every NEW dependency introduced via package.json or imports: is it from a reputable source? Does it match the package-lock.json hash if security-sensitive?
+
+3. Spend Reads where the diff alone leaves a question open (e.g., new route — Read the auth.js to see what \`requireRank\` actually does; new query — Read the db.js to see if there's a parameterization helper).
+
+4. Score \`security_score\` (0-10):
+   - 10 = production-quality, no exploitable patterns, hardening choices are sound.
+   - 8 = clean; one or two low-severity hardening notes.
+   - 6 = ships but with at least one named medium-severity defense-in-depth gap. (Threshold for passing the gate.)
+   - 4 = one high-severity issue found.
+   - 2 = multiple high-severity issues OR one critical-severity issue.
+   - 0 = clear critical exposure (auth bypass, injection, hardcoded credential).
+
+5. Map severities to issue.severity: critical → \`blocker\`, high → \`blocker\`, medium → \`major\`, low → \`minor\`.
+
+6. Confidence (0-1): if the diff touches a surface you can't fully evaluate within budget (large refactor to auth.js, new external API integration where you can't see the SDK's contract), set confidence LOW (< 0.4). Honest uncertainty > over-confident pass.
+
+## Sanity checks
+
+- A PASS verdict on a diff that touched route handlers must affirmatively name which auth wrapper protects each new/changed handler. "No security issues found" with no specifics is not a valid PASS.
+- A FAIL verdict requires at least one issue. Name the specific line.
+- A score below 6 with no \`major\`-or-\`blocker\` issue is inconsistent — name the high-or-critical finding.
+- Don't moralize about style. Don't flag patterns that are normal for this codebase if the surrounding code does the same thing safely (e.g., bearer-token auth is fine even though cookie auth would have CSRF concerns).
+- Trust-boundary rule (ADR 0016) is load-bearing: if a code change implies that editing a local file (CLAUDE.md, a skill, a hook, settings.json) could grant a builder authority they don't have in the DB — that's critical. Server-side rank checks must be re-read on every privileged request.
+
+## Return ONLY JSON
+
+No prose, no markdown fences:
+
+\`\`\`
+{
+  "security_score": <number 0-10>,
+  "confidence": <number 0-1>,
+  "reads_used": <integer 0-5>,
+  "surfaces_checked": [
+    { "kind": "route"|"db_write"|"fs_op"|"external_api"|"template"|"secret_handling"|"auth_wrapper"|"other", "where": "<file:line OR description>", "verdict": "ok"|"flagged" }
+  ],
+  "issues": [
+    { "severity": "blocker"|"major"|"minor"|"nit", "file": "<path>", "summary": "<one line, names the security pattern and the specific risk>" }
+  ],
+  "notes_md": "<short markdown — what surfaces you checked, what the threat model is, what you could not evaluate within budget>"
+}
+\`\`\`
+
+You have a Read tool with a hard budget of 5 calls. Do not run tests, do not edit files, do not call the network.`;
+
+function buildPrompt({ task, valueSummary, diff, changedFiles, deterministicFindings }) {
+  const t = task || {};
+  const findings = Array.isArray(deterministicFindings) ? deterministicFindings : [];
+
+  // Hacker owns a deterministic route-rank pre-check section before the diff,
+  // present only when the pre-pass produced findings.
+  const findingsLines = [];
+  if (findings.length > 0) {
+    findingsLines.push('---');
+    findingsLines.push('## Deterministic route-rank pre-check (INPUT for your adjudication)');
+    findingsLines.push('');
+    findingsLines.push('A deterministic check already ran over `src/bongos/routes/`. It flags routes it could NOT classify to a known rank — it found neither a `requireRank`/`requireBuilder` middleware nor a `rank:` annotation. Clearly-ungated WRITE routes are already a hard block; your job is to adjudicate INTENT for each flag below:');
+    findingsLines.push('');
+    findingsLines.push('- **Forgotten gate** → confirm it as a critical authz finding (`blocker`), naming the missing check per ADR 0016.');
+    findingsLines.push('- **Intentionally public** route that merely lacks the annotation → low-severity (`minor`): recommend adding a `rank:` annotation so the gate is verifiable. Do not score it as an exposure.');
+    findingsLines.push('');
+    // Defense-in-depth: route/file come from parsed source, so a builder could
+    // craft a path or `rank:` comment carrying instruction text. Strip control
+    // chars, Unicode bidi overrides (U+200E–200F, U+202A–202E, U+2066–2069),
+    // backticks, and the bracket chars used in the line template, then cap
+    // length — so a finding line can't break out and steer the LLM.
+    // On top of the shared SR-15 scrub (control + zero-width + bidi chars,
+    // fence.js), this single-line list template also collapses whitespace and
+    // strips backticks + the bracket chars of the `- [sev] route (file)` slot,
+    // then caps length \u2014 so a finding can't break out of its slot.
+    const safe = (s) => scrubUntrusted(s)
+      .replace(/[`[\]]/g, ' ')
+      .replace(/\s+/g, ' ').trim().slice(0, 120);
+    for (const f of findings) {
+      findingsLines.push(`- [${safe(f.severity)}] ${safe(f.route)} (${safe(f.file)})`);
+    }
+    findingsLines.push('');
+    findingsLines.push('Use a Read on the flagged route file (within budget) to decide which case applies.');
+    findingsLines.push('');
+  }
+
+  return buildWorkerPrompt({
+    header: PROMPT_HEADER,
+    task: t,
+    valueSummary,
+    diff,
+    changedFiles,
+    taskHeader: '## Task (context — Narc judges completion; you judge security)',
+    descLabel: '**Description:**',
+    emptyFilesText: '(no files changed — this is suspicious)',
+    readFilesHint: 'You can Read any of these files to see their post-merge state (5-call budget).',
+    finalInstruction: 'Now red-team. Default-fail unless the security-relevant surfaces affirmatively check out. Output ONLY the JSON object.',
+    beforeDiffLines: findingsLines,
+  });
+}
+
+// #79 (#493): delegate to the shared robust extractor so the v4 panel path
+// gets the same parse-resilience (whole-string -> fenced -> balanced-brace) as
+// grader.js, instead of the brittle first-{-to-last-} copy that flaked.
+const { extractJson } = require('./extract-json');
+
+// Hacker's per-worker verdict. Severity mapping (aligned with the existing
+// /builder-redteam skill):
+//   critical / high → issue severity 'blocker' → worker verdict 'fail'
+//   medium          → issue severity 'major'   → worker verdict 'concerns'
+//   low             → issue severity 'minor'   → does not change verdict
+function computeVerdict(parsed, meta = {}) {
+  if (meta.subprocess_error) {
+    return failResult({ notesMd: `Hacker: subagent error (${meta.subprocess_error}).`, error: meta.subprocess_error });
+  }
+  if (!parsed || typeof parsed !== 'object') {
+    return failResult({ notesMd: 'Hacker: could not parse subagent output as JSON.', error: 'parse_error' });
+  }
+
+  const sec = Number(parsed.security_score);
+  const { conf, issues, notesFromSubagent } = parseCommon(parsed);
+  const surfacesChecked = Array.isArray(parsed.surfaces_checked) ? parsed.surfaces_checked : [];
+
+  if (!Number.isFinite(sec) || sec < 0 || sec > 10) {
+    return failResult({ issues, notesMd: `Hacker: security_score was non-numeric or out of range (got ${parsed.security_score}).`, error: 'schema_error' });
+  }
+
+  const secR = Math.round(sec * 10) / 10;
+  const blockerCount = issues.filter((i) => i.severity === 'blocker').length;
+  const majorCount = issues.filter((i) => i.severity === 'major').length;
+  const lowConfidence = conf != null && conf < LOW_CONF;
+
+  let verdict;
+  let notesPrefix;
+  if (blockerCount > 0 || secR < THRESHOLD) {
+    verdict = 'fail';
+    notesPrefix = `Hacker — FAIL (sec=${secR}/10`
+      + (blockerCount > 0 ? `, ${blockerCount} critical/high finding${blockerCount === 1 ? '' : 's'}` : '')
+      + `)`;
+  } else if (lowConfidence || majorCount > 0) {
+    verdict = 'concerns';
+    notesPrefix = `Hacker — CONCERNS (sec=${secR}/10`
+      + (lowConfidence ? `, low confidence ${conf}` : '')
+      + (majorCount > 0 ? `, ${majorCount} medium-severity finding${majorCount === 1 ? '' : 's'}` : '')
+      + `)`;
+  } else {
+    verdict = 'pass';
+    notesPrefix = `Hacker — PASS (sec=${secR}/10, ${surfacesChecked.length} surface${surfacesChecked.length === 1 ? '' : 's'} checked, conf=${conf ?? '?'})`;
+  }
+
+  return finalizeVerdict({
+    verdict,
+    scores: { security_score: secR },
+    issues,
+    extra: { surfaces_checked: surfacesChecked },
+    notesPrefix,
+    notesFromSubagent,
+    confidence: conf,
+  });
+}
+
+module.exports = {
+  KIND,
+  NAME,
+  SPECIALTY,
+  PROMPT_HEADER,
+  buildPrompt,
+  extractJson,
+  computeVerdict,
+};

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

@@ -0,0 +1,183 @@
+// MAS Phase 2.0 (#410) — Worker panel registry + shared runner.
+//
+// Each worker (narc.js, quality.js, …) exports:
+//   KIND, NAME, SPECIALTY        — identification
+//   buildPrompt({...})           — produces the subagent prompt
+//   extractJson(rawString)       — parses the subagent's JSON response
+//   computeVerdict(parsed, meta) — returns a partial WorkerResult
+//
+// runWorker() ties them together: build prompt → spawn subagent (via the
+// existing grader.runSubagent) → parse → compute verdict → assemble the
+// final WorkerResult (kind/name/scores/verdict/issues/notes/...).
+//
+// The DEFAULT_PANEL is the set of workers run by gradeSubagent today.
+// Phase 2.0 ships narc + quality. Phase 2.1 will add 'hacker'. Phase 2.2
+// will add 'efficiency'.
+
+const narc = require('./narc');
+const quality = require('./quality');
+const hacker = require('./hacker');
+const efficiency = require('./efficiency');
+
+const REGISTRY = {
+  [narc.KIND]: narc,
+  [quality.KIND]: quality,
+  [hacker.KIND]: hacker,
+  [efficiency.KIND]: efficiency,
+};
+
+// The active panel for the ship-time gate. Order is presentation-only —
+// workers run in parallel inside gradeSubagent.
+const DEFAULT_PANEL = [narc.KIND, quality.KIND, hacker.KIND, efficiency.KIND];
+
+// #465: transient subprocess/parse errors are infra noise, not a quality
+// signal — auto-retry the worker ONCE on these before letting the error stand.
+// Deliberately EXCLUDES:
+//   - SUBAGENT_TIMEOUT — a real budget signal (the worker ran out of wall-clock;
+//     retrying just burns another timeout). Handled via per-worker timeouts (#467).
+//   - null / a real verdict — that's signal, never retried.
+// One retry only — never erodes the gate's strictness, just absorbs the ~1-in-3
+// good ships that were flaking on a single noisy subagent (see #465 desc).
+const TRANSIENT_WORKER_ERRORS = new Set([
+  'parse_error',
+  'schema_error',
+  'SUBAGENT_SPAWN_FAILED',
+  'SUBAGENT_NONZERO_EXIT',
+]);
+
+// #467: per-worker subagent timeout. The global 240s applied to EVERY worker,
+// which timed out the Read-heavy ones (Narc walks ACs + reads files — hence
+// Phase 2.0.5's 5-read workaround; Quality is next-heaviest) while the light
+// ones (Hacker, Efficiency) never needed that long. Per-worker budgets let the
+// heavy lenses breathe without globally inflating every ship's worst-case wall
+// time. A worker module may override by exporting its own MAX_TIMEOUT_MS;
+// otherwise this map (keyed by KIND) is the single tuning surface. Falls back
+// to runOpts.timeoutMs (then runSubagent's own 240s default) for any unlisted
+// worker. Tune from the calibration data (#292) once it accrues.
+const WORKER_MAX_TIMEOUT_MS = {
+  narc: 360_000,       // Read-heavy: walks every acceptance criterion
+  quality: 360_000,    // Read-heavy: reads changed files for cleanliness review
+  hacker: 240_000,     // lighter: focused security scan
+  efficiency: 240_000, // lighter: focused performance scan
+};
+
+// Resolve the timeout for a worker: explicit module override > KIND map >
+// caller's runOpts > undefined (runSubagent applies its own default).
+function timeoutForWorker(worker, runOpts) {
+  return (
+    worker.MAX_TIMEOUT_MS ??
+    WORKER_MAX_TIMEOUT_MS[worker.KIND] ??
+    runOpts?.timeoutMs
+  );
+}
+
+// Resolve a list of worker kinds to their modules. Throws on unknown kinds
+// so a typo in a custom panel surfaces immediately, not as a silent skip.
+function resolvePanel(kinds) {
+  const out = [];
+  for (const k of kinds) {
+    const mod = REGISTRY[k];
+    if (!mod) throw new Error(`unknown worker kind: ${k}. Known: ${Object.keys(REGISTRY).join(', ')}`);
+    out.push(mod);
+  }
+  return out;
+}
+
+// Runs one worker end-to-end. Returns a WorkerResult — always; subprocess /
+// parse / schema errors become a verdict='fail' result with an error tag, so
+// the caller can write the audit-trail row regardless.
+//
+// runSubagentFn is injected to avoid a circular dependency between
+// grader-workers/* and grader.js (grader.js requires this module).
+//
+// opts:
+//   model           the grader model for this worker (selected by caller)
+//   runOpts         passed to runSubagentFn (timeout, cwd, etc.)
+//
+// The subagent's raw stdout + run timing + any subprocess error are surfaced
+// onto the WorkerResult so aggregatePanel can decide pass/concerns/fail
+// without knowing about the runSubagent internals. ("shot" is v3 multi-shot
+// terminology; v4 calls these workers — but the subprocess plumbing is the
+// same shape underneath.)
+async function runWorker(worker, { task, valueSummary, diff, changedFiles, diffStats, model, runOpts, runSubagentFn, extractAssistantResultFn, deterministicFindings }) {
+  // deterministicFindings (route-rank pre-pass, #475) is forwarded to every
+  // worker's buildPrompt; only the Hacker reads it — the others ignore the
+  // extra field, so this is a no-op for narc/quality/efficiency.
+  const prompt = worker.buildPrompt({ task, valueSummary, diff, changedFiles, diffStats, deterministicFindings });
+
+  // One subagent attempt → verdict. Pulled out so #465 can re-run it once on a
+  // transient error without duplicating the spawn/parse/verdict plumbing.
+  // #467: per-worker timeout (Read-heavy workers get longer; see the map above).
+  const timeoutMs = timeoutForWorker(worker, runOpts);
+  async function attempt() {
+    let raw = null;
+    let runMs = null;
+    let costUsd = null;
+    let subprocessError = null;
+    const t0 = Date.now();
+    try {
+      const { stdout, run_ms, cost_usd } = await runSubagentFn({ prompt, opts: { ...runOpts, model, timeoutMs } });
+      runMs = run_ms;
+      // #486 (ADR 0028 path 1): runSubagent attaches the `claude -p` envelope's
+      // total_cost_usd. Carry it out so aggregatePanel can sum the panel's own
+      // API spend into panel_cost_usd → cost_log (source=grader).
+      costUsd = cost_usd ?? null;
+      raw = extractAssistantResultFn ? extractAssistantResultFn(stdout) : stdout;
+    } catch (err) {
+      runMs = err.run_ms ?? (Date.now() - t0);
+      subprocessError = err.code || 'UNKNOWN';
+    }
+    const parsed = subprocessError
+      ? null
+      : (typeof raw === 'string' ? worker.extractJson(raw) : raw);
+    const verdict = worker.computeVerdict(parsed, {
+      model,
+      run_ms: runMs,
+      subprocess_error: subprocessError,
+    });
+    return { verdict, runMs, costUsd };
+  }
+
+  let { verdict, runMs, costUsd } = await attempt();
+  // #465: retry ONCE on a transient error (the freshest attempt wins, even if it
+  // also errored — one retry only). A real verdict or a SUBAGENT_TIMEOUT is
+  // never retried. NB (#486): the freshest attempt's cost wins; a transient
+  // first attempt's spend is not added (slight, rare undercount).
+  let retried = false;
+  if (TRANSIENT_WORKER_ERRORS.has(verdict.error)) {
+    retried = true;
+    ({ verdict, runMs, costUsd } = await attempt());
+  }
+
+  return {
+    kind: worker.KIND,
+    name: worker.NAME,
+    specialty: worker.SPECIALTY,
+    verdict: verdict.verdict,
+    scores: verdict.scores || {},
+    issues: verdict.issues || [],
+    notes_md: verdict.notes_md || '',
+    confidence: verdict.confidence ?? null,
+    model,
+    run_ms: runMs,
+    cost_usd: costUsd, // #486: this worker's own subprocess API spend (USD)
+    retried,
+    error: verdict.error ?? null,
+    // Narc-specific (carried opaquely; aggregatePanel doesn't need to know):
+    ...(verdict.ac_checklist ? { ac_checklist: verdict.ac_checklist } : {}),
+  };
+}
+
+module.exports = {
+  REGISTRY,
+  DEFAULT_PANEL,
+  resolvePanel,
+  runWorker,
+  timeoutForWorker, // public surface; WORKER_MAX_TIMEOUT_MS stays module-internal
+  TRANSIENT_WORKER_ERRORS,
+  // re-export per-worker modules for direct access by tests
+  narc,
+  quality,
+  hacker,
+  efficiency,
+};

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

@@ -0,0 +1,207 @@
+// MAS Phase 2.0 (#410) — Narc worker.
+//
+// Specialty: semantic completion. Walks the task description's acceptance
+// criteria line by line, verifies each in the diff or (via Read) the post-
+// merge file state, and flags any AC that isn't satisfied. Reports a
+// `functional_fidelity` score (0-10) + a per-AC checklist.
+//
+// Replaces the ff axis of the v3 generalist grader. cq + economy are
+// handled by the Quality worker (until Phase 2.1+ specializes them).
+
+// THRESHOLD + LOW_CONF come from the shared rubric module (task 1090, C6) — a
+// bump to grader-rubric.json drives every per-worker verdict without code edits.
+const { THRESHOLD, LOW_CONF } = require('./rubric');
+
+// SR-15 / G1 (#995): wrap all builder-controlled inputs in a scrubbed, fenced
+// block the model is told to treat as DATA, never instructions. The shared
+// scaffold (worker-prompt) owns fenceBlock/scrubUntrusted/NOFOLLOW_PREAMBLE.
+const { buildWorkerPrompt, LLM_PROJECT } = require('./worker-prompt');
+const { failResult, parseCommon, finalizeVerdict } = require('./worker-verdict');
+
+const KIND = 'narc';
+const NAME = 'Narc';
+const SPECIALTY = 'semantic completion (description vs diff, line-level)';
+
+const PROMPT_HEADER = `You are the **Narc** — a specialist adversarial subagent for the ${LLM_PROJECT} project. You exist to catch the single most common form of shipped-but-broken work: the task whose acceptance criteria were not actually satisfied by the diff.
+
+Your ONLY job is semantic completion. You do NOT score code quality, security, or economy — other specialists handle those. Your verdict is about whether the description was implemented.
+
+**The default verdict is FAIL.** You PASS only after walking the description's acceptance criteria and finding affirmative evidence that EACH ONE is satisfied or explicitly out-of-scope per the description's own words.
+
+## Read budget (CRITICAL)
+
+**You have a hard budget of 5 Read calls per grade.** This is a calibration constraint — you previously deterministically timed out by Read-verifying every AC. The fix is to be selective.
+
+**Prefer the diff over Read.** Most ACs are visible in the diff: a new function, a comment update, an ADR section, a test file added, a constant changed. If the diff text shows what the AC claims, that's evidence — you do NOT need to Read the file. Mark it \`diff-confirmed\`.
+
+**Only spend a Read on ACs that need it.** Read is for: verifying that a deletion is unreferenced elsewhere, that a rename's call sites all updated, that behavior promised in the description (but not visible in the hunk) is actually present in the post-merge file. If an AC is plainly visible in the diff, do NOT Read.
+
+**If you exhaust the budget,** mark remaining ACs that would have needed a Read with status \`unverified-budget\` rather than chasing each one. The verdict logic treats \`unverified-budget\` neutrally — it doesn't drag your score down unless a majority of ACs land in that bucket.
+
+## How you work
+
+1. Read the task description (provided below). Find every acceptance criterion. ACs typically live under "Acceptance:" or "Acceptance criteria:" headers but may be stated as bullet points anywhere in the description.
+
+2. For each AC, build a checklist entry. Status is one of:
+   - **diff-confirmed** — the AC is plainly visible in the diff text below. You quote the diff line. No Read needed.
+   - **satisfied** — you used a Read call to verify the AC in the post-merge file state. You name the file:line.
+   - **partial** — the AC is partly implemented but a named gap remains. You describe the gap.
+   - **missing** — the AC is not implemented at all. You describe what's missing.
+   - **out-of-scope** — the description itself explicitly excludes this. Quote where it says so.
+   - **unverified-budget** — would have needed a Read but the budget is exhausted. The diff is ambiguous on this AC; you couldn't reach the file. (Use sparingly — this is a confession, not an escape hatch.)
+
+3. Score functional_fidelity (0-10) based on the checklist. \`diff-confirmed\` counts the same as \`satisfied\` for scoring. \`unverified-budget\` is neutral (doesn't push the score up or down by itself) unless it dominates:
+   - 10 = every AC is satisfied / diff-confirmed / out-of-scope; no gaps anywhere.
+   - 8 = every AC satisfied or diff-confirmed; minor polish items remain.
+   - 6 = mostly there with ONE named partial OR a few unverified-budget items mixed with satisfied. (Threshold for passing the gate.)
+   - 4 = multiple partials OR one missing AC OR most ACs are unverified-budget.
+   - 2 = mostly missing; the diff implements a different thing.
+   - 0 = the diff does not implement the described work at all.
+
+4. For each **partial** or **missing** AC, write an issue with severity (\`blocker\` for missing, \`major\` for partial) — file is the file the AC should have touched, summary is one line naming the gap.
+
+5. Confidence (0-1): how sure are you of the score? If the description is too vague to grade against, or you couldn't reach key files within budget — set confidence LOW (< 0.4). The downstream system treats low confidence as fall-through.
+
+## Sanity checks
+
+- A PASS verdict with no \`ac_checklist\` entries is invalid — you must enumerate the ACs you verified.
+- A FAIL verdict with no \`issues\` entries is invalid — name at least one missing AC.
+- A score of 6+ requires no missing ACs and at most one partial.
+- "Acceptance: tests pass" is NOT a valid AC verification on your part — you can't run tests. If the diff adds a test for the named behavior, that's \`diff-confirmed\`. If the test is in a file the diff doesn't fully show, that's worth ONE Read.
+- If you find yourself wanting to Read every file mentioned by every AC, stop. Re-check whether the diff already shows it. The diff text is your primary evidence.
+
+## Return ONLY JSON
+
+No prose before or after, no markdown fences:
+
+\`\`\`
+{
+  "functional_fidelity": <number 0-10>,
+  "confidence": <number 0-1>,
+  "reads_used": <integer 0-5>,
+  "ac_checklist": [
+    { "ac": "<string — the AC as written in the description>", "status": "diff-confirmed"|"satisfied"|"partial"|"missing"|"out-of-scope"|"unverified-budget", "evidence": "<diff line OR file:line OR quoted text>" }
+  ],
+  "issues": [
+    { "severity": "blocker"|"major"|"minor"|"nit", "file": "<path>", "summary": "<one line>" }
+  ],
+  "notes_md": "<short markdown — what you verified, what gaps you found, what you couldn't reach within budget>"
+}
+\`\`\`
+
+You have a Read tool with a hard budget of 5 calls. Do not run tests, do not edit files, do not call the network.`;
+
+function buildPrompt({ task, valueSummary, diff, changedFiles }) {
+  const t = task || {};
+  // Narc's description fallback is uniquely "(no description — set confidence
+  // LOW)" (the others use "(no description)"); the shared scaffold defaults to
+  // "(no description)", so pre-resolve the fallback here and hand it through.
+  // Truthy descriptions pass untouched, so the scaffold's own `|| ... .trim()`
+  // stays byte-identical to the inlined version.
+  return buildWorkerPrompt({
+    header: PROMPT_HEADER,
+    task: { ...t, description: t.description || '(no description — set confidence LOW)' },
+    valueSummary,
+    diff,
+    changedFiles,
+    taskHeader: '## Task',
+    descLabel: '**Description (your source of truth for the ACs):**',
+    emptyFilesText: '(no files changed — this is suspicious; mark every AC as missing)',
+    readFilesHint: 'You can Read any of these files to see their post-merge state.',
+    finalInstruction: 'Now walk the ACs. Default-fail unless every one is satisfied or explicitly out-of-scope. Output ONLY the JSON object.',
+  });
+}
+
+// #79 (#493): delegate to the shared robust extractor so the v4 panel path
+// gets the same parse-resilience (whole-string -> fenced -> balanced-brace) as
+// grader.js, instead of the brittle first-{-to-last-} copy that flaked.
+const { extractJson } = require('./extract-json');
+
+// Narc's per-worker verdict. Inputs:
+//   parsed: the JSON the subagent emitted (or null on parse failure)
+//   meta:   { run_ms, model, etc. } — pass-through from runOneShot
+// Output: a partial WorkerResult; runWorker fills in kind/name/etc.
+function computeVerdict(parsed, meta = {}) {
+  // Errors short-circuit to 'fail' so the panel can decide what to do.
+  if (meta.subprocess_error) {
+    return failResult({ notesMd: `Narc: subagent error (${meta.subprocess_error}).`, error: meta.subprocess_error });
+  }
+  if (!parsed || typeof parsed !== 'object') {
+    return failResult({ notesMd: 'Narc: could not parse subagent output as JSON.', error: 'parse_error' });
+  }
+
+  const ff = Number(parsed.functional_fidelity);
+  const { conf, issues, notesFromSubagent } = parseCommon(parsed);
+  const checklist = Array.isArray(parsed.ac_checklist) ? parsed.ac_checklist : [];
+
+  // Out-of-range or non-numeric ff → schema error → fail.
+  if (!Number.isFinite(ff) || ff < 0 || ff > 10) {
+    return failResult({ issues, notesMd: `Narc: functional_fidelity was non-numeric or out of range (got ${parsed.functional_fidelity}).`, error: 'schema_error' });
+  }
+
+  const ffR = Math.round(ff * 10) / 10;
+  const blockerCount = issues.filter((i) => i.severity === 'blocker').length;
+  const missingCount = checklist.filter((c) => c && c.status === 'missing').length;
+  const partialCount = checklist.filter((c) => c && c.status === 'partial').length;
+  // diff-confirmed counts as satisfied for scoring (Phase 2.0.5 #413).
+  const satisfiedCount = checklist.filter(
+    (c) => c && (c.status === 'satisfied' || c.status === 'diff-confirmed')
+  ).length;
+  // unverified-budget is neutral by itself; concerns trip only if it dominates
+  // the checklist (more than half of the verifiable ACs landed there).
+  const unverifiedBudgetCount = checklist.filter(
+    (c) => c && c.status === 'unverified-budget'
+  ).length;
+  const totalChecklist = checklist.length;
+  // Verifiable ACs = total minus out-of-scope (which is a positive verdict
+  // type, not a "couldn't verify" state).
+  const verifiableCount = checklist.filter(
+    (c) => c && c.status !== 'out-of-scope'
+  ).length;
+  const unverifiedDominates =
+    verifiableCount > 0 && unverifiedBudgetCount * 2 > verifiableCount;
+  const lowConfidence = conf != null && conf < LOW_CONF;
+
+  let verdict;
+  let notesPrefix;
+  if (blockerCount > 0 || missingCount > 0 || ffR < THRESHOLD) {
+    verdict = 'fail';
+    notesPrefix = `Narc — FAIL (ff=${ffR}/10`
+      + (missingCount > 0 ? `, ${missingCount} missing AC${missingCount === 1 ? '' : 's'}` : '')
+      + (blockerCount > 0 ? `, ${blockerCount} blocker issue${blockerCount === 1 ? '' : 's'}` : '')
+      + `)`;
+  } else if (lowConfidence || partialCount > 0 || unverifiedDominates) {
+    verdict = 'concerns';
+    notesPrefix = `Narc — CONCERNS (ff=${ffR}/10`
+      + (lowConfidence ? `, low confidence ${conf}` : '')
+      + (partialCount > 0 ? `, ${partialCount} partial AC${partialCount === 1 ? '' : 's'}` : '')
+      + (unverifiedDominates ? `, ${unverifiedBudgetCount}/${verifiableCount} ACs unverified (budget)` : '')
+      + `)`;
+  } else {
+    verdict = 'pass';
+    const verifiedStr = satisfiedCount === totalChecklist
+      ? `${totalChecklist} AC${totalChecklist === 1 ? '' : 's'} verified`
+      : `${satisfiedCount} verified / ${unverifiedBudgetCount} unverified-budget / ${totalChecklist} total`;
+    notesPrefix = `Narc — PASS (ff=${ffR}/10, ${verifiedStr}, conf=${conf ?? '?'})`;
+  }
+
+  return finalizeVerdict({
+    verdict,
+    scores: { functional_fidelity: ffR },
+    issues,
+    extra: { ac_checklist: checklist },
+    notesPrefix,
+    notesFromSubagent,
+    confidence: conf,
+  });
+}
+
+module.exports = {
+  KIND,
+  NAME,
+  SPECIALTY,
+  PROMPT_HEADER,
+  buildPrompt,
+  extractJson,
+  computeVerdict,
+};