@bongos/core 1.19.313 → 1.19.315

package/.bongos-core.json

@@ -2,11 +2,11 @@
   "artifact": "bongos-core",
   "manifest_schema": 1,
   "generator": "scripts/gds/package-core.js",
-  "core_version": "1.19.313",
-  "core_contract": "1.19.313",
-  "source_commit": "f0f640457ac94cf62a4704d54abe9aa58632e183",
+  "core_version": "1.19.315",
+  "core_contract": "1.19.315",
+  "source_commit": "fa29b8da2f1429be8b46153157348ad0893bb702",
   "source_ref": "HEAD",
-  "built_at": "2026-08-23T21:45:16.664Z",
+  "built_at": "2026-08-23T21:55:22.014Z",
   "redaction": {
     "model": "docs-redacted+functional-verbatim",
     "docs_redacted": 323,
@@ -17,7 +17,7 @@
     "gate": "passed"
   },
   "file_count": 1766,
-  "tree_sha256": "92e06651a3b977ed15aece09dd42e0fa33db37b85170d195d0c1f8a11840144b",
+  "tree_sha256": "194e6d23ae1dc848c9e95e48b8383a33a401686fe98169758b9084884818966b",
   "files": [
     {
       "path": ".claude/skills/blocker-review/SKILL.md",
@@ -1672,7 +1672,7 @@
     {
       "path": "docs/recipes/core-release-pipeline.md",
       "mode": "0000644",
-      "sha256": "b42d8b4620355bef0e27480b2ddfaa07140e322de988839f0e102f1a1545ac47"
+      "sha256": "15517dbf462ce85e7d161b4e173c90376a19ecad3d0cf57a728f066533697bb2"
     },
     {
       "path": "docs/recipes/devbox-app-release.md",
@@ -1797,7 +1797,7 @@
     {
       "path": "docs/recipes/upgrading-the-core.md",
       "mode": "0000644",
-      "sha256": "732f3b01b7d2e6cc238dd5f48d5ed774f6c2c27ecc737710047758bf85f2d9e5"
+      "sha256": "82a8a5b17d465b9048ce645e2bc13acaa492f766726cc79981fff1352a92d1b0"
     },
     {
       "path": "docs/recipes/windows-builders.md",
@@ -4582,12 +4582,12 @@
     {
       "path": "package-lock.json",
       "mode": "0000644",
-      "sha256": "3e04f2907dd0a7d2cefbde8ae36e307e28fc703febd443d15fd2f204425d534d"
+      "sha256": "501134bb188ffffca60077b5b43b4e068e5713ff2c35002380cddad4a86076b4"
     },
     {
       "path": "package.json",
       "mode": "0000644",
-      "sha256": "81d11724ce5ac12446cf9d80adebe66eef5c8e5dc9082fc12ab493dbff60746a"
+      "sha256": "4e8358d26d8d6cdd6c5378b0860ebc58671a75d40ad790bb896000e91f9bd0c7"
     },
     {
       "path": "public-docs/index.html",
@@ -5317,7 +5317,7 @@
     {
       "path": "scripts/gds/go-live.js",
       "mode": "0000644",
-      "sha256": "05734e21763cc0b0614275efa76b7b68afabee8be93f3f2d797400d6a97e86c1"
+      "sha256": "fa7803b178d64eda47d4f05032353582f7000359b13caea7d018112f03c9906a"
     },
     {
       "path": "scripts/gds/goal.js",
@@ -5477,7 +5477,7 @@
     {
       "path": "scripts/gds/npmrc.js",
       "mode": "0000644",
-      "sha256": "9dfd27e75def392a73d7de7fd23d462afc97b17a8199acfe6563a80692570026"
+      "sha256": "1beffeed111e8528cfa0a629d5ef81c766023de5c6820a81659a390070868228"
     },
     {
       "path": "scripts/gds/oauth-secret.js",
@@ -5877,7 +5877,7 @@
     {
       "path": "scripts/gds/upgrade.js",
       "mode": "0000644",
-      "sha256": "04ee659f61c79a1dbc2302f047d1d7870352d0892c2df974f6f000184794d3f8"
+      "sha256": "80856db9974df9b3451decf55385eeb78bcba61e523ca09a2ea070deb48991ab"
     },
     {
       "path": "scripts/gds/validate-design.js",
@@ -6257,7 +6257,7 @@
     {
       "path": "src/module-api.js",
       "mode": "0000644",
-      "sha256": "b62609c76a5f302081de9ddec668656fd4d498dd10c545e9f108c4bf764e0ef8"
+      "sha256": "ce9693c479994dbf2f113c783048cd9b3dca8c3cdbc14c655ffdc0f893227eb3"
     },
     {
       "path": "src/module-loader/catalog.js",
@@ -7182,7 +7182,7 @@
     {
       "path": "tests/go_live.mjs",
       "mode": "0000644",
-      "sha256": "90c8cbfd8bf0b446261f9fd837b9b08b1035210f1cbf1f7ff81998ec535c32f1"
+      "sha256": "360712fee43b00b410e4b3b8ca27e801ae41966ac0c5ce0a4679fa7943aa554b"
     },
     {
       "path": "tests/goal_abuse_matrix.mjs",
@@ -7977,7 +7977,7 @@
     {
       "path": "tests/npmrc.mjs",
       "mode": "0000644",
-      "sha256": "87cbb8a5fd896f36197957be56c9107f672a49b2ae8afc3ba69fe00bde11c3ca"
+      "sha256": "1aaa68ee1a4c4a58563cef86aac44cfa0e046ad7376d3a2108bf6dd455580942"
     },
     {
       "path": "tests/oauth_secret.mjs",

package/docs/recipes/core-release-pipeline.md

@@ -188,6 +188,11 @@ The permission classifier blocks the agent from running a mutating `sudo -u lars
 What each piece is for — each guards a failure that actually happened:
 
 - **Token extraction runs as lars** (the whole command is inside `sudo -u lars bash -c`). Reading `/home/lars/.npmrc` as `jaxri` is `Permission denied`, which yields an **empty** `NPM_TOKEN`, which sends npm to the **public** registry, which 404s on the private `@bongos/core` — and the upgrade rolls back cleanly, having taught you nothing. The `[ -n "$NPM_TOKEN" ] || exit` guard aborts instead of half-running.
+- **Never put the token in the command line — `sudo` logs the full argv (task 1003218).** The shape above is safe *because* the token is read INSIDE the quoted script, so only the `grep` reaches argv. The tempting variant is not:
+  ```
+  sudo -u lars -H env NPM_TOKEN="<redacted>" … bongos upgrade …     # ← LEAKS
+  ```
+  The shell expands `$NPM_TOKEN` before `sudo` ever runs, so the real token lands in the system journal — which is persistent on this box. That variant put the live token into 26 journal lines between 2026-08-17 and 2026-08-23. If you need to hand a secret to a privileged child, use `sudo --preserve-env=NPM_TOKEN …`, which passes it through the environment where nothing logs it. Passing "by reference" in the script text is NOT enough; what matters is what argv looks like after expansion.
 - **`--to <VER>` is required** — `bongos upgrade` refuses to guess a target.
 - **`--service` + `--health-url` buy the automatic rollback.** Point the health URL at `http://127.0.0.1:3002/healthz`, **not the public URL** — a pre-launch `basic_auth` on the apex makes a healthy boot look failed and triggers a needless rollback.
 - **`--commit-pin` commits AND pushes the pin.** The instance is a pull-deploy repo: the next sync runs `git reset --hard origin/main`, which reverts an uncommitted pin, and `npm ci` then reinstalls the old core. Nothing errors. This is exactly how live sat 13 releases behind (task 1002712). The same applies to any tracked instance-config edit (`config/branding.json`): commit + push or the next deploy tick undoes it. A commit that fails to *push* saves nothing — deploy.sh resets to the remote.

package/docs/recipes/upgrading-the-core.md

@@ -116,6 +116,8 @@ Each subscribed instance: read its installed core → ask the registry (`npm vie
 
 ## Gotchas
 
+- **`--registry` no longer needs a hand-exported `NPM_TOKEN`** (task 1002754). The instance `.npmrc` reads `_authToken=<redacted>, and npm gives that per-project key precedence — so with the env var unset it expanded EMPTY and **masked a perfectly valid literal token in `~/.npmrc`** (npm went anonymous; the private core 404'd; the error blamed a "missing" credential the box actually held). `bongos upgrade --registry` now resolves the credential itself: env `NPM_TOKEN` wins, else the **user-level `~/.npmrc`'s literal `//registry.npmjs.org/:_authToken=…`** is injected into the install's environment (forward install and rollback reinstall both). A pin bump on a box whose `~/.npmrc` authenticates therefore succeeds with **no exported env var**. Resolver: `resolveNpmToken()` in [`scripts/gds/npmrc.js`](../../scripts/gds/npmrc.js).
+- **A green `publish` run is not evidence of a publish.** The publish-on-merge lane succeeds on its no-op paths too (cascade terminator, armed-gate). Read the run's **job summary**, which now states the verdict explicitly: `PUBLISHED @bongos/core@<v>` vs `NO-OP — nothing was published this run`.
 - **`PGDATABASE` is load-bearing on a co-tenant droplet.** `migrate.sh` defaults `PGDATABASE` to `example` — **production**. Always set `PGDATABASE=<instance-db>` explicitly, or you migrate the wrong database.
 - **The health check polls the restart** (fixed in task [#1984](https://example.com/builders#/task/1984)). The service binds its port ~1s after `systemctl restart`, so `--health-url` now polls up to ~30s for a 2xx before reporting a warning — an immediate `fetch failed` no longer means a failed upgrade. (Pre-1984 cores fetched once and spuriously reported `fetch failed`; there, confirm with `is-active` + a manual `curl`.)
 - **The ledger auto-inserts via `PGDATABASE` too** (fixed in task [#1984](https://example.com/builders#/task/1984)). A consumer on `PGDATABASE` + peer auth now gets its `core_upgrades` row written automatically — the channel delegates the insert to `psql -d "$PGDATABASE"`, exactly like `migrate.sh`, so no manual `psql INSERT` is needed. (`DATABASE_URL` still works, via the `pg` driver.) Pre-1984 cores only auto-wrote with `DATABASE_URL`; on those, record the row manually.

package/package-lock.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bongos/core",
-  "version": "1.19.313",
+  "version": "1.19.315",
   "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

@@ -177,22 +177,36 @@ 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 to pass through BY REFERENCE (`K="$K"`), for values that
-// exist in the calling root shell but must not appear in this script's text. That is
-// how NPM_TOKEN reaches the upgrade: 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; this is the second half of that trap.
+// `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 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 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 = [] } = {}) {
   const envPairs = Object.entries(target.env || {}).map(([k, v]) => `${k}=${v}`);
-  for (const k of forward) {
-    if (!SAFE_ENV_KEY_RE.test(k)) continue; // never interpolate an unvetted name
-    envPairs.push(`${k}="$${k}"`);          // by reference — the VALUE is never written here
+  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();
   }
-  const joined = envPairs.join(' ');
-  const prefix = target.runAs ? `sudo -u ${target.runAs} -H env ${joined} HOME=/home/${target.runAs}` : (joined ? `env ${joined}` : '');
-  return `${prefix} ${cmd}`.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();
 }
 
 // POSIX single-quote a value for embedding in a shell command.

package/scripts/gds/npmrc.js

@@ -48,6 +48,37 @@ function hasNpmToken(env = process.env) {
   return !!String(env[TOKEN_ENV] || '').trim();
 }
 
+// resolveNpmToken (task 1002754) — the install-time credential resolver that removes
+// the hand-exported-NPM_TOKEN step from deploys.
+//
+// THE TRAP. The committed instance `.npmrc` reads `_authToken=${NPM_TOKEN}`; npm gives
+// a per-project key precedence over the user-level one, so with NPM_TOKEN unset the
+// expansion is EMPTY and it MASKS a perfectly valid literal token in ~/.npmrc — npm
+// goes anonymous and the private core 404s. Every deploy then silently depended on the
+// operator remembering `export NPM_TOKEN=…` (the ADR-0162 shape: a human-gated step in
+// the ship path). npm's config syntax cannot express "env var, else fall through", so
+// the fix is to RESOLVE the credential here and feed it to the child install's env —
+// the committed file stays secret-free and unchanged.
+//
+// Order: env NPM_TOKEN wins (explicit operator intent), else the user-level ~/.npmrc's
+// literal `//<host>/:_authToken=<value>` (ignoring env-fed `${…}` values — those are
+// the trap, not a credential). Returns { token, source: 'env'|'user-npmrc'|null }.
+function resolveNpmToken({ env = process.env, homedir, fsImpl = fs, host = REGISTRY_HOST } = {}) {
+  const fromEnv = String(env[TOKEN_ENV] || '').trim();
+  if (fromEnv) return { token: fromEnv, source: 'env' };
+  const home = homedir || (env.HOME || env.USERPROFILE || '');
+  if (home) {
+    try {
+      const raw = fsImpl.readFileSync(path.join(home, '.npmrc'), 'utf8');
+      const re = new RegExp(`^\\s*//${host.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}/:_authToken\\s*=\\s*(.+?)\\s*$`, 'm');
+      const m = re.exec(raw);
+      const val = m && m[1].replace(/^["']|["']$/g, '');
+      if (val && !val.includes('${')) return { token: val, source: 'user-npmrc' };
+    } catch { /* no user npmrc, unreadable — fall through to null */ }
+  }
+  return { token: null, source: null };
+}
+
 // Has the operator opted the standalone scaffold into the registry path? OFF by
 // default — the vendored tarball stays the default until the registry path is proven
 // end-to-end (ADR 0134). '1'/'true'/'yes'/'on' (case-insensitive) → true.
@@ -76,7 +107,7 @@ function writeNpmrc(dir, { fsImpl = fs, dryRun = false, overwrite = true, log =
 
 module.exports = {
   REGISTRY_HOST, CORE_SCOPE, TOKEN_ENV, REQUEST_ENV,
-  npmrcContent, hasNpmToken, registryCoreRequested, writeNpmrc,
+  npmrcContent, hasNpmToken, resolveNpmToken, registryCoreRequested, writeNpmrc,
 };
 
 // Tiny CLI: `node scripts/gds/npmrc.js [--print | --write <dir>]` — print the `.npmrc`

package/scripts/gds/upgrade.js

@@ -30,7 +30,7 @@ const fs = require('node:fs');
 const path = require('node:path');
 const { spawnSync } = require('node:child_process');
 const { arg, hasFlag } = require('./cli-lib');
-const { writeNpmrc, hasNpmToken } = require('./npmrc'); // ADR 0134 (task 2090): the --registry channel's env-fed .npmrc
+const { writeNpmrc, hasNpmToken, resolveNpmToken } = require('./npmrc'); // ADR 0134 (task 2090): the --registry channel's env-fed .npmrc; resolveNpmToken task 1002754
 
 const CORE_PKG = '@bongos/core';
 const ARTIFACT = 'bongos-core';
@@ -284,10 +284,14 @@ function reportModulePreflight(mods, targetVersion, { log = console.log, err = c
   return lines;
 }
 
-function npmInstall(instanceDir, run = spawnSync) {
+function npmInstall(instanceDir, run = spawnSync, extraEnv = null) {
   // `npm install` (NOT `npm ci`): the pin just changed, so the lockfile must be regenerated from the
   // new tarball; `npm ci` would refuse on the package.json↔lock divergence.
-  const r = run('npm', ['install', '--no-audit', '--no-fund'], { cwd: instanceDir, stdio: 'inherit' });
+  // extraEnv (task 1002754): the registry path injects a resolved NPM_TOKEN here so the
+  // instance `.npmrc`'s `${NPM_TOKEN}` expansion never shadows a valid user-level token.
+  const opts = { cwd: instanceDir, stdio: 'inherit' };
+  if (extraEnv) opts.env = { ...process.env, ...extraEnv };
+  const r = run('npm', ['install', '--no-audit', '--no-fund'], opts);
   return !r || r.error ? { ok: false, reason: r && r.error ? r.error.message : 'spawn failed' } : { ok: r.status === 0, code: r.status };
 }
 
@@ -703,8 +707,11 @@ async function rollback({ instanceDir, snapshot, fromVersion, toVersion, opts },
   try { restore(instanceDir, snapshot.prevPin, fsImpl); result.restoreOk = true; log(`  ✓ restored pin → ${snapshot.prevPin}`); }
   catch (e) { result.restoreOk = false; err(`  ! could not restore pin (${e.message}) — package.json may need manual repair`); }
 
-  // 2. reinstall the previous core.
-  const inst = npmInstall(instanceDir, run);
+  // 2. reinstall the previous core. Same credential resolution as the forward path
+  //    (task 1002754): the previous pin may be a registry pin too, and a rollback
+  //    must never fail on the env-shadowing trap the forward install just avoided.
+  const rbCred = resolveNpmToken();
+  const inst = npmInstall(instanceDir, run, rbCred.source === 'user-npmrc' ? { NPM_TOKEN: rbCred.token } : null);
   result.reinstallOk = !!inst.ok;
   if (inst.ok) log('  ✓ reinstalled previous core');
   else err(`  ! reinstall of previous core failed (${inst.reason || 'exit ' + inst.code}) — the instance may need manual repair`);
@@ -813,9 +820,17 @@ async function runUpgrade(opts, deps = {}) {
   //    REGISTRY (--registry): pin @bongos/core@<version> + ensure the env-fed .npmrc, so
   //      the `npm install` below pulls the PRIVATE package from the registry (needs NPM_TOKEN).
   //    VENDORED (default, --from <tgz>): copy the .tgz into vendor/ + rewrite the file: dep.
+  let installEnv = null;
   if (opts.registry) {
     if (opts.from) return { ok: false, error: '--registry and --from are mutually exclusive (registry pull vs vendored tarball) — pick one core source' };
-    if (!hasNpmToken()) log('  ! no NPM_TOKEN in env — `npm install` will 404 on the PRIVATE @bongos/core until a read-only automation token is provided (ADR 0134).');
+    // task 1002754 — resolve the credential HERE instead of demanding a hand-exported
+    // env var: env NPM_TOKEN wins, else the user-level ~/.npmrc's literal token is
+    // injected into the install's env so the instance `.npmrc`'s `${NPM_TOKEN}`
+    // expansion (which OUTRANKS the user-level key and expands EMPTY when unset)
+    // can never shadow a working credential again.
+    const cred = resolveNpmToken();
+    if (!cred.token) log('  ! no NPM_TOKEN in env and no literal token in ~/.npmrc — `npm install` will 404 on the PRIVATE @bongos/core until a read-only automation token is provided (ADR 0134).');
+    else if (cred.source === 'user-npmrc') { installEnv = { NPM_TOKEN: cred.token }; log('  ✓ registry credential: inherited from the user-level ~/.npmrc (no NPM_TOKEN export needed — task 1002754)'); }
     const prevPin = dryRun ? null : writeRegistryPin(instanceDir, targetVersion, fsImpl);
     if (!dryRun) { writeNpmrc(instanceDir, { fsImpl, overwrite: false, log }); snapshot = { prevPin, prevVersion: fromVersion }; }
     log(`  ${dryRun ? '[dry-run] would pin' : '✓ pinned'} ${CORE_PKG} → ${targetVersion} (registry)${dryRun ? ' + write an env-fed .npmrc' : ''}${prevPin ? `  (was ${prevPin})` : ''}`);
@@ -837,7 +852,7 @@ async function runUpgrade(opts, deps = {}) {
   if (dryRun) { log('  [dry-run] would: npm install → npm run migrate → materialize .claude → regen API docs+client → restart → verify'); return { ok: true, dryRun: true, fromVersion, toVersion: targetVersion }; }
 
   // 3. npm install.
-  const inst = npmInstall(instanceDir, run);
+  const inst = npmInstall(instanceDir, run, installEnv);
   if (!inst.ok) {
     const error = `npm install failed (${inst.reason || 'exit ' + inst.code})`;
     if (rollbackOnFailure && snapshot) {

package/src/module-api.js

@@ -1053,8 +1053,12 @@ const { validateOrRespond, LIMITS, parseId, asyncHandler, corsPublicGet, parsePa
 //         landed since 1.19.311 with no explicit bump. run 32665664699. (task 1002620)
 //   1.19.313 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
 //         landed since 1.19.312 with no explicit bump. run 32668457836. (task 1002620)
+//   1.19.314 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+//         landed since 1.19.313 with no explicit bump. run 32668599111. (task 1002620)
+//   1.19.315 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+//         landed since 1.19.314 with no explicit bump. run 32668969037. (task 1002620)
 // ---------------------------------------------------------------------------
-const CORE_VERSION = '1.19.313'; // CI auto-patch carrier (ADR 0161); see changelog above
+const CORE_VERSION = '1.19.315'; // 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,11 +296,17 @@ 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 var is passed BY REFERENCE, never by value', () => {
+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, /NPM_TOKEN="\$NPM_TOKEN"/);
-  // The point of by-reference: the secret's VALUE must never appear in the script text.
-  assert.ok(!cmd.includes('npm_'), 'a token value must never be interpolated here');
+  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.
+  assert.match(cmd, /PGDATABASE=cb/);
 });
 
 test('forwarding is only wired when the target names an env file to source from', () => {
@@ -310,12 +316,24 @@ test('forwarding is only wired when the target names an env file to source from'
   assert.deepEqual(G.npmForward({}), []);
 });
 
-test('an unvetted variable name is never interpolated', () => {
+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, /GOOD="\$GOOD"/);
+  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');
+  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');
+});
+
 // ---------------------------------------------------------------------------
 // A failed run must say what the tool said
 // ---------------------------------------------------------------------------

package/tests/npmrc.mjs

@@ -100,6 +100,55 @@ test('writeNpmrc: overwrite:true (default) replaces an existing .npmrc', () => {
   } finally { rmSync(dir, { recursive: true, force: true }); }
 });
 
+// ---- resolveNpmToken (task 1002754) ----------------------------------------
+// The install-time credential resolver that removes the hand-exported-NPM_TOKEN
+// deploy step: env wins, else the user-level ~/.npmrc's LITERAL token; env-fed
+// `${…}` values in the user file are the trap, never a credential.
+test('resolveNpmToken: env NPM_TOKEN wins over everything', () => {
+  const home = mkdtempSync(join(tmpdir(), 'npmrc-home-'));
+  try {
+    writeFileSync(join(home, '.npmrc'), '//registry.npmjs.org/:_authToken=npm_userlevel\n');
+    const r = n.resolveNpmToken({ env: { NPM_TOKEN: ' npm_fromenv ' }, homedir: home });
+    assert.deepEqual(r, { token: 'npm_fromenv', source: 'env' });
+  } finally { rmSync(home, { recursive: true, force: true }); }
+});
+
+test('resolveNpmToken: falls back to the user-level ~/.npmrc literal token', () => {
+  const home = mkdtempSync(join(tmpdir(), 'npmrc-home-'));
+  try {
+    writeFileSync(join(home, '.npmrc'),
+      'registry=https://registry.npmjs.org/\n//registry.npmjs.org/:_authToken=npm_ABC123\nfund=false\n');
+    const r = n.resolveNpmToken({ env: {}, homedir: home });
+    assert.deepEqual(r, { token: 'npm_ABC123', source: 'user-npmrc' });
+  } finally { rmSync(home, { recursive: true, force: true }); }
+});
+
+test('resolveNpmToken: an env-fed ${…} value in the user file is the trap, not a credential', () => {
+  const home = mkdtempSync(join(tmpdir(), 'npmrc-home-'));
+  try {
+    writeFileSync(join(home, '.npmrc'), '//registry.npmjs.org/:_authToken=${NPM_TOKEN}\n');
+    const r = n.resolveNpmToken({ env: {}, homedir: home });
+    assert.deepEqual(r, { token: null, source: null });
+  } finally { rmSync(home, { recursive: true, force: true }); }
+});
+
+test('resolveNpmToken: a token for a DIFFERENT host is not borrowed', () => {
+  const home = mkdtempSync(join(tmpdir(), 'npmrc-home-'));
+  try {
+    writeFileSync(join(home, '.npmrc'), '//npm.pkg.github.com/:_authToken=ghp_other\n');
+    const r = n.resolveNpmToken({ env: {}, homedir: home });
+    assert.deepEqual(r, { token: null, source: null });
+  } finally { rmSync(home, { recursive: true, force: true }); }
+});
+
+test('resolveNpmToken: no user npmrc at all → null, never a throw', () => {
+  const home = mkdtempSync(join(tmpdir(), 'npmrc-home-'));
+  try {
+    const r = n.resolveNpmToken({ env: {}, homedir: home });
+    assert.deepEqual(r, { token: null, source: null });
+  } finally { rmSync(home, { recursive: true, force: true }); }
+});
+
 console.log('');
 console.log(`npmrc tests: ${passed} passed, ${failed} failed`);
 process.exit(failed ? 1 : 0);