@bongos/core 1.19.923 → 1.19.925

package/modules/hall-ui/public/deploy.js

@@ -50,6 +50,19 @@
   // instance_id -> 'preview' | 'confirm'. Held per box so opening the confirm on one does
   // not arm it on another.
   const steps = new Map();
+  // Rows whose dry run is in flight — per box, like `steps`, because a page-wide flag
+  // would spin every other project's row on one project's check.
+  const checking = new Set();
+  // How long the page waits for the runner to answer. Read off `window` when present so
+  // a harness can drive the loop without sleeping through it — a test that injects the
+  // real timer spends 30s of wall-clock per non-converging case and keeps repainting a
+  // sandbox that has already been torn down.
+  // `|| 2000` would be a bug here: an override of 0 — the one a harness wants — is
+  // falsy, so the fallback would swallow it and the test would sleep the full interval
+  // anyway while appearing to be driven.
+  const num = (v, dflt) => (Number.isFinite(v) ? v : dflt);
+  const POLL_MS = typeof window !== 'undefined' ? num(window.__deployPollMs, 2000) : 2000;
+  const POLL_TRIES = typeof window !== 'undefined' ? num(window.__deployPollTries, 15) : 15;
 
   async function fetchJson(path) {
     const res = await api.request('GET', `${API}${path}`);
@@ -117,10 +130,94 @@
   // to that button closes over this same preview object — so the owner confirms the thing
   // they were shown rather than "the newest", which is a different act by the time it is
   // resolved.
+  // What the dry run said, from the runner's own tick (task 1004121). Before this, step
+  // one made NO network call — it redrew a fixed sentence and called that a preview. The
+  // owner pressed it four times on 2026-09-20, restarted four live boxes, and learned
+  // three different pre-flight refusals one production restart at a time. Every one of
+  // them was in this verdict already.
+  //
+  // A REFUSAL DOES NOT DISABLE THE BUTTON. The runner refuses on its own, and this
+  // reading can be minutes old; a control that blocked on a stale ✖ would be lying in
+  // the other direction. Say what will happen and let the owner decide.
+  function preflightHtml(p) {
+    const pf = p.preflight;
+    if (checking.has(String(p.instance_id)) && !(pf && pf.target === p.recommended_version)) {
+      return `<p class="ov-row__sub dp-preflight dp-preflight--checking">Checking what this would do…</p>`;
+    }
+    // No verdict is its own state, and it is NOT "fine". A silent gap here is how the
+    // page used to promise a preview it never performed.
+    if (!pf) {
+      return `<p class="ov-row__sub dp-preflight dp-preflight--none">Not checked yet — the runner takes this reading on its own tick.</p>`;
+    }
+    const when = pf && p.preflight_at ? ` <span class="dp-preflight__age">(checked ${escapeHtml(ago(p.preflight_at))})</span>` : '';
+    if (pf.ok) {
+      const lines = (pf.lines || []).map((l) => `<li>${escapeHtml(String(l))}</li>`).join('');
+      return `<div class="dp-preflight dp-preflight--ok">
+          <p class="ov-row__sub">Checked against ${escapeHtml(String(pf.target))} — nothing blocks this move.${when}</p>
+          ${lines ? `<ul class="dp-preflight__list">${lines}</ul>` : ''}
+        </div>`;
+    }
+    return `<div class="dp-preflight dp-preflight--blocked">
+        <p class="ov-row__sub"><strong>This would fail.</strong> The upgrade checked ${escapeHtml(String(pf.target))} and refused:${when}</p>
+        <pre class="dp-preflight__error">${escapeHtml(String(pf.error || 'no reason given'))}</pre>
+        <p class="ov-row__sub">You can still press Move — the runner will refuse it the same way, and the box is left where it is.</p>
+      </div>`;
+  }
+
+  // Arming ASKS for the check (task 1004121). The web tier has no shell — it queues the
+  // dry run as an intent and the runner answers, which is the same division of labour as
+  // every other fact on this page. Then it re-reads the preview until the verdict lands.
+  //
+  // Only when there isn't already a fresh one: a verdict for THIS target is the answer,
+  // and re-asking would spend a subprocess to reprint it.
+  const asked = new Set();
+  async function askPreflight(p) {
+    const id = String(p.instance_id);
+    if (p.preflight && p.preflight.target === p.recommended_version) return;
+    if (asked.has(id)) return;
+    asked.add(id);
+    checking.add(id);
+    repaint();
+    try {
+      await sendJson('POST', `/provisioning/instances/${id}/core-upgrade`, {
+        to: p.recommended_version, dry_run: true,
+      });
+    } catch (e) {
+      if (e && e.kind === '401') return;
+      // A refused REQUEST is not a refused upgrade, and must not be painted as one:
+      // fall back to "not checked", which is honest about what is known.
+      checking.delete(id); asked.delete(id); repaint();
+      return;
+    }
+    // The runner drains on its own tick, so this waits rather than assuming. Bounded:
+    // a check that never lands leaves the row saying it was never checked, which is
+    // true, instead of spinning for ever.
+    //
+    // AND IT STOPS WHEN NOBODY IS LOOKING. The loop is started from a click and not
+    // awaited by it, so without this it outlives whatever closed the row — cancelling,
+    // confirming, or a reload — and goes on repainting a step the owner has left. It
+    // also made every test that never converges sit through the full ~30s in real time.
+    for (let i = 0; i < POLL_TRIES; i++) {
+      await new Promise((r) => setTimeout(r, POLL_MS));
+      if (steps.get(p.instance_id) !== 'confirm') break;   // the row was closed; stop.
+      try {
+        await refreshOne(p, { keepStep: true });
+        const now = (view.self && String(view.self.instance_id) === id)
+          ? view.self
+          : view.boxes.find((b) => String(b.instance_id) === id);
+        if (now && now.preflight && now.preflight.target === now.recommended_version) break;
+      } catch (e) { break; }
+    }
+    checking.delete(id);
+    asked.delete(id);
+    repaint();
+  }
+
   function stepTwoHtml(p, isSelf) {
     const id = escapeHtml(String(p.instance_id));
     return `
       <div class="ps-controls">
+        ${preflightHtml(p)}
         <p class="ov-row__sub">This restarts ${isSelf ? 'the platform' : escapeHtml(String(p.slug))} onto core
           <strong>${escapeHtml(String(p.recommended_version))}</strong>. It waits for the box to answer and
           puts itself back on ${escapeHtml(String(p.served_version))} if it does not.</p>
@@ -166,7 +263,7 @@
   function wire(p) {
     const id = String(p.instance_id);
     const preview = $(`dp-preview-${id}`);
-    if (preview) preview.addEventListener('click', () => { steps.set(p.instance_id, 'confirm'); repaint(); });
+    if (preview) preview.addEventListener('click', () => { steps.set(p.instance_id, 'confirm'); repaint(); askPreflight(p); });
     const cancel = $(`dp-cancel-${id}`);
     if (cancel) cancel.addEventListener('click', () => { steps.set(p.instance_id, 'preview'); repaint(); });
     const confirm = $(`dp-confirm-${id}`);
@@ -223,14 +320,17 @@
   // far wider than the change — it also re-probes boxes the owner never touched. A
   // failure here falls back to the full read, because a stale row on a deploy page is
   // the one thing worse than an extra request.
-  async function refreshOne(p) {
+  // `keepStep` is for the pre-flight poll (task 1004121): a refresh AFTER a move should
+  // return the row to step one, but a refresh DURING the wait must not — it would close
+  // the panel the owner is reading, under them, every two seconds.
+  async function refreshOne(p, { keepStep = false } = {}) {
     const id = String(p.instance_id);
     const isSelf = view.self && String(view.self.instance_id) === id;
     try {
       const d = await fetchJson(isSelf ? '/provisioning/control-plane' : `/provisioning/instances/${id}/core-upgrade`);
       if (isSelf) view.self = d.preview;
       else view.boxes = view.boxes.map((b) => (String(b.instance_id) === id ? d.preview : b));
-      steps.set(p.instance_id, 'preview');
+      if (!keepStep) steps.set(p.instance_id, 'preview');
       repaint();
     } catch (e) {
       if (e && e.kind === '401') return;

package/modules/hall-ui/public/project-settings.css

@@ -88,3 +88,42 @@
   color: var(--ink-soft);
 }
 .ps-sibling strong { color: inherit; font-weight: 600; }
+
+/* The deploy control's pre-flight verdict (task 1004121) — what the upgrade says it
+   would do, taken by the runner's dry run. Three states, and "not checked" is one of
+   them: the page used to show a confident sentence where it had performed no check at
+   all, so silence here must look like silence, not like a pass. */
+.dp-preflight { margin: 0 0 0.6rem; }
+.dp-preflight--none,
+.dp-preflight--checking { color: var(--ink-soft); font-style: italic; }
+/* The pass state earns a mark of its own. Without one, "nothing blocks this" and "not
+   checked" differ only in wording, and the three-state legibility this file claims is
+   two states and a sentence. */
+.dp-preflight--ok {
+  border-left: 3px solid var(--ok);
+  padding-left: 0.7rem;
+}
+.dp-preflight__age { color: var(--ink-soft); font-weight: normal; }
+.dp-preflight__list {
+  margin: 0.25rem 0 0;
+  padding-left: 1.1rem;
+  color: var(--ink-soft);
+  font-size: 0.86rem;
+  line-height: 1.5;
+}
+.dp-preflight--blocked {
+  border-left: 3px solid var(--danger);
+  padding-left: 0.7rem;
+}
+/* The refusal is upgrade.js's own words, multi-line and already indented to name the
+   fix — preserved rather than reflowed, because the wording IS the instruction. */
+.dp-preflight__error {
+  margin: 0.35rem 0;
+  padding: 0.5rem 0.6rem;
+  background: var(--surface-2);
+  border-radius: 6px;
+  font-size: 0.82rem;
+  line-height: 1.45;
+  white-space: pre-wrap;
+  overflow-x: auto;
+}

package/modules/provisioning/core-upgrade.js

@@ -124,8 +124,8 @@ function coreUpgradeFault(inst, to, live = null) {
  * is. So a second request is a conflict the route names, including when the open
  * intent is itself a core-upgrade.
  */
-async function enqueueCoreUpgrade(provisioning, db, instanceId, to, requestedBy) {
-  const { intent, created } = await provisioning.enqueueIntent(db, instanceId, 'core-upgrade', requestedBy, to);
+async function enqueueCoreUpgrade(provisioning, db, instanceId, to, requestedBy, action = 'core-upgrade') {
+  const { intent, created } = await provisioning.enqueueIntent(db, instanceId, action, requestedBy, to);
   if (created) return { intent, created: true };
   return { intent, created: false, conflict: 'open_intent' };
 }
@@ -172,7 +172,13 @@ function makeCoreUpgradeHandler({ provisioning, pool, parseId, validateOrRespond
       // core_upgrades ledger (ADR 0293 D5): a privileged action with an
       // unattributed row is not acceptable here.
       const actor = `api:archon:${req.builder.id}`;
-      const r = await enqueueCoreUpgrade(provisioning, pool, id, to, actor);
+      // `dry_run: true` asks what the move WOULD do and moves nothing (task 1004121).
+      // Queued the same way as the move, through the same single-open-intent slot, so a
+      // preview cannot be requested on top of a move that is already running — and, just
+      // as deliberately, a preview occupies that slot only for as long as it takes.
+      const dryRun = req.body && req.body.dry_run === true;
+      const action = dryRun ? 'core-upgrade-preflight' : 'core-upgrade';
+      const r = await enqueueCoreUpgrade(provisioning, pool, id, to, actor, action);
       if (r.conflict) {
         return res.fail('intent_conflict', {
           status: 409,
@@ -181,9 +187,15 @@ function makeCoreUpgradeHandler({ provisioning, pool, parseId, validateOrRespond
         });
       }
       await provisioning.recordEvent(pool, {
-        instanceId: id, ownerBuilderId: inst.owner_builder_id, event: 'core-upgrade',
-        detail: `core pin move to ${to} requested`, actor,
+        instanceId: id, ownerBuilderId: inst.owner_builder_id, event: action,
+        detail: dryRun ? `pre-flight check for ${to} requested` : `core pin move to ${to} requested`, actor,
       }).catch(() => {});
+      if (dryRun) {
+        return res.json({
+          ok: true, queued: true, action, target_version: to,
+          message: `Checking what moving to ${to} would do. Nothing is changed by this — the answer appears here when the check finishes.`,
+        });
+      }
       // No duration is promised and no success is claimed: this says the request
       // was RECORDED, which is the only thing true at this moment (ADR 0190 §7).
       return res.json({
@@ -213,6 +225,7 @@ function makeCoreUpgradeHandler({ provisioning, pool, parseId, validateOrRespond
  */
 function previewFromSnapshot(inst, snap, openIntent) {
   const served = (snap && snap.served_version) || null;
+  const pf = (snap && snap.preflight) || null;
   const available = (snap && Array.isArray(snap.available) ? snap.available : []);
   const recommended = (snap && snap.recommended) || null;
   // Only what a move could actually go TO: newer than what is running, and admitted by
@@ -230,6 +243,12 @@ function previewFromSnapshot(inst, snap, openIntent) {
     // Named so the UI cannot accidentally render "up to date" over a missing reading.
     reading: served ? 'ok' : 'no_answer',
     observed_at: (snap && snap.observed_at) || null,
+    // What the upgrade SAYS it would do, from the runner's dry run (task 1004121).
+    // Withheld unless it was taken against the move now on offer: a verdict about
+    // 1.19.920 tells the owner nothing true about pressing a button that says 1.19.921,
+    // and a stale pass is worse than no answer because it reads as a guarantee.
+    preflight: pf && recommended && pf.target === recommended ? pf : null,
+    preflight_at: pf && recommended && pf.target === recommended ? (snap.preflight_at || null) : null,
     open_intent: openIntent ? { action: openIntent.action, state: openIntent.state, target_version: openIntent.target_version || null } : null,
   };
 }

package/modules/provisioning/migrations/provisioning_020_core_upgrade_preflight.sql

@@ -0,0 +1,53 @@
+-- provisioning_020_core_upgrade_preflight.sql — what the upgrade would say if you pressed it
+-- (task 1004121, ADR 0293 D4).
+--
+-- WHY THIS EXISTS. Step one of the deploy control's two-step was labelled "see what would
+-- change" and made no network call at all: it flipped a local flag and redrew one fixed
+-- sentence naming the two versions. Nothing was computed and no precondition was checked.
+--
+-- What that cost, on 2026-09-20: the owner pressed Upgrade four times across four
+-- instances. Every press restarted a live box, failed in pre-flight and rolled back, and
+-- the four failures were three DIFFERENT causes — a root Postgres role, an unresolvable
+-- database name (both task 1004119) and an unclean working tree (task 1004122). Each one
+-- is a pre-flight check, and `upgrade.js --dry-run` runs the whole pre-flight before it
+-- returns. Every one of them was reportable without restarting anything.
+--
+-- So the runner now performs that dry run on its own tick, beside the version probe it
+-- already takes, and caches the verdict here. Same division of labour as the columns
+-- next door (provisioning_019): facts the web tier may not go and look for itself, taken
+-- by the process that has a shell and read by the process that does not.
+--
+-- KEYED BY THE TARGET IT WAS RUN AGAINST. A verdict is only about one move. `target` is
+-- stored with it so the control can tell a live answer from one taken against a version
+-- that has since been superseded, rather than showing a stale pass over a new release.
+
+BEGIN;
+
+ALTER TABLE provisioning_core_version_snapshot
+  -- { target, ok, lines[], error } as the dry run reported it, or NULL when there was
+  -- nothing to preview (the box is current, so no move exists to check).
+  ADD COLUMN IF NOT EXISTS preflight jsonb,
+  -- When the dry run ran, which is NOT observed_at: the version probe is taken every
+  -- tick and this is only re-taken when there is a move to check. A control that
+  -- rendered one timestamp for both would age-stamp the verdict with the probe's clock.
+  ADD COLUMN IF NOT EXISTS preflight_at timestamptz;
+
+-- The intent vocabulary gains the ASKING action. The JS list (INTENT_ACTIONS) and this
+-- CHECK are two spellings of one vocabulary, and a widening that lands in only one of
+-- them fails at insert time, in production, on the first real use — which is exactly what
+-- tests/core_upgrade_door.mjs asserts against, and what it caught here.
+--
+-- The target_version CHECK from provisioning_018 is re-stated, not just left alone: it
+-- read `(action = 'core-upgrade') = (target_version IS NOT NULL)`, which would REFUSE a
+-- preflight intent for naming the version it is about to check.
+ALTER TABLE provisioning_intents DROP CONSTRAINT IF EXISTS provisioning_intents_action_check;
+ALTER TABLE provisioning_intents ADD CONSTRAINT provisioning_intents_action_check
+  CHECK (action IN ('provision', 'teardown', 'oauth-manifest', 'domain-attach',
+                    'settings-apply', 'restart', 'disconnect', 'core-upgrade',
+                    'core-upgrade-preflight'));
+
+ALTER TABLE provisioning_intents DROP CONSTRAINT IF EXISTS provisioning_intents_target_version_chk;
+ALTER TABLE provisioning_intents ADD CONSTRAINT provisioning_intents_target_version_chk
+  CHECK ((action IN ('core-upgrade', 'core-upgrade-preflight')) = (target_version IS NOT NULL));
+
+COMMIT;

package/modules/provisioning/provisioning.js

@@ -61,7 +61,7 @@ const PROJECT_TYPES = ['game', 'research', 'business', 'non-profit', 'not-sure']
 // 'disconnect' (task 1003249, migration provisioning_016): the owner's true delete — ./disconnect.js.
 // 'core-upgrade' (task 1003159, ADR 0293): move this instance's core pin — the owner's
 // deploy door. The web tier only QUEUES it; the control-plane runner performs it.
-const INTENT_ACTIONS = ['provision', 'teardown', 'oauth-manifest', 'domain-attach', 'settings-apply', 'restart', 'disconnect', 'core-upgrade'];
+const INTENT_ACTIONS = ['provision', 'teardown', 'oauth-manifest', 'domain-attach', 'settings-apply', 'restart', 'disconnect', 'core-upgrade', 'core-upgrade-preflight'];
 // Every state a teardown can be asked for — i.e. everything except the one
 // state where there is provably nothing left to release. DERIVED from
 // INSTANCE_STATES on purpose (task 1003042, walk finding N5): the old hand-kept

package/package-lock.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bongos/core",
-  "version": "1.19.923",
+  "version": "1.19.925",
   "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/provision-core-upgrade.js

@@ -30,7 +30,7 @@
 
 const path = require('path');
 const { CONFIG, MANIFEST_VERIFY_INTERVAL_MS, MANIFEST_VERIFY_TRIES, REPO_ROOT } = require('./provision-config.js');
-const { APP_USER, dbName, instanceUser, standaloneRoot } = require('./provision-repo.js');
+const { APP_USER, dbName, instanceUser, selfInstanceRoot, standaloneRoot } = require('./provision-repo.js');
 const { isValidSlug } = require('../../modules/provisioning/provisioning.js');
 
 // The shapes whose box this runner can actually reach. Mirrors UPGRADE_SHAPES in the
@@ -96,7 +96,19 @@ function targetFault(to, available, installed, channel, channelAllows) {
   if (!available.includes(to)) {
     return `core ${to} is not published yet — nothing was changed. A release tag appears several minutes before the package itself does; try again once it lands.`;
   }
-  if (installed && channelAllows && !channelAllows(installed, to, channel)) {
+  // AN UNREADABLE `installed` IS A FAULT, NOT A FREE PASS (task 1004123).
+  //
+  // This guard used to be written `if (installed && …)`, so a null installed version
+  // skipped the channel check entirely rather than failing it. That is backwards: not
+  // knowing where an instance is today is the one state in which "is this jump
+  // permitted" cannot be answered, and the channel exists precisely to refuse jumps
+  // nobody has looked at. It also hid the defect that motivated this: the control
+  // plane read its installed version from the wrong directory for weeks and got null
+  // every time, and every press sailed past this line.
+  if (!installed) {
+    return `could not read the core version installed at this instance — nothing was changed. An upgrade that cannot say where it is starting from cannot be bounded by the '${channel}' channel.`;
+  }
+  if (channelAllows && !channelAllows(installed, to, channel)) {
     return `core ${to} is outside this project's '${channel}' update channel — nothing was changed. Change the channel first if this is deliberate.`;
   }
   return null;
@@ -156,7 +168,8 @@ async function coreUpgradeInstance(inst, deps, intent) {
 
   // ---- 2. is the target real, and permitted -----------------------------------------
   const channelMod = deps.updateChannel || require('./update-channel.js');
-  const instanceDir = inst.hosting_shape === 'standalone' ? standaloneRoot(inst) : REPO_ROOT;
+  const selfRoot = deps.selfInstanceRoot || selfInstanceRoot;
+  const instanceDir = inst.hosting_shape === 'standalone' ? standaloneRoot(inst) : selfRoot();
   const readInstalled = deps.readInstalledCoreVersion || require('./upgrade.js').readInstalledCoreVersion;
   const installed = readInstalled(instanceDir);
   // THE PLATFORM DEFAULT, NOT A PER-INSTANCE CHANNEL — and saying so beats implying
@@ -184,73 +197,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, selfRoot });
 
   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 +254,116 @@ 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 = '', selfRoot = selfInstanceRoot } = {}) {
+  if (!isValidSlug(inst && inst.slug)) {
+    throw new Error(`upgradeInvocation: refusing to build a shell command from an invalid slug ${JSON.stringify(inst && inst.slug)}`);
+  }
+  // WHERE THE CLI LIVES AND WHERE THE TARGET LIVES ARE DIFFERENT PLACES, TWICE OVER.
+  //
+  // `upgrade.js` ships in the CORE, and a provisioned instance root holds no scripts/
+  // directory at all — so the CLI runs from REPO_ROOT and NAMES its target (task
+  // 1004053, which fixed every standalone tenant).
+  //
+  // The second half is that REPO_ROOT is not the instance either (task 1004123). It
+  // names the copy of the core that is EXECUTING, which coincides with the instance
+  // only while the core is a checkout run in place. Once the control plane's runner
+  // moved into its vendored core the two diverged silently — REPO_ROOT still resolved,
+  // just to node_modules/@bongos/core — and the door aimed at the package instead of
+  // the project. So ask, rather than assume; in the legacy shape the answer is
+  // REPO_ROOT and the command below is byte-identical to what it always was.
+  const instanceDir = inst.hosting_shape === 'standalone' ? standaloneRoot(inst) : selfRoot();
+  // 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}`];  // REPO_ROOT is where the CLI runs (runDir below)
+  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;
+  // A distinct local name: `deps.selfInstanceRoot || selfInstanceRoot` with a const of
+  // the same name would TDZ-shadow the import and crash every uninjected call.
+  const selfRoot = deps.selfInstanceRoot || selfInstanceRoot;
+  const { cmd, runDir } = upgradeInvocation(inst, to, { privileged, dryRun: true, selfRoot });
+  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.
  *
@@ -308,7 +382,8 @@ async function snapshotCoreVersions(inst, deps) {
   if (!UPGRADE_SHAPES.has(inst.hosting_shape) || inst.status !== 'active') return { ok: true, skipped: true };
   const boxExec = inst.hosting_shape === 'standalone' ? (deps.controlExec || exec) : exec;
   const channelMod = deps.updateChannel || require('./update-channel.js');
-  const instanceDir = inst.hosting_shape === 'standalone' ? standaloneRoot(inst) : REPO_ROOT;
+  const selfRoot = deps.selfInstanceRoot || selfInstanceRoot;
+  const instanceDir = inst.hosting_shape === 'standalone' ? standaloneRoot(inst) : selfRoot();
   try {
     const probe = boxExec(versionCmd(inst), { allowFail: true });
     const served = parseServedVersion(probe && !probe.softFailed ? (probe.stdout || '') : null);
@@ -323,14 +398,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 +439,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 };