@bongos/core 1.19.384 → 1.19.386

package/.bongos-core.json

@@ -2,11 +2,11 @@
   "artifact": "bongos-core",
   "manifest_schema": 1,
   "generator": "scripts/gds/package-core.js",
-  "core_version": "1.19.384",
-  "core_contract": "1.19.384",
-  "source_commit": "c17ffedef449a2cb392b9bedc87fa31f1746625a",
+  "core_version": "1.19.386",
+  "core_contract": "1.19.386",
+  "source_commit": "c4899bbdaafe758d4521d6cb7944ad0117886573",
   "source_ref": "HEAD",
-  "built_at": "2026-08-27T21:02:17.519Z",
+  "built_at": "2026-08-27T21:58:01.005Z",
   "redaction": {
     "model": "docs-redacted+functional-verbatim",
     "docs_redacted": 338,
@@ -17,7 +17,7 @@
     "gate": "passed"
   },
   "file_count": 1963,
-  "tree_sha256": "d6620f625c1c0969033c8326d7e5d9490f054072e6a6d0eecef66552c2025290",
+  "tree_sha256": "856370a346d104a96b56e2fe9a3fefd50a50298a18e82c9afa13ef04387f6b7a",
   "files": [
     {
       "path": ".claude/skills/blocker-review/SKILL.md",
@@ -3537,7 +3537,7 @@
     {
       "path": "modules/grading/grader-workers/index.js",
       "mode": "0000644",
-      "sha256": "8ec5e91341ec5247ee643c6ce75fb5ec21a62b3bba176fdde060cdb352edb808"
+      "sha256": "186ebc1d6456f3d9d0435766744fd767005b667fc4f6020bb9041f6b66388c4b"
     },
     {
       "path": "modules/grading/grader-workers/narc.js",
@@ -3567,7 +3567,7 @@
     {
       "path": "modules/grading/grader.js",
       "mode": "0000644",
-      "sha256": "bb66bece4bf5d1364be931b39d7b1e179615b59613d74e491ff48b399291ff24"
+      "sha256": "53001adcb058742f39bdb475fca023809c239f50bf9dddc61ccef966d5d01d6a"
     },
     {
       "path": "modules/grading/module.json",
@@ -5117,12 +5117,12 @@
     {
       "path": "package-lock.json",
       "mode": "0000644",
-      "sha256": "d1bb9eb4376b39eb26a2fb46d91a70556c332521be0f193633d11807248f48ca"
+      "sha256": "34407c6061bf61f8ec416b91f30da5ae1140c1e584e6721af64fbadadb60c9b0"
     },
     {
       "path": "package.json",
       "mode": "0000644",
-      "sha256": "cbb22bb9c93706c85329e51d1a67becc24d477f6c63baadadb2c6b10aa1cc59a"
+      "sha256": "e49313249eef5acc6d3a2926aeb5725f0773d8d4300393a8ed57a3016a25a995"
     },
     {
       "path": "public-docs/index.html",
@@ -5782,7 +5782,7 @@
     {
       "path": "scripts/gds/docs-entropy.js",
       "mode": "0000644",
-      "sha256": "1a7cbe47158e4de63c1b788d6bb4f682584723a45c1824ab2ae3fbf92a54fbce"
+      "sha256": "e052ddf4d44c0d67512cb14e150cd309a9ab09414c557db8319a57fd8f0d6961"
     },
     {
       "path": "scripts/gds/doctor.js",
@@ -6472,7 +6472,7 @@
     {
       "path": "scripts/gds/ship-grade-steps.js",
       "mode": "0000644",
-      "sha256": "52dc5ae1aca08033d2d217694273d8fed1597c0329491118ffa48ccdadc0a3ca"
+      "sha256": "e68f4c2848cb59878cd0b96b48fdd075db4a035354d51afef52aa6225f7895e5"
     },
     {
       "path": "scripts/gds/ship-grade.js",
@@ -7032,7 +7032,7 @@
     {
       "path": "src/module-api.js",
       "mode": "0000644",
-      "sha256": "62c5f68383474bfeb692ea38e926c689615320d644d8d83fe7c35b3dd51e23bb"
+      "sha256": "28a5f25668bc0297f421e200dbb658a5365db71874af4f8fd29c37016b4dcd29"
     },
     {
       "path": "src/module-loader/catalog.js",
@@ -7862,7 +7862,7 @@
     {
       "path": "tests/docs_entropy.mjs",
       "mode": "0000644",
-      "sha256": "4d64164d45d6b81d706074b8394da4f3d0f7f8c5263a37a287a163d6a746a96b"
+      "sha256": "c3ef388bb7baacd4da4319fed82ceb5687e0d444cacce2ee84f9061dccbd1018"
     },
     {
       "path": "tests/docs_openapi_route.mjs",
@@ -8302,7 +8302,7 @@
     {
       "path": "tests/grade_unavailable_display.mjs",
       "mode": "0000644",
-      "sha256": "82746689da273a8bd9d53d80204b15147d87574d2331c3a70d736d95a6126a09"
+      "sha256": "08e08714d025fe7c0f1177fbfa6724241ff519cd34848f953d5bc7cce6c142fa"
     },
     {
       "path": "tests/grader.mjs",
@@ -8322,7 +8322,7 @@
     {
       "path": "tests/grader_panel.mjs",
       "mode": "0000644",
-      "sha256": "2e62f5eb5896691df78e1c63f495d1cf7bea23dd1dfb8f2bd764e23e87982616"
+      "sha256": "32dc0e219ed6aa7430c9ba9523faddb2ddc9602d939731788c660d9d79751d22"
     },
     {
       "path": "tests/grader_prompt_fencing.mjs",

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

@@ -70,6 +70,35 @@ const WORKER_MAX_TIMEOUT_MS = {
   efficiency: 360_000, // Read-heavy on a large diff: traces perf across every changed file
 };
 
+// task 1003313: the diagnostic a dark panel used to throw away.
+//
+// runSubagent attaches exit_code + stdout + stderr to every subprocess error,
+// but the catch below kept only err.code — so a TOTAL outage stored four
+// identical `SUBAGENT_NONZERO_EXIT` rows and nothing else, and two builders sat
+// dark for days with a 0/10 card that could not name its own cause. At least two
+// known environmental faults produce that exact signature (a logged-out `claude`
+// CLI — preflight.js claudeAuthFinding; the Windows WindowsApps alias stub —
+// learning 42) and the stored grade could not tell them apart.
+//
+// The tail is REDACTED and BOUNDED because it lands in a grade row that the hall
+// renders: CLI stderr can carry an auth header or a key echoed back in an error.
+const STDERR_TAIL_MAX = 400;
+// eslint-disable-next-line no-control-regex -- stripping ANSI SGR from CLI stderr
+const ANSI_RE = /\x1B\[[0-9;]*[A-Za-z]/g;
+const SECRET_RES = [
+  /sk-ant-[A-Za-z0-9_-]+/g,
+  /(?:ghp|gho|ghu|ghs|ghr)_[A-Za-z0-9]{20,}/g,
+  /github_pat_[A-Za-z0-9_]{20,}/g,
+  /\b[Bb]earer\s+[A-Za-z0-9._~+/-]{12,}=*/g,
+];
+function redactStderrTail(raw) {
+  let s = String(raw || '').replace(ANSI_RE, '').trim();
+  if (!s) return null;
+  for (const re of SECRET_RES) s = s.replace(re, '[redacted]');
+  s = s.slice(-STDERR_TAIL_MAX);
+  return s || null;
+}
+
 // Resolve the timeout for a worker: explicit module override > KIND map >
 // caller's runOpts > undefined (runSubagent applies its own default).
 function timeoutForWorker(worker, runOpts) {
@@ -127,6 +156,9 @@ async function runWorker(worker, { task, valueSummary, diff, changedFiles, diffS
     let runMs = null;
     let costUsd = null;
     let subprocessError = null;
+    // task 1003313: the WHY behind subprocessError. Null on a clean run.
+    let exitCode = null;
+    let stderrTail = null;
     const t0 = Date.now();
     try {
       const { stdout, run_ms, cost_usd } = await runSubagentFn({ prompt, opts: { ...runOpts, model, timeoutMs } });
@@ -139,6 +171,11 @@ async function runWorker(worker, { task, valueSummary, diff, changedFiles, diffS
     } catch (err) {
       runMs = err.run_ms ?? (Date.now() - t0);
       subprocessError = err.code || 'UNKNOWN';
+      exitCode = Number.isInteger(err.exit_code) ? err.exit_code : null;
+      // A CLI that dies before writing JSON often says why on stdout, not stderr
+      // (`claude` prints its "not logged in" line there) — fall back so the tail
+      // is never empty when the subprocess did explain itself.
+      stderrTail = redactStderrTail(err.stderr) ?? redactStderrTail(err.stdout);
     }
     const parsed = subprocessError
       ? null
@@ -148,10 +185,10 @@ async function runWorker(worker, { task, valueSummary, diff, changedFiles, diffS
       run_ms: runMs,
       subprocess_error: subprocessError,
     });
-    return { verdict, runMs, costUsd };
+    return { verdict, runMs, costUsd, exitCode, stderrTail };
   }
 
-  let { verdict, runMs, costUsd } = await attempt();
+  let { verdict, runMs, costUsd, exitCode, stderrTail } = await attempt();
   // #465: retry ONCE on a transient error (the freshest attempt wins, even if it
   // also errored — one retry only). A real verdict or a SUBAGENT_TIMEOUT is
   // never retried. NB (#486): the freshest attempt's cost wins; a transient
@@ -159,7 +196,7 @@ async function runWorker(worker, { task, valueSummary, diff, changedFiles, diffS
   let retried = false;
   if (TRANSIENT_WORKER_ERRORS.has(verdict.error)) {
     retried = true;
-    ({ verdict, runMs, costUsd } = await attempt());
+    ({ verdict, runMs, costUsd, exitCode, stderrTail } = await attempt());
   }
 
   return {
@@ -176,6 +213,10 @@ async function runWorker(worker, { task, valueSummary, diff, changedFiles, diffS
     cost_usd: costUsd, // #486: this worker's own subprocess API spend (USD)
     retried,
     error: verdict.error ?? null,
+    // task 1003313: on an errored worker, WHY. Omitted entirely on a clean run so
+    // a healthy grade row keeps its existing shape.
+    ...(verdict.error && exitCode != null ? { exit_code: exitCode } : {}),
+    ...(verdict.error && stderrTail ? { stderr_tail: stderrTail } : {}),
     // Narc-specific (carried opaquely; aggregatePanel doesn't need to know):
     ...(verdict.ac_checklist ? { ac_checklist: verdict.ac_checklist } : {}),
   };
@@ -188,6 +229,8 @@ module.exports = {
   runWorker,
   timeoutForWorker, // public surface; WORKER_MAX_TIMEOUT_MS stays module-internal
   TRANSIENT_WORKER_ERRORS,
+  redactStderrTail, // task 1003313: exported so the redaction contract is pinned
+  STDERR_TAIL_MAX,
   // re-export per-worker modules for direct access by tests
   narc,
   quality,

package/modules/grading/grader.js

@@ -88,6 +88,27 @@ const { buildPrompt, extractJson } = require('./grader-prompt.js');
 const { aggregateShots, changeMagnitude, hasPanelEvidence, isSubstantiveIssue, serverSideGuards, validateAndScore } = require('./grader-score.js');
 const { buildContextBundle, diffAddedLinesByFile, extractAssistantResult, extractCostUsd, runOneShot, runSubagent, runSubagentCached } = require('./grader-subagent.js');
 
+// task 1003313: render the WHY of a total outage into the verdict line.
+//
+// Exists because "GRADER UNAVAILABLE — all 4 workers failed to run" is not a
+// diagnosis: a logged-out `claude` CLI, a Windows app-execution-alias stub, and a
+// genuine API outage all produce it, and the builder sees no way to tell which.
+// runWorker now carries exit_code + a redacted stderr_tail off each dead worker;
+// this puts the shared exit code and the first distinct CLI error line into the
+// text the builder actually reads. Silent when the workers carry no detail
+// (a grade from a server predating the propagation).
+const OUTAGE_TAIL_MAX = 300;
+function describeOutage(gating) {
+  const dead = gating.filter((w) => w.error);
+  const codes = [...new Set(dead.map((w) => w.exit_code).filter((c) => c != null))];
+  const tails = [...new Set(dead.map((w) => w.stderr_tail).filter(Boolean))];
+  if (!codes.length && !tails.length) return '';
+  const parts = [];
+  if (codes.length) parts.push(`exit ${codes.join('/')}`);
+  if (tails.length) parts.push(`subprocess said: ${tails[0].slice(-OUTAGE_TAIL_MAX)}`);
+  return ` Diagnostic — ${parts.join('; ')}`;
+}
+
 function aggregatePanel(workerResults, meta = {}) {
   const N = workerResults.length;
 
@@ -232,6 +253,10 @@ function aggregatePanel(workerResults, meta = {}) {
     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.` +
+      // task 1003313: name the cause. Without this the card said only "failed to
+      // run" four times over, and two builders sat dark for days because nothing
+      // stored — or showed — the exit code and the CLI's own error line.
+      describeOutage(gating) +
       advisoryNote;
     panelOutcome = 'unavailable';
     forwardedConfidence = FALLTHROUGH_CONFIDENCE;

package/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "@bongos/core",
-  "version": "1.19.384",
+  "version": "1.19.386",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@bongos/core",
-      "version": "1.19.384",
+      "version": "1.19.386",
       "license": "AGPL-3.0-or-later",
       "dependencies": {
         "express": "^4.21.2",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bongos/core",
-  "version": "1.19.384",
+  "version": "1.19.386",
   "description": "Cloud Bongos — the AI-first build platform core (GDS + platform surfaces + module system), installed as a versioned dependency (ADR 0108).",
   "license": "AGPL-3.0-or-later",
   "main": "src/platform-server.js",

package/scripts/gds/docs-entropy.js

@@ -89,7 +89,17 @@ function parseFile(absPath) {
     return { headings: [], links: [], paragraphs: [] };
   }
 
-  const lines = raw.split('\n');
+  // Split on CRLF **or** LF, and drop a leading BOM (task 1003314). A Windows
+  // checkout gets CRLF from git, and splitting on a bare newline then leaves a
+  // trailing carriage return on every line — which the heading regex below
+  // cannot match, because `.` excludes line terminators and `$` is not in
+  // multiline mode. The file parsed as having ZERO headings, so every
+  // [text](file.md#anchor) pointing into it was reported as a broken anchor:
+  // doc_broken_anchors read 21 on Windows and 6 in CI, and the quality ratchet
+  // a Windows builder ran was pure noise. Same failure family as task 1002526's
+  // `git ls-files` quoting bug, one layer in — a gate that reports confidently
+  // and wrongly on one platform.
+  const lines = raw.replace(/^\uFEFF/, '').split(/\r?\n/);
   const headings = [];
   const links = [];
   const paragraphs = [];

package/scripts/gds/ship-grade-steps.js

@@ -14,6 +14,10 @@ const os = require('node:os');
 const { cliClient, rewardPolicy } = require('./cli-lib');
 const { gitOk } = require('./ship-git.js');
 const { resolveInstanceBase } = require('./ship-deploy-target.js');
+// task 1003313: the shared onboarding/doctor preflight — reused (not duplicated)
+// so the grader outage explains itself with the same `claude CLI` verdict doctor
+// gives, and the two can never drift.
+const { preflightChecks } = require('./preflight.js');
 const { computeRawDiffHash, reconstructPanelIssues, runSubagentGrader, shouldReuseGrade } = require('./ship-grade.js');
 
 // ---------- Shared grade-step helpers (used by shipMain AND regradeMain) ----------
@@ -223,7 +227,33 @@ async function gradeAndRecord({ taskId, task, summary, baseline, committedFiles,
 // issues + next-step hints). Pure + exported so the #943 grader-unavailable vs
 // FAIL branch is unit-tested without capturing stdout. printGradeOutcome just
 // prints what this returns.
-function formatGradeOutcome(g, taskId) {
+// task 1003313: the per-worker diagnostic lines for a total outage, plus the
+// local `claude` CLI verdict. Pure over its inputs (cliFinding is INJECTED, never
+// spawned here) so formatGradeOutcome stays unit-testable without a subprocess.
+function formatOutageDiagnostic(g, cliFinding) {
+  const out = [];
+  const dead = (g.signals?.workers || []).filter((w) => w && w.error);
+  const detailed = dead.filter((w) => w.exit_code != null || w.stderr_tail);
+  if (detailed.length) {
+    out.push('');
+    out.push('What the grader subprocess actually did:');
+    for (const w of detailed) {
+      const code = w.exit_code != null ? `exit ${w.exit_code}` : w.error;
+      out.push(`  ${String(w.kind || '?').padEnd(11)} ${code}${w.stderr_tail ? ` — ${w.stderr_tail.split('\n')[0]}` : ''}`);
+    }
+  }
+  if (cliFinding && cliFinding.level !== 'ok') {
+    out.push('');
+    out.push(`Local \`claude\` CLI: ${cliFinding.detail}`);
+    if (cliFinding.fix) out.push(`  Fix: ${cliFinding.fix}`);
+  }
+  return out;
+}
+
+// cliFinding: the preflight `claude CLI` row, injected by printGradeOutcome so a
+// dark panel can say "your CLI is logged out" instead of leaving the builder to
+// guess. Report-only — it never changes the outcome (ADR 0162: no new gates).
+function formatGradeOutcome(g, taskId, cliFinding = null) {
   const out = [];
   // #943: a TOTAL grader outage (every gating worker failed to spawn / the
   // grader was bypassed pre-spawn) is NOT a quality rejection — it's "the grader
@@ -236,6 +266,7 @@ function formatGradeOutcome(g, taskId) {
     out.push('');
     out.push(`Subagent grade: GRADER UNAVAILABLE${reason ? ` (${reason})` : ''}  ·  no quality signal produced — NOT a quality rejection`);
     if (g.notes_md) out.push(g.notes_md.split('\n').map((l) => '  ' + l).join('\n'));
+    out.push(...formatOutageDiagnostic(g, cliFinding));
     out.push('');
     out.push('The grader could not run (infra/outage/bypass) — there are no findings to fix. Task stays at completed.');
     out.push('When the grader is reachable again, re-grade:');
@@ -308,7 +339,17 @@ function formatGradeOutcome(g, taskId) {
 // last resort — see feedback_prefer_regrade_over_override). #943: a total grader
 // outage prints as "GRADER UNAVAILABLE", not a 0/10 FAIL — see formatGradeOutcome.
 function printGradeOutcome(g, taskId) {
-  console.log(formatGradeOutcome(g, taskId));
+  // task 1003313: on a TOTAL outage only, ask the existing preflight whether the
+  // local `claude` CLI is launchable and logged in — the two faults that produce
+  // this exact all-workers-dead signature. Report-only and outage-only, so the
+  // happy path pays nothing and no ship is newly gated (ADR 0162).
+  let cliFinding = null;
+  if (g?.signals?.panel_outcome === 'unavailable') {
+    try {
+      cliFinding = preflightChecks().find((r) => r.title === 'claude CLI') || null;
+    } catch (_) { /* best-effort: a broken probe must never mask the grade output */ }
+  }
+  console.log(formatGradeOutcome(g, taskId, cliFinding));
 }
 
 // Print the credits line + multiplier breakdown + idea bonus + unlocked

package/src/module-api.js

@@ -1208,8 +1208,12 @@ const { validateOrRespond, LIMITS, parseId, asyncHandler, corsPublicGet, parsePa
 //         landed since 1.19.382 with no explicit bump. run 33101389971. (task 1002620)
 //   1.19.384 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
 //         landed since 1.19.383 with no explicit bump. run 33116184189. (task 1002620)
+//   1.19.385 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+//         landed since 1.19.384 with no explicit bump. run 33118682829. (task 1002620)
+//   1.19.386 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+//         landed since 1.19.385 with no explicit bump. run 33120468176. (task 1002620)
 // ---------------------------------------------------------------------------
-const CORE_VERSION = '1.19.384'; // CI auto-patch carrier (ADR 0161); see changelog above
+const CORE_VERSION = '1.19.386'; // CI auto-patch carrier (ADR 0161); see changelog above
 
 // A namespaced logger so a module's log lines are attributable + consistent.
 // Usage: const log = api.logger('dev-box'); log.info('mounted');

package/tests/docs_entropy.mjs

@@ -12,12 +12,14 @@ import { test } from 'node:test';
 import { execFileSync } from 'node:child_process';
 import { createRequire } from 'node:module';
 import { fileURLToPath } from 'node:url';
+import fs from 'node:fs';
+import os from 'node:os';
 import path from 'node:path';
 
 const require = createRequire(import.meta.url);
 const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
 const SCANNER = path.join(ROOT, 'scripts', 'gds', 'docs-entropy.js');
-const { collectMarkdownFiles } = require(SCANNER); // require.main-guarded → no scan on import
+const { collectMarkdownFiles, parseFile } = require(SCANNER); // require.main-guarded → no scan on import
 
 test('collectMarkdownFiles passes the glob as an argv array, never a shell string', () => {
   let seen = null;
@@ -53,3 +55,86 @@ test('the real scan enumerates the repo (the regression: it reported on 0 files)
   assert.ok(Number.isFinite(result.stale_links));
   assert.ok(Number.isFinite(result.broken_anchors));
 });
+
+// --- CRLF: a Windows checkout must parse exactly like a Linux one (task 1003314) ---
+//
+// The bug: parseFile() split on a bare '\n', so on a Windows checkout (git hands
+// out CRLF) every line kept a trailing '\r'. The heading regex /^(#{1,6})\s+(.+)$/
+// cannot match that — '.' excludes line terminators and '$' is not in multiline
+// mode — so EVERY CRLF file parsed as having zero headings, and every
+// [text](file.md#anchor) pointing into one was reported broken. doc_broken_anchors
+// read 21 on Windows against a baseline of 6, which made the quality ratchet
+// unusable there: a builder could not tell a real regression from platform noise.
+// Same family as the `git ls-files` quoting bug above — a gate that reports
+// confidently and WRONGLY on one platform only.
+
+const DOC_LINES = [
+  '# Title one',
+  '',
+  'Some prose with a [link](other.md#deep-anchor) in it.',
+  '',
+  '## 12. Session Update Protocol',
+  '',
+  'More prose.',
+];
+
+// Write `text` to a temp .md and parse it — parseFile takes a path, not a string.
+function parseString(text) {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'docs-entropy-eol-'));
+  try {
+    const file = path.join(dir, 'sample.md');
+    fs.writeFileSync(file, text);
+    return parseFile(file);
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+}
+
+test('parseFile reads CRLF and LF identically — headings, slugs and links', () => {
+  const lf = parseString(DOC_LINES.join('\n'));
+  const crlf = parseString(DOC_LINES.join('\r\n'));
+
+  assert.equal(lf.headings.length, 2, 'fixture sanity: the LF form has two headings');
+  assert.deepEqual(
+    crlf.headings, lf.headings,
+    'a CRLF file must parse to the same headings as the LF one — before this fix it parsed to NONE',
+  );
+  assert.deepEqual(crlf.links.map((l) => l.href), lf.links.map((l) => l.href));
+});
+
+test('parseFile slugs a CRLF heading without a trailing carriage return', () => {
+  const slugs = parseString(DOC_LINES.join('\r\n')).headings.map((h) => h.slug);
+  assert.deepEqual(
+    slugs, ['title-one', '12-session-update-protocol'],
+    'the real anchor CLAUDE.md cites — a stray \\r in the slug is what made it report as "missing"',
+  );
+  assert.ok(!slugs.some((s) => s.includes('\r')), 'no slug carries a carriage return');
+});
+
+test('parseFile ignores a leading BOM, so a BOM file is not one heading short', () => {
+  // Same class, different byte: PowerShell writes UTF-8 WITH BOM by default
+  // (scripts/gds/CLAUDE.md warns about this for JSON bodies) and
+  // readFileSync('utf8') does not strip it — the BOM would sit before the first
+  // '#' and hide that heading.
+  const withBom = parseString('' + DOC_LINES.join('\r\n'));
+  assert.equal(withBom.headings.length, 2, 'the first heading survives a BOM');
+  assert.equal(withBom.headings[0].text, 'Title one');
+});
+
+test('the real scan on THIS checkout matches the CI baselines (the platform-parity proof)', () => {
+  // The point of the fix: the number a Windows builder sees is the number CI
+  // sees. Read the baseline rather than hardcoding it, so this stays honest as
+  // the ratchet legitimately tightens.
+  const stdout = execFileSync(process.execPath, [SCANNER, '--json'], {
+    cwd: ROOT, encoding: 'utf8', maxBuffer: 64 * 1024 * 1024,
+  });
+  const result = JSON.parse(stdout);
+  const baselines = JSON.parse(
+    fs.readFileSync(path.join(ROOT, 'config', 'fitness-baselines.json'), 'utf8'),
+  ).metrics;
+  assert.ok(
+    result.broken_anchors <= baselines.doc_broken_anchors,
+    `broken_anchors ${result.broken_anchors} exceeds the baseline ${baselines.doc_broken_anchors} — `
+    + 'on a CRLF checkout this read 21, because every heading in every CRLF file went unparsed',
+  );
+});

package/tests/grade_unavailable_display.mjs

@@ -35,6 +35,54 @@ test('grader-unavailable grade → "GRADER UNAVAILABLE", NOT a 0/10 FAIL or "fix
   assert.doesNotMatch(out, /blended .*\/10/, 'must NOT print a 0/10 quality score for a non-grade');
 });
 
+// ---------- task 1003313: the outage card says WHY ----------
+//
+// Before this, a total outage printed "GRADER UNAVAILABLE" and stopped — the
+// builder had no way to tell a logged-out CLI from a Windows alias stub from a
+// real API outage, and two builders stayed dark for days. The diagnostic and the
+// local `claude` CLI verdict are report-only: they never change the outcome.
+
+const OUTAGE = {
+  passed: false, score: 0, threshold: 6, notes_md: 'GRADER UNAVAILABLE — all 4/4 gating worker(s) failed to run',
+  rubric_scores: {}, issues: [],
+  signals: {
+    panel_outcome: 'unavailable',
+    workers: ['narc', 'quality', 'hacker', 'efficiency'].map((kind) => ({
+      kind, error: 'SUBAGENT_NONZERO_EXIT', exit_code: 1, stderr_tail: 'Invalid API key · Run /login',
+    })),
+  },
+};
+
+test('an outage card prints each dead worker with its exit code + CLI error (task 1003313)', () => {
+  const out = formatGradeOutcome(OUTAGE, 1003313);
+  assert.match(out, /GRADER UNAVAILABLE/);
+  assert.match(out, /What the grader subprocess actually did/);
+  assert.match(out, /narc\s+exit 1 — Invalid API key/, 'names the worker, its exit code, and what the CLI said');
+  assert.doesNotMatch(out, /Fix the issues above/, 'still not a quality rejection');
+});
+
+test('an outage card relays the injected claude-CLI preflight finding + its fix (task 1003313)', () => {
+  const out = formatGradeOutcome(OUTAGE, 1003313, {
+    level: 'warn', title: 'claude CLI',
+    detail: 'launches (2.1.0) but is not logged in',
+    fix: 'Run `claude login`',
+  });
+  assert.match(out, /Local `claude` CLI: launches \(2\.1\.0\) but is not logged in/);
+  assert.match(out, /Fix: Run `claude login`/);
+});
+
+test('a HEALTHY claude-CLI finding adds no noise to the outage card (task 1003313)', () => {
+  const out = formatGradeOutcome(OUTAGE, 1003313, { level: 'ok', title: 'claude CLI', detail: 'logged in' });
+  assert.doesNotMatch(out, /Local `claude` CLI/, 'an ok finding is not worth a line');
+});
+
+test('an outage from a pre-propagation server prints no empty diagnostic block (task 1003313)', () => {
+  const g = { ...OUTAGE, signals: { panel_outcome: 'unavailable', workers: [{ kind: 'narc', error: 'SUBAGENT_NONZERO_EXIT' }] } };
+  const out = formatGradeOutcome(g, 1003313);
+  assert.match(out, /GRADER UNAVAILABLE/);
+  assert.doesNotMatch(out, /What the grader subprocess actually did/);
+});
+
 test('a real FAIL still prints the FAIL block + fix-the-issues guidance (#943 regression guard)', () => {
   const g = {
     passed: false, score: 4, threshold: 6,

package/tests/grader_panel.mjs

@@ -246,6 +246,90 @@ await atest('graderUnavailableResult: server-compat shape (null axes, fallthroug
   assert.equal(r.passed, false);
 });
 
+// ---------- task 1003313: a dark panel names its own cause ----------
+//
+// The regression these pin: runWorker used to keep only err.code and throw away
+// err.exit_code / err.stderr, so a total outage stored four identical
+// SUBAGENT_NONZERO_EXIT rows and two builders sat dark for days with a 0/10 card
+// that could not say whether the CLI was logged out, aliased, or the API down.
+
+const workersMod = require('../modules/grading/grader-workers/index.js');
+const { runWorker, redactStderrTail, STDERR_TAIL_MAX } = workersMod;
+
+// A worker module stub: buildPrompt/extractJson/computeVerdict, no spawning.
+const STUB_WORKER = {
+  KIND: 'quality', NAME: 'Quality', SPECIALTY: 'stub',
+  buildPrompt: () => 'prompt',
+  extractJson: (s) => JSON.parse(s),
+  computeVerdict: (parsed, meta) => (meta.subprocess_error
+    ? { verdict: 'fail', scores: {}, issues: [], notes_md: '', confidence: 0, error: meta.subprocess_error }
+    : { verdict: 'pass', scores: { code_quality: 9 }, issues: [], notes_md: '', confidence: 0.9, error: null }),
+};
+
+// The exact error runSubagent throws on a nonzero exit.
+const nonzeroExit = ({ exitCode = 1, stderr = '', stdout = '' } = {}) =>
+  Object.assign(new Error(`subagent exited with code ${exitCode}`), {
+    code: 'SUBAGENT_NONZERO_EXIT', exit_code: exitCode, run_ms: 120, stdout, stderr,
+  });
+
+await atest('runWorker: a dead subprocess carries exit_code + stderr_tail onto the worker row (task 1003313)', async () => {
+  const r = await runWorker(STUB_WORKER, {
+    task: {}, diff: '', changedFiles: [], diffStats: {}, model: 'm', runOpts: {},
+    runSubagentFn: async () => { throw nonzeroExit({ exitCode: 1, stderr: 'Invalid API key · Run /login' }); },
+  });
+  assert.equal(r.error, 'SUBAGENT_NONZERO_EXIT');
+  assert.equal(r.exit_code, 1, 'the exit code must survive the catch');
+  assert.match(r.stderr_tail, /Invalid API key/, "the CLI's own error line must survive the catch");
+  assert.equal(r.retried, true, 'a transient error is still retried once (#465)');
+});
+
+await atest('runWorker: a clean run adds neither exit_code nor stderr_tail (task 1003313)', async () => {
+  const r = await runWorker(STUB_WORKER, {
+    task: {}, diff: '', changedFiles: [], diffStats: {}, model: 'm', runOpts: {},
+    runSubagentFn: async () => ({ stdout: '{"code_quality":9}', run_ms: 10, cost_usd: 0.5 }),
+  });
+  assert.equal(r.verdict, 'pass');
+  assert.equal('exit_code' in r, false, 'a healthy grade row keeps its existing shape');
+  assert.equal('stderr_tail' in r, false);
+});
+
+await atest('runWorker: stdout is the fallback when the CLI explained itself there (task 1003313)', async () => {
+  const r = await runWorker(STUB_WORKER, {
+    task: {}, diff: '', changedFiles: [], diffStats: {}, model: 'm', runOpts: {},
+    runSubagentFn: async () => { throw nonzeroExit({ exitCode: 1, stderr: '', stdout: 'Not logged in.' }); },
+  });
+  assert.match(r.stderr_tail, /Not logged in/);
+});
+
+test('redactStderrTail: strips secrets, strips ANSI, bounds the length (task 1003313)', () => {
+  assert.match(redactStderrTail('auth failed for sk-ant-api03-AbCdEf_12345'), /\[redacted\]/);
+  assert.doesNotMatch(redactStderrTail('token ghp_abcdefghijklmnopqrstuvwxyz0123'), /ghp_/);
+  assert.doesNotMatch(redactStderrTail('header Bearer eyJhbGciOiJIUzI1NiJ9.abc'), /eyJhbGci/);
+  assert.equal(redactStderrTail('\u001B[31mred error\u001B[0m'), 'red error', 'ANSI colour codes are stripped');
+  assert.equal(redactStderrTail('x'.repeat(STDERR_TAIL_MAX + 200)).length, STDERR_TAIL_MAX);
+  assert.equal(redactStderrTail('   '), null, 'an empty tail is null, not an empty string');
+  assert.equal(redactStderrTail(undefined), null);
+});
+
+test('aggregatePanel: the GRADER UNAVAILABLE verdict names exit code + CLI error (task 1003313)', () => {
+  const dead = (kind) => ({
+    kind, verdict: 'fail', error: 'SUBAGENT_NONZERO_EXIT', scores: {}, issues: [], confidence: 0,
+    exit_code: 1, stderr_tail: 'Invalid API key · Run /login',
+  });
+  const r = aggregatePanel([dead('narc'), dead('quality'), dead('hacker'), dead('efficiency')], {});
+  assert.equal(r.signals.panel_outcome, 'unavailable');
+  assert.match(r.notes_md, /GRADER UNAVAILABLE/);
+  assert.match(r.notes_md, /exit 1/, 'the verdict text must carry the exit code');
+  assert.match(r.notes_md, /Invalid API key/, 'the verdict text must carry the CLI error line');
+});
+
+test('aggregatePanel: no diagnostic appended when the workers carry none (pre-propagation grades)', () => {
+  const dead = (kind) => ({ kind, verdict: 'fail', error: 'SUBAGENT_NONZERO_EXIT', scores: {}, issues: [], confidence: 0 });
+  const r = aggregatePanel([dead('narc'), dead('quality'), dead('hacker'), dead('efficiency')], {});
+  assert.equal(r.signals.panel_outcome, 'unavailable');
+  assert.doesNotMatch(r.notes_md, /Diagnostic —/);
+});
+
 console.log(`${asyncPassed} passed, ${asyncFailed} failed (async)`);
 const totalFailed = failed + asyncFailed;
 console.log(`\n${passed + asyncPassed} passed, ${totalFailed} failed`);