@bongos/core 1.19.1033 → 1.19.1034

package/scripts/gds/grade-replay.js

@@ -0,0 +1,237 @@
+#!/usr/bin/env node
+'use strict';
+
+// scripts/gds/grade-replay.js — the differential replay over RECORDED grades
+// (task 1002839, ADR 0089 §1). Read-only: it never grades, never spawns a model
+// and never writes a row.
+//
+// WHY. How a grade is aggregated and gated IS the live ship gate, so a change to
+// either is only behaviour-preserving if real recorded grades still come out the
+// way production recorded them. Every persisted panel grade carries its judges'
+// verdicts (signals.workers, the deterministic pseudo-judges included), so the
+// grade engine's aggregate + gate stages can be re-run over them at zero cost and
+// compared field by field with what the server stored.
+//
+// WHAT IS COMPARED — the decision, not the prose: panel_outcome, the four verdict
+// counts, the worker count, the panel's own cost, the forwarded confidence (skipped
+// when the server-side guards downgraded it — that number is theirs, not the
+// panel's), and the five rubric axes the server re-records.
+//
+// Usage:
+//   node scripts/gds/grade-replay.js                    replay the committed corpus
+//   node scripts/gds/grade-replay.js --file <corpus>    replay another corpus file
+//   node scripts/gds/grade-replay.js --live [--recent N]
+//        pull the N most recently finished tasks' grades from the API (default 150)
+//   ... --write-fixture <path>   write the AGREEING replays, trimmed (issue text and
+//        stderr hashed), one per panel shape — how the test corpus is made
+//   ... --json                   machine-readable summary
+// Exit 0 when every replayed grade agrees, 1 when any does not. A report, not a
+// gate: nothing reads the exit code but the person who ran it.
+
+const fs = require('node:fs');
+const path = require('node:path');
+const crypto = require('node:crypto');
+const { arg, hasFlag, cliClient } = require('./cli-lib');
+// Through the module facade: requiring grader.js is what registers the code panel
+// as the engine's default work-type.
+const engine = require('../../modules/grading/grader').gradeEngine;
+
+const DEFAULT_CORPUS = path.join(__dirname, '..', '..', 'tests', 'fixtures', 'grade-replay', 'recorded-panel-grades.json');
+const COUNT_FIELDS = ['pass_count', 'concerns_count', 'fail_count', 'error_count', 'worker_count'];
+const RUBRIC_AXES = ['functional_fidelity', 'code_quality', 'economy', 'security_score', 'efficiency_score'];
+const PER_SHAPE = 1;
+
+const num = (v) => (v == null || v === '' ? null : Number(v));
+
+// The decision a stored grade row records. The rubric axes are the server's
+// re-derivation (validateAndScore) of the panel's medians — equal to them for
+// every grade since the null-axis fixes (tasks 1002653 / 1003318).
+function recordedDecision(grade) {
+  const s = (grade && grade.signals) || {};
+  const guard = s.server_guard || {};
+  const out = { panel_outcome: s.panel_outcome ?? null };
+  for (const k of COUNT_FIELDS) out[k] = s[k] ?? null;
+  out.panel_cost_usd = num(s.panel_cost_usd);
+  out.confidence = guard.downgraded_to ? undefined : num(s.confidence);
+  out.rubric = {};
+  for (const a of RUBRIC_AXES) out.rubric[a] = num(grade && grade.rubric_scores ? grade.rubric_scores[a] : null);
+  return out;
+}
+
+// The same decision, read off a replayed grade-result.
+function replayedDecision(result) {
+  const s = (result && result.signals) || {};
+  const out = { panel_outcome: s.panel_outcome ?? null };
+  for (const k of COUNT_FIELDS) out[k] = s[k] ?? null;
+  out.panel_cost_usd = num(s.panel_cost_usd);
+  out.confidence = num(s.confidence);
+  out.rubric = {};
+  for (const a of RUBRIC_AXES) out.rubric[a] = num(result && result.rubric_scores ? result.rubric_scores[a] : null);
+  return out;
+}
+
+const same = (a, b) => a === b || (typeof a === 'number' && typeof b === 'number' && Math.abs(a - b) < 1e-9);
+
+// Every field on which a replay disagrees with the record, as
+// { field, recorded, replayed }. An `undefined` recorded value is not compared.
+//
+// One pairing is NOT a disagreement: a rubric axis the panel left null (no judge
+// reported it) that the row stores as 0. That 0 is the server's, not the panel's —
+// validateAndScore coerced a missing axis with Number(null) === 0 until tasks
+// 1002653 / 1003318 made it record null. A real 0/10 median replays as 0, so the
+// pairing can only mean that coercion; any other value against a null still counts.
+function compareDecision(recorded, replayed) {
+  const out = [];
+  for (const k of ['panel_outcome', ...COUNT_FIELDS, 'panel_cost_usd', 'confidence']) {
+    if (recorded[k] === undefined) continue;
+    if (!same(recorded[k], replayed[k])) out.push({ field: k, recorded: recorded[k], replayed: replayed[k] });
+  }
+  for (const a of RUBRIC_AXES) {
+    const r = (recorded.rubric || {})[a];
+    const p = (replayed.rubric || {})[a];
+    if (r === undefined || same(r, p) || (r === 0 && p === null)) continue;
+    out.push({ field: `rubric.${a}`, recorded: r, replayed: p });
+  }
+  return out;
+}
+
+const shortHash = (s) => `h:${crypto.createHash('sha256').update(String(s)).digest('hex').slice(0, 10)}`;
+
+// A worker, reduced to what aggregate + gate read. Issue summaries, their file
+// paths and stderr are hashed: the gate reads a summary and a file only to
+// de-duplicate (the hash of the trimmed text preserves exactly that), and a
+// fixture should not carry verbatim review prose.
+function trimWorker(w) {
+  const t = {
+    kind: w.kind,
+    verdict: w.verdict,
+    error: w.error ?? null,
+    scores: w.scores || {},
+    confidence: w.confidence ?? null,
+    model: w.model ?? null,
+    cost_usd: w.cost_usd ?? null,
+    retried: !!w.retried,
+    issues: (Array.isArray(w.issues) ? w.issues : []).filter((i) => i && typeof i === 'object').map((i) => ({
+      severity: i.severity ?? null,
+      file: i.file == null ? null : shortHash(i.file),
+      summary: shortHash(String(i.summary ?? '').trim()),
+    })),
+  };
+  if (w.exit_code != null) t.exit_code = w.exit_code;
+  if (w.stderr_tail) t.stderr_tail = shortHash(w.stderr_tail);
+  return t;
+}
+
+// One recorded grade → a corpus row, or null when it is not a panel grade.
+function trimRecordedGrade({ task_id, graded_at = null, grade }) {
+  const s = (grade && grade.signals) || {};
+  if (!Array.isArray(s.workers) || s.workers.length === 0) return null;
+  return { task_id: String(task_id), graded_at, recorded: recordedDecision(grade), workers: s.workers.map(trimWorker) };
+}
+
+// The panel's shape — outcome plus each judge's kind/verdict/error/retry — so
+// the fixture keeps variety instead of 200 copies of an all-pass panel.
+function shapeKey(row) {
+  return [row.recorded.panel_outcome, ...row.workers.map((w) => `${w.kind}:${w.verdict}${w.error ? `!${w.error}` : ''}${w.retried ? '~r' : ''}`)].join('|');
+}
+
+// Replay one corpus row (or one raw recorded grade) through the engine.
+function replayRow(row) {
+  const result = engine.replayRecorded({ signals: { workers: row.workers } });
+  return { result, mismatches: compareDecision(row.recorded, replayedDecision(result)) };
+}
+
+// The most recently finished tasks' STORED grades, raw and newest first:
+// [{ task_id, task_status, at, grade }]. Read-only GETs. Shared with the
+// correlation audit (scripts/gds/grade-correlation-audit.js), which needs the
+// task's fate beside its grade. The per-task reads run a few at a time — one
+// after another made a 400-task pull take minutes for no reason.
+const FETCH_CONCURRENCY = 6;
+async function fetchRecentGrades({ recent = 150, statuses = ['shipped', 'completed', 'confirmed'], client = null } = {}) {
+  const api = client || await cliClient();
+  const tasks = [];
+  for (const status of statuses) {
+    const r = await api.tasks.getTasks({ query: { status, limit: 1000 } });
+    if (!r.ok) throw new Error(`GET /tasks?status=${status} → HTTP ${r.status}`);
+    for (const t of r.data.tasks || []) tasks.push({ id: String(t.id), status: t.status || status, at: t.shipped_at || t.updated_at || '' });
+  }
+  tasks.sort((a, b) => String(b.at).localeCompare(String(a.at)));
+  const picked = tasks.slice(0, recent);
+  const out = new Array(picked.length).fill(null);
+  for (let i = 0; i < picked.length; i += FETCH_CONCURRENCY) {
+    await Promise.all(picked.slice(i, i + FETCH_CONCURRENCY).map(async (t, j) => {
+      const r = await api.tasks.getTasksId({ id: t.id, query: { include: 'grade' } });
+      if (r.ok && r.data && r.data.grade) out[i + j] = { task_id: t.id, task_status: t.status, at: t.at, grade: r.data.grade };
+    }));
+  }
+  return out.filter(Boolean);
+}
+
+async function fetchLive(recent) {
+  const rows = [];
+  for (const g of await fetchRecentGrades({ recent })) {
+    const row = trimRecordedGrade({ task_id: g.task_id, graded_at: g.at, grade: g.grade });
+    if (row) rows.push(row);
+  }
+  return rows;
+}
+
+function readCorpus(file) {
+  const doc = JSON.parse(fs.readFileSync(file, 'utf8'));
+  return Array.isArray(doc) ? doc : doc.grades;
+}
+
+async function main() {
+  const live = hasFlag('--live');
+  const rows = live
+    ? await fetchLive(Number(arg('--recent')) || 150)
+    : readCorpus(arg('--file') || DEFAULT_CORPUS);
+  const report = rows.map((row) => ({ row, ...replayRow(row) }));
+  const disagree = report.filter((r) => r.mismatches.length);
+
+  const fixturePath = arg('--write-fixture');
+  if (fixturePath) {
+    const perShape = new Map();
+    const keep = [];
+    for (const r of report) {
+      if (r.mismatches.length) continue;
+      const k = shapeKey(r.row);
+      const n = perShape.get(k) || 0;
+      if (n >= PER_SHAPE) continue;
+      perShape.set(k, n + 1);
+      keep.push(r.row);
+    }
+    const note = 'Recorded panel grades for the differential replay (tests/grade_engine_replay.mjs). Generated by scripts/gds/grade-replay.js --live --write-fixture: only grades whose replay agreed with the stored row, one per panel shape. Issue summaries, their files and stderr are hashed.';
+    fs.mkdirSync(path.dirname(fixturePath), { recursive: true });
+    // One grade per line: small in a diff, and a regenerated corpus diffs by row.
+    fs.writeFileSync(fixturePath, `{"note":${JSON.stringify(note)},\n"grades":[\n${keep.map((g) => JSON.stringify(g)).join(',\n')}\n]}\n`);
+    console.error(`wrote ${keep.length} grades (${perShape.size} panel shapes) → ${fixturePath}`);
+  }
+
+  if (hasFlag('--json')) {
+    console.log(JSON.stringify({
+      replayed: report.length,
+      agree: report.length - disagree.length,
+      disagree: disagree.map((r) => ({ task_id: r.row.task_id, graded_at: r.row.graded_at, mismatches: r.mismatches })),
+    }, null, 2));
+  } else {
+    console.log(`grade replay: ${report.length} recorded panel grade(s), ${report.length - disagree.length} agree, ${disagree.length} disagree`);
+    for (const r of disagree) {
+      const what = r.mismatches.map((m) => `${m.field} recorded=${JSON.stringify(m.recorded)} replayed=${JSON.stringify(m.replayed)}`).join('; ');
+      console.log(`  task ${r.row.task_id}${r.row.graded_at ? ` (${r.row.graded_at})` : ''}: ${what}`);
+    }
+  }
+  process.exitCode = disagree.length ? 1 : 0;
+}
+
+module.exports = {
+  compareDecision,
+  fetchRecentGrades,
+  replayRow,
+  shapeKey,
+  trimRecordedGrade,
+};
+
+if (require.main === module) {
+  main().catch((err) => { console.error(`grade-replay: ${err.message}`); process.exit(2); });
+}

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

