@bongos/core 1.19.318 → 1.19.319

package/.bongos-core.json

@@ -2,11 +2,11 @@
   "artifact": "bongos-core",
   "manifest_schema": 1,
   "generator": "scripts/gds/package-core.js",
-  "core_version": "1.19.318",
-  "core_contract": "1.19.318",
-  "source_commit": "01d0a25617f7ca9212b310552724d7eb8c183a32",
+  "core_version": "1.19.319",
+  "core_contract": "1.19.319",
+  "source_commit": "682a79a31b7882310cc854404a34a8743b0e3804",
   "source_ref": "HEAD",
-  "built_at": "2026-08-23T22:11:19.148Z",
+  "built_at": "2026-08-23T22:19:11.577Z",
   "redaction": {
     "model": "docs-redacted+functional-verbatim",
     "docs_redacted": 323,
@@ -17,7 +17,7 @@
     "gate": "passed"
   },
   "file_count": 1783,
-  "tree_sha256": "24fa1a6a45d9a8ad89550dcdf06b82e5aeffa56776dcd6666a1be6524d9d4a6e",
+  "tree_sha256": "7c253e075a3fb04c94cc2fb0df42550178740faa03e84c8e9c1cb7675be2c23f",
   "files": [
     {
       "path": ".claude/skills/blocker-review/SKILL.md",
@@ -4642,12 +4642,12 @@
     {
       "path": "package-lock.json",
       "mode": "0000644",
-      "sha256": "509e4a76d5eb6f21fd8c926c6bf7ec9f1938d62ed4055558e2d3911858166b38"
+      "sha256": "cb1d669bd4b49b50fc37854b48c9363f3b6a7bccf503cd3a1291dfa87ac072ac"
     },
     {
       "path": "package.json",
       "mode": "0000644",
-      "sha256": "5e3c53bb9627f4dcf747e5e7bc8fa7fb0e136554f04d96081137ca1bc05654ad"
+      "sha256": "ca4620fbb1129ae165e0f7bfb9f4bc6d837c027a2d7326eec6d9418718bbf03c"
     },
     {
       "path": "public-docs/index.html",
@@ -5377,7 +5377,7 @@
     {
       "path": "scripts/gds/go-live.js",
       "mode": "0000644",
-      "sha256": "fa7803b178d64eda47d4f05032353582f7000359b13caea7d018112f03c9906a"
+      "sha256": "1e14a452c0ae53384facd6a20526a90106cb479c414937ebb7fe180f11c5fa31"
     },
     {
       "path": "scripts/gds/goal.js",
@@ -5947,7 +5947,7 @@
     {
       "path": "scripts/gds/update-channel.js",
       "mode": "0000644",
-      "sha256": "e4ad34a4a98ad6e7327922c36a60eb54cbb507ca3e26a9ec793f5a9390eacd77"
+      "sha256": "065095ccdcb104ede0312375484f62b23742fa1bc446f9749505c22b71babb5d"
     },
     {
       "path": "scripts/gds/upgrade.js",
@@ -6332,7 +6332,7 @@
     {
       "path": "src/module-api.js",
       "mode": "0000644",
-      "sha256": "af9d10cbaf1d6320df892f4d0e1403c0f5f1bb6e8c314695e89477690ba7fc85"
+      "sha256": "c918c65478a9b35e7a10371f117e8a826c063f577331147740f9fa8ffa121161"
     },
     {
       "path": "src/module-loader/catalog.js",
@@ -7257,7 +7257,7 @@
     {
       "path": "tests/go_live.mjs",
       "mode": "0000644",
-      "sha256": "360712fee43b00b410e4b3b8ca27e801ae41966ac0c5ce0a4679fa7943aa554b"
+      "sha256": "ce97c74d749ec3574c0683160b3ce5dad8a7af2dcf1ce53fd23e95f5e0ad480d"
     },
     {
       "path": "tests/goal_abuse_matrix.mjs",
@@ -8872,7 +8872,7 @@
     {
       "path": "tests/update_channel.mjs",
       "mode": "0000644",
-      "sha256": "4e082a36725d91f00d5fc0cc266d32bf607c144994ac88cb2abb3b49149632da"
+      "sha256": "3b0912dcda6888b4daa2cd13bbef0cddddafc425c39a509dc4955ce77ddd720e"
     },
     {
       "path": "tests/upgrade.mjs",

package/package-lock.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bongos/core",
-  "version": "1.19.318",
+  "version": "1.19.319",
   "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/go-live.js

@@ -76,8 +76,9 @@ function isSafeToken(v) {
 // The fields a target must carry, and the ones it may. Unknown keys are reported
 // rather than ignored: a typo'd `healthURL` that silently disables the health gate
 // is precisely the class of quiet failure this pipeline keeps being bitten by.
-const REQUIRED_FIELDS = ['ssh', 'instanceDir', 'service', 'healthUrl', 'versionUrl', 'deployTimer'];
-const OPTIONAL_FIELDS = ['deployService', 'npmEnvFile', 'runAs', 'backupDb', 'backupDir', 'env', 'registryPackage'];
+// `ssh` is NOT required: a target with no ssh host is LOCAL (the box driving itself).
+const REQUIRED_FIELDS = ['instanceDir', 'service', 'healthUrl', 'versionUrl', 'deployTimer'];
+const OPTIONAL_FIELDS = ['ssh', 'local', 'deployService', 'npmEnvFile', 'runAs', 'backupDb', 'backupDir', 'env', 'registryPackage'];
 
 function validateTarget(name, t) {
   const errors = [];
@@ -100,6 +101,10 @@ function validateTarget(name, t) {
       continue;
     }
     if (!known.has(k)) continue;
+    if (k === 'local') { // a flag, never interpolated into a command
+      if (typeof v !== 'boolean') errors.push(`target "${name}".local must be true or false`);
+      continue;
+    }
     if (!isSafeToken(v)) errors.push(`target "${name}".${k} contains characters that are unsafe in a shell (got ${JSON.stringify(v)})`);
   }
   return errors;
@@ -166,8 +171,32 @@ function selectTarget(config, name) {
 // the remote login shell). Values are validated above; this is the second layer.
 // ---------------------------------------------------------------------------
 
+// Privilege preamble for any phase that touches systemd.
+//
+// Over ssh these phases run as ROOT, so `systemctl stop …` just works — which is what
+// they originally assumed. Run LOCALLY by the nightly lane they run as the instance
+// OWNER, where the same line fails with "Interactive authentication required" and the
+// timer is never stopped: the pull-deploy `git reset --hard` then stays armed for the
+// whole upgrade, which is the exact hazard the stop exists to remove. Deciding at RUN
+// time keeps one script correct for both callers.
+const SUDO_PREAMBLE = 'SUDO=""; [ "$(id -u)" -eq 0 ] || SUDO="sudo -n"';
+
+// A target is LOCAL when it names no ssh host: the phases run through a local shell
+// instead of a remote one. Everything else — the phases, the halts, the reporting —
+// is byte-identical, which is the point: one deployment engine, reachable from a
+// laptop (remote) or from the box itself (local, how the nightly lane uses it).
+// Without this the unattended path would need its own second implementation, and the
+// two would drift — which is exactly how the nightly deploy ended up with weaker
+// checks than the manual one (task 1003219).
+function isLocalTarget(target) {
+  return !target || !target.ssh;
+}
+
 function remote(target, script, { run = spawnSync, timeoutMs = 900000 } = {}) {
-  const res = run('ssh', ['-o', 'ConnectTimeout=20', '-o', 'BatchMode=yes', target.ssh, 'bash', '-s'], {
+  const [cmd, args] = isLocalTarget(target)
+    ? ['bash', ['-s']]
+    : ['ssh', ['-o', 'ConnectTimeout=20', '-o', 'BatchMode=yes', target.ssh, 'bash', '-s']];
+  const res = run(cmd, args, {
     input: script, encoding: 'utf8', timeout: timeoutMs, maxBuffer: 32 * 1024 * 1024,
   });
   if (!res || res.error) return { ok: false, status: null, stdout: '', stderr: res && res.error ? res.error.message : 'spawn failed' };
@@ -177,36 +206,47 @@ function remote(target, script, { run = spawnSync, timeoutMs = 900000 } = {}) {
 // `sudo -u <user> -H env K=V … <cmd>` — the shape every runbook entry uses. Returns
 // a string safe to embed because every component was allowlist-validated.
 //
-// `forward` names variables that exist in the calling root shell and must reach the
-// child — NPM_TOKEN above all. sudo's env_reset drops it, and an explicit `env K=V`
-// list that omits it drops it too, so `npm install` 404s the PRIVATE package and the
-// upgrade auto-rolls-back, which reads as "the release is broken" when it is only
-// "the token never arrived". Sourcing the env file in the OUTER shell is necessary
-// and NOT sufficient.
+// A privileged child needs npm auth, and there is NO WAY to hand it a secret through
+// sudo without logging it (task 1003218, corrected).
+//
+//   `env NPM_TOKEN="$NPM_TOKEN" …`     → sudo logs it in COMMAND=
+//   `sudo --preserve-env=NPM_TOKEN …`  → sudo logs it in ENV=
 //
-// A FORWARDED VARIABLE IS A SECRET, SO IT MUST NOT ENTER argv (task 1003218).
-// `env K="$K"` keeps the value out of the script TEXT, but the shell EXPANDS it
-// before sudo runs — and sudo logs the full argv. That is how 26 lines of
-// `COMMAND=... NPM_TOKEN=npm_<real token> ...` ended up in the droplet's PERSISTENT
-// journal between 2026-08-17 and 2026-08-23. Passing by reference is NOT the same as
-// keeping a secret out of argv; only `--preserve-env` does that, handing the variable
-// over through the environment where nothing logs it. Verified side by side on the
-// box: both forms reach the child, only this one leaves no value in the journal.
+// The first was the original bug; the second was my "fix", which only MOVED the value
+// to a different field of the same log line. Both put a live credential in a
+// persistent journal. What matters is that sudo logs its whole invocation, so the
+// secret must never be part of it.
+//
+// So the child DERIVES the token itself, from a file it can already read. Only the
+// `sed` appears in argv; the value never does. This is the shape docs/recipes/
+// core-release-pipeline.md already documents as the safe one. The guard matters as
+// much as the derivation: an EMPTY token silently sends npm to the public registry,
+// which 404s the private package, which auto-rolls-back "cleanly" having taught you
+// nothing — so an empty read aborts loudly instead of half-running.
+//
+// (The nightly lane never takes this path: it runs under systemd as the owner with an
+// EnvironmentFile, no sudo, and leaks nothing. This is the manual/agent path only.)
+const NPM_AUTH_PREAMBLE = [
+  'export NPM_TOKEN="${NPM_TOKEN:-$(sed -n \'s/.*_authToken=//p\' "$HOME/.npmrc" 2>/dev/null | head -1)}"',
+  '[ -n "$NPM_TOKEN" ] || { echo "go-live: EMPTY NPM_TOKEN — npm would 404 the private core and roll back; aborting" >&2; exit 12; }',
+].join('; ');
+
+// `sudo -u <user> -H env K=V … <cmd>` — the shape every runbook entry uses. Returns
+// a string safe to embed because every component was allowlist-validated.
 //
-// The plain `env K=V` list is still used for NON-secret values (PGDATABASE, HOME) —
-// those are configuration, and seeing them in a log is useful rather than harmful.
-function asOwner(target, cmd, { forward = [] } = {}) {
+// `needsNpm` wraps the command so it derives its own npm auth (see above) instead of
+// having a secret handed across the privilege boundary. Only NON-secret configuration
+// (PGDATABASE, HOME) travels in the plain `env K=V` list — seeing those in a log is
+// useful rather than harmful.
+function asOwner(target, cmd, { needsNpm = false } = {}) {
+  const inner = needsNpm ? `sh -c ${shq(`${NPM_AUTH_PREAMBLE}; ${cmd}`)}` : cmd;
   const envPairs = Object.entries(target.env || {}).map(([k, v]) => `${k}=${v}`);
-  const preserve = forward.filter((k) => SAFE_ENV_KEY_RE.test(k)); // never interpolate an unvetted name
   if (!target.runAs) {
-    // No privilege drop: the child already inherits our environment, so a forwarded
-    // secret needs no mention at all.
     const joined = envPairs.join(' ');
-    return `${joined ? `env ${joined} ` : ''}${cmd}`.trim();
+    return `${joined ? `env ${joined} ` : ''}${inner}`.trim();
   }
-  const keep = preserve.length ? `--preserve-env=${preserve.join(',')} ` : '';
   const joined = [...envPairs, `HOME=/home/${target.runAs}`].join(' ');
-  return `sudo ${keep}-u ${target.runAs} -H env ${joined} ${cmd}`.trim();
+  return `sudo -u ${target.runAs} -H env ${joined} ${inner}`.trim();
 }
 
 // POSIX single-quote a value for embedding in a shell command.
@@ -264,6 +304,12 @@ function parseMarkerHits(raw) {
   return Number(first);
 }
 
+// Does this process sit inside a git repo that knows the given ref?
+function gitRefExists(ref, { run = spawnSync } = {}) {
+  const r = run('git', ['rev-parse', '--verify', '--quiet', ref], { cwd: ROOT, encoding: 'utf8' });
+  return !!r && !r.error && r.status === 0;
+}
+
 // Refresh origin/main before reading anything from it.
 //
 // deploy-divergence reads CORE_VERSION at the local `origin/main` REF, and a ref is
@@ -283,13 +329,6 @@ function refreshMain({ run = spawnSync } = {}) {
   return { ok: true };
 }
 
-// Which variables an npm-running command needs forwarded. Only when the target
-// declares an env file to source them from — otherwise `K="$K"` would expand to
-// empty and quietly do nothing.
-function npmForward(target) {
-  return target.npmEnvFile ? ['NPM_TOKEN'] : [];
-}
-
 // Parse a `key=value` marker into its parts. Kept pure + exported: the marker is
 // the answer to the trap that the release current when your fix merges usually
 // does NOT contain your fix (ADR 0161 carriers bump on their own cadence).
@@ -435,13 +474,13 @@ function probeRemote(target, targetVersion, marker, opts = {}) {
 set -uo pipefail
 ${src}
 echo "##REGISTRY##"
-${asOwner(target, `npm view ${pkg}@${targetVersion} version`, { forward: npmForward(target) })} 2>&1 | tail -1
+${asOwner(target, `npm view ${pkg}@${targetVersion} version`, { needsNpm: true })} 2>&1 | tail -1
 echo "##TREE##"
 ( cd ${target.instanceDir} && ${target.runAs ? `sudo -u ${target.runAs} -H ` : ''}git status --porcelain | head -20 )
 echo "##INSTALLED##"
 ${asOwner(target, `node -e "console.log(require('${target.instanceDir}/node_modules/${pkg}/package.json').version)"`)} 2>&1 | tail -1
 ${marker ? `echo "##MARKER##"
-${asOwner(target, `sh -c ${shq(markerProbe(pkg, targetVersion, marker))}`, { forward: npmForward(target) })}` : ''}
+${asOwner(target, `sh -c ${shq(markerProbe(pkg, targetVersion, marker))}`, { needsNpm: true })}` : ''}
 echo "##END##"
 `;
   const res = remote(target, script, opts);
@@ -479,7 +518,8 @@ function applyGoLive(target, targetName, targetVersion, from, opts = {}) {
     : 'echo "(no backupDb configured — skipping)"';
   const phaseA = remote(target, `
 set -euo pipefail
-echo "##TIMER##"; systemctl stop ${target.deployTimer} && systemctl is-active ${target.deployTimer} || true
+${SUDO_PREAMBLE}
+echo "##TIMER##"; $SUDO systemctl stop ${target.deployTimer} && $SUDO systemctl is-active ${target.deployTimer} || true
 echo "##BACKUP##"; ${backup}
 echo "##END##"
 `, opts);
@@ -499,7 +539,7 @@ echo "##END##"
   const phaseB = remote(target, `
 set -uo pipefail
 ${src}
-${asOwner(target, `bash -c "cd ${target.instanceDir} && ${upgrade}"`, { forward: npmForward(target) })}
+${asOwner(target, `bash -c "cd ${target.instanceDir} && ${upgrade}"`, { needsNpm: true })}
 `, opts);
   const rolledBack = /rolled back/i.test(phaseB.stdout + phaseB.stderr);
   steps.push({
@@ -510,7 +550,7 @@ ${asOwner(target, `bash -c "cd ${target.instanceDir} && ${upgrade}"`, { forward:
   if (!phaseB.ok || rolledBack) {
     // Restart the timer even on failure — leaving it stopped silently disables
     // the instance's pull-deploy until someone notices.
-    remote(target, `systemctl start ${target.deployTimer} || true`, opts);
+    remote(target, `${SUDO_PREAMBLE}\n$SUDO systemctl start ${target.deployTimer} || true`, opts);
     return { ok: false, steps, from, to: targetVersion, targetName, failedAt: 'UPGRADE', rolledBack, raw: phaseB };
   }
 
@@ -519,10 +559,11 @@ ${asOwner(target, `bash -c "cd ${target.instanceDir} && ${upgrade}"`, { forward:
   // not evidence; 127.0.0.1 is.
   const phaseC = remote(target, `
 set -uo pipefail
-echo "##TIMERSTART##"; systemctl start ${target.deployTimer}; systemctl is-active ${target.deployTimer}
+${SUDO_PREAMBLE}
+echo "##TIMERSTART##"; $SUDO systemctl start ${target.deployTimer}; $SUDO systemctl is-active ${target.deployTimer}
 echo "##PIN##"; ( cd ${target.instanceDir} && ${target.runAs ? `sudo -u ${target.runAs} -H ` : ''}git status --porcelain -- package.json package-lock.json )
 echo "##HEAD##"; ( cd ${target.instanceDir} && ${target.runAs ? `sudo -u ${target.runAs} -H ` : ''}git log -1 --format='%h %s' )
-${target.deployService ? `echo "##TICK##"; systemctl start ${target.deployService} || true; journalctl -u ${target.deployService} -n 20 --no-pager | tail -8` : ''}
+${target.deployService ? `echo "##TICK##"; $SUDO systemctl start ${target.deployService} || true; $SUDO journalctl -u ${target.deployService} -n 20 --no-pager | tail -8` : ''}
 echo "##VERSION##"; curl -s --max-time 20 ${target.versionUrl} | head -c 400
 echo ""
 echo "##INSTALLED##"; ${asOwner(target, `node -e "console.log(require('${target.instanceDir}/node_modules/${pkg}/package.json').version)"`)} 2>&1 | tail -1
@@ -563,6 +604,8 @@ go-live — move an enrolled instance's core pin, as one command.
   node scripts/gds/go-live.js --config <path>     default: ${DEFAULT_CONFIG}
   node scripts/gds/go-live.js --allow-unreleased  downgrade UNRELEASED_ON_MAIN to a warning
   node scripts/gds/go-live.js --no-fetch          skip the origin/main refresh (default: fetch)
+  node scripts/gds/go-live.js --target-json '{…}' pass a target inline instead of a config file
+  node scripts/gds/go-live.js --no-divergence     skip the git-derived checks (needs --to)
   node scripts/gds/go-live.js --json              machine-readable
 
 Host topology is NOT baked into the core. ${DEFAULT_CONFIG} (host-owned, not published):
@@ -578,6 +621,24 @@ async function main() {
   const apply = hasFlag('--apply');
   const allowUnreleased = hasFlag('--allow-unreleased');
 
+  // An inline target lets a CALLER drive this without inventing a second host-owned
+  // config file beside the one it already has. The nightly lane already holds a roster
+  // entry; making it also maintain config/go-live.json would be two sources of truth
+  // for one box, which is how they drift.
+  const inline = arg('--target-json');
+  if (inline) {
+    let parsed;
+    try { parsed = JSON.parse(inline); }
+    catch (e) { console.error(`  go-live: --target-json is not valid JSON — ${e.message}`); return 2; }
+    const errors = validateTarget('inline', parsed);
+    if (errors.length) {
+      if (json) { console.log(JSON.stringify({ ok: false, halt: 'CONFIG_INVALID', detail: errors.join('; ') }, null, 2)); return 1; }
+      console.error(`\n  go-live: CONFIG_INVALID — ${errors.join('; ')}\n`);
+      return 1;
+    }
+    return runGoLive({ target: parsed, targetName: arg('--target') || 'inline', configPath: '--target-json', json, apply, allowUnreleased });
+  }
+
   const cfg = loadConfig({ configPath: arg('--config') });
   if (cfg.error) {
     if (json) { console.log(JSON.stringify({ ok: false, halt: cfg.error, path: cfg.path, detail: cfg.detail }, null, 2)); return 1; }
@@ -595,7 +656,10 @@ async function main() {
     return 1;
   }
   const { target, name: targetName } = sel;
+  return runGoLive({ target, targetName, configPath: cfg.path, json, apply, allowUnreleased });
+}
 
+async function runGoLive({ target, targetName, configPath, json, apply, allowUnreleased }) {
   const marker = parseMarker(arg('--verify-marker'));
   if (marker && marker.error) { console.error(`  go-live: ${marker.error}`); return 2; }
 
@@ -603,18 +667,40 @@ async function main() {
   let targetVersion = arg('--to');
   if (targetVersion && !SEMVER_RE.test(targetVersion)) { console.error(`  go-live: --to "${targetVersion}" is not a version`); return 2; }
 
-  const fetched = hasFlag('--no-fetch') ? { ok: false, skipped: true } : refreshMain();
-  const div = await divergence.check({ base: arg('--url') });
+  // Is there a core GIT CHECKOUT to reason about at all?
+  //
+  // Every git-derived signal — the target read from origin/main, the UNRELEASED halt,
+  // the dirty-checkout halt — presumes this process is running inside a core repo.
+  // The nightly lane is NOT: it runs on the box, against an installed package, and it
+  // resolves its target from the REGISTRY under a channel policy instead. Running the
+  // git checks there would halt every sweep on a condition that does not apply.
+  //
+  // So the git legs are SKIPPED only when both are true: there is no resolvable
+  // origin/main, AND the caller named the version explicitly. A missing checkout with
+  // no --to is still an error — silently inventing a target is exactly the class of
+  // guess this script exists to refuse.
+  // "Am I in a SOURCE checkout?" is `.git` AT OUR ROOT — not "is there a git repo
+  // somewhere above me". The installed core package lives inside the INSTANCE's repo
+  // and ships its own src/module-api.js, so a naive `git rev-parse HEAD` succeeds
+  // there and CORE_VERSION resolves — against the instance repo's main, which is a
+  // meaningless answer delivered confidently. That is the failure this check avoids.
+  const hasCheckout = fs.existsSync(path.join(ROOT, '.git'));
+  const gitless = (!hasCheckout || hasFlag('--no-divergence')) && !!targetVersion;
+
+  const fetched = (gitless || hasFlag('--no-fetch')) ? { ok: false, skipped: true } : refreshMain();
+  const div = gitless ? null : await divergence.check({ base: arg('--url') });
   if (!targetVersion) targetVersion = div && div.onMain;
-  if (targetVersion && !SEMVER_RE.test(targetVersion)) {
-    console.error(`  go-live: could not resolve a target version (read ${JSON.stringify(targetVersion)} from main)`);
+  if (!targetVersion || !SEMVER_RE.test(targetVersion)) {
+    console.error(`  go-live: could not resolve a target version${hasCheckout ? ` (read ${JSON.stringify(targetVersion)} from main)` : ' — this is not a core source checkout, so pass --to <version>'}`);
     return 1;
   }
 
-  const dirtyRes = spawnSync('git', ['status', '--porcelain'], { cwd: ROOT, encoding: 'utf8' });
+  const dirtyRes = gitless ? { status: 1 } : spawnSync('git', ['status', '--porcelain'], { cwd: ROOT, encoding: 'utf8' });
   const dirtyCheckout = dirtyRes.status === 0 && (dirtyRes.stdout || '').trim() ? (dirtyRes.stdout || '').trim().split('\n').slice(0, 5).join(', ') : null;
 
-  const plan = planGoLive({ div, target, targetVersion, dirtyCheckout, allowUnreleased });
+  const plan = gitless
+    ? { halts: [], notes: [{ code: 'NO_CORE_CHECKOUT', message: `no core git checkout here — target ${targetVersion} was given explicitly, so the git-derived checks (unreleased-on-main, dirty tree) are skipped` }], from: null, targetVersion, target }
+    : planGoLive({ div, target, targetVersion, dirtyCheckout, allowUnreleased });
   plan.marker = marker;
   if (!fetched.ok && !fetched.skipped) {
     // Say so rather than silently planning off a ref of unknown age.
@@ -626,6 +712,14 @@ async function main() {
   if (!plan.halts.length) {
     const probe = probeRemote(target, targetVersion, marker);
     plan.registry = probe.registry;
+    // With no source checkout there is no git-derived `from`; the installed version on
+    // the box IS the truth, and the probe just read it.
+    if (gitless && probe.installed) {
+      plan.from = probe.installed;
+      if (probe.installed === targetVersion) {
+        plan.halts.push({ code: 'ALREADY_LIVE', message: HALTS.ALREADY_LIVE, detail: `installed and target are both ${targetVersion}` });
+      }
+    }
     if (!probe.reachable) {
       plan.halts.push({ code: 'BOX_UNREACHABLE', message: `could not reach ${target.ssh}`, detail: (probe.raw.stderr || '').trim().split('\n').pop() });
     } else {
@@ -656,7 +750,7 @@ async function main() {
 
   if (!apply || plan.halts.length) {
     if (json) { console.log(JSON.stringify({ ok: !plan.halts.length, mode: apply ? 'halted' : 'plan', targetName, ...plan }, null, 2)); }
-    else { console.log(renderPlan(plan, { targetName, configPath: cfg.path })); }
+    else { console.log(renderPlan(plan, { targetName, configPath })); }
     return plan.halts.length ? 1 : 0;
   }
 
@@ -675,6 +769,6 @@ if (require.main === module) {
 
 module.exports = {
   loadConfig, selectTarget, validateTarget, planGoLive, parseMarker, parseMarkerHits,
-  renderPlan, renderReport, failureExcerpt, asOwner, isSafeToken, npmForward, refreshMain,
+  renderPlan, renderReport, failureExcerpt, asOwner, isSafeToken, NPM_AUTH_PREAMBLE, refreshMain, isLocalTarget, gitRefExists, SUDO_PREAMBLE,
   CONFIG_TEMPLATE, HALTS, SEMVER_RE,
 };

package/scripts/gds/update-channel.js

@@ -159,6 +159,18 @@ function loadSubscriptions({ instanceDir = process.cwd(), fsImpl = fs, file = SU
       service: r.service ? String(r.service) : null,
       healthUrl: r.healthUrl ? String(r.healthUrl) : null,
       channel: normalizeChannel(r.channel == null ? defaultChannel : r.channel),
+      // Deploy topology (task 1003219). Optional, and only meaningful together: with
+      // versionUrl + deployTimer present the sweep can hand the bump to go-live.js and
+      // inherit its backup, pull-deploy-timer guard and INDEPENDENT box-side version
+      // read-back. Absent, the sweep falls back to calling `bongos upgrade` directly.
+      // Carried through here because a normalizer that silently drops a field makes an
+      // entry look enrolled while the capability it names never engages.
+      versionUrl: r.versionUrl ? String(r.versionUrl) : null,
+      deployTimer: r.deployTimer ? String(r.deployTimer) : null,
+      deployService: r.deployService ? String(r.deployService) : null,
+      backupDb: r.backupDb ? String(r.backupDb) : null,
+      backupDir: r.backupDir ? String(r.backupDir) : null,
+      registryPackage: r.registryPackage ? String(r.registryPackage) : null,
       // Per-instance env merged into the `bongos upgrade` child (e.g. PGDATABASE so the migrate step
       // hits THIS instance's DB, not the control plane's — see the live-op learnings for demo). Only
       // string values are kept; anything else is ignored.

package/src/module-api.js

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

package/tests/go_live.mjs

@@ -296,48 +296,40 @@ test("'could not check' is a distinct halt from 'absent'", () => {
 // `env K=V` list that omits it drops it too. This cost a real failed go-live.
 // ---------------------------------------------------------------------------
 
-test('a forwarded secret NEVER enters argv — it is handed over via --preserve-env', () => {
-  const cmd = G.asOwner({ runAs: 'lars', env: { PGDATABASE: 'cb' } }, 'npm install', { forward: ['NPM_TOKEN'] });
-  assert.match(cmd, /--preserve-env=NPM_TOKEN/);
-  // THE REGRESSION (task 1003218). `env K="$K"` kept the value out of the script TEXT,
-  // but the shell expands it before sudo runs and sudo LOGS THE FULL argv — which put
-  // the real token into the droplet's persistent journal 26 times. So the command must
-  // not mention the variable as an assignment at all, by reference or otherwise.
-  assert.ok(!/NPM_TOKEN=/.test(cmd.replace('--preserve-env=NPM_TOKEN', '')),
-    'a secret must never appear as an argv assignment — sudo logs argv');
-  // Non-secret config is still passed plainly; seeing PGDATABASE in a log is useful.
+test('a privileged npm command DERIVES its token — no secret in argv at all', () => {
+  const cmd = G.asOwner({ runAs: 'lars', env: { PGDATABASE: 'cb' } }, 'npm install', { needsNpm: true });
+  // THE REGRESSION, TWICE (task 1003218). `env NPM_TOKEN="$NPM_TOKEN"` put the value in
+  // sudo's COMMAND= field. `--preserve-env=NPM_TOKEN` moved it to sudo's ENV= field —
+  // a different field of the SAME log line, which is not a fix. sudo logs its whole
+  // invocation, so the only safe answer is that the secret is never part of it.
+  assert.ok(!/NPM_TOKEN=npm_/.test(cmd), 'no token VALUE may appear');
+  assert.ok(!/--preserve-env/.test(cmd), '--preserve-env logs the value in ENV=');
+  assert.ok(!/env [^;]*NPM_TOKEN="\$NPM_TOKEN"/.test(cmd), 'no by-reference assignment in argv either');
+  // What SHOULD be there: the child deriving it, and refusing to run on an empty read.
+  assert.match(cmd, /_authToken/);
+  assert.match(cmd, /EMPTY NPM_TOKEN/);
+  // Non-secret config still travels plainly.
   assert.match(cmd, /PGDATABASE=cb/);
 });
 
-test('forwarding is only wired when the target names an env file to source from', () => {
-  // Otherwise K="$K" expands to empty and silently does nothing — a quiet no-op
-  // is worse than not trying.
-  assert.deepEqual(G.npmForward({ npmEnvFile: '/etc/x/npm.env' }), ['NPM_TOKEN']);
-  assert.deepEqual(G.npmForward({}), []);
+test('an empty token ABORTS rather than half-running', () => {
+  // An empty token sends npm to the PUBLIC registry, which 404s the private core, which
+  // auto-rolls-back "cleanly" — a failure that teaches you nothing. Fail loudly instead.
+  assert.match(G.NPM_AUTH_PREAMBLE, /exit 12/);
 });
 
-test('an unvetted variable name never reaches the command', () => {
-  const cmd = G.asOwner({ runAs: 'me' }, 'x', { forward: ['GOOD', 'bad name', '$(id)', '1BAD'] });
-  assert.match(cmd, /--preserve-env=GOOD/);
-  assert.ok(!cmd.includes('bad name') && !cmd.includes('$(id)') && !cmd.includes('1BAD'));
-});
-
-test('with no privilege drop a secret needs no mention at all', () => {
-  // The child already inherits our environment, so naming it would be pure exposure.
-  const cmd = G.asOwner({ env: { A: 'b' } }, 'x', { forward: ['NPM_TOKEN'] });
-  assert.equal(cmd, 'env A=b x');
+test('a command that does not need npm is left alone', () => {
+  const cmd = G.asOwner({ runAs: 'me', env: { PGDATABASE: 'mydb' } }, 'echo hi');
+  assert.equal(cmd, 'sudo -u me -H env PGDATABASE=mydb HOME=/home/me echo hi');
   assert.ok(!cmd.includes('NPM_TOKEN'));
 });
 
-test('no forwarding leaves the documented sudo shape untouched', () => {
-  assert.equal(G.asOwner({ runAs: 'me', env: { PGDATABASE: 'mydb' } }, 'echo hi'),
-    'sudo -u me -H env PGDATABASE=mydb HOME=/home/me echo hi');
+test('with no privilege drop the command still derives its own auth', () => {
+  const cmd = G.asOwner({ env: { A: 'b' } }, 'npm x', { needsNpm: true });
+  assert.ok(!cmd.startsWith('sudo'));
+  assert.match(cmd, /_authToken/);
 });
 
-// ---------------------------------------------------------------------------
-// A failed run must say what the tool said
-// ---------------------------------------------------------------------------
-
 test('the report surfaces the failing tool’s own words', () => {
   const out = G.renderReport({
     ok: false, failedAt: 'UPGRADE', targetName: 'web', from: '1.19.305', to: '1.19.306',
@@ -378,3 +370,44 @@ test('a spawn error is handled, not thrown', () => {
   const r = G.refreshMain({ run: () => ({ error: new Error('ENOENT'), status: null }) });
   assert.equal(r.ok, false);
 });
+
+// ---------------------------------------------------------------------------
+// Local execution — one engine, two callers (task 1003219)
+//
+// The nightly lane runs ON the box, so it cannot reach the deploy path through ssh.
+// Without a local mode it would need a second implementation, and the two would
+// drift — which is exactly how the unattended deploy ended up with WEAKER checks
+// than the manual one (no backup, no timer guard, no independent read-back).
+// ---------------------------------------------------------------------------
+
+test('a target with no ssh host is local; one with an ssh host is not', () => {
+  const base = { instanceDir: '/i', service: 's.service', healthUrl: 'http://h', versionUrl: 'http://v', deployTimer: 'd.timer' };
+  assert.equal(G.isLocalTarget(base), true);
+  assert.equal(G.isLocalTarget({ ...base, ssh: 'my-box' }), false);
+});
+
+test('ssh is OPTIONAL — a local target validates clean', () => {
+  const local = { instanceDir: '/i', service: 's.service', healthUrl: 'http://h', versionUrl: 'http://v', deployTimer: 'd.timer' };
+  assert.deepEqual(G.validateTarget('local', local), []);
+});
+
+test('the remaining required fields are still enforced for a local target', () => {
+  const errs = G.validateTarget('local', { instanceDir: '/i' });
+  for (const f of ['service', 'healthUrl', 'versionUrl', 'deployTimer']) {
+    assert.match(errs.join(' '), new RegExp(`missing required field "${f}"`));
+  }
+  // ssh must NOT be demanded any more.
+  assert.ok(!/missing required field "ssh"/.test(errs.join(' ')));
+});
+
+test('`local` is a boolean flag, not a shell token', () => {
+  const base = { instanceDir: '/i', service: 's.service', healthUrl: 'http://h', versionUrl: 'http://v', deployTimer: 'd.timer' };
+  assert.deepEqual(G.validateTarget('t', { ...base, local: true }), []);
+  assert.match(G.validateTarget('t', { ...base, local: 'yes' }).join(' '), /must be true or false/);
+});
+
+test('gitRefExists reports rather than throwing', () => {
+  assert.equal(G.gitRefExists('x', { run: () => ({ status: 0 }) }), true);
+  assert.equal(G.gitRefExists('x', { run: () => ({ status: 1 }) }), false);
+  assert.equal(G.gitRefExists('x', { run: () => ({ error: new Error('ENOENT') }) }), false);
+});

package/tests/update_channel.mjs

@@ -184,3 +184,36 @@ t('loadSubscriptions: an entry without a dir is dropped (cannot be upgraded)', (
 
 console.log(`\nupdate_channel: ${passed} passed, ${failed} failed`);
 process.exit(failed ? 1 : 0);
+
+// ---------------------------------------------------------------------------
+// Deploy topology survives normalization (task 1003219)
+//
+// The sweep can only hand a bump to go-live.js — and so inherit its backup, its
+// pull-deploy-timer guard and its independent box-side read-back — if the roster's
+// topology actually REACHES the entry. The first cut of this dropped the new fields
+// on the floor, so an instance that named them looked enrolled while the sweep
+// quietly kept using the weaker direct path. A normalizer that silently discards a
+// field is indistinguishable from a feature that does not work.
+// ---------------------------------------------------------------------------
+
+test('deploy topology is carried through loadSubscriptions', () => {
+  const entry = {
+    slug: 's', dir: '/i', service: 'x.service', healthUrl: 'http://h',
+    versionUrl: 'http://v', deployTimer: 'd.timer', deployService: 'd.service',
+    backupDb: 'db', backupDir: '~/b', registryPackage: '@scope/core',
+  };
+  const fsImpl = { readFileSync: () => JSON.stringify({ instances: [entry] }) };
+  const { instances } = loadSubscriptions({ instanceDir: '/x', fsImpl });
+  assert.equal(instances.length, 1);
+  for (const k of ['versionUrl', 'deployTimer', 'deployService', 'backupDb', 'backupDir', 'registryPackage']) {
+    assert.equal(instances[0][k], entry[k], `${k} must survive normalization`);
+  }
+});
+
+test('an entry that names no topology reports null, not undefined', () => {
+  const fsImpl = { readFileSync: () => JSON.stringify({ instances: [{ slug: 's', dir: '/i' }] }) };
+  const { instances } = loadSubscriptions({ instanceDir: '/x', fsImpl });
+  for (const k of ['versionUrl', 'deployTimer', 'deployService', 'backupDb', 'backupDir']) {
+    assert.equal(instances[0][k], null, `${k} should be an explicit null`);
+  }
+});