@bongos/core 1.19.1033 → 1.19.1034

package/scripts/gds/dev.js

@@ -26,6 +26,9 @@
 //  * PORT is forced to branding's port (the server ignores branding — platform-server.js:44).
 //  * PGDATABASE is set for BOTH migrate.sh and the server (fixes the pool.js/migrate.sh
 //    default split); PGHOST defaults to TCP localhost (not the Linux peer socket).
+//  * Windows (task 1002707) runs the same steps: npm via its own entry point, the
+//    migrations in Git Bash, the Postgres installer's bin folder and `postgres` role.
+//    Every Windows decision is a pure function in dev-lib.js's WINDOWS section.
 
 const cp = require('node:child_process');
 const fs = require('node:fs');
@@ -70,7 +73,8 @@ Usage:
 
 What it does (idempotent — safe to re-run):
   1. Install dependencies if this checkout has none
-  2. Make sure Postgres is running (Homebrew on a Mac, systemd/service on a host)
+  2. Make sure Postgres is running (Homebrew on a Mac, systemd/service on a host,
+     the Postgres Windows service on Windows)
   3. Create this instance's database if it doesn't exist
   4. Build/refresh its tables (migrations)
   5. Start the server on the port in config/branding.json
@@ -84,33 +88,44 @@ What --server changes:
   • it checks the PUBLIC origin, not just loopback, and never opens a browser
   Extra flags: --bind <addr>, --user <unix-user> (who the service runs as).
 
-Needs Postgres + Node >= 22 installed. macOS/Linux (uses bash for migrations;
-on Windows use WSL or the Docker path in docs/recipes/self-host.md).
-Server walkthrough: docs/recipes/server-bring-up.md`);
+Needs Postgres + Node >= 22 installed. Runs on macOS, Linux and Windows.
+On Windows the migrations run in Git Bash (it comes with Git for Windows), and
+bongos dev connects to Postgres as "postgres" with the password you chose when
+installing it (set PGPASSWORD). Fallback anywhere: the Docker path in docs/recipes/self-host.md.
+Walkthroughs: docs/recipes/local-dev.md, docs/recipes/server-bring-up.md`);
 }
 
-// psql/createdb take -h/-U only when we have them; libpq fills the rest.
-function pgArgs(params) {
-  const a = ['-h', params.pgHost];
-  if (params.pgUser) a.push('-U', params.pgUser);
-  return a;
-}
+// psql/createdb connection flags (dev-lib.pgClientArgs decides; -w on Windows so a
+// password prompt can never hang a run).
+function pgArgs(params, opts) { return dev.pgClientArgs(params, opts); }
 
 function pgReady(params) {
-  return run('pg_isready', [...pgArgs(params), '-q']).status === 0;
+  return run('pg_isready', [...pgArgs(params, { forReady: true }), '-q']).status === 0;
+}
+
+// Every path `where` prints for a binary (Windows lists all matches, in PATH order).
+function whereAll(bin) {
+  if (process.platform !== 'win32') return [];
+  return run('where', [bin]).stdout.split(/\r?\n/).map((s) => s.trim()).filter(Boolean);
+}
+
+// The Postgres installs the Windows installer left under Program Files ([] elsewhere).
+function pgInstalls() {
+  return process.platform === 'win32' ? dev.windowsPgInstalls() : [];
 }
 
 // Am I root? (Only meaningful on POSIX; Windows has no getuid.)
 function isRoot() { return typeof process.getuid === 'function' && process.getuid() === 0; }
 
 // Best-effort: start whatever service manager owns Postgres on this platform
