@bongos/core 1.19.747 → 1.19.749

package/.bongos-core.json

@@ -2,22 +2,22 @@
   "artifact": "bongos-core",
   "manifest_schema": 1,
   "generator": "scripts/gds/package-core.js",
-  "core_version": "1.19.747",
-  "core_contract": "1.19.747",
-  "source_commit": "492774317dbad5e66a4cd25638d81545e3561be3",
+  "core_version": "1.19.749",
+  "core_contract": "1.19.749",
+  "source_commit": "238806532985c069a1b8a778e5a3d223cd6b01c4",
   "source_ref": "HEAD",
-  "built_at": "2026-09-15T21:22:06.627Z",
+  "built_at": "2026-09-15T22:00:53.285Z",
   "redaction": {
     "model": "docs-redacted+functional-verbatim",
-    "docs_redacted": 481,
+    "docs_redacted": 482,
     "agent_docs_stubbed": 25,
     "functional_verbatim": 2109,
     "rules": 3,
     "gate_literals": 3,
     "gate": "passed"
   },
-  "file_count": 2615,
-  "tree_sha256": "839a3564a1926eee62dfb94ddeb8383deb0e2a794820335ab13c4a45fd1fddb5",
+  "file_count": 2616,
+  "tree_sha256": "ddc2e6cffdc346ee09a971dd7f237459cf8c142ad8cf058845f48638fa01a3e7",
   "files": [
     {
       "path": ".claude/skills/ask-for-help/SKILL.md",
@@ -1934,10 +1934,15 @@
       "mode": "0000644",
       "sha256": "f9141e74643a8055c3e7f7943957e1103d34b4673dd96c673636c30a50d47c36"
     },
+    {
+      "path": "docs/adr/0286-a-gated-project-s-manifest-tells-a-stranger-how-to-sign-in-and-nothing-else.md",
+      "mode": "0000644",
+      "sha256": "df40904ac989d54ea6bea561649a35a98ec7dc1ba96ea65395cb314ffe2059a9"
+    },
     {
       "path": "docs/adr/README.md",
       "mode": "0000644",
-      "sha256": "e36f3dffd983d410498269c6923c2b66a18071a25c1ea57eac0c8353b1ebc1bc"
+      "sha256": "e7f895a2f6dc062acd2afcf2c477ab8e60f1cbc93a836d8759a47d204a55a450"
     },
     {
       "path": "docs/api-reference.md",
@@ -2502,7 +2507,7 @@
     {
       "path": "docs/module-api-changelog.md",
       "mode": "0000644",
-      "sha256": "8bd715e0a97a235285a67533236b0769798356c3c72e22af8895ae7209bcc7f2"
+      "sha256": "207ce89a17ab5bd75cb956f9e41497ef39eb10d4f59eb634f0d1c1933304ced0"
     },
     {
       "path": "docs/modules-contract.md",
@@ -2762,7 +2767,7 @@
     {
       "path": "docs/recipes/upgrading-the-core.md",
       "mode": "0000644",
-      "sha256": "3691b017562bde760fbe3ff29a5efb80d886dd770f1187dc4673459871cec513"
+      "sha256": "408b4792ffb869f2fa13201485c1ab5b8306b93996bb75f01b4117de3fd39303"
     },
     {
       "path": "docs/recipes/windows-builders.md",
@@ -7557,12 +7562,12 @@
     {
       "path": "package-lock.json",
       "mode": "0000644",
-      "sha256": "07948a29433225ad3eb2ce1b2d71af8f884e723cd8a12b8d44a7a46331a7e156"
+      "sha256": "1cf816c4ca4b4b56d3fefe33e86e8ce4caa511ee69fd8dd6c2ecc2940dc07f7f"
     },
     {
       "path": "package.json",
       "mode": "0000644",
-      "sha256": "d20112e72f90d6ffe815316162e30da9ccdd4e0a3dd8a475572c62f39e90419a"
+      "sha256": "d890fe5b32e9b8158a19a40b765570972673f8558cb5d2e8e13ba396eee4476f"
     },
     {
       "path": "public-docs/index.html",
@@ -8922,7 +8927,7 @@
     {
       "path": "scripts/gds/upgrade.js",
       "mode": "0000644",
-      "sha256": "7a82fb0cf919e14700ceba718e28da1324df2eab669a847348271c85b2f7bd66"
+      "sha256": "fe3abe00b43163eb1b24dd2da57d4c8fd51194e79bab8a6683355980787a9e8c"
     },
     {
       "path": "scripts/gds/validate-design.js",
@@ -9197,7 +9202,7 @@
     {
       "path": "src/bongos/platform-visibility-gate.js",
       "mode": "0000644",
-      "sha256": "f422cf189a4d29fd2cc9a0ff4a6c71f4032f7cb56eab254f9b304a973afbb88d"
+      "sha256": "f1563c32d78eb1c598f49c5b241f9709c4957bcc4e8319773cf6a2c212d936e4"
     },
     {
       "path": "src/bongos/pool.js",
@@ -9277,7 +9282,7 @@
     {
       "path": "src/bongos/routes/instance.js",
       "mode": "0000644",
-      "sha256": "c3bfdf5f1242fe4bbbb51ea79401dd5ae09cca95adc475e0dc0e5c76055677c4"
+      "sha256": "f5ab4f2ad7391cbbfc9504190fe8fee19e18b5b43532dd4ffd37df258591fe66"
     },
     {
       "path": "src/bongos/routes/live.js",
@@ -9362,7 +9367,7 @@
     {
       "path": "src/module-api.js",
       "mode": "0000644",
-      "sha256": "269664a23f5e22f8499ae3067550f3edfc853d55b128cd6ec6f6556e337df0b9"
+      "sha256": "6c9cce81108782c099d58259ce776bed22f815f7276fa9fb9a50264aeedd3835"
     },
     {
       "path": "src/module-loader/catalog.js",
@@ -11312,7 +11317,7 @@
     {
       "path": "tests/instance_manifest.mjs",
       "mode": "0000644",
-      "sha256": "0686358d061f465409c585b46e38e9905728fc829aca361e1d0d15beb2316af9"
+      "sha256": "c45a264128a2cdc55675dcab82f8510a0d64e4d81bf4fd3f528b1aa720bdace0"
     },
     {
       "path": "tests/instance_mismatch_guard.mjs",
@@ -11817,7 +11822,7 @@
     {
       "path": "tests/platform_visibility_gate.mjs",
       "mode": "0000644",
-      "sha256": "bc2cf20f85fa231b0a8edf7bbf6eef4ef698674397ad9a7009aaaa3399e2dd1f"
+      "sha256": "ff9d438a33a32fecc04caa6e652eeaaded6394438bcec0d508ae7c516fa62333"
     },
     {
       "path": "tests/post_login_landing.mjs",
@@ -12937,12 +12942,12 @@
     {
       "path": "tests/upgrade.mjs",
       "mode": "0000644",
-      "sha256": "def73ab0f532c04df167d77917981eaf7e0dc7e1d2a7e7c85f3f962d7d65ce2a"
+      "sha256": "bcbba7b1c952088f43300405184849bbcbb2da789097fcc4cf38d95441e0c158"
     },
     {
       "path": "tests/upgrade_persist_pin.mjs",
       "mode": "0000644",
-      "sha256": "c0a96fbdc6a9f851925babfb0857c9a168374c4165c84884f5c4c56c7177dd58"
+      "sha256": "864b9471fcd6bfc41e99fd5356a3124c25d288946326c2797cc2bacb86120d05"
     },
     {
       "path": "tests/verify_task_guard.mjs",

package/docs/adr/0286-a-gated-project-s-manifest-tells-a-stranger-how-to-sign-in-and-nothing-else.md

@@ -0,0 +1,44 @@
+# ADR 0286 — A gated project's manifest tells a stranger how to sign in, and nothing else
+
+- **Status:** accepted
+- **Date:** 2026-09-15
+- **Task:** [1003652](https://cloudbongos.com/builders#/task/1003652) (goal 1000106), from idea 1000845. Closes the item [ADR 0192](0192-platform-visibility-member-door.md) deferred as "projecting the manifest down when gated".
+
+## Context
+
+A gated project (`platformVisibility: 'gated'`, ADR 0192) refuses strangers on every surface except a short exempt list. `GET /api/*/instance` is on that list for two reasons. A stranger reads it to learn how to sign in, and the platform's runner reads it cookie-less after a settings restart to confirm the value was consumed (`provision-units.js` `settingsConsumed`), including the push that turns the gate on.
+
+The route still answered with the **full** manifest: every branding string (company, tagline, palette, rank labels), the module roster, the rank ladder, dev-box availability, and the repository's `owner/repo/branch/url`, even when the owner had made that repository private.
+
+## Decision
+
+The owner's call: **sign-in basics only.** When the project is gated **and** the caller has no live, non-deactivated session (cookie or Bearer, the same `resolveSession` lookup the member door uses), `routes/instance.js` answers with `strangerManifest()`:
+
+```
+{ schema, name, brand: { identity: { productName }, project }, auth, admission }
+```
+
+| Kept | Why |
+|---|---|
+| `schema` | `bongos login` refuses any other id, so the value stays `instance-manifest/v1`: the stranger shape is a subset, and every kept field means what it means in the full manifest |
+| `name`, `brand.identity.productName` | the door and the CLI name the project |
+| `auth` including `idp` | the CLI routes device-flow and web sign-in through the hub from `auth.idp` |
+| `admission` | `bongos login` tells an applicant invite-only from open |
+| `brand.project` | the runner's settings read-back; the hub's `projects.html` (`platformVisibility`); `platform-identity/visibility-pull.js` (`visibility`); `bongos login` (`joinability`) |
+
+- **Members** get the full manifest.
+- **A session lookup that fails** gets the stranger answer rather than a 500. The manifest is how the door gets opened, and an unknown identity must not see a member's answer.
+- **Every gated response** is sent with `Cache-Control: private, no-store` and `Vary: Cookie, Authorization`: one URL, two answers by identity. The route is exempt from the gate, so the gate's own `markPrivate` never runs on it.
+- **Ungated projects** are unchanged.
+
+## Alternatives considered
+
+- **Gate the manifest like every other surface.** Rejected: the door could not be opened, and the runner could not confirm the push that gates the project.
+- **A separate `/instance/sign-in` endpoint.** Rejected: two routes to keep in agreement, and every shipped CLI already reads `/instance`.
+- **Project down for everyone, gated or not.** Rejected: an ungated project is public by the owner's choice, and the CLI's `devBox` and module checks read the full shape.
+
+## Consequences
+
+- **+** A stranger to a gated project no longer learns what it runs, how its ranks are named, what it looks like, or where its code lives.
+- **−** `cli-lib.js` `devBoxEnabledInManifest` fails open (assumes a box exists) when `modules` is missing. That only happens on a session-less fetch; the CLI sends its bearer, so a signed-in member reads the real roster.
+- **−** A gated project's manifest can no longer be cached at an edge. It is one small JSON read per sign-in.

package/docs/adr/README.md

@@ -377,3 +377,4 @@ This keeps the decision history honest and traceable.
 | 0283 | [**The core publishes publicly, because access was never the thing protecting it** ([task 1003872](https://cloudbongos.com/builders#/task/1003872) · goal 1000090 — *Working area 4, Bongos Core distribution*; owner decision 2026-09-13, resolving [task 1003502](https://cloudbongos.com/builders#/task/1003502)). [ADR 0134](0134-private-first-npm-distribution.md) chose private-first and named "public at launch" as a later deliberate step; this is that step. The restricted posture had a cost that grew quietly because every symptom read as a different bug: a tokenless `npm install` returns a flat **E404**, indistinguishable from "no such package", so every co-tenant and downstream upgrade needed a credential to move at all; the nightly auto-upgrade sweep **died on 2026-08-25 and reported `failed=0`** (its unit passed no `NPM_TOKEN`, the env-fed `.npmrc` expanded to empty, and a skip is not a failure in that script's accounting, so nothing complained while the instance stopped receiving core updates); an Anthropic-hosted cloud session could not install the dependency at all; and a fresh scaffold's README step 1 IS `npm install`, which is also what installs the `bongos` command — so without a token an owner got no working instance rather than a stale one. [ADR 0258](0258-the-public-cli-is-a-generated-client-package-not-the-published-core.md)'s `@cloudbongos/cli`, require-closure delazification and all, exists ONLY because of this. **The decisive point is that access control was never what protected the artifact:** three gates decide what is IN the tarball — the in-build no-leak gate (branding literals + credential shapes, fail-closed, 2,624 files clean), the prior-instance leak scan (**fatal by default since [task 1003870](https://cloudbongos.com/builders#/task/1003870)**, `--no-leak-scan` the only escape), and the fixture confirmation of [task 1003871](https://cloudbongos.com/builders#/task/1003871) (all 14 credential-shape files checked against each provider's real key format: 11 too short to have ever been valid, 3 alphabet sequences or Amazon's own published doc example). `--access restricted` decides who may FETCH it; those three decide what is IN it, and conflating them is what made a launch-timing choice feel like a security control. **Decision: publish public — at all three sites.** `publishConfig.access` and `publishArgs` both say `public` (belt-and-braces of the restricted era pointed the other way, so neither drifting alone reverts it), **and so does `publish.yml`** — the site that ACTUALLY releases, `package-core --publish` being the manual owner path. Flipping only `package-core.js` would have left every real release restricted while the code claimed otherwise: exactly task 1003870's shape, where the workflow did not arm the gate its own header comment advertised. A test reads the workflow and fails if `restricted` reappears anywhere in the lane. **The one-time registry flip stays a separate owner step** (`npm access set status=public`): `--access` governs what THAT publish declares and has historically been a no-op when re-publishing an already-private package — the package read `private` on the registry when this was written — so it is verified by a tokenless install from a clean `HOME`, never by the flag's presence. **Provenance stays off:** the PACKAGE is public, the SOURCE REPO is not, and npm blocks provenance on the repo's visibility — turning it on before the source repository goes public fails every publish. The npm path deliberately does not run [ADR 0099](0099-delayed-redacted-mirror-export.md)'s mirror pipeline (`package-core` runs its own redaction: 476 docs redacted, 24 agent-docs stubbed), which is why gates 1–3 carry the whole safety burden and had to land first. **Going public is effectively one-way** — a published tarball is mirrored and cached beyond our control and `npm unpublish` has a 72-hour window that does not reach mirrors. **Does NOT fix the 22 co-tenants:** twenty pin `file:vendor/bongos-core-<v>.tgz`, a local path with no registry channel to follow, so public access is necessary but not sufficient. Rejected: a **rank-gated registry proxy** (server holds the token, builders authenticate with their existing Bongos session, per-request rank check — the RIGHT design if the core must stay private, rejected because it manages the problem going public deletes); **handing builders the read token gated by rank** (rank-gating the handout does not rank-gate the use — a token once held is held forever and revocation means rotating it for everyone: access control in name only); keeping the vendored tarball as the answer (it is why twenty co-tenants are frozen at their provisioning date); making the REPO public in the same change (a larger decision, not required for any of this, and separating them keeps the provenance question honest).](0283-the-core-publishes-publicly-because-access-was-never-the-thing-protecting-it.md) | core distribution / npm access |
 | 0284 | [**The control plane carries no metrics stack** ([task 1003876](https://cloudbongos.com/builders#/task/1003876) · goal 1000106). Supersedes ADR 0127. Grafana (187 MB, the box's largest process) + Prometheus (110 MB, 2.5 GB data) were removed from the `s-1vcpu-2gb` control plane every provisioned project shares; they scraped none of those projects and nothing in the core read them. Owner chose remove over move-to-own-droplet. The `/metrics` exporter stays in every instance, so a scraper can return from a box that is not the control plane. Leftovers (DNS record, co-hosting-box socat forwarders, instance `infra/` copies) filed as a follow-up.](0284-the-control-plane-carries-no-metrics-stack.md) | infra / Cloud Bongos |
 | 0285 | [**A shared box holds about twelve projects per GB, and memory is the wall** ([task 1003877](https://cloudbongos.com/builders#/task/1003877) · goal 1000106, a spike measured read-only on the live control plane at the owner's call). A project costs ~80 MB warm (70 MB Node + one busy Postgres backend); idle projects look like ~25 MB only because swap holds their cold pages, and swap is not capacity. Fixed base ~750 MB on a control plane. Ceiling per tier `floor((usable − fixed) / 80)`: 15 on today's `s-1vcpu-2gb` (11 live), 39 on `s-2vcpu-4gb`; resize at 12. RAM binds first, Postgres connections (pool default 10 × N vs 97) second; CPU, ports, units, disk and the backup window do not bind. Keep the three shapes, add placement ("standalone until the box is full, then the next box"); a shared slot costs box price ÷ ceiling ($0.62–0.80/mo), `dedicated` 8–40× that.](0285-a-shared-box-holds-about-twelve-projects-per-gb-and-memory-is-the-wall.md) | infra / Cloud Bongos |
+| 0286 | [**A gated project's manifest tells a stranger how to sign in, and nothing else** ([task 1003652](https://cloudbongos.com/builders#/task/1003652) · goal 1000106, from idea 1000845; closes ADR 0192's deferred item). `GET /instance` stays exempt from the member door, but on a gated project a caller with no live session gets `{ schema, name, brand: { identity.productName, project }, auth (incl. idp), admission }` — no modules, ranks, repo coordinates, dev-box flag or branding strings. Members get the full manifest; a failed lookup answers as a stranger; gated responses are `private, no-store` + `Vary: Cookie, Authorization`. Schema id stays `instance-manifest/v1` (a subset; `bongos login` refuses any other). Owner's call: sign-in basics only.](0286-a-gated-project-s-manifest-tells-a-stranger-how-to-sign-in-and-nothing-else.md) | security / Cloud Bongos |

package/docs/module-api-changelog.md

@@ -1968,5 +1968,9 @@ is load-bearing: the script throws rather than guess if it is missing, and
         landed since 1.19.745 with no explicit bump. run 35021312150. (task 1002620)
   1.19.747 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
         landed since 1.19.746 with no explicit bump. run 35025151628. (task 1002620)
+  1.19.748 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+        landed since 1.19.747 with no explicit bump. run 35026862340. (task 1002620)
+  1.19.749 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+        landed since 1.19.748 with no explicit bump. run 35028684745. (task 1002620)
 ---------------------------------------------------------------------------
 ```

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

@@ -55,7 +55,7 @@ The instance runs on the droplet (co-tenant): systemd `emersonian-circles.servic
 
    > **The pin MUST reach the repo of record, or the bump silently un-does itself** (task 1002712). A pull-deploy instance resets to `origin/main`; a pin that lives only in the working tree is reverted the next time anything lands, and the lockfile change then trips `npm ci`, which reinstalls the OLD core. Nothing errors. cloudbongos.com lost thirteen releases exactly this way — the `core_upgrades` ledger held two successful `auto-subscription (patch)` rows whose result no longer existed on disk, because deploy.sh short-circuits while `HEAD == origin/main` so the upgrade *looks* fine right up until someone else pushes.
    >
-   > `bongos upgrade` now **warns loudly** whenever it leaves the pin uncommitted in a git repo, and `--commit-pin` (optionally `--git-remote <name>`) commits + pushes `package.json` + `package-lock.json` for you. A commit that fails to push is reported as a failure too — deploy.sh resets to the *remote*, so committing locally saves nothing. Verify durability by forcing a deploy tick (`sudo systemctl start <instance>-deploy.service`) and re-reading the pin.
+   > `bongos upgrade` now **warns loudly** whenever it leaves the pin uncommitted in a git repo, and `--commit-pin` (optionally `--git-remote <name>`) commits + pushes `package.json` + `package-lock.json` for you, together with any regenerated API spec, reference and typed client the bump rewrote (task 1003926 — left uncommitted, they made the next upgrade fail its clean-tree pre-flight). A commit that fails to push is reported as a failure too — deploy.sh resets to the *remote*, so committing locally saves nothing. Verify durability by forcing a deploy tick (`sudo systemctl start <instance>-deploy.service`) and re-reading the pin.
 7. **Align the droplet checkout** — the droplet has no deploy key (`git pull` fails; idea 509), so `git bundle` the new commit on the laptop, `scp`, `git fetch <bundle> && git reset --hard FETCH_HEAD`. `node_modules` is already the new version, so no re-`npm ci`; a final restart makes `/version` report the new commit.
 
 ## Auto-rollback on failure (task 2149)

package/package-lock.json

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

package/package.json

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

@@ -157,6 +157,17 @@ function gitTreeClean(instanceDir, run = spawnSync) {
 // Hence: --commit-pin lands it, and its absence WARNS rather than staying quiet.
 const PIN_FILES = ['package.json', 'package-lock.json'];
 
+// The tracked files regenerateApiArtifacts' generators rewrite WHOLE, by generator (task
+// 1003926). Committing only the pin left these dirty, so the NEXT `bongos upgrade` refused
+// its clean-tree pre-flight. They are generated end to end, so once a generator has run
+// their content is its output whatever they held before: committing them can never carry
+// an owner's edit. tests/upgrade_persist_pin.mjs pins this list against both generators.
+const API_ARTIFACT_FILES = {
+  'gen-api-docs.js': ['docs/api/openapi.json', 'docs/api-reference.md', 'docs/routes-permissions.md'],
+  'gen-api-client.js': ['index.mjs', 'index.cjs', 'bongos-client.global.js', 'index.d.ts', 'package.json', 'README.md']
+    .map((f) => `clients/bongos-client/${f}`),
+};
+
 function gitCurrentBranch(instanceDir, run = spawnSync) {
   const r = run('git', ['rev-parse', '--abbrev-ref', 'HEAD'], { cwd: instanceDir, encoding: 'utf8' });
   if (!r || r.error || r.status !== 0) return null;
@@ -164,13 +175,17 @@ function gitCurrentBranch(instanceDir, run = spawnSync) {
   return b && b !== 'HEAD' ? b : null;
 }
 
-// Which of the pin files git currently reports as modified.
-function dirtyPinFiles(instanceDir, run = spawnSync) {
-  const r = run('git', ['status', '--porcelain', '--', ...PIN_FILES], { cwd: instanceDir, encoding: 'utf8' });
+// Which of `paths` git currently reports as changed — never a path it was not asked about,
+// and no git call for an empty list (a pathspec of nothing is the whole tree).
+function dirtyPaths(instanceDir, paths, run = spawnSync) {
+  if (!paths.length) return [];
+  const r = run('git', ['status', '--porcelain', '--', ...paths], { cwd: instanceDir, encoding: 'utf8' });
   if (!r || r.error || r.status !== 0) return null; // not a git repo — nothing to persist
-  return (r.stdout || '').split('\n').map((l) => l.slice(3).trim()).filter(Boolean);
+  return (r.stdout || '').split('\n').map((l) => l.slice(3).trim()).filter((p) => paths.includes(p));
 }
 
+function dirtyPinFiles(instanceDir, run = spawnSync) { return dirtyPaths(instanceDir, PIN_FILES, run); }
+
 // ---- 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
@@ -285,11 +300,16 @@ function gitSaid(r) {
 // 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 },
+// `artifactPaths` (task 1003926) are the generated files this upgrade rewrote; the ones
+// that changed are staged and committed with the pin.
+function persistPin({ instanceDir, fromVersion, toVersion, commitPin, push = true, remote = 'origin', dryRun = false, pushAuth = null, artifactPaths = [] },
   run = spawnSync, log = console.log, err = console.error) {
-  const dirty = dirtyPinFiles(instanceDir, run);
-  if (dirty === null) return { applicable: false, reason: 'not a git repo' };
+  const dirtyPins = dirtyPinFiles(instanceDir, run);
+  if (dirtyPins === null) return { applicable: false, reason: 'not a git repo' };
+  const dirtyArtifacts = dirtyPaths(instanceDir, artifactPaths, run) || [];
+  const dirty = [...dirtyPins, ...dirtyArtifacts];
   if (!dirty.length) return { applicable: false, reason: 'pin files already match the repo' };
+  const toStage = [...PIN_FILES, ...dirtyArtifacts];
 
   const branch = gitCurrentBranch(instanceDir, run);
   const target = `HEAD:${branch || 'main'}`;
@@ -314,7 +334,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:`);
-    err(`      ${at} add ${PIN_FILES.map(q).join(' ')} && ${at} commit -m ${q(`pin @bongos/core ${toVersion}`)} && ${at} push ${q(remote)} ${q(target)}`);
+    err(`      ${at} add ${toStage.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 };
   }
 
@@ -326,7 +346,7 @@ function persistPin({ instanceDir, fromVersion, toVersion, commitPin, push = tru
   }
 
   const message = `pin @bongos/core ${toVersion}${fromVersion ? ` (was ${fromVersion})` : ''}`;
-  const add = run('git', ['add', ...PIN_FILES], { cwd: instanceDir, encoding: 'utf8' });
+  const add = run('git', ['add', ...toStage], { cwd: instanceDir, encoding: 'utf8' });
   if (!add || add.error || add.status !== 0) {
     err('  ! could not stage the pin files — commit + push them by hand or the next deploy reverts this bump.');
     return { applicable: true, committed: false, pushed: false, dirty, error: 'git add failed' };
@@ -572,7 +592,7 @@ function resolveInstanceDb({ instanceDir }, run = spawnSync) {
 function regenerateApiArtifacts({ instanceDir, coreRoot }, run = spawnSync, fsImpl = fs) {
   const env = { ...process.env, BONGOS_INSTANCE_ROOT: instanceDir };
   const ran = [];
-  for (const gen of ['gen-api-docs.js', 'gen-api-client.js']) {
+  for (const gen of Object.keys(API_ARTIFACT_FILES)) {
     const script = path.join(coreRoot, 'scripts', 'gds', gen);
     if (!fsImpl.existsSync(script)) return { ok: false, ran, reason: `${gen} not found in core (${coreRoot})` };
     const r = run(process.execPath, [script], { cwd: instanceDir, env, stdio: 'inherit' });
@@ -1185,9 +1205,11 @@ async function runUpgrade(opts, deps = {}) {
   // 5b. regenerate the per-instance API artifacts (OpenAPI spec + typed client) from the
   // new core's routes — the claude-materialize sibling (task 2051). Best-effort: a regen
   // hiccup is a warning, not a failed bump (the next ship's fitness gate refreshes them).
+  let regenArtifacts = [];
   if (!opts.skipRegenDocs) {
     const coreRoot = path.join(instanceDir, 'node_modules', CORE_PKG);
     const regen = (deps.regenerateApiArtifacts || regenerateApiArtifacts)({ instanceDir, coreRoot }, run);
+    regenArtifacts = (regen.ran || []).flatMap((gen) => API_ARTIFACT_FILES[gen] || []);
     if (regen.ok) log(`  ✓ regenerated API docs + typed client from core ${targetVersion}`);
     else err(`  ! API-artifact regen incomplete (${regen.reason}) — ran ${regen.ran.join(', ') || 'nothing'}; the next ship's fitness gate refreshes them.`);
     // 5c. regenerate the whole-file navigation docs (repo-map + session-index) from the new
@@ -1301,7 +1323,8 @@ async function runUpgrade(opts, deps = {}) {
   // 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 pushComing = !!opts.commitPin && !opts.pinNoPush && !dryRun
+    && ((dirtyPinFiles(instanceDir, run) || []).length > 0 || (dirtyPaths(instanceDir, regenArtifacts, run) || []).length > 0);
   const pushAuth = pushComing ? await (deps.resolvePinPushAuth || resolvePinPushAuth)({ instanceDir, remote }, deps, run) : null;
   const pin = persistPin({
     instanceDir,
@@ -1312,6 +1335,7 @@ async function runUpgrade(opts, deps = {}) {
     remote,
     dryRun: opts.dryRun,
     pushAuth,
+    artifactPaths: regenArtifacts,
   }, run, log, err);
 
   const ok = versionOk && healthOk !== false && servedOk !== false;
@@ -1394,7 +1418,7 @@ 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,
+  vendorTarball, gitTreeClean, persistPin, dirtyPinFiles, gitCurrentBranch, PIN_FILES, API_ARTIFACT_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

package/src/bongos/platform-visibility-gate.js

@@ -56,6 +56,7 @@ const API = `(?:${ALL_API_PREFIXES.map(escRe).join('|')})`;
 //                        value was consumed (provision-units.js settingsConsumed)
 //                        — including the very push that turns this gate on. It
 //                        carries the policy itself, public by nature (ADR 0190 §9).
+//                        A stranger gets its sign-in projection only (ADR 0286).
 //   <api>/healthz, /healthz, /version, /metrics
 //                        the probes: the deploy's, the runner's, the uptime
 //                        poller's, the control plane's liveness sweep; Prometheus

package/src/bongos/routes/instance.js

@@ -26,14 +26,22 @@
 // hosts, no DB name, no env prefix, no tokens. The assembler (buildInstanceManifest)
 // is PURE — all inputs injected — so a unit test proves the shape + the no-leak
 // guarantee with zero I/O (mirrors resolveBranding/resolveModules, ADR 0062 §3/§4).
+//
+// GATED PROJECTS (task 1003652, ADR 0286): the route stays exempt from the member
+// door (ADR 0192) because a stranger needs it to sign in, but a caller with no live
+// session on a gated project gets strangerManifest() — sign-in basics only, not
+// what the project runs or where its code lives. Members get the full manifest.
 
 const express = require('express');
 const { corsPublicGet, asyncHandler } = require('./_helpers');
 const { clientBranding } = require('../../branding');
 const { clientModules, isModuleEnabled } = require('../../modules');
 const { loadRepoInfo } = require('../repo-info');
-const { authConfigured, openEnrollmentEnabled, loadIdpConfig } = require('../auth');
+const { authConfigured, openEnrollmentEnabled, loadIdpConfig, resolveSession } = require('../auth');
 const { RANK_TIER } = require('../permission-path-check');
+const { isGated } = require('../platform-visibility-gate');
+
+const log = require('../logger').logger.child({ src: 'instance' });
 
 // The manifest format id — bumped when the SHAPE changes so a CLI can detect a
 // too-new server. Deliberately neutral (no instance/platform identity literal).
@@ -105,7 +113,61 @@ function buildInstanceManifest({
   };
 }
 
-module.exports = function buildInstanceRouter() {
+// strangerManifest — PURE. What a gated project tells a caller with no live session:
+// enough to sign in (name, auth incl. the idp hint, admission) plus brand.project,
+// which the platform runner reads back cookie-less after a settings restart. Same
+// schema id — every kept field means what it does in the full manifest.
+function strangerManifest(manifest) {
+  const { schema, name, brand, auth, admission } = manifest;
+  return {
+    schema,
+    name,
+    brand: { identity: { productName: name }, project: brand && brand.project },
+    auth,
+    admission,
+  };
+}
+
+function currentManifest() {
+  const idpCfg = loadIdpConfig();
+  return buildInstanceManifest({
+    branding: clientBranding(),
+    modules: clientModules(),
+    rankTier: RANK_TIER,
+    repo: loadRepoInfo(),
+    authConfigured: authConfigured(),
+    // The COMPOSED join door, not the raw `joinability` knob (task 1003579):
+    // `admission.policy` says whether a stranger can actually sign themselves
+    // in, so a project that is off the map reports 'invite-only' even while its
+    // `joinability` reads back 'open' under brand.project. The two fields answer
+    // different questions on purpose — one is the owner's setting, the other is
+    // what the gate will do — and 'invite-only' already covers every non-open
+    // door, so narrowing it names no state (ADR 0247 D3).
+    openEnrollment: openEnrollmentEnabled(),
+    devBoxEnabled: isModuleEnabled('dev-box'),
+    // Project OUT the client secret — the manifest is public; only origin +
+    // client_id (both public) advertise federation.
+    idp: idpCfg ? { origin: idpCfg.origin, client_id: idpCfg.clientId } : null,
+  });
+}
+
+// A failed lookup answers as a stranger rather than a 500: the manifest is how the
+// door gets opened, and an unknown identity must not see a member's answer.
+async function isMember(req, lookup) {
+  try {
+    const session = await lookup(req);
+    return !!session && session.status !== 'inactive';
+  } catch (err) {
+    log.error({ err: err && err.message }, 'session lookup failed — answering as a stranger');
+    return false;
+  }
+}
+
+// `deps` exists for tests only (the platformVisibilityGate shape).
+module.exports = function buildInstanceRouter(deps = {}) {
+  const gated = deps.isGated || isGated;
+  const lookup = deps.resolveSession || resolveSession;
+  const buildManifest = deps.buildManifest || currentManifest;
   const router = express.Router();
 
   // CORS for the unauthenticated cross-origin read (same posture as /public/*
@@ -116,33 +178,20 @@ module.exports = function buildInstanceRouter() {
   // fetches it to learn how to sign in). asyncHandler returns a 500 with no
   // err.message if branding/modules fail to resolve (misconfigured instance) —
   // never leaks internals.
-  router.get('/instance', asyncHandler('GET /instance', (_req, res) => {
-    const idpCfg = loadIdpConfig();
-    res.json(buildInstanceManifest({
-      branding: clientBranding(),
-      modules: clientModules(),
-      rankTier: RANK_TIER,
-      repo: loadRepoInfo(),
-      authConfigured: authConfigured(),
-      // The COMPOSED join door, not the raw `joinability` knob (task 1003579):
-      // `admission.policy` says whether a stranger can actually sign themselves
-      // in, so a project that is off the map reports 'invite-only' even while its
-      // `joinability` reads back 'open' under brand.project. The two fields answer
-      // different questions on purpose — one is the owner's setting, the other is
-      // what the gate will do — and 'invite-only' already covers every non-open
-      // door, so narrowing it names no state (ADR 0247 D3).
-      openEnrollment: openEnrollmentEnabled(),
-      devBoxEnabled: isModuleEnabled('dev-box'),
-      // Project OUT the client secret — the manifest is public; only origin +
-      // client_id (both public) advertise federation.
-      idp: idpCfg ? { origin: idpCfg.origin, client_id: idpCfg.clientId } : null,
-    }));
+  router.get('/instance', asyncHandler('GET /instance', async (req, res) => {
+    const manifest = buildManifest();
+    if (!gated()) return res.json(manifest);
+    // One URL, two answers by identity: no shared cache may keep either.
+    res.set('Cache-Control', 'private, no-store');
+    res.vary('Cookie').vary('Authorization');
+    res.json(await isMember(req, lookup) ? manifest : strangerManifest(manifest));
   }, { message: false, errorCode: 'instance_manifest_failed' }));
 
   return router;
 };
 
-// Exported for unit tests (the pure assembler) + the schema/auth constants.
+// Exported for unit tests (the pure assemblers) + the schema/auth constants.
 module.exports.buildInstanceManifest = buildInstanceManifest;
+module.exports.strangerManifest = strangerManifest;
 module.exports.MANIFEST_SCHEMA = MANIFEST_SCHEMA;
 module.exports.AUTH_METHODS = AUTH_METHODS;

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.747'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
+const CORE_VERSION = '1.19.749'; // 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/instance_manifest.mjs

@@ -116,3 +116,84 @@ test('manifest: vanilla instance is fully populated (every field present)', () =
   assert.equal(m.name, 'Cloud Bongos');
   assert.deepEqual(m.modules.enabled, MODULES_VANILLA.enabled);
 });
+
+// ── task 1003652: a gated project tells a stranger only what sign-in needs ──
+const express = require('express');
+const http = require('node:http');
+const buildInstanceRouter = instanceMod;
+import { strangerManifest } from '../src/bongos/routes/instance.js';
+
+const IDP = { origin: 'https://hub.example.com', client_id: 'proj-1' };
+const FULL = () => buildInstanceManifest({ branding: BRAND_OTB, modules: MODULES_OTB, rankTier: RANK_TIER, repo: REPO, authConfigured: false, openEnrollment: false, devBoxEnabled: true, idp: IDP });
+
+test('stranger manifest: schema, name, brand.project, auth (idp kept), admission — and nothing else', () => {
+  const s = strangerManifest(FULL());
+  assert.deepEqual(Object.keys(s).sort(), ['admission', 'auth', 'brand', 'name', 'schema']);
+  assert.equal(s.schema, MANIFEST_SCHEMA, '`bongos login` refuses any other schema id');
+  assert.equal(s.name, 'Example World');
+  assert.deepEqual(s.brand, { identity: { productName: 'Example World' }, project: BRAND_OTB.project },
+    'brand.project stays: the runner reads it back after a settings restart, the hub and login read it too');
+  assert.deepEqual(s.auth, { methods: AUTH_METHODS, configured: true, idp: IDP });
+  assert.deepEqual(s.admission, { policy: 'invite-only' });
+  const json = JSON.stringify(s);
+  for (const gone of ['example-owner', 'github.com', 'Straight example world', 'Hermeslines', 'drachmae', 'art-pipeline', 'Archon', 'devBox']) {
+    assert.ok(!json.includes(gone), `a stranger must not read "${gone}"`);
+  }
+});
+
+test('stranger manifest: a brand with no project policy projects none', () => {
+  const s = strangerManifest(buildInstanceManifest({ branding: BRAND_VANILLA, modules: MODULES_VANILLA, rankTier: RANK_TIER, repo: { error: 'x' }, authConfigured: false, openEnrollment: true, devBoxEnabled: false }));
+  assert.deepEqual(JSON.parse(JSON.stringify(s.brand)), { identity: { productName: 'Cloud Bongos' } });
+  assert.equal(s.admission.policy, 'open');
+});
+
+async function getInstance(deps) {
+  const app = express();
+  app.use(buildInstanceRouter({ buildManifest: FULL, ...deps }));
+  const server = http.createServer(app);
+  await new Promise((r) => server.listen(0, '127.0.0.1', r));
+  try {
+    return await new Promise((resolve, reject) => {
+      http.get({ host: '127.0.0.1', port: server.address().port, path: '/instance', agent: false }, (res) => {
+        let data = '';
+        res.on('data', (c) => { data += c; });
+        res.on('end', () => resolve({ status: res.statusCode, headers: res.headers, body: JSON.parse(data) }));
+      }).on('error', reject);
+    });
+  } finally {
+    await new Promise((r) => server.close(r));
+  }
+}
+
+test('route: an ungated project serves the full manifest and never looks the caller up', async () => {
+  let looked = 0;
+  const res = await getInstance({ isGated: () => false, resolveSession: async () => { looked += 1; return null; } });
+  assert.equal(res.status, 200);
+  assert.deepEqual(res.body, JSON.parse(JSON.stringify(FULL())));
+  assert.equal(looked, 0);
+  assert.equal(res.headers['cache-control'], undefined, 'the public answer keeps its caching');
+});
+
+test('route: gated + no session → the stranger projection, uncacheable and varied on identity', async () => {
+  const res = await getInstance({ isGated: () => true, resolveSession: async () => null });
+  assert.equal(res.status, 200, 'the manifest stays public — it is how the door gets opened');
+  assert.deepEqual(res.body, JSON.parse(JSON.stringify(strangerManifest(FULL()))));
+  assert.equal(res.headers['cache-control'], 'private, no-store');
+  assert.equal(res.headers.vary, 'Cookie, Authorization');
+});
+
+test('route: gated + a live member session → the full manifest, still uncacheable', async () => {
+  const res = await getInstance({ isGated: () => true, resolveSession: async () => ({ builder_id: 7, status: 'active' }) });
+  assert.deepEqual(res.body, JSON.parse(JSON.stringify(FULL())));
+  assert.equal(res.headers['cache-control'], 'private, no-store');
+  assert.equal(res.headers.vary, 'Cookie, Authorization');
+});
+
+test('route: gated + a deactivated session, or a lookup that fails → the stranger answer, never a 500', async () => {
+  const stranger = JSON.parse(JSON.stringify(strangerManifest(FULL())));
+  const inactive = await getInstance({ isGated: () => true, resolveSession: async () => ({ builder_id: 7, status: 'inactive' }) });
+  assert.deepEqual(inactive.body, stranger);
+  const failed = await getInstance({ isGated: () => true, resolveSession: async () => { throw new Error('db down'); } });
+  assert.equal(failed.status, 200);
+  assert.deepEqual(failed.body, stranger);
+});

package/tests/platform_visibility_gate.mjs

@@ -309,6 +309,10 @@ test('booted gated: the door, the manifest, the probes and the downloads still a
     assert.equal(m.status, 200, `${p}: the manifest stays public`);
     const j = JSON.parse(m.body);
     assert.equal(j.brand.project.platformVisibility, 'gated', 'and it carries the policy itself');
+    // …and only what sign-in needs (task 1003652)
+    assert.equal(j.modules, undefined, `${p}: a stranger is not told what the project runs`);
+    assert.equal(j.repo, undefined, `${p}: nor where its code lives`);
+    assert.equal(m.headers['cache-control'], 'private, no-store');
   }
   // the sign-in start must be reachable: it reaches the auth router (which may
   // refuse for its own reasons — a missing OAuth app — but never with the door)

package/tests/upgrade.mjs

@@ -228,7 +228,9 @@ t('full: pre-flight → pin → install → migrate → materialize → restart
     // pin is committed (task 1002712). It runs LAST — after verify — and without
     // --commit-pin it only warns, so no git add/commit/push appears here.
     ['git status --porcelain', 'npm install --no-audit --no-fund', 'npm run migrate', 'systemctl restart emersonian.service',
-      'git status --porcelain -- package.json package-lock.json']
+      'git status --porcelain -- package.json package-lock.json',
+      // task 1003926: both generators ran, so the files they rewrote are the pin commit's too
+      `git status --porcelain -- ${Object.values(u.API_ARTIFACT_FILES).flat().join(' ')}`]
   );
   // materialize pointed at the freshly-installed core
   assert.ok(materialized && materialized.coreRoot.endsWith(join('node_modules', '@bongos', 'core')));
@@ -1676,6 +1678,42 @@ t('runUpgrade: the token store is consulted only when a push is actually coming'
   }
 });
 
+// task 1003926 — the pin commit carries the files the generators that RAN rewrote, and no others.
+t('runUpgrade --commit-pin --pin-no-push: a generator that did not run contributes nothing to the pin commit', 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 calls = [];
+  const changed = ['package.json', 'package-lock.json', 'docs/api/openapi.json', 'clients/bongos-client/package.json'];
+  const run = (cmd, args) => {
+    calls.push(`${cmd} ${(args || []).join(' ')}`.trim());
+    if (cmd === 'git' && args[0] === 'status') {
+      if (!args.includes('--')) return { status: 0, stdout: '' }; // pre-flight: clean
+      const asked = args.slice(args.indexOf('--') + 1);
+      return { status: 0, stdout: changed.filter((p) => asked.includes(p)).map((p) => ` M ${p}\n`).join('') };
+    }
+    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 };
+  };
+  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, pinNoPush: true },
+    {
+      log: hush, err: hush, run, materialize: () => ({}),
+      // the client generator failed, so its files are not the upgrade's output
+      regenerateApiArtifacts: () => ({ ok: false, ran: ['gen-api-docs.js'], reason: 'gen-api-client.js exited 1' }),
+      databaseUrl: '', pgDatabase: '',
+    },
+  );
+  assert.equal(res.ok, true, `upgrade should succeed: ${res.error}`);
+  assert.equal(res.pin && res.pin.committed, true);
+  assert.ok(calls.includes('git add package.json package-lock.json docs/api/openapi.json'),
+    `got ${JSON.stringify(calls.filter((c) => c.startsWith('git add')))}`);
+  assert.ok(!calls.some((c) => c.startsWith('git push')), '--pin-no-push');
+});
+
 await Promise.all(pending);
 console.log(`\nupgrade: ${passed} passed, ${failed} failed`);
 process.exit(failed ? 1 : 0);

package/tests/upgrade_persist_pin.mjs

@@ -21,9 +21,14 @@
 import { test } from 'node:test';
 import assert from 'node:assert/strict';
 import { createRequire } from 'node:module';
+import { spawnSync } from 'node:child_process';
+import { mkdtempSync, mkdirSync, writeFileSync, readFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join, dirname } from 'node:path';
+import { API_ARTIFACT_FILES } from '../scripts/gds/upgrade.js';
 
 const require = createRequire(import.meta.url);
-const { persistPin, dirtyPinFiles, preflightDbIdentity, PIN_FILES } = require('../scripts/gds/upgrade.js');
+const { persistPin, dirtyPinFiles, preflightDbIdentity, gitTreeClean, PIN_FILES } = require('../scripts/gds/upgrade.js');
 
 // A fake `run` driven by a table of [matcher, result]. Records every invocation.
 function fakeRun(handlers = {}) {
@@ -250,3 +255,99 @@ test('dirtyPinFiles only ever reports the pin files', () => {
   const statusCall = run.calls.find((c) => c.startsWith('git status'));
   assert.match(statusCall, /--\s+package\.json package-lock\.json$/, 'pathspec-limited');
 });
+
+// ── the upgrade's own regenerated files ride the pin commit (task 1003926) ───────
+//
+// regenerateApiArtifacts rewrites the instance's TRACKED spec, reference and typed client
+// WHOLE. With only the pin committed they stayed dirty, and the next `bongos upgrade`
+// refused its clean-tree pre-flight: the stranding the pin commit exists to prevent.
+
+const ARTIFACTS = Object.values(API_ARTIFACT_FILES).flat();
+// A `git status --porcelain -- <paths>` fake that reports only what was asked AND changed.
+const statusOf = (changed) => (args) => {
+  const asked = args.slice(args.indexOf('--') + 1);
+  return { status: 0, stdout: changed.filter((p) => asked.includes(p)).map((p) => ` M ${p}\n`).join('') };
+};
+
+test('API_ARTIFACT_FILES names exactly the files the two generators write', () => {
+  const client = require('../scripts/gds/gen-api-client.js').build();
+  assert.deepEqual(API_ARTIFACT_FILES['gen-api-client.js'], Object.keys(client.files).map((f) => `clients/bongos-client/${f}`));
+  const docsSrc = readFileSync(new URL('../scripts/gds/gen-api-docs.js', import.meta.url), 'utf8');
+  assert.deepEqual(API_ARTIFACT_FILES['gen-api-docs.js'], [...docsSrc.matchAll(/\brel: '([^']+)'/g)].map((m) => m[1]));
+});
+
+test('the generated files that changed are staged and committed WITH the pin', () => {
+  const run = fakeRun({ status: statusOf([...PIN_FILES, 'docs/api/openapi.json', 'clients/bongos-client/package.json']), 'rev-parse': ON_MAIN });
+  const r = persistPin({ ...base, commitPin: true, push: false, artifactPaths: ARTIFACTS }, run, quiet, quiet);
+  assert.equal(r.committed, true);
+  assert.deepEqual(r.dirty, [...PIN_FILES, 'docs/api/openapi.json', 'clients/bongos-client/package.json']);
+  assert.ok(run.calls.includes(`git add ${PIN_FILES.join(' ')} docs/api/openapi.json clients/bongos-client/package.json`),
+    `stages the pin + only the generated files that changed; got ${JSON.stringify(run.calls)}`);
+});
+
+test('generated files that did not change add nothing to the staging argv', () => {
+  const run = fakeRun({ status: statusOf([...PIN_FILES]), 'rev-parse': ON_MAIN });
+  persistPin({ ...base, commitPin: true, push: false, artifactPaths: ARTIFACTS }, run, quiet, quiet);
+  assert.ok(run.calls.includes(`git add ${PIN_FILES.join(' ')}`));
+});
+
+test('an already-committed pin still commits the generated files the upgrade rewrote', () => {
+  const run = fakeRun({ status: statusOf(['docs/api-reference.md']), 'rev-parse': ON_MAIN });
+  const r = persistPin({ ...base, commitPin: true, push: false, artifactPaths: ARTIFACTS }, run, quiet, quiet);
+  assert.equal(r.committed, true, 'a dirty generated file alone is still the upgrade\'s to persist');
+  assert.ok(run.calls.includes(`git add ${PIN_FILES.join(' ')} docs/api-reference.md`));
+});
+
+test('a path nobody asked about is never reported, and no artifact paths means no extra git call', () => {
+  const run = fakeRun({ status: { status: 0, stdout: ' M config/branding.json\n M docs/api/openapi.json\n' }, 'rev-parse': ON_MAIN });
+  const r = persistPin({ ...base, commitPin: true, push: false, artifactPaths: ['docs/api/openapi.json'] }, run, quiet, quiet);
+  assert.deepEqual(r.dirty, ['docs/api/openapi.json'], 'config/branding.json is not the upgrade\'s to commit');
+  const bare = fakeRun({ status: DIRTY, 'rev-parse': ON_MAIN });
+  persistPin({ ...base, commitPin: true, push: false }, bare, quiet, quiet);
+  assert.equal(bare.calls.filter((c) => c.startsWith('git status')).length, 1, 'an empty pathspec would mean the WHOLE tree');
+});
+
+test('without --commit-pin, the paste-ready fix stages the changed generated files too', () => {
+  const warnings = [];
+  const run = fakeRun({ status: statusOf([...PIN_FILES, 'docs/api/openapi.json']), 'rev-parse': ON_MAIN });
+  persistPin({ ...base, commitPin: false, artifactPaths: ARTIFACTS }, run, quiet, (m) => warnings.push(m));
+  const cmd = warnings.find((w) => w.includes('git -C'));
+  assert.match(cmd, /add 'package\.json' 'package-lock\.json' 'docs\/api\/openapi\.json' &&/);
+});
+
+// Real git, no fakes: the task's done-when, reproduced on a scratch repo.
+function git(dir, ...args) { return spawnSync('git', args, { cwd: dir, encoding: 'utf8' }); }
+function put(dir, rel, content) { mkdirSync(dirname(join(dir, rel)), { recursive: true }); writeFileSync(join(dir, rel), content); }
+function scratchInstance() {
+  const dir = mkdtempSync(join(tmpdir(), 'upgrade-regen-'));
+  git(dir, 'init', '-q');
+  git(dir, 'config', 'user.email', 'upgrade-test@example.invalid');
+  git(dir, 'config', 'user.name', 'upgrade test');
+  git(dir, 'config', 'core.autocrlf', 'false');
+  for (const f of [...PIN_FILES, ...ARTIFACTS, 'config/branding.json']) put(dir, f, 'scaffold\n');
+  git(dir, 'add', '-A');
+  git(dir, 'commit', '-q', '-m', 'scaffold');
+  return dir;
+}
+// What one upgrade writes: the moved pin, and the generators' whole files.
+const upgradeWrites = (dir, version) => { for (const f of [...PIN_FILES, ...ARTIFACTS]) put(dir, f, `${version}\n`); };
+
+test('real git: two consecutive co-tenant upgrades each leave the tree clean, so the next pre-flight passes', () => {
+  const dir = scratchInstance();
+  for (const [from, to] of [['1.19.737', '1.19.745'], ['1.19.745', '1.19.746']]) {
+    assert.equal(gitTreeClean(dir).ok, true, `pre-flight before ${to}`);
+    upgradeWrites(dir, to);
+    const r = persistPin({ instanceDir: dir, fromVersion: from, toVersion: to, commitPin: true, push: false, artifactPaths: ARTIFACTS }, spawnSync, quiet, quiet);
+    assert.equal(r.committed, true, `upgrade to ${to} committed`);
+    assert.equal(git(dir, 'status', '--porcelain').stdout, '', `upgrade to ${to} leaves nothing uncommitted`);
+  }
+});
+
+test('real git: an owner edit outside the generated files is never swept into the pin commit', () => {
+  const dir = scratchInstance();
+  put(dir, 'config/branding.json', 'the owner was here\n');
+  upgradeWrites(dir, '1.19.745');
+  persistPin({ instanceDir: dir, fromVersion: '1.19.737', toVersion: '1.19.745', commitPin: true, push: false, artifactPaths: ARTIFACTS }, spawnSync, quiet, quiet);
+  assert.equal(git(dir, 'status', '--porcelain').stdout, ' M config/branding.json\n');
+  assert.ok(!git(dir, 'show', '--name-only', '--format=', 'HEAD').stdout.includes('config/branding.json'));
+});