@bongos/core 1.21.175 → 1.21.176

package/scripts/gds/upgrade.js

@@ -1,1499 +1,7 @@
 #!/usr/bin/env node
+// scripts/gds/upgrade.js — @bongos-forwarder (task 1004848). Generated by
+// scripts/bongos/codemod-rename-scripts-gds.js; do not edit.
+// The real script is scripts/bongos/upgrade.js. This forwarder keeps callers that still name
+// the old path working, and warns once so they get repointed. Task 1003706 removes it.
 'use strict';
-// scripts/gds/upgrade.js — the `bongos upgrade` update-consumption channel (ADR 0100 §2, task 1690).
-//
-// Turns the former stub (which only ran a module-vs-core compatibility PRE-CHECK) into the real
-// channel a two-repo consumer uses to pull the Cloud Bongos core from version N to N+1:
-//
-//   pre-flight   clean git tree + module-compat vs the TARGET core version + the artist gate (ADR 0241)
-//     → bump pin   vendor the new core .tgz, rewrite the package.json `file:` dependency
-//     → npm install  node_modules/@bongos/core becomes the new version
-//     → migrate      `npm run migrate` (no such script: the core's migrate.sh itself, upgrade-migrate.js) applies additive `core_*` migrations
-//     → materialize  refresh .claude/ skills+settings+hooks from the new core (claude-materialize / W3)
-//     → restart      restart the instance's service so the new core is live
-//     → verify       installed package version == target (+ optional /healthz + ledger row)
-//
-// SCOPE (ADR 0100 §2, reshaped by ADR 0103 §4): first built for emersonian-circles (task 1917), an
-// npm-dependency instance pinning "@bongos/core": "file:vendor/bongos-core-<ver>.tgz" with
-// `start`/`migrate` npm scripts and a materialized .claude/; the registry source (ADR 0134) and
-// auto-rollback (task 2149) came later, with the consumers that needed them.
-//
-// Runs from the consumer instance root (default) or `--instance <dir>`. This script ships IN the core
-// package, so once a consumer is on core vN+1 its own `bongos upgrade` is this code. The FIRST bump
-// (before vN+1 is installed) is driven by running THIS file out of the new version's staged tree
-// against `--instance <consumer>` — see docs/recipes for the bootstrap note.
-
-const fs = require('node:fs');
-const os = require('node:os');
-const path = require('node:path');
-const crypto = require('node:crypto');
-const { spawnSync } = require('node:child_process');
-const { arg, hasFlag } = require('./cli-lib');
-const { parseSemver, compareSemver, isStable, listAvailableVersions, npmSpawnOpts } = require('./update-channel');
-const { checkArtistGate } = require('./upgrade-artist-gate');
-// The database side of a move: which command migrates, as which account, and whether that
-// account can reach the database (tasks 1004274, 1002712, 1004512).
-const { preflightDbIdentity, asAccount, ACCOUNT_RE, teeSpawn, migrateResult, migrateError } = require('./upgrade-migrate');
-
-const CORE_PKG = '@bongos/core';
-const ARTIFACT = 'bongos-core';
-// WHERE THE VENDORED TARBALL SITS, as a package.json `file:` specifier — and the reason
-// this is not a path.join(). The same string is spent two ways: it is joined onto an
-// absolute dir for an fs check (path.join normalises a forward slash on every platform,
-// so that direction is free), and it is WRITTEN INTO package.json as `file:<vendorRel>`.
-// npm specifiers are POSIX. A path.join() here emits `file:vendor\\bongos-core-x.y.z.tgz`
-// on a Windows builder's machine, and that pin is then COMMITTED to the instance repo —
-// where the provisioner runs `npm ci` on Linux and reads a literal backslash in the
-// filename. One copy, POSIX by construction, so a scaffold cannot be platform-stamped
-// by the box that happened to run the scaffolder (task 1003839).
-function vendorRelFor(version) { return path.posix.join('vendor', `${ARTIFACT}-${version}.tgz`); }
-
-// ---- pure helpers (no I/O side effects beyond the injected fs) --------------
-
-// The pin a consumer carries is the vendored-tarball version in its `file:` dependency — there is no
-// separate pin file for this consumer shape. Extract the version from either the dep string or the
-// installed package.
-function versionFromTgzPath(p) {
-  const m = String(p || '').match(new RegExp(`${ARTIFACT}-(\\d+\\.\\d+\\.\\d+[^/]*)\\.tgz$`));
-  return m ? m[1] : null;
-}
-
-// The version from a REGISTRY dep spec — a bare semver, optionally range-prefixed
-// (`1.17.0`, `^1.17.0`, `~1.17.0`). Returns null for a `file:` tarball spec (that's
-// versionFromTgzPath's job) so the two never both match. ADR 0134 (task 2090).
-function versionFromDep(dep) {
-  const s = String(dep || '').trim();
-  if (!s || /^file:/.test(s)) return null;
-  const m = s.match(/^[\^~>=<\s]*v?(\d+\.\d+\.\d+[A-Za-z0-9.+-]*)$/);
-  return m ? m[1] : null;
-}
-
-function readJson(file, fsImpl = fs) {
-  try { return JSON.parse(fsImpl.readFileSync(file, 'utf8')); } catch { return null; }
-}
-
-// The version currently installed under node_modules — the authoritative "from".
-function readInstalledCoreVersion(instanceDir, fsImpl = fs) {
-  const pkg = readJson(path.join(instanceDir, 'node_modules', CORE_PKG, 'package.json'), fsImpl);
-  return pkg && pkg.version ? pkg.version : null;
-}
-
-// The version the consumer's package.json currently pins — from either the `file:`
-// tarball path (vendored) or a bare registry semver (ADR 0134). A best-effort "from"
-// hint; readInstalledCoreVersion (node_modules) is the authoritative source.
-function readPinnedCoreVersion(instanceDir, fsImpl = fs) {
-  const pkg = readJson(path.join(instanceDir, 'package.json'), fsImpl);
-  const dep = pkg && ((pkg.dependencies || {})[CORE_PKG] || (pkg.devDependencies || {})[CORE_PKG]);
-  return versionFromTgzPath(dep) || versionFromDep(dep);
-}
-
-// Rewrite the consumer package.json to pin `file:<vendorRel>`. Returns the previous dep string.
-function writePin(instanceDir, vendorRel, fsImpl = fs) {
-  const pkgPath = path.join(instanceDir, 'package.json');
-  const pkg = readJson(pkgPath, fsImpl);
-  if (!pkg) throw new Error(`no readable package.json at ${pkgPath}`);
-  pkg.dependencies = pkg.dependencies || {};
-  const prev = pkg.dependencies[CORE_PKG];
-  pkg.dependencies[CORE_PKG] = `file:${vendorRel}`;
-  fsImpl.writeFileSync(pkgPath, JSON.stringify(pkg, null, 2) + '\n');
-  return prev;
-}
-
-// Rewrite the consumer package.json to pin an EXACT registry version: the registry sibling
-// of writePin. `npm install` then resolves @bongos/core@version from the public registry —
-// no credential, since the package is public (task 1003872). Returns the previous dep string.
-function writeRegistryPin(instanceDir, version, fsImpl = fs) {
-  const pkgPath = path.join(instanceDir, 'package.json');
-  const pkg = readJson(pkgPath, fsImpl);
-  if (!pkg) throw new Error(`no readable package.json at ${pkgPath}`);
-  pkg.dependencies = pkg.dependencies || {};
-  const prev = pkg.dependencies[CORE_PKG];
-  pkg.dependencies[CORE_PKG] = version;
-  fsImpl.writeFileSync(pkgPath, JSON.stringify(pkg, null, 2) + '\n');
-  return prev;
-}
-
-// Restore the consumer package.json's @bongos/core pin to an EXACT previous dep string,
-// VERBATIM — whether that was a `file:` tarball path (vendored) or a bare registry semver.
-// The inverse of writePin/writeRegistryPin used by the auto-rollback path (task 2149), which
-// snapshots the returned prev-dep before the bump. Returns the dep string it overwrote.
-function restorePin(instanceDir, depString, fsImpl = fs) {
-  const pkgPath = path.join(instanceDir, 'package.json');
-  const pkg = readJson(pkgPath, fsImpl);
-  if (!pkg) throw new Error(`no readable package.json at ${pkgPath}`);
-  pkg.dependencies = pkg.dependencies || {};
-  const prev = pkg.dependencies[CORE_PKG];
-  pkg.dependencies[CORE_PKG] = depString;
-  fsImpl.writeFileSync(pkgPath, JSON.stringify(pkg, null, 2) + '\n');
-  return prev;
-}
-
-// ---- steps (each injectable for tests) --------------------------------------
-
-// `ignore` is waived (it comes from — and is argued for in — claude-materialize.js materializeWillRewrite, task 1004122); every OTHER dirty path still halts the bump. -uall (task 1004188): a bare status collapses a NEW untracked dir to one '?? dir/' entry the file-path waiver never matches.
-function gitTreeClean(instanceDir, run = spawnSync, ignore = []) {
-  const r = run('git', ['status', '--porcelain', '-uall'], { cwd: instanceDir, encoding: 'utf8' });
-  // git's OWN words, not a guess at them (task 1004512). `not a git repo?` was the only
-  // explanation ever offered, and the failure that actually happens in the field is
-  // `detected dubious ownership` — a repo git can see perfectly well and refuses to read
-  // for the account asking. Swallowing the reason is what let that read as dirt.
-  if (!r || r.error || r.status !== 0) {
-    const said = String((r && (r.stderr || r.stdout)) || (r && r.error && r.error.message) || '').trim().split('\n').slice(0, 4).join('\n');
-    return { ok: false, reason: said || 'git status failed (not a git repo?)' };
-  }
-  const skip = new Set(ignore), all = (r.stdout || '').split('\n').filter((l) => l.trim());
-  const kept = all.filter((l) => !skip.has(l.slice(3).trim()));
-  return { ok: !kept.length, dirty: kept.join('\n'), ignored: all.length - kept.length };
-}
-
-// ---- persisting the pin (task 1002712) --------------------------------------
-//
-// THE BUG THIS EXISTS FOR. `bongos upgrade` rewrites package.json +
-// package-lock.json in the instance WORKING TREE and stops there. On a
-// pull-deploy instance that is not durable, and the way it fails is silent:
-//
-//   deploy.sh short-circuits while HEAD == origin/main, so a freshly-upgraded
-//   (but uncommitted) tree survives — health-green, ledger-recorded, apparently
-//   done. Then ANY later push to the instance repo moves origin/main, deploy.sh
-//   runs `git reset --hard origin/main`, and the pin reverts to whatever is
-//   COMMITTED. The lockfile hash changes with it, which trips deploy.sh's
-//   `npm ci`, which reinstalls the OLD core. Nothing errors, at any point.
-//
-// cloudbongos.com sat on 1.19.56 for thirteen releases exactly this way: the
-// core_upgrades ledger holds two successful `auto-subscription (patch)` rows
-// (1.19.56→1.19.60, 1.19.60→1.19.62) whose result no longer existed.
-//
-// The pin is REPO state, so the repo of record is the right place for it —
-// deploy.sh treating origin/main as authoritative is correct, not the bug.
-// Hence: --commit-pin lands it, and its absence WARNS rather than staying quiet.
-const PIN_FILES = ['package.json', 'package-lock.json'];
-
-// The tracked files regenerateApiArtifacts' generators rewrite WHOLE, by generator (task
-// 1003926). Committing only the pin left these dirty, so the NEXT `bongos upgrade` refused
-// its clean-tree pre-flight. They are generated end to end, so once a generator has run
-// their content is its output whatever they held before: committing them can never carry
-// an owner's edit. tests/upgrade_persist_pin.mjs pins this list against both generators.
-const API_ARTIFACT_FILES = {
-  'gen-api-docs.js': ['docs/api/openapi.json', 'docs/api-reference.md', 'docs/routes-permissions.md'],
-  'gen-api-client.js': ['index.mjs', 'index.cjs', 'bongos-client.global.js', 'index.d.ts', 'package.json', 'README.md']
-    .map((f) => `clients/bongos-client/${f}`),
-};
-
-function gitCurrentBranch(instanceDir, run = spawnSync) {
-  const r = run('git', ['rev-parse', '--abbrev-ref', 'HEAD'], { cwd: instanceDir, encoding: 'utf8' });
-  if (!r || r.error || r.status !== 0) return null;
-  const b = (r.stdout || '').trim();
-  return b && b !== 'HEAD' ? b : null;
-}
-
-// Which of `paths` git currently reports as changed — never a path it was not asked about,
-// and no git call for an empty list (a pathspec of nothing is the whole tree).
-function dirtyPaths(instanceDir, paths, run = spawnSync) {
-  if (!paths.length) return [];
-  const r = run('git', ['status', '--porcelain', '--', ...paths], { cwd: instanceDir, encoding: 'utf8' });
-  if (!r || r.error || r.status !== 0) return null; // not a git repo — nothing to persist
-  return (r.stdout || '').split('\n').map((l) => l.slice(3).trim()).filter((p) => paths.includes(p));
-}
-
-function dirtyPinFiles(instanceDir, run = spawnSync) { return dirtyPaths(instanceDir, PIN_FILES, run); }
-
-// ---- which credential the pin push rides (task 1003081, ADR 0176 follow-up) ----
-//
-// THE BUG THIS EXISTS FOR. A PRIVATE standalone instance's `origin` authenticates with
-// a per-repo deploy key that GitHub registers READ-ONLY (ADR 0176): it can pull, never
-// push. The push leg below went `git push origin HEAD:main` regardless, so on such an
-// instance GitHub refused the pin push, the bump was not durable, and the next
-// pull-deploy `git reset --hard origin/main` + `npm ci` reinstalled the OLD core
-// against an already-migrated DB — the exact silent rollback task 1002712 closed for
-// every other path, back through a warning line nobody read. The scaffold push and the
-// re-provision pin refresh already prefer the owner's stored `repo`-scoped OAuth token
-// over the SSH origin (provision.js resolveOwnerGithubToken + buildCorePinRefreshCommit);
-// the pin push now has the same preference — the token when one is stored, the git
-// remote otherwise — and a refused push is LOUD, naming the read-only key and the fix.
-
-// The GitHub owner/name behind `remote`, or null when the remote is not a GitHub
-// repository (there is nothing to push a GitHub token at) or cannot be read. Accepts
-// the plain github.com forms and every SSH alias instanceRepoRemotes wires
-// (`git@github-deploy:owner/repo.git`) — never another host, so a stored token is
-// never pointed at github.com/<owner>/<repo> for a repo that lives elsewhere.
-function remoteGithubRepo(instanceDir, remote = 'origin', run = spawnSync) {
-  const r = run('git', ['remote', 'get-url', remote], { cwd: instanceDir, encoding: 'utf8' });
-  if (!r || r.error || r.status !== 0) return null;
-  const url = String(r.stdout || '').trim();
-  let auth;
-  try { auth = require('./provision-repo-auth'); } catch { return null; } // a package without the provisioner has no token path
-  const repo = auth.parseTargetRef(url);
-  if (!repo) return null;
-  const host = (url.match(/^(?:[a-z+]+:\/\/)?(?:[^@/]+@)?([^/:]+)[/:]/i) || [])[1] || '';
-  if (host.toLowerCase() !== 'github.com' && !auth.instanceRepoRemotes(repo).includes(url)) return null;
-  return repo;
-}
-
-// The deploy key `remote` authenticates with when the checkout is wired the ADR 0176
-// way (`core.sshCommand … -i <key>` in the repo's own config); null when it is not.
-// What a refused origin push is diagnosed against — GitHub's SSH refusal is a terse
-// one-liner that names no key.
-function pinnedDeployKey(instanceDir, run = spawnSync) {
-  const r = run('git', ['config', '--get', 'core.sshCommand'], { cwd: instanceDir, encoding: 'utf8' });
-  if (!r || r.error || r.status !== 0) return null;
-  const m = String(r.stdout || '').match(/(?:^|\s)-i\s+(\S+)/);
-  return m ? m[1] : null;
-}
-
-// Resolve { token, repo } for the pin push, or null → push via the git remote.
-//   repo  — the remote's GitHub owner/name (remoteGithubRepo);
-//   row   — provision-repo-auth lookupInstanceRow, used ONLY when its target_ref IS that
-//           repo, so another instance's credential is never spent on this checkout;
-//   token — provision-repo-auth resolveOwnerGithubToken (deps.getGithubToken / deps.db
-//           are its test seams), the same resolver the scaffold push uses.
-// Every miss is the origin path, not an error, and the token is never logged. The row
-// lookup and the token read BOTH live in the leaf rather than here because their default
-// requires are computed, and this file is inside the merge resolver's executed closure
-// with a pinned computed-require count of its own (task 1003081).
-async function resolvePinPushAuth({ instanceDir, remote = 'origin' }, deps = {}, run = spawnSync) {
-  const log = deps.log || console.log;
-  const repo = remoteGithubRepo(instanceDir, remote, run);
-  if (!repo) return null;
-  const auth = require('./provision-repo-auth');
-  const inst = await auth.lookupInstanceRow(instanceDir, deps);
-  if (!inst) { const key = pinnedDeployKey(instanceDir, run); if (key) log(auth.missingRowNote(key, remote)); return null; } // task 1004065
-  const rowRepo = auth.parseTargetRef(inst.target_ref);
-  const same = (a, b) => a && b && a.owner.toLowerCase() === b.owner.toLowerCase() && a.name.toLowerCase() === b.name.toLowerCase();
-  if (!same(rowRepo, repo)) {
-    log(`  • pin push: the provisioning row for ${path.basename(instanceDir)} names ${inst.target_ref}, not ${remote}'s ${repo.owner}/${repo.name} — its owner's token is not for this checkout; pushing via ${remote}`);
-    return null;
-  }
-  const token = await auth.resolveOwnerGithubToken(inst, { ...deps, log }, { tag: '[pin-push]' });
-  if (!token) {
-    log(`  • pin push: no owner GitHub token stored for ${repo.owner}/${repo.name} — pushing via ${remote}`);
-    return null;
-  }
-  return { token, repo };
-}
-
-// The pin push over the owner's token: a chmod-600 credential-store file in the temp
-// dir carries the secret, git reads it through `credential.helper=store`, and the file
-// is removed in `finally` whatever the push did — the token is never in argv (ps,
-// journald) and never in a log line. provision.js buildCorePinRefreshCommit's shape,
-// as argv instead of a shell string.
-function pushPinViaToken({ instanceDir, token, repo, target }, run = spawnSync) {
-  const credFile = path.join(os.tmpdir(), `bongos-gitcred-pin-${process.pid}-${crypto.randomBytes(6).toString('hex')}`);
-  try {
-    fs.writeFileSync(credFile, `https://x-access-token:${token}@github.com\n`, { mode: 0o600 });
-    return run('git', ['-c', `credential.helper=store --file=${credFile}`, 'push', `https://x-access-token@github.com/${repo.owner}/${repo.name}.git`, target], {
-      cwd: instanceDir, encoding: 'utf8',
-      env: { ...process.env, GIT_TERMINAL_PROMPT: '0' }, // a rejected credential must fail, not sit at a password prompt
-    });
-  } finally {
-    fs.rmSync(credFile, { force: true });
-  }
-}
-
-// What git said on stderr, for a refusal line — GitHub's own reason ("ERROR: The key you
-// are authenticating with has been marked as read only", "remote: Write access to
-// repository not granted") is the fact an operator wants beside the diagnosis, and it
-// is never the LAST line: git closes with its generic `fatal:`. Prefer the server's
-// line, fall back to the last one.
-function gitSaid(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})` : '';
-}
-
-// `push: false` is CO-TENANT MODE (task 1003521). The reasoning above assumes the repo
-// of record is OURS; on a provisioned instance it is the customer's own GitHub repo, so
-// pushing there is both wrong and uncredentialed. Such an instance also has no
-// pull-deploy timer, so nothing will `reset --hard` the pin away — the commit alone
-// makes it durable, and leaves the tree clean for the customer's own pulls.
-//
-// `pushAuth` ({ token, repo }, from resolvePinPushAuth) makes the push ride the owner's
-// GitHub token over HTTPS (task 1003081); null pushes via `remote`. The result carries
-// `via: 'owner-token'` on the token path and `refused` ('read-only-deploy-key' |
-// 'owner-token') with a plain-sentence `error` when GitHub turned the push away.
-// `artifactPaths` (task 1003926) are the generated files this upgrade rewrote; the ones
-// that changed are staged and committed with the pin.
-function persistPin({ instanceDir, fromVersion, toVersion, commitPin, push = true, remote = 'origin', dryRun = false, pushAuth = null, artifactPaths = [] },
-  run = spawnSync, log = console.log, err = console.error) {
-  const dirtyPins = dirtyPinFiles(instanceDir, run);
-  if (dirtyPins === null) return { applicable: false, reason: 'not a git repo' };
-  const dirtyArtifacts = dirtyPaths(instanceDir, artifactPaths, run) || [];
-  const dirty = [...dirtyPins, ...dirtyArtifacts];
-  if (!dirty.length) return { applicable: false, reason: 'pin files already match the repo' };
-  const toStage = [...PIN_FILES, ...dirtyArtifacts];
-
-  const branch = gitCurrentBranch(instanceDir, run);
-  const target = `HEAD:${branch || 'main'}`;
-  // Single-quote the interpolated values. Nothing here executes these strings — they
-  // are printed for a human to paste — but an unquoted branch or remote carrying shell
-  // metacharacters would misbehave once pasted, so emit them paste-safe.
-  const q = (s) => `'${String(s).replace(/'/g, `'\\''`)}'`;
-  const at = `git -C ${q(instanceDir)}`;
-
-  if (!commitPin) {
-    if (!push) {
-      // No pull-deploy of ours reaches this instance, so an uncommitted pin is untidy
-      // rather than doomed. Crying wolf here would teach an operator to ignore the
-      // warning that DOES matter on the platform instance.
-      err(`  ! pin not committed — ${dirty.join(', ')} changed in the working tree only.`);
-      err('    This target pulls from a repo that is not ours, so nothing here will revert it —');
-      err('    but the tree stays dirty until it is committed. Re-run with --commit-pin to commit it.');
-      return { applicable: true, committed: false, pushed: false, dirty, warned: true };
-    }
-    // LOUD — this is the whole point. A silent uncommitted pin is the bug.
-    err(`  ! PIN NOT COMMITTED — ${dirty.join(', ')} changed in the working tree only.`);
-    err('    On a pull-deploy instance the next push to the repo of record makes deploy.sh');
-    err(`    'git reset --hard ${remote}/${branch || 'main'}', which REVERTS this pin and lets npm ci`);
-    err(`    reinstall ${fromVersion || 'the previous core'}. Re-run with --commit-pin, or commit + push:`);
-    err(`      ${at} add ${toStage.map(q).join(' ')} && ${at} commit -m ${q(`pin @bongos/core ${toVersion}`)} && ${at} push ${q(remote)} ${q(target)}`);
-    return { applicable: true, committed: false, pushed: false, dirty, warned: true };
-  }
-
-  if (dryRun) {
-    log(push
-      ? `  [dry-run] would commit + push ${dirty.join(', ')} to ${remote}/${branch || 'main'}`
-      : `  [dry-run] would commit ${dirty.join(', ')} locally (no push — this remote is not ours)`);
-    return { applicable: true, committed: false, pushed: false, dirty, dryRun: true };
-  }
-
-  const message = `pin @bongos/core ${toVersion}${fromVersion ? ` (was ${fromVersion})` : ''}`;
-  const add = run('git', ['add', ...toStage], { cwd: instanceDir, encoding: 'utf8' });
-  if (!add || add.error || add.status !== 0) {
-    err('  ! could not stage the pin files — commit + push them by hand or the next deploy reverts this bump.');
-    return { applicable: true, committed: false, pushed: false, dirty, error: 'git add failed' };
-  }
-  const idEnv = require('./upgrade-commit-identity').commitIdentityEnv(instanceDir, run), commit = run('git', ['commit', '-m', message], { cwd: instanceDir, encoding: 'utf8', ...(idEnv ? { env: idEnv } : {}) }); // a repo naming nobody still commits (task 1004514)
-  if (!commit || commit.error || commit.status !== 0) {
-    err('  ! could not commit the pin — commit + push it by hand or the next deploy reverts this bump.');
-    return { applicable: true, committed: false, pushed: false, dirty, error: 'git commit failed' };
-  }
-  log(`  ✓ committed the pin (${dirty.join(', ')})`);
-
-  if (!push) {
-    log('  ✓ not pushed, by request — this instance\'s repo of record is not ours, and no pull-deploy of ours can revert the commit');
-    return { applicable: true, committed: true, pushed: false, dirty, pushSkipped: true };
-  }
-
-  // Committed but not pushed is still doomed: deploy.sh resets to the REMOTE. So every
-  // refusal below is LOUD (task 1003081) — the pull-deploy consequence, the diagnosis,
-  // and a by-hand push that can actually write.
-  const revert = () => err(`    The next pull-deploy 'git reset --hard ${remote}/${branch || 'main'}' + npm ci then reinstalls ${fromVersion || 'the previous core'}.`);
-
-  if (pushAuth && pushAuth.token && pushAuth.repo) {
-    const { repo } = pushAuth;
-    let pushed = null;
-    try {
-      pushed = pushPinViaToken({ instanceDir, token: pushAuth.token, repo, target }, run);
-    } catch (e) {
-      // The credential file could not even be written (an unwritable temp dir): say so
-      // and fall through to the remote — a public origin may still take it.
-      err(`  ! could not stage the owner's GitHub credential (${e && e.message}) — pushing via ${remote} instead`);
-    }
-    if (pushed && !pushed.error && pushed.status === 0) {
-      log(`  ✓ pushed the pin to ${repo.owner}/${repo.name}@${branch || 'main'} via the owner's GitHub token — a pull-deploy reset can no longer revert it`);
-      return { applicable: true, committed: true, pushed: true, dirty, via: 'owner-token' };
-    }
-    if (pushed) {
-      err(`  ! PIN NOT PUSHED — GitHub refused the push over the owner's GitHub token, so this bump is NOT durable.`);
-      err(`    The stored token could not write ${repo.owner}/${repo.name}: it may have expired (they live an hour), or`);
-      err(`    lack the \`repo\` scope (\`public_repo\` cannot write a private repository — ADR 0155).${gitSaid(pushed)}`);
-      revert();
-      err('    Fix: have the instance owner reconnect GitHub with repository access, then re-run `bongos upgrade --commit-pin`;');
-      err('    or push the commit yourself with a credential that can write:');
-      err(`      ${at} push ${q(`https://github.com/${repo.owner}/${repo.name}.git`)} ${q(target)}`);
-      return {
-        applicable: true, committed: true, pushed: false, dirty, refused: 'owner-token',
-        error: `GitHub refused the pin push over the owner's GitHub token (expired, or missing the repo scope) — the pin is committed locally but not on ${repo.owner}/${repo.name}`,
-      };
-    }
-  }
-
-  const pushed = run('git', ['push', remote, target], { cwd: instanceDir, encoding: 'utf8' });
-  if (!pushed || pushed.error || pushed.status !== 0) {
-    const key = pinnedDeployKey(instanceDir, run);
-    if (key) {
-      // A wired private instance (ADR 0176): the key can pull, never push, and no owner
-      // token was stored to push with instead — the bug this leg exists for.
-      const repo = remoteGithubRepo(instanceDir, remote, run);
-      err(`  ! PIN NOT PUSHED — GitHub refused the push to ${remote}, so this bump is NOT durable.`);
-      err(`    ${remote} authenticates with the deploy key at ${key}, which is registered READ-ONLY on the`);
-      err(`    repository (ADR 0176): it can pull, never push. No owner GitHub token was available to push with instead (none is stored, or — on a hosted project's own box — the hub's record of it is not readable from here).${gitSaid(pushed)}`);
-      revert();
-      err('    Fix: have the instance owner reconnect GitHub with repository access (that stores a short-lived repo token),');
-      err(`    then re-run \`bongos upgrade --commit-pin\` where that token is readable — the control plane, with --instance ${q(instanceDir)};`);
-      err('    or push the commit yourself with a credential that can write:');
-      err(`      ${at} push ${q(`https://github.com/${repo ? `${repo.owner}/${repo.name}` : '<owner>/<repo>'}.git`)} ${q(target)}`);
-      return {
-        applicable: true, committed: true, pushed: false, dirty, refused: 'read-only-deploy-key',
-        error: `GitHub refused the pin push: ${remote} authenticates with the read-only deploy key at ${key}, and no owner GitHub token was available to push with — the pin is committed locally but not on the remote`,
-      };
-    }
-    err(`  ! commit landed locally but the push to ${remote} FAILED — this bump is still not durable.`);
-    err(`    Push it: git -C ${instanceDir} push ${remote} ${target}`);
-    return { applicable: true, committed: true, pushed: false, dirty, error: 'git push failed' };
-  }
-  log(`  ✓ pushed the pin to ${remote}/${branch || 'main'} — a pull-deploy reset can no longer revert it`);
-  return { applicable: true, committed: true, pushed: true, dirty };
-}
-
-// Copy the source .tgz (+ its side-car manifest, if present) into the consumer's vendor/ dir under the
-// canonical name. Returns the vendor-relative tarball path to pin.
-function vendorTarball({ instanceDir, fromTgz, targetVersion }, fsImpl = fs) {
-  const vendorDir = path.join(instanceDir, 'vendor');
-  fsImpl.mkdirSync(vendorDir, { recursive: true });
-  const destName = `${ARTIFACT}-${targetVersion}.tgz`;
-  const destAbs = path.join(vendorDir, destName);
-  fsImpl.copyFileSync(fromTgz, destAbs);
-  const fromManifest = fromTgz.replace(/\.tgz$/, '.manifest.json');
-  if (fsImpl.existsSync(fromManifest)) {
-    fsImpl.copyFileSync(fromManifest, path.join(vendorDir, `${ARTIFACT}-${targetVersion}.manifest.json`));
-  }
-  return path.posix.join('vendor', destName);
-}
-
-// Lightweight module-compat pre-check reusing module.js against the TARGET core version. Best-effort:
-// a vanilla consumer has no modules/ (trivially OK); any failure downgrades to a warning, never blocks
-// the MVP bump. Returns { ok, blocking:[], warnings:[], deprecations:[], expired:[], note }.
-//
-// WARNINGS ARE NOT OPTIONAL OUTPUT (ADR 0166 / task 1001773). This function used to return only
-// `blocking`, so a DISABLED module whose coreVersion the target no longer satisfies vanished from the
-// bump entirely. That is precisely the catalog-rot case ADR 0107 §7 names: an accepted catalog module
-// ships `default: false` (§6), so EVERY rotted catalog entry is disabled by construction and every one
-// of them was invisible here. The bump still doesn't BLOCK on them — a disabled module breaks nothing
-// at boot — but it must SAY so, with the maintainer named, or the incompatibility is discovered by
-// whoever next tries to enable it.
-function preflightModules({ instanceDir, targetVersion }, deps = {}) {
-  const empty = { blocking: [], warnings: [], deprecations: [], expired: [] };
-  const modulesDir = path.join(instanceDir, 'modules');
-  if (!fs.existsSync(modulesDir)) return { ok: true, ...empty, note: 'no modules/ — nothing to pre-check' };
-  try {
-    const mod = deps.moduleLib || require('./module');
-    const data = mod.gatherUpgrade({ modulesDir, core: targetVersion });
-    const verdict = mod.evaluateUpgrade(data);
-    const rotted = (verdict.warnings || []).length;
-    const note = !verdict.ok
-      ? 'incompatible enabled module(s)'
-      : rotted
-        ? `all enabled modules satisfy the target, but ${rotted} disabled module(s) do NOT`
-        : 'all enabled modules satisfy the target';
-    return {
-      ok: verdict.ok,
-      blocking: verdict.blocking || [],
-      warnings: verdict.warnings || [],
-      deprecations: verdict.deprecations || [],
-      expired: verdict.expired || [],
-      note,
-    };
-  } catch (e) {
-    return { ok: true, ...empty, note: `module pre-check skipped (${e.message})` };
-  }
-}
-
-// Print the non-blocking half of the module pre-check: rotted-but-disabled modules and
-// self-declared deprecations, each with its maintenance hint so the reader knows who to chase.
-// Split out of runUpgrade so it is testable without driving a whole bump.
-function reportModulePreflight(mods, targetVersion, { log = console.log, err = console.error, hint } = {}) {
-  const fmt = hint || ((row) => { try { return require('./module').formatMaintenanceHint(row); } catch { return ''; } });
-  const lines = [];
-  for (const w of mods.warnings || []) {
-    lines.push(`  ! module "${w.key}" is DISABLED here, so it does not block this bump — but its coreVersion ${w.coreVersion || '(none)'} is not satisfied by core ${targetVersion}: enabling it would silently fail to mount.`);
-    lines.push(`      ↳ ${fmt(w)}`);
-  }
-  for (const d of mods.deprecations || []) {
-    const overdue = (mods.expired || []).includes(d);
-    lines.push(`  ! module "${d.key}" is ${d.maintenance.status}${overdue ? ` and PAST its removeAfter ${d.maintenance.removeAfter} (core ${targetVersion}) — it is due for removal` : ''}.`);
-    lines.push(`      ↳ ${fmt(d)}`);
-  }
-  for (const l of lines) err(l);
-  return lines;
-}
-
-function npmInstall(instanceDir, run = spawnSync) {
-  // `npm install` (NOT `npm ci`): the pin just changed, so the lockfile must be regenerated from the
-  // new tarball; `npm ci` would refuse on the package.json↔lock divergence.
-  // This used to take an extraEnv carrying a resolved npm credential, because the instance
-  // `.npmrc`'s env expansion could shadow a valid user-level one (task 1002754). The core is
-  // public and writes no `.npmrc`, so there is no credential to resolve (task 1003878).
-  const opts = { cwd: instanceDir, stdio: 'inherit', ...npmSpawnOpts() }; // Windows: npm.cmd needs a shell (task 1004631)
-  const r = run('npm', ['install', '--no-audit', '--no-fund'], opts);
-  return !r || r.error ? { ok: false, reason: r && r.error ? r.error.message : 'spawn failed' } : { ok: r.status === 0, code: r.status };
-}
-
-async function runMigrate(instanceDir, run = spawnSync, account = null) {
-  const { cmd, args, env } = require('./upgrade-migrate').migratePlan(instanceDir); // its own migrate script, else the core's migrate.sh (task 1004274)
-  // `account`: the project's own unix+Postgres identity when the move itself is running as
-  // the account that owns the CHECKOUT instead (--migrate-as; upgrade-migrate.js, task 1004512).
-  const q = asAccount(account, cmd, args, env ? { INIT_CWD: instanceDir } : {});
-  // TEED, not inherited: still streams live, and a failure names its migration + psql's ERROR line (upgrade-migrate.js, task 1004734)
-  return migrateResult(await (run === spawnSync ? teeSpawn : run)(q.cmd, q.args, { cwd: instanceDir, ...(env ? { env } : {}) }));
-}
-
-// WHICH database will migrate target? (task 1002755)
-//
-// The pre-flight probe below is only meaningful if it tests the SAME database the migration
-// will later use. It used to be handed `process.env.PGDATABASE` — undefined on a normal box —
-// so psql fell through to a database named after the OS user, failed for an unrelated reason,
-// and soft-skipped with "psql failed for another reason". migrate then picked its own name and
-// hit a database that did not exist. Two soft failures composing into a hard one, discovered
-// only AFTER the pin had moved.
-//
-// So resolve it here, up front, by asking the core's OWN resolver in a child pointed at this
-// instance — the same precedence migrate.sh uses (PGDATABASE wins, else the instance's branding
-// pack) and the same function, so the probe and the migration cannot disagree. Spawned rather
-// than required because requiring pool.js constructs a pg Pool in this process.
-// Returns { db, ran }:
-//   { db: 'name', ran: true }  — resolved
-//   { db: null,  ran: true  }  — the resolver RAN and this instance names no database. Fatal:
-//                                migrate cannot proceed and we know it before the pin moves.
-//   { db: null,  ran: false }  — the resolver could not run at all (no node_modules yet, a
-//                                stubbed spawn in tests). NOT fatal: that is a different problem
-//                                from "no database configured", and guessing which one it is would
-//                                block bumps for the wrong reason. migrate.sh makes the same
-//                                distinction and still fails loudly later, so the net holds.
-function resolveInstanceDb({ instanceDir }, run = spawnSync) {
-  if (process.env.PGDATABASE) return { db: process.env.PGDATABASE, ran: true };
-  const poolPath = path.join(instanceDir, 'node_modules', CORE_PKG, 'src', 'bongos', 'pool');
-  // the module path rides as argv, never interpolated into JS source — a Windows-shaped path's
-  // backslashes are escape sequences inside a string literal
-  const r = run(process.execPath, ['-e', "process.stdout.write(require(process.argv[1]).instanceDbName() || '')", poolPath], {
-    cwd: instanceDir,
-    encoding: 'utf8',
-    env: { ...process.env, BONGOS_INSTANCE_ROOT: instanceDir },
-  });
-  if (!r || r.error || r.status !== 0 || typeof r.stdout !== 'string') return { db: null, ran: false };
-  return { db: String(r.stdout).trim() || null, ran: true };
-}
-
-// Regenerate the per-instance API artifacts (OpenAPI spec + api-reference + typed
-// client) from the NEW core's routes — the claude-materialize sibling (task 2051).
-// WHY: the routes + generators ship WITH core, and the generated spec/docs/client also
-// ship as CORE STARTERS (task 2078 — a fresh hall/docs must render before first regen),
-// but they are per-instance GENERATED, so a bump changes the served API while the
-// instance's committed spec/client lag until regenerated (the classification settled in
-// task 2141; init does the same at standup). We SPAWN the new core's generators (a fresh child
-// captures its output root from the env below) with <FALLBACK_PREFIX>_INSTANCE_ROOT set
-// so resolveDocsRoot() writes INTO the instance repo, not node_modules. docs first — the
-// client reads the spec it produces. Best-effort: a hiccup warns, never fails the bump
-// (fitness `gen-api-docs --check` + the api_client test backstop it on the next ship).
-// Runs AFTER npm install so the generators come from the NEW core.
-function regenerateApiArtifacts({ instanceDir, coreRoot }, run = spawnSync, fsImpl = fs) {
-  const env = { ...process.env, BONGOS_INSTANCE_ROOT: instanceDir };
-  const ran = [];
-  for (const gen of Object.keys(API_ARTIFACT_FILES)) {
-    const script = path.join(coreRoot, 'scripts', 'gds', gen);
-    if (!fsImpl.existsSync(script)) return { ok: false, ran, reason: `${gen} not found in core (${coreRoot})` };
-    const r = run(process.execPath, [script], { cwd: instanceDir, env, stdio: 'inherit' });
-    if (!r || r.error || r.status !== 0) {
-      return { ok: false, ran, reason: r && r.error ? r.error.message : `${gen} exited ${r && r.status}` };
-    }
-    ran.push(gen);
-  }
-  return { ok: true, ran };
-}
-
-// The instance's GITIGNORED WHOLE-FILE navigation docs (ADR 0110). On the monorepo these
-// regenerate at deploy (deploy-prod.sh) + box-fetch and are gitignored so no branch ever diffs
-// them. STANDALONE instances (ADR 0108) never got that step: their bespoke deploy regenerated
-// nothing and init/upgrade only did the API docs, so a fresh instance shipped with an empty docs/
-// and nothing kept the index live (task 1002314, the owner's "docs didn't transfer from primea").
-// This is the standalone sibling of deploy-prod.sh's regen: run the generator(s) against the
-// INSTANCE root, best-effort + LOUD — a broken generator must surface (::ERROR::) but must NEVER
-// fail the deploy/bump (a stale nav doc is tolerable; a failed deploy is not — ADR 0110 §2
-// "accepted staleness").
-//
-// SCOPE — deliberately just session-index (the one gitignored whole-file doc that is INSTANCE
-// content). Excluded on purpose:
-//   • repo-map.md — CORE-scoped: gen-repo-map writes to resolveCoreRoot() (the platform code map),
-//     not the instance. A pure standalone instance runs core from node_modules and has ~no code of
-//     its own to map, so an instance-level repo-map is empty/meaningless; the core ships its own.
-//     (An instance-scoped map for BROWNFIELD/adopted repos is a separate enhancement — task 1001655.)
-//   • file-map.md + API docs — TRACKED/committed (seeded at init, refreshed at ship/upgrade);
-//     regenerating them on the box would perpetually dirty the tree that deploy.sh `git reset
-//     --hard`es. file-map is also HYBRID (hand-written prose + generated sections, ADR 0110) so it
-//     cannot leave git; seeding it at standup is a follow-up (needs a scaffolded file-map.md).
-//   • diagrams + atlas.json — NOT instance content: they are CORE-scoped generated assets that
-//     live under resolveCoreRoot(). They are handled separately by healDocAssets() below, because
-//     an upgrade is precisely what destroys them (task 1002441).
-const NAV_WHOLE_FILE_GENERATORS = ['gen-session-index.js'];
-function regenerateNavDocs({ instanceDir, coreRoot, generators = NAV_WHOLE_FILE_GENERATORS }, run = spawnSync, fsImpl = fs) {
-  const env = { ...process.env, BONGOS_INSTANCE_ROOT: instanceDir };
-  const ran = [];
-  const failed = [];
-  for (const gen of generators) {
-    const script = path.join(coreRoot, 'scripts', 'gds', gen);
-    if (!fsImpl.existsSync(script)) { failed.push({ gen, reason: `not found in core (${coreRoot})` }); continue; }
-    const r = run(process.execPath, [script], { cwd: instanceDir, env, stdio: 'inherit' });
-    if (!r || r.error || r.status !== 0) {
-      // LOUD per ADR 0110 §2 — journald greps ::ERROR:: so a broken generator alarms.
-      failed.push({ gen, reason: r && r.error ? r.error.message : `exited ${r && r.status}` });
-      continue;
-    }
-    ran.push(gen);
-  }
-  return { ok: failed.length === 0, ran, failed };
-}
-
-// The CORE-scoped generated doc assets that back two builders'-hall surfaces:
-//
-//   modules/hall-ui/public/atlas.json      → the Repo Atlas   (/builders/atlas)
-//   docs/onboarding/diagrams/<n>.svg+.png  → the system maps  (/builders/diagrams)
-//
-// Both are GITIGNORED (.gitignore: `modules/hall-ui/public/atlas.json`,
-// `docs/onboarding/diagrams/*.svg|*.png` — ADR 0122 / task 1002027) and both are generated INTO
-// the vendored core root. So an upgrade DESTROYS them: npmInstall replaces node_modules wholesale
-// and the new tarball carries only the .mmd sources. Nothing else puts them back —
-//   • packaging does not render (package-core.js has no render step, and the renders are
-//     gitignored so a git checkout has none to copy), and
-//   • a standalone instance's pull-deploy typically short-circuits on an unchanged git SHA, which
-//     an upgrade does not move — so its regen hooks never fire.
-// Result before this healer: /builders/atlas 404'd and the diagrams page showed broken images
-// after every `bongos upgrade`, until some unrelated commit happened to land (task 1002441).
-//
-// Both generators resolve their own output dir from __dirname, so running the CORE's copy always
-// writes into coreRoot regardless of cwd. Idempotent by design — each asset is regenerated only
-// when actually absent, so this is also safe to call from a deploy loop.
-//
-// Best-effort + LOUD, per ADR 0110 §2 "accepted staleness": a stale diagram is tolerable, a failed
-// upgrade is not. render-diagrams.sh additionally needs a system Chromium (ADR 0122); where none is
-// installed it fails and we say so via ::ERROR:: rather than aborting the bump.
-const DOC_ASSET_GENERATORS = {
-  atlas: { rel: path.join('scripts', 'gds', 'gen-atlas.js'), kind: 'node' },
-  diagrams: { rel: path.join('scripts', 'render-diagrams.sh'), kind: 'bash' },
-};
-
-// Which of the two asset groups are missing under coreRoot. Exported for testing.
-function missingDocAssets(coreRoot, fsImpl = fs) {
-  const missing = [];
-  if (!fsImpl.existsSync(path.join(coreRoot, 'modules', 'hall-ui', 'public', 'atlas.json'))) {
-    missing.push('atlas');
-  }
-  const diagramDir = path.join(coreRoot, 'docs', 'onboarding', 'diagrams');
-  let sources = [];
-  try {
-    sources = fsImpl.readdirSync(diagramDir).filter((f) => f.endsWith('.mmd'));
-  } catch { sources = []; }  // no diagram dir in this core → nothing to render
-  const unrendered = sources.some((src) => {
-    const base = path.join(diagramDir, src.replace(/\.mmd$/, ''));
-    return !fsImpl.existsSync(`${base}.svg`) || !fsImpl.existsSync(`${base}.png`);
-  });
-  if (unrendered) missing.push('diagrams');
-  return missing;
-}
-
-function healDocAssets({ coreRoot }, run = spawnSync, fsImpl = fs) {
-  const missing = missingDocAssets(coreRoot, fsImpl);
-  if (missing.length === 0) return { ok: true, ran: [], failed: [], missing: [] };
-  const ran = [];
-  const failed = [];
-  for (const group of missing) {
-    const gen = DOC_ASSET_GENERATORS[group];
-    const script = path.join(coreRoot, gen.rel);
-    if (!fsImpl.existsSync(script)) { failed.push({ group, reason: `not found in core (${gen.rel})` }); continue; }
-    const argv = gen.kind === 'bash' ? ['bash', [script]] : [process.execPath, [script]];
-    const r = run(argv[0], argv[1], { cwd: coreRoot, stdio: 'inherit' });
-    if (!r || r.error || r.status !== 0) {
-      failed.push({ group, reason: r && r.error ? r.error.message : `exited ${r && r.status}` });
-      continue;
-    }
-    ran.push(group);
-  }
-  return { ok: failed.length === 0, ran, failed, missing };
-}
-
-// Restart the instance service so the newly-installed core becomes the one being SERVED.
-// Escalation is the whole difficulty here (task 1002884). A provisioned instance runs under a
-// `User=` systemd unit, and the unattended sweep that restarts it has no TTY — so a bare
-// `systemctl restart` from the owning (non-root) user returns "Interactive authentication
-// required" and exits 1. We retry once through `sudo -n`, the same idiom dev.js and dev-lib.js
-// already use for privileged systemctl; `-n` fails fast rather than blocking on a password
-// prompt, so the retry costs nothing when it isn't permitted. An operator who prefers polkit
-// over sudo can install the rule in docs/recipes/instance-service-restart.md instead — either
-// path makes this return ok.
-// `--restart-cmd` is NOT escalated: an explicit command is the operator's own contract.
-// Trust boundary: `service` comes from `--service` or the subscription roster — operator-supplied
-// config, never request input — and the escalation reaches only as far as the host's own sudoers
-// or polkit scoping allows. Do not wire a caller that derives `service` from anything untrusted.
-function restartService({ service, restartCmd }, run = spawnSync, deps = {}) {
-  if (restartCmd) {
-    const parts = restartCmd.split(/\s+/);
-    const r = run(parts[0], parts.slice(1), { stdio: 'inherit' });
-    return { ok: !!r && !r.error && r.status === 0, code: r && r.status };
-  }
-  if (service) {
-    const r = run('systemctl', ['restart', service], { stdio: 'inherit' });
-    if (r && !r.error && r.status === 0) return { ok: true, code: 0 };
-    const isRoot = deps.isRoot !== undefined
-      ? !!deps.isRoot
-      : (typeof process.getuid === 'function' && process.getuid() === 0);
-    if (isRoot) return { ok: false, code: r && r.status };
-    const s = run('sudo', ['-n', 'systemctl', 'restart', service], { stdio: 'inherit' });
-    const ok = !!s && !s.error && s.status === 0;
-    return { ok, code: ok ? 0 : (s && s.status), triedSudo: true, directCode: r && r.status };
-  }
-  return { ok: null, skipped: true };
-}
-
-// The two attribution columns migration core_241 adds (task 1003159, ADR 0293 D5).
-//
-// APPENDED ONLY WHEN THE CALLER SUPPLIES THEM, and that conditionality is the whole
-// design rather than laziness. An upgrade run the old way — a human at a shell — has
-// no builder to attribute, and this file also runs ON instances whose DB may not have
-// core_241 yet (the core upgrades itself; the migration lands during the very run that
-// would be writing this row). Naming a column that does not exist turns a best-effort
-// ledger append into a hard `column "source" does not exist`, so the bump would report
-// a failure over bookkeeping. Absent → the original four-column INSERT, byte for byte.
-//
-// The DB is still the backstop: core_upgrades_door_needs_actor_chk refuses a row that
-// claims source='owner-control' without an actor, so a caller that passes one and not
-// the other is rejected there rather than landing an unattributable privileged row.
-const LEDGER_ACTOR_COLS = Object.freeze(['requested_by_builder_id', 'source']);
-
-// Build the INSERT for the columns this call actually has. Returns the statement plus
-// the ordered values, so the two connection paths below cannot drift apart.
-function ledgerInsert({ fromVersion, toVersion, sourceCommit, note, requestedByBuilderId, source }) {
-  const cols = ['from_version', 'to_version', 'source_commit', 'note'];
-  const vals = [fromVersion || null, toVersion, sourceCommit || null, note || null];
-  if (requestedByBuilderId != null || source) {
-    cols.push(...LEDGER_ACTOR_COLS);
-    vals.push(requestedByBuilderId != null ? String(requestedByBuilderId) : null, source || null);
-  }
-  const holders = cols.map((_, i) => `$${i + 1}`).join(',');
-  return { sql: `INSERT INTO core_upgrades (${cols.join(', ')}) VALUES (${holders})`, cols, vals };
-}
-
-// Best-effort append to the core_upgrades ledger (migration core_189). Resolves the DB the same two
-// ways a consumer might connect:
-//   • DATABASE_URL — a connection string (managed / hosted shape): via the pg driver.
-//   • PGDATABASE   — a bare db name over the unix socket + peer auth (the self-host shape): by
-//     delegating to `psql -d "$PGDATABASE"`, EXACTLY as migrate.sh does. We shell out rather than
-//     reuse pg here because pg defaults host to localhost/TCP, so `new Pool({database})` would miss
-//     the socket + peer auth a provisioned instance relies on (systemd sets only PGDATABASE — task
-//     1976 found the URL-only path silently skipped on emersonian, the very shape it must serve).
-// Skips silently only when NEITHER is present (a local rehearsal with no DB pointed at) — the bump's
-// verification never depends on the ledger. An attempted-but-failed insert returns skipped:false so
-// the caller can surface it (the manual-INSERT footgun from 1976), never lose it.
-async function recordLedger({ fromVersion, toVersion, sourceCommit, note, requestedByBuilderId, source, account = null }, deps = {}) {
-  const url = deps.databaseUrl !== undefined ? deps.databaseUrl : process.env.DATABASE_URL;
-  const database = deps.pgDatabase !== undefined ? deps.pgDatabase : process.env.PGDATABASE;
-  if (!url && !database) return { ok: false, skipped: true, reason: 'no DATABASE_URL or PGDATABASE' };
-  const stmt = ledgerInsert({ fromVersion, toVersion, sourceCommit, note, requestedByBuilderId, source });
-
-  // DATABASE_URL path: the pg driver with a bound-parameter query (no psql client needed).
-  if (url) {
-    let Pool;
-    try { ({ Pool } = deps.pg || require('pg')); } catch { return { ok: false, skipped: true, reason: 'pg not resolvable' }; }
-    const pool = new Pool({ connectionString: url });
-    try {
-      await pool.query(stmt.sql, stmt.vals);
-      return { ok: true };
-    } catch (e) {
-      return { ok: false, skipped: false, reason: e.message };
-    } finally {
-      try { await pool.end(); } catch { /* ignore */ }
-    }
-  }
-
-  // PGDATABASE path: `psql -d <db>` lets libpq resolve the socket + peer auth (same as migrate.sh).
-  // Values pass as separate argv `--set`s (no shell → no shell injection) and reach the SQL as psql
-  // :'var' literals, which psql quotes/escapes safely (no SQL injection). NULLIF maps an absent value
-  // to NULL, matching the `x || null` of the pg path. The SQL is fed on STDIN, not `-c`: `-c` requires
-  // pure server-parseable SQL and does NOT run :'var' interpolation, so a `-c` INSERT would send the
-  // literal `:'from_version'` and syntax-error — psql only interpolates variables in script/stdin
-  // mode. ON_ERROR_STOP=1 guarantees a non-zero exit on any SQL error.
-  const run = deps.run || spawnSync;
-  // Built from the SAME column list the pg path uses, so the two cannot drift.
-  // to_version is the one NOT NULL column, hence the one without a NULLIF; the
-  // builder id is text on the wire (a psql :'var' is always a quoted literal) and
-  // casts at the DB, which also rejects anything non-numeric rather than coercing.
-  const psqlValue = (col) => {
-    if (col === 'to_version') return `:'${col}'`;
-    if (col === 'requested_by_builder_id') return `NULLIF(:'${col}','')::bigint`;
-    return `NULLIF(:'${col}','')`;
-  };
-  const sql = `${stmt.sql.slice(0, stmt.sql.indexOf(' VALUES '))}\n  VALUES (${stmt.cols.map(psqlValue).join(', ')});\n`;
-  const sets = [];
-  for (let i = 0; i < stmt.cols.length; i++) sets.push('--set', `${stmt.cols[i]}=${stmt.vals[i] == null ? '' : stmt.vals[i]}`);
-  // Through the project's own account when the move is not running as it (task 1004512):
-  // this psql peer-auths exactly as migrate does, so it must be the same identity or the
-  // ledger row silently stops being written on every own-account project.
-  const q = asAccount(account, 'psql', ['-d', database, '-v', 'ON_ERROR_STOP=1', '-q', '--no-psqlrc', ...sets]);
-  const r = run(q.cmd, q.args, { encoding: 'utf8', input: sql });
-  if (!r || r.error) {
-    const enoent = !!(r && r.error && r.error.code === 'ENOENT');
-    return { ok: false, skipped: enoent, reason: enoent ? 'psql not found' : (r && r.error ? r.error.message : 'psql spawn failed') };
-  }
-  if (r.status !== 0) return { ok: false, skipped: false, reason: (r.stderr || '').trim() || `psql exit ${r.status}` };
-  return { ok: true };
-}
-
-// Poll a health URL until it returns 2xx or the time budget (~30s) elapses. After `systemctl restart`
-// the service needs a moment to bind its port, so a single immediate GET races the restart and
-// spuriously reports `fetch failed` (task 1976 — it bound ~1s later on the emersonian 1.15→1.16 bump).
-// Connection-refused fails fast, so the early retries are cheap; the backoff caps at 2s.
-async function pollHealth(healthUrl, deps = {}) {
-  const fetchImpl = deps.fetch || fetch;
-  const sleep = deps.sleep || ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
-  const now = deps.now || Date.now;
-  const budgetMs = deps.healthBudgetMs != null ? deps.healthBudgetMs : 30_000;
-  const deadline = now() + budgetMs;
-  let attempt = 0;
-  let last = { ok: false, error: 'not attempted' };
-  for (;;) {
-    attempt++;
-    try {
-      const res = await fetchImpl(healthUrl, { signal: AbortSignal.timeout(5_000) });
-      if (res.ok) return { ok: true, status: res.status, attempts: attempt };
-      last = { ok: false, status: res.status };
-    } catch (e) {
-      last = { ok: false, error: e.message };
-    }
-    if (now() >= deadline) return { ...last, attempts: attempt, timedOut: true };
-    await sleep(Math.min(2_000, 500 * attempt));
-  }
-}
-
-// ---- served-version verification (task 1002884) -----------------------------
-// The gap this closes: after a restart, `readInstalledCoreVersion` reads node_modules on DISK
-// and `pollHealth` proves only that *something* answers the port. Neither can tell "the new core
-// is up" from "the old core never went down" — so when a restart silently failed on
-// cloudbongos.com (2026-08-11), the health poll hit the STILL-RUNNING old process, got 200, and
-// the bump reported "✓ upgrade complete" while live kept serving the previous core.
-// `/version` reports the LIVE process's coreVersion (serve-internal.js, since 1.17.2), which is
-// the one signal that distinguishes the two.
-
-// Default the version endpoint to /version on the same origin as the health URL. Deriving rather
-// than demanding a second flag is deliberate: every existing call site passes only --health-url,
-// and a check that has to be opted into is off exactly where it is needed. Returns null when the
-// health URL isn't parseable as one.
-function deriveVersionUrl(healthUrl) {
-  try {
-    const u = new URL(healthUrl);
-    u.pathname = '/version';
-    u.search = '';
-    u.hash = '';
-    return u.toString();
-  } catch { return null; }
-}
-
-// Poll the version endpoint until it yields a parseable coreVersion or the budget elapses. Runs
-// AFTER the health poll, so the service is already answering and the budget is short — this is
-// re-reading a live endpoint, not waiting for a boot. A body without a usable coreVersion is
-// "unreadable", NOT a mismatch: the caller must be able to tell "it says the wrong version"
-// (a real failure) from "it wouldn't tell me" (unconfirmed), because only the first is proof.
-async function pollServedVersion(versionUrl, deps = {}) {
-  const fetchImpl = deps.fetch || fetch;
-  const sleep = deps.sleep || ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
-  const now = deps.now || Date.now;
-  // Default to the health budget when a caller (or a test) has already narrowed it, else 15s.
-  const budgetMs = deps.versionBudgetMs != null
-    ? deps.versionBudgetMs
-    : (deps.healthBudgetMs != null ? deps.healthBudgetMs : 15_000);
-  // A hard attempt cap alongside the clock: `now` is injectable, and a frozen or non-advancing
-  // clock would otherwise spin this loop forever instead of giving up.
-  const maxAttempts = deps.versionMaxAttempts != null ? deps.versionMaxAttempts : 12;
-  const deadline = now() + budgetMs;
-  let attempt = 0;
-  let last = { ok: false, error: 'not attempted' };
-  for (;;) {
-    attempt++;
-    try {
-      const res = await fetchImpl(versionUrl, { signal: AbortSignal.timeout(5_000) });
-      if (!res || !res.ok) last = { ok: false, error: `status ${res && res.status}` };
-      else if (typeof res.json !== 'function') last = { ok: false, error: 'response carried no JSON body' };
-      else {
-        const body = await res.json();
-        const version = body && typeof body.coreVersion === 'string' ? body.coreVersion : null;
-        if (version) return { ok: true, version, attempts: attempt };
-        last = { ok: false, error: 'no coreVersion in the response body' };
-      }
-    } catch (e) {
-      last = { ok: false, error: e.message };
-    }
-    if (now() >= deadline || attempt >= maxAttempts) return { ...last, attempts: attempt, timedOut: true };
-    await sleep(Math.min(2_000, 500 * attempt));
-  }
-}
-
-// ---- integrity-pin verification (task 1002216 / audit H8, finding F1) --------
-// The packager (package-core.js) computes tree_sha256 = canonicalTreeHash over the
-// redacted core files (+ the two synthesized files) and records it, the per-file
-// hashes, AND the exact tarball bytes' sha256 in a side-car manifest — stating a
-// consumer "verifies an install by recomputing it from the unpacked tree." Until now
-// nothing on the CONSUME side did: `bongos upgrade` compared only the version STRING,
-// so a corrupted / truncated / swapped tarball whose package.json still read the target
-// version installed silently — the R88-class failure this goal exists to prevent.
-// The three functions below close that gap: recompute the pin over the INSTALLED tree
-// and assert it equals the TRUSTED reference manifest.
-
-// Read + parse a manifest JSON; null on any failure (missing / unparseable).
-function readManifest(file, fsImpl = fs) {
-  try { return JSON.parse(fsImpl.readFileSync(file, 'utf8')); } catch { return null; }
-}
-
-// Resolve the trusted reference pin for this bump:
-//   • VENDORED — the committed side-car `vendor/<artifact>-<v>.manifest.json` (carries
-//     tree_sha256 + files[] + the exact tarball.sha256). It lives OUTSIDE the tarball
-//     (version-controlled in the consumer repo), so it detects a swapped/corrupted
-//     tarball. This is the strong reference.
-//   • REGISTRY / no side-car — the inner manifest `<core>/.bongos-core.json` that ships
-//     INSIDE the package (tree_sha256 + files[], no tarball.*). Self-referential (a full
-//     swap regenerates it too), so it is a self-consistency check backing npm's own
-//     registry integrity rather than an independent one — flagged `strong:false`.
-function resolveReferenceManifest({ instanceDir, coreDir, targetVersion }, fsImpl = fs) {
-  const sidecarPath = path.join(instanceDir, 'vendor', `${ARTIFACT}-${targetVersion}.manifest.json`);
-  const sidecar = readManifest(sidecarPath, fsImpl);
-  if (sidecar && sidecar.tree_sha256) {
-    const tgz = path.join(instanceDir, 'vendor', `${ARTIFACT}-${targetVersion}.tgz`);
-    return { manifest: sidecar, tgzPath: fsImpl.existsSync(tgz) ? tgz : null, source: 'vendored side-car manifest', strong: true };
-  }
-  const inner = readManifest(path.join(coreDir, '.bongos-core.json'), fsImpl);
-  if (inner && inner.tree_sha256) return { manifest: inner, tgzPath: null, source: 'installed inner manifest', strong: false };
-  return { manifest: null, tgzPath: null, source: null, strong: false };
-}
-
-// Recompute the integrity pin over the installed core tree and compare to `referenceManifest`.
-// Reuses the PACKAGER's exact hash functions (canonicalTreeHash / sha256hex) so the consume-side
-// recompute can never drift from the produce-side pin. Returns { ran, ok, checks, problems };
-// ran=false ⇒ the manifest carried no pin to check against.
-function verifyInstalledPin({ coreDir, referenceManifest, tgzPath }, deps = {}) {
-  const fsImpl = deps.fs || fs;
-  const pc = deps.packageCore || require('./package-core');
-  const checks = [];
-  const problems = [];
-  if (!referenceManifest || !referenceManifest.tree_sha256) return { ran: false, ok: false, checks, problems };
-
-  // (a) exact tarball bytes (vendored path only) — the strongest single check: the bytes
-  //     npm actually installs, hashed and compared to the externally-held pin.
-  const tb = referenceManifest.tarball;
-  if (tgzPath && tb && tb.sha256 && fsImpl.existsSync(tgzPath)) {
-    const got = pc.sha256hex(fsImpl.readFileSync(tgzPath));
-    const ok = got === tb.sha256;
-    checks.push({ name: 'tarball.sha256', ok });
-    if (!ok) problems.push(`vendored tarball bytes sha256 ${got.slice(0, 12)}… ≠ pinned ${String(tb.sha256).slice(0, 12)}…`);
-  }
-
-  // (b) installed tree — recompute each pinned file's sha256 from the unpacked tree, rebuild
-  //     the canonical tree hash (using the manifest's already-canonical modes), assert equality.
-  //     Catches partial extraction, post-install corruption, or a registry package that diverged.
-  const files = Array.isArray(referenceManifest.files) ? referenceManifest.files : [];
-  if (files.length) {
-    const recomputed = [];
-    let missing = 0, changed = 0;
-    for (const f of files) {
-      const abs = path.join(coreDir, ...String(f.path).split('/')); // POSIX manifest path → native
-      let buf;
-      try { buf = fsImpl.readFileSync(abs); } catch { missing++; problems.push(`missing installed file: ${f.path}`); continue; }
-      const sha = pc.sha256hex(buf);
-      if (sha !== f.sha256) { changed++; problems.push(`content mismatch: ${f.path}`); }
-      recomputed.push({ path: f.path, mode: f.mode, sha256: sha });
-    }
-    const treeHash = pc.canonicalTreeHash(recomputed);
-    const ok = missing === 0 && changed === 0 && treeHash === referenceManifest.tree_sha256;
-    checks.push({ name: 'tree_sha256', ok, missing, changed, file_count: files.length });
-    if (!ok && missing === 0 && changed === 0) {
-      problems.push(`recomputed tree_sha256 ${treeHash.slice(0, 12)}… ≠ pinned ${String(referenceManifest.tree_sha256).slice(0, 12)}…`);
-    }
-  }
-
-  const ran = checks.length > 0;
-  return { ran, ok: ran && problems.length === 0, checks, problems };
-}
-
-// Auto-rollback (task 2149): a bump failed AFTER the pin was moved — an install or migrate
-// error, or a failed post-restart health check. Revert the code pin to the pre-upgrade
-// snapshot, reinstall the previous core, restart, re-verify health, and record the reversal
-// in the ledger. The DB is deliberately NOT rolled back: core migrations are additive +
-// forward-safe (the core migration rule), so any already-applied migration is left in place —
-// only the code PIN moves back. Best-effort + fail-soft: every sub-step logs but never throws,
-// so a rollback attempt can't itself crash the upgrader on top of the original failure.
-async function rollback({ instanceDir, snapshot, fromVersion, toVersion, opts }, reason, deps = {}) {
-  const log = deps.log || console.log;
-  const err = deps.err || console.error;
-  const run = deps.run || spawnSync;
-  const fsImpl = deps.fs || fs;
-  const restore = deps.restorePin || restorePin;
-
-  err(`  ↩ rolling back: ${reason} — reverting ${CORE_PKG} ${toVersion} → ${snapshot.prevVersion || snapshot.prevPin}`);
-  const result = { rolledBack: true, reason, restoredPin: snapshot.prevPin, restoredVersion: snapshot.prevVersion };
-
-  // 1. revert the pin to the exact previous dep string.
-  try { restore(instanceDir, snapshot.prevPin, fsImpl); result.restoreOk = true; log(`  ✓ restored pin → ${snapshot.prevPin}`); }
-  catch (e) { result.restoreOk = false; err(`  ! could not restore pin (${e.message}) — package.json may need manual repair`); }
-
-  // 2. reinstall the previous core.
-  const inst = npmInstall(instanceDir, run);
-  result.reinstallOk = !!inst.ok;
-  if (inst.ok) log('  ✓ reinstalled previous core');
-  else err(`  ! reinstall of previous core failed (${inst.reason || 'exit ' + inst.code}) — the instance may need manual repair`);
-
-  // 3. restart back onto the previous core.
-  // `deps` is passed here for the same reason the forward path passes it: this restart runs
-  // AFTER a failure, so its sudo-escalation is the one that matters most and must be testable.
-  const rs = restartService({ service: opts.service, restartCmd: opts.restartCmd }, run, deps);
-  if (rs.skipped) log('  • restart: no --service/--restart-cmd — restart the instance service manually to load the reverted core.');
-  else if (!rs.ok) err(`  ! restart after rollback failed (exit ${rs.code}) — restart the service manually.`);
-  else log(`  ✓ restarted ${opts.service || 'service'} on the previous core`);
-  result.restartOk = rs.ok;
-
-  // 4. re-verify: installed == previous, optional health recovery.
-  const installedNow = readInstalledCoreVersion(instanceDir, fsImpl);
-  result.installedAfter = installedNow;
-  log(`  ${installedNow === snapshot.prevVersion ? '✓' : '!'} installed core after rollback: ${installedNow || '(unknown)'}`);
-  if (opts.healthUrl) {
-    const h = await pollHealth(opts.healthUrl, deps);
-    result.healthOk = h.ok;
-    if (h.ok) log(`  ✓ health recovered ${opts.healthUrl} → ${h.status}${h.attempts > 1 ? ` (after ${h.attempts} tries)` : ''}`);
-    else err(`  ! health STILL failing after rollback (${h.error || 'status ' + h.status}) — manual intervention needed`);
-  }
-
-  // 5. record the reversal in the ledger via the always-present `note` column (no schema
-  //    dependency — so it records even when a FAILED migrate means a newer column wouldn't exist).
-  const note = `rolled_back: ${reason} (attempted ${fromVersion || '(none)'} → ${toVersion}, restored ${snapshot.prevVersion || 'previous'})`;
-  const ledger = await recordLedger({ fromVersion, toVersion, sourceCommit: opts.sourceCommit, note, requestedByBuilderId: opts.requestedBy, source: opts.upgradeSource, account: opts.migrateAs || null }, deps);
-  if (ledger.ok) log('  ✓ recorded rollback in core_upgrades ledger');
-  else if (ledger.skipped) log(`  • rollback ledger skipped (${ledger.reason})`);
-  else err(`  ! rollback ledger insert failed (${ledger.reason}) — record it manually`);
-  result.ledger = ledger.ok;
-
-  err(`  ↩ rollback complete — instance restored to core ${snapshot.prevVersion || snapshot.prevPin}.`);
-  return result;
-}
-
-// ---- orchestration ----------------------------------------------------------
-
-async function runUpgrade(opts, deps = {}) {
-  const log = deps.log || console.log;
-  const err = deps.err || console.error;
-  const run = deps.run || spawnSync;
-  const fsImpl = deps.fs || fs;
-  const materialize = deps.materialize || require('./claude-materialize').materializeClaude;
-
-  const instanceDir = path.resolve(opts.instance || process.cwd());
-  const targetVersion = opts.to;
-  const dryRun = !!opts.dryRun;
-  // Auto-rollback is ON by default (task 2149); `--no-rollback-on-failure` opts out (e.g. an
-  // interactive run that wants to inspect a broken state). Programmatic callers pass false.
-  const rollbackOnFailure = opts.rollbackOnFailure !== false;
-  // Pre-upgrade snapshot { prevPin, prevVersion } — captured the instant the pin is moved, so a
-  // failure AFTER that point (install / migrate / health) can revert. null until then = nothing to undo.
-  let snapshot = null;
-  if (!targetVersion) return { ok: false, error: 'missing --to <version> (the target core version)' };
-  // Checked once, here, rather than at each of the three places it is spent: an account
-  // name that reaches `sudo` is refused outright, never quoted into shape (task 1004512).
-  if (opts.migrateAs && !ACCOUNT_RE.test(opts.migrateAs)) return { ok: false, error: `--migrate-as ${JSON.stringify(opts.migrateAs)} is not a unix account name` };
-
-  const pinnedVersion = readPinnedCoreVersion(instanceDir, fsImpl);
-  const fromVersion = readInstalledCoreVersion(instanceDir, fsImpl) || pinnedVersion;
-  const doRollback = (reason) => rollback({ instanceDir, snapshot, fromVersion, toVersion: targetVersion, opts }, reason, deps);
-  // A --to OLDER than this instance's core is refused before anything moves, --force included
-  // (task 1004009). Measured against the NEWER of installed and pinned — a half-applied bump
-  // leaves them apart. rollback() restores its own pin and never comes through here.
-  const baseline = compareSemver(pinnedVersion, fromVersion) > 0 ? pinnedVersion : fromVersion;
-  const isDowngrade = !!(parseSemver(baseline) && parseSemver(targetVersion) && compareSemver(targetVersion, baseline) < 0);
-  if (isDowngrade && !opts.allowDowngrade) {
-    const newest = listAvailableVersions({ cwd: instanceDir, run }).versions.filter(isStable).sort(compareSemver).pop();
-    return { ok: false, downgrade: true, fromVersion, toVersion: targetVersion, error: `refusing to DOWNGRADE: --to ${targetVersion} is older than this instance's core ${baseline}${pinnedVersion && pinnedVersion !== fromVersion ? ` (installed ${fromVersion}, pinned ${pinnedVersion})` : ''}; newest published: ${newest || 'unknown — the registry could not be read'}. Re-read the live version and target that; pass --allow-downgrade only if going backwards is the point (migrations are not reverted).` };
-  }
-  log(`bongos ${isDowngrade ? 'DOWNGRADE (--allow-downgrade; migrations are NOT reverted)' : 'upgrade'} — ${CORE_PKG}: ${fromVersion || '(none)'} → ${targetVersion}`);
-  log(`  instance: ${instanceDir}${dryRun ? '   [DRY RUN — no changes]' : ''}`);
-  if (fromVersion === targetVersion && !opts.force) {
-    return { ok: false, error: `already on ${targetVersion} (pass --force to re-run the steps anyway)`, fromVersion };
-  }
-
-  // 1. pre-flight: clean tree (so the pin change is reviewable + revertable) + module compatibility.
-  if (!opts.force) {
-    // Step 5's own output is not dirt (task 1004122) — but only when step 5 is going to run.
-    const preview = opts.skipMaterialize ? () => [] : (deps.willRewrite || require('./claude-materialize').materializeWillRewrite);
-    const tree = gitTreeClean(instanceDir, run, preview({ instanceDir, materialize }, err));
-    // TWO DIFFERENT FAILURES, TWO DIFFERENT SENTENCES (task 1004512). git ANSWERING with a
-    // list of dirty paths is a dirty tree, which the self-heal chain knows how to fix. git
-    // REFUSING to answer is not: committing anything would be committing a guess. They used
-    // to share one message, so a `dubious ownership` refusal was classified dirty_tree, the
-    // runner committed a tree that was never dirty, and the retry failed identically.
-    if (!tree.ok && tree.reason) return { ok: false, error: `git could not read the working tree in ${instanceDir} — the clean-tree pre-flight never ran, so this is NOT a report of uncommitted work.\n${tree.reason}` };
-    if (!tree.ok) return { ok: false, error: `working tree not clean — commit/stash first, or pass --force.\n${tree.dirty || ''}` };
-    if (tree.ignored) log(`  • pre-flight: ignored ${tree.ignored} dirty path(s) this upgrade rewrites from the core (.claude/ materialization)${opts.commitPin ? ' — they are committed with the pin' : ' — pass --commit-pin to commit them'}.`);
-  }
-  const mods = preflightModules({ instanceDir, targetVersion }, deps);
-  log(`  ✓ pre-flight: ${mods.note}`);
-  // Surface the non-blocking findings (rotted-but-disabled + deprecated modules) BEFORE the
-  // blocking check returns, so they are reported on a refused bump too — a refusal is exactly
-  // when someone is reading this output (ADR 0166).
-  (deps.reportModulePreflight || reportModulePreflight)(mods, targetVersion, { log, err });
-  if (!mods.ok) return { ok: false, error: `module pre-check failed: ${mods.blocking.map((b) => b.key).join(', ')} incompatible with core ${targetVersion}` };
-  // Fail on the DB identity BEFORE anything moves — a wrong OS user is an operator
-  // mistake, and finding it at migrate means unwinding a pin that never should have
-  // been written (task 1002712).
-  if (!opts.skipMigrate) {
-    const { db, ran } = (deps.resolveInstanceDb || resolveInstanceDb)({ instanceDir }, run);
-    if (ran && !db) {
-      return { ok: false, error: 'cannot determine which database to migrate.\n'
-        + '    Set PGDATABASE, or give this instance a db.database in config/branding.json.\n'
-        + '    Checked BEFORE the pin moves: migrate runs after the install, so a name that\n'
-        + '    cannot be resolved there costs a full rollback to discover (task 1002755).' };
-    }
-    const dbId = (deps.preflightDbIdentity || preflightDbIdentity)({ instanceDir, db, account: opts.migrateAs || null }, run);
-    if (!dbId.ok) return { ok: false, error: dbId.reason };
-    if (dbId.skipped) log(`  • db identity pre-check${db ? ` (${db})` : ''}: ${dbId.skipped}`);
-    else log(`  ✓ pre-flight: database${db ? ` "${db}"` : ''} reachable as ${opts.migrateAs || 'the current user'}`);
-    const { note: migrateNote } = require('./upgrade-migrate').migratePlan(instanceDir); if (migrateNote) log(`  ✓ pre-flight: ${migrateNote}`);
-  }
-
-  // 1a. artist gate (ADR 0241, task 1004205): an open review holds the pin, --force too; a downgrade never waits.
-  const gate = isDowngrade ? { halts: [], notes: [] } : await (deps.checkArtistGate || checkArtistGate)(opts, deps);
-  for (const n of gate.notes) err(`  ! ${n.message}`);
-  if (gate.halts.length) return { ok: false, artistGate: true, error: gate.halts.map((h) => [h.message, h.detail].filter(Boolean).join('\n    ')).join('\n') };
-  // 1b. mandatory post-restart health check (audit H9 / task 1002222, F5): a bump that restarts the
-  //     service must prove it serves, so --health-url is required up front, before anything moves.
-  //     (No managed restart ⇒ nothing is brought live here ⇒ the operator restarts + verifies.)
-  const willRestart = !!(opts.service || opts.restartCmd);
-  if (!dryRun && opts.healthCheck !== false && willRestart && !opts.healthUrl) {
-    return { ok: false, error: 'post-restart health check is mandatory for a bump that restarts the service, but no --health-url was given.\n  Pass --health-url <url> to confirm the new core serves after restart, or --no-health-check to explicitly skip the confirmation.' };
-  }
-
-  // 2. bump the pin. Two mutually exclusive core sources:
-  //    REGISTRY (--registry): pin @bongos/core@<version> and let `npm install` pull it from
-  //      the public registry. No credential — the package is public (task 1003872), which
-  //      also retired the whole resolve-a-token-and-inject-it dance (task 1002754/1003878).
-  //    VENDORED (default, --from <tgz>): copy the .tgz into vendor/ + rewrite the file: dep.
-  if (opts.registry) {
-    if (opts.from) return { ok: false, error: '--registry and --from are mutually exclusive (registry pull vs vendored tarball) — pick one core source' };
-    const prevPin = dryRun ? null : writeRegistryPin(instanceDir, targetVersion, fsImpl);
-    if (!dryRun) { snapshot = { prevPin, prevVersion: fromVersion }; }
-    log(`  ${dryRun ? '[dry-run] would pin' : '✓ pinned'} ${CORE_PKG} → ${targetVersion} (registry)${prevPin ? `  (was ${prevPin})` : ''}`);
-  } else {
-    let vendorRel = opts.pinPath || (opts.from ? null : vendorRelFor(targetVersion));
-    if (opts.from) {
-      if (!fsImpl.existsSync(opts.from)) return { ok: false, error: `--from tarball not found: ${opts.from}` };
-      if (dryRun) { log(`  [dry-run] would vendor ${opts.from} → vendor/${ARTIFACT}-${targetVersion}.tgz`); vendorRel = vendorRelFor(targetVersion); }
-      else vendorRel = vendorTarball({ instanceDir, fromTgz: path.resolve(opts.from), targetVersion }, fsImpl);
-    }
-    if (!fsImpl.existsSync(path.join(instanceDir, vendorRel)) && !dryRun) {
-      return { ok: false, error: `no core tarball at ${vendorRel} — pass --from <path-to-.tgz> to vendor it (or --registry to pull from the npm registry)` };
-    }
-    const prevPin = dryRun ? null : writePin(instanceDir, vendorRel, fsImpl);
-    if (!dryRun) snapshot = { prevPin, prevVersion: fromVersion };
-    log(`  ${dryRun ? '[dry-run] would pin' : '✓ pinned'} ${CORE_PKG} → file:${vendorRel}${prevPin ? `  (was ${prevPin})` : ''}`);
-  }
-
-  if (dryRun) { log(`  [dry-run] would: npm install → ${opts.skipMigrate ? '(no migrate)' : require('./upgrade-migrate').migratePlan(instanceDir).label} → materialize .claude → regen API docs+client → restart → verify`); return { ok: true, dryRun: true, fromVersion, toVersion: targetVersion }; }
-
-  // 3. npm install.
-  const inst = npmInstall(instanceDir, run);
-  if (!inst.ok) {
-    const error = `npm install failed (${inst.reason || 'exit ' + inst.code})`;
-    if (rollbackOnFailure && snapshot) {
-      const rb = await doRollback('npm install failed');
-      return { ok: false, error, fromVersion, toVersion: targetVersion, rolledBack: true, rollback: rb };
-    }
-    return { ok: false, error, fromVersion };
-  }
-  log('  ✓ npm install');
-
-  // 3b. verify the integrity pin (audit H8 / task 1002216, finding F1). Recompute tree_sha256 over
-  //     the freshly-installed core (+ the exact vendored tarball bytes) and assert it matches the
-  //     TRUSTED reference manifest — the pin the packager produced but the consume side never
-  //     re-checked. Runs BEFORE migrate so a corrupted core can never touch the DB. A MISMATCH is
-  //     fatal → rollback (like an install/migrate failure). A MISSING reference (no side-car AND no
-  //     inner manifest) can't be verified: a warning by default, fatal only with --require-pin.
-  if (!opts.skipPinVerify) {
-    const coreDir = path.join(instanceDir, 'node_modules', CORE_PKG);
-    const ref = (deps.resolveReferenceManifest || resolveReferenceManifest)({ instanceDir, coreDir, targetVersion }, fsImpl);
-    if (!ref.manifest) {
-      const msg = `integrity pin: no reference manifest (looked for vendor/${ARTIFACT}-${targetVersion}.manifest.json and ${CORE_PKG}/.bongos-core.json) — cannot verify this install`;
-      if (opts.requirePin) {
-        const error = `${msg} (--require-pin)`;
-        if (rollbackOnFailure && snapshot) { const rb = await doRollback('integrity pin unverifiable (--require-pin)'); return { ok: false, error, fromVersion, toVersion: targetVersion, rolledBack: true, rollback: rb }; }
-        return { ok: false, error, fromVersion };
-      }
-      err(`  ! ${msg} — pass --require-pin to treat this as fatal.`);
-    } else {
-      const pin = (deps.verifyInstalledPin || verifyInstalledPin)({ coreDir, referenceManifest: ref.manifest, tgzPath: ref.tgzPath }, deps);
-      if (!pin.ok) {
-        const detail = pin.problems.slice(0, 6).join('; ') + (pin.problems.length > 6 ? `; +${pin.problems.length - 6} more` : '');
-        const error = `integrity pin MISMATCH (${ref.source}) — installed core does not match its pin: ${detail}`;
-        if (rollbackOnFailure && snapshot) {
-          const rb = await doRollback('integrity pin mismatch');
-          return { ok: false, error, fromVersion, toVersion: targetVersion, rolledBack: true, rollback: rb };
-        }
-        return { ok: false, error, fromVersion };
-      }
-      log(`  ✓ integrity pin verified (${pin.checks.map((c) => c.name).join(' + ')}) against the ${ref.source}${ref.strong ? '' : ' — self-consistency check; npm registry integrity is the primary guard'}`);
-    }
-  } else log('  • integrity-pin verify skipped (--skip-pin-verify)');
-
-  // 4. migrate (additive core_* migrations).
-  if (!opts.skipMigrate) {
-    const mig = await runMigrate(instanceDir, run, opts.migrateAs || null);
-    if (!mig.ok) {
-      const error = migrateError(mig); // names the failing migration + its ERROR line (task 1004734)
-      if (rollbackOnFailure && snapshot) {
-        const rb = await doRollback('migrate failed');
-        return { ok: false, error, fromVersion, toVersion: targetVersion, rolledBack: true, rollback: rb };
-      }
-      return { ok: false, error, fromVersion };
-    }
-    log('  ✓ migrate');
-  } else log('  • migrate skipped (--skip-migrate)');
-
-  // 5. materialize .claude/ from the freshly-installed core.
-  //
-  // Its output rides the pin commit for the same reason the regenerated API artifacts below
-  // do (task 1003957 extending task 1003926): left dirty, the NEXT sweep's clean-tree guard
-  // reads `.claude/skills/*` as a human's uncommitted work and skips the instance forever —
-  // an enrolled co-tenant that upgrades exactly once. materializeClaude reports the paths it
-  // actually wrote or withdrew, so this is what THIS run touched, not a static list.
-  let materializedPaths = [];
-  if (!opts.skipMaterialize) {
-    const coreRoot = path.join(instanceDir, 'node_modules', CORE_PKG);
-    const sum = materialize({ coreRoot, instanceDir, log: (m) => log(m) });
-    materializedPaths = sum.writtenPaths || [];
-    log(`  ✓ materialized .claude/ (${sum.skills} skill file(s)${sum.settings ? ', settings.json' : ''}${sum.hooks ? `, ${sum.hooks} hook(s)` : ''})`);
-  } else log('  • materialize skipped (--skip-materialize)');
-
-  // 5b. regenerate the per-instance API artifacts (OpenAPI spec + typed client) from the
-  // new core's routes — the claude-materialize sibling (task 2051). Best-effort: a regen
-  // hiccup is a warning, not a failed bump (the next ship's fitness gate refreshes them).
-  let regenArtifacts = [];
-  if (!opts.skipRegenDocs) {
-    const coreRoot = path.join(instanceDir, 'node_modules', CORE_PKG);
-    const regen = (deps.regenerateApiArtifacts || regenerateApiArtifacts)({ instanceDir, coreRoot }, run);
-    regenArtifacts = (regen.ran || []).flatMap((gen) => API_ARTIFACT_FILES[gen] || []);
-    if (regen.ok) log(`  ✓ regenerated API docs + typed client from core ${targetVersion}`);
-    else err(`  ! API-artifact regen incomplete (${regen.reason}) — ran ${regen.ran.join(', ') || 'nothing'}; the next ship's fitness gate refreshes them.`);
-    // 5c. regenerate the whole-file navigation docs (repo-map + session-index) from the new
-    // core against the instance root (ADR 0110 / task 1002314). Best-effort + LOUD: a broken
-    // generator alarms via ::ERROR:: but never fails the bump.
-    const nav = (deps.regenerateNavDocs || regenerateNavDocs)({ instanceDir, coreRoot }, run);
-    if (nav.ok) log(`  ✓ regenerated navigation docs (${nav.ran.join(', ')}) from core ${targetVersion}`);
-    else err(`  ! ::ERROR:: navigation-doc regen incomplete — ran ${nav.ran.join(', ') || 'nothing'}; failed ${nav.failed.map((f) => `${f.gen} (${f.reason})`).join(', ')}. The next deploy retries.`);
-    // 5d. re-generate the CORE-scoped doc assets this very upgrade just wiped — the Repo Atlas
-    // data file + the onboarding diagram renders (task 1002441). See healDocAssets() for why
-    // nothing else puts them back. Best-effort + LOUD, same contract as 5c.
-    const heal = (deps.healDocAssets || healDocAssets)({ coreRoot }, run);
-    if (heal.missing.length === 0) log('  • doc assets intact (atlas + diagram renders present)');
-    else if (heal.ok) log(`  ✓ regenerated doc assets wiped by the core swap (${heal.ran.join(', ')})`);
-    else err(`  ! ::ERROR:: doc-asset regen incomplete — ran ${heal.ran.join(', ') || 'nothing'}; failed ${heal.failed.map((f) => `${f.group} (${f.reason})`).join(', ')}. /builders/atlas or /builders/diagrams may be broken until the next deploy retries (diagram renders need a system Chromium — ADR 0122).`);
-  } else log('  • doc regen skipped (--skip-regen-docs)');
-
-  // 6. restart.
-  const rs = restartService({ service: opts.service, restartCmd: opts.restartCmd }, run, deps);
-  if (rs.skipped) log(`  • restart: no --service/--restart-cmd — restart the instance service to load core ${targetVersion}.`);
-  else if (!rs.ok) {
-    // task 1002884: a failed restart is an upgrade FAILURE, not a warning. It used to fall
-    // through to the verification below — but the old process is still up, so the health poll
-    // passed against IT and the bump wrote a success row for a core that was never served.
-    // Failing here also keeps disk and process consistent: rollback puts the previous core back
-    // on disk, matching the one that is (still) running.
-    err(`  ✖ restart failed (exit ${rs.code})${rs.triedSudo ? ` — \`systemctl restart\` exited ${rs.directCode} and \`sudo -n systemctl restart\` could not escalate` : ''}`);
-    err('    The previous core is still the one being served. Grant the restart a non-interactive path');
-    err('    (sudoers NOPASSWD or a polkit rule — docs/recipes/instance-service-restart.md), then re-run.');
-    const error = `restart failed (exit ${rs.code}) — the instance is still running the previous core`;
-    if (rollbackOnFailure && snapshot) {
-      const rb = await doRollback('restart failed');
-      return { ok: false, error, fromVersion, toVersion: targetVersion, restartOk: false, rolledBack: true, rollback: rb };
-    }
-    return { ok: false, error, fromVersion, toVersion: targetVersion, restartOk: false };
-  } else log(`  ✓ restarted ${opts.service || 'service'}${rs.triedSudo ? ' (via sudo -n)' : ''}`);
-
-  // 7. verify: installed version == target, optional /healthz, ledger row.
-  const installed = readInstalledCoreVersion(instanceDir, fsImpl);
-  const versionOk = installed === targetVersion;
-  log(`  ${versionOk ? '✓' : '!'} installed core version: ${installed || '(unknown)'}${versionOk ? '' : ` (expected ${targetVersion})`}`);
-
-  let healthOk = null;
-  if (opts.healthCheck === false) {
-    log('  • post-restart health check skipped (--no-health-check) — success is NOT confirmed against a live endpoint.');
-  } else if (opts.healthUrl) {
-    const h = await pollHealth(opts.healthUrl, deps);
-    healthOk = h.ok;
-    if (h.ok) log(`  ✓ health ${opts.healthUrl} → ${h.status}${h.attempts > 1 ? ` (ready after ${h.attempts} tries)` : ''}`);
-    else err(`  ! health ${opts.healthUrl} not ready after ${h.attempts} tr${h.attempts === 1 ? 'y' : 'ies'}: ${h.error || 'status ' + h.status}`);
-  } else {
-    // Reachable only when NO managed restart happened (pre-flight requires a URL when one will):
-    // the new core is installed on disk, but nothing was brought live here to health-check.
-    log('  • no managed restart + no --health-url — new core installed but not confirmed serving; restart the instance + health-check it to complete the bump.');
-  }
-
-  // 7b. Confirm the SERVED process actually swapped (task 1002884). Everything above this point
-  //     can be true of an instance still running the OLD core: the pin moved, node_modules holds
-  //     the new version, and /healthz answers 200 — from the process that never went down. Only
-  //     the live coreVersion settles it.
-  //     A definite MISMATCH is a failure (same treatment as a failed health check). Being unable
-  //     to READ the endpoint is not: an instance may not expose it, and refusing every such bump
-  //     would be a worse regression than the false-pass. Passing --version-url explicitly asks
-  //     for proof, so there an unreadable endpoint IS a failure.
-  let servedOk = null;
-  let servedVersion = null;
-  const versionUrl = opts.versionUrl || (opts.healthUrl ? deriveVersionUrl(opts.healthUrl) : null);
-  if (opts.healthCheck === false) {
-    // --no-health-check is the documented opt-out from confirming the bump serves; it covers this.
-  } else if (versionUrl && healthOk !== false) {
-    const sv = await pollServedVersion(versionUrl, deps);
-    servedVersion = sv.version || null;
-    if (sv.ok && servedVersion === targetVersion) {
-      servedOk = true;
-      log(`  ✓ served core version: ${servedVersion} (${versionUrl})`);
-    } else if (sv.ok) {
-      servedOk = false;
-      err(`  ! served core version is ${servedVersion} but the target is ${targetVersion} (${versionUrl})`);
-      err('    The restart did not swap the running process — the old core is still being served.');
-    } else if (opts.versionUrl) {
-      servedOk = false;
-      err(`  ! could not read ${versionUrl} (${sv.error}) — --version-url was given, so this bump cannot be confirmed`);
-    } else {
-      err(`  ! could not read ${versionUrl} (${sv.error}) — this bump is NOT confirmed against the running process.`);
-      err('    Pass --version-url <url> if this instance serves its version elsewhere.');
-    }
-  }
-
-  // A failed post-restart health check means the new core is serving broken — auto-revert (task
-  // 2149) instead of recording an "upgraded" row + leaving the instance down. A served-version
-  // mismatch means the new core is not serving AT ALL (task 1002884) and reverts the same way.
-  // The rollback writes its OWN rolled_back ledger row, so skip the normal insert below.
-  if ((healthOk === false || servedOk === false) && rollbackOnFailure && snapshot) {
-    const why = healthOk === false
-      ? 'health check failed after restart'
-      : `served core version did not change (still ${servedVersion || 'unconfirmed'}, expected ${targetVersion})`;
-    const rb = await doRollback(why);
-    return { ok: false, error: `${why} — rolled back to ${snapshot.prevVersion || 'the previous core'}`, fromVersion, toVersion: targetVersion, versionOk, healthOk, servedOk, servedVersion, rolledBack: true, rollback: rb };
-  }
-
-  const ledger = await recordLedger({ fromVersion, toVersion: targetVersion, sourceCommit: opts.sourceCommit, note: isDowngrade ? `downgrade (--allow-downgrade)${opts.note ? `: ${opts.note}` : ''}` : opts.note, requestedByBuilderId: opts.requestedBy, source: opts.upgradeSource, account: opts.migrateAs || null }, deps);
-  if (ledger.ok) log('  ✓ recorded in core_upgrades ledger');
-  else if (ledger.skipped) log(`  • ledger skipped (${ledger.reason})`);
-  else err(`  ! ledger insert failed (${ledger.reason}) — record it manually`);
-
-  // Make the pin durable (task 1002712). Runs LAST — only a verified-healthy
-  // upgrade is worth persisting, and a rolled-back one returned long before here.
-  //
-  // Which credential the push rides is resolved HERE (async — it may read the token
-  // store) and handed to persistPin, which stays synchronous — and only when a push is
-  // actually coming: --commit-pin without --pin-no-push, not a dry run, and the pin
-  // files really are dirty. Nothing reads a credential it will not spend (task 1003081).
-  const remote = opts.gitRemote || 'origin';
-  // Everything this upgrade generated into the instance's tree: the API artifacts (task
-  // 1003926) and the materialized .claude/ (task 1003957). One list, so the push-credential
-  // probe and persistPin agree on what "the upgrade rewrote" means.
-  const generatedPaths = [...regenArtifacts, ...materializedPaths];
-  const pushComing = !!opts.commitPin && !opts.pinNoPush && !dryRun
-    && ((dirtyPinFiles(instanceDir, run) || []).length > 0 || (dirtyPaths(instanceDir, generatedPaths, run) || []).length > 0);
-  const pushAuth = pushComing ? await (deps.resolvePinPushAuth || resolvePinPushAuth)({ instanceDir, remote }, deps, run) : null;
-  const pin = persistPin({
-    instanceDir,
-    fromVersion,
-    toVersion: targetVersion,
-    commitPin: opts.commitPin,
-    push: !opts.pinNoPush,
-    remote,
-    dryRun: opts.dryRun,
-    pushAuth,
-    artifactPaths: generatedPaths,
-  }, run, log, err);
-
-  const ok = versionOk && healthOk !== false && servedOk !== false;
-  log(ok ? `\n✓ ${isDowngrade ? 'downgrade' : 'upgrade'} complete — core ${fromVersion || '(none)'} → ${targetVersion}` : `\n! ${isDowngrade ? 'downgrade' : 'upgrade'} finished with warnings — review above.`);
-  return { ok, fromVersion, toVersion: targetVersion, versionOk, healthOk, servedOk, servedVersion, ledger: ledger.ok, pin };
-}
-
-function parseArgs(argv) {
-  return {
-    to: arg('--to', argv),
-    from: arg('--from', argv),
-    instance: arg('--instance', argv),
-    service: arg('--service', argv),
-    restartCmd: arg('--restart-cmd', argv),
-    healthUrl: arg('--health-url', argv),
-    versionUrl: arg('--version-url', argv), // task 1002884: read the LIVE process's coreVersion back; defaults to /version on the health URL's origin
-    sourceCommit: arg('--source-commit', argv),
-    note: arg('--note', argv),
-    // Who asked, and through which door (task 1003159, ADR 0293 D5). Both reach the
-    // core_upgrades row so a privileged act that an HTTP request could start is never
-    // unattributable. Omitted on a hand-run bump, where there is no builder to name —
-    // and omitting them keeps the INSERT on its pre-core_241 four columns, which is
-    // what lets this script keep working against an instance DB that has not migrated.
-    requestedBy: arg('--requested-by', argv),
-    upgradeSource: arg('--upgrade-source', argv),
-    pinPath: arg('--pin-path', argv),
-    migrateAs: arg('--migrate-as', argv), // task 1004512: the project's own unix+Postgres identity, when the move itself runs as the account that owns the checkout
-    registry: hasFlag('--registry', argv), // ADR 0134: pull @bongos/core@<--to> from the npm registry instead of vendoring
-    commitPin: hasFlag('--commit-pin', argv), // task 1002712: commit + push package.json/-lock so a pull-deploy reset cannot revert the bump
-    pinNoPush: hasFlag('--pin-no-push', argv), // task 1003521 co-tenant mode: commit the pin but leave the customer's own remote alone
-    gitRemote: arg('--git-remote', argv),
-    dryRun: hasFlag('--dry-run', argv),
-    force: hasFlag('--force', argv),
-    allowDowngrade: hasFlag('--allow-downgrade', argv), // task 1004009: a --to older than the installed core is refused without it
-    skipMigrate: hasFlag('--skip-migrate', argv),
-    skipMaterialize: hasFlag('--skip-materialize', argv),
-    skipRegenDocs: hasFlag('--skip-regen-docs', argv),
-    skipPinVerify: hasFlag('--skip-pin-verify', argv), // task 1002216: opt out of the post-install integrity-pin check
-    requirePin: hasFlag('--require-pin', argv), // task 1002216: a MISSING reference manifest becomes fatal (not just a warning)
-    healthCheck: !hasFlag('--no-health-check', argv), // task 1002222: post-restart health check is ON by default (finding F5/H9)
-    rollbackOnFailure: !hasFlag('--no-rollback-on-failure', argv), // ADR 0100: auto-revert ON by default (task 2149)
-  };
-}
-
-async function main(argv = process.argv.slice(2), deps = {}) {
-  if (hasFlag('--help', argv) || argv[0] === 'help') {
-    process.stdout.write([
-      'bongos upgrade — pull the Cloud Bongos core to a new version and apply it.',
-      '',
-      'Usage:',
-      '  bongos upgrade                         module-compat pre-check against the installed core (exit 1 on mismatch)',
-      '  bongos upgrade --to <version> [opts]   pull + apply a new core version (the real channel)',
-      '',
-      '  --to <version>       target core version — presence switches from pre-check to a real bump',
-      '  --from <tgz>         source tarball to vendor into vendor/ (else it must already be there)',
-      '  --registry           pull @bongos/core@<--to> from the public npm registry (no token needed) instead of vendoring a tarball; mutually exclusive with --from',
-      '  --instance <dir>     consumer instance root (default: cwd)',
-      '  --service <unit>     systemd unit to restart after applying',
-      '  --restart-cmd <cmd>  explicit restart command (overrides --service)',
-      '  --health-url <url>   poll after restart (~30s) until 2xx; a still-failing check fails the bump (auto-rollback). REQUIRED for a bump that restarts the service, unless --no-health-check.',
-      '  --version-url <url>  read the RUNNING process\'s coreVersion back after restart and require it to equal --to (default: /version on the --health-url origin). A health check alone cannot tell a new core from an old one that never went down.',
-      '  --no-health-check    explicitly skip the post-restart health confirmation (default: the check is ON — a bump that restarts the service must confirm it serves); also skips the served-version read-back',
-      '  --skip-migrate       do not migrate (the default runs the instance\'s `migrate` script, else the core\'s scripts/migrate.sh)',
-      '  --migrate-as <user>  run the database steps (identity pre-check, migrate, ledger) as this unix account via `sudo -n -u`. For a project whose checkout is owned by the operator account but whose database is owned by its OWN account: the move needs the first to write files, the migration needs the second to connect. Omit it and everything runs as the current user, as before',
-      '  --skip-materialize   do not refresh .claude/',
-      '  --skip-regen-docs    do not regenerate the OpenAPI spec + typed client from the new core',
-      '  --skip-pin-verify    do not verify the integrity pin (tree_sha256 + tarball.sha256) after install',
-      '  --require-pin        treat a MISSING reference manifest as fatal (default: warn — a MISMATCH is always fatal)',
-      '  --no-rollback-on-failure  do NOT auto-revert on a failed install/pin-verify/migrate/health check (default: auto-rollback ON)',
-      '  --commit-pin         commit + push package.json/-lock so a pull-deploy reset cannot revert the bump. The push rides the instance owner\'s stored GitHub token when one is stored (a PRIVATE instance\'s origin is a read-only deploy key — ADR 0176), else the git remote (--git-remote <name>, default origin); a refused push is reported loudly with the fix',
-      '  --pin-no-push        with --commit-pin: commit the pin but do NOT push it — for an instance whose repo of record is not ours (a provisioned co-tenant), where the push is wrong and no pull-deploy can revert the commit',
-      '  --dry-run            show the plan; change nothing',
-      '  --force              skip the clean-tree + same-version guards (NOT the downgrade guard)',
-      '  --allow-downgrade    let --to be OLDER than the installed core. Refused otherwise: a stale --to silently takes merged work off a live instance, and migrations are never reverted, so the DB stays ahead of the code',
-      '',
-      'Full bump: pre-flight → bump pin → npm install → verify integrity pin → migrate → materialize .claude → regen API docs+client → restart → verify (health + served coreVersion).',
-      'On a failure after the pin moves (install/pin-verify/migrate/restart/health/served-version), auto-rollback reverts the pin, reinstalls the previous core, restarts, and records a rolled_back ledger row (the DB is not rolled back — core migrations are additive).',
-    ].join('\n') + '\n');
-    return 0;
-  }
-  // Backward-compatible: bare `bongos upgrade` (no --to) is the documented module-compatibility
-  // PRE-CHECK — unchanged behavior, delegated to the module CLI. A --to switches to the real channel.
-  // task 1004596: from a builder's own checkout of a project its OPERATOR runs, say who upgrades it and how to ask — never a server-only refusal (upgrade-operator.js has the condition).
-  const operatorMsg = await (deps.operatorNotice || require('./upgrade-operator').operatorNotice)({ instanceDir: path.resolve(arg('--instance', argv) || process.cwd()) });
-  if (!arg('--to', argv)) {
-    const code = await (deps.cmdUpgrade || require('./module').cmdUpgrade)(argv);
-    if (operatorMsg) process.stdout.write(`\n${operatorMsg}`);
-    return code;
-  }
-  if (operatorMsg) { process.stderr.write(`\n✖ ${operatorMsg}`); return 1; }
-  const res = await runUpgrade(parseArgs(argv));
-  if (!res.ok) { process.stderr.write(`\n✖ ${res.error || 'upgrade failed'}\n${require('./upgrade-outcome').outcomeLine(res)}`); return 1; } // the outcome line: how far it got, for the deploy runner (task 1004446)
-  return 0;
-}
-
-module.exports = {
-  runUpgrade, parseArgs, main, rollback,
-  versionFromTgzPath, versionFromDep, readInstalledCoreVersion, readPinnedCoreVersion, writePin, writeRegistryPin, restorePin,
-  vendorTarball, gitTreeClean, persistPin, dirtyPinFiles, gitCurrentBranch, PIN_FILES, API_ARTIFACT_FILES, preflightDbIdentity,
-  resolveInstanceDb, preflightModules, reportModulePreflight, npmInstall, runMigrate, regenerateApiArtifacts, regenerateNavDocs, NAV_WHOLE_FILE_GENERATORS, missingDocAssets, healDocAssets, DOC_ASSET_GENERATORS, restartService, recordLedger, ledgerInsert, LEDGER_ACTOR_COLS, pollHealth, deriveVersionUrl, pollServedVersion,
-  resolvePinPushAuth, remoteGithubRepo, pinnedDeployKey, // task 1003081 — the pin push prefers the owner's GitHub token (ADR 0176 follow-up)
-  readManifest, resolveReferenceManifest, verifyInstalledPin, // task 1002216 (audit H8) — integrity-pin verification
-  CORE_PKG, ARTIFACT, vendorRelFor,
-};
-
-if (require.main === module) {
-  main().then((code) => { if (arg('--to', process.argv.slice(2))) process.exit(code); else process.exitCode = code; }).catch((e) => { process.stderr.write(`✖ ${e.message}\n`); process.exit(1); }); // bare pre-check drains: it ends after a store read (task 1003787), and a hard exit there aborts on Windows (task 1002734)
-}
+require('../bongos/forwarder.js').forward(module, 'upgrade.js');