@bongos/core 1.19.1032 → 1.19.1033

package/tests/ship_land_conflict.mjs

@@ -0,0 +1,181 @@
+// tests/ship_land_conflict.mjs — a CONFLICTING PR is named while the land waits (task 1003499).
+//
+// WHY. GitHub's auto-merge waits for a clean merge as well as green checks, so a PR
+// whose branch conflicts with main sits open under a fully green rollup and never
+// merges. PR #497 did that for ~25 minutes while the ship's poll printed nothing and
+// then signed off with "auto-merge is armed ... NOT a failure" and a card saying
+// "Nothing to do" — so the completion card read "landing automatically" over a land
+// that could not happen. These tests drive the REAL poll loops (pollCiDeploy, the
+// gh path; pollServerPublish, the server path) with a scripted PR, and pin both
+// halves: the conflict is said once, when it appears, and a wait that ends
+// conflicting is a bail with the fix named, never the pending banner.
+//
+// Run:  node tests/ship_land_conflict.mjs
+
+import { strict as assert } from 'node:assert';
+import { createRequire } from 'node:module';
+
+process.env.BONGOS_SURFACE = 'agent'; // the plain cards print on the agent surface only
+
+const require = createRequire(import.meta.url);
+const land = require('../scripts/gds/ship-land.js');
+const { CARDS } = require('../scripts/gds/plain-cards.js');
+
+let passed = 0;
+let failed = 0;
+async function test(name, fn) {
+  try { await fn(); passed++; console.log(`  ok  ${name}`); }
+  catch (err) { failed++; console.log(`  FAIL ${name}`); console.log(`     ${err.message}`); }
+}
+
+// Run fn with console.log captured; returns { result, out }.
+async function capture(fn) {
+  const lines = [];
+  const real = console.log;
+  console.log = (...a) => { lines.push(a.join(' ')); };
+  try { return { result: await fn(), out: lines.join('\n') }; }
+  finally { console.log = real; }
+}
+const count = (hay, needle) => hay.split(needle).length - 1;
+const CONFLICT_LINE = 'the PR CONFLICTS with main';
+const PENDING_BANNER = 'This is NOT a failure';
+
+// A scripted `gh pr view`: the Nth read answers with states[N] (the last one repeats).
+function ghScript(states, calls = []) {
+  let i = 0;
+  return (args) => {
+    calls.push(args.join(' '));
+    const s = states[Math.min(i, states.length - 1)];
+    i++;
+    return typeof s === 'function' ? s(args) : s;
+  };
+}
+const OPEN = (mergeable, mergeStateStatus) => ({ state: 'OPEN', mergeCommit: null, mergeable, mergeStateStatus });
+const noPause = () => {};
+
+// ---- the pure half ----
+
+await test('prConflicting reads both shapes it is handed, and a failed read is not a conflict', () => {
+  // gh pr view (camelCase)
+  assert.equal(land.prConflicting(OPEN('CONFLICTING', 'DIRTY')), true);
+  assert.equal(land.prConflicting(OPEN('UNKNOWN', 'DIRTY')), true);
+  assert.equal(land.prConflicting(OPEN('CONFLICTING', 'UNKNOWN')), true);
+  assert.equal(land.prConflicting(OPEN('MERGEABLE', 'CLEAN')), false);
+  assert.equal(land.prConflicting(OPEN('MERGEABLE', 'BLOCKED')), false, 'a red or pending check is not a conflict');
+  assert.equal(land.prConflicting(OPEN('UNKNOWN', 'UNKNOWN')), false, 'mergeability still computing is not a conflict');
+  // publish-status merge_driver (snake_case, as mergeIfGreen returns it)
+  assert.equal(land.prConflicting({ reason: 'merge_conflict', mergeable: 'CONFLICTING', merge_state: 'DIRTY' }), true);
+  assert.equal(land.prConflicting({ reason: null, merge_state: 'DIRTY' }), true);
+  assert.equal(land.prConflicting({ reason: 'failing_check:unit', mergeable: 'MERGEABLE', merge_state: 'BLOCKED' }), false);
+  for (const nothing of [null, undefined, {}]) assert.equal(land.prConflicting(nothing), false);
+});
+
+await test('the conflict lines name the fix — merge main in, then re-run this task\'s ship — and carry the card', () => {
+  const text = land.conflictPrLines(4242).join('\n');
+  assert.ok(text.includes(CONFLICT_LINE), text);
+  assert.ok(text.includes('git merge origin/main'), 'merge, never rebase: the branch is already published (strand-fix case C)');
+  assert.ok(!/rebase/.test(text), 'a rebase makes every later push non-fast-forward');
+  assert.ok(text.includes('node scripts/gds/ship.js 4242'), 'the resume names THIS task');
+  assert.ok(text.includes(CARDS.merge_conflict.happened), 'the plain-words card for merge_conflict follows');
+});
+
+await test('landConflicted is a bail with the fix as its next step, never pending', async () => {
+  const { result } = await capture(() => land.landConflicted(4242));
+  assert.equal(result.ok, false);
+  assert.equal(result.pending, false, 'pending is what makes the card say "landing automatically"');
+  assert.match(result.reason, /conflicts with main/);
+  assert.equal(result.nextStep, '/strand-fix 4242');
+  assert.equal(result.bailId, null, 'untagged, so ship-merge never reroutes it into the PR path it already took');
+});
+
+// ---- the gh path: pollCiDeploy ----
+
+await test('pollCiDeploy: a PR conflicting for the whole wait bails, says so ONCE, and never prints the pending banner', async () => {
+  const calls = [];
+  const { result, out } = await capture(() => land.pollCiDeploy(4242, 'task-4242', 'abc', {
+    ghJson: ghScript([OPEN('CONFLICTING', 'DIRTY')], calls), pause: noPause,
+  }));
+  assert.equal(result.pending, false, 'a conflicting PR is not "landing automatically"');
+  assert.equal(result.nextStep, '/strand-fix 4242');
+  assert.equal(count(out, CONFLICT_LINE), 1, `said once when it appeared, not on every poll:\n${out}`);
+  assert.ok(!out.includes(PENDING_BANNER), 'the "NOT a failure" banner is for a land that is on its way');
+  assert.ok(!out.includes(CARDS.land_pending.next), 'nor the "Nothing to do" card');
+  assert.ok(calls[0].includes('mergeable') && calls[0].includes('mergeStateStatus'), `the poll asks GitHub whether it can merge: ${calls[0]}`);
+});
+
+await test('pollCiDeploy: a mergeable PR that merely outlasts the wait is still pending, as before', async () => {
+  const { result, out } = await capture(() => land.pollCiDeploy(4242, 'task-4242', 'abc', {
+    ghJson: ghScript([OPEN('MERGEABLE', 'BLOCKED')]), pause: noPause,
+  }));
+  assert.equal(result.pending, true);
+  assert.ok(out.includes(PENDING_BANNER));
+  assert.equal(count(out, CONFLICT_LINE), 0);
+});
+
+await test('pollCiDeploy: a conflict the server heals inside the window is announced, then the wait ends pending', async () => {
+  const states = [OPEN('UNKNOWN', 'UNKNOWN'), OPEN('CONFLICTING', 'DIRTY'), OPEN('CONFLICTING', 'DIRTY'), OPEN('MERGEABLE', 'BLOCKED')];
+  const { result, out } = await capture(() => land.pollCiDeploy(4242, 'task-4242', 'abc', {
+    ghJson: ghScript(states), pause: noPause,
+  }));
+  assert.equal(count(out, CONFLICT_LINE), 1);
+  assert.equal(result.pending, true, 'healed: the checks re-run and auto-merge is armed again');
+});
+
+await test('pollCiDeploy: a heal undone by main moving on is announced again, and the verdict is the LAST state', async () => {
+  const states = [OPEN('CONFLICTING', 'DIRTY'), OPEN('MERGEABLE', 'BLOCKED'), OPEN('CONFLICTING', 'DIRTY')];
+  const { result, out } = await capture(() => land.pollCiDeploy(4242, 'task-4242', 'abc', {
+    ghJson: ghScript(states), pause: noPause,
+  }));
+  assert.equal(count(out, CONFLICT_LINE), 2);
+  assert.equal(result.pending, false);
+});
+
+await test('pollCiDeploy: a gh that predates the mergeable fields falls back to the old read, no worse than before', async () => {
+  const calls = [];
+  const oldGh = (args) => (args.join(' ').includes('mergeable') ? null : { state: 'OPEN', mergeCommit: null });
+  const { result, out } = await capture(() => land.pollCiDeploy(4242, 'task-4242', 'abc', {
+    ghJson: ghScript([oldGh], calls), pause: noPause,
+  }));
+  assert.equal(result.pending, true, 'with nothing to say about mergeability, the old verdict stands');
+  assert.equal(count(out, CONFLICT_LINE), 0);
+  assert.ok(calls.some((c) => c.endsWith('--json state,mergeCommit')), 'the two-field read was the fallback');
+});
+
+await test('pollCiDeploy: a failed read keeps the last answer instead of forgetting the conflict', async () => {
+  const states = [OPEN('CONFLICTING', 'DIRTY'), null];
+  const { result } = await capture(() => land.pollCiDeploy(4242, 'task-4242', 'abc', {
+    ghJson: ghScript(states), pause: noPause,
+  }));
+  assert.equal(result.pending, false, 'a gh hiccup at the end must not turn a conflict back into "landing automatically"');
+});
+
+// ---- the server path: pollServerPublish ----
+
+const status = (merge_driver) => async () => ({
+  ok: true, data: { merged: false, pr_state: 'open', deploy_status: null, reconcile_blocked: null, merge_driver },
+});
+
+await test('pollServerPublish: a merge_conflict from the server is named once, and the timeout bails', async () => {
+  const { result, out } = await capture(() => land.pollServerPublish(4242, 'task-4242', {
+    readStatus: status({ reason: 'merge_conflict', mergeable: 'CONFLICTING', merge_state: 'DIRTY', rollup_state: 'SUCCESS' }),
+    pause: noPause,
+  }));
+  assert.equal(count(out, CONFLICT_LINE), 1, out);
+  assert.ok(!out.includes('is RED'), 'green checks: a conflict is not a red PR');
+  assert.ok(!out.includes(PENDING_BANNER));
+  assert.equal(result.pending, false);
+  assert.equal(result.nextStep, '/strand-fix 4242');
+});
+
+await test('pollServerPublish: a red check still reads RED and still waits pending — this change does not touch it', async () => {
+  const { result, out } = await capture(() => land.pollServerPublish(4242, 'task-4242', {
+    readStatus: status({ reason: 'failing_check:unit', mergeable: 'MERGEABLE', merge_state: 'BLOCKED' }),
+    pause: noPause,
+  }));
+  assert.ok(out.includes('is RED'));
+  assert.equal(count(out, CONFLICT_LINE), 0);
+  assert.equal(result.pending, true);
+});
+
+console.log(`\nship-land conflict signal (task 1003499) tests: ${passed} passed, ${failed} failed`);
+process.exitCode = failed > 0 ? 1 : 0;

