@bongos/core 1.21.174 → 1.21.176

package/scripts/bongos/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 (the worker panel, 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/bongos/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/bongos/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.WORKERS.DEFAULT_PANEL.length}-worker panel, threshold=${grader.THRESHOLD})`);
+  console.log(`Two scenarios will run sequentially. Each runs the ${grader.WORKERS.DEFAULT_PANEL.length}-worker panel.`);
+
+  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);
+});

package/scripts/bongos/home-isolation-guard.js

@@ -0,0 +1,126 @@
+'use strict';
+
+// scripts/bongos/home-isolation-guard.js — setting HOME for a child process isolates
+// nothing on Windows (task 1003763).
+//
+// THE DEFECT, three times now. os.homedir() reads USERPROFILE on win32 and never
+// consults HOME, so `env: { ...process.env, HOME: tmp }` leaves the child looking at
+// the DEVELOPER'S REAL home — and therefore their real CLI session.
+//
+//   tests/cli_sessions.mjs  (task 1003760) — DESTROYED the developer's live session.
+//   tests/cli_surface.mjs   (task 1003941) — guidance printers took the authenticated
+//                                            branch, so the test failed for a false
+//                                            reason on any signed-in Windows box.
+//   tests/cli_package.mjs   (task 1003763) — an unauthenticated-path assertion could
+//                                            pass because the machine was signed in.
+//
+// The last two are the dangerous shape: a test that isolates nothing does not
+// announce itself, it just quietly stops testing what its comment says it tests.
+//
+// WHY A GUARD AND NOT THREE FIXES. Three sites, three separate tasks, each found by
+// accident. tests/memory_pull.mjs, tests/redteam_patrol.mjs and
+// tests/setup_device_flow_fallback.mjs already do it correctly, so the convention
+// exists and is simply easy to miss — which is the definition of something CI should
+// hold rather than a reviewer.
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const REPO_ROOT = path.resolve(__dirname, '..', '..');
+const TESTS_DIR = path.join(REPO_ROOT, 'tests');
+
+// WHAT COUNTS AS A SPAWN ENV. Only a literal that SPREADS process.env and assigns
+// HOME — that is the shape every real defect had. Two narrowings, both learned by
+// getting this wrong on the first run against the tree:
+//
+//   - COMMENTS ARE STRIPPED. All three fixed files now explain the bug by QUOTING
+//     the broken line, so a raw text scan reports the very files that fixed it.
+//   - A HELPER'S CALL SITE IS NOT A SPAWN ENV. tests/setup_smoke.mjs passes
+//     `{ HOME: fakeHome }` to its own runSetup(), which adds USERPROFILE itself.
+//     Requiring `...process.env` in the same literal distinguishes 'building a
+//     child's environment' from 'passing an option to a function', and flags the
+//     helper rather than each of its callers — which is where the fix belongs.
+const HOME_ASSIGN_RE = /(^|[{,\s])HOME\s*:/;
+const USERPROFILE_RE = /(^|[{,\s])USERPROFILE\s*:/;
+const PROCESS_ENV_RE = /\.\.\.process\.env/;
+
+// Strip line and block comments so prose ABOUT the bug is not read as the bug.
+// Errs toward keeping text (a guard should fail loud, not quiet): only the two
+// unambiguous comment forms are removed.
+function stripComments(src) {
+  return String(src || '')
+    .replace(/\/\*[\s\S]*?\*\//g, '')
+    .replace(/(^|[^:])\/\/.*$/gm, '$1');
+}
+
+// Files where HOME is the SUBJECT rather than an isolation mechanism, named in task
+// 1003763. An allowlist entry is a claim that the file means something else by HOME,
+// so each one says which.
+const ALLOW = new Map([
+  ['scrubber_corpus.mjs', "HOME:'/root' is literal corpus DATA — a string the scrubber is asked to redact, not an env handed to a child"],
+  ['lib_sh_resolution.mjs', 'exercises POSIX shell HOME resolution; HOME is the thing under test, and a win32 variable would change the subject'],
+  ['home_isolation_guard.mjs', "this guard's OWN tests carry the broken shape as fixture strings — it must not report its own corpus, the same way category-advisory-guard.js had to stop matching its own filename"],
+]);
+
+// PURE — the lines that build a child env with HOME and no USERPROFILE. Exported so
+// the matching is testable without the tree: a scanner whose pattern silently stops
+// matching reports a clean repo, which is the failure mode this whole file is about.
+function offendingLines(src) {
+  const lines = stripComments(src).split('\n');
+  const out = [];
+  for (let i = 0; i < lines.length; i++) {
+    if (!HOME_ASSIGN_RE.test(lines[i])) continue;
+    // A literal can wrap: read a small window either side for its companions.
+    const window = lines.slice(Math.max(0, i - 4), i + 5).join('\n');
+    if (!PROCESS_ENV_RE.test(window)) continue;   // an option object, not a child env
+    if (USERPROFILE_RE.test(window)) continue;    // already isolated properly
+    out.push({ line: i + 1, text: lines[i].trim() });
+  }
+  return out;
+}
+function checkHomeIsolation() {
+  const name = 'a child env that sets HOME also sets USERPROFILE (task 1003763)';
+  let names = [];
+  try {
+    names = fs.readdirSync(TESTS_DIR).filter((f) => f.endsWith('.mjs'));
+  } catch (e) {
+    return { name, ok: true, hardFail: false, violations: [], warnings: [`tests/ unreadable: ${e.message}`], note: 'skipped.' };
+  }
+  // The scan must not pass by finding nothing.
+  if (names.length === 0) {
+    return {
+      name, ok: false, hardFail: true,
+      violations: ['no tests/*.mjs found at all — that is a broken scan, not a clean one'],
+      warnings: [], note: 'the scan produced an empty file set.',
+    };
+  }
+
+  const violations = [];
+  let scanned = 0;
+  let sitesSeen = 0;
+  for (const n of names) {
+    const src = fs.readFileSync(path.join(TESTS_DIR, n), 'utf8');
+    scanned += 1;
+    const hits = offendingLines(src);
+    if (HOME_ASSIGN_RE.test(stripComments(src)) && PROCESS_ENV_RE.test(stripComments(src))) sitesSeen += 1;
+    if (ALLOW.has(n)) continue;
+    for (const h of hits) {
+      violations.push(`tests/${n}:${h.line} sets HOME for a child without USERPROFILE — \`${h.text.slice(0, 90)}\`. `
+        + 'On Windows os.homedir() reads USERPROFILE and ignores HOME, so this isolates NOTHING: the child sees the '
+        + 'developer\'s real home and real session, and an unauthenticated-path assertion can pass because the machine '
+        + 'happens to be signed in. Set USERPROFILE (and HOMEDRIVE/HOMEPATH) to the same directory.');
+    }
+  }
+
+  return {
+    name,
+    ok: violations.length === 0,
+    hardFail: violations.length > 0,
+    violations,
+    warnings: [],
+    note: `${scanned} test file(s) scanned, ${sitesSeen} of them build a child env with HOME; ${ALLOW.size} allowlisted where HOME is the subject rather than the isolation. `
+      + 'Three separate tasks (1003760, 1003941, 1003763) fixed this one site at a time before it was worth a check.',
+  };
+}
+
+module.exports = { checkHomeIsolation, offendingLines, stripComments, ALLOW, HOME_ASSIGN_RE, USERPROFILE_RE, PROCESS_ENV_RE };

