@bongos/core 1.19.922 → 1.19.924

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

@@ -184,73 +184,24 @@ async function coreUpgradeInstance(inst, deps, intent) {
   // the two attribution flags (ADR 0293 D5). --commit-pin is NOT optional here: without
   // it the pin lives only in the working tree, and the next pull-deploy resets it away —
   // the silent thirteen-release revert upgrade.js's own header records.
-  const healthUrl = `http://127.0.0.1:${inst.port}/healthz`;
   const versionUrl = `http://127.0.0.1:${inst.port}/version`;
-  // WHO THE UPGRADE RUNS AS, AND WHICH DATABASE IT NAMES (task 1004119).
-  //
-  // A bare `sudo` runs as ROOT, and both halves of the upgrade resolve against the
-  // CURRENT OS USER rather than a flag:
-  //
-  //   • migrate.sh peer-auths over the local socket as whoever invoked it, and `root`
-  //     is almost never a Postgres role — pre-flight refuses with "Postgres has no
-  //     role root" before the pin moves (correctly; the pin must not move for a
-  //     migrate that cannot run).
-  //   • with no PGDATABASE, resolveInstanceDb() has to FIND the database by loading
-  //     node_modules/@bongos/core/src/bongos/pool from the instance root. An adopted
-  //     repo that installs its workspaces rather than its root has no core there, so
-  //     the name cannot be resolved at all.
-  //
-  // Both were live on 2026-09-20: four presses of the owner's Upgrade button, four
-  // pre-flight refusals, no instance ever moved. The helpers to fix it already sat in
-  // provision-repo.js — this leg simply never used them.
-  //
-  // The account is the instance's own (`bongos-<slug>`), which is ALSO the name of its
-  // Postgres login role (instanceDbRole), so peer auth lands on a role that owns
-  // exactly that instance's database. The control plane is the exception: it is not a
-  // provisioned tenant and has no `bongos-` account — it runs as APP_USER, the operator
-  // the recipe's gate-3 invocation names.
-  const runAs = inst.hosting_shape === 'control-plane' ? APP_USER : instanceUser(inst);
-  const sudoP = privileged ? `sudo -u ${runAs} env PGDATABASE=${dbName(inst)} ` : '';
-  // WHERE THE CLI LIVES AND WHERE THE TARGET LIVES ARE DIFFERENT PLACES (task 1004053).
-  //
-  // `scripts/gds/upgrade.js` ships in the CORE checkout. A provisioned instance root holds
-  // no scripts/ directory at all — its core sits under node_modules/@bongos/core — so
-  // running the CLI with cwd = the instance root resolved nothing, and EVERY standalone
-  // upgrade died before it began:
-  //
-  //   Error: Cannot find module '/srv/<base>/<slug>/scripts/gds/upgrade.js'
-  //
-  // It worked only where instanceDir HAPPENED to be this checkout — the control-plane self
-  // row and a co-tenant — which is why it survived to production: the shapes that are
-  // upgraded by hand are the shapes the relative path fits. Every ACTIVE tenant is
-  // standalone, so the deploy door could not move a single one of them.
-  //
-  // upgrade.js's own header states the contract this restores: "Runs from the consumer
-  // instance root (default) or `--instance <dir>`. This script ships IN the core … against
-  // `--instance <consumer>`." So: run it where it exists, and NAME the target.
-  const runDir = REPO_ROOT;
-  const targetArg = instanceDir === REPO_ROOT ? '' : `--instance ${instanceDir}`;
-  const cli = path.posix.join('scripts', 'gds', 'upgrade.js');
   const requestedBy = intent.requested_by && /^api:archon:(\d+)$/.test(intent.requested_by)
     ? intent.requested_by.replace(/^api:archon:/, '')
     : '';
-  const cmd = [
-    `${sudoP}node ${cli}`,
-    '--registry',
-    `--to ${to}`,
-    targetArg,
-    `--service ${inst.slug}`,
-    `--health-url ${healthUrl}`,
-    `--version-url ${versionUrl}`,
-    '--commit-pin',
-    requestedBy ? `--requested-by ${requestedBy}` : '',
-    requestedBy ? '--upgrade-source owner-control' : '',
-  ].filter(Boolean).join(' ');
+  // Built by the SAME function the preview uses, so "what you were shown" and "what runs"
+  // cannot drift apart into two hand-maintained flag lists (task 1004121).
+  const { cmd, runDir } = upgradeInvocation(inst, to, { privileged, requestedBy });
 
   if (!apply) {
-    log(`  ✓ would run (in ${runDir}): ${cmd} (dry-run — nothing ran)`);
+    // A --dry-run runner tick used to only PRINT this command. It now runs the CLI's own
+    // dry run, so `provision.js --dry-run` reports what the upgrade would actually refuse
+    // rather than a command string the reader has to evaluate in their head.
+    log(`  ✓ would run (in ${runDir}): ${cmd}`);
+    const verdict = (deps.preflightUpgrade || preflightUpgrade)(inst, to, deps);
+    for (const line of verdict.lines || []) log(`    ✓ pre-flight: ${line}`);
+    if (!verdict.ok) log(`    ✖ ${verdict.error}`);
     log(`  ✓ would then read ${versionUrl} on the box and require it to say ${to}`);
-    return { ok: true, served: null };
+    return { ok: true, served: null, preflight: verdict };
   }
   try {
     log(`  [upgrade] (in ${runDir}) ${cmd}`);
@@ -290,6 +241,100 @@ async function coreUpgradeInstance(inst, deps, intent) {
   return { ok: true, served, confirmed: served === to };
 }
 
+// The pre-flight lines a dry run emits, and the refusal when it has one. upgrade.js writes
+// its pre-flight to stdout as `  ✓ pre-flight: …` and returns a `✖`-prefixed multi-line
+// error on a refusal, so BOTH streams matter: a pass is only legible from stdout, and a
+// refusal only from the failure text. PURE given its input.
+function parsePreflight(out) {
+  const text = String(out || '');
+  const lines = text.split('\n').map((l) => l.trim());
+  const checks = lines.filter((l) => /^[✓✖]\s*pre-flight:/.test(l)).map((l) => l.replace(/^[✓✖]\s*/, ''));
+  // A refusal is whatever upgrade.js said after the ✖ — reported verbatim rather than
+  // re-worded, because its wording already names the fix ("Set PGDATABASE, or …").
+  const failAt = text.indexOf('✖');
+  const error = failAt >= 0 ? text.slice(failAt + 1).trim() : null;
+  return { checks, error };
+}
+
+// ONE BUILDER FOR BOTH LEGS (task 1004121).
+//
+// The preview and the move must be the same command or the preview is worthless — and
+// two hand-copied builders are exactly how they stop being the same. The mode decides
+// only the TAIL: a dry run stops after pre-flight, so the flags that describe what to do
+// AFTER the pin moves (restart, health, version, pin-commit, attribution) would be
+// inert on it. Everything that decides whether the upgrade is ALLOWED — the account, the
+// database, the target, the instance — is shared, which is the half a preview is about.
+//
+// The slug rides into a shell command through instanceUser()/dbName(), so it is checked
+// HERE rather than left to instanceUser()'s own throw: that throw is correct today, but
+// a call site whose safety depends on a helper's internals is one refactor away from a
+// shell-injection path (and the apply leg's own guard sits at the route, not here).
+function upgradeInvocation(inst, to, { privileged = false, dryRun = false, requestedBy = '' } = {}) {
+  if (!isValidSlug(inst && inst.slug)) {
+    throw new Error(`upgradeInvocation: refusing to build a shell command from an invalid slug ${JSON.stringify(inst && inst.slug)}`);
+  }
+  const instanceDir = inst.hosting_shape === 'standalone' ? standaloneRoot(inst) : REPO_ROOT;
+  // The control plane is not a provisioned tenant and has no `bongos-` account; every
+  // other shape runs as its own, which is also its Postgres login role (task 1004119).
+  const runAs = inst.hosting_shape === 'control-plane' ? APP_USER : instanceUser(inst);
+  const sudoP = privileged ? `sudo -u ${runAs} env PGDATABASE=${dbName(inst)} ` : '';
+  const cli = path.posix.join('scripts', 'gds', 'upgrade.js');
+  const shared = [`${sudoP}node ${cli}`, '--registry', `--to ${to}`,
+    instanceDir === REPO_ROOT ? '' : `--instance ${instanceDir}`];
+  const tail = dryRun
+    ? ['--dry-run']
+    : [`--service ${inst.slug}`,
+      `--health-url http://127.0.0.1:${inst.port}/healthz`,
+      `--version-url http://127.0.0.1:${inst.port}/version`,
+      '--commit-pin',
+      requestedBy ? `--requested-by ${requestedBy}` : '',
+      requestedBy ? '--upgrade-source owner-control' : ''];
+  return { cmd: [...shared, ...tail].filter(Boolean).join(' '), runDir: REPO_ROOT, instanceDir, runAs };
+}
+
+// Ask the upgrade CLI what it WOULD do, changing nothing. `allowFail` because a refusal
+// is the interesting answer, not an exception: pre-flight refusing is what this is for.
+function preflightUpgrade(inst, to, deps) {
+  const { exec, privileged } = deps;
+  const boxExec = inst.hosting_shape === 'standalone' ? (deps.controlExec || exec) : exec;
+  const { cmd, runDir } = upgradeInvocation(inst, to, { privileged, dryRun: true });
+  const r = boxExec(cmd, { cwd: runDir, allowFail: true });
+  const out = `${(r && r.stdout) || ''}\n${(r && r.stderr) || ''}`;
+  const { checks, error } = parsePreflight(out);
+  // ok is the RUN's verdict, not the parser's: a command that exited non-zero without a
+  // recognisable ✖ is still a refusal, and reporting it as a pass is the failure mode
+  // this whole task exists to remove.
+  const ok = !!(r && !r.softFailed && r.ok !== false) && !error;
+  return { target: to, ok, lines: checks, error: error || (ok ? null : 'the dry run did not complete') };
+}
+
+// Run a dry run for one instance and cache its verdict — the ON-DEMAND leg, drained from
+// a `core-upgrade-preflight` intent the owner's arming queues (task 1004121). The tick
+// does not do this: a verdict that is only ever produced on a background schedule is
+// missing at exactly the moment it is wanted (a fresh release, a new instance), and
+// re-running it every tick for a box that has been behind for hours spends a subprocess
+// to re-learn the same answer. Asked for, then cached, is both cheaper and timelier.
+async function preflightCoreUpgrade(inst, deps, intent) {
+  const { db, log } = deps;
+  const to = intent && intent.target_version;
+  if (!UPGRADE_SHAPES.has(inst.hosting_shape) || inst.status !== 'active') {
+    return { ok: false, error: `cannot preview a ${inst.hosting_shape} instance` };
+  }
+  if (!to) return { ok: false, error: 'no target version to preview' };
+  const verdict = (deps.preflightUpgrade || preflightUpgrade)(inst, to, deps);
+  await db.query(
+    `INSERT INTO provisioning_core_version_snapshot (instance_id, preflight, preflight_at, observed_at)
+     VALUES ($1, $2::jsonb, now(), now())
+     ON CONFLICT (instance_id) DO UPDATE
+       SET preflight = EXCLUDED.preflight, preflight_at = now()`,
+    [inst.id, JSON.stringify(verdict)]);
+  log(`  ${verdict.ok ? '✓' : '✖'} ${inst.slug}: pre-flight for ${to} — ${verdict.ok ? 'clear' : verdict.error}`);
+  // ok:true means THE PREVIEW RAN. A refusal is a successful preview of a refusal — the
+  // intent must not go to 'error', or the owner's next arming is blocked by a stale open
+  // intent describing a check that worked perfectly.
+  return { ok: true, preflight: verdict };
+}
+
 /**
  * Observe one instance and cache what the deploy control needs, without acting.
  *
@@ -323,14 +368,26 @@ async function snapshotCoreVersions(inst, deps) {
     const recommended = served
       ? channelMod.resolveChannelTarget({ installed: served, channel: channelMod.DEFAULT_CHANNEL, available })
       : null;
+    // THE TICK DOES NOT DRY-RUN. The verdict is produced on demand (preflightCoreUpgrade),
+    // because a check re-run every tick for a box that has been behind for hours spends a
+    // subprocess to re-learn the same answer, and is still missing in the one window that
+    // matters — the minutes after a release, which is when someone presses the button.
+    // The version probe below is cheap and genuinely per-tick; a dry run is not.
+    const preflight = null;
     await db.query(
-      `INSERT INTO provisioning_core_version_snapshot (instance_id, served_version, available, recommended, observed_at)
-       VALUES ($1, $2, $3::jsonb, $4, now())
+      `INSERT INTO provisioning_core_version_snapshot
+         (instance_id, served_version, available, recommended, observed_at, preflight, preflight_at)
+       VALUES ($1, $2, $3::jsonb, $4, now(), $5::jsonb, $6)
        ON CONFLICT (instance_id) DO UPDATE
          SET served_version = EXCLUDED.served_version, available = EXCLUDED.available,
-             recommended = EXCLUDED.recommended, observed_at = now()`,
-      [inst.id, served, JSON.stringify(available), recommended || null]);
-    return { ok: true, served, available: available.length };
+             recommended = EXCLUDED.recommended, observed_at = now(),
+             -- A tick with nothing to preview must not ERASE the last verdict; it simply
+             -- has nothing newer to say. Only a real dry run overwrites one.
+             preflight = COALESCE(EXCLUDED.preflight, provisioning_core_version_snapshot.preflight),
+             preflight_at = COALESCE(EXCLUDED.preflight_at, provisioning_core_version_snapshot.preflight_at)`,
+      [inst.id, served, JSON.stringify(available), recommended || null,
+       preflight ? JSON.stringify(preflight) : null, preflight ? new Date() : null]);
+    return { ok: true, served, available: available.length, preflight };
   } catch (e) {
     log(`  ~ core-version snapshot for ${inst.slug} skipped (${(e && e.message) || e})`);
     return { ok: true, skipped: true };
@@ -352,4 +409,4 @@ async function snapshotAllCoreVersions(deps) {
   return { seen };
 }
 
-module.exports = { UPGRADE_SHAPES, versionCmd, parseServedVersion, targetFault, coreUpgradeInstance, snapshotCoreVersions, snapshotAllCoreVersions };
+module.exports = { UPGRADE_SHAPES, versionCmd, parseServedVersion, targetFault, parsePreflight, upgradeInvocation, preflightUpgrade, preflightCoreUpgrade, coreUpgradeInstance, snapshotCoreVersions, snapshotAllCoreVersions };

package/scripts/gds/provision.js

@@ -58,7 +58,7 @@ const { capacityPreflight, statusCapacityLine } = require('./provision-capacity.
 const { installedCoreVersion, runnerBanner } = require('./runner-drift.js');
 const { teardownInstance } = require('./provision-teardown.js');
 const { disconnectInstance } = require('./provision-disconnect.js');
-const { coreUpgradeInstance, snapshotAllCoreVersions } = require('./provision-core-upgrade.js'); // the owner's deploy door, ADR 0293
+const { coreUpgradeInstance, preflightCoreUpgrade, snapshotAllCoreVersions } = require('./provision-core-upgrade.js'); // the owner's deploy door, ADR 0293
 
 // WHAT supervises an instance's service (ADR 0306). systemd on every box we run — the
 // seam exists so a plane without systemd is not a dead end. Injectable for tests.
@@ -1288,6 +1288,7 @@ async function cmdRunIntents(deps) {
       else if (intent.action === 'restart') result = await restartInstance(inst, deps);
       else if (intent.action === 'disconnect') result = await disconnectInstance(inst, deps);
       else if (intent.action === 'core-upgrade') result = await coreUpgradeInstance(inst, deps, intent); // also reads the INTENT: the version the owner previewed (ADR 0293 D4)
+      else if (intent.action === 'core-upgrade-preflight') result = await preflightCoreUpgrade(inst, deps, intent); // changes nothing; caches what the move WOULD say (task 1004121)
       else result = { ok: false, error: `unknown_action '${intent.action}' — runner core ${coreVersionSafe() || '?'} does not know it (runner too old?); refusing to guess` };
       if (result && result.ok === false) {
         if (intent.attempts >= MAX_INTENT_ATTEMPTS) {

package/src/module-api.js

@@ -71,7 +71,7 @@ const { responsibilityFor, ROLE_RESPONSIBILITIES } = require('./role-responsibil
 // there. scripts/gds/bump-version.js still rewrites the literal below; it appends
 // the entry to that file. Look for a version's history there, not here.
 // ---------------------------------------------------------------------------
-const CORE_VERSION = '1.19.922'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
+const CORE_VERSION = '1.19.924'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
 
 // A namespaced logger so a module's log lines are attributable + consistent.
 // Usage: const log = api.logger('dev-box'); log.info('mounted');

package/tests/core_upgrade_door.mjs

@@ -15,7 +15,7 @@
 
 import { strict as assert } from 'node:assert';
 import { createRequire } from 'node:module';
-import { readFileSync } from 'node:fs';
+import { readFileSync, readdirSync } from 'node:fs';
 import { fileURLToPath } from 'node:url';
 import { dirname, join } from 'node:path';
 
@@ -52,10 +52,24 @@ await t('the shape and the action both reach the DB constraints', () => {
   // The JS list and the CHECK are two spellings of one vocabulary; a widening that
   // lands in only one of them fails at insert time, in production, on the first
   // real use. (The bug class task 1003913 shipped a fix for, in another file.)
-  const mig = read('modules', 'provisioning', 'migrations', 'provisioning_018_core_upgrade_intent.sql')
+  // Read the NEWEST migration that widens the action CHECK, not a fixed filename: the
+  // vocabulary grows, and a test pinned to one file passes forever while the constraint
+  // it is meant to guard falls behind (task 1004121 added an action 018 does not carry).
+  const migDir = join(__dirname, '..', 'modules', 'provisioning', 'migrations');
+  const widenings = readdirSync(migDir).filter((f) => f.endsWith('.sql'))
+    .filter((f) => /ADD CONSTRAINT provisioning_intents_action_check/.test(readFileSync(join(migDir, f), 'utf8')))
+    .sort();
+  assert.ok(widenings.length, 'some migration defines the action CHECK');
+  const mig = readFileSync(join(migDir, widenings[widenings.length - 1]), 'utf8')
+    .replace(/^\s*--.*$/gm, ' ').replace(/\s+/g, ' ');
+  const shapes = read('modules', 'provisioning', 'migrations', 'provisioning_018_core_upgrade_intent.sql')
     .replace(/^\s*--.*$/gm, ' ').replace(/\s+/g, ' ');
-  assert.match(mig, /CHECK \(action IN \([^)]*'core-upgrade'\)\)/, 'the intents CHECK admits the new action');
-  assert.match(mig, /CHECK \(hosting_shape IN \([^)]*'control-plane'\)\)/, 'the instances CHECK admits the new shape');
+  // Membership, not POSITION. The old spelling required 'core-upgrade' to be the last
+  // item before the closing paren, so the next action appended after it failed a test
+  // that had nothing to say about the next action.
+  assert.match(mig, /CHECK \(action IN \(/, 'the intents CHECK is an action allow-list');
+  assert.ok(mig.includes("'core-upgrade'"), 'and it still admits the move itself');
+  assert.match(shapes, /CHECK \(hosting_shape IN \([^)]*'control-plane'\)\)/, 'the instances CHECK admits the new shape');
   for (const a of P.INTENT_ACTIONS) {
     assert.ok(mig.includes(`'${a}'`), `the widened CHECK must still carry '${a}' — a rewrite drops what it forgets`);
   }
@@ -404,5 +418,43 @@ await t('THE DEPLOY PAGE NEVER COMPUTES A VERSION COMPARISON — every number on
   assert.match(js, /p\.behind/, 'and asks the server whether there is anything to do');
 });
 
+console.log('\nthe pre-flight verdict, and when it may be shown (task 1004121):');
+
+const snapOf = (over = {}) => ({
+  served_version: '1.19.917', available: ['1.19.917', '1.19.921'], recommended: '1.19.921',
+  observed_at: new Date().toISOString(), preflight_at: new Date().toISOString(), ...over,
+});
+const box = { id: '1', slug: 'cloudbongos', hosting_shape: 'control-plane' };
+
+await t('a verdict taken against the version ON OFFER is shown', () => {
+  const p = CU.previewFromSnapshot(box, snapOf({
+    preflight: { target: '1.19.921', ok: true, lines: ['database reachable'], error: null } }), null);
+  assert.ok(p.preflight, 'it reaches the control');
+  assert.equal(p.preflight.target, '1.19.921');
+  assert.ok(p.preflight_at, 'with its own age, not the probe’s');
+});
+
+await t('a verdict taken against a SUPERSEDED version is withheld, not shown as a pass', () => {
+  // The whole point of storing `target` with the verdict. A pass checked against
+  // 1.19.920 says nothing true about a button labelled 1.19.921 — and a stale pass is
+  // worse than no answer, because it reads as a guarantee.
+  const p = CU.previewFromSnapshot(box, snapOf({
+    preflight: { target: '1.19.920', ok: true, lines: ['database reachable'], error: null } }), null);
+  assert.equal(p.preflight, null, 'withheld');
+  assert.equal(p.preflight_at, null, 'and so is its timestamp — no age for an answer not given');
+});
+
+await t('a stale REFUSAL is withheld too — it must not veto a move it never checked', () => {
+  const p = CU.previewFromSnapshot(box, snapOf({
+    preflight: { target: '1.19.900', ok: false, lines: [], error: 'working tree not clean' } }), null);
+  assert.equal(p.preflight, null, 'the guard is symmetric: it withholds fails as well as passes');
+});
+
+await t('no verdict at all is null — never an implied pass', () => {
+  const p = CU.previewFromSnapshot(box, snapOf({ preflight: null, preflight_at: null }), null);
+  assert.equal(p.preflight, null);
+  assert.equal(p.behind, true, 'and the rest of the reading is unaffected');
+});
+
 console.log(`\ncore_upgrade_door: ${passed} passed, ${failed} failed`);
 if (failed) process.exit(1);

package/tests/core_upgrade_runner.mjs

@@ -471,5 +471,87 @@ await t('an UNPRIVILEGED runner still adds no sudo and no env at all', async ()
   assert.match(cmd, /^node \S*scripts\/gds\/upgrade\.js /, 'it still invokes the CLI directly');
 });
 
+console.log('\nthe dry run behind "see what would change" (task 1004121):');
+
+await t('a passing dry run is parsed into its pre-flight lines, with no error', () => {
+  const { checks, error } = R.parsePreflight([
+    'bongos upgrade — @bongos/core: 1.19.917 → 1.19.921',
+    '  ✓ pre-flight: no modules/ — nothing to pre-check',
+    '  ✓ pre-flight: database "cloudbongos" reachable as the current user',
+  ].join('\n'));
+  assert.equal(error, null);
+  assert.equal(checks.length, 2);
+});
+
+await t('a REFUSAL is carried verbatim — its wording is the instruction', () => {
+  const { error } = R.parsePreflight(
+    '  ✖ cannot determine which database to migrate.\n    Set PGDATABASE, or give this instance a db.database in config/branding.json.');
+  assert.match(error, /Set PGDATABASE/, 'the remedy rides along, not just the complaint');
+});
+
+await t('ONE builder serves both legs — the preview and the move cannot drift apart', () => {
+  // Two hand-copied builders are how "what you were shown" stops matching "what runs".
+  // Everything deciding whether the upgrade is ALLOWED must be identical; only the tail
+  // that describes what happens AFTER the pin moves may differ, because a dry run stops
+  // before it.
+  const box = { id: 7, slug: 'test4', port: 3006, hosting_shape: 'standalone', db_name: 'test4' };
+  const move = R.upgradeInvocation(box, '1.19.921', { privileged: true, requestedBy: '42' });
+  const peek = R.upgradeInvocation(box, '1.19.921', { privileged: true, dryRun: true });
+  for (const shared of ['sudo -u bongos-test4 ', 'env PGDATABASE=test4 ', '--to 1.19.921', '--registry']) {
+    assert.ok(move.cmd.includes(shared), `move carries ${shared}`);
+    assert.ok(peek.cmd.includes(shared), `preview carries the same ${shared}`);
+  }
+  assert.equal(move.instanceDir, peek.instanceDir, 'same target directory');
+  assert.equal(move.runAs, peek.runAs, 'same account');
+  // And the tail genuinely differs — asserted rather than assumed, so this test cannot
+  // quietly pass a preview that would restart the box.
+  assert.match(peek.cmd, /--dry-run/);
+  for (const post of ['--service', '--health-url', '--version-url', '--commit-pin', '--requested-by']) {
+    assert.ok(move.cmd.includes(post), `the move carries ${post}`);
+    assert.ok(!peek.cmd.includes(post), `the preview must NOT carry ${post} — it never gets that far`);
+  }
+});
+
+await t('an invalid slug is refused at the BUILDER, not left to a helper to throw', () => {
+  // The slug reaches a shell through instanceUser()/dbName(). Depending on another
+  // function's internals for that is one refactor away from an injection path.
+  assert.throws(() => R.upgradeInvocation({ slug: 'a; rm -rf /', port: 1, hosting_shape: 'standalone' }, '1.19.921', {}),
+    /invalid slug/);
+});
+
+await t('a dry run that fails WITHOUT a recognisable marker is still a refusal, never a pass', () => {
+  const deps = { privileged: false, exec: () => ({ ok: false, stdout: 'something went sideways' }) };
+  const r = R.preflightUpgrade({ id: 7, slug: 'test4', port: 3006, hosting_shape: 'standalone' }, '1.19.921', deps);
+  assert.equal(r.ok, false, 'a non-zero exit is a refusal whatever it printed');
+  assert.ok(r.error);
+});
+
+await t('the TICK never dry-runs — the verdict is asked for, not produced on a schedule', async () => {
+  // Re-running a check every tick for a box behind for hours spends a subprocess to
+  // re-learn the same answer, and is still missing in the window that matters.
+  const d = makeDeps({ served: '1.19.762' });
+  let spawned = 0;
+  d.preflightUpgrade = () => { spawned++; return { ok: true }; };
+  await R.snapshotCoreVersions(inst(), d);
+  assert.equal(spawned, 0, 'the version probe is per-tick; the dry run is not');
+});
+
+await t('the on-demand leg caches the verdict, and a REFUSAL is still a successful preview', async () => {
+  const d = makeDeps({ served: '1.19.762' });
+  d.preflightUpgrade = () => ({ target: '1.19.921', ok: false, lines: [], error: 'working tree not clean' });
+  const r = await R.preflightCoreUpgrade(inst(), d, intent({ target_version: '1.19.921' }));
+  assert.equal(r.ok, true, 'the CHECK ran — a refusal is what it was for, not a failure of it');
+  const write = d.queries.find((q) => /INSERT INTO provisioning_core_version_snapshot/.test(q.sql));
+  assert.ok(write, 'the verdict is cached');
+  assert.match(String(write.params[1]), /working tree not clean/);
+});
+
+await t('a preview of nothing is refused rather than cached as a pass', async () => {
+  const d = makeDeps({ served: '1.19.762' });
+  const r = await R.preflightCoreUpgrade(inst(), d, intent({ target_version: null }));
+  assert.equal(r.ok, false);
+  assert.equal(d.queries.filter((q) => /INSERT INTO provisioning_core_version_snapshot/.test(q.sql)).length, 0);
+});
+
 console.log(`\ncore_upgrade_runner: ${passed} passed, ${failed} failed`);
 if (failed) process.exit(1);

package/tests/deploy_page_projects.mjs

@@ -75,12 +75,18 @@ function boot({ controlPlane = preview('1', 'cloudbongos'), controlPlaneStatus =
     OTB: { escapeHtml: (s) => String(s).replace(/[&<>"]/g, (c) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;' }[c])), toast() {} },
     location: { assign() {} },
   };
+  // The page's poll interval, driven rather than slept through. Injecting the REAL
+  // setTimeout made every case whose preview never converges sit out the page's full
+  // ~30s wait in wall-clock, still repainting after the test had finished — slow, and
+  // flaky against a torn-down sandbox.
+  windowObj.__deployPollMs = 0;
+  windowObj.__deployPollTries = 3;
   const sandbox = { window: windowObj, document: documentObj, console, setTimeout, clearTimeout, queueMicrotask, Date, Set, Map, Promise };
   sandbox.globalThis = sandbox;
   vm.createContext(sandbox);
   vm.runInContext(SRC, sandbox, { filename: 'deploy.js' });
   documentObj._ready();
-  const settle = async () => { for (let i = 0; i < 12; i++) await new Promise((r) => setTimeout(r, 0)); };
+  const settle = async () => { for (let i = 0; i < 40; i++) await new Promise((r) => setTimeout(r, 0)); };
   return { els, posts, gets, settle, panel: () => els.get('dp-panel').innerHTML, sub: () => els.get('dp-sub').textContent };
 }
 
@@ -126,13 +132,20 @@ test('confirming sends THAT project’s id and the version it was shown', async
   b.els.get('dp-preview-32')._on.click();
   b.els.get('dp-confirm-32')._on.click();
   await b.settle();
-  assert.equal(b.posts.length, 1);
-  assert.equal(b.posts[0].path, '/provisioning/instances/32/core-upgrade');
+  // Arming also asks for a dry run now (task 1004121), so the MOVE is the post that is
+  // not one — separated by its payload rather than by its position, because "the second
+  // post" would silently start asserting about the wrong request the next time the order
+  // changes.
+  const moves = b.posts.filter((x) => !(x.body && x.body.dry_run));
+  assert.equal(moves.length, 1, 'exactly one move is sent');
+  assert.equal(moves[0].path, '/provisioning/instances/32/core-upgrade');
   // Field-wise, not deepEqual: the body is built inside the vm realm, so its
   // prototype is not this realm's Object and deepStrictEqual rejects it on identity
   // alone — a harness artifact that says nothing about the payload.
-  assert.equal(b.posts[0].body.to, '1.19.871');
-  assert.deepEqual(Object.keys(b.posts[0].body), ['to'], 'and nothing else is sent');
+  assert.equal(moves[0].body.to, '1.19.871');
+  assert.deepEqual(Object.keys(moves[0].body), ['to'], 'and nothing else is sent');
+  // And the move must never carry the flag that would turn it into a no-op.
+  assert.equal(moves[0].body.dry_run, undefined, 'a move is not a dry run');
 });
 
 test('a box with nothing newer offers no button', async () => {
@@ -191,3 +204,89 @@ test('a move on the platform row re-reads the control plane, not a tenant previe
   assert.ok(b.gets.includes('/provisioning/control-plane'), 'the self row is read from its own endpoint');
   assert.ok(!b.gets.some((g) => /instances\/3\d\/core-upgrade/.test(g)), 'and no tenant is re-probed');
 });
+
+// ---- the pre-flight verdict on step two (task 1004121) ---------------------------
+// The defect: step one was called "see what would change" and changed nothing but a
+// local flag. These read what step two actually PAINTS, because the bug was invisible
+// to every assertion about what the page fetched — it fetched nothing.
+
+test('step two shows what the dry run found, not just a restatement of the action', async () => {
+  const b = boot({ controlPlane: preview('1', 'cloudbongos', {
+    preflight: { target: '1.19.871', ok: true, lines: ['database "cloudbongos" reachable as the current user'], error: null },
+    preflight_at: new Date().toISOString(),
+  }) });
+  await b.settle();
+  b.els.get('dp-preview-1')._on.click();
+  const html = b.panel();
+  assert.match(html, /nothing blocks this move/i, 'it states a verdict');
+  assert.match(html, /database &quot;cloudbongos&quot; reachable|database "cloudbongos" reachable/, 'and shows what was checked');
+});
+
+test('a BLOCKED move says so, in the upgrade’s own words, and still offers the button', async () => {
+  const b = boot({ controlPlane: preview('1', 'cloudbongos', {
+    preflight: { target: '1.19.871', ok: false, lines: [], error: 'working tree not clean — commit/stash first, or pass --force.' },
+    preflight_at: new Date().toISOString(),
+  }) });
+  await b.settle();
+  b.els.get('dp-preview-1')._on.click();
+  const html = b.panel();
+  assert.match(html, /This would fail/, 'the owner is told before pressing');
+  assert.match(html, /working tree not clean/, 'verbatim — the wording names the fix');
+  // Deliberate: the runner refuses on its own, and this reading can be minutes old.
+  assert.match(html, /id="dp-confirm-1"/, 'the button is still there — a stale ✖ must not lock the owner out');
+});
+
+test('with no verdict yet, arming ASKS for one and says so — never an implied pass', async () => {
+  // The whole failure mode in one test: silence where a check should be must not look
+  // like a clean bill of health, and the page must actually go and get the answer rather
+  // than wait for a background tick that may be minutes away.
+  const b = boot({ controlPlane: preview('1', 'cloudbongos', { preflight: null, preflight_at: null }) });
+  await b.settle();
+  b.els.get('dp-preview-1')._on.click();
+  // While it is in flight the row says so — asserted BEFORE settling, because the whole
+  // point is what the owner sees during the wait.
+  assert.match(b.panel(), /Checking what this would do/, 'it states that a check is under way');
+  await b.settle();
+  const asks = b.posts.filter((x) => x.body && x.body.dry_run === true);
+  assert.equal(asks.length, 1, 'exactly one check is requested');
+  assert.equal(asks[0].body.to, '1.19.871', 'against the version on offer');
+  // And when the answer never arrives (this harness never converges), it falls back to
+  // the honest state rather than to a pass — which is the failure mode being guarded.
+  const settled = b.panel();
+  assert.match(settled, /Not checked yet/, 'an answer that never came is stated as such');
+  assert.doesNotMatch(settled, /nothing blocks this move/i, 'and never dressed up as a pass');
+});
+
+test('the poll does not close the panel the owner is reading', async () => {
+  // refreshOne() returns a row to step one — right after a MOVE, wrong during the wait.
+  // Polling with it un-armed the row under the owner every interval, so the confirm
+  // button vanished mid-check.
+  const b = boot({ controlPlane: preview('1', 'cloudbongos', { preflight: null, preflight_at: null }) });
+  await b.settle();
+  b.els.get('dp-preview-1')._on.click();
+  await b.settle();
+  assert.match(b.panel(), /id="dp-confirm-1"/, 'still armed after the poll has run and given up');
+});
+
+test('a poll whose row is closed stops instead of repainting a step nobody is on', async () => {
+  const b = boot({ controlPlane: preview('1', 'cloudbongos', { preflight: null, preflight_at: null }) });
+  await b.settle();
+  b.els.get('dp-preview-1')._on.click();
+  b.els.get('dp-cancel-1')._on.click();
+  await b.settle();
+  assert.match(b.panel(), /id="dp-preview-1"/, 'back at step one');
+  assert.doesNotMatch(b.panel(), /Checking what this would do/, 'and not still claiming to be checking');
+});
+
+test('a verdict already in hand is NOT re-requested', async () => {
+  // Re-asking would spend a subprocess on the box to reprint an answer already shown.
+  const b = boot({ controlPlane: preview('1', 'cloudbongos', {
+    preflight: { target: '1.19.871', ok: true, lines: ['database reachable'], error: null },
+    preflight_at: new Date().toISOString(),
+  }) });
+  await b.settle();
+  b.els.get('dp-preview-1')._on.click();
+  await b.settle();
+  assert.equal(b.posts.filter((x) => x.body && x.body.dry_run).length, 0, 'no check requested');
+  assert.match(b.panel(), /nothing blocks this move/i, 'the held verdict is shown');
+});