@bongos/core 1.19.736 → 1.19.738

package/tests/go_live.mjs

@@ -442,26 +442,27 @@ 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 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/);
+test('a privileged npm command carries NO credential machinery at all', () => {
+  const cmd = G.asOwner({ runAs: 'lars', env: { PGDATABASE: 'cb' } }, 'npm install');
+  // HISTORY, so nobody reintroduces it (task 1003218, twice). `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 was never a fix. The third
+  // shape had the child DERIVE the token from a file so only a `sed` appeared in argv.
+  //
+  // All three are now moot rather than mitigated: @bongos/core is public (task 1003872), so
+  // the deploy path needs no npm credential and the hazard cannot recur (task 1003878). This
+  // asserts the ABSENCE, which is a stronger guarantee than any of the three mitigations.
+  assert.doesNotMatch(cmd, /NPM_TOKEN/, 'no token by value, by reference, or by derivation');
+  assert.doesNotMatch(cmd, /--preserve-env/, '--preserve-env would log the value in ENV=');
+  assert.doesNotMatch(cmd, /_authToken/, 'nothing reads a credential out of an .npmrc');
   // Non-secret config still travels plainly.
   assert.match(cmd, /PGDATABASE=cb/);
 });
 
-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('the retired auth preamble is really gone from the module surface', () => {
+  // It was exported and embedded into every privileged command. A re-export would mean the
+  // mitigation came back, which now means a credential came back with it.
+  assert.equal(G.NPM_AUTH_PREAMBLE, undefined, 'NPM_AUTH_PREAMBLE must not be exported');
 });
 
 test('a command that does not need npm is left alone', () => {
@@ -470,10 +471,10 @@ test('a command that does not need npm is left alone', () => {
   assert.ok(!cmd.includes('NPM_TOKEN'));
 });
 
-test('with no privilege drop the command still derives its own auth', () => {
-  const cmd = G.asOwner({ env: { A: 'b' } }, 'npm x', { needsNpm: true });
+test('with no privilege drop the command is still credential-free', () => {
+  const cmd = G.asOwner({ env: { A: 'b' } }, 'npm x');
   assert.ok(!cmd.startsWith('sudo'));
-  assert.match(cmd, /_authToken/);
+  assert.doesNotMatch(cmd, /NPM_TOKEN|_authToken/);
 });
 
 test('the report surfaces the failing tool’s own words', () => {

package/tests/init.mjs

@@ -768,10 +768,10 @@ async function runSeedTests() {
   });
 }
 
-// ---- greenfield registry-install path (ADR 0134, task 2090) ----------------
+// ---- greenfield registry-install path ---------------------------------------
 // main() with --registry-core --dry-run only LOGS (no fs, no network), so we capture
-// console output and assert the plan. The real write+install path is proven by the
-// CLI scratch run in the session log; the pure gates live in tests/npmrc.mjs.
+// console output and assert the plan. The package is public (task 1003872), so this path
+// writes no `.npmrc` and needs no token; tests/npmrc.mjs went with the module (task 1003878).
 async function runRegistryCoreTests() {
   const at = async (name, fn) => {
     try { await fn(); passed++; console.log(`  ok  ${name}`); }
@@ -799,14 +799,19 @@ async function runRegistryCoreTests() {
     return { code, out: lines.join('\n') };
   };
 
-  await at('main --registry-core --dry-run: plans the env-fed .npmrc; does NOT vendor a tarball', async () => {
+  await at('main --registry-core --dry-run: plans a plain lockfile generation, no .npmrc, no token', async () => {
     const { dir, p } = specFile();
     try {
       const { code, out } = await capture(['--from', p, '--dir', join(dir, 'out'), '--no-seed', '--registry-core', '--dry-run']);
       assert.equal(code, 0);
-      assert.match(out, /would write \.npmrc \(env-fed @bongos auth\)/);
+      assert.match(out, /would run `npm install` to generate package-lock\.json/);
       assert.ok(!/vendor/i.test(out), 'no vendored-tarball step on the registry path');
-      assert.equal(existsSync(join(dir, 'out', '.npmrc')), false, 'dry-run writes nothing');
+      // The load-bearing half (task 1003878): a public package resolves from the default
+      // registry, so planning an `.npmrc` or mentioning a token would mean the retired
+      // auth path came back.
+      assert.doesNotMatch(out, /\.npmrc/, 'must not plan an .npmrc');
+      assert.doesNotMatch(out, /NPM_TOKEN/, 'must not mention a token');
+      assert.equal(existsSync(join(dir, 'out', '.npmrc')), false, 'writes no .npmrc at all');
     } finally { rmSync(dir, { recursive: true, force: true }); }
   });
 

package/tests/provision.mjs

@@ -599,18 +599,41 @@ async function scaffoldWithEnv(env) {
   }
 }
 
-await ta('scaffoldStandaloneRepo: PROVISION_CORE_FROM_REGISTRY=1 + NPM_TOKEN → registry path (init --registry-core, no tarball build)', async () => {
+// Provisioning used to FORK on two env vars: PROVISION_CORE_FROM_REGISTRY chose the registry
+// path, and a missing NPM_TOKEN silently failed it soft back to the vendored tarball. Both are
+// gone (task 1003878) — the package is public, so nothing needs a token, and an env var that
+// silently changed which install path ran is the divergence behind task 1003520.
+//
+// These two assert the ABSENCE of that fork, which is why they set the retired vars explicitly:
+// a test that merely stopped mentioning them would pass whether or not the fork came back.
+await ta('scaffoldStandaloneRepo: the retired PROVISION_CORE_FROM_REGISTRY env no longer diverts to the registry', async () => {
   const joined = await scaffoldWithEnv({ PROVISION_CORE_FROM_REGISTRY: '1', NPM_TOKEN: 'npm_readonly' });
-  assert.match(joined, /init\.js --from .* --dir .* --no-seed --force --registry-core/, 'materializes via --registry-core');
-  assert.ok(!/package-core\.js/.test(joined), 'does NOT build a core tarball on the registry path');
-  assert.ok(!/--vendor-core/.test(joined), 'does NOT vendor a tarball on the registry path');
-});
-
-await ta('scaffoldStandaloneRepo: registry requested but NO NPM_TOKEN → FAILS SOFT to the vendored tarball', async () => {
-  const joined = await scaffoldWithEnv({ PROVISION_CORE_FROM_REGISTRY: '1' });
-  assert.match(joined, /node scripts\/gds\/package-core\.js/, 'builds the core tarball (vendored fallback)');
+  assert.match(joined, /node scripts\/gds\/package-core\.js/, 'still vendors — the env var is inert');
   assert.match(joined, /init\.js --from .* --dir .* --no-seed --force --vendor-core /, 'file:-pins the vendored tarball');
-  assert.ok(!/--registry-core/.test(joined), 'does NOT take the registry path without a token');
+  assert.ok(!/--registry-core/.test(joined), 'the retired env var must not resurrect the registry path');
+});
+
+await ta('scaffoldStandaloneRepo: a token in env changes NOTHING about the install path', async () => {
+  // BOTH runs set the retired request flag and vary ONLY the token — that is precisely the
+  // old divergence (flag + token → registry; flag, no token → vendored fail-soft). Comparing
+  // two runs that DON'T set the flag would pass whether or not the fork existed, which an
+  // adversarial re-add of the fork proved while this test was written that way.
+  const withToken = await scaffoldWithEnv({ PROVISION_CORE_FROM_REGISTRY: '1', NPM_TOKEN: 'npm_readonly' });
+  const without = await scaffoldWithEnv({ PROVISION_CORE_FROM_REGISTRY: '1' });
+  // THE LOAD-BEARING ASSERTION. The old fail-soft made a tokenless standup take a DIFFERENT
+  // install path than a tokenized one — two modes diverging on an env var (task 1003520).
+  // One public path means the presence of a credential cannot change the outcome at all.
+  // Normalize the per-run random temp names (scratch dir, spec file, pack dir) — they differ
+  // between any two runs and say nothing about which install path was taken.
+  const norm = (t) => t
+    .replace(/scaffold-[A-Za-z0-9]+/g, 'SCRATCH')
+    .replace(/bongos-init-[^\s.]+/g, 'SPEC')
+    .replace(/core-pack-[^\s/]+/g, 'PACK');
+  assert.equal(
+    norm(withToken),
+    norm(without),
+    'the command sequence must be identical with and without a token',
+  );
 });
 
 await ta('scaffoldStandaloneRepo: default (no registry env) stays on the vendored tarball path', async () => {

package/tests/start_env_guard.mjs

@@ -107,10 +107,15 @@ t('a hosted origin leads with the board being a website that needs no install',
   assert.ok(/healthz/.test(card), 'offers the health probe instead of a bring-up');
 });
 
-t('a hosted origin explains the private-package 404 rather than implying a lost version', () => {
+t('a hosted origin says the core installs with no token, and never re-offers the retired NPM_TOKEN advice', () => {
   const card = instanceNotRunningCard({ origin: 'https://example-instance.cloudbongos.com', depsMissing: true });
-  assert.ok(/private/i.test(card) && /NPM_TOKEN/.test(card), 'names the real cause of a tokenless install failure');
-  assert.ok(/not a missing version/.test(card), 'kills the "go find a version that still exists" wild goose chase');
+  assert.ok(/public/i.test(card), 'names the package as public — it is (task 1003872)');
+  assert.ok(/no token|needs no token/i.test(card), 'tells the reader nothing needs authenticating');
+  // The load-bearing half: this card spent months telling people to go find an NPM_TOKEN for
+  // a package that is now public. Advising that again would send a newcomer hunting a
+  // credential that does not exist and cannot be issued to them.
+  assert.doesNotMatch(card, /NPM_TOKEN/, 'must not resurrect the token advice');
+  assert.doesNotMatch(card, /\bprivate\b/i, 'must not call the package private');
 });
 
 t('isLocalOrigin: loopback is local, everything else is remote', () => {

package/tests/upgrade.mjs

@@ -9,12 +9,15 @@
 //   5. dry-run — plans without mutating package.json or spawning npm.
 //   6. full happy-path — pre-flight → pin → install → migrate → materialize → restart → verify,
 //      with every side effect injected (DB-free: the ledger is skipped when no DATABASE_URL).
+//  10. the pin push on a PRIVATE instance rides the owner's GitHub token through a chmod-600
+//      credential-store file, falls back to the remote only when none is stored, and a refused
+//      push is LOUD, naming the read-only deploy key and the fix (task 1003081, ADR 0176).
 //
 // Run:  node tests/upgrade.mjs
 
 import { strict as assert } from 'node:assert';
 import { createRequire } from 'node:module';
-import { mkdtempSync, mkdirSync, writeFileSync, readFileSync, existsSync } from 'node:fs';
+import { mkdtempSync, mkdirSync, writeFileSync, readFileSync, existsSync, statSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join, dirname } from 'node:path';
 
@@ -441,7 +444,7 @@ t('runUpgrade --registry + --from: refuses (mutually exclusive core sources)', a
   assert.match(res.error, /mutually exclusive/);
 });
 
-t('runUpgrade --registry (full): pins the exact version + writes the env-fed .npmrc, then install→migrate→verify', async () => {
+t('runUpgrade --registry (full): pins the exact version, writes NO .npmrc, then install→migrate→verify', async () => {
   const dir = scratchConsumer({ pinned: '1.16.0', installed: '1.16.0' });
   const calls = [];
   const res = await u.runUpgrade(
@@ -457,8 +460,11 @@ t('runUpgrade --registry (full): pins the exact version + writes the env-fed .np
   assert.equal(res.ok, true, 'registry upgrade succeeds');
   assert.equal(res.toVersion, '1.17.0');
   assert.equal(JSON.parse(readFileSync(join(dir, 'package.json'), 'utf8')).dependencies['@bongos/core'], '1.17.0', 'exact registry pin (no file:)');
-  const npmrc = readFileSync(join(dir, '.npmrc'), 'utf8');
-  assert.match(npmrc, /_authToken=\$\{NPM_TOKEN\}/, 'wrote the env-fed .npmrc');
+  // @bongos/core is public (task 1003872), so the registry path writes no `.npmrc` and
+  // resolves from the default registry. An `.npmrc` reappearing here would mean the retired
+  // auth plumbing came back — and it is the file whose `${NPM_TOKEN}` expansion used to
+  // SHADOW a working user-level credential (task 1002754), so its absence is load-bearing.
+  assert.equal(existsSync(join(dir, '.npmrc')), false, 'writes no .npmrc on the registry path');
   assert.ok(calls.some((c) => /^npm install/.test(c)), 'ran npm install (resolves from the registry)');
   assert.ok(!calls.some((c) => /vendor/.test(c)), 'did not vendor a tarball');
 });
@@ -1390,6 +1396,286 @@ t('pollServedVersion: gives up rather than spinning when the clock never advance
   assert.match(r.error, /no coreVersion/);
 });
 
+// ---- 10. the pin push rides the owner's GitHub token on a private instance (task 1003081, ADR 0176 follow-up) ----
+//
+// A PRIVATE standalone instance's origin authenticates with a deploy key GitHub registers
+// READ-ONLY, so `git push origin HEAD:main` is refused and the pin bump silently un-does
+// itself at the next pull-deploy. persistPin now prefers the owner's stored `repo` token
+// (the scaffold's + refreshStandaloneCorePin's credential-store shape), falls back to the
+// remote only when none is stored, and a refused push is LOUD. `run` is injected, so no
+// real repo, remote, or network — the assertions are on the argv persistPin CHOOSES and
+// on the credential file it writes beside it.
+
+const PIN_DIRTY = ' M package.json\n M package-lock.json\n';
+const hush = () => {};
+// A `run` fake for persistPin: `git -c <cfg> push …` is routed as the verb `push`, so a
+// handler sees the token-path push and the origin push alike. Unset config / no such
+// remote by default (exit 1), the way git answers a checkout that is not wired.
+function pinRun(handlers = {}) {
+  const calls = [];
+  const fn = (cmd, args, opts) => {
+    calls.push(`${cmd} ${(args || []).join(' ')}`.trim());
+    const verb = args[0] === '-c' ? args[2] : args[0];
+    const h = handlers[verb];
+    if (typeof h === 'function') return h(args, opts);
+    if (h) return h;
+    if (verb === 'status') return { status: 0, stdout: PIN_DIRTY };
+    if (verb === 'rev-parse') return { status: 0, stdout: 'main\n' };
+    if (verb === 'config' || verb === 'remote') return { status: 1, stdout: '' };
+    return { status: 0, stdout: '' };
+  };
+  fn.calls = calls;
+  return fn;
+}
+const pinBase = { instanceDir: '/srv/bongos/acme', fromVersion: '1.19.56', toVersion: '1.19.69', commitPin: true };
+const acme = { owner: 'acme', name: 'widgets' };
+const credFileOf = (args) => (String(args[1] || '').match(/^credential\.helper=store --file=(.+)$/) || [])[1] || null;
+
+t('persistPin: a stored owner token pushes over HTTPS through a chmod-600 credential-store file, and the token never rides argv', () => {
+  const token = 'gho_SECRET_OWNER_TOKEN';
+  let seen = null;
+  const run = pinRun({
+    push: (args, opts) => {
+      const credFile = credFileOf(args);
+      const there = !!credFile && existsSync(credFile);
+      seen = {
+        credFile, there,
+        mode: there ? statSync(credFile).mode & 0o777 : null,
+        body: there ? readFileSync(credFile, 'utf8') : null,
+        url: args[3], target: args[4],
+        noPrompt: opts && opts.env && opts.env.GIT_TERMINAL_PROMPT,
+      };
+      return { status: 0, stdout: '' };
+    },
+  });
+  const r = u.persistPin({ ...pinBase, pushAuth: { token, repo: acme } }, run, hush, hush);
+  assert.deepEqual(r, { applicable: true, committed: true, pushed: true, dirty: u.PIN_FILES, via: 'owner-token' });
+  assert.ok(seen, 'the push ran');
+  assert.ok(seen.credFile, `the push reads a credential-store file; argv was ${JSON.stringify(run.calls)}`);
+  assert.equal(seen.url, 'https://x-access-token@github.com/acme/widgets.git', 'HTTPS at the remote repo, the placeholder user in the URL');
+  assert.equal(seen.target, 'HEAD:main');
+  assert.equal(seen.there, true, 'the credential file exists while git runs');
+  if (process.platform !== 'win32') assert.equal(seen.mode, 0o600, 'chmod 600 — the secret is readable by this user only');
+  assert.equal(seen.body, `https://x-access-token:${token}@github.com\n`, 'the token lives in the file, credential-store shape');
+  assert.equal(seen.noPrompt, '0', 'a rejected credential fails instead of sitting at a password prompt');
+  assert.ok(!existsSync(seen.credFile), 'removed in finally');
+  assert.ok(run.calls.every((c) => !c.includes(token)), `the token never rides argv: ${JSON.stringify(run.calls)}`);
+  assert.ok(!run.calls.some((c) => /^git push /.test(c)), 'the SSH origin was not used');
+  assert.ok(run.calls.some((c) => c === `git add ${u.PIN_FILES.join(' ')}`) && run.calls.some((c) => c.startsWith('git commit -m pin @bongos/core 1.19.69')), 'stage + commit are unchanged');
+});
+
+t('persistPin: no stored token → the push falls back to the git remote, with no credential helper anywhere', () => {
+  const run = pinRun();
+  const r = u.persistPin({ ...pinBase }, run, hush, hush);
+  assert.deepEqual(r, { applicable: true, committed: true, pushed: true, dirty: u.PIN_FILES }, 'the origin-path result is byte-for-byte what every existing caller reads');
+  assert.ok(run.calls.some((c) => c === 'git push origin HEAD:main'), 'pushes via the remote');
+  assert.ok(!run.calls.some((c) => /credential\.helper|x-access-token/.test(c)), 'no credential helper, no token URL');
+  // `pushAuth: null` — what resolvePinPushAuth returns on every miss — is the same path.
+  const run2 = pinRun();
+  assert.equal(u.persistPin({ ...pinBase, pushAuth: null }, run2, hush, hush).pushed, true);
+  assert.ok(run2.calls.some((c) => c === 'git push origin HEAD:main'));
+});
+
+t('persistPin: a refused origin push on a WIRED private instance is loud — names the read-only key, the consequence, and the fix', () => {
+  const warnings = [];
+  const run = pinRun({
+    push: { status: 128, stdout: '', stderr: 'ERROR: The key you are authenticating with has been marked as read only.\nfatal: Could not read from remote repository.\n' },
+    config: { status: 0, stdout: 'ssh -F /dev/null -i /srv/bongos/acme/.git/cloudbongos-deploy-key -o IdentitiesOnly=yes -o StrictHostKeyChecking=accept-new\n' },
+    remote: { status: 0, stdout: 'git@github.com:acme/widgets.git\n' },
+  });
+  const r = u.persistPin({ ...pinBase }, run, hush, (m) => warnings.push(m));
+  assert.equal(r.committed, true);
+  assert.equal(r.pushed, false);
+  assert.equal(r.refused, 'read-only-deploy-key');
+  // The tokenless refusal is a plain sentence, not the bare status line.
+  assert.match(r.error, /read-only deploy key at \/srv\/bongos\/acme\/\.git\/cloudbongos-deploy-key/, 'names the key');
+  assert.match(r.error, /no owner GitHub token is stored/, 'and why nothing else was tried');
+  assert.notEqual(r.error, 'git push failed');
+  const text = warnings.join('\n');
+  assert.match(text, /PIN NOT PUSHED/, 'shouts');
+  assert.match(text, /\/srv\/bongos\/acme\/\.git\/cloudbongos-deploy-key/, 'names the key on stderr too');
+  assert.match(text, /READ-ONLY/);
+  assert.match(text, /reset --hard/, 'names the mechanism that reverts it');
+  assert.match(text, /npm ci/);
+  assert.match(text, /1\.19\.56/, 'and the version it would fall back to');
+  assert.match(text, /reconnect GitHub with repository access/, 'names the fix');
+  assert.match(text, /--commit-pin/);
+  assert.match(text, /--instance '\/srv\/bongos\/acme'/, 'and where to re-run it');
+  assert.match(text, /push 'https:\/\/github\.com\/acme\/widgets\.git' 'HEAD:main'/, 'plus a by-hand push at the real repo, paste-safe');
+  assert.match(text, /marked as read only/, "git's own reason rides along");
+});
+
+t('persistPin: a refused origin push on an UN-wired checkout keeps the plain failure (no false read-only diagnosis)', () => {
+  const warnings = [];
+  const run = pinRun({ push: { status: 1, stdout: '', stderr: 'fatal: unable to access: Could not resolve host\n' } });
+  const r = u.persistPin({ ...pinBase }, run, hush, (m) => warnings.push(m));
+  assert.equal(r.pushed, false);
+  assert.equal(r.error, 'git push failed');
+  assert.equal(r.refused, undefined);
+  assert.ok(!/READ-ONLY|deploy key/.test(warnings.join('\n')), 'no read-only story when no key is pinned');
+  assert.match(warnings.join('\n'), /still not durable/i);
+});
+
+t('persistPin: a refused push OVER the token is loud too, and the credential file is still removed', () => {
+  const token = 'gho_EXPIRED_TOKEN';
+  const warnings = [];
+  let credFile = null;
+  const run = pinRun({
+    push: (args) => {
+      credFile = credFileOf(args);
+      return { status: 128, stdout: '', stderr: 'remote: Write access to repository not granted.\nfatal: unable to access \'https://github.com/acme/widgets.git/\': The requested URL returned error: 403\n' };
+    },
+  });
+  const r = u.persistPin({ ...pinBase, pushAuth: { token, repo: acme } }, run, hush, (m) => warnings.push(m));
+  assert.equal(r.committed, true);
+  assert.equal(r.pushed, false);
+  assert.equal(r.refused, 'owner-token');
+  assert.match(r.error, /over the owner's GitHub token/);
+  assert.match(r.error, /expired, or missing the repo scope/);
+  assert.ok(credFile && !existsSync(credFile), 'the credential file is gone even on failure');
+  const text = warnings.join('\n');
+  assert.match(text, /PIN NOT PUSHED/);
+  assert.match(text, /expired/);
+  assert.match(text, /repo.*scope/);
+  assert.match(text, /reconnect GitHub with repository access/, 'names the fix');
+  assert.match(text, /Write access to repository not granted/, "GitHub's own reason rides along, not git's generic fatal line");
+  assert.match(text, /push 'https:\/\/github\.com\/acme\/widgets\.git' 'HEAD:main'/, 'and a by-hand push');
+  assert.ok(!text.includes(token), 'the token is never logged');
+  assert.ok(!run.calls.some((c) => /^git push /.test(c)), 'a token refusal does not retry the read-only origin');
+});
+
+t('pinnedDeployKey / remoteGithubRepo: read the ADR 0176 wiring off the checkout, and only GitHub remotes count', () => {
+  const wired = pinRun({ config: { status: 0, stdout: 'ssh -F /dev/null -i /srv/bongos/acme/.git/cloudbongos-deploy-key -o IdentitiesOnly=yes\n' } });
+  assert.equal(u.pinnedDeployKey('/srv/bongos/acme', wired), '/srv/bongos/acme/.git/cloudbongos-deploy-key');
+  assert.equal(u.pinnedDeployKey('/srv/bongos/acme', pinRun()), null, 'unset core.sshCommand → not wired');
+  assert.equal(u.pinnedDeployKey('/srv/bongos/acme', pinRun({ config: { status: 0, stdout: 'ssh -o BatchMode=yes\n' } })), null, 'a sshCommand without -i pins no key');
+
+  const at = (url) => pinRun({ remote: { status: 0, stdout: `${url}\n` } });
+  assert.deepEqual(u.remoteGithubRepo('/srv/bongos/acme', 'origin', at('git@github.com:acme/widgets.git')), acme, 'the ADR 0176 private wiring');
+  assert.deepEqual(u.remoteGithubRepo('/srv/bongos/acme', 'origin', at('https://github.com/acme/widgets')), acme);
+  assert.deepEqual(u.remoteGithubRepo('/srv/bongos/acme', 'origin', at('https://x-access-token@github.com/acme/widgets.git')), acme);
+  const P = require('../scripts/gds/provision.js');
+  assert.deepEqual(u.remoteGithubRepo('/srv/bongos/acme', 'origin', at(P.instanceRepoRemote(acme))), acme, 'the shared SSH alias the public scaffold wires is GitHub too');
+  assert.equal(u.remoteGithubRepo('/srv/bongos/acme', 'origin', at('https://gitlab.com/acme/widgets.git')), null, 'another host is never pointed at github.com');
+  assert.equal(u.remoteGithubRepo('/srv/bongos/acme', 'origin', at('git@bitbucket.org:acme/widgets.git')), null);
+  assert.equal(u.remoteGithubRepo('/srv/bongos/acme', 'origin', pinRun()), null, 'no such remote');
+  // --git-remote is honoured: the URL of THAT remote is read.
+  const deploy = pinRun({ remote: (args) => (args[2] === 'deploy' ? { status: 0, stdout: 'git@github.com:acme/widgets.git\n' } : { status: 1, stdout: '' }) });
+  assert.deepEqual(u.remoteGithubRepo('/srv/bongos/acme', 'deploy', deploy), acme);
+});
+
+t('resolvePinPushAuth: the owner token is spent only when one is stored AND the provisioning row names the remote repo', async () => {
+  const inst = { slug: 'acme', owner_builder_id: 7, target_ref: 'acme/widgets', hosting_shape: 'standalone' };
+  const at = (url) => pinRun({ remote: { status: 0, stdout: `${url}\n` } });
+  const dir = { instanceDir: '/srv/bongos/acme' };
+
+  // stored token + matching row → { token, repo }, the repo parsed from the REMOTE
+  const a = await u.resolvePinPushAuth(dir, { log: hush, instance: inst, getGithubToken: async (bid) => (bid === 7 ? { token: 'gho_T', scope: 'read:user,repo' } : null) }, at('git@github.com:acme/widgets.git'));
+  assert.deepEqual(a, { token: 'gho_T', repo: acme });
+  // case never decides it (GitHub owner/repo names are case-insensitive)
+  const b = await u.resolvePinPushAuth(dir, { log: hush, instance: { ...inst, target_ref: 'Acme/Widgets' }, getGithubToken: async () => ({ token: 'gho_T' }) }, at('git@github.com:acme/widgets.git'));
+  assert.equal(b && b.token, 'gho_T');
+  // no token stored → null: the origin path
+  assert.equal(await u.resolvePinPushAuth(dir, { log: hush, instance: inst, getGithubToken: async () => null }, at('git@github.com:acme/widgets.git')), null);
+  // a row for ANOTHER repo → null: never another instance's credential for this checkout
+  let asked = 0;
+  const other = await u.resolvePinPushAuth(dir, { log: hush, instance: { ...inst, target_ref: 'acme/other' }, getGithubToken: async () => { asked++; return { token: 'gho_T' }; } }, at('git@github.com:acme/widgets.git'));
+  assert.equal(other, null);
+  assert.equal(asked, 0, 'the token store is not even consulted for a mismatched row');
+  // a non-GitHub remote → null, before any row or token lookup
+  let rows = 0;
+  assert.equal(await u.resolvePinPushAuth(dir, { log: hush, getInstanceBySlug: async () => { rows++; return inst; }, getGithubToken: async () => ({ token: 'gho_T' }) }, at('https://gitlab.com/acme/widgets.git')), null);
+  assert.equal(rows, 0);
+  // no row at all (an instance's own DB, a laptop) → null, and a THROWING lookup is the same answer
+  assert.equal(await u.resolvePinPushAuth(dir, { log: hush, getInstanceBySlug: async () => null, getGithubToken: async () => ({ token: 'gho_T' }) }, at('git@github.com:acme/widgets.git')), null);
+  assert.equal(await u.resolvePinPushAuth(dir, { log: hush, getInstanceBySlug: async () => { throw new Error('relation "provisioning_instances" does not exist'); }, getGithubToken: async () => ({ token: 'gho_T' }) }, at('git@github.com:acme/widgets.git')), null);
+  // the by-slug lookup uses the checkout's basename — standaloneRoot is <base>/<slug>
+  const slugs = [];
+  const c = await u.resolvePinPushAuth(dir, { log: hush, getInstanceBySlug: async (s) => { slugs.push(s); return inst; }, getGithubToken: async () => ({ token: 'gho_T' }) }, at('git@github.com:acme/widgets.git'));
+  assert.deepEqual(slugs, ['acme']);
+  assert.equal(c && c.token, 'gho_T');
+  // a row without an owner (or a token lookup that throws) is the origin path, never a crash
+  assert.equal(await u.resolvePinPushAuth(dir, { log: hush, getInstanceBySlug: async () => ({ ...inst, owner_builder_id: null }), getGithubToken: async () => ({ token: 'gho_T' }) }, at('git@github.com:acme/widgets.git')), null);
+  assert.equal(await u.resolvePinPushAuth(dir, { log: hush, instance: inst, getGithubToken: async () => { throw new Error('secret-box off'); } }, at('git@github.com:acme/widgets.git')), null);
+});
+
+t('runUpgrade --commit-pin: on a wired private instance the pin lands via the owner token, end to end', async () => {
+  const dir = scratchConsumer({ pinned: '1.14.1', installed: '1.14.1' });
+  const src = mkdtempSync(join(tmpdir(), 'otb-upgrade-src-'));
+  writeFileSync(join(src, 'bongos-core-1.15.0.tgz'), 'TGZ');
+  const token = 'gho_END_TO_END_TOKEN';
+  const calls = [];
+  let pushArgv = null;
+  const run = (cmd, args, opts) => {
+    calls.push(`${cmd} ${(args || []).join(' ')}`.trim());
+    // pre-flight `git status --porcelain` is clean; persistPin's pathspec-limited look
+    // (`-- package.json package-lock.json`) sees the moved pin.
+    if (cmd === 'git' && args[0] === 'status') return { status: 0, stdout: args.includes('--') ? PIN_DIRTY : '' };
+    if (cmd === 'git' && args[0] === 'rev-parse') return { status: 0, stdout: 'main\n' };
+    if (cmd === 'git' && args[0] === 'remote') return { status: 0, stdout: 'git@github.com:acme/widgets.git\n' };
+    if (cmd === 'git' && args[0] === 'config') return { status: 0, stdout: 'ssh -F /dev/null -i /srv/bongos/acme/.git/cloudbongos-deploy-key -o IdentitiesOnly=yes\n' };
+    if (cmd === 'git' && args[0] === '-c') { pushArgv = args; return { status: 0, stdout: '' }; }
+    if (cmd === 'npm' && args[0] === 'install') {
+      writeFileSync(join(dir, 'node_modules', '@bongos', 'core', 'package.json'), JSON.stringify({ name: '@bongos/core', version: '1.15.0' }) + '\n');
+    }
+    return { status: 0 }; // no stdout: resolveInstanceDb reads "could not run" (not fatal), as the happy-path test's shim does
+  };
+  const res = await u.runUpgrade(
+    { to: '1.15.0', from: join(src, 'bongos-core-1.15.0.tgz'), instance: dir, service: 'acme.service', healthCheck: false, commitPin: true },
+    {
+      log: hush, err: hush, run,
+      materialize: () => ({ skills: 35, settings: true, hooks: 3 }),
+      regenerateApiArtifacts: () => ({ ok: true, ran: ['gen-api-docs.js', 'gen-api-client.js'] }),
+      databaseUrl: '', pgDatabase: '',
+      instance: { slug: 'acme', owner_builder_id: 7, target_ref: 'acme/widgets', hosting_shape: 'standalone' },
+      getGithubToken: async () => ({ token, scope: 'read:user,repo' }),
+    },
+  );
+  assert.equal(res.ok, true, `upgrade should succeed: ${res.error}`);
+  assert.equal(res.pin && res.pin.pushed, true, 'the pin was pushed');
+  assert.equal(res.pin.via, 'owner-token', 'over the owner token, not the read-only origin');
+  assert.ok(pushArgv, 'pushed via the credential-store helper');
+  assert.equal(pushArgv[3], 'https://x-access-token@github.com/acme/widgets.git');
+  assert.equal(pushArgv[4], 'HEAD:main');
+  assert.ok(!calls.some((c) => c.includes(token)), 'the token never rides argv');
+  assert.ok(!calls.some((c) => /^git push /.test(c)), 'the read-only origin was never asked');
+});
+
+t('runUpgrade: the token store is consulted only when a push is actually coming', async () => {
+  // --pin-no-push, --dry-run, and a clean pin all skip resolvePinPushAuth entirely:
+  // nothing reads a credential it will not spend.
+  const cases = [
+    { name: 'no --commit-pin', opts: {}, dirtyPin: true },
+    { name: '--pin-no-push', opts: { commitPin: true, pinNoPush: true }, dirtyPin: true },
+    { name: '--dry-run', opts: { commitPin: true, dryRun: true }, dirtyPin: true },
+    { name: 'pin already committed', opts: { commitPin: true }, dirtyPin: false },
+  ];
+  for (const c of cases) {
+    const dir = scratchConsumer({ pinned: '1.14.1', installed: '1.14.1' });
+    const src = mkdtempSync(join(tmpdir(), 'otb-upgrade-src-'));
+    writeFileSync(join(src, 'bongos-core-1.15.0.tgz'), 'TGZ');
+    let resolved = 0;
+    const run = (cmd, args) => {
+      if (cmd === 'git' && args[0] === 'status') return { status: 0, stdout: args.includes('--') && c.dirtyPin ? PIN_DIRTY : '' };
+      if (cmd === 'git' && args[0] === 'rev-parse') return { status: 0, stdout: 'main\n' };
+      if (cmd === 'npm' && args[0] === 'install') {
+        writeFileSync(join(dir, 'node_modules', '@bongos', 'core', 'package.json'), JSON.stringify({ name: '@bongos/core', version: '1.15.0' }) + '\n');
+      }
+      return { status: 0 };
+    };
+    await u.runUpgrade(
+      { to: '1.15.0', from: join(src, 'bongos-core-1.15.0.tgz'), instance: dir, service: 'acme.service', healthCheck: false, ...c.opts },
+      {
+        log: hush, err: hush, run,
+        materialize: () => ({}), regenerateApiArtifacts: () => ({ ok: true, ran: [] }),
+        databaseUrl: '', pgDatabase: '',
+        resolvePinPushAuth: async () => { resolved++; return null; },
+      },
+    );
+    assert.equal(resolved, 0, `${c.name}: must not consult the token store`);
+  }
+});
+
 await Promise.all(pending);
 console.log(`\nupgrade: ${passed} passed, ${failed} failed`);
 process.exit(failed ? 1 : 0);

package/scripts/gds/npmrc.js

@@ -1,124 +0,0 @@
-#!/usr/bin/env node
-'use strict';
-//
-// scripts/gds/npmrc.js — env-fed `.npmrc` for installing the PRIVATE @bongos/* core
-// from the npm registry (ADR 0134, task 2090). The single place that knows the
-// registry host + scope + the `.npmrc` shape + the opt-in/token gates, shared by:
-//   • init.js       — the greenfield `--registry-core` scaffold
-//   • provision.js  — the standalone scaffold's registry path (opt-in, fail-soft)
-//   • upgrade.js     — the `--registry <version>` update channel
-//
-// WHY private + env-fed. `@bongos/core` publishes as a SCOPED, PRIVATE package (ADR
-// 0134): a private scoped package can only be installed with auth. Consumers
-// authenticate with an `.npmrc` whose token EXPANDS FROM THE ENVIRONMENT at install
-// time (`_authToken=${NPM_TOKEN}`) — so the committed file carries NO secret, and a
-// tokenless install 404s cleanly (the expected pre-launch outcome).
-//
-// The vendored-tarball path (task 2053) stays the DEFAULT/fallback until this registry
-// path is proven end-to-end on a real greenfield standup (ADR 0134 §Consequences).
-
-const fs = require('node:fs');
-const path = require('node:path');
-
-const REGISTRY_HOST = 'registry.npmjs.org';
-const CORE_SCOPE = '@bongos'; // the paid, canonical npm org (ADR 0134 scope correction, task 2092)
-const TOKEN_ENV = 'NPM_TOKEN';
-const REQUEST_ENV = 'PROVISION_CORE_FROM_REGISTRY';
-
-// The `.npmrc` a scaffolded instance commits. The token is the LITERAL `${NPM_TOKEN}`
-// (npm expands env vars in `.npmrc` values at read time), so the file is safe to
-// commit — it holds no secret. Scoping @bongos to the registry keeps every unrelated
-// install on the default public registry.
-function npmrcContent({ scope = CORE_SCOPE, host = REGISTRY_HOST, tokenEnv = TOKEN_ENV } = {}) {
-  return [
-    `; Cloud Bongos — env-fed auth for the PRIVATE ${scope}/* packages (ADR 0134, task 2090).`,
-    `; The token EXPANDS FROM THE ENVIRONMENT at install time; nothing secret is committed here.`,
-    `; \`npm ci\` needs ${tokenEnv} set (a read-only npm access token from the paid \`bongos\` org);`,
-    `; without it the private package 404s — that is the expected tokenless outcome.`,
-    `${scope}:registry=https://${host}/`,
-    `//${host}/:_authToken=\${${tokenEnv}}`,
-    '',
-  ].join('\n');
-}
-
-// Is a registry token present in the environment? The fail-soft gate: provisioning
-// falls back to the vendored tarball when this is false, so a tokenless standup still
-// works (never a broken instance).
-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.
-function registryCoreRequested(env = process.env) {
-  return /^(1|true|yes|on)$/i.test(String(env[REQUEST_ENV] || '').trim());
-}
-
-// Write the env-fed `.npmrc` into an instance dir. Default overwrites (a greenfield
-// scaffold owns the file); pass overwrite:false to leave a pre-existing `.npmrc`
-// untouched (an upgrade must not clobber a consumer's other registries). Returns the
-// path (or null when skipped). Dry-run writes nothing.
-function writeNpmrc(dir, { fsImpl = fs, dryRun = false, overwrite = true, log = () => {} } = {}) {
-  const p = path.join(dir, '.npmrc');
-  if (!overwrite && fsImpl.existsSync(p)) {
-    log(`  • .npmrc already present — left untouched (add \`${CORE_SCOPE}:registry\` + \`_authToken=\${${TOKEN_ENV}}\` if the private core doesn't resolve).`);
-    return null;
-  }
-  if (dryRun) {
-    log(`  [dry-run] would write ${p} (env-fed ${CORE_SCOPE} auth; token via $${TOKEN_ENV}, never committed)`);
-    return p;
-  }
-  fsImpl.writeFileSync(p, npmrcContent());
-  log(`  ✓ wrote .npmrc (env-fed ${CORE_SCOPE} auth; token via $${TOKEN_ENV}, never committed)`);
-  return p;
-}
-
-module.exports = {
-  REGISTRY_HOST, CORE_SCOPE, TOKEN_ENV, REQUEST_ENV,
-  npmrcContent, hasNpmToken, resolveNpmToken, registryCoreRequested, writeNpmrc,
-};
-
-// Tiny CLI: `node scripts/gds/npmrc.js [--print | --write <dir>]` — print the `.npmrc`
-// body or materialize it into <dir>. Handy for a manual registry-standup rehearsal.
-if (require.main === module) {
-  const args = process.argv.slice(2);
-  const writeIdx = args.indexOf('--write');
-  if (writeIdx !== -1 && args[writeIdx + 1]) {
-    const p = writeNpmrc(path.resolve(args[writeIdx + 1]), { log: console.log });
-    process.stdout.write(`${p}\n`);
-  } else {
-    process.stdout.write(npmrcContent());
-  }
-}