@@ -18,7 +18,8 @@
 //   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: OTB_ALLOW_MAIN_PUSH=1.
+//      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).
@@ -33,6 +34,9 @@ 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';
@@ -122,7 +126,7 @@ 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 = process.env.OTB_ALLOW_MAIN_PUSH === '1';
+  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) => {
@@ -141,7 +145,7 @@ async function run() {
           '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 OTB_ALLOW_MAIN_PUSH=1 to override.)',
+          `(Operator/deploy identity only: set ${envPrefix()}_ALLOW_MAIN_PUSH=1 to override.)`,
         ]);
       }
     }

package/scripts/gds/main-audit.js

@@ -50,6 +50,7 @@
 const { execSync } = require('node:child_process');
 const ppc = require(require('node:path').join(__dirname, '..', '..', 'src', 'bongos', 'permission-path-check.js'));
 const { cliClient, cliExit, API_BASE } = require('./cli-lib');
+const { resolveEnv, envPrefix } = require(require('node:path').join(__dirname, '..', '..', 'src', 'instance-config.js'));
 
 // ---------- pure analyzer (tested in tests/main_audit.mjs) ----------
 
@@ -314,23 +315,31 @@ function arg(name, fallback = null) {
   return i >= 0 ? (process.argv[i + 1] && !process.argv[i + 1].startsWith('--') ? process.argv[i + 1] : true) : fallback;
 }
 
