@bongos/core 1.21.174 → 1.21.176

package/scripts/bongos/upgrade-artist-gate.js

@@ -0,0 +1,46 @@
+'use strict';
+
+// scripts/bongos/upgrade-artist-gate.js — the artist gate's deploy hold on the
+// UPGRADE path (task 1004205; ADR 0241).
+//
+// WHY. On a `strict` project an unresolved artist review holds the DEPLOY, never
+// the ship. Only go-live.js asked the gate, and cloudbongos.com moves its pin
+// with the vendored `upgrade.js --from` instead, so on this instance an open
+// review held nothing (2026-09-23: the gate answered holds:true and the upgrade
+// never read it). Every UI change now files such a review (owner decision
+// 2026-09-23, task 1004201), so this is where "the owner sees it before users
+// do" is actually enforced.
+//
+// It reuses go-live.js's reader and judgement verbatim, so both deploy paths
+// decide the same answer the same way: a hold or a broken gate halts, a gate
+// that cannot be read at all is a note. It asks the instance being upgraded,
+// at the origin of --health-url, because the box runs the instance it upgrades;
+// the instance answers a direct local request without a session (the route).
+// The FIRST upgrade carrying this asks an instance that still wants a session,
+// so it can only print the unread note — every upgrade after that holds.
+// Kept out of upgrade.js, which sits at the line cap.
+
+const { readArtistGate, artistGateEntries } = require('./go-live');
+
+const GATE_TIMEOUT_MS = 10_000;
+
+function unreadNote(why) {
+  return { halts: [], notes: [{ code: 'ARTIST_GATE_UNREAD', message: `could not read this instance's artist gate (${why}) — if the project runs artist_gate 'strict', an unresolved artist review may be holding this deploy and this upgrade cannot see it` }] };
+}
+
+// checkArtistGate — { halts, notes } for this instance's gate, go-live's shape.
+async function checkArtistGate({ healthUrl }, deps = {}) {
+  if (!healthUrl) return unreadNote('no --health-url to reach the instance by');
+  let origin;
+  try { origin = new URL(healthUrl).origin; } catch (_) { return unreadNote(`--health-url ${healthUrl} is not a URL`); }
+  const fetchImpl = deps.fetchImpl || fetch;
+  const call = async (method, urlPath) => {
+    const res = await fetchImpl(`${origin}${urlPath}`, { method, signal: AbortSignal.timeout(GATE_TIMEOUT_MS) });
+    let data = null;
+    try { data = await res.json(); } catch (_) { /* not JSON: readArtistGate reads it as "not a gate" */ }
+    return { status: res.status, ok: res.ok, data };
+  };
+  return artistGateEntries(await readArtistGate(call));
+}
+
+module.exports = { checkArtistGate };

package/scripts/bongos/upgrade-commit-identity.js

@@ -0,0 +1,32 @@
+'use strict';
+
+// scripts/bongos/upgrade-commit-identity.js — WHO the pin commit is signed by when the project's
+// git names nobody (task 1004514). Kept out of upgrade.js, which sits at the 1500-line cap.
+//
+// THE BUG. persistPin staged the new pin and ran `git commit`. In a repo with no
+// user.name/user.email — none in the repo, none global for the account the upgrade runs as —
+// git refuses ("Please tell me who you are"), so the move reported success with the pin
+// STAGED but never committed. The next move then read its own leftovers as a dirty tree and
+// spent its one automatic fix (wedge-remedy.js) committing them. Seen live on 2026-10-01: a
+// throwaway hosted project on cloudbongos.com, and hermeslines-marketing, whose repo carries no
+// identity while every scaffolded one does (provision-repo.js sets it at scaffold time).
+//
+// THE FIX IS A FALLBACK, NEVER AN OVERRIDE. A repo or account that names someone keeps
+// signing as them. Only an empty answer gets the provisioner's own identity, the one the
+// scaffold commits as, through git's AUTHOR/COMMITTER env — so nothing is written into the
+// owner's git config, and the argv stays exactly what it was.
+
+/**
+ * Env for `git commit` in `instanceDir`: null when git already names a committer there, else
+ * the provisioner's identity. Asks git itself, so repo, global and system config all count.
+ */
+function commitIdentityEnv(instanceDir, run, env = process.env) {
+  const r = run('git', ['config', 'user.email'], { cwd: instanceDir, encoding: 'utf8' });
+  if (r && !r.error && r.status === 0 && String(r.stdout || '').trim()) return null;
+  if (env.GIT_AUTHOR_EMAIL || env.GIT_COMMITTER_EMAIL) return null;   // the caller already chose
+  const { provisionerBotName, provisionerBotEmail } = require('./instance-apex.js');
+  const name = provisionerBotName(), email = provisionerBotEmail(env);
+  return { ...env, GIT_AUTHOR_NAME: name, GIT_AUTHOR_EMAIL: email, GIT_COMMITTER_NAME: name, GIT_COMMITTER_EMAIL: email };
+}
+
+module.exports = { commitIdentityEnv };