package/tests/ship_preflight.mjs

@@ -12,9 +12,12 @@ import os from 'node:os';
 import path from 'node:path';
 
 const require = createRequire(import.meta.url);
-const { parsePorcelain, trackedDirty, classifyEmptyShip, cleanupMacFinderDupRefs, findMainWorktree, closeoutPlan } = require(
-  '../modules/lifecycle/ship-preflight.js',
-);
+const {
+  parsePorcelain, trackedDirty, classifyEmptyShip, cleanupMacFinderDupRefs, findMainWorktree, closeoutPlan,
+  untrackedPaths, untrackedLeftBehind, untrackedWarningLines,
+} = require('../modules/lifecycle/ship-preflight.js');
+// task 1001436: the preflight step itself + the ship-input resolver it is handed.
+const { preflight, shipInputPaths } = require('../scripts/gds/ship-preflight-steps.js');
 
 const tests = [];
 const test = (name, fn) => tests.push({ name, fn });
@@ -352,6 +355,160 @@ test('closeoutPlan: stashLabel embeds the task id', () => {
   assert.equal(closeoutPlan('?? x\n', 1234).stashLabel, 'otb-postship-1234');
 });
 
+// ---- the residual phantom ship: untracked files left behind (task 1001436) ----
+// A branch with REAL committed work ships; a new file beside it that was never
+// `git add`ed silently does not. The preflight now names those files — a warning,
+// never a refusal (trackedDirty must keep ignoring scratch).
+
+test('untrackedPaths: only ?? lines, in order, unquoted; tracked changes are not listed', () => {
+  const out = ' M src/a.js\n?? tests/new_case.mjs\nA  src/b.js\n?? "docs/with space.md"\n';
+  assert.deepEqual(untrackedPaths(out), ['tests/new_case.mjs', 'docs/with space.md']);
+  assert.deepEqual(untrackedPaths(''), []);
+  assert.deepEqual(untrackedPaths(null), []);
+});
+
+test('untrackedLeftBehind: nothing committed → [] (the empty-diff guard already refuses and lists them)', () => {
+  const out = '?? tests/new_case.mjs\n';
+  assert.deepEqual(untrackedLeftBehind(out, { committedFileCount: 0 }), []);
+  assert.deepEqual(untrackedLeftBehind(out), [], 'default opts behave as "nothing committed"');
+  // ...and that empty case is exactly the one classifyEmptyShip refuses on:
+  assert.equal(classifyEmptyShip(out).reason, 'uncommitted-work');
+});
+
+test('untrackedLeftBehind: committed work + an untracked file → that file is named', () => {
+  const out = ' M src/unrelated.js\n?? tests/new_case.mjs\n?? docs/adr/0999-x.md\n';
+  assert.deepEqual(untrackedLeftBehind(out, { committedFileCount: 3 }), ['tests/new_case.mjs', 'docs/adr/0999-x.md']);
+});
+
+test('untrackedLeftBehind: the ship\'s own input files are excluded, whatever their spelling', () => {
+  const out = '?? notes.md\n?? summary.txt\n?? shots/after.png\n?? tests/new_case.mjs\n';
+  const inputs = ['./notes.md', 'summary.txt', 'shots\\after.png'];
+  assert.deepEqual(untrackedLeftBehind(out, { committedFileCount: 1, inputs }), ['tests/new_case.mjs']);
+});
+
+test('untrackedWarningLines: [] when there is nothing to say', () => {
+  assert.deepEqual(untrackedWarningLines([]), []);
+  assert.deepEqual(untrackedWarningLines(null), []);
+});
+
+test('untrackedWarningLines: names the count, the task, each file, and says it does not block', () => {
+  const text = untrackedWarningLines(['tests/new_case.mjs', 'docs/x.md'], { taskId: 1001436 }).join('\n');
+  assert.match(text, /2 untracked file\(s\) in this worktree will NOT ship with task 1001436/);
+  assert.match(text, /- tests\/new_case\.mjs/);
+  assert.match(text, /- docs\/x\.md/);
+  assert.match(text, /Warning only — not blocking; the ship proceeds/);
+});
+
+test('untrackedWarningLines: a long list is capped, with the remainder counted', () => {
+  const files = Array.from({ length: 17 }, (_, i) => `scratch/f${i}.txt`);
+  const lines = untrackedWarningLines(files, { cap: 15 });
+  assert.equal(lines.filter((l) => l.startsWith('    - ')).length, 15);
+  assert.ok(lines.includes('    … and 2 more'));
+  assert.match(lines.join('\n'), /17 untracked file\(s\)/);
+});
+
+test('shipInputPaths: prose/visual flags resolve to repo-relative paths; stdin and out-of-tree paths add nothing', () => {
+  const root = fs.realpathSync.native(fs.mkdtempSync(path.join(os.tmpdir(), 'otb-shipinputs-')));
+  const outside = fs.realpathSync.native(fs.mkdtempSync(path.join(os.tmpdir(), 'otb-shipinputs-out-')));
+  try {
+    fs.mkdirSync(path.join(root, 'sub'));
+    for (const f of ['notes.md', 'summary.txt', 'sub/shot.png', 'resp.md']) fs.writeFileSync(path.join(root, f), 'x');
+    fs.writeFileSync(path.join(outside, 'notes.md'), 'x');
+    const args = [
+      '1001436', '--notes-file', 'notes.md', '--summary-file=summary.txt',
+      '--visual', path.join(root, 'sub', 'shot.png'), '--response-file', '-',
+    ];
+    assert.deepEqual(shipInputPaths(args, { cwd: root, repoRoot: root }), ['notes.md', 'summary.txt', 'sub/shot.png']);
+    // Run from a subdirectory: the relative flag value resolves against cwd, the result against the root.
+    assert.deepEqual(shipInputPaths(['1', '--response-file', '../resp.md'], { cwd: path.join(root, 'sub'), repoRoot: root }), ['resp.md']);
+    // A file outside the checkout cannot be an untracked file in it.
+    assert.deepEqual(shipInputPaths(['1', '--notes-file', path.join(outside, 'notes.md')], { cwd: root, repoRoot: root }), []);
+    // A flag with no value (last token) is ignored rather than resolved to the root.
+    assert.deepEqual(shipInputPaths(['1', '--notes-file'], { cwd: root, repoRoot: root }), []);
+    assert.deepEqual(shipInputPaths([], { cwd: root, repoRoot: root }), []);
+  } finally {
+    fs.rmSync(root, { recursive: true, force: true });
+    fs.rmSync(outside, { recursive: true, force: true });
+  }
+});
+
+// The behaviour, not just the helpers: run the REAL preflight() in a throwaway
+// repo with a local "origin", and read what it prints. Two worlds: a branch
+// carrying committed work (the warning must fire, minus inputs and ignored
+// files), and a branch with nothing committed (it must stay silent — the
+// empty-diff guard owns that case).
+function withPreflightRepo(fn) {
+  const tmp = fs.realpathSync.native(fs.mkdtempSync(path.join(os.tmpdir(), 'otb-untracked-')));
+  const origin = path.join(tmp, 'origin.git');
+  const work = path.join(tmp, 'work');
+  const run = (cmd, cwd = work) => execSync(cmd, { cwd, stdio: ['ignore', 'pipe', 'pipe'] });
+  const prevCwd = process.cwd();
+  try {
+    execSync(`git init -q --bare -b main "${origin}"`);
+    execSync(`git clone -q "${origin}" "${work}"`, { stdio: ['ignore', 'pipe', 'pipe'] });
+    run('git config user.email t@t.t && git config user.name t && git config commit.gpgsign false');
+    run('git checkout -q -b main');
+    fs.writeFileSync(path.join(work, '.gitignore'), '*.log\n');
+    fs.writeFileSync(path.join(work, 'a.txt'), 'x');
+    run('git add -A && git commit -q -m init && git push -q origin main');
+    process.chdir(work);
+    return fn({ work, run });
+  } finally {
+    process.chdir(prevCwd);
+    fs.rmSync(tmp, { recursive: true, force: true });
+  }
+}
+
+function capturePreflight(claim, opts) {
+  const out = [];
+  const err = [];
+  const log = console.log;
+  const error = console.error;
+  console.log = (...a) => out.push(a.join(' '));
+  console.error = (...a) => err.push(a.join(' '));
+  try {
+    return { result: preflight(claim, opts), out: out.join('\n'), err: err.join('\n') };
+  } finally {
+    console.log = log;
+    console.error = error;
+  }
+}
+
+test('preflight (real git): committed work + a forgotten new file → warns, still OK, inputs + ignored files unlisted', () => {
+  withPreflightRepo(({ work, run }) => {
+    run('git checkout -q -b feature');
+    fs.mkdirSync(path.join(work, 'src'));
+    fs.writeFileSync(path.join(work, 'src', 'fix.js'), 'module.exports = 1;\n');
+    run('git add src/fix.js && git commit -q -m "the committed half"');
+    fs.mkdirSync(path.join(work, 'tests'));
+    fs.writeFileSync(path.join(work, 'tests', 'forgot.mjs'), '// never git-added\n');
+    fs.writeFileSync(path.join(work, 'notes.md'), 'handoff notes\n');
+    fs.writeFileSync(path.join(work, 'debug.log'), 'ignored by .gitignore\n');
+
+    const { result, out, err } = capturePreflight({ task_id: 4242, head_sha: null }, { inputFiles: ['notes.md'] });
+    assert.equal(result.ok, true, 'a warning must never refuse the ship');
+    // A wholly-untracked directory is still named file by file (--untracked-files=all).
+    assert.deepEqual(result.untrackedLeftBehind, ['tests/forgot.mjs']);
+    assert.match(err, /1 untracked file\(s\) in this worktree will NOT ship with task 4242/);
+    assert.match(err, /- tests\/forgot\.mjs/);
+    assert.doesNotMatch(err, /notes\.md/, 'the ship\'s own --notes-file is not a deliverable');
+    assert.doesNotMatch(err, /debug\.log/, 'an ignored file is never listed');
+    assert.match(out, /preflight: tracked files clean \(1 untracked file\(s\) will not ship/);
+  });
+});
+
+test('preflight (real git): nothing committed on the branch → no untracked warning', () => {
+  withPreflightRepo(({ work, run }) => {
+    run('git checkout -q -b feature');
+    fs.writeFileSync(path.join(work, 'forgot.md'), 'never git-added\n');
+    const { result, out, err } = capturePreflight({ task_id: 4243, head_sha: null }, {});
+    assert.equal(result.ok, true);
+    assert.deepEqual(result.untrackedLeftBehind, []);
+    assert.doesNotMatch(err, /Untracked-file warning/);
+    assert.match(out, /preflight: working tree clean/);
+  });
+});
+
 // ---- runner ----
 
 let pass = 0;

package/tests/sweep_app_account.mjs

@@ -17,13 +17,17 @@ const REPO = path.join(path.dirname(fileURLToPath(import.meta.url)), '..');
 const skip = spawnSync('bash', ['-c', 'true']).error ? 'bash not on PATH' : false;
 const slash = (p) => p.replace(/\\/g, '/');
 
-function stubs() {
+// `bsdStat` swaps in macOS's stat, which refuses GNU's `-c` outright and names an owner
+// with `-f %Su` instead (task 1004170).
+function stubs({ bsdStat = false } = {}) {
   const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'sweep-stubs-'));
   const sudoLog = slash(path.join(dir, 'sudo.log'));
   const statLog = slash(path.join(dir, 'stat.log'));
   const bin = (name, body) => fs.writeFileSync(path.join(dir, name), `#!/usr/bin/env bash\n${body}\n`, { mode: 0o755 });
   bin('sudo', `echo "$*" >> "${sudoLog}"; exit 0`);
-  bin('stat', `echo "$*" >> "${statLog}"; echo checkout-owner`);
+  bin('stat', `echo "$*" >> "${statLog}"; ` + (bsdStat
+    ? 'case "$1 $2" in "-c "*) echo "stat: illegal option -- c" >&2; exit 1 ;; "-f %Su") echo checkout-owner ;; *) exit 1 ;; esac'
+    : 'echo checkout-owner'));
   bin('systemctl', 'exit 0');
   const lines = (f) => (fs.existsSync(f) ? fs.readFileSync(f, 'utf8').split('\n').filter(Boolean) : []);
   return { dir, sudo: () => lines(sudoLog), stat: () => lines(statLog) };
@@ -109,4 +113,13 @@ for (const [name, src] of [['address-park-sweep', PARK], ['stray-unit-sweep', ST
     assert.match(s.stat()[0] || '', new RegExp(`^-c %U .*${path.basename(inst)}$`), 'the instance root, not the package');
     assert.match(s.sudo()[0] || '', /^-n -u checkout-owner psql /);
   });
+
+  test(`${name}: on macOS, where stat refuses GNU's -c, the checkout's owner still acts (task 1004170)`, { skip }, () => {
+    // It used to read '' as the owner there and refuse with "cannot use '' as the app account".
+    const s = stubs({ bsdStat: true });
+    const inst = fs.mkdtempSync(path.join(os.tmpdir(), 'sweep-inst-'));
+    run(src, s, { INSTANCE_DIR: slash(inst) });
+    assert.deepEqual(s.stat().map((l) => l.split(' ').slice(0, 2).join(' ')), ['-c %U', '-f %Su'], 'GNU is asked first and BSD answers');
+    assert.match(s.sudo()[0] || '', /^-n -u checkout-owner psql /);
+  });
 }

package/tests/upgrade_migrate.mjs

@@ -0,0 +1,195 @@
+// tests/upgrade_migrate.mjs — `bongos upgrade` migrates an ADOPTED project that declares
+// no migrate script, instead of rolling itself back (task 1004274; found preparing the
+// task 1004047 catch-up pass).
+//
+// The catch-up pass could not reach mercury: an adopted Python/Flask project whose
+// package.json is exactly what the adopt layer mints — name, private, dependencies, no
+// scripts. upgrade.js migrated with `npm run migrate` only, so every upgrade of it died
+// at step 4, after the pin had moved and the new core was installed, and rolled back —
+// restarting a live app to change nothing — while the dry run reported nothing wrong.
+//
+// Pinned here: the fallback is the core's own migrate.sh, byte-identical to what a
+// scaffold's script runs; a declared script still wins; the dry run says which one will
+// run, on a line the Deploy page's pre-flight parser picks up; and the real command
+// resolves the instance even when whoever launched the upgrade left a stray INIT_CWD.
+//
+// Run:  node --test tests/upgrade_migrate.mjs
+
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { createRequire } from 'node:module';
+import { execFileSync } from 'node:child_process';
+import { mkdtempSync, mkdirSync, writeFileSync, readFileSync, realpathSync, symlinkSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const require = createRequire(import.meta.url);
+const { migratePlan, CORE_MIGRATE_SCRIPT } = require('../scripts/gds/upgrade-migrate.js');
+const u = require('../scripts/gds/upgrade.js');
+const init = require('../scripts/gds/init.js');
+const { parsePreflight } = require('../scripts/gds/provision-core-upgrade.js');
+
+const REPO_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const fixture = (prefix) => realpathSync(mkdtempSync(path.join(tmpdir(), prefix)));
+
+// A project exactly as the adopt layer leaves one that had no package.json of its own —
+// built BY that layer, so this cannot drift from what adoption really writes.
+function adoptedProject({ installed = '1.19.312' } = {}) {
+  const dir = fixture('upgrade-migrate-adopted-');
+  const { pkg, action } = init.mergeCoreDependency(null, { coreRange: `file:vendor/bongos-core-${installed}.tgz`, name: 'mercury' });
+  assert.equal(action, 'created', 'fixture: the adopt layer minted the package.json');
+  assert.deepEqual(Object.keys(pkg).sort(), ['dependencies', 'name', 'private'], 'fixture: mercury\'s real shape — no scripts at all');
+  writeFileSync(path.join(dir, 'package.json'), `${JSON.stringify(pkg, null, 2)}\n`);
+  const core = path.join(dir, 'node_modules', '@bongos', 'core');
+  mkdirSync(core, { recursive: true });
+  writeFileSync(path.join(core, 'package.json'), `${JSON.stringify({ name: '@bongos/core', version: installed })}\n`);
+  return dir;
+}
+
+function scaffoldedProject(scripts = { migrate: init.INSTANCE_MIGRATE_SCRIPT, start: init.INSTANCE_START_SCRIPT }) {
+  const dir = fixture('upgrade-migrate-scaffold-');
+  writeFileSync(path.join(dir, 'package.json'), `${JSON.stringify({ name: 'charter', private: true, scripts, dependencies: { '@bongos/core': '1.19.871' } }, null, 2)}\n`);
+  return dir;
+}
+
+// Records every spawn as "cmd args…" plus its options. The pre-flight's database
+// resolver is answered with a name (as the real one answers on a provisioned box), and
+// `npm install` flips the installed core to `installTo` — all a successful install needs
+// to look like here.
+function recordingRun(calls, { dir, installTo, db = 'mercury' } = {}) {
+  return (cmd, args = [], opts = {}) => {
+    calls.push({ line: `${cmd} ${args.join(' ')}`.trim(), opts });
+    if (cmd === 'git' && args[0] === 'status') return { status: 0, stdout: '' };
+    if (cmd === process.execPath && String(args[1] || '').includes('instanceDbName')) return { status: 0, stdout: db };
+    if (cmd === 'npm' && args[0] === 'install' && installTo) {
+      writeFileSync(path.join(dir, 'node_modules', '@bongos', 'core', 'package.json'), `${JSON.stringify({ name: '@bongos/core', version: installTo })}\n`);
+    }
+    return { status: 0, stdout: '' };
+  };
+}
+
+test('the fallback IS the scaffold\'s own migrate script, byte for byte', () => {
+  assert.equal(`bash ${CORE_MIGRATE_SCRIPT}`, init.INSTANCE_MIGRATE_SCRIPT,
+    'an adopted project must be migrated by exactly the command a greenfield scaffold declares');
+});
+
+test('a project with no migrate script is migrated by the core\'s migrate.sh, from its own root', () => {
+  const dir = adoptedProject();
+  const plan = migratePlan(dir, { env: { PATH: '/usr/bin', PGDATABASE: 'mercury', INIT_CWD: '/somewhere/else' } });
+  assert.equal(plan.via, 'core-script');
+  assert.equal(plan.cmd, 'bash');
+  assert.deepEqual(plan.args, [CORE_MIGRATE_SCRIPT]);
+  assert.equal(plan.env.INIT_CWD, dir, 'INIT_CWD is what npm run would set — the project, never an inherited stray');
+  assert.equal(plan.env.PGDATABASE, 'mercury', 'the database the runner named still reaches migrate.sh');
+  assert.match(plan.note, /declares no migrate script/);
+});
+
+test('scripts without a migrate entry, or a blank one, also fall back', () => {
+  assert.equal(migratePlan(scaffoldedProject({ start: 'node app.js' })).via, 'core-script');
+  assert.equal(migratePlan(scaffoldedProject({ migrate: '   ' })).via, 'core-script');
+});
+
+test('a declared migrate script still wins, whatever it says', () => {
+  for (const migrate of [init.INSTANCE_MIGRATE_SCRIPT, 'node scripts/own-migrate.js']) {
+    const plan = migratePlan(scaffoldedProject({ migrate }));
+    assert.equal(plan.via, 'npm-script');
+    assert.deepEqual([plan.cmd, ...plan.args], ['npm', 'run', 'migrate']);
+    assert.equal(plan.env, null, 'npm sets INIT_CWD itself, so nothing is overridden');
+    assert.equal(plan.note, null, 'the ordinary case adds no pre-flight line');
+  }
+});
+
+test('a missing or unparseable package.json keeps the old command rather than guessing', () => {
+  assert.equal(migratePlan(fixture('upgrade-migrate-empty-')).via, 'npm-script');
+  const bad = fixture('upgrade-migrate-bad-');
+  writeFileSync(path.join(bad, 'package.json'), '{ not json');
+  assert.equal(migratePlan(bad).via, 'npm-script');
+});
+
+test('runMigrate spawns the plan: npm on a scaffold, the core script on an adopted project', () => {
+  const calls = [];
+  u.runMigrate(scaffoldedProject(), recordingRun(calls));
+  const adopted = adoptedProject();
+  u.runMigrate(adopted, recordingRun(calls));
+  assert.equal(calls[0].line, 'npm run migrate');
+  assert.equal(calls[0].opts.env, undefined, 'the scaffold path inherits the environment exactly as before');
+  assert.equal(calls[1].line, `bash ${CORE_MIGRATE_SCRIPT}`);
+  assert.equal(calls[1].opts.cwd, adopted);
+  assert.equal(calls[1].opts.env.INIT_CWD, adopted);
+});
+
+test('a full registry upgrade of an adopted project migrates it instead of rolling back', async () => {
+  const dir = adoptedProject({ installed: '1.19.312' });
+  const calls = [];
+  const res = await u.runUpgrade(
+    { to: '1.19.1029', registry: true, instance: dir, service: 'mercury', healthCheck: false },
+    {
+      log: () => {}, err: () => {},
+      run: recordingRun(calls, { dir, installTo: '1.19.1029' }),
+      materialize: () => ({ skills: 0 }),
+      regenerateApiArtifacts: () => ({ ok: true, ran: [] }),
+      databaseUrl: '', pgDatabase: '',
+    },
+  );
+  const lines = calls.map((c) => c.line);
+  assert.equal(res.ok, true, `the upgrade completes: ${res.error || ''}`);
+  assert.ok(!res.rolledBack, 'and was not rolled back');
+  assert.ok(lines.includes(`bash ${CORE_MIGRATE_SCRIPT}`), 'the schema moved with the code');
+  assert.ok(!lines.includes('npm run migrate'), 'the missing script was never asked for');
+  assert.ok(lines.indexOf(`bash ${CORE_MIGRATE_SCRIPT}`) < lines.indexOf('systemctl restart mercury'), 'and migrate still runs before the restart that makes the code live');
+});
+
+test('the dry run names the fallback on a line the Deploy page\'s pre-flight shows', async () => {
+  const dir = adoptedProject();
+  const out = [];
+  const res = await u.runUpgrade(
+    { to: '1.19.1029', registry: true, instance: dir, dryRun: true },
+    { log: (m) => out.push(m), err: () => {}, run: recordingRun([]) },
+  );
+  assert.equal(res.ok, true);
+  const text = out.join('\n');
+  assert.match(text, new RegExp(`would: npm install → bash ${CORE_MIGRATE_SCRIPT.replace(/[.*+?^${}()|[\]\\/]/g, '\\$&')} →`));
+  const { checks } = parsePreflight(text);
+  assert.ok(checks.some((c) => /declares no migrate script/.test(c)), `the door's parser carries it: ${JSON.stringify(checks)}`);
+  assert.deepEqual(JSON.parse(readFileSync(path.join(dir, 'package.json'), 'utf8')).dependencies,
+    { '@bongos/core': 'file:vendor/bongos-core-1.19.312.tgz' }, 'and the dry run moved nothing');
+});
+
+test('the dry run of an ordinary scaffold is unchanged', async () => {
+  const dir = scaffoldedProject();
+  const core = path.join(dir, 'node_modules', '@bongos', 'core');
+  mkdirSync(core, { recursive: true });
+  writeFileSync(path.join(core, 'package.json'), `${JSON.stringify({ name: '@bongos/core', version: '1.19.871' })}\n`);
+  const out = [];
+  await u.runUpgrade({ to: '1.19.1029', registry: true, instance: dir, dryRun: true }, { log: (m) => out.push(m), err: () => {}, run: recordingRun([]) });
+  const text = out.join('\n');
+  assert.match(text, /would: npm install → npm run migrate →/);
+  assert.doesNotMatch(text, /declares no migrate script/);
+});
+
+// The real migrate.sh, through its DB-free --print-roots seam (tests/migrate_root_resolution.mjs):
+// the fallback must find the PROJECT, not the core package and not a stray INIT_CWD.
+test('the real fallback command resolves the project as its instance root, despite a stray INIT_CWD', (t) => {
+  const dir = adoptedProject();
+  writeFileSync(path.join(dir, 'bongos.config.json'), JSON.stringify({ instanceRoot: '.' }));
+  const core = path.join(dir, 'node_modules', '@bongos', 'core');
+  // Swap the stub for the real core, so the script that runs is the one that ships.
+  execFileSync(process.execPath, ['-e', 'require("fs").rmSync(process.argv[1], { recursive: true, force: true })', core]);
+  try { symlinkSync(REPO_ROOT, core, 'dir'); } catch (e) {
+    if (e.code === 'EPERM' || e.code === 'EACCES') return t.skip('this platform refuses symlinks without elevation');
+    throw e;
+  }
+  const stray = fixture('upgrade-migrate-stray-');
+  const base = { ...process.env, INIT_CWD: stray };
+  for (const k of Object.keys(base)) if (/_INSTANCE_ROOT$/.test(k)) delete base[k];
+  const rootsOf = (out) => Object.fromEntries(out.split('\n').map((l) => /^(INVOKE_CWD|CORE_ROOT|INSTANCE_ROOT)=(.*)$/.exec(l)).filter(Boolean).map((m) => [m[1], m[2]]));
+
+  const plan = migratePlan(dir, { env: base });
+  const roots = rootsOf(execFileSync(plan.cmd, [...plan.args, '--print-roots'], { cwd: dir, env: plan.env, encoding: 'utf8' }));
+  assert.equal(roots.INSTANCE_ROOT, dir, 'migrate.sh migrates THIS project');
+
+  // And the override is load-bearing: the same script with the inherited value is misaimed.
+  const blind = rootsOf(execFileSync('bash', [CORE_MIGRATE_SCRIPT, '--print-roots'], { cwd: dir, env: base, encoding: 'utf8' }));
+  assert.notEqual(blind.INSTANCE_ROOT, dir, 'without INIT_CWD pinned, a stray value decides which project is migrated');
+});