@bongos/core 1.19.926 → 1.19.928

package/.bongos-core.json

@@ -2,11 +2,11 @@
   "artifact": "bongos-core",
   "manifest_schema": 1,
   "generator": "scripts/gds/package-core.js",
-  "core_version": "1.19.926",
-  "core_contract": "1.19.926",
-  "source_commit": "e29c4e2c4c22fc015eaaa56174f643b557051564",
+  "core_version": "1.19.928",
+  "core_contract": "1.19.928",
+  "source_commit": "261ed6d91994bae7a06841fd943e0737687a4306",
   "source_ref": "HEAD",
-  "built_at": "2026-09-20T23:12:12.395Z",
+  "built_at": "2026-09-21T00:22:12.769Z",
   "redaction": {
     "model": "docs-redacted+functional-verbatim",
     "docs_redacted": 511,
@@ -17,7 +17,7 @@
     "gate": "passed"
   },
   "file_count": 2851,
-  "tree_sha256": "7760b472bbc2c5cd345c6c4becda6c92d06d09c727c967667d7794740b51b8d6",
+  "tree_sha256": "b4640600eaa88633d42e88e234e812d059f570eaa8029a8ee15a71e6d3d3c910",
   "files": [
     {
       "path": ".claude/skills/ask-for-help/SKILL.md",
@@ -2677,7 +2677,7 @@
     {
       "path": "docs/module-api-changelog.md",
       "mode": "0000644",
-      "sha256": "b656ffb12e3d62e7042fbde0a6dc547d9b8b480ce2acacc21da0795443b117ac"
+      "sha256": "f346c24c2f8283aab581f3567876fd8a95cd625f7cfb71efdbcc5f240c850aea"
     },
     {
       "path": "docs/modules-contract.md",
@@ -6412,12 +6412,12 @@
     {
       "path": "modules/provisioning/control-plane-guard.js",
       "mode": "0000644",
-      "sha256": "b70ad687c7699a3023e8be973b67ceeb7ff67afb38ff47665c7089614901c200"
+      "sha256": "e1d060477287884f878748da4c2b7cfe164c782538728ffc7efc473c8b6a4997"
     },
     {
       "path": "modules/provisioning/core-upgrade.js",
       "mode": "0000644",
-      "sha256": "bd0109f1e270c868cc1c1d27d1c3b51ccb48c8b3d54c8274ffedbf2a4bbce051"
+      "sha256": "291a3765197f9429c70dd240fe5cdfa72a245ad3698c822032e71bb88999d533"
     },
     {
       "path": "modules/provisioning/credential-preflight.js",
@@ -7922,12 +7922,12 @@
     {
       "path": "package-lock.json",
       "mode": "0000644",
-      "sha256": "3ec884fff4704eceb947c709b0143b4428c435f8a7cad753d4c758028cf13bfd"
+      "sha256": "cbd8d9b4fa353962ff64a3f6a34ecec361a606052643189ab4d37512a7dd69ef"
     },
     {
       "path": "package.json",
       "mode": "0000644",
-      "sha256": "2e4530f1e38ef785e735ae6fc924451aab9d22beecdf2bb99af943cdfb470453"
+      "sha256": "5d1494f1844cf2fc5684fc5f2b01a5eaa12c3d096ed4e21cbaa18a8ec070e57e"
     },
     {
       "path": "public-docs/index.html",
@@ -8867,12 +8867,12 @@
     {
       "path": "scripts/gds/provision-config.js",
       "mode": "0000644",
-      "sha256": "d9d76ed5992ea84b347e0dbe37c78dda014df62208772ff00a2987d34ec27059"
+      "sha256": "68882e5e600881c0e3a96d4b84a9ad38dd77c3216a09a7886a263cfe40044f1e"
     },
     {
       "path": "scripts/gds/provision-core-upgrade.js",
       "mode": "0000644",
-      "sha256": "05292d556595bb3ce88a3e0b76c10c7cab2fef7f9d7e1af1e0b3610d48830692"
+      "sha256": "8ad61c85e0cf3f515fbd970fedcd6c33871d70e4dd42c36cb275ae907e31b655"
     },
     {
       "path": "scripts/gds/provision-disconnect.js",
@@ -8912,7 +8912,7 @@
     {
       "path": "scripts/gds/provision.js",
       "mode": "0000644",
-      "sha256": "2dee107429b1391e6e00a0c4915f9972c0e9d16f90a3d2ac111a34ffa5e7bc1d"
+      "sha256": "e384ffc0ecfcdb05d275d1245a6bc1214f2737c0fa67ae21eb8228ce1a398abf"
     },
     {
       "path": "scripts/gds/publish-credential-check.js",
@@ -9927,7 +9927,7 @@
     {
       "path": "src/module-api.js",
       "mode": "0000644",
-      "sha256": "938fdfedf2e8b99ae44c637371144016754b82cb8b96e254e47f8766e945a3b5"
+      "sha256": "06cd6203ef000d02b7a483f2423dcbf07d4fb3ed4a8376bd07d8ddb4f602edfe"
     },
     {
       "path": "src/module-loader/catalog.js",
@@ -10837,12 +10837,12 @@
     {
       "path": "tests/core_upgrade_door.mjs",
       "mode": "0000644",
-      "sha256": "c0457b6d1b0b0b3ee4117544e9203c28306a99772e2b085f0611132cf3d358d9"
+      "sha256": "bb2a39d645141a15b7391580069bf05b6f812e40f20d10fd55dbc564eb8f00ec"
     },
     {
       "path": "tests/core_upgrade_runner.mjs",
       "mode": "0000644",
-      "sha256": "994af91fda0df0ceb8b6e3eb80dd8bd23595a127a0e1d2e0381cb55e97beb557"
+      "sha256": "6077bfd9eca120db9dcfebec30fa355d0ae281df6cf9fbd6489203640051fcc1"
     },
     {
       "path": "tests/cosmos_token_contrast.mjs",
@@ -12937,7 +12937,7 @@
     {
       "path": "tests/provision.mjs",
       "mode": "0000644",
-      "sha256": "642ba54a20f08df1514f94114d39cdb70427f93542f4c060c83251ad1f46c80a"
+      "sha256": "4e1d463693cb7d5e363964360b72085d2307578bd430f2fee1129698d907a567"
     },
     {
       "path": "tests/provision_account_identity.mjs",

package/docs/module-api-changelog.md

@@ -2326,5 +2326,9 @@ is load-bearing: the script throws rather than guess if it is missing, and
         landed since 1.19.924 with no explicit bump. run 35542154729. (task 1002620)
   1.19.926 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
         landed since 1.19.925 with no explicit bump. run 35543911646. (task 1002620)
+  1.19.927 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+        landed since 1.19.926 with no explicit bump. run 35545006099. (task 1002620)
+  1.19.928 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+        landed since 1.19.927 with no explicit bump. run 35547446984. (task 1002620)
 ---------------------------------------------------------------------------
 ```

package/modules/provisioning/control-plane-guard.js

@@ -30,10 +30,18 @@
 //                  the door task 1003159 builds.
 //   restart      — the liveness remedy (task 1003238). Restarting the platform is
 //                  recoverable and already owner-initiated elsewhere.
+//   core-upgrade-preflight
+//                — `upgrade.js --dry-run`. It RUNS NOTHING: it returns at pre-flight
+//                  before the pin moves, before npm, before any restart. Refusing it
+//                  here protected the box from nothing and removed the feature from
+//                  everyone, because the control plane is the ONLY instance that runs
+//                  the provisioning module — so its hall is the only one with an
+//                  Upgrade page at all. A preview that cannot run where the button
+//                  lives is not a preview (task 1004125).
 //
 // Adding to this list is a deliberate edit someone has to argue for. It is pinned
 // by name in tests/core_upgrade_door.mjs so it cannot grow as a side effect.
-const CONTROL_PLANE_ACTIONS = Object.freeze(['core-upgrade', 'restart']);
+const CONTROL_PLANE_ACTIONS = Object.freeze(['core-upgrade', 'core-upgrade-preflight', 'restart']);
 
 /**
  * May this intent action be aimed at an instance of this hosting shape? PURE.

package/modules/provisioning/core-upgrade.js

@@ -209,6 +209,17 @@ function makeCoreUpgradeHandler({ provisioning, pool, parseId, validateOrRespond
       });
     } catch (err) {
       log.error('[provisioning] POST /provisioning/instances/:id/core-upgrade', err);
+      // A REFUSAL IS NOT AN OUTAGE. The control-plane guard throws an error carrying
+      // `code`, `status` and a `publicMessage` it wrote for exactly this moment — and
+      // this catch used to discard all three, so every guard refusal reached the owner
+      // as a 500 "internal error" while the real sentence sat in the journal. Nothing
+      // in the repo honoured `publicMessage`; it was assigned once and read never
+      // (task 1004125). Only an error that has already declared itself public is
+      // forwarded — anything else still gets the opaque 500, because an unexpected
+      // throw may carry anything.
+      if (err && err.publicMessage && err.code && err.status) {
+        return res.fail(err.code, { status: err.status, message: err.publicMessage });
+      }
       return res.fail('core_upgrade_failed', { status: 500, message: 'internal error' });
     }
   };

package/package-lock.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bongos/core",
-  "version": "1.19.926",
+  "version": "1.19.928",
   "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-config.js

@@ -30,6 +30,16 @@ function coreVersionSafe() {
   try { return require(path.join(REPO_ROOT, 'src/module-api')).CORE_VERSION; } catch { return null; }
 }
 
+// What an allowFail step returns when its command failed (task 1004128). It KEEPS the
+// output: a caller that opts into allowFail needs the reason, and returning an empty
+// string made every upgrade pre-flight report a generic "the dry run did not complete"
+// while `sudo: unknown user …` sat in the journal. WITHHELD when the step is
+// secret-bearing (a `shown` call site), where only an exit status may ever surface.
+function softFailResult(e, secretBearing) {
+  if (secretBearing) return { ok: true, stdout: '', softFailed: true };
+  return { ok: true, stdout: (e.stdout || '').toString(), stderr: (e.stderr || '').toString(), softFailed: true };
+}
+
 function numEnv(name, dflt) {
   const v = process.env[name];
   if (v == null || v === '') return dflt;
@@ -219,4 +229,5 @@ module.exports = {
   numEnv,
   oauthSecret,
   provisionerBotEmail,
+  softFailResult,
 };

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

@@ -203,7 +203,11 @@ async function coreUpgradeInstance(inst, deps, intent) {
     : '';
   // 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 });
+  // The preview probes; the move must probe identically or the two commands diverge on
+  // the one field task 1004121 exists to keep identical. Skipped when !apply, where the
+  // command is printed and never run — a plan should not spend a subprocess per tick.
+  const { runAs } = resolveRunAs(inst, deps, { probe: apply });
+  const { cmd, runDir } = upgradeInvocation(inst, to, { privileged, requestedBy, selfRoot, runAs });
 
   if (!apply) {
     // A --dry-run runner tick used to only PRINT this command. It now runs the CLI's own
@@ -269,6 +273,53 @@ function parsePreflight(out) {
   return { checks, error };
 }
 
+/**
+ * Which unix account should this instance's upgrade run as? Asks the box (task 1004128).
+ *
+ * The fleet is heterogeneous: instances provisioned before task 1003369 run as the
+ * shared APP_USER, instances provisioned after run as their own `bongos-<slug>`. Neither
+ * is guessable from the row, and getting it wrong is not a soft failure — `sudo` refuses
+ * an unknown user and the upgrade dies before pre-flight, which is exactly how the
+ * tenant leg has been broken.
+ *
+ * Falling back is NOT a privilege escalation: an instance with no account of its own is
+ * already running as APP_USER (its unit says so), so this runs the upgrade as precisely
+ * the account that owns the files and the database it is about to touch. It IS reported,
+ * because a missing per-instance account is a provisioning gap someone should close, and
+ * a silent fallback would hide it forever.
+ */
+function resolveRunAs(inst, deps, { probe: allowProbe = true } = {}) {
+  if (inst.hosting_shape === 'control-plane') return { runAs: APP_USER, fellBack: false };
+  // Re-checked HERE rather than left to instanceUser()'s own throw, for the reason
+  // upgradeInvocation states about itself: a call site whose safety depends on a
+  // helper's internals is one refactor away from a shell-interpolation path.
+  if (!isValidSlug(inst && inst.slug)) {
+    throw new Error(`resolveRunAs: refusing to probe an account for invalid slug ${JSON.stringify(inst && inst.slug)}`);
+  }
+  const wanted = instanceUser(inst);
+  if (!allowProbe) return { runAs: wanted, fellBack: false };
+  // THE SAME EXECUTOR THE UPGRADE ITSELF WILL USE. Every sibling here picks
+  // `standalone ? (controlExec || exec) : exec`, because under PROVISION_REMOTE_HOST
+  // (ADR 0130) `exec` is the REMOTE ssh executor while `controlExec` stays local. A
+  // probe on `exec` would then ask the co-hosting box whether an account exists while
+  // the command it is deciding for runs on the control plane — a wrong answer that
+  // looks like a right one.
+  const boxExec = inst.hosting_shape === 'standalone' ? (deps.controlExec || deps.exec) : deps.exec;
+  const r = boxExec(`id -u ${wanted}`, { allowFail: true });
+  const failed = !r || r.softFailed === true || r.ok === false;
+  if (!failed) return { runAs: wanted, fellBack: false };
+  // ONLY A DEFINITIVE "no such user" JUSTIFIES THE FALLBACK. A probe that could not
+  // answer — an exec timeout, an NSS hiccup — must not silently narrow the per-instance
+  // isolation of task 1003369 for this operation. So an inconclusive probe keeps the
+  // intended account: if it really is missing the upgrade fails loudly, and since this
+  // task a failure now carries the reason instead of "the dry run did not complete".
+  const said = `${(r && r.stdout) || ''}\n${(r && r.stderr) || ''}`;
+  if (!/no such user|unknown user/i.test(said)) {
+    return { runAs: wanted, fellBack: false, probeInconclusive: true };
+  }
+  return { runAs: APP_USER, fellBack: true, wanted };
+}
+
 // ONE BUILDER FOR BOTH LEGS (task 1004121).
 //
 // The preview and the move must be the same command or the preview is worthless — and
@@ -282,7 +333,7 @@ function parsePreflight(out) {
 // 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 } = {}) {
+function upgradeInvocation(inst, to, { privileged = false, dryRun = false, requestedBy = '', selfRoot = selfInstanceRoot, runAs = null } = {}) {
   if (!isValidSlug(inst && inst.slug)) {
     throw new Error(`upgradeInvocation: refusing to build a shell command from an invalid slug ${JSON.stringify(inst && inst.slug)}`);
   }
@@ -300,10 +351,25 @@ function upgradeInvocation(inst, to, { privileged = false, dryRun = false, reque
   // 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)} ` : '';
+  // WHICH ACCOUNT, AND WHY IT IS RESOLVED RATHER THAN DERIVED (task 1004128).
+  //
+  // Task 1004119 wrote this as `control-plane ? APP_USER : instanceUser(inst)` and was
+  // half right. The control-plane leg is correct and verified live. The tenant leg
+  // assumed the per-instance account model of task 1003369 is provisioned everywhere —
+  // and on the live box NO `bongos-*` account exists, no such Postgres role exists, and
+  // every instance unit still says `User=lars`. So the fix for "Postgres has no role
+  // root" swapped one absent account for another, and every tenant upgrade died with
+  // `sudo: unknown user bongos-test4`.
+  //
+  // The account model is a real security control, not an accident — a distinct uid per
+  // instance is what stops a co-tenant reading a sibling's /proc/<pid>/environ. So the
+  // answer is NOT to route everyone back to the shared account. It is to run as the
+  // account the instance ACTUALLY runs as, which a caller establishes by probing
+  // (resolveRunAs below) instead of either side assuming. Passing it in keeps this
+  // builder pure; the default preserves the old derivation for callers that have not
+  // probed.
+  const account = runAs || (inst.hosting_shape === 'control-plane' ? APP_USER : instanceUser(inst));
+  const sudoP = privileged ? `sudo -u ${account} 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)
@@ -315,7 +381,7 @@ function upgradeInvocation(inst, to, { privileged = false, dryRun = false, reque
       '--commit-pin',
       requestedBy ? `--requested-by ${requestedBy}` : '',
       requestedBy ? '--upgrade-source owner-control' : ''];
-  return { cmd: [...shared, ...tail].filter(Boolean).join(' '), runDir: REPO_ROOT, instanceDir, runAs };
+  return { cmd: [...shared, ...tail].filter(Boolean).join(' '), runDir: REPO_ROOT, instanceDir, runAs: account };
 }
 
 // Ask the upgrade CLI what it WOULD do, changing nothing. `allowFail` because a refusal
@@ -326,7 +392,8 @@ function preflightUpgrade(inst, to, deps) {
   // 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 { runAs, fellBack, wanted } = resolveRunAs(inst, deps);
+  const { cmd, runDir } = upgradeInvocation(inst, to, { privileged, dryRun: true, selfRoot, runAs });
   const r = boxExec(cmd, { cwd: runDir, allowFail: true });
   const out = `${(r && r.stdout) || ''}\n${(r && r.stderr) || ''}`;
   const { checks, error } = parsePreflight(out);
@@ -334,7 +401,20 @@ function preflightUpgrade(inst, to, deps) {
   // 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') };
+  // WHEN THERE IS NO ✖, SAY WHAT THE COMMAND SAID (task 1004128). The generic sentence
+  // is the LAST resort, not the first: the first live pre-flight reported "the dry run
+  // did not complete" while `sudo: unknown user bongos-test4` sat in the journal, and
+  // the second did the same over `✖ already on 1.19.927`. Both were in hand. The trim
+  // is because this reaches a DOM.
+  const raw = out.trim().split('\n').filter(Boolean).slice(-4).join('\n').slice(0, 600);
+  const why = error || (raw || null);
+  const note = fellBack
+    ? `ran as ${runAs} — this instance has no ${wanted} account yet (it predates the per-instance account model)`
+    : null;
+  return {
+    target: to, ok, lines: checks, ran_as: runAs, account_note: note,
+    error: ok ? null : (why || 'the dry run did not complete, and said nothing this could report'),
+  };
 }
 
 // Run a dry run for one instance and cache its verdict — the ON-DEMAND leg, drained from
@@ -439,4 +519,4 @@ async function snapshotAllCoreVersions(deps) {
   return { seen };
 }
 
-module.exports = { UPGRADE_SHAPES, versionCmd, parseServedVersion, targetFault, parsePreflight, upgradeInvocation, preflightUpgrade, preflightCoreUpgrade, coreUpgradeInstance, snapshotCoreVersions, snapshotAllCoreVersions };
+module.exports = { UPGRADE_SHAPES, resolveRunAs, versionCmd, parseServedVersion, targetFault, parsePreflight, upgradeInvocation, preflightUpgrade, preflightCoreUpgrade, coreUpgradeInstance, snapshotCoreVersions, snapshotAllCoreVersions };

package/scripts/gds/provision.js

@@ -49,7 +49,7 @@ const path = require('node:path');
 const cp = require('node:child_process');
 const crypto = require('node:crypto');
 
-const { CONFIG, MANIFEST_UA, MANIFEST_VERIFY_INTERVAL_MS, MANIFEST_VERIFY_TRIES, MAX_INTENT_ATTEMPTS, REPO_ROOT, coreVersionSafe, hasFlag, loadDeps, oauthSecret, provisionerBotEmail } = require('./provision-config.js');
+const { CONFIG, MANIFEST_UA, softFailResult, MANIFEST_VERIFY_INTERVAL_MS, MANIFEST_VERIFY_TRIES, MAX_INTENT_ATTEMPTS, REPO_ROOT, coreVersionSafe, hasFlag, loadDeps, oauthSecret, provisionerBotEmail } = require('./provision-config.js');
 const { APP_USER, accountPreflight, alreadyScaffolded, buildCorePinRefreshCommit, coreCheckoutHasGit, dbCreateCmd, dbName, dbRoleCmd, dbRoleCmdShown, dbRoleGrantsCmd, ensureInstanceUserCmd, generateDbPassword, grantInstanceRepoReadCmd, instanceDbRole, instanceStateDir, instanceUser, deployKeyPath, deployKeyTitle, ensurePrivateRepoAccess, installedCorePackDir, installedCoreTarball, instanceInitSpec, instanceRepoRemote, migrateCmd, onboardMode, ownerLoginOf, parseTargetRef, planCorePinRefresh, refreshStandaloneCorePin, resolveOwnerGithubToken, resolveVendorableCoreTarball, safeVersionLabel, scaffoldStandaloneRepo, seedFirstVersionCmd, standaloneInstallCmd, standaloneMigrateCmd, standalonePullCmd, standaloneRegenDocsCmd, standaloneRoot } = require('./provision-repo.js');
 const { backupScriptPath, backupService, backupServicePath, backupTimer, backupTimerPath, backupUnitName, instanceManifestCmd, originEnvVarsFor, serviceUnit, serviceUnitPath, settingsConsumed, settingsEnvVarsFor, upsertEnvVars, webEnvBody, webEnvPath } = require('./provision-units.js');
 const { caddyBlock, caddySnippetPath, checkCaddyWiring, checkDnsTokenScope, classifyZoneScope, dnsReleaseEnv, dnsUpsertEnv, federateInstance, federationHubOrigin, healthzCmd, identityCmd, identityVerdict, ingressPlaneGap, ingressPreflight, shouldFederate, zoneForDomain } = require('./provision-net.js');
@@ -95,7 +95,7 @@ function makeExec({ apply, log = console.log, remoteHost = null, remoteCwd = nul
         // `shown` call site is secret-bearing by declaration: log the exit status
         // alone, never stderr (a remote shell may echo the failing line back).
         const why = shownAs ? `exit status ${e && e.status != null ? e.status : '?'}` : (e.stderr || e.message || '').toString().trim().slice(0, 120);
-        if (allowFail) { log(`    ~ ${shown} (non-fatal: ${why})`); return { ok: true, stdout: '', softFailed: true }; }
+        if (allowFail) { log(`    ~ ${shown} (non-fatal: ${why})`); return softFailResult(e, !!shownAs); }
         log(`    ✖ ${shown}`);
         throw e;
       }
@@ -113,7 +113,7 @@ function makeExec({ apply, log = console.log, remoteHost = null, remoteCwd = nul
       // non-fatal line carries only the exit status — never e.message, whose
       // "Command failed: <cmd>" would echo the command back into the journal.
       const why = shownAs ? `exit status ${e && e.status != null ? e.status : '?'}` : (e.stderr || e.message || '').toString().trim().slice(0, 120);
-      if (allowFail) { log(`    ~ ${label} (non-fatal: ${why})`); return { ok: true, stdout: '', softFailed: true }; }
+      if (allowFail) { log(`    ~ ${label} (non-fatal: ${why})`); return softFailResult(e, !!shownAs); }
       log(`    ✖ ${label}`);
       throw e;
     }

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.926'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
+const CORE_VERSION = '1.19.928'; // 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

@@ -93,10 +93,29 @@ await t('every action not explicitly allowed is refused on the self row', () =>
   }
 });
 
-await t('the allow-list is exactly the two acts that cannot destroy the box', () => {
+await t('the allow-list is exactly the acts that cannot destroy the box', () => {
   // Pinned by NAME so widening it is a deliberate edit someone has to argue for,
-  // not a side effect of adding an action to INTENT_ACTIONS.
-  assert.deepEqual([...G.CONTROL_PLANE_ACTIONS].sort(), ['core-upgrade', 'restart']);
+  // not a side effect of adding an action to INTENT_ACTIONS. It did its job: adding
+  // 'core-upgrade-preflight' to INTENT_ACTIONS in task 1004121 did NOT reach here, and
+  // this line is what forced the argument to be made (task 1004125). The argument: a
+  // dry run returns at pre-flight having moved no pin, run no npm and restarted
+  // nothing, and the control plane is the only instance whose hall HAS an Upgrade
+  // page — so refusing the preview there protected nothing and removed everything.
+  assert.deepEqual([...G.CONTROL_PLANE_ACTIONS].sort(),
+    ['core-upgrade', 'core-upgrade-preflight', 'restart']);
+});
+
+await t('the preview is permitted on the control plane — the one row that can use it', () => {
+  assert.equal(G.intentAllowedForShape('core-upgrade-preflight', 'control-plane'), true);
+});
+
+await t('and widening it did NOT let the destructive acts through', () => {
+  // The whole risk of arguing one action onto an allow-list is arguing four.
+  for (const a of P.INTENT_ACTIONS) {
+    if (['core-upgrade', 'core-upgrade-preflight', 'restart'].includes(a)) continue;
+    assert.equal(G.intentAllowedForShape(a, 'control-plane'), false,
+      `'${a}' must still be refused against the box the platform runs on`);
+  }
 });
 
 await t('an ordinary instance is untouched by the guard', () => {
@@ -489,7 +508,7 @@ const validatorHarness = () => {
     fail: (code, o) => { body = { code, ...(typeof o === 'object' ? o : { status: o }) }; status = (o && o.status) || o || 400; return res; },
     status: (c) => { status = c; return res; },
   };
-  return { calls, handler, res, read: () => ({ body, status }) };
+  return { calls, handler, res, provisioning, read: () => ({ body, status }) };
 };
 
 await t('the preview payload the page posts is ACCEPTED, not refused as an unknown field', async () => {
@@ -503,6 +522,38 @@ await t('the preview payload the page posts is ACCEPTED, not refused as an unkno
   assert.ok(queued, 'and it reaches the queue as a PREVIEW, not as a move');
 });
 
+await t('a guard refusal reaches the owner as ITS OWN sentence, not "internal error"', async () => {
+  // The guard writes `code`, `status: 409` and a publicMessage for exactly this moment.
+  // The catch discarded all three, so every control-plane refusal this route ever made
+  // was shown as a 500 "internal error" while the real sentence sat in the journal —
+  // which is how the preview refusal stayed invisible until it was pressed live.
+  // Elsewhere in this file we already assert that sentence is well-formed; nothing
+  // asserted it ARRIVED.
+  const h = validatorHarness();
+  const refusal = Object.assign(new Error('blocked'), {
+    code: 'control_plane_protected', status: 409,
+    publicMessage: 'That action cannot be aimed at the machine the platform itself runs on.',
+  });
+  h.provisioning.enqueueIntent = async () => { throw refusal; };
+  await h.handler({ builder: { id: 42 }, params: { id: '7' }, body: { to: '1.19.926' } }, h.res);
+  const { body } = h.read();
+  assert.equal(body && body.code, 'control_plane_protected', 'the guard\'s own code, not core_upgrade_failed');
+  assert.equal(body && body.status, 409, 'a refusal is not a 500');
+  assert.match((body && body.message) || '', /cannot be aimed at the machine/);
+});
+
+await t('an UNEXPECTED throw is still opaque — this is not a blanket error passthrough', async () => {
+  // Forwarding every error would leak internals. Only an error that declared itself
+  // public (code + status + publicMessage) is forwarded.
+  const h = validatorHarness();
+  h.provisioning.enqueueIntent = async () => { throw new Error('connection terminated: relation "secrets" does not exist'); };
+  await h.handler({ builder: { id: 42 }, params: { id: '7' }, body: { to: '1.19.926' } }, h.res);
+  const { body } = h.read();
+  assert.equal(body && body.code, 'core_upgrade_failed');
+  assert.equal(body && body.message, 'internal error');
+  assert.ok(!/secrets|relation/.test(JSON.stringify(body)), 'no internals reach the client');
+});
+
 await t('the move payload still validates, and still queues a move', async () => {
   const h = validatorHarness();
   await h.handler({ builder: { id: 42 }, params: { id: '7' }, body: { to: '1.19.925' } }, h.res);

package/tests/core_upgrade_runner.mjs

@@ -647,5 +647,158 @@ await t('the runner refuses, and runs NOTHING, when it cannot see where the inst
   assert.equal(d.ranWith.filter((c) => /upgrade\.js/.test(c.cmd)).length, 0, 'the box was not touched');
 });
 
+
+console.log('\nwhich account, and saying what went wrong (task 1004128):');
+
+// A deps bag whose `id -u` probe can be made to succeed or fail, and whose upgrade
+// invocation can be made to soft-fail with real command output.
+function acctDeps({ accountExists = true, dryRunStdout = '', dryRunStderr = '', softFail = false } = {}) {
+  const d = makeDeps({ served: '1.19.762' });
+  d.privileged = true;
+  const ran = [];
+  d.ranWith = ran;
+  d.exec = (cmd, opts) => {
+    ran.push({ cmd, cwd: opts && opts.cwd });
+    if (/^id -u /.test(cmd)) {
+      if (accountExists) return { ok: true, stdout: '1001\n' };
+      // What `id -u` really says for an absent account — the definitive answer the
+      // fallback is allowed to act on.
+      return { ok: true, stdout: '', stderr: `id: '${cmd.split(' ').pop()}': no such user\n`, softFailed: true };
+    }
+    if (/\/version/.test(cmd)) return { ok: true, stdout: JSON.stringify({ coreVersion: '1.19.762' }) };
+    if (/upgrade\.js/.test(cmd)) {
+      return softFail
+        ? { ok: true, stdout: dryRunStdout, stderr: dryRunStderr, softFailed: true }
+        : { ok: true, stdout: dryRunStdout, stderr: dryRunStderr };
+    }
+    return { ok: true, stdout: '' };
+  };
+  return d;
+}
+
+await t('a tenant WITH its own account runs as that account — the security model is kept', () => {
+  // task 1003369: a distinct uid per instance is what stops a co-tenant reading a
+  // sibling's /proc/<pid>/environ. Falling back everywhere would quietly undo it.
+  const d = acctDeps({ accountExists: true });
+  const r = R.resolveRunAs(inst({ hosting_shape: 'standalone', slug: 'test4' }), d);
+  assert.deepEqual({ runAs: r.runAs, fellBack: r.fellBack }, { runAs: 'bongos-test4', fellBack: false });
+});
+
+await t('a tenant WITHOUT one falls back to the app user, and says so', () => {
+  // The live box has no bongos-* account at all, so every tenant upgrade died on
+  // `sudo: unknown user bongos-test4`. Falling back is not an escalation — the
+  // instance's own unit already says User=lars — but it IS a provisioning gap, so it
+  // is reported rather than silently papered over.
+  const d = acctDeps({ accountExists: false });
+  const r = R.resolveRunAs(inst({ hosting_shape: 'standalone', slug: 'test4' }), d);
+  assert.equal(r.runAs, 'lars');
+  assert.equal(r.fellBack, true);
+  assert.equal(r.wanted, 'bongos-test4', 'and names the account that is missing');
+});
+
+await t('the control plane is never probed — it has no instance account by design', () => {
+  const d = acctDeps({ accountExists: false });
+  const r = R.resolveRunAs(inst({ hosting_shape: 'control-plane', slug: 'cloudbongos' }), d);
+  assert.deepEqual({ runAs: r.runAs, fellBack: r.fellBack }, { runAs: 'lars', fellBack: false });
+  assert.equal(d.ranWith.filter((c) => /^id -u /.test(c.cmd)).length, 0, 'no probe was spent');
+});
+
+await t('the dry run is invoked as the account that actually exists', async () => {
+  const d = acctDeps({ accountExists: false, dryRunStdout: '  ✓ pre-flight: ok\n' });
+  await R.preflightUpgrade(inst({ hosting_shape: 'standalone', slug: 'test4', port: 3006 }), '1.19.762', d);
+  const cmd = (d.ranWith.find((c) => /upgrade\.js/.test(c.cmd)) || {}).cmd || '';
+  assert.match(cmd, /sudo -u lars /, `must not sudo to an account that does not exist — got: ${cmd}`);
+  assert.doesNotMatch(cmd, /bongos-test4/);
+});
+
+await t('the MOVE probes identically, so preview and move cannot diverge on the account', async () => {
+  const d = acctDeps({ accountExists: false });
+  await R.coreUpgradeInstance(inst({ hosting_shape: 'standalone', slug: 'test4', port: 3006 }), d, intent());
+  const cmd = (d.ranWith.find((c) => /upgrade\.js/.test(c.cmd)) || {}).cmd || '';
+  assert.match(cmd, /sudo -u lars /, 'the move follows the same probe as the preview');
+});
+
+await t('an INCONCLUSIVE probe keeps the isolated account rather than quietly widening it', () => {
+  // A probe that could not answer (exec timeout, NSS hiccup) is not evidence the
+  // account is absent. Falling back on it would narrow task 1003369's per-instance
+  // /proc isolation for that operation, silently, on a fleet where the account may
+  // well exist. Only `no such user` is evidence.
+  const d = makeDeps({ served: '1.19.762' });
+  d.exec = () => ({ ok: true, stdout: '', stderr: 'id: cannot connect to name service\n', softFailed: true });
+  const r = R.resolveRunAs(inst({ hosting_shape: 'standalone', slug: 'test4' }), d);
+  assert.equal(r.runAs, 'bongos-test4', 'the intended account is kept');
+  assert.equal(r.fellBack, false);
+  assert.equal(r.probeInconclusive, true, 'and the caller can tell it was not a clean answer');
+});
+
+await t('the probe uses the SAME executor the upgrade will use', () => {
+  // Under PROVISION_REMOTE_HOST (ADR 0130) `exec` is the remote ssh executor while
+  // `controlExec` stays local, and every sibling here picks controlExec for a
+  // standalone. A probe on the other one asks the wrong machine and gets a confident
+  // wrong answer.
+  const asked = { control: [], remote: [] };
+  const d = makeDeps({ served: '1.19.762' });
+  d.controlExec = (cmd) => { asked.control.push(cmd); return { ok: true, stdout: '1001\n' }; };
+  d.exec = (cmd) => { asked.remote.push(cmd); return { ok: true, stdout: '', stderr: "id: 'x': no such user\n", softFailed: true }; };
+  const r = R.resolveRunAs(inst({ hosting_shape: 'standalone', slug: 'test4' }), d);
+  assert.deepEqual(asked.remote, [], 'the remote executor was not asked');
+  assert.equal(asked.control.length, 1, 'the control-plane executor was');
+  assert.equal(r.runAs, 'bongos-test4', 'and its answer is the one that counts');
+});
+
+await t('a planning tick probes ONCE, not twice', async () => {
+  // The non-apply path prints the move it would make AND runs the CLI's own dry run, so
+  // one probe is real work. The second — for a command string that is only logged — was
+  // a subprocess per tick for nothing.
+  const d = acctDeps({ accountExists: false });
+  d.apply = false;
+  await R.coreUpgradeInstance(inst({ hosting_shape: 'standalone', slug: 'test4', port: 3006 }), d, intent());
+  assert.equal(d.ranWith.filter((c) => /^id -u /.test(c.cmd)).length, 1,
+    'exactly one probe: the dry run that actually executes');
+});
+
+await t('an invalid slug is refused by THIS call site, not merely by the helper it calls', () => {
+  // Asserting /invalid slug/ alone proves nothing: instanceUser() throws its own
+  // message matching that, so the test passes with this guard deleted — verified by
+  // deleting it. The point of the finding is that safety here must not DEPEND on the
+  // helper's internals, so the assertion names the thrower.
+  const d = acctDeps({});
+  assert.throws(
+    () => R.resolveRunAs({ hosting_shape: 'standalone', slug: 'bad slug;rm -rf /' }, d),
+    /resolveRunAs: refusing to probe/,
+    'the refusal must come from this function, not from instanceUser further down',
+  );
+  assert.equal(d.ranWith.filter((c) => /^id -u /.test(c.cmd)).length, 0, 'and nothing was executed');
+});
+
+await t('a refusal reports what the command SAID, not "did not complete"', async () => {
+  const d = acctDeps({ softFail: true, dryRunStderr: 'sudo: unknown user bongos-test4\n' });
+  const v = await R.preflightUpgrade(inst({ hosting_shape: 'standalone', slug: 'test4', port: 3006 }), '1.19.762', d);
+  assert.equal(v.ok, false);
+  assert.match(v.error, /unknown user bongos-test4/,
+    `the reason was in hand and must travel — got: ${JSON.stringify(v.error)}`);
+});
+
+await t('a ✖ line still wins over the raw tail', async () => {
+  const d = acctDeps({ softFail: true, dryRunStdout: 'noise\n  ✖ already on 1.19.927 (pass --force to re-run)\n' });
+  const v = await R.preflightUpgrade(inst({ hosting_shape: 'standalone', slug: 'test4', port: 3006 }), '1.19.762', d);
+  assert.match(v.error, /already on 1\.19\.927/);
+  assert.doesNotMatch(v.error, /^noise/, 'the parsed refusal is preferred to the raw tail');
+});
+
+await t('a fallback is recorded on the verdict the owner reads', async () => {
+  const d = acctDeps({ accountExists: false, dryRunStdout: '  ✓ pre-flight: ok\n' });
+  const v = await R.preflightUpgrade(inst({ hosting_shape: 'standalone', slug: 'test4', port: 3006 }), '1.19.762', d);
+  assert.equal(v.ran_as, 'lars');
+  assert.match(v.account_note, /no bongos-test4 account yet/);
+});
+
+await t('and a silent failure STILL refuses rather than inventing a pass', async () => {
+  const d = acctDeps({ softFail: true, dryRunStdout: '', dryRunStderr: '' });
+  const v = await R.preflightUpgrade(inst({ hosting_shape: 'standalone', slug: 'test4', port: 3006 }), '1.19.762', d);
+  assert.equal(v.ok, false, 'a command that said nothing is not a pass');
+  assert.match(v.error, /said nothing/);
+});
+
 console.log(`\ncore_upgrade_runner: ${passed} passed, ${failed} failed`);
 if (failed) process.exit(1);

package/tests/provision.mjs

@@ -3126,5 +3126,46 @@ await ta('provisionInstance: the password IS written to web.env, which makeWrite
   assert.ok(env.body.includes('PGUSER=bongos-mercury'));
 });
 
+
+// A soft failure must KEEP what the command said (task 1004128). `allowFail` exists so
+// a caller can act on a failure; returning stdout:'' left every such caller inventing a
+// generic sentence while the real reason sat in the journal. Two live pre-flights
+// reported "the dry run did not complete" over `sudo: unknown user bongos-test4` and
+// `✖ already on 1.19.927` — both were in hand and neither travelled.
+//
+// Driven through the REAL cp.execSync against a real failing shell, because the thing
+// being relied on is that Node populates e.stdout/e.stderr on a throw. A fake that
+// simply returns what the fix expects would prove nothing about that.
+t('makeExec(allowFail): a soft failure carries the command output back to the caller', () => {
+  const logs = [];
+  const run = P.makeExec({ apply: true, log: (m) => logs.push(m) });
+  const r = run(`sh -c 'echo "✖ already on 1.19.927"; echo "sudo: unknown user bongos-test4" 1>&2; exit 1'`, { allowFail: true });
+  assert.equal(r.softFailed, true, 'still a soft failure');
+  assert.equal(r.ok, true, 'and still ok:true — the caller decides, not the runner');
+  assert.match(r.stdout, /already on 1\.19\.927/, 'stdout survives');
+  assert.match(r.stderr, /unknown user bongos-test4/, 'stderr survives');
+});
+
+t('makeExec(allowFail): a SECRET-BEARING step still withholds its output', () => {
+  // `shownAs` means the command text is secret-bearing by declaration, and the journal
+  // deliberately carries only an exit status there. Returning its stderr would route
+  // around that control on the return value instead of the log.
+  const logs = [];
+  const run = P.makeExec({ apply: true, log: (m) => logs.push(m) });
+  const r = run(`sh -c 'echo "token=abcd1234"; echo "token=abcd1234" 1>&2; exit 1'`, { allowFail: true, shown: 'npm publish (token redacted)' });
+  assert.equal(r.softFailed, true);
+  assert.equal(r.stdout, '', 'no output escapes a secret-bearing step');
+  assert.ok(!/abcd1234/.test(JSON.stringify(r)), 'nothing token-shaped is on the result at all');
+  assert.ok(!logs.join('\n').includes('abcd1234'), 'nor in the log');
+});
+
+t('makeExec: a SUCCEEDING step is unchanged', () => {
+  const run = P.makeExec({ apply: true, log: () => {} });
+  const r = run(`sh -c 'echo fine'`, { allowFail: true });
+  assert.equal(r.ok, true);
+  assert.ok(!r.softFailed, 'no soft-fail marker on a success');
+  assert.match(r.stdout, /fine/);
+});
+
 console.log(`\nprovision: ${passed} passed, ${failed} failed`);
 process.exit(failed ? 1 : 0);