@bongos/core 1.19.736 → 1.19.737

package/.bongos-core.json

@@ -2,22 +2,22 @@
   "artifact": "bongos-core",
   "manifest_schema": 1,
   "generator": "scripts/gds/package-core.js",
-  "core_version": "1.19.736",
-  "core_contract": "1.19.736",
-  "source_commit": "917ef53331537c93796fb9db9a8b77be72cffe22",
+  "core_version": "1.19.737",
+  "core_contract": "1.19.737",
+  "source_commit": "1ceb8f6a2ad0321079098910ad8a721dffa67454",
   "source_ref": "HEAD",
-  "built_at": "2026-09-13T17:30:35.415Z",
+  "built_at": "2026-09-14T01:10:42.991Z",
   "redaction": {
     "model": "docs-redacted+functional-verbatim",
     "docs_redacted": 479,
     "agent_docs_stubbed": 24,
-    "functional_verbatim": 2108,
+    "functional_verbatim": 2109,
     "rules": 3,
     "gate_literals": 3,
     "gate": "passed"
   },
-  "file_count": 2611,
-  "tree_sha256": "4cd2b02aa80c6f20919a54413b4983dd572af10e199bf5401e6e75ee8914b543",
+  "file_count": 2612,
+  "tree_sha256": "c34cdc2f87b36f12f71f276e47ce740238e94841fab60b4245613189e0c527d2",
   "files": [
     {
       "path": ".claude/skills/ask-for-help/SKILL.md",
@@ -2492,7 +2492,7 @@
     {
       "path": "docs/module-api-changelog.md",
       "mode": "0000644",
-      "sha256": "8dc183ec4dc010d5897f8cca67dd0f55bb6abe5620e358388e9ed07a2f6521a8"
+      "sha256": "d1b64255f150e8c8a1b88cffa7326633b7e5bc22e22744f7b1d9ee47410f9e13"
     },
     {
       "path": "docs/modules-contract.md",
@@ -7537,12 +7537,12 @@
     {
       "path": "package-lock.json",
       "mode": "0000644",
-      "sha256": "014dc18dcf764c17d7927fe5475436f4d6e2acf18e7baa6f16b7852306dc89e0"
+      "sha256": "fc4587a7fbaaa14aad1e0296015adb626e89da62f4a90a95647f1bbb55a61f1e"
     },
     {
       "path": "package.json",
       "mode": "0000644",
-      "sha256": "96f124d7dee1ff76d006c102798790ab7b59b27c0fbacdb36c545d658c185f39"
+      "sha256": "d7595c39c515821f76d0b5045c3a9cbb400f2c36a663046d19dfc7cab098cf69"
     },
     {
       "path": "public-docs/index.html",
@@ -8369,10 +8369,15 @@
       "mode": "0000644",
       "sha256": "502b1aeb571d463aea02ef4db3e848d23fdd8c865e7bfc37f66679c09cc203a9"
     },
+    {
+      "path": "scripts/gds/provision-repo-auth.js",
+      "mode": "0000644",
+      "sha256": "b08032667c9f06495c750e4dd8d41fdc2f5aa587093cf7b4de8e7a46390f0724"
+    },
     {
       "path": "scripts/gds/provision-repo.js",
       "mode": "0000644",
-      "sha256": "3612ebe8f54da7498a6c4998e0d1d1c4596a80d54f70b5543b4a46dfca2ffbcf"
+      "sha256": "77ca585d99f4058427f1abbe629d66ce5ec9f87b6c974aebc114d1c0e734d8e2"
     },
     {
       "path": "scripts/gds/provision-units.js",
@@ -8902,7 +8907,7 @@
     {
       "path": "scripts/gds/upgrade.js",
       "mode": "0000644",
-      "sha256": "4f30ee3036846f449f6fc8143da32b3767376352743d373c39ace2f50f66e913"
+      "sha256": "64b2571770a5be9dc046f6c64adf45a09642c6961a6036c9405e1c933be6c3b7"
     },
     {
       "path": "scripts/gds/validate-design.js",
@@ -9342,7 +9347,7 @@
     {
       "path": "src/module-api.js",
       "mode": "0000644",
-      "sha256": "ad6748bac62f397b729ead21e7f591bc8e03fe771fff22855eb3813b066663da"
+      "sha256": "9ad95d6241cc8f3dfda5d02445246c1f7fd62b75b5014a15a9254c15a620aef7"
     },
     {
       "path": "src/module-loader/catalog.js",
@@ -10432,7 +10437,7 @@
     {
       "path": "tests/executed_closure.mjs",
       "mode": "0000644",
-      "sha256": "8c0ed9407dd3f19dab03f45fd2778fae0d2a5595bcd0daefc0e3e5a63137aa04"
+      "sha256": "1e1a899e8838c7c84bdad9ea9d8533aca9173ed1e72f15e13c3616493e11900f"
     },
     {
       "path": "tests/explore_visible_states.mjs",
@@ -12917,7 +12922,7 @@
     {
       "path": "tests/upgrade.mjs",
       "mode": "0000644",
-      "sha256": "492b9dc7efdd6f63b81f1662d5fdc9a7541b7f8ccc6c0ec77a456ad3f574ee74"
+      "sha256": "010c9ac8b05e25c10b9d43c7efd02454facf0d5663df11df555ea913697e23e8"
     },
     {
       "path": "tests/upgrade_persist_pin.mjs",

package/docs/module-api-changelog.md

@@ -1946,5 +1946,7 @@ is load-bearing: the script throws rather than guess if it is missing, and
         landed since 1.19.734 with no explicit bump. run 34768136326. (task 1002620)
   1.19.736 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
         landed since 1.19.735 with no explicit bump. run 34771773838. (task 1002620)
+  1.19.737 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+        landed since 1.19.736 with no explicit bump. run 34795026282. (task 1002620)
 ---------------------------------------------------------------------------
 ```

package/package-lock.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bongos/core",
-  "version": "1.19.736",
+  "version": "1.19.737",
   "description": "Cloud Bongos — the AI-first build platform core (GDS + platform surfaces + module system), installed as a versioned dependency (ADR 0108).",
   "license": "AGPL-3.0-or-later",
   "main": "src/platform-server.js",

package/scripts/gds/provision-repo-auth.js

@@ -0,0 +1,106 @@
+// scripts/gds/provision-repo-auth.js — the repo-identity + owner-credential leaf: parse a
+// `target_ref` into { owner, name }, build an instance's SSH deploy remote, find the
+// provisioning row that owns a checkout, and read that owner's stored GitHub token
+// (task 1003081).
+//
+// WHY THIS FILE EXISTS AT ALL. scripts/gds/upgrade.js is inside the merge resolver's
+// EXECUTED CLOSURE (modules/lifecycle/executed-closure.js; 2026-08-29 security audit ref
+// B1) — the set of files the server may run out of a CLONED BUILDER BRANCH. That closure
+// is a STATIC walk of string-literal requires, and it does not care whether a require is
+// lazy or inside a function: upgrade.js reaching these helpers through `./provision`
+// dragged provision.js plus provision-config/-repo/-units/-net.js into the closure with
+// it — five more files a branch could edit into the live server's process, three of them
+// carrying computed requires (provision-config 7, provision-repo 1, provision-units 1)
+// that tests/executed_closure.mjs has no account of. Carving the helpers into this LEAF
+// instead grows the closure by exactly ONE small file, whose computed-require count is
+// pinned in that test.
+//
+// THE RULE THAT KEEPS IT THAT WAY. Top level requires node builtins ONLY. Every
+// non-builtin require is lazy AND inside a function body, so nothing on the generator
+// path ever resolves it. Never require provision-config.js (or any other provision file)
+// from here — REPO_ROOT is recomputed below precisely so we don't have to.
+//
+// provision-repo.js requires this module and re-exports parseTargetRef,
+// instanceRepoRemote and resolveOwnerGithubToken unchanged, so provision.js,
+// provision-units.js, modules/provisioning/credential-preflight.js and their tests see
+// exactly the surface they saw before.
+
+'use strict';
+
+const path = require('node:path');
+
+// The same value provision-config.js exports as REPO_ROOT, recomputed here rather than
+// imported: that module carries seven computed requires, and importing it would put all
+// of them inside the executed closure (see the header).
+const REPO_ROOT = path.resolve(__dirname, '..', '..');
+
+// Parse an 'owner/repo' (or a github SSH/HTTPS URL) target_ref → { owner, name }.
+// Null when unparseable, so the scaffold can fail with actionable guidance.
+function parseTargetRef(ref) {
+  const m = String(ref || '').trim()
+    .replace(/^git@[^:]+:/, '')
+    .replace(/^https?:\/\/[^/]+\//, '')
+    .match(/^([A-Za-z0-9][A-Za-z0-9_.-]*)\/([A-Za-z0-9][A-Za-z0-9_.-]*?)(?:\.git)?$/);
+  return m ? { owner: m[1], name: m[2] } : null;
+}
+
+// The git remote for an instance's OWN repo. Reuses the SAME SSH deploy alias the
+// control-plane checkout uses (git@<alias>:<owner>/<repo>.git) — NO secret in the
+// command (SSH-key auth, nothing to leak into journald), consistent with how the
+// platform repo is wired. Standing up a new instance repo therefore needs only that
+// the control plane's deploy key has WRITE access to that repo (ADR 0125). Alias is
+// overridable via PROVISION_GIT_SSH_ALIAS.
+function instanceRepoRemote(repo, { sshAlias = process.env.PROVISION_GIT_SSH_ALIAS || 'github-deploy' } = {}) {
+  return `git@${sshAlias}:${repo.owner}/${repo.name}.git`;
+}
+
+// The instance owner's stored `repo`-scoped OAuth token (ADR 0155), or null (none
+// stored, org-owned repo, secret-box off). Shared by the scaffold push, the
+// private-repo deploy-key wiring, the teardown revoke, and upgrade.js's pin push.
+// `deps.getGithubToken` is injectable for tests; production resolves it lazily against
+// the core db slice with the runner's pool.
+async function resolveOwnerGithubToken(inst, deps, { tag = '[repo-auth]' } = {}) {
+  if (!inst.owner_builder_id) return null;
+  try {
+    const fetchTok = deps.getGithubToken
+      || ((bid) => require(path.join(REPO_ROOT, 'src/bongos/db')).getGithubToken({ builderId: bid, p: deps.db })); // eslint-disable-line global-require
+    const r = await fetchTok(inst.owner_builder_id);
+    return r && r.token ? r.token : null;
+  } catch (e) {
+    (deps.log || (() => {}))(`  ${tag} owner OAuth token lookup failed (${e && e.message})`);
+    return null;
+  }
+}
+
+// The provisioning row that owns a checkout — where `owner_builder_id` (whose token) and
+// `target_ref` (which repo) come from. A control-plane caller hands it over as
+// `deps.instance`; a CLI run on the control plane (`--instance /srv/bongos/<slug>`) finds
+// it by the checkout's basename, which standaloneRoot makes the slug. An instance's own
+// database has no provisioning table and answers null — that is the origin path, not an
+// error, so every failure here is swallowed. The default lookup requires the core pool
+// in-process (a CLI run exits right after; a programmatic caller passes `deps.db` or
+// `deps.getInstanceBySlug`).
+//
+// It lives HERE rather than in its only caller, upgrade.js: both of its default requires
+// are computed, and upgrade.js is in the executed closure with a pinned count of its own
+// (see the header). Keeping them on this side leaves upgrade.js string-literal-only.
+async function lookupInstanceRow(instanceDir, deps = {}) {
+  if (deps.instance) return deps.instance;
+  const slug = path.basename(instanceDir);
+  try {
+    const bySlug = deps.getInstanceBySlug || (async (s) => {
+      const provisioning = require(path.join(REPO_ROOT, 'modules/provisioning/provisioning')); // eslint-disable-line global-require
+      const db = deps.db || require(path.join(REPO_ROOT, 'src/bongos/pool')).pool; // eslint-disable-line global-require
+      return provisioning.getInstanceBySlug(db, s);
+    });
+    const row = await bySlug(slug);
+    return row && row.owner_builder_id && row.target_ref ? row : null;
+  } catch { return null; }
+}
+
+module.exports = {
+  instanceRepoRemote,
+  lookupInstanceRow,
+  parseTargetRef,
+  resolveOwnerGithubToken,
+};

package/scripts/gds/provision-repo.js

@@ -15,6 +15,10 @@ const fs = require('node:fs');
 const os = require('node:os');
 const path = require('node:path');
 const { CONFIG, REPO_ROOT, coreVersionSafe, hasNpmToken, provisionerBotEmail, registryCoreRequested } = require('./provision-config.js');
+// The repo-identity + owner-credential leaf (task 1003081). Carved OUT of this file so
+// upgrade.js can reach these three without pulling provision*.js into the merge
+// resolver's executed closure; re-exported below so every existing caller is unchanged.
+const { instanceRepoRemote, parseTargetRef, resolveOwnerGithubToken } = require('./provision-repo-auth.js');
 
 function dbName(inst) { return inst.db_name || inst.slug; }
 
@@ -288,25 +292,10 @@ function dbRoleGrantsCmd(inst, { privileged = false } = {}) {
 // THROW if the instance repo wasn't already cloned. These generate + run the scaffold
 // that clones an EMPTY target_ref and turns it into an installable, bootable instance.
 
-// Parse an 'owner/repo' (or a github SSH/HTTPS URL) target_ref → { owner, name }.
-// Null when unparseable, so the scaffold can fail with actionable guidance.
-function parseTargetRef(ref) {
-  const m = String(ref || '').trim()
-    .replace(/^git@[^:]+:/, '')
-    .replace(/^https?:\/\/[^/]+\//, '')
-    .match(/^([A-Za-z0-9][A-Za-z0-9_.-]*)\/([A-Za-z0-9][A-Za-z0-9_.-]*?)(?:\.git)?$/);
-  return m ? { owner: m[1], name: m[2] } : null;
-}
-
-// The git remote for an instance's OWN repo. Reuses the SAME SSH deploy alias the
-// control-plane checkout uses (git@<alias>:<owner>/<repo>.git) — NO secret in the
-// command (SSH-key auth, nothing to leak into journald), consistent with how the
-// platform repo is wired. Standing up a new instance repo therefore needs only that
-// the control plane's deploy key has WRITE access to that repo (ADR 0125). Alias is
-// overridable via PROVISION_GIT_SSH_ALIAS.
-function instanceRepoRemote(repo, { sshAlias = process.env.PROVISION_GIT_SSH_ALIAS || 'github-deploy' } = {}) {
-  return `git@${sshAlias}:${repo.owner}/${repo.name}.git`;
-}
+// parseTargetRef + instanceRepoRemote (and resolveOwnerGithubToken, below the scaffold)
+// now live in the ./provision-repo-auth.js leaf and are re-exported unchanged from here —
+// upgrade.js needs them and is inside the merge resolver's executed closure, which a require of
+// this file would have widened by five (task 1003081; see that module's header).
 
 // A minimal, VALID `bongos init` spec (init.validateSpec greenfield) from the
 // provisioning row + the owner's github login. The scaffold produces a bootable,
@@ -711,24 +700,6 @@ async function scaffoldStandaloneRepo(inst, deps) {
 
 // ── private-repo deploy key (ADR 0176, task 1002735; walk finding N4) ────────────
 
-// The instance owner's stored `repo`-scoped OAuth token (ADR 0155), or null (none
-// stored, org-owned repo, secret-box off). Shared by the scaffold push, the
-// private-repo deploy-key wiring, and the teardown revoke. `deps.getGithubToken` is
-// injectable for tests; production resolves it lazily against the core db slice
-// with the runner's pool.
-async function resolveOwnerGithubToken(inst, deps, { tag = '[repo-auth]' } = {}) {
-  if (!inst.owner_builder_id) return null;
-  try {
-    const fetchTok = deps.getGithubToken
-      || ((bid) => require(path.join(REPO_ROOT, 'src/bongos/db')).getGithubToken({ builderId: bid, p: deps.db }));
-    const r = await fetchTok(inst.owner_builder_id);
-    return r && r.token ? r.token : null;
-  } catch (e) {
-    (deps.log || (() => {}))(`  ${tag} owner OAuth token lookup failed (${e && e.message})`);
-    return null;
-  }
-}
-
 function deployKeyTitle(inst) { return `cloudbongos-deploy-${inst.slug}`; }
 // Beside the checkout's own metadata: untracked by definition, survives the deploy's
 // `git reset --hard`, and dies with the checkout rather than accreting in ~/.ssh.

package/scripts/gds/upgrade.js

@@ -27,7 +27,9 @@
 // against `--instance <consumer>` — see docs/recipes for the bootstrap note.
 
 const fs = require('node:fs');
+const os = require('node:os');
 const path = require('node:path');
+const crypto = require('node:crypto');
 const { spawnSync } = require('node:child_process');
 const { arg, hasFlag } = require('./cli-lib');
 const { writeNpmrc, hasNpmToken, resolveNpmToken } = require('./npmrc'); // ADR 0134 (task 2090): the --registry channel's env-fed .npmrc; resolveNpmToken task 1002754
@@ -170,18 +172,133 @@ function dirtyPinFiles(instanceDir, run = spawnSync) {
   return (r.stdout || '').split('\n').map((l) => l.slice(3).trim()).filter(Boolean);
 }
 
+// ---- which credential the pin push rides (task 1003081, ADR 0176 follow-up) ----
+//
+// THE BUG THIS EXISTS FOR. A PRIVATE standalone instance's `origin` authenticates with
+// a per-repo deploy key that GitHub registers READ-ONLY (ADR 0176): it can pull, never
+// push. The push leg below went `git push origin HEAD:main` regardless, so on such an
+// instance GitHub refused the pin push, the bump was not durable, and the next
+// pull-deploy `git reset --hard origin/main` + `npm ci` reinstalled the OLD core
+// against an already-migrated DB — the exact silent rollback task 1002712 closed for
+// every other path, back through a warning line nobody read. The scaffold push and the
+// re-provision pin refresh already prefer the owner's stored `repo`-scoped OAuth token
+// over the SSH origin (provision.js resolveOwnerGithubToken + buildCorePinRefreshCommit);
+// the pin push now has the same preference — the token when one is stored, the git
+// remote otherwise — and a refused push is LOUD, naming the read-only key and the fix.
+
+// The GitHub owner/name behind `remote`, or null when the remote is not a GitHub
+// repository (there is nothing to push a GitHub token at) or cannot be read. Accepts
+// the plain github.com forms and the shared SSH alias instanceRepoRemote wires
+// (`git@github-deploy:owner/repo.git`) — never another host, so a stored token is
+// never pointed at github.com/<owner>/<repo> for a repo that lives elsewhere.
+function remoteGithubRepo(instanceDir, remote = 'origin', run = spawnSync) {
+  const r = run('git', ['remote', 'get-url', remote], { cwd: instanceDir, encoding: 'utf8' });
+  if (!r || r.error || r.status !== 0) return null;
+  const url = String(r.stdout || '').trim();
+  let auth;
+  try { auth = require('./provision-repo-auth'); } catch { return null; } // a package without the provisioner has no token path
+  const repo = auth.parseTargetRef(url);
+  if (!repo) return null;
+  const host = (url.match(/^(?:[a-z+]+:\/\/)?(?:[^@/]+@)?([^/:]+)[/:]/i) || [])[1] || '';
+  if (host.toLowerCase() !== 'github.com' && url !== auth.instanceRepoRemote(repo)) return null;
+  return repo;
+}
+
+// The deploy key `remote` authenticates with when the checkout is wired the ADR 0176
+// way (`core.sshCommand … -i <key>` in the repo's own config); null when it is not.
+// What a refused origin push is diagnosed against — GitHub's SSH refusal is a terse
+// one-liner that names no key.
+function pinnedDeployKey(instanceDir, run = spawnSync) {
+  const r = run('git', ['config', '--get', 'core.sshCommand'], { cwd: instanceDir, encoding: 'utf8' });
+  if (!r || r.error || r.status !== 0) return null;
+  const m = String(r.stdout || '').match(/(?:^|\s)-i\s+(\S+)/);
+  return m ? m[1] : null;
+}
+
+// Resolve { token, repo } for the pin push, or null → push via the git remote.
+//   repo  — the remote's GitHub owner/name (remoteGithubRepo);
+//   row   — provision-repo-auth lookupInstanceRow, used ONLY when its target_ref IS that
+//           repo, so another instance's credential is never spent on this checkout;
+//   token — provision-repo-auth resolveOwnerGithubToken (deps.getGithubToken / deps.db
+//           are its test seams), the same resolver the scaffold push uses.
+// Every miss is the origin path, not an error, and the token is never logged. The row
+// lookup and the token read BOTH live in the leaf rather than here because their default
+// requires are computed, and this file is inside the merge resolver's executed closure
+// with a pinned computed-require count of its own (task 1003081).
+async function resolvePinPushAuth({ instanceDir, remote = 'origin' }, deps = {}, run = spawnSync) {
+  const log = deps.log || console.log;
+  const repo = remoteGithubRepo(instanceDir, remote, run);
+  if (!repo) return null;
+  const auth = require('./provision-repo-auth');
+  const inst = await auth.lookupInstanceRow(instanceDir, deps);
+  if (!inst) return null;
+  const rowRepo = auth.parseTargetRef(inst.target_ref);
+  const same = (a, b) => a && b && a.owner.toLowerCase() === b.owner.toLowerCase() && a.name.toLowerCase() === b.name.toLowerCase();
+  if (!same(rowRepo, repo)) {
+    log(`  • pin push: the provisioning row for ${path.basename(instanceDir)} names ${inst.target_ref}, not ${remote}'s ${repo.owner}/${repo.name} — its owner's token is not for this checkout; pushing via ${remote}`);
+    return null;
+  }
+  const token = await auth.resolveOwnerGithubToken(inst, { ...deps, log }, { tag: '[pin-push]' });
+  if (!token) {
+    log(`  • pin push: no owner GitHub token stored for ${repo.owner}/${repo.name} — pushing via ${remote}`);
+    return null;
+  }
+  return { token, repo };
+}
+
+// The pin push over the owner's token: a chmod-600 credential-store file in the temp
+// dir carries the secret, git reads it through `credential.helper=store`, and the file
+// is removed in `finally` whatever the push did — the token is never in argv (ps,
+// journald) and never in a log line. provision.js buildCorePinRefreshCommit's shape,
+// as argv instead of a shell string.
+function pushPinViaToken({ instanceDir, token, repo, target }, run = spawnSync) {
+  const credFile = path.join(os.tmpdir(), `bongos-gitcred-pin-${process.pid}-${crypto.randomBytes(6).toString('hex')}`);
+  try {
+    fs.writeFileSync(credFile, `https://x-access-token:${token}@github.com\n`, { mode: 0o600 });
+    return run('git', ['-c', `credential.helper=store --file=${credFile}`, 'push', `https://x-access-token@github.com/${repo.owner}/${repo.name}.git`, target], {
+      cwd: instanceDir, encoding: 'utf8',
+      env: { ...process.env, GIT_TERMINAL_PROMPT: '0' }, // a rejected credential must fail, not sit at a password prompt
+    });
+  } finally {
+    fs.rmSync(credFile, { force: true });
+  }
+}
+
+// What git said on stderr, for a refusal line — GitHub's own reason ("ERROR: The key you
+// are authenticating with has been marked as read only", "remote: Write access to
+// repository not granted") is the fact an operator wants beside the diagnosis, and it
+// is never the LAST line: git closes with its generic `fatal:`. Prefer the server's
+// line, fall back to the last one.
+function gitSaid(r) {
+  const lines = String((r && r.stderr) || '').split('\n').map((l) => l.trim()).filter(Boolean);
+  const server = lines.filter((l) => /^(ERROR:|remote:)/i.test(l));
+  const said = server.length ? server[server.length - 1] : lines[lines.length - 1];
+  return said ? ` (git: ${said})` : '';
+}
+
 // `push: false` is CO-TENANT MODE (task 1003521). The reasoning above assumes the repo
 // of record is OURS; on a provisioned instance it is the customer's own GitHub repo, so
 // pushing there is both wrong and uncredentialed. Such an instance also has no
 // pull-deploy timer, so nothing will `reset --hard` the pin away — the commit alone
 // makes it durable, and leaves the tree clean for the customer's own pulls.
-function persistPin({ instanceDir, fromVersion, toVersion, commitPin, push = true, remote = 'origin', dryRun = false },
+//
+// `pushAuth` ({ token, repo }, from resolvePinPushAuth) makes the push ride the owner's
+// GitHub token over HTTPS (task 1003081); null pushes via `remote`. The result carries
+// `via: 'owner-token'` on the token path and `refused` ('read-only-deploy-key' |
+// 'owner-token') with a plain-sentence `error` when GitHub turned the push away.
+function persistPin({ instanceDir, fromVersion, toVersion, commitPin, push = true, remote = 'origin', dryRun = false, pushAuth = null },
   run = spawnSync, log = console.log, err = console.error) {
   const dirty = dirtyPinFiles(instanceDir, run);
   if (dirty === null) return { applicable: false, reason: 'not a git repo' };
   if (!dirty.length) return { applicable: false, reason: 'pin files already match the repo' };
 
   const branch = gitCurrentBranch(instanceDir, run);
+  const target = `HEAD:${branch || 'main'}`;
+  // Single-quote the interpolated values. Nothing here executes these strings — they
+  // are printed for a human to paste — but an unquoted branch or remote carrying shell
+  // metacharacters would misbehave once pasted, so emit them paste-safe.
+  const q = (s) => `'${String(s).replace(/'/g, `'\\''`)}'`;
+  const at = `git -C ${q(instanceDir)}`;
 
   if (!commitPin) {
     if (!push) {
@@ -198,12 +315,7 @@ function persistPin({ instanceDir, fromVersion, toVersion, commitPin, push = tru
     err('    On a pull-deploy instance the next push to the repo of record makes deploy.sh');
     err(`    'git reset --hard ${remote}/${branch || 'main'}', which REVERTS this pin and lets npm ci`);
     err(`    reinstall ${fromVersion || 'the previous core'}. Re-run with --commit-pin, or commit + push:`);
-    // Single-quote the interpolated values. Nothing here executes this string — it is
-    // printed for a human to paste — but an unquoted branch or remote carrying shell
-    // metacharacters would misbehave once pasted, so emit it paste-safe.
-    const q = (s) => `'${String(s).replace(/'/g, `'\\''`)}'`;
-    const at = `git -C ${q(instanceDir)}`;
-    err(`      ${at} add ${PIN_FILES.map(q).join(' ')} && ${at} commit -m ${q(`pin @bongos/core ${toVersion}`)} && ${at} push ${q(remote)} ${q(`HEAD:${branch || 'main'}`)}`);
+    err(`      ${at} add ${PIN_FILES.map(q).join(' ')} && ${at} commit -m ${q(`pin @bongos/core ${toVersion}`)} && ${at} push ${q(remote)} ${q(target)}`);
     return { applicable: true, committed: false, pushed: false, dirty, warned: true };
   }
 
@@ -232,11 +344,62 @@ function persistPin({ instanceDir, fromVersion, toVersion, commitPin, push = tru
     return { applicable: true, committed: true, pushed: false, dirty, pushSkipped: true };
   }
 
-  const pushed = run('git', ['push', remote, `HEAD:${branch || 'main'}`], { cwd: instanceDir, encoding: 'utf8' });
+  // Committed but not pushed is still doomed: deploy.sh resets to the REMOTE. So every
+  // refusal below is LOUD (task 1003081) — the pull-deploy consequence, the diagnosis,
+  // and a by-hand push that can actually write.
+  const revert = () => err(`    The next pull-deploy 'git reset --hard ${remote}/${branch || 'main'}' + npm ci then reinstalls ${fromVersion || 'the previous core'}.`);
+
+  if (pushAuth && pushAuth.token && pushAuth.repo) {
+    const { repo } = pushAuth;
+    let pushed = null;
+    try {
+      pushed = pushPinViaToken({ instanceDir, token: pushAuth.token, repo, target }, run);
+    } catch (e) {
+      // The credential file could not even be written (an unwritable temp dir): say so
+      // and fall through to the remote — a public origin may still take it.
+      err(`  ! could not stage the owner's GitHub credential (${e && e.message}) — pushing via ${remote} instead`);
+    }
+    if (pushed && !pushed.error && pushed.status === 0) {
+      log(`  ✓ pushed the pin to ${repo.owner}/${repo.name}@${branch || 'main'} via the owner's GitHub token — a pull-deploy reset can no longer revert it`);
+      return { applicable: true, committed: true, pushed: true, dirty, via: 'owner-token' };
+    }
+    if (pushed) {
+      err(`  ! PIN NOT PUSHED — GitHub refused the push over the owner's GitHub token, so this bump is NOT durable.`);
+      err(`    The stored token could not write ${repo.owner}/${repo.name}: it may have expired (they live an hour), or`);
+      err(`    lack the \`repo\` scope (\`public_repo\` cannot write a private repository — ADR 0155).${gitSaid(pushed)}`);
+      revert();
+      err('    Fix: have the instance owner reconnect GitHub with repository access, then re-run `bongos upgrade --commit-pin`;');
+      err('    or push the commit yourself with a credential that can write:');
+      err(`      ${at} push ${q(`https://github.com/${repo.owner}/${repo.name}.git`)} ${q(target)}`);
+      return {
+        applicable: true, committed: true, pushed: false, dirty, refused: 'owner-token',
+        error: `GitHub refused the pin push over the owner's GitHub token (expired, or missing the repo scope) — the pin is committed locally but not on ${repo.owner}/${repo.name}`,
+      };
+    }
+  }
+
+  const pushed = run('git', ['push', remote, target], { cwd: instanceDir, encoding: 'utf8' });
   if (!pushed || pushed.error || pushed.status !== 0) {
-    // Committed but not pushed is still doomed: deploy.sh resets to the REMOTE.
+    const key = pinnedDeployKey(instanceDir, run);
+    if (key) {
+      // A wired private instance (ADR 0176): the key can pull, never push, and no owner
+      // token was stored to push with instead — the bug this leg exists for.
+      const repo = remoteGithubRepo(instanceDir, remote, run);
+      err(`  ! PIN NOT PUSHED — GitHub refused the push to ${remote}, so this bump is NOT durable.`);
+      err(`    ${remote} authenticates with the deploy key at ${key}, which is registered READ-ONLY on the`);
+      err(`    repository (ADR 0176): it can pull, never push. No owner GitHub token is stored to push with instead.${gitSaid(pushed)}`);
+      revert();
+      err('    Fix: have the instance owner reconnect GitHub with repository access (that stores a short-lived repo token),');
+      err(`    then re-run \`bongos upgrade --commit-pin\` where that token is readable — the control plane, with --instance ${q(instanceDir)};`);
+      err('    or push the commit yourself with a credential that can write:');
+      err(`      ${at} push ${q(`https://github.com/${repo ? `${repo.owner}/${repo.name}` : '<owner>/<repo>'}.git`)} ${q(target)}`);
+      return {
+        applicable: true, committed: true, pushed: false, dirty, refused: 'read-only-deploy-key',
+        error: `GitHub refused the pin push: ${remote} authenticates with the read-only deploy key at ${key}, and no owner GitHub token is stored to push with — the pin is committed locally but not on the remote`,
+      };
+    }
     err(`  ! commit landed locally but the push to ${remote} FAILED — this bump is still not durable.`);
-    err(`    Push it: git -C ${instanceDir} push ${remote} HEAD:${branch || 'main'}`);
+    err(`    Push it: git -C ${instanceDir} push ${remote} ${target}`);
     return { applicable: true, committed: true, pushed: false, dirty, error: 'git push failed' };
   }
   log(`  ✓ pushed the pin to ${remote}/${branch || 'main'} — a pull-deploy reset can no longer revert it`);
@@ -1144,14 +1307,23 @@ async function runUpgrade(opts, deps = {}) {
 
   // Make the pin durable (task 1002712). Runs LAST — only a verified-healthy
   // upgrade is worth persisting, and a rolled-back one returned long before here.
+  //
+  // Which credential the push rides is resolved HERE (async — it may read the token
+  // store) and handed to persistPin, which stays synchronous — and only when a push is
+  // actually coming: --commit-pin without --pin-no-push, not a dry run, and the pin
+  // files really are dirty. Nothing reads a credential it will not spend (task 1003081).
+  const remote = opts.gitRemote || 'origin';
+  const pushComing = !!opts.commitPin && !opts.pinNoPush && !dryRun && (dirtyPinFiles(instanceDir, run) || []).length > 0;
+  const pushAuth = pushComing ? await (deps.resolvePinPushAuth || resolvePinPushAuth)({ instanceDir, remote }, deps, run) : null;
   const pin = persistPin({
     instanceDir,
     fromVersion,
     toVersion: targetVersion,
     commitPin: opts.commitPin,
     push: !opts.pinNoPush,
-    remote: opts.gitRemote || 'origin',
+    remote,
     dryRun: opts.dryRun,
+    pushAuth,
   }, run, log, err);
 
   const ok = versionOk && healthOk !== false && servedOk !== false;
@@ -1211,6 +1383,7 @@ async function main(argv = process.argv.slice(2)) {
       '  --skip-pin-verify    do not verify the integrity pin (tree_sha256 + tarball.sha256) after install',
       '  --require-pin        treat a MISSING reference manifest as fatal (default: warn — a MISMATCH is always fatal)',
       '  --no-rollback-on-failure  do NOT auto-revert on a failed install/pin-verify/migrate/health check (default: auto-rollback ON)',
+      '  --commit-pin         commit + push package.json/-lock so a pull-deploy reset cannot revert the bump. The push rides the instance owner\'s stored GitHub token when one is stored (a PRIVATE instance\'s origin is a read-only deploy key — ADR 0176), else the git remote (--git-remote <name>, default origin); a refused push is reported loudly with the fix',
       '  --pin-no-push        with --commit-pin: commit the pin but do NOT push it — for an instance whose repo of record is not ours (a provisioned co-tenant), where the push is wrong and no pull-deploy can revert the commit',
       '  --dry-run            show the plan; change nothing',
       '  --force              skip the clean-tree + same-version guards',
@@ -1233,7 +1406,9 @@ async function main(argv = process.argv.slice(2)) {
 module.exports = {
   runUpgrade, parseArgs, main, rollback,
   versionFromTgzPath, versionFromDep, readInstalledCoreVersion, readPinnedCoreVersion, writePin, writeRegistryPin, restorePin,
-  vendorTarball, gitTreeClean, persistPin, dirtyPinFiles, gitCurrentBranch, PIN_FILES, preflightDbIdentity, resolveInstanceDb, preflightModules, reportModulePreflight, npmInstall, runMigrate, regenerateApiArtifacts, regenerateNavDocs, NAV_WHOLE_FILE_GENERATORS, missingDocAssets, healDocAssets, DOC_ASSET_GENERATORS, restartService, recordLedger, pollHealth, deriveVersionUrl, pollServedVersion,
+  vendorTarball, gitTreeClean, persistPin, dirtyPinFiles, gitCurrentBranch, PIN_FILES, preflightDbIdentity,
+  resolveInstanceDb, preflightModules, reportModulePreflight, npmInstall, runMigrate, regenerateApiArtifacts, regenerateNavDocs, NAV_WHOLE_FILE_GENERATORS, missingDocAssets, healDocAssets, DOC_ASSET_GENERATORS, restartService, recordLedger, pollHealth, deriveVersionUrl, pollServedVersion,
+  resolvePinPushAuth, remoteGithubRepo, pinnedDeployKey, // task 1003081 — the pin push prefers the owner's GitHub token (ADR 0176 follow-up)
   readManifest, resolveReferenceManifest, verifyInstalledPin, // task 1002216 (audit H8) — integrity-pin verification
   CORE_PKG, ARTIFACT, vendorRelFor,
 };

package/src/module-api.js

@@ -71,7 +71,7 @@ const { responsibilityFor, ROLE_RESPONSIBILITIES } = require('./role-responsibil
 // there. scripts/gds/bump-version.js still rewrites the literal below; it appends
 // the entry to that file. Look for a version's history there, not here.
 // ---------------------------------------------------------------------------
-const CORE_VERSION = '1.19.736'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
+const CORE_VERSION = '1.19.737'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
 
 // A namespaced logger so a module's log lines are attributable + consistent.
 // Usage: const log = api.logger('dev-box'); log.info('mounted');

package/tests/executed_closure.mjs

@@ -97,6 +97,14 @@ test('every computed require inside the closure is one we have accounted for', (
     // floor) is lazy and inside a function.
     ['scripts/gds/package-core.js', 6],   // publish-manifest/mirror-redact/secret-scrub/leak-scan-allowlist/…
     ['scripts/gds/upgrade.js', 1],        // a `node -e` child, not a require in this process
+    // Added by task 1003081: upgrade.js's pin push needs the owner-credential helpers,
+    // and requiring provision.js for them would have pulled provision-config/-repo/-units
+    // (7/1/1 unaccounted computed requires) into the closure. This LEAF is the whole of
+    // that growth: 3 computed requires — src/bongos/db in resolveOwnerGithubToken, and
+    // modules/provisioning + src/bongos/pool in lookupInstanceRow — each inside a function
+    // body reached only from the pin push, which no generator calls. Its top level requires
+    // node builtins only, so it drags nothing else in behind it.
+    ['scripts/gds/provision-repo-auth.js', 3],
     ['scripts/gds/gen-api-docs.js', 1],   // require(path.join(CORE_ROOT,'package.json')) — JSON
   ]);
 

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';
 
@@ -1390,6 +1393,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);