package/scripts/bongos/hooks/pre-push.js

@@ -0,0 +1,211 @@
+#!/usr/bin/env node
+// scripts/bongos/hooks/pre-push.js — client-side push gate (SEC #863).
+//
+// Invoked via the tracked .husky/pre-push wrapper. Inert until a clone runs
+// scripts/bongos/install-git-hooks.js (from /builder-setup), which points
+// core.hooksPath at .husky/ — activation is per-clone (task 1002608; ADR 0043
+// §"G-2/G-17 resolution"). The published core artifact excludes .husky/
+// (publish-manifest.js PROTECTED_TOPOLOGY_EXCLUDE) — instance topology.
+// This is LAYER 1 of the #863 fix — fast, cooperative, blocks
+// the honest builder before a bad push ever leaves the machine. It is NOT a
+// trust boundary on its own (a builder can `git push --no-verify` or delete the
+// hook); the authoritative net is the post-push main audit + the deploy-side
+// gate (scripts/bongos/main-audit.js, LAYER 3), which read the REAL git history and
+// REAL builder ranks server-side. Layer 1 exists so the common case never even
+// gets that far.
+//
+// Two rules:
+//   1. NOBODY pushes refs/heads/main directly. Under Option A (ADR 0043) the
+//      GDS lands graded work; a builder pushing main bypasses the grader, the
+//      confirm gate, parallel-safety, and credits — exactly the #863 incident.
+//      Override for the server/operator deploy identity only: <PREFIX>_ALLOW_MAIN_PUSH=1
+//      (BONGOS_ on a vanilla instance; the legacy OTB_ALLOW_MAIN_PUSH is still read).
+//   2. A builder BELOW Metic may not push a diff that touches a permission-
+//      sensitive path (rank / permission / ship-grade / deploy / migration
+//      machinery — see src/bongos/permission-path-check.js).
+//
+// git invokes pre-push with argv: <remoteName> <remoteURL>, and feeds the refs
+// being pushed on STDIN, one per line: "<localRef> <localSha> <remoteRef> <remoteSha>".
+
+'use strict';
+
+const { execSync } = require('node:child_process');
+const path = require('node:path');
+
+const ppc = require(path.join(__dirname, '..', '..', '..', 'src', 'bongos', 'permission-path-check.js'));
+const { apiCall, productName } = require(path.join(__dirname, '..', 'cli-lib.js'));
+// The main-push override resolves through the branded prefix, the same reader
+// push-main.js's canonical spelling is written for (task 1001441).
+const { resolveEnv, envPrefix } = require(path.join(__dirname, '..', '..', '..', 'src', 'instance-config.js'));
+
+const ZERO = /^0+$/;
+const MAIN_REF = 'refs/heads/main';
+
+// The ONE exit code that means "the gate deliberately blocked this push". Any
+// other non-zero exit is a CRASH, and .husky/pre-push translates it back to a
+// warn-and-allow (task 1002725 / idea 1000704).
+//
+// WHY a reserved code and not the conventional 1: node itself exits 1 on a
+// syntax error / unhandled rejection, so `1` cannot distinguish "we decided to
+// block" from "the gate fell over". Reserving an unusual code means the wrapper
+// only ever fails CLOSED on a decision this file actually made — every other
+// shape (127 native abort, 134 SIGABRT, 1 syntax error) reads as a crash and
+// fails OPEN, which is this layer's documented design (the post-push main audit
+// is the fail-closed net).
+const BLOCK_EXIT_CODE = 13;
+
+// Sentinel returned by block() so each call site can `return block([...])` and
+// stop the sweep. run() must never call process.exit() itself — see the note on
+// the entrypoint at the bottom of this file.
+const BLOCKED = Symbol('blocked');
+
+function git(args) {
+  try {
+    return execSync(`git ${args}`, { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim();
+  } catch (_) {
+    return '';
+  }
+}
+
+// Files changed in a push line. New-branch pushes (remoteSha all-zero) diff
+// against origin/main so we see what the branch ADDS, not its whole history.
+function changedFilesFor(localSha, remoteSha) {
+  if (ZERO.test(localSha)) return []; // branch deletion — nothing to inspect
+  let range;
+  if (ZERO.test(remoteSha)) {
+    const base = git('rev-parse --verify --quiet origin/main') || git('rev-parse --verify --quiet main');
+    range = base ? `${base}...${localSha}` : localSha;
+  } else {
+    range = `${remoteSha}..${localSha}`;
+  }
+  const out = git(`diff --name-only ${range}`);
+  return out ? out.split('\n').map((s) => s.trim()).filter(Boolean) : [];
+}
+
+// #863-followup (finding #15): cli-lib's apiCall uses a bare fetch with no
+// timeout, so a slow/hung GDS API would block EVERY legit push that touches a
+// protected path (the hook awaits liveRank before deciding). Cap it: if /me
+// doesn't answer within LIVE_RANK_TIMEOUT_MS, treat rank as unknown — the
+// caller then warns-and-allows (the post-push main audit is the fail-closed
+// net), so a flaky API degrades to "audit catches it" rather than "nobody can
+// push."
+const LIVE_RANK_TIMEOUT_MS = 4000;
+
+async function liveRank() {
+  let timer = null;
+  try {
+    const timeout = new Promise((resolve) => { timer = setTimeout(() => resolve('__timeout__'), LIVE_RANK_TIMEOUT_MS); });
+    const res = await Promise.race([
+      apiCall('GET', '/api/bongos/me', null, { allowUnauthenticated: true }),
+      timeout,
+    ]);
+    // The loser of the race must be cleared. This used to leak: process.exit()
+    // tore the loop down regardless, so nobody noticed. Now that the hook exits
+    // NATURALLY (task 1002725), an armed 4s timer would hold every
+    // protected-path push open for the full timeout after the API already
+    // answered.
+    if (timer) clearTimeout(timer);
+    if (res === '__timeout__') {
+      console.error(`\n\x1b[33m⚠ permission gate: GDS /me did not respond within ${LIVE_RANK_TIMEOUT_MS}ms — treating rank as unknown.\x1b[0m`);
+      return null;
+    }
+    if (res && res.ok) return res.data?.builder?.rank ?? null;
+  } catch (_) { /* offline / no session */ } finally { if (timer) clearTimeout(timer); }
+  return null;
+}
+
+function block(lines) {
+  console.error(`\n\x1b[31m✖ push blocked by the ${productName()} permission gate (SEC #863)\x1b[0m`);
+  for (const l of lines) console.error('  ' + l);
+  console.error('');
+  process.exitCode = BLOCK_EXIT_CODE;
+  return BLOCKED;
+}
+
+async function run() {
+  // The operator / server deploy identity is the ONLY thing allowed to push
+  // main, and it sets this env explicitly. (Belt-and-braces; under full Option A
+  // builders never push main at all.)
+  const allowMain = resolveEnv('ALLOW_MAIN_PUSH') === '1';
+
+  const stdin = require('node:fs').readFileSync(0, 'utf8');
+  const refs = stdin.split('\n').map((l) => l.trim()).filter(Boolean).map((l) => {
+    const [localRef, localSha, remoteRef, remoteSha] = l.split(/\s+/);
+    return { localRef, localSha, remoteRef, remoteSha };
+  });
+  if (refs.length === 0) return; // nothing to push
+
+  // Rule 1: no direct push to main.
+  if (!allowMain) {
+    for (const r of refs) {
+      if (r.remoteRef === MAIN_REF && !ZERO.test(r.localSha)) {
+        return block([
+          'Direct pushes to `main` are not allowed.',
+          'The GDS lands graded work for you: run `/builder-ship` on your claimed task.',
+          'A direct push to main skips the grader, the confirm gate, parallel-safety, and',
+          'credits — this is exactly the breach SEC #863 closes (ADR 0043).',
+          '',
+          `(Operator/deploy identity only: set ${envPrefix()}_ALLOW_MAIN_PUSH=1 to override.)`,
+        ]);
+      }
+    }
+  }
+
+  // Rule 2: a sub-Metic builder may not push permission-sensitive paths.
+  const allChanged = new Set();
+  for (const r of refs) {
+    for (const f of changedFilesFor(r.localSha, r.remoteSha)) allChanged.add(f);
+  }
+  const changedFiles = [...allChanged];
+  const protectedHits = ppc.matchProtected(changedFiles);
+  if (protectedHits.length === 0) return; // nothing sensitive — fast path
+
+  const rank = await liveRank();
+  if (rank === null) {
+    // Couldn't resolve rank (offline / no session). Warn but allow — the
+    // post-push main audit (layer 3) re-checks with the real DB rank and is the
+    // fail-closed enforcement. We do NOT hard-block here to avoid bricking a
+    // Metic/Archon working offline.
+    console.error('\n\x1b[33m⚠ permission gate: could not confirm your rank (offline or no GDS session).\x1b[0m');
+    console.error('  This push touches permission-sensitive paths:');
+    for (const h of protectedHits.slice(0, 10)) console.error(`    - ${h.file}`);
+    console.error('  Allowing the push; the server-side audit will re-check with your real rank.\n');
+    return;
+  }
+
+  const result = ppc.checkPermissionPaths({ changedFiles, builderRank: rank });
+  if (result.hardFail) {
+    return block([
+      `Your rank '${rank}' is below Metic and may not modify permission-sensitive surfaces:`,
+      ...protectedHits.slice(0, 12).map((h) => `  - ${h.file}  (matches ${h.glob})`),
+      '',
+      'These files define the rank ladder, the trust boundary, the ship/grade gates,',
+      'the deploy path, and DB migrations. If a change here is genuinely needed,',
+      'raise it with an Archon — do not edit it from a sandbox/newcomer rank (ADR 0016, ADR 0043).',
+    ]);
+  }
+}
+
+// Only run when invoked directly (the husky wrapper does `node pre-push.js`).
+// Requiring this file (e.g. a test importing matchProtected logic) must NOT
+// read stdin or call process.exit.
+//
+// NOTE (task 1002725): nothing on this path may call process.exit(). Calling it
+// after liveRank()'s fetch aborts the process natively on Windows —
+// "Assertion failed: !(handle->flags & UV_HANDLE_CLOSING), file src\win\async.c"
+// — because undici's handles are still closing when the loop is torn down. The
+// abort exits 127 BEFORE the .catch() below can run, so the fail-open guarantee
+// was silently inverted into "no Windows builder can push anything at all".
+// Setting process.exitCode and letting the loop drain naturally is what keeps
+// this hook's own error handling reachable.
+if (require.main === module) {
+  run().catch((e) => {
+    // A hook crash must not silently allow a bad push of protected paths, but it
+    // also must not brick all pushes on an unrelated bug. Fail OPEN with a loud
+    // warning — the post-push audit remains the fail-closed net.
+    console.error(`\n⚠ permission pre-push hook errored (${e.message}); allowing push. The server-side audit still applies.\n`);
+    process.exitCode = 0;
+  });
+}
+
+module.exports = { run, BLOCK_EXIT_CODE };