@bongos/core 1.19.196 → 1.19.197

package/.bongos-core.json

@@ -2,11 +2,11 @@
   "artifact": "bongos-core",
   "manifest_schema": 1,
   "generator": "scripts/gds/package-core.js",
-  "core_version": "1.19.196",
-  "core_contract": "1.19.196",
-  "source_commit": "057ae65d085a223a3f09f796164eee79e35242d6",
+  "core_version": "1.19.197",
+  "core_contract": "1.19.197",
+  "source_commit": "daaea01c453e9eae6e2748316e8e7dcfc24ae76b",
   "source_ref": "HEAD",
-  "built_at": "2026-08-17T02:44:35.952Z",
+  "built_at": "2026-08-17T14:35:32.236Z",
   "redaction": {
     "model": "docs-redacted+functional-verbatim",
     "docs_redacted": 309,
@@ -17,7 +17,7 @@
     "gate": "passed"
   },
   "file_count": 1615,
-  "tree_sha256": "0bab078fb9153e86b9ebaf32900bd0c90ba911bc05100fd25ce101dc5e4342b7",
+  "tree_sha256": "4788b5bff5cc099e1dff83c6a3bee9765222848137afe419fd54e869a6c4c39e",
   "files": [
     {
       "path": ".claude/skills/blocker-review/SKILL.md",
@@ -1137,7 +1137,7 @@
     {
       "path": "docs/adr/0133-github-app-manifest-onboarding-signin.md",
       "mode": "0000644",
-      "sha256": "23a28176cd5521d75a8179bef7da7d532c252470cf4e88f570f186cd0003015e"
+      "sha256": "94e1f79e0a32a53b51e5bbf6d10d37d477d676cad33b267dc3ddc0891ae70704"
     },
     {
       "path": "docs/adr/0134-private-first-npm-distribution.md",
@@ -1672,7 +1672,7 @@
     {
       "path": "docs/recipes/ops-gotchas.md",
       "mode": "0000644",
-      "sha256": "5a448a2d5520580623e91ca023dfc8d7e6f6fce2558b3c19e7cd24d16d4cb987"
+      "sha256": "52a209553565405dca461b1c4c0cef9fb0ec6d98b95ed420c82eaf1fa3eb15f6"
     },
     {
       "path": "docs/recipes/overnight-builder.md",
@@ -3967,7 +3967,7 @@
     {
       "path": "modules/provisioning/provisioning.js",
       "mode": "0000644",
-      "sha256": "90aa880898f6b3235e8b2a1a553695c63c29920968edb9c9af58364902118e33"
+      "sha256": "eebcba4b333030f17c06bc6e1423450ae4af124e4075af52cbd512e80d5ba95e"
     },
     {
       "path": "modules/provisioning/rate-limit.js",
@@ -3987,7 +3987,7 @@
     {
       "path": "modules/provisioning/tests/provisioning.mjs",
       "mode": "0000644",
-      "sha256": "0dc18db288580ca00792194ce5f50a13aae8c445c14d7fc42a2095ab2379c93f"
+      "sha256": "98787fad5df787a8ebdbf90fb8bf21b68f1529387b15d65724fdafc8ac0b91d0"
     },
     {
       "path": "modules/provisioning/ui/.gitkeep",
@@ -4272,12 +4272,12 @@
     {
       "path": "package-lock.json",
       "mode": "0000644",
-      "sha256": "ee80b4cb2114c56ba516f47f2e883ebaab71a1369863ce1c5f96cb982bd636eb"
+      "sha256": "69be9b66c6af5ccad87644d9a2460f8a6c59908e42613104b612654c41fa67ba"
     },
     {
       "path": "package.json",
       "mode": "0000644",
-      "sha256": "43f68be2f5fa45a19e658f124d5b70c535990e6b40a01abc9fc67e4daf9c28f1"
+      "sha256": "0b113ba37f114ec82e9f2dafa7e9d5cca35886e157934d7475850eb4f9dd66e1"
     },
     {
       "path": "public-docs/index.html",
@@ -5192,7 +5192,7 @@
     {
       "path": "scripts/gds/provision.js",
       "mode": "0000644",
-      "sha256": "1925ed112ec553a95388b81cccc1fb003ba2a0e91a5a80c6e315b45895688d0f"
+      "sha256": "1c348e8859004c69e66b8eede56da0bab68ec4d473790f1c1f9bf1769934211f"
     },
     {
       "path": "scripts/gds/publish-credential-check.js",
@@ -5887,7 +5887,7 @@
     {
       "path": "src/module-api.js",
       "mode": "0000644",
-      "sha256": "d789e8fcee6eed4ab2bf9badfaed68832830493d1d6b76f9d9263fae5c1d4163"
+      "sha256": "bdfd06f58403f6cb568ed65718a92450c7e41470a6eae1c2583101e9e47e6656"
     },
     {
       "path": "src/module-loader/catalog.js",
@@ -7507,7 +7507,7 @@
     {
       "path": "tests/provision.mjs",
       "mode": "0000644",
-      "sha256": "5297caf5005fd26c8435aa374511882a6c2d232e43f07cdc6ec19d1168ee1cc1"
+      "sha256": "9e8da984a2a9378809f03cc3f5f1c2cda34f8589ad954db1acd5b12bf424f322"
     },
     {
       "path": "tests/provisioning_default_domain.mjs",

package/docs/adr/0133-github-app-manifest-onboarding-signin.md

@@ -31,7 +31,9 @@ The conversion endpoint is unauthenticated (the code is the auth), so the web ti
 
 ### Manifest shape
 
-`redirect_url` = the **mothership** callback (the instance can't do the exchange). `callback_urls` = the **instance's** own `/api/gds/auth/web/callback` (what `auth.js` actually builds) **and** the `/api/bongos/...` alias, so sign-in works regardless of which prefix a build emits. `default_permissions: {}` (sign-in needs none), `hook_attributes.active:false`, `public:false`. Personal vs org differs only in the POST URL (derived from the repo owner); the App works for sign-in either way.
+`redirect_url` = the **mothership** callback (the instance can't do the exchange). `callback_urls` = the **instance's** own `/api/gds/auth/web/callback` (what `auth.js` actually builds) **and** the `/api/bongos/...` alias, so sign-in works regardless of which prefix a build emits. `default_permissions: {}` (sign-in needs none), `hook_attributes.active:false`, `public:true`. Personal vs org differs only in the POST URL (derived from the repo owner); the App works for sign-in either way.
+
+> **Amended 2026-08-17 (task 1003048, gap-list W6):** the manifest originally set `public:false`. That made every wizard-born project structurally single-builder on the web — GitHub answers a private App's authorize URL for any non-owner account with a bare 404, before the instance is ever involved (reproduced live on Spike Harbor). The App requests zero permissions, so public costs nothing; the manifest now sets `public:true`. Apps minted before the fix must be flipped by hand (GitHub App settings → Advanced → Make public) — see the ops-gotchas entry.
 
 **App name (tasks 2093 → 2095).** GitHub App names are globally unique across all of GitHub, so a bare project slug (e.g. `demo`) is almost always already taken. The auto name is the **instance domain** (e.g. `demo.cloudbongos.com`): a domain is inherently unique (so it never collides) and it reads perfectly on GitHub's sign-in consent screen, where the name is shown as *"`<name>` by `<owner>` … will redirect to `https://<domain>`"* — the name IS the destination. GitHub keeps the dots in the display name (only the internal slug is transformed) and caps it at 34 chars. **Fallback** (no domain, or a domain over 34 chars): brand-qualify the project — `<mothership brand> - <project>`, e.g. `Cloud Bongos - demo`, from the mothership's own `branding().identity.productName` (portable, not hardcoded) — still far less collision-prone than a bare slug. Either way it is only a default the owner can rename on GitHub's confirmation screen.
 

package/docs/recipes/ops-gotchas.md

@@ -127,6 +127,13 @@ Organized by topic, not chronology. New entries go in the matching section; crea
 - **Where this lives in the codebase:** [`src/bongos/routes/auth.js`](../../src/bongos/routes/auth.js) — `/auth/web/start` computes `redirectUri` from `publicOrigin(req)` and the `/auth/web/callback` route reads back to it. As of [#371](https://example.com/builders#/task/371) the error branches render a styled HTML page (with a retry link) instead of `text/plain`, so the visitor at least sees something coherent.
 - **Why it bites:** GitHub's warning page is intentionally scary and doesn't tell you *which* URL it expected; the only diagnostic is the `error=redirect_uri_mismatch` query param on the redirect back, which our server now surfaces in the styled error page.
 
+### Manifest-born GitHub Apps created before the task-1003048 fix are PRIVATE — non-owners get a bare 404 at sign-in
+
+- **Symptom:** On a wizard-created instance, any GitHub account other than the App's owner clicks "Sign in with GitHub" and gets a bare GitHub 404 — before the instance is ever involved. The project is effectively single-builder on the web. (Device Flow sign-in for the same non-owner works, which makes the failure look like anything but an App setting.)
+- **Root cause:** the ADR 0133 manifest flow used to mint the GitHub App with `public: false`, and GitHub 404s a private App's authorize URL for every non-owner. Fixed for newly minted Apps (`buildGithubAppManifest` now sets `public: true` — gap-list W6, task 1003048), but a manifest can't be re-applied to an existing App.
+- **Fix for pre-existing instances:** the App owner flips it by hand — github.com → Settings → Developer settings → GitHub Apps → (the instance's App) → **Advanced** → **Make public**. One click, no permission changes (the App requests none).
+- **Live evidence:** reproduced twice against Spike Harbor (instance 18) with a fresh verified-email account, 2026-08-16 — see `docs/audits/project-creation-gap-list.md` W6.
+
 ---
 
 ## Mac / local dev

package/modules/provisioning/provisioning.js

@@ -265,7 +265,7 @@ function githubAppName({ domain, brand, project } = {}) {
 //   • callback_urls — where "Login with GitHub" on the INSTANCE redirects during real
 //     sign-in. Both /api/gds/... (what auth.js actually builds) and the /api/bongos/...
 //     alias are registered so sign-in works regardless of which prefix a build emits.
-// Minimal for sign-in: no repo permissions, no webhook (active:false), not public. PURE.
+// Minimal for sign-in: no repo permissions, no webhook (active:false). PURE.
 function buildGithubAppManifest({ instanceName, slug, instanceDomain, mothershipOrigin, brand }) {
   const instOrigin = `https://${instanceDomain}`;
   const redirectUrl = `${String(mothershipOrigin || '').replace(/\/+$/, '')}/api/bongos/provisioning/github-app/callback`;
@@ -284,7 +284,13 @@ function buildGithubAppManifest({ instanceName, slug, instanceDomain, mothership
       `${instOrigin}/api/gds/auth/web/callback`,
       `${instOrigin}/api/bongos/auth/web/callback`,
     ],
-    public: false,
+    // public: GitHub answers a PRIVATE App's web authorize URL for any non-owner
+    // account with a bare 404 (before the instance is ever involved), so a private
+    // App makes the project structurally single-builder on the web. The App requests
+    // zero permissions, so public costs nothing (gap-list W6, task 1003048). Apps
+    // minted before this fix stay private until flipped by hand — see
+    // docs/recipes/ops-gotchas.md.
+    public: true,
   };
 }
 

package/modules/provisioning/tests/provisioning.mjs

@@ -165,7 +165,7 @@ t('githubAppName falls back to brand-qualified project when there is no usable d
   assert.ok(long.length <= 34 && long.startsWith('Cloud Bongos - '), `capped + brand kept: ${long}`);
 });
 
-t('buildGithubAppManifest points redirect at the MOTHERSHIP, callbacks at the INSTANCE, minimal perms, domain-named', () => {
+t('buildGithubAppManifest points redirect at the MOTHERSHIP, callbacks at the INSTANCE, minimal perms, public, domain-named', () => {
   const m = P.buildGithubAppManifest({
     instanceName: 'mercury', slug: 'mercury', brand: 'Cloud Bongos',
     instanceDomain: 'mercury.example.com', mothershipOrigin: 'https://cloudbongos.com',
@@ -179,10 +179,12 @@ t('buildGithubAppManifest points redirect at the MOTHERSHIP, callbacks at the IN
     'https://mercury.example.com/api/gds/auth/web/callback',
     'https://mercury.example.com/api/bongos/auth/web/callback',
   ]);
-  // sign-in needs no repo/account permissions; no active webhook; not public
+  // sign-in needs no repo/account permissions; no active webhook
   assert.deepEqual(m.default_permissions, {});
   assert.equal(m.hook_attributes.active, false);
-  assert.equal(m.public, false);
+  // public: a PRIVATE App answers the web authorize URL for any non-owner with a bare
+  // GitHub 404, making the project single-builder on the web (gap-list W6, task 1003048)
+  assert.equal(m.public, true);
 });
 
 t('buildGithubAppManifest tolerates a trailing slash on the mothership origin', () => {

package/package-lock.json

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

package/package.json

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

@@ -440,6 +440,42 @@ function installedCorePackDir({ instanceRoot, fsImpl = fs } = {}) {
   return null;
 }
 
+// Resolve a vendorable @bongos/core tarball — the three-rung ladder, freshest-correct
+// first, shared by the fresh scaffold and the re-provision pin refresh (task 1003050):
+//   1. a `file:`-pinned control plane reuses its own pinned tarball (task 1002275 —
+//      rebuilding via package-core.js aborts with an EMPTY core set when this runner
+//      IS a consumer instance, leaving new repos empty);
+//   2. a REGISTRY-pinned consumer (the post-1002621 mothership shape) packs the core
+//      it has INSTALLED — the child pins the SAME, CURRENT core the hub runs, ending
+//      the frozen-old-tarball births (task 1002706, gap 13) without requiring the
+//      child's owner to hold a token for the still-private registry package;
+//   3. a genuine core source checkout rebuilds fresh via package-core.js.
+// Returns { tgz, packDest } — packDest (set only on rung 2) is a temp dir the CALLER
+// must `rm -rf` once the tarball has been vendored.
+function resolveVendorableCoreTarball({ instanceRoot, exec, log, coreV, tag = '[core]' }) {
+  let tgz = installedCoreTarball({ instanceRoot });
+  let packDest = null;
+  if (tgz) {
+    log(`  ${tag} reusing the pinned core tarball this control plane runs (${path.basename(tgz)}) — no source rebuild (task 1002275)`);
+  } else {
+    const packSrc = installedCorePackDir({ instanceRoot });
+    if (packSrc) {
+      // Keyed by VERSION, not slug: no request-derived value enters this command, and
+      // two concurrent scaffolds of the same core pack identical bytes — collision-safe.
+      packDest = path.join(os.tmpdir(), `bongos-core-pack-${packSrc.version}`);
+      log(`  ${tag} packing the registry-installed core this control plane runs (v${packSrc.version}) — no source rebuild (task 1002706)`);
+      exec(`mkdir -p ${packDest}`);
+      exec(`npm pack ${packSrc.dir} --pack-destination ${packDest}`);
+      tgz = path.join(packDest, packSrc.tarballName);
+    } else {
+      log(`  ${tag} building a fresh vendored tarball from source (package-core.js)`);
+      exec(`node scripts/gds/package-core.js`);                    // cwd = REPO_ROOT → dist/bongos-core-<v>.tgz
+      tgz = path.join(REPO_ROOT, 'dist', `bongos-core-${coreV}.tgz`);
+    }
+  }
+  return { tgz, packDest };
+}
+
 // The onboard mode a provisioning row carries (migration provisioning_004, task 1002562).
 // 'adopt' means target_ref is a repo the owner ALREADY has, so the scaffold must LAYER
 // onto its history. Anything else — including a row written before the column existed, or
@@ -647,35 +683,11 @@ async function scaffoldStandaloneRepo(inst, deps) {
       log(`  [scaffold] core install: registry — PRIVATE @bongos/core@${coreV} via env-fed NPM_TOKEN (ADR 0134)`);
       exec(`node scripts/gds/init.js --from ${specPath} --dir ${root} --no-seed ${modeFlags} --registry-core`);
     } else {
-      // Vendored tarball — a three-rung resolution ladder, freshest-correct first:
-      //   1. a `file:`-pinned control plane reuses its own pinned tarball (task 1002275 —
-      //      rebuilding via package-core.js aborts with an EMPTY core set when this runner
-      //      IS a consumer instance, leaving new repos empty);
-      //   2. a REGISTRY-pinned consumer (the post-1002621 mothership shape) packs the core
-      //      it has INSTALLED — the child pins the SAME, CURRENT core the hub runs, ending
-      //      the frozen-old-tarball births (task 1002706, gap 13) without requiring the
-      //      child's owner to hold a token for the still-private registry package;
-      //   3. a genuine core source checkout rebuilds fresh via package-core.js.
-      let tgz = installedCoreTarball({ instanceRoot: deps.instanceRoot });
-      let packDest = null;   // set on the pack rung — cleaned up once init has vendored the tgz
-      if (tgz) {
-        log(`  [scaffold] core install: reusing the pinned core tarball this control plane runs (${path.basename(tgz)}) — no source rebuild (task 1002275)`);
-      } else {
-        const packSrc = installedCorePackDir({ instanceRoot: deps.instanceRoot });
-        if (packSrc) {
-          // Keyed by VERSION, not slug: no request-derived value enters this command, and
-          // two concurrent scaffolds of the same core pack identical bytes — collision-safe.
-          packDest = path.join(os.tmpdir(), `bongos-core-pack-${packSrc.version}`);
-          log(`  [scaffold] core install: packing the registry-installed core this control plane runs (v${packSrc.version}) — no source rebuild (task 1002706)`);
-          exec(`mkdir -p ${packDest}`);
-          exec(`npm pack ${packSrc.dir} --pack-destination ${packDest}`);
-          tgz = path.join(packDest, packSrc.tarballName);
-        } else {
-          log(`  [scaffold] core install: building a fresh vendored tarball from source (package-core.js)`);
-          exec(`node scripts/gds/package-core.js`);                    // cwd = REPO_ROOT → dist/bongos-core-<v>.tgz
-          tgz = path.join(REPO_ROOT, 'dist', `bongos-core-${coreV}.tgz`);
-        }
-      }
+      // Vendored tarball — resolveVendorableCoreTarball's three-rung ladder (shared
+      // with the re-provision pin refresh, task 1003050).
+      const { tgz, packDest } = resolveVendorableCoreTarball({
+        instanceRoot: deps.instanceRoot, exec, log, coreV, tag: '[scaffold] core install:',
+      });
       exec(`node scripts/gds/init.js --from ${specPath} --dir ${root} --no-seed ${modeFlags} --vendor-core ${tgz}`);
       // init --vendor-core COPIED the tarball into the child's vendor/ — the temp pack dir is spent.
       if (packDest) exec(`rm -rf ${packDest}`);
@@ -730,6 +742,140 @@ async function scaffoldStandaloneRepo(inst, deps) {
   }
 }
 
+// ── re-provision core-pin refresh (gap-list W3, task 1003050) ────────────────────
+//
+// The hazard: a standalone instance's RUNNING core can move ahead of its repo's
+// committed `file:` pin (an out-of-band `bongos upgrade`, a pre-fix re-provision that
+// refreshed the box without committing) — seen live on Spike Harbor, running a modern
+// core while the repo still pinned 1.19.2. The deploy path is repo-driven
+// (`git reset --hard origin/main` + `npm ci`), so the NEXT deploy silently rolls the
+// instance back against a DB the newer core has already migrated. ADR 0168 fixed
+// fresh scaffolds only; this closes the re-provision leg: every provision of an
+// already-scaffolded instance heals the committed pin to the core this control plane
+// runs, as a commit pushed to the instance repo.
+
+// The PURE decision half (tested in tests/provision.mjs). Registry pins are npm's to
+// resolve; an absent dep is not ours to invent; only `file:` pins are healed.
+function planCorePinRefresh({ pinnedDep, coreVersion }) {
+  const dep = String(pinnedDep || '').trim();
+  if (!dep) return { action: 'skip', reason: 'no @bongos/core dependency in the instance package.json' };
+  if (!/^file:/.test(dep)) return { action: 'skip', reason: `registry pin (${dep}) — npm ci resolves it; nothing to vendor` };
+  const upgrade = require('./upgrade');
+  const pinned = upgrade.versionFromTgzPath(dep);
+  if (pinned && pinned === coreVersion) return { action: 'current', pinned };
+  return { action: 'refresh', pinned: pinned || null };
+}
+
+// Coerce a version label to a semver-safe charset BEFORE it is interpolated into any
+// shell string. The "from" label ultimately derives from the INSTANCE's own repo
+// package.json `file:` pin (lower trust than the shared control plane) via
+// versionFromTgzPath, whose regex admits any char but `/` — including `"`, backtick,
+// `$()`, `;`. A crafted pin (e.g. `file:vendor/bongos-core-1.0.0";touch x;echo".tgz`)
+// would otherwise break out of a `git commit -m "…"` argument and run as the
+// control-plane user. This chokepoint rejects anything outside semver's own alphabet
+// (task 1003050 grade — command-injection block). PURE.
+function safeVersionLabel(v) {
+  const s = String(v == null ? '' : v).trim();
+  return /^[0-9A-Za-z.+-]{1,64}$/.test(s) ? s : '(unversioned)';
+}
+
+// The commit + push command sequence for a pin refresh — PURE, so tests/provision.mjs
+// covers "the runner's commit step" (task 1003050 AC) deterministically. Version
+// labels pass through safeVersionLabel (the one interpolation-safety chokepoint); the
+// push prefers the owner's OAuth token URL (the shared deploy key can't write a
+// consumer repo — task 1002317) and falls back to the SSH origin.
+function buildCorePinRefreshCommit({ root, fromVersion, toVersion, repo, ownerToken, credFile }) {
+  const from = safeVersionLabel(fromVersion);
+  const to = safeVersionLabel(toVersion);
+  const msg = `chore: re-provision refreshes the pinned @bongos/core ${from} -> ${to} (task 1003050)`;
+  const push = (ownerToken && repo && credFile)
+    ? `git -C ${root} -c credential.helper='store --file=${credFile}' push https://x-access-token@github.com/${repo.owner}/${repo.name}.git HEAD:main`
+    : `git -C ${root} push origin main`;
+  return {
+    config: [
+      `git -C ${root} config user.name "Cloud Bongos"`,
+      `git -C ${root} config user.email "bot@cloudbongos.com"`,
+    ],
+    add: `git -C ${root} add -A`,
+    commit: `git -C ${root} commit -m "${msg}"`,
+    push,
+  };
+}
+
+async function refreshStandaloneCorePin(inst, deps) {
+  const { log } = deps;
+  const exec = deps.controlExec || deps.exec;
+  const writeFile = deps.controlWriteFile || deps.writeFile;
+  const upgrade = require('./upgrade');
+  const root = standaloneRoot(inst);
+  const coreV = coreVersionSafe();
+  if (!coreV) { log('  [core-pin] cannot resolve the running core version — leaving the committed pin alone'); return { action: 'skip', reason: 'no core version' }; }
+  let pkg = null;
+  try { pkg = JSON.parse(fs.readFileSync(path.join(root, 'package.json'), 'utf8')); } catch { /* unreadable → skip below */ }
+  const pinnedDep = pkg && ((pkg.dependencies || {})['@bongos/core'] || (pkg.devDependencies || {})['@bongos/core']);
+  const plan = planCorePinRefresh({ pinnedDep, coreVersion: coreV });
+  if (plan.action === 'skip') { log(`  [core-pin] ${plan.reason}`); return plan; }
+  if (plan.action === 'current') { log(`  [core-pin] committed pin already matches the running core (${coreV})`); return plan; }
+  log(`  [core-pin] committed pin ${safeVersionLabel(plan.pinned)} trails this control plane's core ${coreV} — refreshing so the next repo-driven deploy cannot roll the instance back (task 1003050)`);
+
+  const { tgz, packDest } = resolveVendorableCoreTarball({
+    instanceRoot: deps.instanceRoot, exec, log, coreV, tag: '[core-pin]',
+  });
+  try {
+    const targetVersion = upgrade.versionFromTgzPath(path.basename(tgz)) || coreV;
+    const vendorRel = upgrade.vendorTarball({ instanceDir: root, fromTgz: tgz, targetVersion });
+    // Prune superseded vendored tarballs (+ manifests) so the repo carries exactly ONE
+    // core. fs.rmSync, NOT exec — a filename comes off the instance's own (lower-trust)
+    // vendor/ dir, so shelling `rm -f ${f}` would be the same injection vector as the
+    // commit label (a committed file named `bongos-core-x";touch pwn;".tgz`). A direct
+    // fs call takes the name as data, never as shell (task 1003050 grade).
+    const vendorDir = path.join(root, 'vendor');
+    const keep = new Set([`${upgrade.ARTIFACT}-${targetVersion}.tgz`, `${upgrade.ARTIFACT}-${targetVersion}.manifest.json`]);
+    // vendorTarball just mkdirSync'd this, so it exists on the happy path; guard anyway
+    // so an unexpectedly-absent dir prunes nothing instead of crashing the whole provision.
+    if (fs.existsSync(vendorDir)) {
+      for (const f of fs.readdirSync(vendorDir)) {
+        if (f.startsWith(`${upgrade.ARTIFACT}-`) && !keep.has(f)) fs.rmSync(path.join(vendorDir, f), { force: true });
+      }
+    }
+    upgrade.writePin(root, vendorRel);
+    // `npm install` (NOT ci): the pin just changed, the lockfile must be regenerated.
+    const instRes = upgrade.npmInstall(root);
+    if (!instRes.ok) {
+      throw new Error(`npm install after the core-pin refresh failed (${instRes.reason || `exit ${instRes.code}`}) — lockfile not regenerated; the pin refresh cannot be committed half-done.`);
+    }
+
+    // Commit + push the refresh to the instance repo — the shared deploy key cannot
+    // write a consumer's repo (task 1002317), so prefer the owner's OAuth token,
+    // exactly like the scaffold's push.
+    let ownerToken = null;
+    if (inst.owner_builder_id) {
+      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);
+        ownerToken = r && r.token ? r.token : null;
+      } catch (e) { log(`  [core-pin] owner OAuth token lookup failed (${e && e.message}) — pushing via the SSH origin`); }
+    }
+    const repo = parseTargetRef(inst.target_ref);
+    const credFile = ownerToken && repo ? path.join(os.tmpdir(), `bongos-gitcred-pin-${inst.slug}-${process.pid}`) : null;
+    const cmd = buildCorePinRefreshCommit({ root, fromVersion: plan.pinned, toVersion: targetVersion, repo, ownerToken, credFile });
+    try {
+      cmd.config.forEach((c) => exec(c));
+      exec(cmd.add);
+      exec(cmd.commit, { allowFail: true });
+      if (credFile) writeFile(credFile, `https://x-access-token:${ownerToken}@github.com\n`, { mode: 0o600 });
+      exec(cmd.push);
+    } finally {
+      if (credFile) exec(`rm -f ${credFile}`, { allowFail: true });
+    }
+    log(`  [core-pin] refreshed + pushed: @bongos/core ${safeVersionLabel(plan.pinned)} → ${targetVersion}`);
+    return { ...plan, refreshed: true, toVersion: targetVersion };
+  } finally {
+    if (packDest) exec(`rm -rf ${packDest}`);
+  }
+}
+
 // The per-instance systemd unit (the infra/cloudbongos.service shape): one Node process
 // bound to the instance's port + DB + brand, secrets from its own env file. SHAPE-AWARE:
 // a STANDALONE instance runs the CORE PACKAGE's platform-server from its OWN repo dir
@@ -1436,6 +1582,13 @@ async function provisionInstance(inst, deps) {
     const root = standaloneRoot(inst);
     log('  [code] standalone — pull instance repo + npm ci (pinned @bongos/core)');
     boxExec(standalonePullCmd(), { cwd: root });
+    // W3 (task 1003050): heal a committed `file:` pin that trails this control plane's
+    // running core BEFORE npm ci, so a re-provision can never leave running != pinned
+    // (the silent-rollback hazard: the next `git reset --hard` + `npm ci` deploy would
+    // otherwise revert the instance against an already-migrated DB). Gated on apply —
+    // the refresh writes through upgrade.js fs/npm calls, not the dry-run-safe exec.
+    if (apply) await refreshStandaloneCorePin(inst, deps);
+    else log('  [code] would refresh the committed @bongos/core pin if it trails the running core (task 1003050)');
     boxExec(standaloneInstallCmd(), { cwd: root });
   }
   log('  [db] create + GDS-only migrate');
@@ -2138,6 +2291,8 @@ module.exports = {
   standaloneRoot, standalonePullCmd, standaloneInstallCmd, standaloneMigrateCmd,
   // standalone scaffold (ADR 0108 / 0125, task 2055; consumer-core fix task 1002275)
   parseTargetRef, instanceRepoRemote, instanceInitSpec, installedCoreTarball, installedCorePackDir, scaffoldStandaloneRepo, coreVersionSafe,
+  // re-provision core-pin refresh (gap-list W3, task 1003050)
+  resolveVendorableCoreTarball, planCorePinRefresh, safeVersionLabel, buildCorePinRefreshCommit, refreshStandaloneCorePin,
   // adopt vs greenfield onboarding (ADR 0121, task 1002562)
   onboardMode, alreadyScaffolded,
   zoneForDomain, dnsUpsertEnv, classifyZoneScope, checkDnsTokenScope,

package/src/module-api.js

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

package/tests/provision.mjs

@@ -100,6 +100,72 @@ t('standalone step generators: root under standaloneBase + pull / npm-ci / insta
   assert.match(P.standaloneMigrateCmd(inst), /PGDATABASE=mercury MEDUSA_GDS_ONLY=1 bash node_modules\/@bongos\/core\/scripts\/migrate\.sh/);
 });
 
+// ── re-provision core-pin refresh (gap-list W3, task 1003050) ─────────────────
+t('planCorePinRefresh: a trailing file: pin → refresh; a current one → no-op', () => {
+  // The W3 shape: repo pins 1.19.2, control plane runs 1.19.196 → refresh (heals
+  // the silent-rollback hazard before the next repo-driven deploy).
+  assert.deepEqual(
+    P.planCorePinRefresh({ pinnedDep: 'file:vendor/bongos-core-1.19.2.tgz', coreVersion: '1.19.196' }),
+    { action: 'refresh', pinned: '1.19.2' });
+  // Pin already matches the running core → nothing to commit.
+  assert.deepEqual(
+    P.planCorePinRefresh({ pinnedDep: 'file:vendor/bongos-core-1.19.196.tgz', coreVersion: '1.19.196' }),
+    { action: 'current', pinned: '1.19.196' });
+  // A non-canonical file: pin can't be compared → refresh heals it to canonical.
+  assert.equal(
+    P.planCorePinRefresh({ pinnedDep: 'file:vendor/core.tgz', coreVersion: '1.19.196' }).action,
+    'refresh');
+});
+
+t('planCorePinRefresh: registry pins and absent deps are skipped, never rewritten', () => {
+  // Registry pin (ADR 0134): npm resolves it within its range — not ours to vendor.
+  assert.equal(P.planCorePinRefresh({ pinnedDep: '^1.19.100', coreVersion: '1.19.196' }).action, 'skip');
+  assert.equal(P.planCorePinRefresh({ pinnedDep: '1.19.196', coreVersion: '1.19.196' }).action, 'skip');
+  // No @bongos/core dependency at all → not ours to invent.
+  assert.equal(P.planCorePinRefresh({ pinnedDep: undefined, coreVersion: '1.19.196' }).action, 'skip');
+  assert.equal(P.planCorePinRefresh({ pinnedDep: '', coreVersion: '1.19.196' }).action, 'skip');
+});
+
+t('safeVersionLabel: passes clean semver, rejects any shell metacharacter', () => {
+  assert.equal(P.safeVersionLabel('1.19.196'), '1.19.196');
+  assert.equal(P.safeVersionLabel('1.19.2-rc.1+build'), '1.19.2-rc.1+build');
+  // The injection payloads the grader named — every one coerced away.
+  assert.equal(P.safeVersionLabel('1.0.0";touch /tmp/pwn;echo"'), '(unversioned)');
+  assert.equal(P.safeVersionLabel('$(whoami)'), '(unversioned)');
+  assert.equal(P.safeVersionLabel('1.0.0`id`'), '(unversioned)');
+  assert.equal(P.safeVersionLabel(''), '(unversioned)');
+  assert.equal(P.safeVersionLabel(null), '(unversioned)');
+});
+
+t('buildCorePinRefreshCommit (the commit step): git sequence, token-URL push, and the injection block', () => {
+  const repo = { owner: 'jaxri', name: 'spike-harbor' };
+  // Token present → push over the owner's OAuth credential URL (task 1002317).
+  const withTok = P.buildCorePinRefreshCommit({
+    root: '/srv/bongos/spike-harbor', fromVersion: '1.19.2', toVersion: '1.19.196',
+    repo, ownerToken: 'ghs_xxx', credFile: '/tmp/cred',
+  });
+  assert.deepEqual(withTok.config, [
+    'git -C /srv/bongos/spike-harbor config user.name "Cloud Bongos"',
+    'git -C /srv/bongos/spike-harbor config user.email "bot@cloudbongos.com"',
+  ]);
+  assert.equal(withTok.add, 'git -C /srv/bongos/spike-harbor add -A');
+  assert.match(withTok.commit, /@bongos\/core 1\.19\.2 -> 1\.19\.196 \(task 1003050\)/);
+  assert.match(withTok.push, /store --file=\/tmp\/cred.*x-access-token@github\.com\/jaxri\/spike-harbor\.git HEAD:main/);
+
+  // No token → SSH origin fallback (never a token URL).
+  const noTok = P.buildCorePinRefreshCommit({ root: '/srv/bongos/spike-harbor', fromVersion: '1.19.2', toVersion: '1.19.196', repo });
+  assert.equal(noTok.push, 'git -C /srv/bongos/spike-harbor push origin main');
+
+  // A malicious `file:` pin in the instance repo cannot break out of the -m argument:
+  // the coerced label carries no quote/`;`/`$()` — the commit line stays one argument.
+  const evil = P.buildCorePinRefreshCommit({
+    root: '/srv/bongos/spike-harbor', fromVersion: '1.0.0";touch /tmp/pwn;echo"', toVersion: '1.19.196',
+    repo, ownerToken: 'ghs_xxx', credFile: '/tmp/cred',
+  });
+  assert.ok(!evil.commit.includes('touch /tmp/pwn'), 'injection payload must not survive into the commit command');
+  assert.match(evil.commit, /@bongos\/core \(unversioned\) -> 1\.19\.196/);
+});
+
 // ── nightly DB backup units (task 2213 — productizes the manual 2210 fix) ──────
 t('backup units: per-instance names + the DB set on the unit (fixes the task-2210 unset GDS_BACKUP_DB)', () => {
   assert.equal(P.backupUnitName(coTenant), 'mercury-db-backup');