+// requestedRange — the range this run was asked to audit, or null for the default
+// window. An explicit --range wins; otherwise the <PREFIX>_AUDIT_RANGE env knob
+// (BONGOS_AUDIT_RANGE on a vanilla instance; the legacy OTB_AUDIT_RANGE is still
+// read, and warned about). The deploy gate and the CI workflow hand the range over
+// as --range, because neither can compute the branded env prefix from a shell
+// (task 1001441).
+function requestedRange(argValue, env = process.env) {
+  if (argValue && argValue !== true) return argValue;
+  return resolveEnv('AUDIT_RANGE', { env }) || null;
+}
+
 async function main() {
   const verifyHead = process.argv.includes('--verify-head');
   const doRevert = process.argv.includes('--revert');
   const strict = process.argv.includes('--strict');
   const useDb = process.argv.includes('--db');
-  let range = arg('--range');
   // #863-followup (findings #8/#14): the verify-head window was a fixed
   // HEAD~30..HEAD — a poisoned commit buried under >30 commits (merges inflate
   // the count) or landed before a rebase/force-push could escape it. The deploy
-  // gate now passes the EXACT previously-deployed SHA via OTB_AUDIT_RANGE
-  // (deploy-main-audit-gate.sh sets it to <prev-deployed-sha>..HEAD), so the
-  // gate audits precisely what this deploy introduces — no window to slip under.
+  // gate now passes the EXACT previously-deployed SHA as --range
+  // <prev-deployed-sha>..HEAD (deploy-main-audit-gate.sh), so the gate audits
+  // precisely what this deploy introduces — no window to slip under.
   // Fallbacks widen to HEAD~200 (verify-head) / a deeper origin scan otherwise.
-  if ((!range || range === true) && process.env.OTB_AUDIT_RANGE) {
-    range = process.env.OTB_AUDIT_RANGE;
-  }
-  if (!range || range === true) {
+  let range = requestedRange(arg('--range'));
+  if (!range) {
     const ref = verifyHead ? 'HEAD' : 'origin/main';
     if (!verifyHead) {
       // Default: recent origin/main. Fetch first so we're auditing the truth.
@@ -344,7 +353,7 @@ async function main() {
       console.error(
         `main-audit: DID NOT RUN — cannot build a default range for ${ref}: its first-parent history is `
         + `${Number.isFinite(depth) ? `${depth} commit(s)` : 'unreadable'} deep. `
-        + 'Pass --range <A..B> or set OTB_AUDIT_RANGE. This is a check that did not execute, not a clean audit.'
+        + `Pass --range <A..B> or set ${envPrefix()}_AUDIT_RANGE. This is a check that did not execute, not a clean audit.`
       );
       cliExit(2);
       return;
@@ -411,7 +420,7 @@ if (require.main === module) {
 
 module.exports = {
   analyzeCommits, resolveRank, parseCommits, rowsToMap,
-  clampWindow, defaultRange, firstParentDepth, DEFAULT_WINDOW,
+  clampWindow, defaultRange, firstParentDepth, DEFAULT_WINDOW, requestedRange,
   // Exported so a test can assert the address is LIVE without a database. The --db
   // path was dead for as long as the db.js carve has been landed precisely because
   // nothing checked that this require target still exports what it is called for.

package/scripts/gds/memory-map.js

@@ -22,6 +22,7 @@
 'use strict';
 const fs = require('node:fs');
 const path = require('node:path');
+const { resolveEnv } = require('../../src/instance-config');
 
 // Budgets, in bytes of MEMORY.md (~4 chars/token for markdown prose).
 const WARN_BYTES = 16000;   // ~4K tok — drifting up; warn so it gets tidied.
@@ -157,7 +158,8 @@ module.exports = {
 if (require.main === module) {
   const args = process.argv.slice(2);
   const dirArg = args.indexOf('--dir');
-  const memoryDir = dirArg >= 0 ? args[dirArg + 1] : process.env.OTB_MEMORY_DIR;
+  // <PREFIX>_MEMORY_DIR (BONGOS_ on a vanilla instance; the legacy OTB_ still read).
+  const memoryDir = dirArg >= 0 ? args[dirArg + 1] : resolveEnv('MEMORY_DIR');
   if (!memoryDir) { console.error('usage: memory-map.js --dir <memoryDir> [--apply]'); process.exit(2); }
   const mapPath = path.join(memoryDir, 'MEMORY.md');
   let text; try { text = fs.readFileSync(mapPath, 'utf8'); } catch { console.error('no MEMORY.md at', mapPath); process.exit(0); }

package/scripts/gds/onboarding-config.js

@@ -27,11 +27,12 @@ const MANIFEST_PATH = path.join(SPOOL_DIR, 'manifest.json');
 // How long the onboarding window stays open after the consent decision.
 // Friction-mining is for the first stretch of a builder's life; after that
 // they're not "onboarding" and shipping their transcripts would be noise (and
-// a privacy overreach). Override for tests via OTB_ONBOARDING_WINDOW_DAYS.
+// a privacy overreach). Override for tests via <PREFIX>_ONBOARDING_WINDOW_DAYS
+// (BONGOS_ on a vanilla instance; the legacy OTB_ spelling is still read).
 const DEFAULT_WINDOW_DAYS = 14;
 
 function windowDays() {
-  const env = Number(process.env.OTB_ONBOARDING_WINDOW_DAYS);
+  const env = Number(ic.resolveEnv('ONBOARDING_WINDOW_DAYS'));
   return Number.isFinite(env) && env > 0 ? env : DEFAULT_WINDOW_DAYS;
 }
 

package/scripts/gds/plain-cards.js

@@ -281,6 +281,10 @@ const CARDS = Object.freeze({
     'Your work touches a protected part of the project that your rank may not change, so the server would not accept it.',
     'Asking again will be refused again. I will take the protected files out and hand in the rest, or we pass the task to someone with the rank.',
     'A builder with a high enough rank, for the protected part.', RULE),
+  grade_unbacked_score: card(
+    'One of the automatic reviewers gave your work a low mark without saying what is wrong, so there is nothing listed to fix. It is not accepted yet, but it was not turned down for a named problem either.',
+    'I will ask for the review again. If the low mark comes back still without a reason, I will ask for your work to be accepted by hand, with an explanation.',
+    'Only if it keeps happening — an Archon decides whether to accept it by hand.', FAULT),
   grade_failed: card(
     'The automatic reviewers found problems in your work, so it is not accepted yet.',
     'I will fix what they listed, save it, and ask for the review again. That costs nothing extra.',

package/scripts/gds/preflight.js

@@ -28,6 +28,7 @@
 const nodeFs = require('node:fs');
 const nodePath = require('node:path');
 const { spawnSync } = require('node:child_process');
+const { resolveEnv, envPrefix, LEGACY_ENV_PREFIXES } = require('../../src/instance-config');
 
 const REPO_ROOT = nodePath.resolve(__dirname, '..', '..');
 const MIN_NODE_MAJOR = 22;
@@ -155,9 +156,16 @@ function preflightChecks({
   //    /builder-start caller via depsFinding() (task 1002403).
   out.push(depsFinding({ repoRoot, fs }));
 
-  // 3. `claude` CLI launchable — same resolution order the grader uses.
-  const bin = env.OTB_CLAUDE_BIN || env.CLAUDE_BIN || 'claude';
-  const via = env.OTB_CLAUDE_BIN ? ' (via OTB_CLAUDE_BIN)' : env.CLAUDE_BIN ? ' (via CLAUDE_BIN)' : '';
+  // 3. `claude` CLI launchable — same resolution order the grader uses:
+  //    <PREFIX>_CLAUDE_BIN (legacy spellings still read), then CLAUDE_BIN, then `claude`.
+  const prefixed = resolveEnv('CLAUDE_BIN', { env });
+  const bin = prefixed || env.CLAUDE_BIN || 'claude';
+  // The label names the spelling that actually supplied the value, so a builder who
+  // set the legacy OTB_CLAUDE_BIN is told so rather than shown a name they never set.
+  const viaName = prefixed
+    ? [envPrefix(), ...LEGACY_ENV_PREFIXES].map((p) => `${p}_CLAUDE_BIN`).find((n) => env[n] === prefixed)
+    : env.CLAUDE_BIN ? 'CLAUDE_BIN' : null;
+  const via = viaName ? ` (via ${viaName})` : '';
   let r;
   try {
     r = spawn(bin, ['--version'], { encoding: 'utf8', shell: platform === 'win32', windowsHide: true, timeout: 15000 });
@@ -174,7 +182,7 @@ function preflightChecks({
       level: 'fail',
       title: 'claude CLI',
       detail: `not launchable (${bin}: ${why}) — the grader spawns it per worker, so ships fail grading with SUBAGENT_SPAWN_FAILED.`,
-      fix: 'Run `npm i -g @anthropic-ai/claude-code` (puts a real claude on PATH), or set OTB_CLAUDE_BIN to its full path.',
+      fix: 'Run `npm i -g @anthropic-ai/claude-code` (puts a real claude on PATH), or set ' + envPrefix() + '_CLAUDE_BIN to its full path.',
     });
   }
 

package/scripts/gds/provision-core-upgrade.js

@@ -28,12 +28,13 @@
 // Its own file because scripts/gds/provision.js sits at the 1500-line oversized-file
 // ratchet, the same reason provision-net.js and provision-units.js were carved out.
 
+const crypto = require('crypto');
 const fs = require('fs');
 const os = require('os');
 const path = require('path');
 const { spawnSync } = require('child_process');
 const { CONFIG, MANIFEST_VERIFY_INTERVAL_MS, MANIFEST_VERIFY_TRIES, REPO_ROOT } = require('./provision-config.js');
-const { appUser, dbName, instanceUser, selfInstanceRoot, standaloneRoot } = require('./provision-repo.js');
+const { appUser, dbName, instanceUser, parseTargetRef, resolveOwnerGithubToken, selfInstanceRoot, standaloneRoot } = require('./provision-repo.js');
 const { isValidSlug } = require('../../modules/provisioning/provisioning.js');
 const { RELEASE_NOTES_FILE, RELEASE_NOTES_MAX_BYTES, parseChangeRecords, notesBetween } = require('./release-notes.js');
 
@@ -273,14 +274,161 @@ async function coreUpgradeInstance(inst, deps, intent) {
     // reaching here means the two disagree. Report what was SEEN rather than a verdict.
     return { ok: false, error: `the box is serving core ${served}, not the requested ${to} — the move did not take` };
   }
+
+  // ---- 5. the pin reaches the project's own repo, pushed from HERE (task 1004065) ----
+  // Only now: a pin worth saving is one the box is serving. upgrade.js was told
+  // --pin-no-push for this shape, so it committed and stopped; see pushUpgradePin.
+  const repo = hubPushesPin(inst) ? await pushUpgradePin(inst, deps, { instanceDir }) : null;
+  const unsaved = repo && !repo.pushed ? `; GitHub was not updated (${repo.code})` : '';
   await provisioning.recordEvent(db, {
     instanceId: inst.id, ownerBuilderId: inst.owner_builder_id, event: 'core-upgraded',
-    detail: served ? `core pin moved to ${served}` : `core pin moved to ${to}; the box did not answer /version, so this is unconfirmed`,
+    detail: (served ? `core pin moved to ${served}` : `core pin moved to ${to}; the box did not answer /version, so this is unconfirmed`) + unsaved,
     actor: intent.requested_by || 'runner',
   }).catch(() => {});
   if (provisioning.clearErrorNote) await provisioning.clearErrorNote(db, inst.id, 'core-upgrade').catch(() => {});
   log(served ? `  ✓ ${inst.slug} serves core ${served}` : `  ⚠ ${inst.slug} upgraded to ${to}, but did not answer /version — unconfirmed`);
-  return { ok: true, served, confirmed: served === to };
+  // `doneNote`: the drain loop resolves the intent DONE and stores this beside it, which
+  // is how the deploy page learns the upgrade landed but GitHub did not get it.
+  return { ok: true, served, confirmed: served === to, repo, doneNote: repo && !repo.pushed ? repo.note : null };
+}
+
+// ── the pin reaches the project's GitHub repo, pushed from the HUB (task 1004065) ──
+//
+// THE BUG THIS EXISTS FOR. upgrade.js commits the new pin on the box and then pushes it.
+// On a hosted project it runs connected to the PROJECT's database — it has to, for
+// migrations — while the owner's GitHub token lives in the HUB's. Its token lookup found
+// no provisioning table there (ADR 0281), fell back to `git push origin`, and origin is a
+// read-only deploy key (ADR 0176). GitHub refused, the refusal reached only the journal
+// and named the wrong cause, and the intent resolved `done`. The box ran the new core,
+// GitHub still pinned the old one, and the box's local commit stopped its fast-forward
+// pulls from taking the owner's new work: hermeslines-marketing served 1.19.994 against
+// a repo pinning 1.19.881, and pages pushed to that repo 404'd on the live site.
+//
+// WHY THE RUNNER PUSHES rather than handing upgrade.js the token. This process already
+// holds the hub's database, where the token is, and it runs as the account that owns the
+// checkout (the project's own account only READS it — grantInstanceRepoReadCmd). Passing
+// the token into the upgrade would put a credential that can write the repo inside the
+// project's own process. So the move passes --pin-no-push, upgrade.js commits, and the
+// push happens here, in the shape refreshStandaloneCorePin already uses for this repo.
+//
+// A FAILED PUSH IS NOT A FAILED UPGRADE. The site runs the new core, and rolling a good
+// deploy back would be worse than the split. The move still resolves `done`, carrying a
+// note the deploy page reads: `repo_not_updated:<code>: <sentence>`, parsed by
+// parseRepoNote in modules/provisioning/core-upgrade.js (re-stated there because a
+// module may not require a script; tests/core_upgrade_runner.mjs round-trips the two).
+//
+// NOTHING IS FORCED OR REBASED. When GitHub has commits the box does not, putting the pin
+// on top of them would change what the live box runs with no restart and no health check.
+// That is reported for an operator to reconcile, never resolved here.
+//
+// THE LIMIT, stated so nobody mistakes this for durable: the owner's token is kept for an
+// hour after they sign in with repository access (GITHUB_TOKEN_TTL_MS in src/bongos/db.js
+// — one wizard sitting). An upgrade days later usually finds none; the box's own remote
+// is then tried, and it can only read a private repo. The note says so in words.
+
+const REPO_NOTE_PREFIX = 'repo_not_updated';
+const REPO_NOTES = Object.freeze({
+  no_repo: 'This project has no GitHub repository on record, so the new version was saved on the server only.',
+  no_branch: 'The server\'s copy of the project is not on a branch, so there was nothing to save to GitHub.',
+  no_access: 'The hub had no permission to write to the project\'s GitHub repository: the owner\'s GitHub access is only kept for an hour after they connect GitHub, and the server\'s own key can only read the repository.',
+  refused: 'GitHub turned down the owner\'s GitHub access — it may have expired, or lack permission to write to the repository.',
+  behind: 'GitHub has changes the server does not have, so the new version could not be added on top of them. An operator needs to bring the two back in line; the site itself is running normally.',
+  failed: 'The hub could not save the new version to GitHub.',
+});
+// A branch name that is safe to interpolate. Narrower than git's own ref grammar on
+// purpose: a name outside it is refused, never quoted.
+const BRANCH_RE = /^[A-Za-z0-9][A-Za-z0-9._/-]{0,99}$/;
+
+/** The note a done-but-unsaved move carries, bounded for the DOM it reaches. PURE. */
+function repoNote(code, extra = '') {
+  const known = Object.prototype.hasOwnProperty.call(REPO_NOTES, code) ? code : 'failed';
+  return `${REPO_NOTE_PREFIX}:${known}: ${REPO_NOTES[known]}${extra ? ` ${extra}` : ''}`.slice(0, 600);
+}
+
+// Which shapes get their pin pushed from here: a hosted project, whose repo is the
+// owner's own. The platform's own row pushes to a repo its key CAN write, and a
+// co-tenant shares the platform's checkout, so neither changes.
+function hubPushesPin(inst) { return !!inst && inst.hosting_shape === 'cloud-host'; }
+
+// Why a push did not happen, from what git said. `behind` is checked first: a rejected
+// update means the credential WORKED and the history is what stopped it.
+function pushFault(r) {
+  const said = `${(r && r.stdout) || ''}\n${(r && r.stderr) || ''}`;
+  if (/\[rejected\]|non-fast-forward|fetch first|Updates were rejected/i.test(said)) return 'behind';
+  if (/\b403\b|Authentication failed|Invalid username or password|Write access to repository not granted|Permission to \S+ denied|marked as read only|Permission denied \(publickey\)|could not read Username/i.test(said)) return 'refused';
+  return 'failed';
+}
+
+// GitHub's own line beats git's closing `fatal:`, which names no reason (upgrade.js
+// gitSaid has the same preference).
+function gitLine(r) {
+  const lines = String((r && r.stderr) || '').split('\n').map((l) => l.trim()).filter(Boolean);
+  const server = lines.filter((l) => /^(ERROR:|remote:|!)/i.test(l));
+  const said = server.length ? server[server.length - 1] : lines[lines.length - 1];
+  return said ? `(git: ${said.slice(0, 200)})` : '';
+}
+
+/**
+ * Push a confirmed upgrade's committed pin to the project's repo. NEVER THROWS: every
+ * miss returns `{ pushed:false, code, note }`, because the drain loop turns a throw into
+ * a broken instance and this instance is running fine.
+ *
+ * The token rides a chmod-600 credential file that is removed whatever the push did —
+ * never argv (ps, the journal), never a log line. The helper list is reset first
+ * (helpers are cumulative, so a global one would answer with some other account) and
+ * hooks are off, so nothing in the project's checkout runs as this account.
+ */
+async function pushUpgradePin(inst, deps, { instanceDir }) {
+  const log = deps.log || (() => {});
+  // The CONTROL PLANE's executor and writer: the checkout, the hub db and the token are
+  // all here, never on a remote co-hosting box (refreshStandaloneCorePin's routing).
+  const exec = deps.controlExec || deps.exec;
+  const writeFile = deps.controlWriteFile || deps.writeFile || ((p, body, o) => fs.writeFileSync(p, body, o));
+  const failedRun = (r) => !r || r.softFailed === true || r.ok === false;
+  const miss = (code, extra = '') => {
+    log(`  ⚠ ${inst.slug}: GitHub was not updated — ${REPO_NOTES[code] || REPO_NOTES.failed}${extra ? ` ${extra}` : ''}`);
+    return { pushed: false, code, note: repoNote(code, extra) };
+  };
+  const repo = parseTargetRef(inst.target_ref);
+  if (!repo) return miss('no_repo');
+  const head = exec(`git -C ${instanceDir} symbolic-ref --short HEAD`, { allowFail: true });
+  const branch = failedRun(head) ? '' : String(head.stdout || '').trim();
+  if (!BRANCH_RE.test(branch)) return miss('no_branch');
+  const at = `${repo.owner}/${repo.name}@${branch}`;
+  const hardened = `git -C ${instanceDir} -c core.hooksPath=/dev/null`;
+  const env = { GIT_TERMINAL_PROMPT: '0' };   // a refused credential fails; it never waits at a prompt
+
+  const token = await resolveOwnerGithubToken(inst, deps, { tag: '[core-upgrade]' });
+  if (token) {
+    const credFile = path.join(os.tmpdir(), `bongos-gitcred-upgrade-${inst.slug}-${process.pid}-${crypto.randomBytes(6).toString('hex')}`);
+    let r = null;
+    try {
+      writeFile(credFile, `https://x-access-token:${token}@github.com\n`, { mode: 0o600 });
+      r = exec(`${hardened} -c credential.helper= -c credential.helper='store --file=${credFile}' push https://x-access-token@github.com/${repo.owner}/${repo.name}.git HEAD:${branch}`,
+        { allowFail: true, env });
+    } catch (e) {
+      return miss('failed', `(could not stage the owner's credential: ${String((e && e.message) || e).slice(0, 160)})`);
+    } finally {
+      exec(`rm -f ${credFile}`, { allowFail: true });
+    }
+    if (!failedRun(r)) {
+      log(`  ✓ pushed the pin to ${at} from the hub, over the owner's GitHub token`);
+      return { pushed: true, via: 'owner-token', branch };
+    }
+    return miss(pushFault(r), gitLine(r));
+  }
+
+  // No token stored — which is the ordinary case (see THE LIMIT above). The box's own
+  // remote is still tried: a checkout wired with a key that can write is not wrong to use.
+  const r = exec(`${hardened} push origin HEAD:${branch}`, { allowFail: true, env });
+  if (!failedRun(r)) {
+    log(`  ✓ pushed the pin to ${at} from the hub, over the checkout's own remote`);
+    return { pushed: true, via: 'origin', branch };
+  }
+  const fault = pushFault(r);
+  // A refusal here is not the owner's access being turned down — there was none to turn
+  // down. It is the read-only key, which is the no-access case.
+  return miss(fault === 'refused' ? 'no_access' : fault, gitLine(r));
 }
 
 // The pre-flight lines a dry run emits, and the refusal when it has one. upgrade.js writes
@@ -404,6 +552,9 @@ function upgradeInvocation(inst, to, { privileged = false, dryRun = false, reque
       `--health-url http://127.0.0.1:${inst.port}/healthz`,
       `--version-url http://127.0.0.1:${inst.port}/version`,
       '--commit-pin',
+      // A hosted project's pin is pushed by the RUNNER, which can reach the owner's
+      // token; the upgrade process cannot (task 1004065, pushUpgradePin).
+      hubPushesPin(inst) ? '--pin-no-push' : '',
       requestedBy ? `--requested-by ${requestedBy}` : '',
       requestedBy ? '--upgrade-source owner-control' : ''];
   return { cmd: [...shared, ...tail].filter(Boolean).join(' '), runDir: REPO_ROOT, instanceDir, runAs: account };
@@ -831,4 +982,4 @@ async function snapshotAllCoreVersions(deps) {
   return { seen };
 }
 
-module.exports = { UPGRADE_SHAPES, CHANGE_CAP, parseChangeRecords, readInstalledNotes, readPackagedNotes, changesBetween, coreCheckoutCandidates, findCoreCheckout, gitFault, resolveRunAs, versionCmd, parseServedVersion, parseSchemaPending, targetFault, parsePreflight, upgradeInvocation, preflightUpgrade, preflightCoreUpgrade, coreUpgradeInstance, snapshotCoreVersions, snapshotAllCoreVersions };
+module.exports = { UPGRADE_SHAPES, CHANGE_CAP, REPO_NOTES, repoNote, parseChangeRecords, readInstalledNotes, readPackagedNotes, changesBetween, coreCheckoutCandidates, findCoreCheckout, gitFault, resolveRunAs, versionCmd, parseServedVersion, parseSchemaPending, targetFault, parsePreflight, upgradeInvocation, preflightUpgrade, preflightCoreUpgrade, coreUpgradeInstance, snapshotCoreVersions, snapshotAllCoreVersions };

package/scripts/gds/provision-repo-auth.js

@@ -140,10 +140,25 @@ async function lookupInstanceRow(instanceDir, deps = {}) {
   } catch { return null; }
 }
 
+// What upgrade.js's pin push says when lookupInstanceRow found NO row on a checkout wired
+// with a read-only deploy key (task 1004065). PURE.
+//
+// That pairing is NOT the origin path the header above describes. The key says this is a
+// hosted private project (ADR 0176), and its own database never has the provisioning row
+// (ADR 0281) — so the owner's token cannot be looked up here, and the remote the push
+// falls back to cannot write. Silence made that indistinguishable from a misconfiguration.
+// A missing row anywhere else IS the origin path and stays quiet, which is why the caller
+// only asks for this line when the key is present. Lives here rather than beside its
+// caller because upgrade.js sits exactly at the oversized-file ratchet.
+function missingRowNote(key, remote = 'origin') {
+  return `  • pin push: no provisioning row is readable from this database, so the owner's GitHub token cannot be looked up here — and ${remote} is the read-only deploy key at ${key}. A hosted project's own database never has that row (ADR 0281); the deploy door pushes the pin from the hub instead (task 1004065).`;
+}
+
 module.exports = {
   instanceRepoRemote,
   instanceRepoRemotes,
   lookupInstanceRow,
+  missingRowNote,
   parseTargetRef,
   resolveOwnerGithubToken,
 };