package/scripts/bongos/upgrade-migrate.js

@@ -0,0 +1,224 @@
+'use strict';
+
+// scripts/bongos/upgrade-migrate.js — the DATABASE side of a core move: which command
+// migrates this instance (task 1004274, found preparing the task 1004047 catch-up pass),
+// WHICH ACCOUNT that command runs as, and whether that account can reach the database at
+// all (task 1004512). Kept out of upgrade.js, which sits at the 1500-line cap.
+//
+// THE GAP. upgrade.js migrated with `npm run migrate`, and that only works where the
+// instance's package.json DECLARES a migrate script. A greenfield scaffold always does
+// (init.js buildInstancePackageJson writes INSTANCE_MIGRATE_SCRIPT), but the ADOPT layer
+// does not: init.js mergeCoreDependency adds the core dependency and nothing else, and
+// for a repo that had no package.json of its own it mints `{ name, private,
+// dependencies }`. So an adopted project that is not a JavaScript app has no scripts at
+// all. There `npm run migrate` answers "Missing script" — AFTER the pin has moved and
+// the new core is installed — and the upgrade rolls itself back, restarting someone's
+// live app to change nothing. mercury (a Python/Flask project; its package.json is
+// exactly name/private/dependencies) is that shape, and it is why the catch-up pass
+// could not reach it. The dry run could not warn either, because it never looked.
+//
+// THE FALLBACK IS NOT A NEW MIGRATION PATH. It is the command a scaffold's own script
+// IS, and the one the control plane ran to create that instance's database at stand-up
+// (provision-repo.js standaloneMigrateCmd): the installed core's scripts/migrate.sh,
+// run from the instance root. A declared script still wins, whatever it says — an
+// owner who wrote their own migrate step meant it — and `--skip-migrate` stays the
+// only way to run no migration at all, which on a real jump leaves the new code
+// running against the old schema.
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { spawn, spawnSync } = require('node:child_process');
+
+// Relative to the instance root, POSIX on purpose: it is an argument to bash, and it
+// must stay byte-identical to the scaffold's script (tests/upgrade_migrate.mjs pins it
+// against init.js INSTANCE_MIGRATE_SCRIPT).
+const CORE_MIGRATE_SCRIPT = 'node_modules/@bongos/core/scripts/migrate.sh';
+
+/**
+ * How this instance is migrated: its own declared script, or the core's migrate.sh.
+ *
+ * Only a package.json we could READ, and that names no migrate script, earns the
+ * fallback. A missing or unparseable one keeps the old command, which then fails the
+ * way it always did — guessing at a file this could not parse would be worse.
+ *
+ * `env` exists only on the fallback, and only to hand migrate.sh what `npm run` would:
+ * migrate.sh finds the instance from INIT_CWD before its own cwd (task 2180), and npm
+ * sets it to the directory the script runs in. Launched directly, a stray INIT_CWD
+ * inherited from whoever started this upgrade would aim it at the wrong project.
+ *
+ * `note` is a pre-flight line, so the dry run says which command the move will run.
+ */
+function migratePlan(instanceDir, { fsImpl = fs, env = process.env } = {}) {
+  let pkg = null;
+  try { pkg = JSON.parse(fsImpl.readFileSync(path.join(instanceDir, 'package.json'), 'utf8')); } catch { /* absent or unreadable */ }
+  const scripts = pkg && typeof pkg.scripts === 'object' && pkg.scripts ? pkg.scripts : {};
+  const declared = typeof scripts.migrate === 'string' && scripts.migrate.trim() !== '';
+  if (!pkg || declared) {
+    return { via: 'npm-script', cmd: 'npm', args: ['run', 'migrate'], label: 'npm run migrate', env: null, note: null };
+  }
+  return {
+    via: 'core-script',
+    cmd: 'bash',
+    args: [CORE_MIGRATE_SCRIPT],
+    label: `bash ${CORE_MIGRATE_SCRIPT}`,
+    env: { ...env, INIT_CWD: instanceDir },
+    note: 'migrate: this project declares no migrate script (an adopted repo), so the core\'s own scripts/migrate.sh will run — the command a scaffold\'s script runs',
+  };
+}
+
+// ---- which ACCOUNT the database work runs as (task 1004512) -----------------
+//
+// THE BUG THIS EXISTS FOR. A core move on a project provisioned since task 1003369 ran
+// the WHOLE of upgrade.js as the project's own `bongos-<slug>` account. That account only
+// READS the checkout (provision-repo.js grantInstanceRepoReadCmd adds it to the app user's
+// group; /srv/<base>/<slug> is owned by the app user), so the move died at its very first
+// step: `git status` refused with `fatal: detected dubious ownership in repository`, the
+// clean-tree pre-flight reported "working tree not clean", and the self-heal chain
+// committed a tree that was never dirty and retried into the identical failure. Every move
+// on such a project ended in a blocker, and the dirt it named did not exist. Had git been
+// appeased, `npm install`, the pin commit and the .claude materialization — all WRITES to a
+// checkout that account cannot write — would have failed next.
+//
+// SO THE MOVE IS SPLIT, rather than papered over with a `safe.directory` entry:
+//   • everything that touches the CHECKOUT runs as the account that owns it (the app
+//     user) — that is also what pushUpgradePin and the wedge remedy's `git` already do;
+//   • everything that touches the DATABASE runs as the project's own account, which is
+//     where the isolation actually lives: it is the project's Postgres login role
+//     (provision-repo.js instanceDbRole), the database is owned by it, and CONNECT is
+//     revoked from PUBLIC — so the app user cannot reach it even by accident.
+//
+// The runner passes `--migrate-as <account>` ONLY when the two differ. A control plane and
+// a project old enough to still run as the app user emit no flag and behave exactly as
+// they did before, which is the half of the fleet that was already working.
+//
+// Narrower than a unix account name may legally be, on purpose: the value arrives on a
+// command line and is refused rather than quoted if it falls outside. ONE copy for the
+// upgrade CLI — wedge-remedy.js imports this rather than re-declaring it, because two
+// copies of a security predicate drift one edit at a time. provision-repo.js keeps its own
+// UNIX_ACCOUNT_RE: that file is the control-plane provisioner and nothing it does should
+// depend on the upgrade CLI, so the duplication there buys a layer boundary.
+const ACCOUNT_RE = /^[a-z_][a-z0-9_-]{0,31}$/;
+
+/**
+ * `cmd args` as `account`, or unchanged when there is no account to drop to. PURE.
+ *
+ * argv form, never a shell string, so nothing here is quoted or interpolated. `sudo -n`
+ * because a sudoers rule that would PROMPT must fail fast: an upgrade runs unattended and
+ * a password prompt nobody can answer would hang the deploy rather than fail it.
+ *
+ * sudo resets the environment, so the variables migrate genuinely needs are re-stated as
+ * `env K=V` arguments: PGDATABASE (migrate.sh defaults to production when it is unset, so
+ * it is always passed and never inherited) and, for the core-script fallback, INIT_CWD
+ * (which is how migrate.sh finds the instance — task 2180).
+ */
+function asAccount(account, cmd, args, extraEnv = {}, env = process.env) {
+  if (!account) return { cmd, args };
+  if (!ACCOUNT_RE.test(String(account))) throw new Error(`asAccount: ${JSON.stringify(account)} is not a unix account name`);
+  const carry = { ...(env.PGDATABASE ? { PGDATABASE: env.PGDATABASE } : {}), ...extraEnv };
+  const pairs = Object.entries(carry).map(([k, v]) => `${k}=${v}`);
+  return { cmd: 'sudo', args: ['-n', '-u', account, 'env', ...pairs, cmd, ...args] };
+}
+
+// migrate.sh reaches Postgres over the local socket as the CURRENT OS USER (peer
+// auth) — so running an upgrade under `sudo` connects as `root`, which usually has
+// no Postgres role. The failure surfaces mid-run as a raw
+// `FATAL: role "root" does not exist`, AFTER the pin has already moved, which then
+// triggers the whole auto-rollback dance for what is really an operator mistake.
+// This names it up front instead (task 1002712). `account` (task 1004512) makes the
+// probe connect as whoever migrate will, so the pre-flight and the migration cannot
+// disagree about which role is being tested.
+function preflightDbIdentity({ instanceDir, db, account = null }, run = spawnSync) {
+  const q = asAccount(account, 'psql', ['-tAc', 'select 1'], db ? { PGDATABASE: db } : {});
+  const r = run(q.cmd, q.args, {
+    cwd: instanceDir, encoding: 'utf8',
+    env: { ...process.env, ...(db ? { PGDATABASE: db } : {}) },
+  });
+  if (!r || r.error) return { ok: true, skipped: 'psql not on PATH — leaving it to migrate' };
+  if (r.status === 0) return { ok: true };
+
+  const out = `${r.stderr || ''}${r.stdout || ''}`;
+  // The escalation itself not working is this pre-flight's business, not migrate's (task
+  // 1004512). Soft-skipping it would let the pin move and then fail at migrate for the one
+  // reason that was knowable up front, costing a full rollback — the exact shape the
+  // role-does-not-exist check below exists to avoid. Only ever reachable with an account.
+  if (account && /^sudo:/m.test(out)) {
+    return { ok: false, reason: `the database steps cannot run as "${account}" — sudo refused.\n`
+      + `    ${out.trim().split('\n').find((l) => l.startsWith('sudo:')) || ''}\n`
+      + `    The move writes files as the account that owns the checkout and hands only the\n`
+      + `    database to the project's own account (--migrate-as), so the first needs\n`
+      + `    passwordless sudo to the second. Checked BEFORE the pin moves.` };
+  }
+  const m = out.match(/role "([^"]+)" does not exist/i);
+  if (!m) return { ok: true, skipped: 'psql failed for another reason — leaving it to migrate' };
+  return {
+    ok: false,
+    role: m[1],
+    reason: `Postgres has no role "${m[1]}" — migrate would fail after the pin moved.\n`
+      + `    migrate.sh connects over the local socket as the CURRENT OS USER. Running the\n`
+      + `    upgrade under sudo connects as root, which is almost never a Postgres role.\n`
+      + `    Re-run as the user that owns the instance (e.g. sudo -u <owner> …), passing the\n`
+      + `    npm token through if the core comes from the registry.`,
+  };
+}
+
+// ── what a FAILED migrate says, so nobody needs SSH to read it (task 1004734) ────────────
+//
+// Seen 2026-10-14: toast's move 1.21.20 → 1.21.115 rolled back and the hub kept exactly
+// "migrate failed (exit 3)". Exit 3 is psql under ON_ERROR_STOP: ONE statement failed on
+// that project's real data. Which file, and which error, reached only the box's journal,
+// because runMigrate spawned with stdio 'inherit'. migrate.sh prints `apply  <version>`
+// before each file, and psql -f prefixes its ERROR with the file too, so the output
+// already names both; it just never came back.
+//
+// teeSpawn: the child's stdout/stderr are piped and WRITTEN THROUGH as they arrive — the
+// journal still reads live, exactly as under 'inherit' — while the last TEE_TAIL chars are
+// kept for migrateFailureDetail. Async, because a sync spawn cannot write through.
+const TEE_TAIL = 64 * 1024;
+function teeSpawn(cmd, args, opts = {}, { spawnImpl = spawn, out = process.stdout, err = process.stderr } = {}) {
+  return new Promise((resolve) => {
+    let output = '';
+    const keep = (c) => { output = (output + c).slice(-TEE_TAIL); };
+    let child;
+    try { child = spawnImpl(cmd, args, { ...opts, stdio: ['inherit', 'pipe', 'pipe'] }); } catch (e) { resolve({ error: e }); return; }
+    for (const [pipe, sink] of [[child.stdout, out], [child.stderr, err]]) {
+      pipe.setEncoding('utf8');
+      pipe.on('data', (c) => { sink.write(c); keep(c); });
+    }
+    child.on('error', (e) => resolve({ error: e }));
+    child.on('close', (status) => resolve({ status, output }));
+  });
+}
+
+// The failing migration and psql's ERROR line, as " at <file>: ERROR: …" — or '' when the
+// output names neither. Secret-scrubbed (the line is stored on the hub and shown to the
+// owner) and capped. The LAST `apply` line is the file it stopped in: migrate.sh stops at
+// the first failure. PURE.
+const DETAIL_MAX = 300;
+function migrateFailureDetail(text) {
+  const lines = String(text || '').split(/\r?\n/);
+  const last = (re) => { for (let i = lines.length - 1; i >= 0; i--) { const m = re.exec(lines[i]); if (m) return m; } return null; };
+  const err = last(/\b((?:ERROR|FATAL):\s+.*)$/);
+  const file = (last(/^apply\s+(\S+)\s*$/) || (err && /^psql:(?:.*[\\/])?([^\\/:]+?)(?:\.sql)?:\d+:/.exec(err.input)) || [])[1] || '';
+  let msg = err ? err[1].trim() : '';
+  if (msg) {
+    // No scrubber, no error text: a credential in a psql line must never reach the hub.
+    try { msg = require('../../modules/security/secret-scrub.js').scrubSecrets(msg); } catch { msg = ''; }
+  }
+  const cap = (s, n) => (s.length > n ? `${s.slice(0, n - 1)}…` : s);
+  return (file ? ` at ${cap(file, 80)}` : '') + (msg ? `: ${cap(msg, DETAIL_MAX)}` : '');
+}
+
+/** runMigrate's spawn result → { ok, code, detail } | { ok:false, reason }. PURE. */
+function migrateResult(r) {
+  if (!r || r.error) return { ok: false, reason: r && r.error ? r.error.message : 'spawn failed' };
+  if (r.status === 0) return { ok: true, code: 0 };
+  // r.output from teeSpawn; stdout/stderr from a spawnSync-shaped run (tests, any injected run)
+  return { ok: false, code: r.status, detail: migrateFailureDetail([r.output, r.stdout, r.stderr].filter(Boolean).join('\n')) };
+}
+
+/** The sentence runUpgrade fails with; its "migrate failed" prefix is what upgrade-outcome.js keys on. PURE. */
+function migrateError(mig) {
+  return `migrate failed (${mig.reason || `exit ${mig.code}`})${mig.detail || ''}`;
+}
+
+module.exports = { migratePlan, preflightDbIdentity, asAccount, ACCOUNT_RE, CORE_MIGRATE_SCRIPT, teeSpawn, migrateFailureDetail, migrateResult, migrateError };

