@bongos/core 1.19.71 → 1.19.72

package/.bongos-core.json

@@ -2,22 +2,22 @@
   "artifact": "bongos-core",
   "manifest_schema": 1,
   "generator": "scripts/gds/package-core.js",
-  "core_version": "1.19.71",
-  "core_contract": "1.19.71",
-  "source_commit": "4eba29162c98469e50170c8942bb995192ac0378",
+  "core_version": "1.19.72",
+  "core_contract": "1.19.72",
+  "source_commit": "36150e839bd63b4544b7828ad26137d2b2501a07",
   "source_ref": "HEAD",
-  "built_at": "2026-08-12T15:37:06.175Z",
+  "built_at": "2026-08-12T16:31:58.158Z",
   "redaction": {
     "model": "docs-redacted+functional-verbatim",
     "docs_redacted": 294,
     "agent_docs_stubbed": 21,
-    "functional_verbatim": 1223,
+    "functional_verbatim": 1224,
     "rules": 3,
     "gate_literals": 3,
     "gate": "passed"
   },
-  "file_count": 1538,
-  "tree_sha256": "7d0cdc9a7a536092bcbcf6f173a3c55c18773c1878e1613394b768dd54d6228f",
+  "file_count": 1539,
+  "tree_sha256": "dc8a5fa6b9f2b5d49dec5763477b0793d156abea3894c575d3989591a6b4ad1c",
   "files": [
     {
       "path": ".claude/skills/blocker-review/SKILL.md",
@@ -1617,7 +1617,7 @@
     {
       "path": "docs/recipes/upgrading-the-core.md",
       "mode": "0000644",
-      "sha256": "dcf0520928832e4a8e723c830a5d8f5e1ae1a0fcef16ff21345aabf715e142f6"
+      "sha256": "732f3b01b7d2e6cc238dd5f48d5ed774f6c2c27ecc737710047758bf85f2d9e5"
     },
     {
       "path": "docs/recipes/work-on-a-task-from-your-dev-box.md",
@@ -4052,12 +4052,12 @@
     {
       "path": "package-lock.json",
       "mode": "0000644",
-      "sha256": "9fed4a4c8c227a418e6cc695f1a9a7ddea366f1e0ddd95f788d7b64dacd03ff2"
+      "sha256": "183fa8f7d1c63c5188516529049a52a88cae64c235b8350f9362ea8e6175f886"
     },
     {
       "path": "package.json",
       "mode": "0000644",
-      "sha256": "af4d4ea3a0dd190dda1d0f04e2d9450b395cc4026405833e970f2ac81772fe5d"
+      "sha256": "1293840e72b03f675e2bc9c30a42f4885f4d54a56674fd605260a0f5549bd8b5"
     },
     {
       "path": "public-docs/index.html",
@@ -5317,7 +5317,7 @@
     {
       "path": "scripts/gds/upgrade.js",
       "mode": "0000644",
-      "sha256": "4ba3cd406e82907ae554e90abb1c746ff7c9802c9fbed0c1eac241798860d0c6"
+      "sha256": "b539715de4893f8fa68c53c145ac2f54de39ccc5517f9e5ad17540c487dc24b0"
     },
     {
       "path": "scripts/gds/validate-design.js",
@@ -5682,7 +5682,7 @@
     {
       "path": "src/module-api.js",
       "mode": "0000644",
-      "sha256": "110f17337515aa6751a7c881bd20c0694f38686b5b62c29da43ac2677be2b5af"
+      "sha256": "b5c45d792faf401db67d81fa567c437b25e2ba9ef521e2f9e8cb052f474b0098"
     },
     {
       "path": "src/module-loader/loader.js",
@@ -7662,7 +7662,12 @@
     {
       "path": "tests/upgrade.mjs",
       "mode": "0000644",
-      "sha256": "3d7aaec00a43c303e0bb6e465f48fd8d6523844cd2414c2979ad6144424d2ebb"
+      "sha256": "60e55591174f59238486d318fb92dc8fd8251eb73435d690e38ea83a2a5f235e"
+    },
+    {
+      "path": "tests/upgrade_persist_pin.mjs",
+      "mode": "0000644",
+      "sha256": "07fd48b255bbd2370580b62a8f77d7fc981b0dfdefcc5be6973a9c4d6cb49add"
     },
     {
       "path": "tests/verify_task_guard.mjs",

package/docs/recipes/upgrading-the-core.md

@@ -52,6 +52,10 @@ The instance runs on the droplet (co-tenant): systemd `emersonian-circles.servic
    ```
 5. **Verify** — `systemctl is-active`, local + public `/healthz` 200, `/version`, `installed core == <version>`, the `core_upgrades` row.
 6. **Update the repo of record** — run the channel on the laptop clone (`--skip-migrate`, no DB there), commit the pin bump (drop the superseded tarball), `git push origin`.
+
+   > **The pin MUST reach the repo of record, or the bump silently un-does itself** (task 1002712). A pull-deploy instance resets to `origin/main`; a pin that lives only in the working tree is reverted the next time anything lands, and the lockfile change then trips `npm ci`, which reinstalls the OLD core. Nothing errors. cloudbongos.com lost thirteen releases exactly this way — the `core_upgrades` ledger held two successful `auto-subscription (patch)` rows whose result no longer existed on disk, because deploy.sh short-circuits while `HEAD == origin/main` so the upgrade *looks* fine right up until someone else pushes.
+   >
+   > `bongos upgrade` now **warns loudly** whenever it leaves the pin uncommitted in a git repo, and `--commit-pin` (optionally `--git-remote <name>`) commits + pushes `package.json` + `package-lock.json` for you. A commit that fails to push is reported as a failure too — deploy.sh resets to the *remote*, so committing locally saves nothing. Verify durability by forcing a deploy tick (`sudo systemctl start <instance>-deploy.service`) and re-reading the pin.
 7. **Align the droplet checkout** — the droplet has no deploy key (`git pull` fails; idea 509), so `git bundle` the new commit on the laptop, `scp`, `git fetch <bundle> && git reset --hard FETCH_HEAD`. `node_modules` is already the new version, so no re-`npm ci`; a final restart makes `/version` report the new commit.
 
 ## Auto-rollback on failure (task 2149)

package/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "@bongos/core",
-  "version": "1.19.71",
+  "version": "1.19.72",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@bongos/core",
-      "version": "1.19.71",
+      "version": "1.19.72",
       "license": "AGPL-3.0-or-later",
       "dependencies": {
         "express": "^4.21.2",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bongos/core",
-  "version": "1.19.71",
+  "version": "1.19.72",
   "description": "Cloud Bongos — the AI-first build platform core (GDS + platform surfaces + module system), installed as a versioned dependency (ADR 0108).",
   "license": "AGPL-3.0-or-later",
   "main": "src/platform-server.js",

package/scripts/gds/upgrade.js

@@ -124,6 +124,94 @@ function gitTreeClean(instanceDir, run = spawnSync) {
   return { ok: dirty === '', dirty };
 }
 
+// ---- 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'];
+
+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 the pin files git currently reports as modified.
+function dirtyPinFiles(instanceDir, run = spawnSync) {
+  const r = run('git', ['status', '--porcelain', '--', ...PIN_FILES], { 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(Boolean);
+}
+
+function persistPin({ instanceDir, fromVersion, toVersion, commitPin, remote = 'origin', dryRun = false },
+  run = spawnSync, log = console.log, err = console.error) {
+  const dirty = dirtyPinFiles(instanceDir, run);
+  if (dirty === null) return { applicable: false, reason: 'not a git repo' };
+  if (!dirty.length) return { applicable: false, reason: 'pin files already match the repo' };
+
+  const branch = gitCurrentBranch(instanceDir, run);
+
+  if (!commitPin) {
+    // 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:`);
+    // Single-quote the interpolated values. Nothing here executes this string — it is
+    // printed for a human to paste — but an unquoted branch or remote carrying shell
+    // metacharacters would misbehave once pasted, so emit it paste-safe.
+    const q = (s) => `'${String(s).replace(/'/g, `'\\''`)}'`;
+    const at = `git -C ${q(instanceDir)}`;
+    err(`      ${at} add ${PIN_FILES.map(q).join(' ')} && ${at} commit -m ${q(`pin @bongos/core ${toVersion}`)} && ${at} push ${q(remote)} ${q(`HEAD:${branch || 'main'}`)}`);
+    return { applicable: true, committed: false, pushed: false, dirty, warned: true };
+  }
+
+  if (dryRun) {
+    log(`  [dry-run] would commit + push ${dirty.join(', ')} to ${remote}/${branch || 'main'}`);
+    return { applicable: true, committed: false, pushed: false, dirty, dryRun: true };
+  }
+
+  const message = `pin @bongos/core ${toVersion}${fromVersion ? ` (was ${fromVersion})` : ''}`;
+  const add = run('git', ['add', ...PIN_FILES], { 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 commit = run('git', ['commit', '-m', message], { cwd: instanceDir, encoding: 'utf8' });
+  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(', ')})`);
+
+  const push = run('git', ['push', remote, `HEAD:${branch || 'main'}`], { cwd: instanceDir, encoding: 'utf8' });
+  if (!push || push.error || push.status !== 0) {
+    // Committed but not pushed is still doomed: deploy.sh resets to 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} HEAD:${branch || 'main'}`);
+    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) {
@@ -203,6 +291,34 @@ function npmInstall(instanceDir, run = spawnSync) {
   return !r || r.error ? { ok: false, reason: r && r.error ? r.error.message : 'spawn failed' } : { ok: r.status === 0, code: r.status };
 }
 
+// migrate.sh reaches Postgres over the local socket as the CURRENT OS USER (peer
+// auth) — so running an upgrade under `sudo` connects as `root`, which usually has
+// no Postgres role. The failure surfaces mid-run as a raw
+// `FATAL: role "root" does not exist`, AFTER the pin has already moved, which then
+// triggers the whole auto-rollback dance for what is really an operator mistake.
+// This names it up front instead (task 1002712).
+function preflightDbIdentity({ instanceDir, db }, run = spawnSync) {
+  const r = run('psql', ['-tAc', 'select 1'], {
+    cwd: instanceDir, encoding: 'utf8',
+    env: { ...process.env, ...(db ? { PGDATABASE: db } : {}) },
+  });
+  if (!r || r.error) return { ok: true, skipped: 'psql not on PATH — leaving it to migrate' };
+  if (r.status === 0) return { ok: true };
+
+  const out = `${r.stderr || ''}${r.stdout || ''}`;
+  const m = out.match(/role "([^"]+)" does not exist/i);
+  if (!m) return { ok: true, skipped: 'psql failed for another reason — leaving it to migrate' };
+  return {
+    ok: false,
+    role: m[1],
+    reason: `Postgres has no role "${m[1]}" — migrate would fail after the pin moved.\n`
+      + `    migrate.sh connects over the local socket as the CURRENT OS USER. Running the\n`
+      + `    upgrade under sudo connects as root, which is almost never a Postgres role.\n`
+      + `    Re-run as the user that owns the instance (e.g. sudo -u <owner> …), passing the\n`
+      + `    npm token through if the core comes from the registry.`,
+  };
+}
+
 function runMigrate(instanceDir, run = spawnSync) {
   const r = run('npm', ['run', 'migrate'], { cwd: instanceDir, stdio: 'inherit' });
   return !r || r.error ? { ok: false, reason: r && r.error ? r.error.message : 'spawn failed' } : { ok: r.status === 0, code: r.status };
@@ -628,6 +744,15 @@ async function runUpgrade(opts, deps = {}) {
   // 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 dbId = (deps.preflightDbIdentity || preflightDbIdentity)({ instanceDir, db: process.env.PGDATABASE }, run);
+    if (!dbId.ok) return { ok: false, error: dbId.reason };
+    if (dbId.skipped) log(`  • db identity pre-check: ${dbId.skipped}`);
+    else log('  ✓ pre-flight: database reachable as the current user');
+  }
 
   // 1b. mandatory post-restart health check (audit H9 / task 1002222, finding F5). A bump that
   //     brings the new core live via a managed restart (--service / --restart-cmd) MUST confirm it
@@ -794,9 +919,20 @@ async function runUpgrade(opts, deps = {}) {
   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.
+  const pin = persistPin({
+    instanceDir,
+    fromVersion,
+    toVersion: targetVersion,
+    commitPin: opts.commitPin,
+    remote: opts.gitRemote || 'origin',
+    dryRun: opts.dryRun,
+  }, run, log, err);
+
   const ok = versionOk && healthOk !== false;
   log(ok ? `\n✓ upgrade complete — core ${fromVersion || '(none)'} → ${targetVersion}` : `\n! upgrade finished with warnings — review above.`);
-  return { ok, fromVersion, toVersion: targetVersion, versionOk, healthOk, ledger: ledger.ok };
+  return { ok, fromVersion, toVersion: targetVersion, versionOk, healthOk, ledger: ledger.ok, pin };
 }
 
 function parseArgs(argv) {
@@ -811,6 +947,8 @@ function parseArgs(argv) {
     note: arg('--note', argv),
     pinPath: arg('--pin-path', argv),
     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
+    gitRemote: arg('--git-remote', argv),
     dryRun: hasFlag('--dry-run', argv),
     force: hasFlag('--force', argv),
     skipMigrate: hasFlag('--skip-migrate', argv),
@@ -867,7 +1005,7 @@ async function main(argv = process.argv.slice(2)) {
 module.exports = {
   runUpgrade, parseArgs, main, rollback,
   versionFromTgzPath, versionFromDep, readInstalledCoreVersion, readPinnedCoreVersion, writePin, writeRegistryPin, restorePin,
-  vendorTarball, gitTreeClean, preflightModules, reportModulePreflight, npmInstall, runMigrate, regenerateApiArtifacts, regenerateNavDocs, NAV_WHOLE_FILE_GENERATORS, missingDocAssets, healDocAssets, DOC_ASSET_GENERATORS, restartService, recordLedger, pollHealth,
+  vendorTarball, gitTreeClean, persistPin, dirtyPinFiles, gitCurrentBranch, PIN_FILES, preflightDbIdentity, preflightModules, reportModulePreflight, npmInstall, runMigrate, regenerateApiArtifacts, regenerateNavDocs, NAV_WHOLE_FILE_GENERATORS, missingDocAssets, healDocAssets, DOC_ASSET_GENERATORS, restartService, recordLedger, pollHealth,
   readManifest, resolveReferenceManifest, verifyInstalledPin, // task 1002216 (audit H8) — integrity-pin verification
   CORE_PKG, ARTIFACT,
 };

package/src/module-api.js

@@ -569,8 +569,10 @@ const { validateOrRespond, LIMITS, parseId, asyncHandler, corsPublicGet, parsePa
 //         landed since 1.19.69 with no explicit bump. run 31612248859. (task 1002620)
 //   1.19.71 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
 //         landed since 1.19.70 with no explicit bump. run 31613220077. (task 1002620)
+//   1.19.72 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+//         landed since 1.19.71 with no explicit bump. run 31617976225. (task 1002620)
 // ---------------------------------------------------------------------------
-const CORE_VERSION = '1.19.71'; // CI auto-patch carrier (ADR 0161); see changelog above
+const CORE_VERSION = '1.19.72'; // CI auto-patch carrier (ADR 0161); see changelog above
 
 // A namespaced logger so a module's log lines are attributable + consistent.
 // Usage: const log = api.logger('dev-box'); log.info('mounted');

package/tests/upgrade.mjs

@@ -181,7 +181,11 @@ t('full: pre-flight → pin → install → migrate → materialize → restart
   // steps ran, in the expected order
   assert.deepEqual(
     calls.filter((c) => c.startsWith('npm') || c.startsWith('git') || c.startsWith('systemctl')),
-    ['git status --porcelain', 'npm install --no-audit --no-fund', 'npm run migrate', 'systemctl restart emersonian.service']
+    // The trailing `git status` is persistPin's read-only look at whether the new
+    // pin is committed (task 1002712). It runs LAST — after verify — and without
+    // --commit-pin it only warns, so no git add/commit/push appears here.
+    ['git status --porcelain', 'npm install --no-audit --no-fund', 'npm run migrate', 'systemctl restart emersonian.service',
+      'git status --porcelain -- package.json package-lock.json']
   );
   // materialize pointed at the freshly-installed core
   assert.ok(materialized && materialized.coreRoot.endsWith(join('node_modules', '@bongos', 'core')));

package/tests/upgrade_persist_pin.mjs

@@ -0,0 +1,191 @@
+// tests/upgrade_persist_pin.mjs
+//
+// Covers persistPin (task 1002712) — the step that makes a core bump DURABLE.
+//
+// The bug: `bongos upgrade` rewrote package.json + package-lock.json in the
+// working tree and stopped. deploy.sh short-circuits while HEAD == origin/main,
+// so the upgraded-but-uncommitted tree survived and looked done — health-green,
+// ledger-recorded. Then any later push moved origin/main, deploy.sh ran
+// `git reset --hard origin/main`, the pin reverted, the lockfile hash changed,
+// and `npm ci` reinstalled the OLD core. Silent at every step.
+//
+// cloudbongos.com lost thirteen releases this way: two successful
+// `auto-subscription (patch)` rows in core_upgrades whose result no longer
+// existed on disk.
+//
+// `run` is injected throughout, so nothing here touches a real repo, remote, or
+// network — the assertions are on the git argv persistPin CHOOSES.
+//
+// Run:  node --test tests/upgrade_persist_pin.mjs
+
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { createRequire } from 'node:module';
+
+const require = createRequire(import.meta.url);
+const { persistPin, dirtyPinFiles, preflightDbIdentity, PIN_FILES } = require('../scripts/gds/upgrade.js');
+
+// A fake `run` driven by a table of [matcher, result]. Records every invocation.
+function fakeRun(handlers = {}) {
+  const calls = [];
+  const fn = (cmd, args) => {
+    calls.push([cmd, ...args].join(' '));
+    const sub = args[0];
+    const h = handlers[sub];
+    if (typeof h === 'function') return h(args);
+    return h || { status: 0, stdout: '' };
+  };
+  fn.calls = calls;
+  return fn;
+}
+
+const DIRTY = { status: 0, stdout: ' M package.json\n M package-lock.json\n' };
+const CLEAN = { status: 0, stdout: '' };
+const NOT_A_REPO = { status: 128, stdout: '', error: null };
+const ON_MAIN = { status: 0, stdout: 'main\n' };
+
+const base = { instanceDir: '/srv/inst', fromVersion: '1.19.56', toVersion: '1.19.69' };
+const quiet = () => {};
+
+test('a non-git instance is simply out of scope', () => {
+  const run = fakeRun({ status: NOT_A_REPO });
+  const r = persistPin({ ...base, commitPin: true }, run, quiet, quiet);
+  assert.equal(r.applicable, false);
+  assert.ok(!run.calls.some((c) => c.includes('commit')), 'must not try to commit');
+});
+
+test('an already-matching pin is a no-op', () => {
+  const run = fakeRun({ status: CLEAN });
+  const r = persistPin({ ...base, commitPin: true }, run, quiet, quiet);
+  assert.equal(r.applicable, false);
+  assert.ok(!run.calls.some((c) => c.includes('commit')));
+});
+
+test('without --commit-pin it WARNS and names the revert mechanism', () => {
+  // The silence is the bug, so the warning is the deliverable.
+  const warnings = [];
+  const run = fakeRun({ status: DIRTY, 'rev-parse': ON_MAIN });
+  const r = persistPin({ ...base, commitPin: false }, run, quiet, (m) => warnings.push(m));
+
+  assert.equal(r.warned, true);
+  assert.equal(r.committed, false);
+  assert.ok(!run.calls.some((c) => c.includes('git commit')), 'must NOT commit without the flag');
+
+  const text = warnings.join('\n');
+  assert.match(text, /PIN NOT COMMITTED/);
+  assert.match(text, /reset --hard/, 'names the mechanism that reverts it');
+  assert.match(text, /npm ci/, 'and that npm ci then reinstalls the old core');
+  assert.match(text, /1\.19\.56/, 'names the version it would fall back to');
+  assert.match(text, /--commit-pin/, 'and the fix');
+});
+
+test('with --commit-pin it stages, commits, and pushes to the tracked branch', () => {
+  const run = fakeRun({ status: DIRTY, 'rev-parse': ON_MAIN });
+  const r = persistPin({ ...base, commitPin: true }, run, quiet, quiet);
+
+  assert.deepEqual(r, { applicable: true, committed: true, pushed: true, dirty: PIN_FILES });
+  assert.ok(run.calls.some((c) => c === `git add ${PIN_FILES.join(' ')}`), 'stages exactly the pin files');
+  assert.ok(run.calls.some((c) => /^git commit -m pin @bongos\/core 1\.19\.69 \(was 1\.19\.56\)$/.test(c)),
+    `commit message names both versions; got ${JSON.stringify(run.calls)}`);
+  assert.ok(run.calls.some((c) => c === 'git push origin HEAD:main'), 'pushes to the branch it is on');
+});
+
+test('a detached HEAD still pushes somewhere sane', () => {
+  const run = fakeRun({ status: DIRTY, 'rev-parse': { status: 0, stdout: 'HEAD\n' } });
+  persistPin({ ...base, commitPin: true }, run, quiet, quiet);
+  assert.ok(run.calls.some((c) => c === 'git push origin HEAD:main'), 'falls back to main');
+});
+
+test('--git-remote is honoured', () => {
+  const run = fakeRun({ status: DIRTY, 'rev-parse': ON_MAIN });
+  persistPin({ ...base, commitPin: true, remote: 'deploy' }, run, quiet, quiet);
+  assert.ok(run.calls.some((c) => c === 'git push deploy HEAD:main'));
+});
+
+test('a FAILED PUSH is loud — committed-but-unpushed is still doomed', () => {
+  // deploy.sh resets to the REMOTE, so a local commit alone saves nothing. This
+  // must never read as success.
+  const warnings = [];
+  const run = fakeRun({ status: DIRTY, 'rev-parse': ON_MAIN, push: { status: 1, stdout: '' } });
+  const r = persistPin({ ...base, commitPin: true }, run, quiet, (m) => warnings.push(m));
+
+  assert.equal(r.committed, true);
+  assert.equal(r.pushed, false);
+  assert.equal(r.error, 'git push failed');
+  assert.match(warnings.join('\n'), /still not durable/i);
+});
+
+test('a failed commit does not claim to have pushed', () => {
+  const run = fakeRun({ status: DIRTY, 'rev-parse': ON_MAIN, commit: { status: 1, stdout: '' } });
+  const r = persistPin({ ...base, commitPin: true }, run, quiet, quiet);
+  assert.equal(r.committed, false);
+  assert.equal(r.pushed, false);
+  assert.ok(!run.calls.some((c) => c.startsWith('git push')), 'must not push an uncommitted pin');
+});
+
+test('--dry-run describes the commit without making one', () => {
+  const run = fakeRun({ status: DIRTY, 'rev-parse': ON_MAIN });
+  const r = persistPin({ ...base, commitPin: true, dryRun: true }, run, quiet, quiet);
+  assert.equal(r.dryRun, true);
+  assert.equal(r.committed, false);
+  assert.ok(!run.calls.some((c) => c.includes('git commit') || c.includes('git push')));
+});
+
+test('the copy-pasteable fix line is shell-quoted', () => {
+  // Nothing executes this string — it is printed for a human to paste — but a
+  // branch or remote carrying shell metacharacters must not misbehave when it is.
+  const warnings = [];
+  const run = fakeRun({ status: DIRTY, 'rev-parse': { status: 0, stdout: "main; rm -rf ~\n" } });
+  persistPin({ ...base, commitPin: false }, run, quiet, (m) => warnings.push(m));
+  const cmd = warnings.find((w) => w.includes('git -C'));
+  assert.ok(cmd, 'a paste-ready command is offered');
+  // The payload may appear — what matters is that it is INSIDE single quotes, so a
+  // paste runs one git command rather than two.
+  assert.match(cmd, /push '[^']*' 'HEAD:main; rm -rf ~'/, 'quoted as a single argument');
+  // Balanced quoting is the real property: an odd count would mean a value broke out.
+  assert.equal((cmd.match(/'/g) || []).length % 2, 0, 'every quote is closed');
+});
+
+// ── preflightDbIdentity (task 1002712) ──────────────────────────────────────
+// migrate.sh uses peer auth, so `sudo bongos upgrade` connects as root, which is
+// almost never a Postgres role. That surfaced as a raw FATAL mid-run, AFTER the
+// pin had moved, triggering a full auto-rollback for an operator mistake.
+
+test('a missing Postgres role is caught BEFORE anything moves', () => {
+  const run = () => ({ status: 2, stderr: 'psql: error: FATAL:  role "root" does not exist\n', stdout: '' });
+  const r = preflightDbIdentity({ instanceDir: '/srv/inst', db: 'cloudbongos' }, run);
+  assert.equal(r.ok, false);
+  assert.equal(r.role, 'root');
+  assert.match(r.reason, /current OS user/i, 'explains peer auth');
+  assert.match(r.reason, /sudo/, 'and names sudo as the likely cause');
+});
+
+test('a reachable database passes quietly', () => {
+  const r = preflightDbIdentity({ instanceDir: '/srv/inst' }, () => ({ status: 0, stdout: '1\n' }));
+  assert.equal(r.ok, true);
+  assert.equal(r.skipped, undefined);
+});
+
+test('an unrelated psql failure is NOT turned into a refusal', () => {
+  // Only the identity problem is diagnosable here; everything else stays migrate's
+  // business, so a pre-check quirk can never block an otherwise fine upgrade.
+  const run = () => ({ status: 2, stderr: 'could not connect to server: No such file or directory\n', stdout: '' });
+  const r = preflightDbIdentity({ instanceDir: '/srv/inst' }, run);
+  assert.equal(r.ok, true);
+  assert.ok(r.skipped, 'defers rather than refusing');
+});
+
+test('no psql on PATH defers instead of refusing', () => {
+  const r = preflightDbIdentity({ instanceDir: '/srv/inst' }, () => ({ error: new Error('ENOENT') }));
+  assert.equal(r.ok, true);
+  assert.ok(r.skipped);
+});
+
+test('dirtyPinFiles only ever reports the pin files', () => {
+  // It scopes `git status` to PIN_FILES, so unrelated instance edits (a config
+  // tweak, a doc) can never be swept into the pin commit.
+  const run = fakeRun({ status: DIRTY });
+  dirtyPinFiles('/srv/inst', run);
+  const statusCall = run.calls.find((c) => c.startsWith('git status'));
+  assert.match(statusCall, /--\s+package\.json package-lock\.json$/, 'pathspec-limited');
+});