@bongos/core 1.19.663 → 1.19.664

package/.bongos-core.json

@@ -2,22 +2,22 @@
   "artifact": "bongos-core",
   "manifest_schema": 1,
   "generator": "scripts/gds/package-core.js",
-  "core_version": "1.19.663",
-  "core_contract": "1.19.663",
-  "source_commit": "6acc4ae42df06ed3334386b6ed58fe312ae7e8a0",
+  "core_version": "1.19.664",
+  "core_contract": "1.19.664",
+  "source_commit": "22eade9fabde0d50dd8dc441b6ad82659c3925af",
   "source_ref": "HEAD",
-  "built_at": "2026-09-11T03:17:38.613Z",
+  "built_at": "2026-09-11T03:34:10.888Z",
   "redaction": {
     "model": "docs-redacted+functional-verbatim",
     "docs_redacted": 473,
     "agent_docs_stubbed": 24,
-    "functional_verbatim": 2113,
+    "functional_verbatim": 2115,
     "rules": 3,
     "gate_literals": 3,
     "gate": "passed"
   },
-  "file_count": 2610,
-  "tree_sha256": "42ab056c27124e80b07512a8787d678c3d74cef4f3b6dbeac2a248a39fa1dde8",
+  "file_count": 2612,
+  "tree_sha256": "84b0905b27f747599562fc3a649df36296c71ea7f08e863fb7f2d886bc788a6f",
   "files": [
     {
       "path": ".claude/skills/ask-for-help/SKILL.md",
@@ -2787,7 +2787,7 @@
     {
       "path": "docs/module-api-changelog.md",
       "mode": "0000644",
-      "sha256": "d5e752a541b45079b1b23eb12eeb282e6f163a676c0d9b9f122fcef2864d120f"
+      "sha256": "5e2db4fa846a72ed355864eb5df81abb6c1dc2833c239d1d6200d5b23eeb67fa"
     },
     {
       "path": "docs/modules-contract.md",
@@ -6374,6 +6374,11 @@
       "mode": "0000644",
       "sha256": "dae214682f6115b3a4e11ac3bcd120460b07c2a517155ba0b7ec690f1db9f3ea"
     },
+    {
+      "path": "modules/provisioning/credential-preflight.js",
+      "mode": "0000644",
+      "sha256": "83e174333fbe6a2e9d11b46bfd5755fbd6314b1ccd09d8b8cefb01973a69fc37"
+    },
     {
       "path": "modules/provisioning/migrations/provisioning_001_tables.sql",
       "mode": "0000644",
@@ -6492,7 +6497,7 @@
     {
       "path": "modules/provisioning/routes/provisioning.js",
       "mode": "0000644",
-      "sha256": "19dcadc78c74d7702a31fcb3d75d4c5fd45d08aab0e32c2a876668ec6dea85ec"
+      "sha256": "14fda38bbfd01404c16e48c626247cbfacd956889e25aab6c65cf1b746b5e3e7"
     },
     {
       "path": "modules/provisioning/starter-bundles.js",
@@ -7752,12 +7757,12 @@
     {
       "path": "package-lock.json",
       "mode": "0000644",
-      "sha256": "014c542d80e35f6e6a5572e169232eedf744e09bae83f6798c2d998ca86a18d5"
+      "sha256": "9f5ffaf4b6733ee29b44799f6911ccec28806c1c89a191d015e14dfa8777723a"
     },
     {
       "path": "package.json",
       "mode": "0000644",
-      "sha256": "56f59c24967d3719f7341742409c6f57ef6551dbfd9600591d201888701dc926"
+      "sha256": "51248222358e2c56acfb51ce7fab9cf83ea1750edb7aa51e2998fdfa29cae0d0"
     },
     {
       "path": "public-docs/index.html",
@@ -9512,7 +9517,7 @@
     {
       "path": "src/module-api.js",
       "mode": "0000644",
-      "sha256": "3d019bf197d89274ef460bd8b86038aca8418d5071d2d76c43479ba1743c556e"
+      "sha256": "b81fd10bc6c7db853fee7809a05275836f743a32b167778d83e9b5f40eec8fc2"
     },
     {
       "path": "src/module-loader/catalog.js",
@@ -11632,7 +11637,7 @@
     {
       "path": "tests/module_api.mjs",
       "mode": "0000644",
-      "sha256": "79b699129e16c31d3b3088e1e00d71f0d7f5b11e4b5d3627d4a2a32f8bc0ef79"
+      "sha256": "4055467ff3bb8f5bcb79a87db12a649d90545986a3f8217a743934a6a50e8b5f"
     },
     {
       "path": "tests/module_api_lazy.mjs",
@@ -12044,6 +12049,11 @@
       "mode": "0000644",
       "sha256": "74d53ae7f3c93883bdc6db5187c904cc6c641267233d70bfef1a25d5b2a4ca05"
     },
+    {
+      "path": "tests/provisioning_credential_preflight.mjs",
+      "mode": "0000644",
+      "sha256": "851e89c4b8d14030fde9ff23f710ce335498c1a215eb7d52d6a6582d4dd0a5c7"
+    },
     {
       "path": "tests/provisioning_default_domain.mjs",
       "mode": "0000644",
@@ -12067,7 +12077,7 @@
     {
       "path": "tests/provisioning_onboard_mode.mjs",
       "mode": "0000644",
-      "sha256": "97d04ee39cc06b720d4a5b42f3e3cc614f64d9462b27471a1af7598b5e2929be"
+      "sha256": "3a76bb14f9dc12ce4fff703b14a9802b1a612e726c77cfe219505743643bca9f"
     },
     {
       "path": "tests/provisioning_paid_shape_gate.mjs",

package/docs/module-api-changelog.md

@@ -1775,5 +1775,17 @@ is load-bearing: the script throws rather than guess if it is missing, and
         landed since 1.19.661 with no explicit bump. run 34553965204. (task 1002620)
   1.19.663 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
         landed since 1.19.662 with no explicit bump. run 34557840364. (task 1002620)
+  (next carrier) — grantedScopeCoversRepos re-exported (task 1002909, goal 1000106).
+        The provisioning module's create-route credential preflight must tell "that
+        repo does not exist" apart from "it is private and your pre-ADR-0155 token
+        cannot see it" — GitHub answers 404 to both — so it needs the canonical scope
+        read. Shared rather than re-implemented because `public_repo` CONTAINS the
+        substring "repo", so a naive match accepts exactly the stale token it guards
+        against. auth-config.js is KERNEL (ADR 0091 §1), so this stays inside the
+        kernel-imports-only rule; db.getGithubToken and github-repos are DOMAIN and
+        deliberately did NOT come through the doorway — the module reaches those via
+        the already-exposed `pool` + `secretBox` and its own one-field repo client.
+  1.19.664 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+        landed since 1.19.663 with no explicit bump. run 34558906002. (task 1002620)
 ---------------------------------------------------------------------------
 ```

package/modules/provisioning/credential-preflight.js

@@ -0,0 +1,170 @@
+// modules/provisioning/credential-preflight.js — does the caller hold a credential
+// that can actually stand up the repo they are adopting? (task 1002909, 1002898 N3)
+//
+// THE GAP THIS CLOSES. `POST /provisioning/instances` validated that an `adopt`
+// carried a target_ref, but never that the owner could READ it — so an API caller
+// could queue a standup that was doomed at request time and only learned about it
+// ~2 minutes later, as raw git stderr on the runner (the task-1002697 acceptance
+// walk did exactly that). The web wizard was only incidentally protected: it 403s
+// earlier on its own repo picker. The API had nothing.
+//
+// WHY IT WAITED FOR ADR 0176 (task 1002735). A preflight is only as good as its
+// definition of "usable credential", and 1002898 carved this out rather than guess
+// at one: written against the wrong definition it would either refuse valid creates
+// or keep admitting doomed ones. 1002735 settled it, so this file encodes THAT
+// definition and nothing else — what `ensurePrivateRepoAccess` (scripts/gds/
+// provision-repo.js) will demand at standup time, asked one round-trip earlier:
+//
+//   public target_ref   → any readable credential is enough. The recurring deploy
+//                         pull rides the shared SSH alias, which reads public repos
+//                         without being registered on them.
+//   private target_ref  → the runner must register a READ-ONLY deploy key on the
+//                         repo, and GitHub requires repository ADMIN for that. A
+//                         credential that can merely read a private repo is NOT
+//                         enough, and discovering that mid-standup is the loud
+//                         version of this same refusal.
+//
+// GREENFIELD IS EXEMPT, and that exemption is load-bearing (the constraint carried
+// over from 1002898): the platform CREATES that repo itself, so there is no
+// pre-existing repo for a credential to cover and nothing here to check.
+//
+// A TRANSIENT GITHUB FAILURE ADMITS. This refuses only on POSITIVE evidence that a
+// standup cannot succeed. GitHub being unreachable is not that evidence — and the
+// runner takes the same posture (`skipped: 'github_unreachable'` continues rather
+// than throwing), so a GitHub hiccup must not become an outage of project creation.
+//
+// WHY IT READS THE TOKEN ITSELF rather than calling core's db.getGithubToken /
+// github-repos.getUserRepo. `src/module-api.js` is a KERNEL file (ADR 0091 §1) and
+// may depend only on kernel files; `src/bongos/db.js` and `src/bongos/github-repos.js`
+// are domain, so routing either through the doorway fails the boundary check in
+// scripts/gds/fitness.js. Modules own their data access through the exposed `pool`
+// (the module contract's own rule), so the two small reads below are that ownership,
+// not a shortcut around it. Both are DELIBERATE TWINS of core's versions and say so;
+// `grantedScopeCoversRepos` is reached through the doorway instead of re-implemented
+// because it is kernel (src/bongos/auth-config.js) AND because its subtlety —
+// `public_repo` CONTAINS "repo", so a substring match accepts exactly the stale
+// pre-ADR-0155 token this guards against — is the kind that must never be re-typed.
+//
+// Its own file, like ../paid-shape-gate.js, for the same two mechanical reasons:
+// `routes/provisioning.js` sits at its 1500-line fitness ratchet, and every
+// dependency here is INJECTED so the check is exercisable without standing up the
+// auth stack or touching the network.
+'use strict';
+
+// Mirrors scripts/gds/provision-repo.js parseTargetRef EXACTLY. The preflight and
+// the runner must agree on what a target_ref means, or this admits refs the runner
+// cannot parse (and refuses ones it can) — a divergence that would be silent.
+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;
+}
+
+// Twin of src/bongos/db.js getGithubToken, kept in step with it deliberately (see
+// the header). Returns { token, scope } or null when there is none, it expired, or
+// the blob will not decrypt under the current master key. Unlike core's version it
+// does NOT lazily delete an expired row — a read-only preflight must not mutate, and
+// core's own reaper still runs on the endpoints that own that table.
+async function readOwnerRepoToken({ builderId }, { pool, secretBox }) {
+  if (!secretBox.isConfigured()) return null;
+  const { rows } = await pool.query(
+    `SELECT token_enc, scope, expires_at FROM github_oauth_tokens WHERE builder_id = $1`,
+    [builderId],
+  );
+  const row = rows[0];
+  if (!row) return null;
+  if (new Date(row.expires_at).getTime() <= Date.now()) return null;
+  try { return { token: secretBox.decrypt(row.token_enc), scope: row.scope }; }
+  catch { return null; }   // a blob that won't decrypt reads as "none", as in core
+}
+
+// Twin of src/bongos/github-repos.js getUserRepo, narrowed to the two fields this
+// decision needs. Throws { code } on the cases the caller branches on; every other
+// status is a transient the caller admits on.
+async function fetchRepoVisibility(token, { owner, name, fetchImpl, userAgent }) {
+  const res = await (fetchImpl || fetch)(
+    `https://api.github.com/repos/${encodeURIComponent(owner)}/${encodeURIComponent(name)}`,
+    { headers: { Authorization: `Bearer ${token}`, 'User-Agent': userAgent, Accept: 'application/vnd.github+json' } },
+  );
+  if (res.status === 401) throw Object.assign(new Error('github rejected the token'), { code: 'github_unauthorized' });
+  if (res.status === 404) throw Object.assign(new Error('repo not found'), { code: 'repo_not_found' });
+  if (!res.ok) throw Object.assign(new Error(`github ${res.status}`), { code: 'github_error' });
+  const r = await res.json();
+  return { private: !!r.private, admin: !!(r.permissions && r.permissions.admin) };
+}
+
+// adoptCredentialFault — null to ADMIT the create, or the refusal the route should
+// send: { code, status, message }. Returning a value rather than writing to `res`
+// keeps this directly testable and leaves the HTTP shape with the route that owns it.
+//
+// deps: { pool, secretBox, grantedScopeCoversRepos, userAgent, fetchImpl?,
+//         readToken?, fetchRepo? } — the last two are test seams.
+async function adoptCredentialFault({ builderId, onboardMode, targetRef }, deps) {
+  if (onboardMode !== 'adopt') return null;            // greenfield: nothing to check
+  const { grantedScopeCoversRepos, secretBox, fetchImpl, userAgent } = deps;
+  const readToken = deps.readToken || readOwnerRepoToken;
+  const fetchRepo = deps.fetchRepo || fetchRepoVisibility;
+
+  // An unparseable ref cannot be checked, and the runner's identical parse would
+  // fail on it too — so this is a doomed standup, refused for the reason it is
+  // doomed rather than admitted because the credential question never got asked.
+  const repo = parseTargetRef(targetRef);
+  if (!repo) {
+    return { code: 'bad_target_ref', status: 400,
+      message: 'Name the repository to adopt as owner/repo.' };
+  }
+
+  // No secret-box means no token can be STORED at all, so every adopt would fail at
+  // the push. 503, not 403: the fault is the server's configuration, not the caller's.
+  if (!secretBox.isConfigured()) {
+    return { code: 'github_credential_unavailable', status: 503,
+      message: 'Repo access is not configured on this server, so an existing repository cannot be adopted yet.' };
+  }
+
+  const row = await readToken({ builderId }, deps);
+  if (!row || !row.token) {
+    return { code: 'repo_scope_required', status: 403,
+      message: 'Connect your GitHub account before adopting an existing repository.' };
+  }
+
+  let info;
+  try {
+    info = await fetchRepo(row.token, { owner: repo.owner, name: repo.name, fetchImpl, userAgent });
+  } catch (e) {
+    const code = e && e.code;
+    if (code === 'github_unauthorized') {
+      return { code: 'repo_scope_required', status: 403,
+        message: 'GitHub rejected your stored credential — reconnect your GitHub account and try again.' };
+    }
+    if (code === 'repo_not_found') {
+      // A `public_repo`-scoped token cannot SEE a private repo: GitHub answers 404
+      // for "absent" and for "private and invisible to you" identically. So the
+      // message covers both honestly rather than asserting the repo does not exist —
+      // a pre-ADR-0155 token reaching its own private repo lands exactly here, which
+      // is the hermeslines-marketing failure told at request time instead of at the pull.
+      if (!grantedScopeCoversRepos(row.scope)) {
+        return { code: 'repo_scope_required', status: 403,
+          message: `We cannot see ${repo.owner}/${repo.name}. If it is private, reconnect GitHub to include your private repositories; if it is public, check the name.` };
+      }
+      return { code: 'target_repo_not_found', status: 404,
+        message: `GitHub has no repository ${repo.owner}/${repo.name} that your account can reach — check the name, or that you still have access.` };
+    }
+    return null;   // unreachable / 5xx: no positive evidence of doom, so admit
+  }
+
+  // Private repos need repository ADMIN, because the runner registers a read-only
+  // deploy key to keep the deploy pull working after the one-shot OAuth token dies
+  // (ADR 0176). Read-only collaborator access passes the read above and then fails at
+  // key registration — the exact "looked like it worked" shape this exists to end.
+  // The sentence matches the runner's own so the two can never disagree.
+  if (info.private && !info.admin) {
+    return { code: 'repo_admin_required', status: 403,
+      message: `Your GitHub account can read ${repo.owner}/${repo.name}, but adopting a private repository needs repository ADMIN so its deploy key can be registered. Ask a repository admin to raise your access, or make the repository public.` };
+  }
+
+  return null;
+}
+
+module.exports = { adoptCredentialFault, parseTargetRef, readOwnerRepoToken, fetchRepoVisibility };

package/modules/provisioning/routes/provisioning.js

@@ -14,7 +14,10 @@
 //     POST   /provisioning/instances               — request a new instance
 //                                                     (a `dedicated` shape ALSO needs
 //                                                      provisioning.fleet.manage — it is the
-//                                                      only shape that bills; ../paid-shape-gate.js)
+//                                                      only shape that bills; ../paid-shape-gate.js.
+//                                                      An `adopt` ALSO passes the credential
+//                                                      preflight — ../credential-preflight.js,
+//                                                      task 1002909; greenfield is exempt)
 //     GET    /provisioning/instances               — list the caller's instances
 //     GET    /provisioning/instances/:id           — read one of the caller's instances
 //                                                     (also SELF-HEALS its catalog projection,
@@ -49,6 +52,7 @@ const { ALWAYS_ON_CORE, OPTIONAL_MODULES, starterBundleAnswerTable, optionalModu
 const { recommendationsForDetails } = require('../recommendations');
 const { makeAskRateLimiter, clientIp } = require('../rate-limit');
 const { requireAuthorityForMeteredShape } = require('../paid-shape-gate');
+const { adoptCredentialFault } = require('../credential-preflight');
 const catalogBridge = require('../catalog-bridge');
 const { callbackPage } = require('./callback-page');
 // task 1003208: structured logging (pino via the doorway) — was console.*.
@@ -409,17 +413,18 @@ module.exports = function provisioningRoutes() {
         reason: 'adopt layers onto an existing repo, so target_ref (owner/repo) is required',
       });
     }
-    // KNOWN GAP — the credential preflight belongs HERE, and is deliberately absent.
-    // This route validates that target_ref is PRESENT but never that the owner holds a
-    // usable repo credential for it, so an API caller can queue a standup that dies
-    // ~2 minutes later in raw git stderr (the task-1002697 walk did exactly that; the
-    // web wizard is only incidentally protected because it 403s earlier). Carved out of
-    // task 1002898 as N3 and tracked by task 1002909, which is BLOCKED on task 1002735
-    // deciding what credential a private-repo standup actually needs: written against
-    // the wrong definition, a preflight would refuse valid creates or keep admitting
-    // doomed ones. Greenfield must stay exempt when it lands — the platform creates
-    // that repo itself, so there is no pre-existing repo to hold a credential for.
     try {
+      // The credential preflight (task 1002909, 1002898 N3). An `adopt` names a repo
+      // the platform must read forever, so ask ONE round-trip early whether this
+      // caller's credential can actually carry that standup — rather than queueing a
+      // doomed intent the runner discovers two minutes later as raw git stderr (the
+      // task-1002697 walk). Greenfield is exempt by construction. Encodes ADR 0176's
+      // definition of a usable credential; ../credential-preflight.js says why.
+      const credFault = await adoptCredentialFault(
+        { builderId: req.builder.id, onboardMode, targetRef: body.target_ref },
+        { pool, secretBox: api.secretBox, grantedScopeCoversRepos: api.grantedScopeCoversRepos, userAgent: api.userAgent() },
+      );
+      if (credFault) return res.fail(credFault.code, { status: credFault.status, message: credFault.message });
       // A re-request must not re-litigate the address: createInstance never updates
       // an existing row's domain, so for one the guards below could only misfire —
       // a "Try again" on a pre-existing reserved-label row, or domain_taken fired

package/package-lock.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bongos/core",
-  "version": "1.19.663",
+  "version": "1.19.664",
   "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/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.663'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
+const CORE_VERSION = '1.19.664'; // 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');
@@ -197,6 +197,20 @@ module.exports = {
   //     isConfigured/encrypt/decrypt/provisionMasterKey without reaching core.
   get secretBox() { return require('./bongos/secret-box'); },
 
+  // --- grantedScopeCoversRepos(scope) — does a scope string GitHub ACTUALLY
+  //     GRANTED still reach private repos? Exposed for the provisioning module's
+  //     create-route credential preflight (task 1002909), which must tell "that
+  //     repo does not exist" apart from "it is private and your pre-ADR-0155 token
+  //     cannot see it" — GitHub answers 404 to both.
+  //
+  //     Shared rather than re-implemented because the subtlety is a trap:
+  //     `public_repo` CONTAINS the substring "repo", so a naive match accepts
+  //     exactly the stale token this guards against. auth-config.js is KERNEL
+  //     (ADR 0091 §1), so this stays inside the kernel-imports-only rule — unlike
+  //     db.getGithubToken / github-repos, which are domain and which a module
+  //     therefore reaches via the exposed `pool` and its own client instead.
+  get grantedScopeCoversRepos() { return require('./bongos/auth-config').grantedScopeCoversRepos; },
+
   // --- KERNEL trust classifiers (ADR 0091 §1, KERNEL_FILES) — the deterministic
   //     route→rank + protected-path matchers. They are KERNEL (the trust
   //     boundary, never "called" by a domain), exposed so a module that runs the

package/tests/module_api.mjs

@@ -24,6 +24,7 @@ const PUBLISHED_SURFACE = [
   'requirePermission', // BV1.R105: the authority-atom gate module routes migrate onto (1.19.0; ADR 0151)
   'pool', 'getPool', 'instanceDbName', 'withTx', 'getBuilderById',
   'secretBox', // Gemini-key storage relocated to modules/art-pipeline + its 'art.getBuilderGeminiKeyRow' port (ADR 0102)
+  'grantedScopeCoversRepos', // the create-route credential preflight's scope read (task 1002909); kernel (auth-config.js), unlike db/github-repos which the module reaches via `pool` + its own client
   'accountExistenceReadRateLimit', // task 1003339 (ADR 0209): the shared per-IP budget both account-existence probes spend from — one instance, not a factory, so the budget is genuinely shared
   'publicProjectFeedRateLimit', // task 1002327 (ADR 0252 §5.3): the per-IP ceiling on GET /projects/featured — the platform's most expensive anonymous read (a cold call fans out to up to 500 third-party origins). One instance for the same reason as its neighbour
   'routeRankCheck', 'permissionPathCheck', // BV1.R73: kernel trust classifiers (1.6.0)

package/tests/provisioning_credential_preflight.mjs

@@ -0,0 +1,153 @@
+// tests/provisioning_credential_preflight.mjs
+//
+// The create-route credential preflight (task 1002909, 1002898 N3).
+//
+// Before this, POST /provisioning/instances checked that an `adopt` NAMED a repo but
+// never that the caller could read it, so the API admitted standups that were doomed at
+// request time and surfaced ~2 minutes later as raw git stderr on the runner (the
+// task-1002697 acceptance walk). The preflight asks ADR 0176's question one round-trip
+// early: can this builder's credential carry THIS repo's standup?
+//
+// The two properties that matter, and the two ways this can be got wrong:
+//   1. it must never refuse a create that would have SUCCEEDED (greenfield, public repos,
+//      admin-on-private, and — deliberately — a GitHub outage), and
+//   2. it must refuse the ones that cannot (no credential, stale public_repo scope on a
+//      private repo, read-only access to a private repo).
+// 1002898 carved this task out rather than guess at the definition precisely because a
+// preflight written against the wrong one fails in one of those two directions.
+//
+// DB-free and network-free: readToken and fetchRepo are injected seams.
+//
+// Run:  node tests/provisioning_credential_preflight.mjs
+
+import { strict as assert } from 'node:assert';
+import { createRequire } from 'node:module';
+
+const require = createRequire(import.meta.url);
+
+const { adoptCredentialFault, parseTargetRef } = require('../modules/provisioning/credential-preflight.js');
+// The REAL scope helper, not a stand-in: its whole point is that `public_repo` contains
+// the substring "repo", so a test double would hide the bug it exists to prevent.
+const { grantedScopeCoversRepos } = require('../src/bongos/auth-config.js');
+
+let passed = 0, failed = 0;
+async function ta(name, fn) {
+  try { await fn(); passed++; console.log(`  PASS  ${name}`); }
+  catch (e) { failed++; console.log(`  FAIL  ${name}\n        ${e.message}`); }
+}
+
+// A deps bundle with every leg stubbed; each test overrides only what it is about.
+function deps({ configured = true, token = { token: 't', scope: 'repo' }, repo = { private: false, admin: false }, throws = null } = {}) {
+  return {
+    secretBox: { isConfigured: () => configured },
+    grantedScopeCoversRepos,
+    userAgent: 'test-agent',
+    readToken: async () => token,
+    fetchRepo: async () => { if (throws) throw Object.assign(new Error('x'), { code: throws }); return repo; },
+  };
+}
+const adopt = (targetRef = 'octo-owner/demo') => ({ builderId: 7, onboardMode: 'adopt', targetRef });
+
+// ── the exemption that is load-bearing ──────────────────────────────────────────
+
+await ta('greenfield is EXEMPT — the platform creates that repo, so nothing is checked', async () => {
+  // Asserted via the seams: a greenfield create must not even read the token, or a
+  // builder with no GitHub connection could no longer make a fresh project at all.
+  let touched = false;
+  const d = deps();
+  d.readToken = async () => { touched = true; return null; };
+  assert.equal(await adoptCredentialFault({ builderId: 7, onboardMode: 'greenfield', targetRef: null }, d), null);
+  assert.equal(touched, false, 'greenfield must not consult the credential at all');
+});
+
+// ── the refusals ────────────────────────────────────────────────────────────────
+
+await ta('no stored credential → 403 repo_scope_required, and the message says what to do', async () => {
+  const f = await adoptCredentialFault(adopt(), deps({ token: null }));
+  assert.equal(f.code, 'repo_scope_required');
+  assert.equal(f.status, 403);
+  assert.match(f.message, /Connect your GitHub account/);
+});
+
+await ta('secret-box unconfigured → 503, not 403 — the fault is the server config, not the caller', async () => {
+  const f = await adoptCredentialFault(adopt(), deps({ configured: false }));
+  assert.equal(f.code, 'github_credential_unavailable');
+  assert.equal(f.status, 503);
+});
+
+await ta('THE HERMESLINES SHAPE: a stale public_repo token 404ing on a private repo re-prompts for scope', async () => {
+  // GitHub answers 404 identically for "absent" and "private and invisible to you", so a
+  // pre-ADR-0155 token reaching its owner's own private repo lands here. Asserting the
+  // repo does not exist would be a lie; the message must offer both readings.
+  const f = await adoptCredentialFault(adopt(), deps({ token: { token: 't', scope: 'public_repo,read:user' }, throws: 'repo_not_found' }));
+  assert.equal(f.code, 'repo_scope_required');
+  assert.equal(f.status, 403);
+  assert.match(f.message, /private/i);
+  assert.match(f.message, /reconnect/i);
+});
+
+await ta('a repo-scoped token that still 404s → 404 target_repo_not_found (it really is absent)', async () => {
+  const f = await adoptCredentialFault(adopt(), deps({ token: { token: 't', scope: 'repo' }, throws: 'repo_not_found' }));
+  assert.equal(f.code, 'target_repo_not_found');
+  assert.equal(f.status, 404);
+});
+
+await ta('private repo WITHOUT admin → 403: the runner could read it and then fail registering the deploy key', async () => {
+  const f = await adoptCredentialFault(adopt(), deps({ repo: { private: true, admin: false } }));
+  assert.equal(f.code, 'repo_admin_required');
+  assert.equal(f.status, 403);
+  assert.match(f.message, /ADMIN/);
+});
+
+await ta('a rejected token → 403 telling the caller to reconnect, not a raw 401', async () => {
+  const f = await adoptCredentialFault(adopt(), deps({ throws: 'github_unauthorized' }));
+  assert.equal(f.code, 'repo_scope_required');
+  assert.match(f.message, /reconnect/i);
+});
+
+await ta('an unparseable target_ref is refused for THAT reason, not admitted unchecked', async () => {
+  const f = await adoptCredentialFault(adopt('not a repo ref!!'), deps());
+  assert.equal(f.code, 'bad_target_ref');
+  assert.equal(f.status, 400);
+});
+
+// ── the admissions (the half a bad preflight breaks) ────────────────────────────
+
+await ta('public repo + any readable credential → ADMITTED, admin irrelevant', async () => {
+  // The deploy pull rides the shared SSH alias for a public repo, so no deploy key and
+  // therefore no admin is needed. Demanding admin here would refuse valid creates.
+  assert.equal(await adoptCredentialFault(adopt(), deps({ repo: { private: false, admin: false } })), null);
+});
+
+await ta('private repo WITH admin → ADMITTED — this is exactly what ADR 0176 needs', async () => {
+  assert.equal(await adoptCredentialFault(adopt(), deps({ repo: { private: true, admin: true } })), null);
+});
+
+await ta('GitHub unreachable → ADMITTED, matching the runner: an outage must not stop project creation', async () => {
+  // No positive evidence of doom. The runner takes the same posture
+  // (ensurePrivateRepoAccess returns skipped:'github_unreachable' rather than throwing),
+  // so refusing here would turn a GitHub hiccup into an outage of the create route.
+  assert.equal(await adoptCredentialFault(adopt(), deps({ throws: 'github_error' })), null);
+});
+
+// ── the parse must not drift from the runner's ──────────────────────────────────
+
+await ta('parseTargetRef accepts every form the runner accepts, and rejects what it rejects', async () => {
+  // A divergence from scripts/gds/provision-repo.js parseTargetRef would be silent: this
+  // would admit refs the runner cannot parse, or refuse ones it can.
+  for (const ref of ['octo-owner/demo', 'git@github.com:octo-owner/demo.git', 'https://github.com/octo-owner/demo', 'https://github.com/octo-owner/demo.git']) {
+    assert.deepEqual(parseTargetRef(ref), { owner: 'octo-owner', name: 'demo' }, `should parse ${ref}`);
+  }
+  for (const ref of ['', null, 'demo', 'a/b/c', 'not a repo ref!!']) {
+    assert.equal(parseTargetRef(ref), null, `should reject ${JSON.stringify(ref)}`);
+  }
+});
+
+await ta('the real scope helper is used, so public_repo never passes as repo', async () => {
+  // The trap this guards: 'public_repo'.includes('repo') is true.
+  assert.equal(grantedScopeCoversRepos('public_repo,read:user'), false);
+  assert.equal(grantedScopeCoversRepos('repo'), true);
+});
+
+console.log(`\nprovisioning_credential_preflight: ${passed} passed, ${failed} failed`);
+process.exit(failed ? 1 : 0);

package/tests/provisioning_onboard_mode.mjs

@@ -101,6 +101,19 @@ provisioning.getInstanceBySlug = async () => null;
 const api = require('../src/module-api.js');
 api.requireBuilder = (req, _res, next) => { req.builder = { id: 7, github_login: 'owner' }; next(); };
 
+// An `adopt` create now also passes the credential preflight (task 1002909), which is a
+// REAL precondition and not test scaffolding: the route refuses a standup whose owner
+// holds no usable credential for the repo it is about to queue a push to. So give this
+// harness a passing one — a `repo`-scoped token over a PUBLIC repo, the cheapest shape
+// that admits — and leave the preflight's own branch matrix to
+// tests/provisioning_credential_preflight.mjs, which owns it.
+api.secretBox = { isConfigured: () => true };
+api.pool = {
+  query: async () => ({ rows: [{ token_enc: 'enc', scope: 'repo', expires_at: new Date(Date.now() + 3600e3) }] }),
+};
+api.secretBox.decrypt = () => 'tok';
+globalThis.fetch = async () => ({ status: 200, ok: true, json: async () => ({ private: false, permissions: { admin: true } }) });
+
 const express = require('express');
 const provisioningRoutes = require('../modules/provisioning/routes/provisioning.js');
 const app = express();