package/scripts/bongos/upgrade-operator.js

@@ -0,0 +1,73 @@
+// scripts/bongos/upgrade-operator.js — "who upgrades this project?" for `bongos upgrade`
+// run from a builder's own computer (task 1004596).
+//
+// A hosted project (its Settings → Software update button leads to the hub — door kind
+// 'hub', see src/bongos/routes/core-update.js updateDoor) lives on its operator's server.
+// Its builders work from a laptop checkout that has no database and no server access. Run
+// there, `bongos upgrade` used to say only "cannot determine which database to migrate.
+// Set PGDATABASE…" — and an assistant reading that, plus the release recipe, wrote the
+// builder server steps full of guessed names for a machine they cannot reach. This module
+// replaces that dead end with the one supported path: the operator upgrades it, and here
+// is how to ask.
+//
+// THE CONDITION, and why it cannot touch the real operator path: BOTH must hold —
+//   1. no database is known in this checkout (no PGDATABASE, no db.database in the
+//      branding pack). On the server a database is always known, or upgrade.js already
+//      refuses there; so the server never reaches step 2.
+//   2. the project, asked through this builder's own CLI session, says its update door is
+//      the hub's. No session, no answer, an older core, a self-hosted or provisioning
+//      instance → no message, and upgrade.js behaves exactly as before.
+
+// Ask the project (via this builder's CLI session) where its Update button leads.
+// Returns { kind, url, hall } or null on ANY failure — a missing answer is never a verdict.
+async function readUpdateDoor({ timeoutMs = 5000 } = {}) {
+  try {
+    const { readSessionToken, dispatchedFetch, noKeepAliveDispatcher, CLI_USER_AGENT, hallBase } = require('./cli-lib');
+    const session = readSessionToken();
+    if (!session) return null;
+    const res = await dispatchedFetch(`${session.apiBase}/api/bongos/software-update`, {
+      headers: { Authorization: `Bearer ${session.token}`, 'User-Agent': CLI_USER_AGENT },
+      signal: AbortSignal.timeout(timeoutMs),
+      dispatcher: noKeepAliveDispatcher(),
+    });
+    if (!res.ok) return null;
+    const body = await res.json();
+    const door = body && body.door;
+    if (!door || typeof door.kind !== 'string') return null;
+    return { kind: door.kind, url: door.url || null, hall: hallBase(session.apiBase) };
+  } catch { return null; }
+}
+
+// The door when the operator runs this project and this checkout is not where it runs;
+// null otherwise (including whenever the answer cannot be read).
+async function operatorRunsThisProject({ instanceDir }, deps = {}) {
+  const { db } = (deps.resolveInstanceDb || require('./upgrade').resolveInstanceDb)({ instanceDir }, deps.run);
+  if (db) return null;
+  const door = await (deps.readUpdateDoor || readUpdateDoor)();
+  return door && door.kind === 'hub' ? door : null;
+}
+
+// What the builder (and any assistant reading over their shoulder) is told. Plain words,
+// one supported path, no server steps and nothing for anyone to fill in.
+function operatorRunMessage(door = {}) {
+  const settings = door.hall ? `${door.hall}/settings#software-update` : 'Settings → Software update';
+  return [
+    'This project is upgraded by its operator, not from this computer.',
+    'It runs on the operator\'s server, and nothing you run here can upgrade it.',
+    '',
+    'To ask for the upgrade:',
+    `  • Open ${settings} and use the button there.`,
+    '  • Or, from this terminal:  bongos feedback "Please upgrade this project to the latest version"',
+    '',
+    'There are no server steps for you to take. An assistant should not write any, or guess',
+    'server, database or service names for this project — pass the request on instead.',
+  ].join('\n') + '\n';
+}
+
+// The message to show, or null — what `bongos upgrade` (upgrade.js main) asks before anything else.
+async function operatorNotice({ instanceDir }, deps = {}) {
+  const door = await operatorRunsThisProject({ instanceDir }, deps);
+  return door ? operatorRunMessage(door) : null;
+}
+
+module.exports = { readUpdateDoor, operatorRunsThisProject, operatorRunMessage, operatorNotice };

