@bongos/core 1.17.0

package/scripts/gds/gen-session-index.js

@@ -0,0 +1,210 @@
+#!/usr/bin/env node
+'use strict';
+// gen-session-index.js — session-log index, generated (Cloud Bongos portable core; ADR 0062 §8, task 1226).
+//
+// WHY. The old CLAUDE.md §13 was a HAND-MAINTAINED index of every session: it bloated the
+// always-loaded context file, drifted, and its links recurrently dangled when a session file was
+// renamed/mis-slugged (the bug recurs as idea 57, BFG F2, task 580). The fix (ADR 0062 §8): the
+// session-log PROSE is canonical in docs/session-logs/*.md (older entries compressed into
+// docs/session-log-archive.md) + the DB session corpus (session_logs / the BFG session_records);
+// the index is GENERATED from those files so no instance hand-maintains it and a link can NEVER
+// dangle (the generator only ever links files that exist on disk).
+//
+// It writes two artifacts, the gen-diagrams.js / gen-repo-map.js pattern (ADR 0063):
+//   (1) docs/session-log-index.md — the FULL index (every session file, newest first). The
+//       browseable full history (renders on GitHub / the hall).
+//   (2) a BOUNDED "recent sessions" snippet injected between markers in CLAUDE.md §13 — the only
+//       session-log content the always-loaded context file carries.
+//
+// Zero-dependency, deterministic (sorts by date desc then filename; no timestamps) — so `--check`
+// is a clean idempotent CI gate, wired into scripts/gds/fitness.js (Path C) and auto-regenerated +
+// committed at ship by ship.js (regenerateSessionIndex), exactly like the repo map.
+//
+// Usage:
+//   node scripts/gds/gen-session-index.js             # regenerate the index + CLAUDE.md snippet
+//   node scripts/gds/gen-session-index.js --check       # write nothing; exit 2 if EITHER bucket would change
+//   node scripts/gds/gen-session-index.js --check-block # exit 2 only if the tracked CLAUDE.md §13 snippet drifts (CI gate)
+//   node scripts/gds/gen-session-index.js --check-whole # exit 2 only if docs/session-log-index.md drifts
+// docs/session-log-index.md is GITIGNORED + regenerated at deploy/box-fetch since ADR 0110 (task 1926).
+//   node scripts/gds/gen-session-index.js --json       # print the parsed entries as JSON (debug)
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const REPO_ROOT = path.resolve(__dirname, '..', '..');
+const LOGS_DIR = path.join(REPO_ROOT, 'docs', 'session-logs');
+const INDEX_PATH = path.join(REPO_ROOT, 'docs', 'session-log-index.md');
+const CLAUDE_PATH = path.join(REPO_ROOT, 'CLAUDE.md');
+
+// How many of the most-recent sessions the always-loaded CLAUDE.md snippet carries. The rest live
+// in the generated full index. Bounded on purpose (ADR 0062 §8) — the context file must stay lean.
+const SNIPPET_COUNT = 10;
+
+// Only dated session-log files are entries — a date-prefixed slug is the naming contract (§12).
+// This excludes any stray README / the index itself / non-session markdown in the directory.
+const SESSION_FILE_RE = /^(\d{4}-\d{2}-\d{2})-.*\.md$/;
+
+const BEGIN = '<!-- BEGIN GENERATED SESSION-LOG SNIPPET (scripts/gds/gen-session-index.js — do not hand-edit) -->';
+const END = '<!-- END GENERATED SESSION-LOG SNIPPET -->';
+
+// Turn a raw H1/H3 heading into clean link TEXT: strip heading markers + backticks, de-linkify
+// embedded markdown links (so the entry — itself a link — has no broken NESTED links), and de-hash
+// bare `#NNN` task refs to plain numbers (committed markdown must pass the linkify-refs CI gate; a
+// bare #NNN auto-links to a GitHub issue and 404s). Genuine `PR #N` / `issue #N` keep their `#`.
+function cleanTitle(rawHeading) {
+  let t = String(rawHeading || '');
+  t = t.replace(/^#{1,6}\s+/, ''); // drop leading heading markers
+  t = t.replace(/`/g, ''); // code spans add nothing as link text and can hide a #NNN
+  t = t.replace(/\[([^\]]*)\]\([^)]*\)/g, '$1'); // de-linkify [text](url) -> text (no nested links)
+  // de-hash bare #NNN -> NNN, but leave real GitHub refs (PR/issue/pull request #N) alone
+  t = t.replace(/(\bPR\b|\bpull request\b|\bissue\b)?(\s*)#(\d{1,7})\b/gi, (m, kw, sp, n) =>
+    kw ? `${kw}${sp}#${n}` : `${sp}${n}`
+  );
+  return t.replace(/\s+/g, ' ').trim();
+}
+
+// Parse one session-log file into { date, file, title }. date comes from the filename (the reliable
+// contract); title from the first heading, prefixed with the date if the heading doesn't already
+// lead with it, so every rendered entry reads uniformly `YYYY-MM-DD — title`.
+function parseEntry(filename, content) {
+  const m = SESSION_FILE_RE.exec(filename);
+  if (!m) return null;
+  const date = m[1];
+  const slug = filename.replace(/^\d{4}-\d{2}-\d{2}-/, '').replace(/\.md$/, '');
+  const headingLine = (content.split('\n').find((l) => /^#{1,6}\s+\S/.test(l)) || '').trim();
+  let title = cleanTitle(headingLine) || slug.replace(/-/g, ' ');
+  if (!title.startsWith(date)) title = `${date} — ${title}`;
+  return { date, file: filename, title };
+}
+
+// Read + parse every dated session-log file, newest first (date desc, then filename desc so a
+// same-day tiebreak is stable — deterministic for the --check gate).
+function collectEntries(dir = LOGS_DIR) {
+  let names = [];
+  try { names = fs.readdirSync(dir); } catch { return []; }
+  const entries = [];
+  for (const name of names) {
+    if (!SESSION_FILE_RE.test(name)) continue;
+    const content = fs.readFileSync(path.join(dir, name), 'utf8');
+    const e = parseEntry(name, content);
+    if (e) entries.push(e);
+  }
+  entries.sort((a, b) => (a.date < b.date ? 1 : a.date > b.date ? -1 : a.file < b.file ? 1 : -1));
+  return entries;
+}
+
+const line = (e, prefix) => `- [${e.title}](${prefix}${e.file})`;
+
+// docs/session-log-index.md — the full generated index (links relative to docs/).
+function renderIndex(entries) {
+  const L = [];
+  L.push('# Session log — index');
+  L.push('');
+  L.push('> **AUTO-GENERATED — do not hand-edit.** Regenerate with `node scripts/gds/gen-session-index.js` (auto-regenerated + committed at ship, like `gen-repo-map.js`). Generated from the files in [`session-logs/`](session-logs/) so a link can never dangle (retires the recurring §13 drift: idea 57, [#580](https://amazonprimea.com/builders#/task/580)). The session PROSE is canonical in those files (older entries compressed into [`session-log-archive.md`](session-log-archive.md)); the DB session corpus (`session_logs` + the BFG `session_records`) is the structured record. See [ADR 0062](adr/0062-medusa-instance-model-decoupling.md) §8 · [ADR 0063](adr/0063-generated-repo-map-symbol-skeleton.md).');
+  L.push('');
+  L.push(`**${entries.length} sessions**, newest first.`);
+  L.push('');
+  for (const e of entries) L.push(line(e, 'session-logs/'));
+  L.push('');
+  L.push('---');
+  L.push('');
+  L.push('Older prose compressed for context budget: [`session-log-archive.md`](session-log-archive.md).');
+  return L.join('\n').replace(/\n+$/, '') + '\n';
+}
+
+// The bounded snippet injected into CLAUDE.md §13 (links relative to repo root).
+function renderSnippet(entries, count = SNIPPET_COUNT) {
+  const recent = entries.slice(0, count);
+  const L = [];
+  L.push(BEGIN);
+  L.push(`**Recent sessions** (newest ${recent.length} — full history in [\`docs/session-log-index.md\`](docs/session-log-index.md)):`);
+  L.push('');
+  for (const e of recent) L.push(line(e, 'docs/session-logs/'));
+  L.push(END);
+  return L.join('\n');
+}
+
+// Replace the marked snippet region in CLAUDE.md (mirrors gen-repo-map.injectBlock).
+function injectSnippet(existing, snippet) {
+  const b = existing.indexOf(BEGIN);
+  const e = existing.indexOf(END);
+  if (b !== -1 && e !== -1 && e > b) {
+    return existing.slice(0, b) + snippet + existing.slice(e + END.length);
+  }
+  return existing; // markers absent → leave the file untouched (the §13 section seeds them)
+}
+
+function computeWrites() {
+  const entries = collectEntries();
+  const writes = [];
+
+  // Two buckets (ADR 0110, task 1926): 'whole' = docs/session-log-index.md, now
+  // GITIGNORED + regenerated at deploy/box-fetch (no committed copy → no branch
+  // collisions); 'block' = the bounded CLAUDE.md §13 snippet, still tracked, so it
+  // stays a HARD CI gate. main() gates them separately (--check-block vs --check-whole).
+  const idxNext = renderIndex(entries);
+  const idxCur = fs.existsSync(INDEX_PATH) ? fs.readFileSync(INDEX_PATH, 'utf8') : '';
+  if (idxCur !== idxNext) writes.push({ full: INDEX_PATH, content: idxNext, rel: 'docs/session-log-index.md', bucket: 'whole' });
+
+  if (fs.existsSync(CLAUDE_PATH)) {
+    const cur = fs.readFileSync(CLAUDE_PATH, 'utf8');
+    const next = injectSnippet(cur, renderSnippet(entries));
+    if (cur !== next) {
+      if (next === cur && cur.indexOf(BEGIN) === -1) {
+        console.error('gen-session-index: WARN CLAUDE.md has no snippet markers — skipping snippet injection.');
+      } else {
+        writes.push({ full: CLAUDE_PATH, content: next, rel: 'CLAUDE.md', bucket: 'block' });
+      }
+    }
+  }
+  return { entries, writes };
+}
+
+function main() {
+  // `--check` = both buckets; `--check-block` = only the tracked CLAUDE.md §13 snippet
+  // (the HARD CI gate); `--check-whole` = only the gitignored docs/session-log-index.md
+  // (deploy owns its freshness). See computeWrites() + ADR 0110.
+  const checkAll = process.argv.includes('--check');
+  const checkWhole = process.argv.includes('--check-whole');
+  const checkBlock = process.argv.includes('--check-block');
+  if (process.argv.includes('--json')) {
+    process.stdout.write(JSON.stringify(collectEntries(), null, 2) + '\n');
+    return;
+  }
+  const { writes } = computeWrites();
+  if (checkAll || checkWhole || checkBlock) {
+    const wantBlock = checkAll || checkBlock;
+    const wantWhole = checkAll || checkWhole;
+    const stale = writes.filter((w) => (w.bucket === 'block' && wantBlock) || (w.bucket === 'whole' && wantWhole));
+    const mode = checkBlock ? '--check-block' : checkWhole ? '--check-whole' : '--check';
+    if (stale.length) {
+      console.error(`gen-session-index ${mode}: STALE — would update ${stale.map((w) => w.rel).join(', ')}`);
+      console.error('  run: node scripts/gds/gen-session-index.js  (and commit any TRACKED files it changes)');
+      process.exit(2);
+    }
+    console.log(`gen-session-index ${mode}: up to date.`);
+    return;
+  }
+  if (!writes.length) {
+    console.log('gen-session-index: index + snippet already current — no changes.');
+    return;
+  }
+  for (const w of writes) fs.writeFileSync(w.full, w.content);
+  console.log(`gen-session-index: wrote ${writes.length} file(s): ${writes.map((w) => w.rel).join(', ')}`);
+}
+
+if (require.main === module) main();
+
+module.exports = {
+  cleanTitle,
+  parseEntry,
+  collectEntries,
+  renderIndex,
+  renderSnippet,
+  injectSnippet,
+  computeWrites,
+  SNIPPET_COUNT,
+  BEGIN,
+  END,
+  SESSION_FILE_RE,
+};

package/scripts/gds/git-merge-regen.js

@@ -0,0 +1,147 @@
+#!/usr/bin/env node
+// scripts/gds/git-merge-regen.js — auto-heal merge conflicts in GENERATED files
+// (task 1243; the prevention for the task 1234 / PR #167 stall).
+//
+// docs/repo-map.md is a 100%-generated index (ADR 0063); the nested CLAUDE.md docs
+// (NESTED_DIRS) carry a generated symbol-skeleton BLOCK between markers. Two
+// parallel branches regenerate them differently, so they CONFLICT on every merge
+// with main — and a `merge=union`/`ours` attribute can't fix it because the
+// committed file must equal the MERGED code or CI's `repo_map --check` fails STALE.
+// The only correct resolution is to REGENERATE from the merged tree. This module is
+// both:
+//   • a git merge driver (registered by install-git-hooks.js, declared in
+//     .gitattributes) — invoked as `git-merge-regen.js %O %A %B %P` during any
+//     `git merge` (manual, /merge-mode, ship's pre-stage); and
+//   • a library (regenerateResolved / resolveInWorktree) reused by ship.js's
+//     mergeMainIntoBranch self-heal so the heal runs even where the driver isn't
+//     installed per-clone.
+//
+// SAFETY: it regenerates the GENERATED content and 3-way-merges the hand-written
+// parts of nested docs; it succeeds ONLY if no conflict markers remain. A genuine
+// hand-written conflict falls through to a normal git conflict — it never invents a
+// resolution or clobbers a real edit.
+
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+const { spawnSync } = require('node:child_process');
+const G = require('./gen-repo-map');
+const FM = require('./gen-file-map');
+const SI = require('./gen-session-index');
+
+const REPO_ROOT = path.resolve(__dirname, '..', '..');
+
+// The files this driver knows how to regenerate. docs/repo-map.md and
+// docs/session-log-index.md are whole-file; each NESTED_DIRS CLAUDE.md is
+// hand-written prose with one generated block; docs/file-map.md is hand-written
+// prose with TWO generated section blocks (ADR 0066). (task 1385: session-log-index
+// joined so a confirmed PR that only conflicts on it self-heals like the rest.)
+const REGENERABLE = new Set([
+  'docs/repo-map.md',
+  'docs/file-map.md',
+  'docs/session-log-index.md',
+  ...G.NESTED_DIRS.map((d) => `${d}/CLAUDE.md`),
+]);
+
+// A line that begins with a git conflict marker. If any survives our resolution,
+// the conflict is in hand-written content and we must NOT auto-resolve.
+const MARKER_RE = /^(<{7}|={7}|>{7})/m;
+
+function hasMarkers(s) {
+  return MARKER_RE.test(s);
+}
+
+// 3-way merge three content strings via `git merge-file` (writes conflict markers
+// where ours/theirs truly diverge). Returns the merged text (markers and all).
+function threeWayMerge(base, ours, theirs) {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'otb-merge-'));
+  try {
+    const o = path.join(dir, 'ours');
+    const b = path.join(dir, 'base');
+    const t = path.join(dir, 'theirs');
+    fs.writeFileSync(o, ours);
+    fs.writeFileSync(b, base);
+    fs.writeFileSync(t, theirs);
+    // `git merge-file -p OURS BASE THEIRS` → merged result to stdout. Exit code is
+    // the conflict count (>0) or <0 on error; we want the body either way, so read
+    // stdout regardless of status.
+    const r = spawnSync('git', ['merge-file', '-p', o, b, t], { encoding: 'utf8' });
+    return typeof r.stdout === 'string' ? r.stdout : ours;
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+}
+
+// Produce the resolved content for one generated file from its three merge inputs.
+// Returns { content, ok }: ok=false means a real (hand-written) conflict remains —
+// the caller must leave it for a human.
+function regenerateResolved(relpath, { base = '', ours = '', theirs = '' } = {}) {
+  if (!REGENERABLE.has(relpath)) return { content: null, ok: false };
+
+  // docs/session-log-index.md is fully generated from the session-log files
+  // (gen-session-index.js, ADR 0062 §8) — like docs/repo-map.md it ignores all
+  // three merge sides and rebuilds from the merged tree. Handled before
+  // buildModel() since it needs none of the code-symbol model.
+  if (relpath === 'docs/session-log-index.md') {
+    return { content: SI.renderIndex(SI.collectEntries()), ok: true };
+  }
+
+  const model = G.buildModel();
+
+  // docs/repo-map.md is fully generated — ignore all three sides, rebuild it.
+  if (relpath === 'docs/repo-map.md') {
+    return { content: G.renderRepoMap(model), ok: true };
+  }
+
+  // docs/file-map.md: hand-written prose with TWO generated section blocks (ADR 0066). 3-way-merge
+  // the prose, then overwrite each generated block with a fresh render from disk (the same dirs +
+  // notes sidecar gen-file-map reads). Two parallel branches that each add a skill conflict only in
+  // those blocks; regenerating from the merged tree is the one correct resolution.
+  if (relpath === 'docs/file-map.md') {
+    const merged = threeWayMerge(base, ours, theirs);
+    let out = merged;
+    for (const m of FM.buildModel()) out = FM.injectSection(out, m);
+    return { content: out, ok: !hasMarkers(out) };
+  }
+
+  // Nested CLAUDE.md: 3-way-merge the hand-written prose, then overwrite the
+  // generated block with a fresh render from the merged code.
+  const dir = relpath.replace(/\/CLAUDE\.md$/, '');
+  const merged = threeWayMerge(base, ours, theirs);
+  const out = G.injectBlock(merged, G.renderNestedBlock(model, dir));
+  return { content: out, ok: !hasMarkers(out) };
+}
+
+// Reused by ship.js mergeMainIntoBranch: resolve a conflicted file straight from the
+// index stages (:1 base, :2 ours, :3 theirs) of an in-progress `git merge`, writing
+// the result into the working tree. Returns true iff fully resolved.
+function resolveInWorktree(relpath) {
+  if (!REGENERABLE.has(relpath)) return false;
+  const stage = (n) => {
+    const r = spawnSync('git', ['show', `:${n}:${relpath}`], { cwd: REPO_ROOT, encoding: 'utf8' });
+    return r.status === 0 && typeof r.stdout === 'string' ? r.stdout : '';
+  };
+  const { content, ok } = regenerateResolved(relpath, { base: stage(1), ours: stage(2), theirs: stage(3) });
+  if (content == null || !ok) return false;
+  fs.writeFileSync(path.join(REPO_ROOT, relpath), content);
+  return true;
+}
+
+// git merge-driver entrypoint: `git-merge-regen.js %O %A %B %P`. Writes the resolved
+// content into %A (git takes %A as the merge result) and exits 0; exits 1 to signal
+// an unresolved conflict (git then leaves the normal conflict for a human).
+function runDriver(argv) {
+  const [O, A, B, P] = argv;
+  if (!A || !P) {
+    process.stderr.write('git-merge-regen: usage as a merge driver: %O %A %B %P\n');
+    process.exit(1);
+  }
+  const read = (p) => { try { return fs.readFileSync(p, 'utf8'); } catch { return ''; } };
+  const { content, ok } = regenerateResolved(P, { base: read(O), ours: read(A), theirs: read(B) });
+  if (content != null) fs.writeFileSync(A, content);
+  process.exit(ok ? 0 : 1);
+}
+
+if (require.main === module) runDriver(process.argv.slice(2));
+
+module.exports = { REGENERABLE, MARKER_RE, hasMarkers, threeWayMerge, regenerateResolved, resolveInWorktree };

package/scripts/gds/grade-smoke.js

@@ -0,0 +1,205 @@
+#!/usr/bin/env node
+// Subagent grader smoke test — GDS-V3 task V3.R18 (#209) → MAS Phase 1 #395.
+//
+// Runs two synthetic ship scenarios end-to-end through the v3 multi-shot
+// subagent grader (DEFAULT_SHOTS × cross-family model, unanimous-PASS gate).
+// Asserts:
+//
+//   - Known-GOOD ship: a tiny, complete change → grade passes (unanimous
+//                      across all shots), both axes >= threshold, zero blockers.
+//   - Known-BAD ship:  a deliberately half-finished change with a TODO and
+//                      a value_summary that overpromises → grade fails,
+//                      issues[] is non-empty and names the gap.
+//
+// Hits the real Claude API at the v3-default model (Sonnet 4.6) × shots.
+// NOT run in CI. Run manually after grader changes:
+//
+//   node scripts/gds/grade-smoke.js
+//
+// Expected wall time: 60-180 seconds per scenario (shots run in parallel; the
+// slowest shot gates). Cost ~$0.30-$0.90 total against the subscription.
+
+const grader = require('../../modules/grading/grader');
+
+// -------- Scenarios --------
+
+const GOOD_TASK = {
+  id: 99001,
+  title: 'Add a tiny pure helper: hoursBetween(start, end)',
+  description: `Add a single pure helper to src/util/time.js that returns the
+number of hours between two Date instances, rounded to one decimal place.
+Acceptance:
+- Function is exported.
+- Returns a number, NOT a Date or a string.
+- Negative differences are returned negative (end < start → negative result).
+- One unit test in tests/util.mjs covers two cases (positive + negative).
+Out of scope: anything to do with timezones; calendar-aware durations.`,
+  kind: 'feature',
+  discipline: 'engineer',
+  version_id: 'GDS-V3',
+};
+const GOOD_VALUE_SUMMARY =
+  'Added hoursBetween(start, end) helper that returns one-decimal hours between two Dates, with tests covering positive and negative diffs.';
+const GOOD_CHANGED_FILES = ['src/util/time.js', 'tests/util.mjs'];
+const GOOD_DIFF = `diff --git a/src/util/time.js b/src/util/time.js
+new file mode 100644
+--- /dev/null
++++ b/src/util/time.js
+@@ -0,0 +1,8 @@
++// Pure helper — no timezone awareness, no calendar math.
++function hoursBetween(start, end) {
++  const ms = end.getTime() - start.getTime();
++  return Math.round((ms / 36e5) * 10) / 10;
++}
++
++module.exports = { hoursBetween };
+diff --git a/tests/util.mjs b/tests/util.mjs
+new file mode 100644
+--- /dev/null
++++ b/tests/util.mjs
+@@ -0,0 +1,12 @@
++import { strict as assert } from 'node:assert';
++import { createRequire } from 'node:module';
++const require = createRequire(import.meta.url);
++const { hoursBetween } = require('../src/util/time.js');
++
++const a = new Date('2026-05-13T10:00:00Z');
++const b = new Date('2026-05-13T13:30:00Z');
++assert.equal(hoursBetween(a, b), 3.5);
++assert.equal(hoursBetween(b, a), -3.5);
++
++console.log('time helper ok');
+`;
+
+const BAD_TASK = {
+  id: 99002,
+  title: 'Wire up real cost-allocation for art-pipeline tasks (Stripe-backed billing)',
+  description: `Replace the placeholder cost ledger with a real Stripe-backed billing flow.
+Acceptance:
+- New table billing_charges captures one row per art-pipeline ship with
+  stripe_charge_id, amount_cents, currency, status.
+- POST /api/gds/cost on art-pipeline tasks creates a Stripe charge against
+  the configured Hermeslines customer and writes the billing_charges row.
+- A failure to charge rolls the cost-log insert back so we never claim a
+  charge that didn't happen.
+- One smoke test that exercises the charge → row → rollback paths.
+Out of scope: refund flow.`,
+  kind: 'feature',
+  discipline: 'engineer',
+  version_id: 'GDS-V3',
+};
+const BAD_VALUE_SUMMARY =
+  'Wired up real Stripe-backed billing for art-pipeline cost allocation.';
+const BAD_CHANGED_FILES = ['src/bongos/billing.js'];
+const BAD_DIFF = `diff --git a/src/bongos/billing.js b/src/bongos/billing.js
+new file mode 100644
+--- /dev/null
++++ b/src/bongos/billing.js
+@@ -0,0 +1,15 @@
++// TODO(V3.R18 smoke): hook up the Stripe SDK.
++// For now this is a stub so the ship can land — the actual Stripe call,
++// the billing_charges table, the smoke test, and the rollback path are
++// all still to do.
++
++async function chargeForArtShip(taskId, amountCents) {
++  // FIXME: doesn't actually charge anything.
++  console.log('would charge', taskId, amountCents);
++  return { stripe_charge_id: 'demo_' + taskId, status: 'demo' };
++}
++
++module.exports = { chargeForArtShip };
+`;
+
+// -------- Helpers --------
+
+function summarize(result, label) {
+  console.log('');
+  console.log('===========================================================');
+  console.log(`${label}`);
+  console.log('===========================================================');
+  console.log(`passed:     ${result.passed}`);
+  console.log(`score:      ${result.score}/10 (threshold ${result.threshold})`);
+  console.log(`functional_fidelity: ${result.rubric_scores?.functional_fidelity ?? '-'}/10`);
+  console.log(`code_quality:        ${result.rubric_scores?.code_quality ?? '-'}/10`);
+  console.log(`confidence:          ${result.signals?.confidence ?? '-'}`);
+  // v3 multi-shot aggregated result exposes total_ms (wall time across N
+  // parallel shots); v2 single-shot exposed run_ms. Prefer total_ms; fall
+  // back to run_ms so single-shot diagnostics still print something.
+  console.log(`wall_ms:             ${result.signals?.total_ms ?? result.signals?.run_ms ?? '-'}`);
+  if (result.signals?.shot_count) {
+    console.log(`shots:               ${result.signals.shot_count}× (aggregation: ${result.signals.shot_aggregation ?? '?'})`);
+  }
+  if (result.issues?.length) {
+    console.log(`issues (${result.issues.length}):`);
+    for (const it of result.issues) {
+      console.log(`  [${it.severity || '?'}] ${it.file || '?'} — ${it.summary || ''}`);
+    }
+  }
+  if (result.signals?.parse_error || result.signals?.schema_error || result.signals?.subprocess_error) {
+    console.log(`signals.parse_error:      ${result.signals.parse_error ?? false}`);
+    console.log(`signals.schema_error:     ${result.signals.schema_error ?? false}`);
+    console.log(`signals.subprocess_error: ${result.signals.subprocess_error ?? null}`);
+  }
+  console.log('');
+  console.log('--- notes_md ---');
+  console.log(result.notes_md);
+}
+
+// -------- Main --------
+
+(async () => {
+  console.log(`Running subagent grader smoke (v${grader.VERSION}, model=${grader.DEFAULT_GRADER_MODEL}, ${grader.DEFAULT_SHOTS}× shots, threshold=${grader.THRESHOLD})`);
+  console.log('Two scenarios will run sequentially. Each spawns 3 parallel shots.');
+
+  let assertFailures = 0;
+
+  // Scenario 1: known-GOOD ship
+  console.log('\n>>> Scenario 1: known-GOOD ship (tiny, complete change)');
+  const good = await grader.gradeSubagent({
+    task: GOOD_TASK,
+    valueSummary: GOOD_VALUE_SUMMARY,
+    diff: GOOD_DIFF,
+    changedFiles: GOOD_CHANGED_FILES,
+  });
+  summarize(good, 'Scenario 1: known-GOOD');
+  if (!good.passed) {
+    console.error('ASSERT FAIL: known-GOOD ship did not pass the grader.');
+    assertFailures++;
+  }
+  const goodBlockers = (good.issues || []).filter((i) => i.severity === 'blocker').length;
+  if (goodBlockers > 0) {
+    console.error(`ASSERT FAIL: known-GOOD ship has ${goodBlockers} blocker issues.`);
+    assertFailures++;
+  }
+
+  // Scenario 2: known-BAD ship
+  console.log('\n>>> Scenario 2: known-BAD ship (TODO/FIXME, value_summary overpromises)');
+  const bad = await grader.gradeSubagent({
+    task: BAD_TASK,
+    valueSummary: BAD_VALUE_SUMMARY,
+    diff: BAD_DIFF,
+    changedFiles: BAD_CHANGED_FILES,
+  });
+  summarize(bad, 'Scenario 2: known-BAD');
+  if (bad.passed) {
+    console.error('ASSERT FAIL: known-BAD ship passed the grader (it should not).');
+    assertFailures++;
+  }
+  if ((bad.issues || []).length === 0) {
+    console.error('ASSERT FAIL: known-BAD ship produced zero issues — expected at least one.');
+    assertFailures++;
+  }
+
+  console.log('');
+  console.log('===========================================================');
+  if (assertFailures === 0) {
+    console.log('Smoke OK — grader gate works as expected (good passes, bad fails with issues).');
+    process.exit(0);
+  } else {
+    console.error(`Smoke FAILED — ${assertFailures} assertion(s) did not hold.`);
+    process.exit(1);
+  }
+})().catch((err) => {
+  console.error('Smoke crashed:', err);
+  process.exit(2);
+});