@bongos/core 1.19.662 → 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.662",
-  "core_contract": "1.19.662",
-  "source_commit": "29f8be216571b2ec145cab49a5a7c230c79270a0",
+  "core_version": "1.19.664",
+  "core_contract": "1.19.664",
+  "source_commit": "22eade9fabde0d50dd8dc441b6ad82659c3925af",
   "source_ref": "HEAD",
-  "built_at": "2026-09-11T02:16:53.563Z",
+  "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": "c1546f9ff797a30c5dff74fa40f96d201e25291c3bb8061ca8aae6ff845e1d6f",
+  "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": "6551b2dbf9ed520f152e8aa2ddc2888dcaae6c4f96d4babf71059fb1550f9ca6"
+      "sha256": "5e2db4fa846a72ed355864eb5df81abb6c1dc2833c239d1d6200d5b23eeb67fa"
     },
     {
       "path": "docs/modules-contract.md",
@@ -5647,7 +5647,7 @@
     {
       "path": "modules/lifecycle/db-claims.js",
       "mode": "0000644",
-      "sha256": "23ed6051b8b9283410f23e10862b6b65361cbf2f95489cd1fc50dfd4584f5c71"
+      "sha256": "1b0d394ee1788decd9ea713a4379ef5322eda28a2ac11ad7adaf68298e6f4075"
     },
     {
       "path": "modules/lifecycle/db-deps-criteria.js",
@@ -5672,7 +5672,7 @@
     {
       "path": "modules/lifecycle/db-rank-authz.js",
       "mode": "0000644",
-      "sha256": "e5feff1eb42ad631b6c0165c23224d8ac56ef7f40e5d238afb09013501e9db7c"
+      "sha256": "fb8180f875828664fcd5cb17aa39f68c70b6cea3c52d03fdbd0b3e835f8b1e64"
     },
     {
       "path": "modules/lifecycle/db-shared.js",
@@ -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": "7eb2f5389815f661c90a4c42111d3caf64a5ede4977a66caf27baf2edd10a59f"
+      "sha256": "9f5ffaf4b6733ee29b44799f6911ccec28806c1c89a191d015e14dfa8777723a"
     },
     {
       "path": "package.json",
       "mode": "0000644",
-      "sha256": "eb2e51ad62585ffd964894ae722d41e98372978ac8a58456efa28b945a21c4b1"
+      "sha256": "51248222358e2c56acfb51ce7fab9cf83ea1750edb7aa51e2998fdfa29cae0d0"
     },
     {
       "path": "public-docs/index.html",
@@ -9512,7 +9517,7 @@
     {
       "path": "src/module-api.js",
       "mode": "0000644",
-      "sha256": "c273737ee3e60e60268081525c1bc144940583038cd23c1779a3671a39444a93"
+      "sha256": "b81fd10bc6c7db853fee7809a05275836f743a32b167778d83e9b5f40eec8fc2"
     },
     {
       "path": "src/module-loader/catalog.js",
@@ -10857,7 +10862,7 @@
     {
       "path": "tests/government_claim_eligibility.mjs",
       "mode": "0000644",
-      "sha256": "1989a7e5e39a6bb177dfd86e610c0806c96fdc97f9149800de431af816f2c31a"
+      "sha256": "05a7c8f8d001bd0d2950619fb46f242d358ecae1a8901a10fbb9ecc7857500e7"
     },
     {
       "path": "tests/government_config.mjs",
@@ -10902,7 +10907,7 @@
     {
       "path": "tests/government_ownership_scope.mjs",
       "mode": "0000644",
-      "sha256": "bdcb0266f38c50b0e3085271bdec4fbe726c32c8af1052104703d0afa7e89d52"
+      "sha256": "76b81db7769290d5ef5c26ece86ce0610c5aef6c8984ffdd54a6340db66db3bc"
     },
     {
       "path": "tests/government_page_gates.mjs",
@@ -10922,7 +10927,7 @@
     {
       "path": "tests/government_protected_surfaces.mjs",
       "mode": "0000644",
-      "sha256": "cd56facc3522f17cd83b067ee1ae9dcb3e4e03dac13157013c44d7ba23508af2"
+      "sha256": "3517e05c1264fbdbeadc533884942926689952c8995548863ca1cfbfc365428e"
     },
     {
       "path": "tests/government_rank_sync.mjs",
@@ -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

@@ -1773,5 +1773,19 @@ is load-bearing: the script throws rather than guess if it is missing, and
         landed since 1.19.660 with no explicit bump. run 34552525938. (task 1002620)
   1.19.662 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
         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/lifecycle/db-claims.js

@@ -15,10 +15,15 @@ const { pool, withTx } = api;
 const log = api.logger('lifecycle');
 const seams = api;
 const { touchesOverlap } = api.pathMatch;
-const { claimEligibilityAllows, CLAIM_ANY, CLAIM_NEWCOMER } = require('./claim-eligibility.js');
+// CLAIM_ANY / CLAIM_NEWCOMER name the two atoms in the refusal message. The
+// decision itself moved to db-rank-authz.claimGate (task 1003196), so this file
+// no longer calls claimEligibilityAllows / rankAllowsTask / xenosClaimAllowed
+// directly — composing them at three separate call sites is what made the gate
+// un-testable except by counting.
+const { CLAIM_ANY, CLAIM_NEWCOMER } = require('./claim-eligibility.js');
 const { goalMembershipFailures } = require('./claim-feed.js');
 const { unsatisfiedDeps } = require('./db-deps-criteria.js');
-const { claimPermissionsFor, disambiguateWorktreeName, foldWorktreeName, rankAllowsTask, xenosClaimAllowed } = require('./db-rank-authz.js');
+const { claimGate, claimPermissionsFor, disambiguateWorktreeName, foldWorktreeName } = require('./db-rank-authz.js');
 const { sealSessionLog } = require('./db-shared.js');
 const { needsRebaseTasksForBuilder, shouldRefuseClaimResolve } = require('./db-ship.js');
 const { REWARD_SUGGESTION_CAP, rewardGateAssignment } = require('./db-tasks.js');
@@ -142,8 +147,18 @@ async function claimTask({ taskId, builderId, worktreeName, headSha, creatorSess
     // is kept as an alias on the error object for callers on the pre-rename
     // release. BV1.R106 (ADR 0151): same rule, now decided on the PERMISSIONS
     // task.claim.any / task.claim.newcomer — see ./claim-eligibility.js.
+    // task 1003196: the queue+floor composition is decided ONCE, in
+    // db-rank-authz.claimGate, so a test can drive the real decision instead of
+    // counting `if`s in this file. The refusal SHAPES below are unchanged — that
+    // is why claimGate returns which gates refused rather than an error object.
     const newcomerFriendly = task.newcomer_friendly;
-    if (!claimEligibilityAllows({ heldPermissions, newcomerFriendly, rankRuleAllows: xenosClaimAllowed(builderRank, newcomerFriendly) })) {
+    const claimRefusals = claimGate({
+      builderRank,
+      newcomerFriendly,
+      requiresRank: task.requires_rank,
+      heldPermissions,
+    });
+    if (claimRefusals.includes('queue')) {
       // task 1002613 (map §4.4): the bare code reported a PERMISSION decision as
       // a rank one — no axis, no remedy. Copy INSUFFICIENT_RANK's shape below:
       // name both sides of the wall and the way forward.
@@ -168,7 +183,7 @@ async function claimTask({ taskId, builderId, worktreeName, headSha, creatorSess
     // blocks Xenos+Metic. The DB CHECK on tasks.requires_rank enforces the
     // enum, so we trust the value here. INSUFFICIENT_RANK carries the actual
     // and required ranks so the caller can render a clean error.
-    if (!rankAllowsTask(builderRank, task.requires_rank)) {
+    if (claimRefusals.includes('floor')) {
       throw {
         code: 'INSUFFICIENT_RANK',
         required: task.requires_rank,
@@ -496,25 +511,32 @@ async function claimTasksBatch({ taskIds, builderId, worktreePrefix, creatorSess
     // never checked here, while claimTask checks every rank), so removing it would
     // change who can batch-claim. That pre-existing asymmetry is reported, not
     // fixed, under this task — closing it is an authority decision of its own.
-    if (builderRank === 'xenos') {
-      for (const t of taskRows) {
-        if (!claimEligibilityAllows({
-          heldPermissions,
-          newcomerFriendly: t.newcomer_friendly,
-          rankRuleAllows: xenosClaimAllowed(builderRank, t.newcomer_friendly),
-        })) {
-          failures.push({ task_id: t.id, reason: 'rank_too_low_for_task', legacy_reason: 'XENOS_RESTRICTED' });
-        }
+    //
+    // V3.R82 (#301): the per-task requires_rank floor rides the same decision.
+    // Mirrors the single claimTask gate so a Metic can't slip through batch-claim
+    // to grab an Archon-only task. The xenos sandbox check handles the xenos case
+    // exhaustively for requires_rank='xenos' (the default); the floor gate refuses
+    // requires_rank='metic'/'archon' when the builder is below.
+    //
+    // task 1003196: both gates now come from db-rank-authz.claimGate. A row can
+    // still collect BOTH refusals, and the two passes below are deliberate — this
+    // path groups every queue refusal ahead of every floor refusal, and `failures`
+    // is returned to the caller in order, so folding them into one pass per row
+    // would reorder a response for no reason.
+    const refusalsFor = (t) => claimGate({
+      builderRank,
+      newcomerFriendly: t.newcomer_friendly,
+      requiresRank: t.requires_rank,
+      heldPermissions,
+      queueGateApplies: builderRank === 'xenos',
+    });
+    for (const t of taskRows) {
+      if (refusalsFor(t).includes('queue')) {
+        failures.push({ task_id: t.id, reason: 'rank_too_low_for_task', legacy_reason: 'XENOS_RESTRICTED' });
       }
     }
-
-    // V3.R82 (#301): the per-task requires_rank floor. Mirrors the single
-    // claimTask gate so a Metic can't slip through batch-claim to grab an
-    // Archon-only task. The xenos sandbox check above handles the xenos case
-    // exhaustively for requires_rank='xenos' (the default); this gate refuses
-    // requires_rank='metic'/'archon' when the builder is below.
     for (const t of taskRows) {
-      if (!rankAllowsTask(builderRank, t.requires_rank)) {
+      if (refusalsFor(t).includes('floor')) {
         failures.push({
           task_id: t.id,
           reason: 'INSUFFICIENT_RANK',
@@ -855,14 +877,19 @@ async function validateClaimBatch({ taskIds, builderId }) {
     const t = byId.get(id);
     if (!t) { push(id, { reason: 'TASK_NOT_FOUND' }); continue; }
     if (t.status !== 'ready') push(id, { reason: 'TASK_NOT_READY', currentStatus: t.status });
-    if (builderRank === 'xenos' && !claimEligibilityAllows({
-      heldPermissions,
+    // task 1003196: same composed decision as claimTask and claimTasksBatch, and
+    // the same deliberate xenos-only queue short-circuit the batch path carries.
+    const refusals = claimGate({
+      builderRank,
       newcomerFriendly: t.newcomer_friendly,
-      rankRuleAllows: xenosClaimAllowed(builderRank, t.newcomer_friendly),
-    })) {
+      requiresRank: t.requires_rank,
+      heldPermissions,
+      queueGateApplies: builderRank === 'xenos',
+    });
+    if (refusals.includes('queue')) {
       push(id, { reason: 'rank_too_low_for_task', legacy_reason: 'XENOS_RESTRICTED' });
     }
-    if (!rankAllowsTask(builderRank, t.requires_rank)) {
+    if (refusals.includes('floor')) {
       push(id, { reason: 'INSUFFICIENT_RANK', required: t.requires_rank, actual: builderRank });
     }
   }

package/modules/lifecycle/db-rank-authz.js

@@ -14,6 +14,7 @@ const api = require('../../src/module-api');
 const { pool, LIVE_RANK_LADDER, RANK_TIER } = api;
 const seams = api;
 const { matchProtected } = api.permissionPathCheck;
+const { claimEligibilityAllows } = require('./claim-eligibility.js');
 
 // -------------------------------------------------------------------------
 // Builders
@@ -166,6 +167,51 @@ function rankAllowsTask(builderRank, requiredRank) {
   return have >= needed;
 }
 
+// ── the COMPOSED per-task claim decision (task 1003196) ──────────────────────
+//
+// Claim eligibility is TWO independent gates — the QUEUE axis (permission atoms,
+// ./claim-eligibility.js) and the FLOOR axis (`requires_rank`, rankAllowsTask
+// above) — and the rule that matters is that BOTH must pass and neither
+// substitutes for the other. That composition used to exist only as a pair of
+// consecutive `if`s repeated at each of the three claim paths, which meant the
+// only thing a test could check was that the source still CONTAINED them:
+// `tests/government_claim_eligibility.mjs` counted occurrences, and neutering
+// claimTask's gate with `&& false` left the count at 3 and the suite green
+// (finding 10 of the task-1002671 verification). Counting is not a behaviour
+// oracle, so the decision lives here, once, where a test can actually drive it.
+//
+// RETURNS THE GATES THAT REFUSED, in ladder order — `[]` means allowed. It
+// deliberately does NOT return a ready-made error: each call site shapes its own
+// refusal and those shapes are API surface (claimTask THROWS
+// `{code:'rank_too_low_for_task', …, message, hint}`, while the batch paths PUSH
+// `{task_id, reason, legacy_reason}` and accumulate both refusals for one row).
+// Returning a decision instead of a wire error is what lets all three delegate
+// without any of them changing what a caller sees.
+//
+// `queueGateApplies` carries a PRE-EXISTING asymmetry rather than quietly fixing
+// it: claimTask runs the queue gate for every rank, while claimTasksBatch and
+// validateClaimBatch run it only when `builderRank === 'xenos'`. That outer
+// short-circuit is semantic, not a fast path — for the SEEDED sets the two agree
+// exactly (thetes+ all hold task.claim.any), but a custom rank granted neither
+// claim atom would be refused by claimTask and admitted by the batch paths.
+// Closing that is an authority decision of its own, already reported and
+// deliberately deferred at the call site; this parameter keeps each path's
+// current meaning exact while still routing it through one decision.
+const CLAIM_GATES = Object.freeze(['queue', 'floor']);
+
+function claimGate({ builderRank, newcomerFriendly, requiresRank, heldPermissions, queueGateApplies = true }) {
+  const refused = [];
+  if (queueGateApplies && !claimEligibilityAllows({
+    heldPermissions,
+    newcomerFriendly,
+    rankRuleAllows: xenosClaimAllowed(builderRank, newcomerFriendly),
+  })) {
+    refused.push('queue');
+  }
+  if (!rankAllowsTask(builderRank, requiresRank)) refused.push('floor');
+  return Object.freeze(refused);
+}
+
 // deriveRequiredRank — task 1498 / ADR 0084. The per-task requires_rank floor
 // (V3.R82 #301) shipped INERT: no create/edit path ever set it, so every task
 // sat at the 'xenos' default and the claim gate never bit. We now DERIVE a floor
@@ -477,6 +523,8 @@ module.exports = {
   RANKS,
   REQUIRES_RANK_TIER,
   THETES_GRADUATION_THRESHOLD,
+  CLAIM_GATES,
+  claimGate,
   claimPermissionsFor,
   countShippedTasksForBuilder,
   deriveRequiredRank,

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.662",
+  "version": "1.19.664",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@bongos/core",
-      "version": "1.19.662",
+      "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.662",
+  "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.662'; // 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/government_claim_eligibility.mjs

@@ -154,16 +154,138 @@ test('the permission predicate cannot see requires_rank at all (structural)', ()
   }
 });
 
-test('every claim path in db.js still gates on requires_rank as its own check', () => {
-  // task 1003204: the lifecycle data layer is db.js + db-*.js now — read the family.
-  const src = lifecycleDbSource();
-  // claimTask, claimTasksBatch, validateClaimBatch — three call sites, three
-  // separate rankAllowsTask conjuncts. If a refactor ever folds the floor into the
-  // permission predicate, this count drops and the test reds.
-  const floorChecks = src.match(/rankAllowsTask\((builderRank|builderRank), (task|t)\.requires_rank\)/g) || [];
-  assert.equal(floorChecks.length, 3, `expected 3 requires_rank gates in the claim paths, found ${floorChecks.length}`);
-  const queueChecks = src.match(/claimEligibilityAllows\(\{/g) || [];
-  assert.equal(queueChecks.length, 3, `expected 3 permission-expressed queue gates, found ${queueChecks.length}`);
+// ── the COMPOSED gate, driven behaviourally (task 1003196, finding 10) ───────
+//
+// WHAT THIS REPLACED, AND WHY. Until task 1003196 this section grepped the
+// lifecycle source for three occurrences of `rankAllowsTask(builderRank,
+// t.requires_rank)` and three of `claimEligibilityAllows({`. That verifies
+// PRESENCE, not EFFECT: neutering claimTask's gate with `&& false` left both
+// counts at 3 and the suite green. The composition now lives in one pure export,
+// db-rank-authz.claimGate, so these tests drive the real decision instead.
+//
+// claimGate returns the gates that REFUSED, in ladder order — `[]` means allowed.
+
+const { claimGate, CLAIM_GATES } = rankAuthz;
+const gatesFor = (o) => [...claimGate(o)];
+
+test('claimGate: BOTH axes must pass, and neither substitutes for the other', () => {
+  // An Archon holding everything is still stopped by nothing at requires_rank xenos...
+  assert.deepEqual(gatesFor({
+    builderRank: 'archon', newcomerFriendly: false, requiresRank: 'xenos', heldPermissions: seedSet('archon'),
+  }), []);
+
+  // ...and a builder who clears the QUEUE axis is still refused by the FLOOR axis.
+  // This is the collapse the two-gate model exists to prevent: holding
+  // task.claim.any must not buy you an archon-floored task.
+  assert.deepEqual(gatesFor({
+    builderRank: 'metic', newcomerFriendly: false, requiresRank: 'archon', heldPermissions: seedSet('metic'),
+  }), ['floor']);
+
+  // The converse: clearing the FLOOR axis does not buy you the queue. A xenos on a
+  // default-floor task that is NOT newcomer_friendly holds only task.claim.newcomer.
+  assert.deepEqual(gatesFor({
+    builderRank: 'xenos', newcomerFriendly: false, requiresRank: 'xenos', heldPermissions: seedSet('xenos'),
+  }), ['queue']);
+
+  // Both can refuse the same row, and the order is the ladder order.
+  assert.deepEqual(gatesFor({
+    builderRank: 'xenos', newcomerFriendly: false, requiresRank: 'archon', heldPermissions: seedSet('xenos'),
+  }), ['queue', 'floor']);
+
+  // ...and a newcomer_friendly flag opens the queue without lowering the floor.
+  assert.deepEqual(gatesFor({
+    builderRank: 'xenos', newcomerFriendly: true, requiresRank: 'metic', heldPermissions: seedSet('xenos'),
+  }), ['floor'], 'newcomer_friendly must never lower requires_rank');
+});
+
+test('claimGate: the composed decision matches the two axes evaluated separately', () => {
+  // The independent oracle: each axis run through its OWN production predicate
+  // (db.rankAllowsTask and eligibility.claimEligibilityAllows), composed here in
+  // the test. A claimGate that silently dropped a conjunct disagrees immediately.
+  let refusalsSeen = 0;
+  for (const rank of LIVE_RANKS) {
+    for (const nf of NF_VALUES) {
+      for (const requiresRank of [...LIVE_RANKS, null]) {
+        for (const held of [seedSet(rank), new Set(), new Set([CLAIM_ANY]), new Set([CLAIM_NEWCOMER]), null]) {
+          const expected = [];
+          if (!claimEligibilityAllows({
+            heldPermissions: held, newcomerFriendly: nf, rankRuleAllows: db.xenosClaimAllowed(rank, nf),
+          })) expected.push('queue');
+          if (!db.rankAllowsTask(rank, requiresRank)) expected.push('floor');
+          refusalsSeen += expected.length;
+          assert.deepEqual(
+            gatesFor({ builderRank: rank, newcomerFriendly: nf, requiresRank, heldPermissions: held }),
+            expected,
+            `${rank}/nf=${String(nf)}/req=${String(requiresRank)}/held=${held ? [...held].length : 'null'}`,
+          );
+        }
+      }
+    }
+  }
+  assert.ok(refusalsSeen > 0, 'a matrix that never refuses would pass vacuously');
+});
+
+test('claimGate: fail-closed on ranks and floors it does not recognise', () => {
+  // An unknown rank clears nothing — the posture rankAllowsTask already takes.
+  assert.ok(gatesFor({
+    builderRank: 'bogus', newcomerFriendly: true, requiresRank: 'xenos', heldPermissions: new Set([CLAIM_ANY]),
+  }).includes('floor'), 'an unrecognised builder rank must not clear the floor');
+  // A requires_rank the DB CHECK should have blocked refuses rather than defaults.
+  assert.ok(gatesFor({
+    builderRank: 'archon', newcomerFriendly: true, requiresRank: 'nonsense', heldPermissions: seedSet('archon'),
+  }).includes('floor'), 'an unrecognised requires_rank must fail closed');
+  // A null requires_rank is the column default — no extra gate.
+  assert.deepEqual(gatesFor({
+    builderRank: 'xenos', newcomerFriendly: true, requiresRank: null, heldPermissions: seedSet('xenos'),
+  }), []);
+});
+
+test('claimGate: queueGateApplies carries the batch paths\' pre-existing asymmetry', () => {
+  // claimTask runs the queue gate for EVERY rank; claimTasksBatch and
+  // validateClaimBatch run it only when builderRank === 'xenos'. For the SEEDED
+  // sets the two agree exactly, which is why the asymmetry has never bitten...
+  for (const rank of LIVE_RANKS) {
+    for (const nf of NF_VALUES) {
+      const held = seedSet(rank);
+      assert.deepEqual(
+        gatesFor({ builderRank: rank, newcomerFriendly: nf, requiresRank: 'xenos', heldPermissions: held }),
+        gatesFor({ builderRank: rank, newcomerFriendly: nf, requiresRank: 'xenos', heldPermissions: held, queueGateApplies: rank === 'xenos' }),
+        `${rank}/nf=${String(nf)}: seeded sets must agree across both call-site flavours`,
+      );
+    }
+  }
+  // ...and here is the case where they DIVERGE, pinned so it stays a known,
+  // deliberate difference rather than a surprise: a CUSTOM rank granted neither
+  // claim atom is refused by claimTask and admitted by the batch paths. Closing
+  // this is an authority decision of its own (see the note at the call site).
+  const neither = new Set(['cost.log']);
+  assert.deepEqual(gatesFor({
+    builderRank: 'metic', newcomerFriendly: false, requiresRank: 'xenos', heldPermissions: neither,
+  }), ['queue'], 'claimTask refuses a rank holding no claim atom');
+  assert.deepEqual(gatesFor({
+    builderRank: 'metic', newcomerFriendly: false, requiresRank: 'xenos', heldPermissions: neither, queueGateApplies: false,
+  }), [], 'the batch paths admit it — the asymmetry, recorded');
+});
+
+test('every claim path delegates to claimGate rather than re-composing the axes', () => {
+  // The cheap STRUCTURAL complement to the behavioural tests above. It can still
+  // only see presence, so it is no longer the only thing standing: what it adds is
+  // that a call site cannot quietly go back to composing the gates itself, which
+  // is what let the three copies drift apart in the first place.
+  // Counted in db-claims.js alone: the whole-family source also carries the
+  // DEFINITION in db-rank-authz.js, which would make the count read 4 and quietly
+  // tolerate one call site dropping out.
+  const claims = fs.readFileSync(path.join(LIFECYCLE, 'db-claims.js'), 'utf8');
+  const delegations = claims.match(/claimGate\(\{/g) || [];
+  assert.equal(delegations.length, 3,
+    `claimTask, claimTasksBatch and validateClaimBatch must each call claimGate — found ${delegations.length}`);
+  // ...and the raw conjuncts are gone from the claim paths, so there is exactly
+  // one place where "both gates must pass" is written down.
+  for (const banned of ['rankAllowsTask(', 'claimEligibilityAllows(']) {
+    assert.ok(!claims.includes(banned),
+      `db-claims.js must reach the axes through claimGate, not call "${banned}" itself`);
+  }
+  assert.deepEqual([...CLAIM_GATES], ['queue', 'floor'], 'the gate names are ladder-ordered');
 });
 
 // ── the "authority could not be established" fallback ────────────────────────

package/tests/government_ownership_scope.mjs

@@ -551,15 +551,25 @@ test('F8: the verb field itself is partitioned with scope and checked against th
 
 // ═══ G — the R94/R95/R98 invariants this slice must not have disturbed ════════
 
-test('G1: the seed is still floor-derived and cumulative — the ownership axis adds no grants', () => {
+test('G1: RANK_SEED is still DERIVED from seedForRank, not hand-maintained', () => {
+  // task 1003196 (finding 8) trimmed this test, and it is worth saying exactly what
+  // it does and does not prove. It USED to re-spell seedForRank's formula
+  // (`floor !== null && RANK_ORDER.indexOf(p.floor) <= tier`) and assert it against
+  // RANK_SEED — but RANK_SEED is BUILT by seedForRank, so the two sides moved
+  // together: the copy could detect drift from the other copies of itself and never
+  // a wrong formula. That formula oracle is kept ONCE, in tests/government_catalog.mjs
+  // ("a role holds a permission iff its floor is a real rank at-or-below"), with the
+  // real independent oracles being government_parity.mjs Part A and the pinned
+  // concrete values beside it.
+  //
+  // What survives here is narrow and genuine: RANK_SEED must remain a DERIVATION.
+  // The catalog's "zero day-one change" guarantee (R103) is structural only while
+  // the seed is computed from floors — the day someone replaces RANK_SEED with a
+  // hand-written list, parity stops being a property of the code and becomes a
+  // promise someone has to keep by hand. That is what this catches.
   for (const rank of RANK_ORDER) {
-    const held = new Set(RANK_SEED[rank]);
-    const tier = RANK_ORDER.indexOf(rank);
-    for (const p of PERMISSIONS) {
-      assert.equal(held.has(p.key), p.floor !== null && RANK_ORDER.indexOf(p.floor) <= tier,
-        `${rank} vs ${p.key}: scope must not touch the floor derivation`);
-    }
-    assert.deepEqual([...seedForRank(rank)].sort(), [...RANK_SEED[rank]].sort());
+    assert.deepEqual([...seedForRank(rank)].sort(), [...RANK_SEED[rank]].sort(),
+      `${rank}: RANK_SEED must be what seedForRank computes, never a maintained copy`);
   }
 });
 

package/tests/government_protected_surfaces.mjs

@@ -214,11 +214,89 @@ test('every entry maps to a permission the catalog defines as system:true', () =
   assert.deepEqual(registry.SYSTEM_PERMISSIONS, ['path.protected.modify']);
 });
 
-test('a surface mapped to a grantable or unknown permission fails loud', () => {
-  // The guard must actually catch a bad mapping, not pass vacuously.
+// Feed a BAD registry through the real loader in a cold subprocess and assert the
+// module refuses to load. The pattern is the sibling probe below ("a missing
+// registry fails CLOSED"): patch fs.readFileSync for the registry path only, then
+// require the module under test and let its load-time throw be the result.
+//
+// WHY A SUBPROCESS AND NOT AN IN-PROCESS ASSERTION (task 1003196, finding 9). The
+// version of this test before that task read the catalog and checked that a
+// grantable key exists and an unknown key returns null — both true regardless of
+// whether the guard exists. Demonstrated: deleting the whole validation loop from
+// modules/government/protected-surfaces.js left the entire suite green. The guard
+// is load-time, so only a fresh module load can exercise it, and the registry is
+// read from disk, so only a patched read can make it bad.
+//
+// This matters because the sibling test above ("every entry maps to a permission
+// the catalog defines as system:true") only checks the COMMITTED file. The
+// load-time throw is what protects an out-of-band registry write — the Government
+// tab editing an instance file at runtime — and nothing was watching it.
+function loadWithRegistry(registryJson) {
+  execFileSync(process.execPath, ['-e',
+    "const fs=require('node:fs');const real=fs.readFileSync;" +
+    'const fake=' + JSON.stringify(JSON.stringify(registryJson)) + ';' +
+    "fs.readFileSync=(p,...r)=>(String(p).includes('protected-surfaces.json') ? fake : real(p,...r));" +
+    "require('./modules/government/protected-surfaces.js');",
+  ], { cwd: ROOT, stdio: 'pipe' });
+}
+
+test('a surface mapped to a GRANTABLE permission fails loud at load', () => {
+  // A grantable (system:false) key is the dangerous case ADR 0151 §4 names: a
+  // custom rank could be handed the very power the substrate reserves.
   const grantable = catalog.grantableKeys()[0];
-  assert.ok(grantable && catalog.isSystem(grantable) === false);
-  assert.equal(catalog.byKey('not.a.real.permission'), null);
+  assert.ok(grantable, 'the catalog must define at least one grantable key for this probe');
+  assert.equal(catalog.isSystem(grantable), false, 'fixture sanity: the probe key must be grantable');
+  assert.throws(
+    () => loadWithRegistry({
+      floor: 'metic',
+      permission: grantable,
+      surfaces: [{ glob: 'src/probe/grantable-surface.js' }],
+    }),
+    /which is not system:true/,
+    'a surface mapping to a grantable permission must refuse to load',
+  );
+});
+
+test('a surface mapped to an UNKNOWN permission fails loud at load', () => {
+  assert.equal(catalog.byKey('not.a.real.permission'), null, 'fixture sanity: the key must be unknown');
+  assert.throws(
+    () => loadWithRegistry({
+      floor: 'metic',
+      permission: 'not.a.real.permission',
+      surfaces: [{ glob: 'src/probe/unknown-surface.js' }],
+    }),
+    /which the permission catalog does not define/,
+    'a surface mapping to a permission the catalog never defines must refuse to load',
+  );
+});
+
+test('the probe itself is honest — a GOOD registry loads clean through the same path', () => {
+  // Without this, both assertions above would pass if the subprocess threw for an
+  // unrelated reason (a bad patch, a missing cwd, a syntax error in the -e script).
+  assert.doesNotThrow(() => loadWithRegistry({
+    floor: 'metic',
+    permission: registry.SYSTEM_PERMISSIONS[0],
+    surfaces: [{ glob: 'src/probe/good-surface.js' }],
+  }), 'a well-formed registry must still load — otherwise the probes above prove nothing');
+});
+
+test('an unknown FLOOR is refused before the catalog check ever sees it', () => {
+  // The validation loop's third branch (`!catalog.RANK_ORDER.includes(s.floor)`) is
+  // a DRIFT guard, not dead code, and this test records why it cannot be provoked
+  // through the registry: the kernel loader keeps its own local RANK_TIER map
+  // (permission-path-check.js) and rejects an unknown floor first. The government
+  // branch only becomes reachable if those two rank lists ever disagree — which is
+  // exactly the drift it exists to catch, and is not craftable from JSON alone.
+  assert.throws(
+    () => loadWithRegistry({
+      floor: 'emperor',
+      permission: registry.SYSTEM_PERMISSIONS[0],
+      surfaces: [{ glob: 'src/probe/bad-floor.js' }],
+    }),
+    /unknown floor/,
+  );
+  assert.deepEqual(catalog.RANK_ORDER, ['xenos', 'thetes', 'metic', 'archon'],
+    'if this list and the kernel RANK_TIER drift, the government floor branch wakes up');
 });
 
 // ---------- synchronous, no DB, no server ----------

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();