package/scripts/bongos/upgrade-outcome.js

@@ -0,0 +1,174 @@
+'use strict';
+//
+// scripts/bongos/upgrade-outcome.js — what a failed core move actually WAS, as a class and a
+// reason code the deploy runner can act on (task 1004446, goal 1000090 deploy self-heal).
+//
+// WHY. Every non-zero exit from `bongos upgrade` reached the owner as "failed and was rolled
+// back", including the refusals that fire BEFORE the pin moves (a dirty tree, the artist
+// gate, a downgrade, the database identity check) — nothing was changed, so nothing was
+// rolled back. And a rollback that itself failed ("manual intervention needed") read exactly
+// like one that worked. The runner could not tell a wait-and-retry from a decision only the
+// owner can make from an outage, so it treated all of them the same: retry, then give up.
+//
+// TWO HALVES, ONE FILE, so the words cannot drift apart:
+//   • upgrade.js ends a failed run with ONE machine-readable stderr line (outcomeLine) saying
+//     how far it got: refused (nothing moved) · rolled_back (moved, restored) ·
+//     rollback_failed (moved, NOT restored). The runner invokes upgrade.js from its own
+//     checkout, so the two halves are always the same version.
+//   • the runner reads it back (parseOutcomeLine) and classifies (classifyFailure).
+//
+// THE FOUR CLASSES the rest of the self-heal chain keys on:
+//   transient       — try again later and it may simply work (registry blip, not published yet)
+//   known_wedge     — a known snag with a known fix the runner applies itself, once (wedge-remedy.js)
+//   needs_decision  — a rule the owner set is refusing it; only the owner can change that
+//   unknown         — anything else, and every rollback that failed; a person should look
+//
+// PURE: no I/O, no requires. Reason codes are a fixed vocabulary — never builder text — so
+// they are safe to store, index and show.
+
+const OUTCOME_TAG = 'BONGOS_UPGRADE_OUTCOME';
+const STAGES = Object.freeze(['refused', 'rolled_back', 'rollback_failed']);
+const FAILURE_CLASSES = Object.freeze(['transient', 'known_wedge', 'needs_decision', 'unknown']);
+
+// reason → class. Anything not listed is `unknown`, which is the safe direction: an unknown
+// failure reaches a person; a mislabelled one could be retried or "healed" wrongly.
+const REASON_CLASS = Object.freeze({
+  // the runner's own refusals (provision-core-upgrade.js)
+  registry_unreadable: 'transient',
+  not_published: 'transient',
+  outside_channel: 'needs_decision',
+  shape_not_automated: 'needs_decision',
+  no_target: 'unknown',
+  bad_slug: 'unknown',
+  installed_unreadable: 'unknown',
+  served_mismatch: 'unknown',
+  schema_pending: 'known_wedge', // the database is behind the code it runs NOW (task 1004448)
+  // upgrade.js refusals, before the pin moves
+  dirty_tree: 'known_wedge',
+  // git REFUSED to read the checkout, so nothing is known about the tree (task 1004512).
+  // Deliberately NOT known_wedge: the dirty_tree remedy commits whatever git reports, and
+  // here git reported nothing — the live shape is `detected dubious ownership`, a tree that
+  // was never dirty. The fix is which ACCOUNT the move runs as, which no remedy can apply.
+  git_unreadable: 'unknown',
+  downgrade: 'needs_decision',
+  artist_gate: 'needs_decision',
+  module_incompatible: 'needs_decision',
+  already_on: 'unknown',
+  db_unresolvable: 'unknown',
+  db_identity: 'unknown',
+  health_url_missing: 'unknown',
+  core_source: 'unknown',
+  // after the pin moved (rolled back)
+  disk_full: 'known_wedge',
+  npm_install: 'transient',
+  integrity_pin: 'unknown',
+  migrate: 'unknown',
+  // a migration's CHECK constraint is broken by rows the project already has (task 1004734): a
+  // retry fails identically and no remedy may rewrite the owner's data, so a person decides.
+  migrate_check_violation: 'unknown',
+  // a migration ALTERs an object the project's own account does not OWN — the tables were made
+  // by postgres at provisioning (task 1004735). Known fix: hand them over (wedge-remedy.js).
+  migrate_not_owner: 'known_wedge',
+  restart: 'unknown',
+  health: 'unknown',
+  // the runner's one automatic fix did not clear it, or itself failed (task 1004448)
+  remedy_did_not_hold: 'unknown',
+  remedy_failed: 'unknown',
+  // the one that must never be retried unattended
+  rollback_failed: 'unknown',
+});
+
+// upgrade.js error text → reason. Ordered; first match wins. Each pattern is the PREFIX of
+// a message upgrade.js builds itself (runUpgrade), so these track that file, not the world.
+const UPGRADE_REASONS = [
+  [/no space left on device|ENOSPC/i, 'disk_full'],
+  [/^refusing to DOWNGRADE/, 'downgrade'],
+  [/^already on /, 'already_on'],
+  [/^git could not read the working tree/, 'git_unreadable'],
+  [/^working tree not clean/, 'dirty_tree'],
+  [/^module pre-check failed/, 'module_incompatible'],
+  [/^cannot determine which database/, 'db_unresolvable'],
+  [/^post-restart health check is mandatory/, 'health_url_missing'],
+  [/^(--registry and --from|--from tarball not found|no core tarball at)/, 'core_source'],
+  [/^npm install failed/, 'npm_install'],
+  [/^integrity pin/, 'integrity_pin'],
+  [/^migrate failed .*\bERROR: .*check constraint/, 'migrate_check_violation'], // upgrade-migrate.js migrateError (task 1004734)
+  [/^migrate failed .*\bmust be owner of /, 'migrate_not_owner'], // Postgres' own wording (task 1004735)
+  [/^migrate failed/, 'migrate'],
+  [/^restart failed/, 'restart'],
+  [/^(health check failed after restart|served core version did not change)/, 'health'],
+];
+
+/** The reason code for an upgrade.js failure result (runUpgrade's `{ ok:false, … }`). PURE. */
+function upgradeReason(res) {
+  if (!res) return 'unknown';
+  if (res.downgrade) return 'downgrade';
+  if (res.artistGate) return 'artist_gate';
+  const text = String(res.error || '');
+  for (const [re, reason] of UPGRADE_REASONS) if (re.test(text)) return reason;
+  // A database-identity refusal carries preflightDbIdentity's own reason, which has no
+  // fixed prefix; it is the only pre-pin refusal left that names the database.
+  if (!res.rolledBack && /database|PGDATABASE/i.test(text)) return 'db_identity';
+  return 'unknown';
+}
+
+/** How far a failed run got. A rollback counts as failed if ANY of its steps did. PURE. */
+function upgradeStage(res) {
+  if (!res || !res.rolledBack) return 'refused';
+  const rb = res.rollback || {};
+  const broken = rb.restoreOk === false || rb.reinstallOk === false || rb.restartOk === false || rb.healthOk === false;
+  return broken ? 'rollback_failed' : 'rolled_back';
+}
+
+/** The single stderr line upgrade.js ends a failed run with. PURE. */
+function outcomeLine(res) {
+  const stage = upgradeStage(res);
+  const reason = stage === 'rollback_failed' ? 'rollback_failed' : upgradeReason(res);
+  return `${OUTCOME_TAG} ${JSON.stringify({ stage, reason })}\n`;
+}
+
+/** Read the outcome line back out of captured output, or null if there is none. PURE. */
+function parseOutcomeLine(text) {
+  const lines = String(text || '').split(/\r?\n/).filter((l) => l.startsWith(`${OUTCOME_TAG} `));
+  if (!lines.length) return null;
+  try {
+    const o = JSON.parse(lines[lines.length - 1].slice(OUTCOME_TAG.length + 1));
+    if (!STAGES.includes(o.stage) || typeof o.reason !== 'string' || !/^[a-z_]{1,40}$/.test(o.reason)) return null;
+    return { stage: o.stage, reason: o.reason };
+  } catch { return null; }
+}
+
+/** `{ class, reason }` for a reason code; an unlisted code is `unknown`. PURE. */
+function classifyFailure(reason) {
+  const r = typeof reason === 'string' && Object.prototype.hasOwnProperty.call(REASON_CLASS, reason) ? reason : 'unknown';
+  return { class: REASON_CLASS[r] || 'unknown', reason: r };
+}
+
+/** The runner's own refusals (targetFault's sentences) → reason code. PURE. */
+function runnerReason(text) {
+  const s = String(text || '');
+  if (/^could not read the published core versions/.test(s)) return 'registry_unreadable';
+  if (/is not published yet/.test(s)) return 'not_published';
+  if (/could not read the core version installed/.test(s)) return 'installed_unreadable';
+  if (/is older than the core this project already runs/.test(s)) return 'downgrade';
+  if (/update channel/.test(s)) return 'outside_channel';
+  return 'unknown';
+}
+
+/**
+ * The sentence the owner reads for a failed upgrade.js run. Says what actually happened,
+ * never more: "rolled back" only when a rollback ran and finished. PURE.
+ */
+function describeUpgradeFailure(to, outcome, detail) {
+  const d = String(detail || '').trim();
+  const tail = d ? `: ${d}` : '';
+  if (!outcome) return `core upgrade to ${to} failed, and the upgrade did not report how far it got — check the project before retrying${tail}`;
+  if (outcome.stage === 'refused') return `core upgrade to ${to} was refused before anything changed — the project is still on its previous core${tail}`;
+  if (outcome.stage === 'rolled_back') return `core upgrade to ${to} failed and was rolled back — the project is back on its previous core${tail}`;
+  return `core upgrade to ${to} failed AND the rollback did not finish — the project may be down or on a half-installed core, and needs a person${tail}`;
+}
+
+module.exports = {
+  OUTCOME_TAG, STAGES, FAILURE_CLASSES, REASON_CLASS,
+  upgradeReason, upgradeStage, outcomeLine, parseOutcomeLine, classifyFailure, runnerReason, describeUpgradeFailure,
+};