-// (Homebrew on a Mac, systemd/service on a Linux host, pg_ctl with PGDATA
-// anywhere), then poll until it accepts connections. The candidate list + sudo
-// prefixing are decided by dev-lib.pgStartPlan; this just executes them in order.
+// (Homebrew on a Mac, systemd/service on a Linux host, the installer's service on
+// Windows, pg_ctl with PGDATA anywhere), then poll until it accepts connections.
+// The candidate list + sudo prefixing are decided by dev-lib.pgStartPlan; this just
+// executes them in order.
 function ensurePostgres(params) {
   if (pgReady(params)) { ok('Postgres is running'); return true; }
   info('Postgres is not running — trying to start it…');
-  for (const step of dev.pgStartPlan({ has, isRoot: isRoot() })) {
+  for (const step of dev.pgStartPlan({ has, isRoot: isRoot(), pgInstalls: pgInstalls() })) {
     let args = step.args;
     if (step.needsFormula) {
       // Homebrew's formula name has to be discovered at runtime (postgresql@16,
@@ -177,13 +192,16 @@ function createDb(params) {
   if (/already exists/i.test(r.stderr)) { ok(`database "${params.dbName}" exists`); return true; }
   if (needsRoleBootstrap(r.stderr) && process.platform === 'linux') return bootstrapRole(params);
   fail(`could not create database "${params.dbName}": ${tail(r.stderr, 2) || r.error}`);
+  for (const line of dev.pgAuthHint(process.platform, r.stderr)) console.error(`  ${line}`);
   return false;
 }
 
-function migrate(params) {
-  const migrateSh = path.join(params.coreRoot, 'scripts', 'migrate.sh');
+// Run migrate.sh under `bashBin` (resolved by preflight: plain `bash` on Mac/Linux,
+// Git Bash's bash.exe on Windows).
+function migrate(params, bashBin = 'bash') {
+  const migrateSh = dev.bashScriptPath(path.join(params.coreRoot, 'scripts', 'migrate.sh'));
   const env = dev.buildEnv(params, { role: 'migrate' });
-  const r = run('bash', [migrateSh], { cwd: params.instanceRoot, env });
+  const r = run(bashBin, [migrateSh], { cwd: params.instanceRoot, env });
   if (r.status !== 0) {
     fail('migrations failed:');
     console.error(tail(r.stderr || r.stdout, 12));
@@ -469,54 +487,86 @@ async function cmdServeStart(params) {
   return 0;
 }
 
-async function cmdUp(params, { foreground, noLogin, skipMigrate }) {
-  info(`Standing up ${path.basename(params.instanceRoot)} on ${params.publicOrigin}`);
-
-  // Step 0: dependencies. A freshly-cloned instance has no node_modules, so
-  // migrate.sh (pg) and the server (pg/express) would crash. Install FIRST, so
-  // `bongos dev` is a true one-command bring-up even from a bare checkout (task
-  // 1002405 — pairs with the root START-HERE that names `npm install` for the
-  // truly-bare case where not even the `bongos` bin exists yet).
+// Step 0: dependencies. A freshly-cloned instance has no node_modules, so
+// migrate.sh (pg) and the server (pg/express) would crash. Install FIRST, so
+// `bongos dev` is a true one-command bring-up even from a bare checkout (task
+// 1002405 — pairs with the root START-HERE that names `npm install` for the
+// truly-bare case where not even the `bongos` bin exists yet). How npm is started
+// is dev-lib.npmInvocation's call: on Windows a plain spawn of `npm` fails.
+function installDeps(params) {
   const depsPlan = dev.depsInstallPlan({ instanceRoot: params.instanceRoot });
-  if (depsPlan.needed) {
-    if (!has('npm')) {
-      fail('node_modules is missing and `npm` is not on PATH — install Node (it bundles npm), then re-run `bongos dev`.');
-      return 1;
-    }
-    info(`installing dependencies (npm ${depsPlan.cmd}) — first run in this checkout, this can take a minute…`);
-    const r = run('npm', depsPlan.args, { cwd: params.instanceRoot, stdio: 'inherit' });
-    if (r.status !== 0) {
-      fail(`\`npm ${depsPlan.cmd}\` failed (exit ${r.status ?? '?'}). Fix the error above, then re-run \`bongos dev\`.`);
-      return 1;
-    }
-    ok('dependencies installed');
+  if (!depsPlan.needed) return true;
+  if (!has('npm')) {
+    fail('node_modules is missing and `npm` is not on PATH — install Node (it bundles npm), then re-run `bongos dev`.');
+    return false;
   }
+  info(`installing dependencies (npm ${depsPlan.cmd}) — first run in this checkout, this can take a minute…`);
+  const npm = dev.npmInvocation(depsPlan.args);
+  const r = run(npm.cmd, npm.args, { cwd: params.instanceRoot, stdio: 'inherit', shell: npm.shell });
+  if (r.status !== 0) {
+    fail(`\`npm ${depsPlan.cmd}\` failed (exit ${r.status ?? '?'}). Fix the error above, then re-run \`bongos dev\`.`);
+    return false;
+  }
+  ok('dependencies installed');
+  return true;
+}
+
+// Windows: the Postgres installer leaves psql & co. OFF PATH. Put the newest
+// installed bin folder on PATH for this run (children inherit it), so an installed
+// Postgres is found without anyone editing PATH. Returns the install used, or null.
+function addWindowsPgToPath() {
+  if (process.platform !== 'win32') return null;
+  const inst = pgInstalls()[0];
+  if (!inst) return null;
+  process.env.PATH = `${inst.bin}${path.win32.delimiter}${process.env.PATH || ''}`;
+  return inst;
+}
 
-  // Preflight: DB tooling + bash for migrations.
-  const missing = ['psql', 'createdb', 'pg_isready'].filter((b) => !has(b));
+// Preflight: Postgres client tools + a bash for migrations. Returns
+// { ok: true, bashBin } or { ok: false } after printing what to do, per platform.
+function preflight({ skipMigrate = false } = {}) {
+  const PG_TOOLS = ['psql', 'createdb', 'pg_isready'];
+  let missing = PG_TOOLS.filter((b) => !has(b));
+  if (missing.length) {
+    const inst = addWindowsPgToPath();
+    if (inst) {
+      missing = PG_TOOLS.filter((b) => !has(b));
+      if (!missing.length) ok(`using the Postgres tools in ${inst.bin}`);
+    }
+  }
   if (missing.length) {
     fail(`Postgres client tools missing: ${missing.join(', ')}`);
     console.error('  Install Postgres, then re-run `bongos dev`:');
-    console.error(process.platform === 'darwin'
-      ? '    brew install postgresql@16 && brew services start postgresql@16'
-      : '    (Debian/Ubuntu) sudo apt-get install -y postgresql   (or your distro’s package)');
-    return 1;
+    for (const line of dev.pgInstallHint(process.platform)) console.error(`    ${line}`);
+    return { ok: false };
   }
-  if (!skipMigrate && !has('bash')) {
+  if (skipMigrate) return { ok: true, bashBin: null };
+  const bash = dev.resolveBash({ has, whereAll });
+  if (!bash.ok) {
     fail('`bash` is required to run migrations (used by scripts/migrate.sh).');
-    console.error('  On Windows, use WSL, or the Docker path in docs/recipes/self-host.md.');
-    return 1;
+    for (const line of dev.bashMissingHint(process.platform, { wslOnly: bash.wslOnly })) console.error(`  ${line}`);
+    return { ok: false };
   }
+  if (process.platform === 'win32') ok(`migrations will run in ${bash.bin}`);
+  return { ok: true, bashBin: bash.bin };
+}
+
+async function cmdUp(params, { foreground, noLogin, skipMigrate }) {
+  info(`Standing up ${path.basename(params.instanceRoot)} on ${params.publicOrigin}`);
+
+  if (!installDeps(params)) return 1;
+  const pre = preflight({ skipMigrate });
+  if (!pre.ok) return 1;
 
   if (!ensurePostgres(params)) {
     fail('Postgres is installed but not reachable, and I could not start it.');
     console.error(`  Start it yourself, then re-run \`bongos dev\`:`);
-    console.error(process.platform === 'darwin' ? '    brew services start postgresql@16' : '    sudo service postgresql start');
+    for (const line of dev.pgStartHint(process.platform, { pgInstalls: pgInstalls() })) console.error(`    ${line}`);
     return 1;
   }
   if (!createDb(params)) return 1;
   if (skipMigrate) warn('skipping migrations (--skip-migrate)');
-  else if (!migrate(params)) return 1;
+  else if (!migrate(params, pre.bashBin)) return 1;
 
   const authReady = dev.authWillWork();
   if (authReady) ok('sign-in configured');
@@ -590,4 +640,6 @@ if (require.main === module) {
   main().then((code) => process.exit(code || 0)).catch((e) => { fail(e && e.message ? e.message : String(e)); process.exit(1); });
 }
 
-module.exports = { usage, pgArgs };
+// installDeps / preflight / migrate / createDb are exported for tests/dev_windows.mjs,
+// which drives the win32 branches with process.platform and spawnSync stubbed.
+module.exports = { usage, pgArgs, installDeps, preflight, migrate, createDb };

package/scripts/gds/doctor.js

@@ -30,6 +30,7 @@ const { execSync, spawnSync } = require('node:child_process');
 const { cliClient, SESSION_PATH, loadSession } = require('./cli-lib');
 const { classifyMergeDriverState, MERGE_DRIVER_NAME } = require('./install-git-hooks.js');
 const { preflightChecks } = require('./preflight');
+const { resolveEnv } = require('../../src/instance-config');
 
 // ANSI helpers (only if stdout is a TTY; otherwise emit plain text)
 const TTY = process.stdout.isTTY;
@@ -126,7 +127,7 @@ async function checkSession() {
 // this bit a real builder twice and was only diagnosed after a long manual dig.
 // This check makes it the FIRST thing doctor reports, with the one-line fix.
 //
-// Resolution mirrors the grader EXACTLY (OTB_CLAUDE_BIN / CLAUDE_BIN / 'claude',
+// Resolution mirrors the grader EXACTLY (<PREFIX>_CLAUDE_BIN / CLAUDE_BIN / 'claude',
 // shell:true on win32 so a `claude.cmd` shim resolves) so a green row here means
 // the grader's spawn will work too. Mac/Linux: shell:false, identical to today.
 function checkToolchain() {
@@ -152,7 +153,7 @@ function checkToolchain() {
   // can pass --version yet misbehave under the grader's stdio redirection
   // (SUBAGENT_NONZERO_EXIT). Learning #42.
   const claudeOk = results.some((r) => r.title === 'claude CLI' && r.level === 'ok');
-  if (claudeOk && process.platform === 'win32' && !process.env.OTB_CLAUDE_BIN && !process.env.CLAUDE_BIN) {
+  if (claudeOk && process.platform === 'win32' && !resolveEnv('CLAUDE_BIN') && !process.env.CLAUDE_BIN) {
     try {
       const where = spawnSync('where', ['claude'], { encoding: 'utf8', shell: true, timeout: 8000 });
       if (where.status === 0 && /WindowsApps/i.test(where.stdout || '')) {

package/scripts/gds/grade-correlation-audit.js

@@ -0,0 +1,280 @@
+#!/usr/bin/env node
+'use strict';
+
+// scripts/gds/grade-correlation-audit.js — do the grader's panel workers fail
+// DIFFERENTLY, or are we paying four times for two votes? (task 1002843,
+// ADR 0089 §5 — the structural answer to "Nine Judges, Two Effective Votes").
+//
+// WHY. Aggregation cannot manufacture independence a panel does not have. ADR
+// 0089 therefore makes panel composition a measured choice, and nothing measured
+// it: /grade-audit and /grader-health are qualitative sweeps with no inter-judge
+// statistics. This reads PERSISTED grades — never re-grades, never spawns a
+// model, never writes anything — and reports:
+//   (a) pairwise agreement between the panel workers on the same task: raw
+//       agreement, Cohen's kappa (agreement corrected for chance) and the phi
+//       correlation of their objections;
+//   (b) each worker's Cohen's kappa against the OWNER'S decisions;
+//   (c) which workers look redundant with another and which carry independent
+//       signal, plus the panel's effective number of independent votes.
+//
+// A VOTE is binary: a worker OBJECTS (verdict concerns or fail) or CLEARS (pass).
+// A worker that errored without a finding produced no signal and casts no vote
+// on that task — the same missing-signal rule the gate applies (#473). The
+// deterministic pseudo-judges and the non-gating reader are not voters.
+//
+// THE OWNER'S DECISIONS — the only labels used, per the task:
+//   accept   an approved override request, or a manual confirm of work whose
+//            stored grade did not pass (task confirmed/shipped anyway);
+//   reject   a denied override request.
+// A passing grade that auto-landed is NOT a label: that is the grader agreeing
+// with itself, and counting it would inflate every worker's kappa. The labelled
+// set is therefore a selected one — tasks the panel did not pass, plus the ones
+// someone argued with — and the report says so.
+//
+// THE MINIMUM-N GUARD. Every statistic is REFUSED, with the reason, below
+// MIN_N observations or when either side has fewer than MIN_PER_CLASS of a
+// class (a kappa over a constant rater is undefined, and one over five labels is
+// noise). --min-n may raise the bar, never lower it. Report-only: no gate reads
+// this, and nothing changes status (ADR 0162).
+//
+// Usage:
+//   node scripts/gds/grade-correlation-audit.js [--recent N] [--min-n N] [--json]
+//        pull the N most recently finished tasks' grades (default 400) + the
+//        decided override requests (Metic+ read) through the API
+//   ... --save <file>   also write the pulled dataset, to re-run offline
+//   ... --file <file>   audit a saved dataset instead of the live API
+
+const fs = require('node:fs');
+const { arg, hasFlag, cliClient } = require('./cli-lib');
+const { fetchRecentGrades, trimRecordedGrade } = require('./grade-replay');
+
+const PANEL = ['narc', 'quality', 'hacker', 'efficiency'];
+const MIN_N = 30;
+const MIN_PER_CLASS = 5;
+const REDUNDANT_KAPPA = 0.8;
+const INDEPENDENT_KAPPA = 0.4;
+
+// A worker's vote on one grade: 1 objects, 0 clears, null no signal.
+function voteOf(w) {
+  if (!w || typeof w !== 'object') return null;
+  const issues = Array.isArray(w.issues) ? w.issues : [];
+  const substantive = issues.some((i) => i && (i.severity === 'blocker' || i.severity === 'major'));
+  if (w.error && !substantive) return null;
+  if (w.verdict === 'pass') return 0;
+  if (w.verdict === 'concerns' || w.verdict === 'fail') return 1;
+  return null;
+}
+
+// { kind -> vote } for the panel workers of one grade.
+function panelVotes(workers) {
+  const out = {};
+  for (const w of Array.isArray(workers) ? workers : []) {
+    if (!w || !PANEL.includes(w.kind)) continue;
+    const v = voteOf(w);
+    if (v != null) out[w.kind] = v;
+  }
+  return out;
+}
+
+// Why a binary series cannot carry a statistic, or null when it can.
+function refusal(pairs, minN) {
+  if (pairs.length < minN) return `n=${pairs.length} is below the minimum of ${minN}`;
+  for (const side of [0, 1]) {
+    const ones = pairs.filter((p) => p[side] === 1).length;
+    const zeros = pairs.length - ones;
+    if (Math.min(ones, zeros) < MIN_PER_CLASS) {
+      return `${side === 0 ? 'the first' : 'the second'} rater has only ${Math.min(ones, zeros)} of one class (need ${MIN_PER_CLASS}+ of each)`;
+    }
+  }
+  return null;
+}
+
+// Cohen's kappa + raw agreement + phi for [[a, b], ...] binary pairs. Pure; the
+// caller has already applied the minimum-N guard.
+function agreementStats(pairs) {
+  const n = pairs.length;
+  let n11 = 0; let n10 = 0; let n01 = 0; let n00 = 0;
+  for (const [a, b] of pairs) {
+    if (a === 1 && b === 1) n11++; else if (a === 1) n10++; else if (b === 1) n01++; else n00++;
+  }
+  const po = (n11 + n00) / n;
+  const pa = (n11 + n10) / n;
+  const pb = (n11 + n01) / n;
+  const pe = pa * pb + (1 - pa) * (1 - pb);
+  const kappa = pe === 1 ? null : (po - pe) / (1 - pe);
+  const den = Math.sqrt((n11 + n10) * (n01 + n00) * (n11 + n01) * (n10 + n00));
+  const phi = den === 0 ? null : (n11 * n00 - n10 * n01) / den;
+  return { n, agreement: po, kappa, phi, table: { both_object: n11, only_first: n10, only_second: n01, both_clear: n00 } };
+}
+
+function guardedStats(pairs, minN) {
+  const why = refusal(pairs, minN);
+  return why ? { n: pairs.length, refused: why } : agreementStats(pairs);
+}
+
+// Effective number of independent votes for k raters whose mean pairwise
+// correlation is rho (the design-effect formula). A negative mean is clamped to
+// 0 — this is a ceiling on independence, not a claim of anti-correlation.
+function effectiveVotes(k, rho) {
+  const r = Math.max(0, rho);
+  return k / (1 + (k - 1) * r);
+}
+
+// The owner's decision per task id, from the override ledger and the tasks'
+// fates. Returns Map(task_id -> { label: 'accept'|'reject', source }). An
+// approval outranks a denial on the same task: it was the later decision.
+function ownerLabels({ grades, overrides }) {
+  const labels = new Map();
+  for (const o of overrides || []) {
+    if (o.status === 'approved') labels.set(String(o.task_id), { label: 'accept', source: 'override_approved' });
+    else if (o.status === 'denied' && !labels.has(String(o.task_id))) labels.set(String(o.task_id), { label: 'reject', source: 'override_denied' });
+  }
+  for (const g of grades || []) {
+    const id = String(g.task_id);
+    if (labels.has(id)) continue;
+    const landed = g.task_status === 'confirmed' || g.task_status === 'shipped';
+    if (landed && g.passed === false) labels.set(id, { label: 'accept', source: 'manual_confirm_after_fail' });
+  }
+  return labels;
+}
+
+function classify(kappa) {
+  if (kappa == null) return 'undetermined';
+  if (kappa >= REDUNDANT_KAPPA) return 'redundant';
+  if (kappa >= INDEPENDENT_KAPPA) return 'overlapping';
+  return 'independent';
+}
+
+// One stored grade → the slim row the audit reads (review prose hashed, as in
+// the replay corpus): { task_id, task_status, passed, workers }, or null when
+// it is not a panel grade.
+function toAuditRow({ task_id, task_status, grade }) {
+  const row = trimRecordedGrade({ task_id, grade });
+  return row ? { task_id: row.task_id, task_status: task_status || null, passed: !!(grade && grade.passed === true), workers: row.workers } : null;
+}
+
+// The whole report, pure over a dataset { grades: [toAuditRow…], overrides: [{task_id, status}] }.
+function audit(dataset, { minN = MIN_N } = {}) {
+  const floor = Math.max(MIN_N, Number(minN) || MIN_N);
+  const panels = (dataset.grades || [])
+    .map((g) => ({ task_id: String(g.task_id), votes: panelVotes(g.workers) }))
+    .filter((p) => Object.keys(p.votes).length > 0);
+  const labels = ownerLabels(dataset);
+  // 1 when the worker's vote disagrees with the owner (objected to accepted
+  // work, or cleared rejected work); only on labelled tasks it voted on.
+  const errorOf = (p, kind) => (labels.has(p.task_id) && kind in p.votes
+    ? Number(p.votes[kind] !== (labels.get(p.task_id).label === 'reject' ? 1 : 0))
+    : null);
+
+  const pairwise = [];
+  for (let i = 0; i < PANEL.length; i++) {
+    for (let j = i + 1; j < PANEL.length; j++) {
+      const a = PANEL[i]; const b = PANEL[j];
+      const pairs = panels.filter((p) => a in p.votes && b in p.votes).map((p) => [p.votes[a], p.votes[b]]);
+      const stats = guardedStats(pairs, floor);
+      // Error correlation: do the two get the SAME tasks wrong against the owner?
+      const errPairs = panels.map((p) => [errorOf(p, a), errorOf(p, b)]).filter(([x, y]) => x != null && y != null);
+      pairwise.push({ a, b, ...stats, reading: stats.refused ? 'undetermined' : classify(stats.kappa), errors: guardedStats(errPairs, floor) });
+    }
+  }
+  // The panel's effective vote count is a claim about ALL of it, so it needs
+  // every pair — one computable pair extrapolated to four workers would be the
+  // over-reading this guard exists to stop.
+  const phis = pairwise.filter((p) => !p.refused && p.phi != null).map((p) => p.phi);
+  const meanPhi = phis.length === pairwise.length ? phis.reduce((s, x) => s + x, 0) / phis.length : null;
+
+  const byLabel = { accept: 0, reject: 0 };
+  for (const v of labels.values()) byLabel[v.label]++;
+  const perWorker = PANEL.map((kind) => {
+    const pairs = panels
+      .filter((p) => labels.has(p.task_id) && kind in p.votes)
+      .map((p) => [p.votes[kind], labels.get(p.task_id).label === 'reject' ? 1 : 0]);
+    return { kind, ...guardedStats(pairs, floor) };
+  });
+
+  return {
+    min_n: floor,
+    panels: panels.length,
+    pairwise,
+    mean_pairwise_phi: meanPhi,
+    effective_votes: meanPhi == null ? null : effectiveVotes(PANEL.length, meanPhi),
+    labels: { total: labels.size, ...byLabel },
+    vs_owner: perWorker,
+  };
+}
+
+// ---------- the CLI ----------
+
+async function fetchDataset(recent) {
+  const client = await cliClient();
+  const grades = (await fetchRecentGrades({ recent, client })).map(toAuditRow).filter(Boolean);
+  const overrides = [];
+  for (const status of ['approved', 'denied']) {
+    const r = await client.overrideRequests.getOverrideRequests({ query: { status } });
+    if (!r.ok) throw new Error(`GET /override-requests?status=${status} → HTTP ${r.status} (a Metic+ read)`);
+    for (const o of (r.data && r.data.requests) || []) overrides.push({ task_id: String(o.task_id), status: o.status, decided_at: o.decided_at || null });
+  }
+  return { pulled_at: new Date().toISOString(), grades, overrides };
+}
+
+const pct = (x) => `${(x * 100).toFixed(1)}%`;
+const num = (x) => (x == null ? 'n/a' : x.toFixed(2));
+const statLine = (s) => (s.refused ? `REFUSED — ${s.refused}` : `n=${s.n}  agree ${pct(s.agreement)}  kappa ${num(s.kappa)}  phi ${num(s.phi)}`);
+
+function printReport(r) {
+  const out = [];
+  out.push(`grade correlation audit — ${r.panels} recorded panel grade(s), minimum n = ${r.min_n}`);
+  out.push('A vote is OBJECTS (concerns/fail) or CLEARS (pass); an errored worker with no finding casts none.');
+  out.push('');
+  out.push('(a) Do the workers fail differently? — agreement between each pair on the same task');
+  for (const p of r.pairwise) {
+    out.push(`  ${`${p.a} × ${p.b}`.padEnd(22)} ${statLine(p)}${p.refused ? '' : `  → ${p.reading}`}`);
+    out.push(`  ${''.padEnd(22)} same tasks wrong vs the owner: ${statLine(p.errors)}`);
+  }
+  const cleared = r.pairwise.filter((p) => !p.refused).length;
+  out.push(r.effective_votes == null
+    ? `  effective independent votes: not computable — needs all ${r.pairwise.length} pairs, ${cleared} cleared the minimum`
+    : `  mean pairwise phi ${num(r.mean_pairwise_phi)} → about ${r.effective_votes.toFixed(1)} effective independent vote(s) out of 4`);
+  out.push('');
+  out.push(`(b) Each worker against the owner's decisions — ${r.labels.total} labelled task(s): ${r.labels.accept} accepted, ${r.labels.reject} rejected`);
+  for (const w of r.vs_owner) out.push(`  ${w.kind.padEnd(22)} ${statLine(w)}`);
+  out.push('');
+  const redundant = r.pairwise.filter((p) => p.reading === 'redundant').map((p) => `${p.a}+${p.b}`);
+  const independent = r.pairwise.filter((p) => p.reading === 'independent').map((p) => `${p.a}+${p.b}`);
+  out.push('(c) Reading');
+  out.push(`  redundant pairs (kappa >= 0.8): ${redundant.join(', ') || 'none'}`);
+  out.push(`  independent pairs (kappa < 0.4): ${independent.join(', ') || 'none'}`);
+  out.push('');
+  out.push('Caveats: labels exist only where a person decided — override requests and manual confirms of work the');
+  out.push('panel did not pass — so they are a selected set, not a sample. A grade that auto-landed on a pass is');
+  out.push('never a label (that is the grader agreeing with itself). Only each task\'s LATEST grade keeps per-worker');
+  out.push('verdicts (grade_attempts stores pass/score only), so a re-graded task counts once, as its final round.');
+  console.log(out.join('\n'));
+}
+
+async function main() {
+  const file = arg('--file');
+  const dataset = file
+    ? JSON.parse(fs.readFileSync(file, 'utf8'))
+    : await fetchDataset(Number(arg('--recent')) || 400);
+  const save = arg('--save');
+  if (save && !file) fs.writeFileSync(save, `${JSON.stringify(dataset)}\n`);
+  const report = audit(dataset, { minN: Number(arg('--min-n')) || MIN_N });
+  if (hasFlag('--json')) console.log(JSON.stringify(report, null, 2));
+  else printReport(report);
+}
+
+module.exports = {
+  MIN_N,
+  agreementStats,
+  audit,
+  effectiveVotes,
+  ownerLabels,
+  panelVotes,
+  toAuditRow,
+  voteOf,
+};
+
+if (require.main === module) {
+  main().catch((err) => { console.error(`grade-correlation-audit: ${err.message}`); process.exit(2); });
+}