@bongos/core 1.21.149 → 1.21.151

package/.bongos-core.json

@@ -2,11 +2,11 @@
   "artifact": "bongos-core",
   "manifest_schema": 1,
   "generator": "scripts/gds/package-core.js",
-  "core_version": "1.21.149",
-  "core_contract": "1.21.149",
-  "source_commit": "59efe78dbbc530e6743f98d50abc605e2184adcc",
+  "core_version": "1.21.151",
+  "core_contract": "1.21.151",
+  "source_commit": "366555c8ca4216d853ce17bab4c85a196abcfe99",
   "source_ref": "HEAD",
-  "built_at": "2026-10-19T21:44:07.784Z",
+  "built_at": "2026-10-21T20:09:00.726Z",
   "redaction": {
     "model": "docs-redacted+functional-verbatim",
     "docs_redacted": 608,
@@ -17,7 +17,7 @@
     "gate": "passed"
   },
   "file_count": 3805,
-  "tree_sha256": "2fb626947478be776e71613c82d973ebf073298ea8d6e5561f4e604e1438d661",
+  "tree_sha256": "b07285b765ca2b3f7a888f50a72ebdbee4d2dc00b3f60cbeca742b826f325648",
   "files": [
     {
       "path": ".claude/skills/ask-for-help/SKILL.md",
@@ -2927,7 +2927,7 @@
     {
       "path": "docs/module-api-changelog.md",
       "mode": "0000644",
-      "sha256": "af2424a88f8836e7035c00a52637fbbf137bf1b716130a360868fa50bab54b2d"
+      "sha256": "9898532c3685ca8978bd6b50f7dd08d517133ea7ec1f1666f1f2bdec93163f06"
     },
     {
       "path": "docs/modules-contract.md",
@@ -7737,7 +7737,7 @@
     {
       "path": "modules/lifecycle/ship-assurance.js",
       "mode": "0000644",
-      "sha256": "690171d9e4e7d82537cf1d030d98aa37ee0ac72bbcdce6a04429d3d49ecbe46a"
+      "sha256": "c4dd044485e664528c01caea0500dd6fe9d8ee9d2319385000d1cee26e32102e"
     },
     {
       "path": "modules/lifecycle/ship-card.js",
@@ -10552,12 +10552,12 @@
     {
       "path": "package-lock.json",
       "mode": "0000644",
-      "sha256": "d03c2a175c60400695aecccbe5c9ef87b085521c6bf92176c6d2ed08e514c8a6"
+      "sha256": "c3a3f8b630793dca42d403a809b1bc443a971b8b716cbc4528b618a2207e088e"
     },
     {
       "path": "package.json",
       "mode": "0000644",
-      "sha256": "9d6713f305cdfe492805906778e171c75c42e4fd8dff5935ad9245d185b6ce22"
+      "sha256": "bd1bf8f46aa70487096bfe37135040919bfdec1f1b0698166c3b29d8f3cdb94d"
     },
     {
       "path": "public-docs/index.html",
@@ -10577,7 +10577,7 @@
     {
       "path": "release-notes.json",
       "mode": "0000644",
-      "sha256": "9394c3c784137020e70389b269a68f36f8f2d0757b306a1f64622b8b5886f368"
+      "sha256": "53613b258fac54f2e36d9728dd874a94d4635a89557c97532b7bdfd1380fb4e1"
     },
     {
       "path": "scripts/cron/style_guide_audit.sh",
@@ -10982,7 +10982,7 @@
     {
       "path": "scripts/gds/credential-presence.js",
       "mode": "0000644",
-      "sha256": "36ecef8da86e9905c8c3e8431881828aba0ecca7e10b63db014f86658c5bf58b"
+      "sha256": "396e7ac7b19cec00134f4d13d7b130d0ef620f8b16ca61134ddf6df6ace0ea44"
     },
     {
       "path": "scripts/gds/cutover-codemod.js",
@@ -11492,17 +11492,17 @@
     {
       "path": "scripts/gds/module-test-runner.js",
       "mode": "0000644",
-      "sha256": "00c844922f5b465485847e45782c71c3103fe9d6aa0e09d4908121769aecbe78"
+      "sha256": "a7b3b169ead1a43021f7207d5da2974728212e45867f1bacd33c66e9c5d33fe6"
     },
     {
       "path": "scripts/gds/module-test-runner/README.md",
       "mode": "0000644",
-      "sha256": "e6253ef4056f35355d5c19af247de840b0f925f7a2b8ead8f2598227be9e6d38"
+      "sha256": "0100c214318a60e6af0259e5194159963c0e879f549652cdd95920d77ac3e790"
     },
     {
       "path": "scripts/gds/module-test-runner/module-tests.yml",
       "mode": "0000644",
-      "sha256": "d721ad7959afb899877aafd31c6a22287d6e479e0fb4fb4f600d12ce5e12a2fd"
+      "sha256": "5446be05a510ac398cf89ae0e03d47055c06b8bbe5db218e7e489f63e477cdb1"
     },
     {
       "path": "scripts/gds/module.js",
@@ -12957,7 +12957,7 @@
     {
       "path": "src/module-api.js",
       "mode": "0000644",
-      "sha256": "b89f1cd4820d3d4257eabf44a666b44c722c9e159dd561bbced94784cceaf8ea"
+      "sha256": "19d8bd5693481f9d261606976c15bc375eeeb0ef35a6d80a89adb32885d6602f"
     },
     {
       "path": "src/module-loader/catalog.js",
@@ -16657,7 +16657,7 @@
     {
       "path": "tests/module_test_runner.mjs",
       "mode": "0000644",
-      "sha256": "e6fbb32fd8f43c748d89aca5a9025872582d1628e47de12c4ce4bca834c8be88"
+      "sha256": "328cf836fd45d28ddfc0630f86801037069396dc7cdd066181375ac3c3a81538"
     },
     {
       "path": "tests/module_toggle_restart.mjs",
@@ -18102,7 +18102,7 @@
     {
       "path": "tests/ship_assurance.mjs",
       "mode": "0000644",
-      "sha256": "ca6e0100049ad284c8467fe4775ed9db4578f11c0704091043dda5e2c25654cf"
+      "sha256": "be68b8dbf514937f581dfa3a892958fd4f16e20dd319d0ed70bf08811a3451e3"
     },
     {
       "path": "tests/ship_autolinkify.mjs",

package/docs/module-api-changelog.md

@@ -3135,5 +3135,9 @@ is load-bearing: the script throws rather than guess if it is missing, and
         landed since 1.21.147 with no explicit bump. run 39286989989. (task 1002620)
   1.21.149 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
         landed since 1.21.148 with no explicit bump. run 39329687123. (task 1002620)
+  1.21.150 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+        landed since 1.21.149 with no explicit bump. run 39331860470. (task 1002620)
+  1.21.151 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+        landed since 1.21.150 with no explicit bump. run 39667670641. (task 1002620)
 ---------------------------------------------------------------------------
 ```

package/modules/lifecycle/ship-assurance.js

@@ -67,7 +67,13 @@ function normalizeShipAssurance(a) {
 //
 // `deps` is injected so this is unit-testable with no network and no DB.
 async function deriveShipAssurance({ taskId, body = {}, db, githubPush, onProbeError }) {
-  const report = (e) => { if (onProbeError) onProbeError(e); };
+  // Every probe miss is kept, not just logged: when the ONLY reason there is no
+  // proof is that this server cannot read GitHub at all, the refusal must say so
+  // (task 1004760). The toast instance merged real work and was told only that the
+  // land was "not proven" — its GitHub App existed but was never installed on the
+  // repo, which is a one-click owner fix nobody was told about.
+  const probeErrors = [];
+  const report = (e) => { probeErrors.push(e); if (onProbeError) onProbeError(e); };
   // The tip is the durable proof (task 1547); the branch/PR status is only a
   // WITNESS for the out-of-band fallback (task 1002615). A claim with no branch
   // makes getPublishStatus throw BAD_BRANCH — that used to abort the whole probe
@@ -117,6 +123,26 @@ async function deriveShipAssurance({ taskId, body = {}, db, githubPush, onProbeE
     return { assurance: { kind: 'no_artifact', reason } };
   }
 
+  const noAccess = githubAccessCause(probeErrors);
+  if (noAccess) {
+    return {
+      refusal: {
+        code: 'ship_land_not_proven',
+        status: 409,
+        message: noAccess.message,
+        details: {
+          cause: noAccess.cause,
+          install_url: noAccess.install_url || null,
+          what_this_means: noAccess.message,
+          your_options: [
+            noAccess.fix,
+            'Nothing is lost: once the server can read GitHub, the reconciler proves the merge and ships the task on its own, with its credits.',
+          ],
+        },
+      },
+    };
+  }
+
   return {
     refusal: {
       code: 'ship_land_not_proven',
@@ -133,6 +159,37 @@ async function deriveShipAssurance({ taskId, body = {}, db, githubPush, onProbeE
 }
 
 
+// Was the land unprovable only because this server has no way to read GitHub?
+// PURE over the probe errors deriveShipAssurance collected. Returns null when the
+// probes could see GitHub (a genuine "not on main" answer stays the generic
+// refusal), else { cause, message, fix, install_url? } (task 1004760).
+//   APP_NOT_INSTALLED        the App exists but nobody installed it on the repo —
+//                            the owner's one remaining setup step.
+//   PUSH_UNCONFIGURED /      no GitHub credential at all, and no git checkout of
+//   LOCAL_PROOF_UNAVAILABLE  the project to ask instead (a hosted instance).
+function githubAccessCause(errors) {
+  const codes = (errors || []).map((e) => e && e.code);
+  const notInstalled = (errors || []).find((e) => e && e.code === 'APP_NOT_INSTALLED');
+  if (notInstalled) {
+    const repo = notInstalled.owner && notInstalled.repo ? `${notInstalled.owner}/${notInstalled.repo}` : 'the project repository';
+    const where = notInstalled.install_url ? `at ${notInstalled.install_url}` : "from the App's page in GitHub settings (Install App)";
+    return {
+      cause: 'github_app_not_installed',
+      install_url: notInstalled.install_url || null,
+      message: `The merge may well be on main, but this server cannot check: the project's GitHub App is not installed on ${repo}, so the server cannot read the repository.`,
+      fix: `The project owner installs the GitHub App on ${repo} ${where} — one click, no other setup.`,
+    };
+  }
+  if (codes.includes('PUSH_UNCONFIGURED') || codes.includes('LOCAL_PROOF_UNAVAILABLE')) {
+    return {
+      cause: 'no_github_access',
+      message: 'The merge may well be on main, but this server cannot check: it has no GitHub access (no GitHub App or token) and no copy of the repository to look in.',
+      fix: "The project owner finishes the project's GitHub setup (Settings → GitHub) so the server can read the repository.",
+    };
+  }
+  return null;
+}
+
 // Record WHY a ship was allowed, not merely that it happened. POST-COMMIT and
 // best-effort by design: insertAuditLog uses the module pool rather than the
 // ship's transaction client, and an audit miss must never roll back a landed ship
@@ -172,13 +229,14 @@ async function gateManualShip(res, opts) {
     onProbeError: (e) => log && log.warn(`POST /tasks/${taskId}/ship: land probe failed (${e && e.message}) — no proof`),
   });
   if (derived.refusal) {
-    res.fail(derived.refusal.code, derived.refusal.status, derived.refusal.details);
+    const { code, status, message, details } = derived.refusal;
+    res.fail(code, { status, message, details });
     return null;
   }
   return derived.assurance;
 }
 
 module.exports = {
-  normalizeShipAssurance, deriveShipAssurance, recordShipAssurance,
+  normalizeShipAssurance, deriveShipAssurance, recordShipAssurance, githubAccessCause,
   assertShipAssurance, gateManualShip, SHIP_BODY_SCHEMA, SHIP_ASSURANCE_KINDS: KINDS, MAX_REASON_CHARS,
 };

package/package-lock.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bongos/core",
-  "version": "1.21.149",
+  "version": "1.21.151",
   "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/release-notes.json

@@ -9908,5 +9908,17 @@
       "id": "1004759",
       "text": "When a project's site is too old to send Bongos feedback, the command now says 'Not sent' and keeps the note, instead of claiming it was sent."
     }
+  ],
+  "1.21.150": [
+    {
+      "id": "1004760",
+      "text": "When a project's GitHub App isn't installed, a refused ship now says so and links the one-click install, instead of a bare 'not proven'."
+    }
+  ],
+  "1.21.151": [
+    {
+      "id": "1004739",
+      "text": "The module test runner can now test against the private core: the server sends its own copy of the core into the private test repo, once per version."
+    }
   ]
 }

package/scripts/gds/credential-presence.js

@@ -121,6 +121,16 @@ const CREDENTIALS = [
     names: ['METRICS_TOKEN'],
     purpose: 'bearer token for a remote Prometheus scrape of /metrics (src/bongos/metrics.js)',
   },
+  {
+    id: 'module-test-runner', file: 'web.env', need: 'optional',
+    names: ['MODULE_TEST_REPO', 'MODULE_TEST_TOKEN'],
+    purpose: "runs store modules' own tests in a separate private GitHub repo (scripts/gds/module-test-runner.js, blocker 1000195); unset leaves Tests pending",
+  },
+  {
+    id: 'module-test-ref', file: 'web.env', need: 'optional',
+    names: ['MODULE_TEST_REF'], notSecret: true,
+    purpose: "the test repo branch holding the module-tests workflow (default main)",
+  },
   {
     id: 'hub-signing-key', file: 'web.env', need: 'optional',
     names: ['HUB_SIGNING_KEY'], prefixed: true,

package/scripts/gds/module-test-runner/README.md

@@ -22,9 +22,9 @@ stays `pending`.
    MODULE_TEST_REPO=<owner>/<repo>
    MODULE_TEST_TOKEN=<the token>
    ```
-   Optional: `MODULE_TEST_CORE_REPO=<owner>/<name>` if the server's git `origin` is not
-   the public core repo, and `MODULE_TEST_REF=<branch>` if the test repo's workflow
-   lives on a branch other than `main`.
+   Optional: `MODULE_TEST_REF=<branch>` if the test repo's workflow lives on a
+   branch other than `main`. Nothing names the core repo: the runner gets the
+   core from the test repo itself (see the header of `module-test-runner.js`).
 
 On the runner, a module's tests run as a separate user with no admin rights and
 no network access (only the machine's own loopback), after the core is installed.

package/scripts/gds/module-test-runner/module-tests.yml

@@ -6,7 +6,8 @@
 # nothing here ever holds a DB credential or a control-plane secret.
 #
 # Two jobs on purpose: `fetch` can read the repo (where the tarball waits on a
-# throwaway branch) but runs no module code; `test` runs the module's code with a
+# throwaway branch, and the core snapshot on core/<sha>) but runs no module code;
+# `test` runs the module's code with a
 # GITHUB_TOKEN that has NO permissions, so a module that scrapes its token still
 # cannot read another run's tarball. Inside `test`, the module's code runs as an
 # unprivileged user with its network cut (see "Cut the network for module code").
@@ -19,8 +20,7 @@ on:
       version_id: { description: store_module_versions.id, required: true, type: string }
       module_key: { description: the module's key, required: true, type: string }
       nonce: { description: this run's nonce (32 hex), required: true, type: string }
-      core_repo: { description: owner/name of the public core, required: true, type: string }
-      core_ref: { description: the core commit to test against, required: true, type: string }
+      core_ref: { description: the core commit to test against (40 hex; branch core/<sha> holds it), required: true, type: string }
 
 permissions: {}
 
@@ -31,14 +31,21 @@ jobs:
     timeout-minutes: 5
     steps:
       - name: Check the inputs
-        env: { NONCE: "${{ inputs.nonce }}", VERSION_ID: "${{ inputs.version_id }}" }
+        env: { NONCE: "${{ inputs.nonce }}", VERSION_ID: "${{ inputs.version_id }}", CORE_REF: "${{ inputs.core_ref }}" }
         run: |
           [[ "$NONCE" =~ ^[0-9a-f]{32}$ ]] || { echo "bad nonce"; exit 1; }
           [[ "$VERSION_ID" =~ ^[0-9]+$ ]] || { echo "bad version id"; exit 1; }
+          [[ "$CORE_REF" =~ ^[0-9a-f]{40}$ ]] || { echo "bad core ref"; exit 1; }
       - uses: actions/checkout@v4
         with: { ref: "module-test/${{ inputs.nonce }}", path: tarball, persist-credentials: false }
+      # The core repo is private, so the control plane pushes a snapshot of the
+      # core it runs to core/<sha> in THIS repo (once per commit; task 1004739).
+      - uses: actions/checkout@v4
+        with: { ref: "core/${{ inputs.core_ref }}", path: core-snapshot, persist-credentials: false }
       - uses: actions/upload-artifact@v4
         with: { name: "tarball-${{ inputs.nonce }}", path: tarball/module.tgz, retention-days: 1 }
+      - uses: actions/upload-artifact@v4
+        with: { name: "core-${{ inputs.nonce }}", path: core-snapshot/core.tgz, retention-days: 1, compression-level: 0 }
 
   test:
     needs: fetch
@@ -46,12 +53,17 @@ jobs:
     permissions: {}
     timeout-minutes: 30
     steps:
-      - uses: actions/checkout@v4
-        with: { repository: "${{ inputs.core_repo }}", ref: "${{ inputs.core_ref }}", path: core, persist-credentials: false }
       - uses: actions/setup-node@v4
         with: { node-version: 22 }
       - uses: actions/download-artifact@v4
         with: { name: "tarball-${{ inputs.nonce }}", path: in }
+      - uses: actions/download-artifact@v4
+        with: { name: "core-${{ inputs.nonce }}", path: core-in }
+      - name: Unpack the core
+        run: |
+          mkdir core
+          tar -xzf core-in/core.tgz -C core
+          rm -rf core-in
       - name: Install the core
         working-directory: core
         run: npm ci --no-audit --no-fund

package/scripts/gds/module-test-runner.js

@@ -13,18 +13,31 @@
 // THE ROUND TRIP. Nothing on the runner ever holds a DB credential:
 //   1. dispatch — the control plane pushes the version's tarball to a throwaway
 //      orphan branch `module-test/<nonce>` in the test repo and dispatches the
-//      workflow with { version_id, module_key, nonce, core_repo, core_ref }. The
-//      nonce goes into the pending Tests row's detail.runner.
+//      workflow with { version_id, module_key, nonce, core_ref }. The nonce goes
+//      into the pending Tests row's detail.runner.
 //   2. the run — a `fetch` job (contents: read, no module code) copies the tarball
-//      into the run as an artifact; a separate `test` job (permissions: {}) checks
-//      out the core at core_ref, runs module-assess-tests.js --tarball with
-//      MODULE_TEST_SANDBOX=1, and uploads the signal JSON as artifact
+//      and the core snapshot into the run as artifacts; a separate `test` job
+//      (permissions: {}) unpacks the core, runs module-assess-tests.js --tarball
+//      with MODULE_TEST_SANDBOX=1, and uploads the signal JSON as artifact
 //      module-tests-<version_id>-<nonce>.
 //   3. collect — the control plane PULLS: it finds the run whose run-name carries
 //      the pending row's nonce, takes only that run's artifact of that exact name,
 //      checks the payload names the same version and nonce, inserts the signal row
 //      itself, recomposes the score, and deletes the branch.
 //
+// WHY THE CORE TRAVELS AS A SNAPSHOT (task 1004739). The core repo is private, so
+// a runner whose token has no permissions cannot check it out by name. Before the
+// first run against a core commit, dispatch pushes `git archive` of that commit
+// (tracked files only, so never node_modules; minus the design mocks in
+// .impeccable/, which nothing runs) to an orphan branch `core/<sha>` in the test
+// repo, with the same token. Once per commit: a later dispatch finds the ref and
+// reuses it. The `fetch` job reads it with its contents: read token like the
+// tarball, so the `test` job still needs no permission and no repo name at all.
+// GitHub refuses a blob over 100 MB and the archive goes up base64-encoded (a
+// third bigger), so a snapshot over MAX_CORE_BYTES fails the dispatch loudly: a
+// dispatch that cannot be sent is logged as an error, not a warning, because the
+// version's Tests part then stays pending until someone fixes the cause.
+//
 // WHY A PER-RUN BRANCH, NOT A DOWNLOAD TICKET. A ticket would mean a new
 // unauthenticated route on the control plane (and a change to the protected
 // route-rank-check), i.e. a fresh inbound path to the server holding the secrets.
@@ -37,53 +50,50 @@
 // tests pass, so the score is never trust-critical; what this protects is the
 // secrets and other authors' code.
 //
-// Configured by three control-plane env vars (all unset = off; Tests then stays
-// `pending`, exactly as before this task):
+// Configured by control-plane env vars (repo + token unset = off; Tests then
+// stays `pending`, exactly as before this task):
 //   MODULE_TEST_REPO       owner/name of the private test repo
 //   MODULE_TEST_TOKEN      a fine-grained token scoped to ONLY that repo, with
 //                          Actions: read & write and Contents: read & write
-//   MODULE_TEST_CORE_REPO  owner/name of the public core the runner checks out
-//                          (default: this checkout's `origin`)
 //   MODULE_TEST_REF        the test repo branch holding the workflow (default main)
 //
 //   node scripts/gds/module-test-runner.js dispatch <store_module_versions.id>
 //   node scripts/gds/module-test-runner.js collect
 
 const fs = require('node:fs');
+const path = require('node:path');
 const crypto = require('node:crypto');
 const zlib = require('node:zlib');
-const { execFileSync } = require('node:child_process');
+const { execFile } = require('node:child_process');
+const { promisify } = require('node:util');
+
+const execFileAsync = promisify(execFile);
 
 const WORKFLOW_FILE = 'module-tests.yml';
 const BRANCH_PREFIX = 'module-test/';
+const CORE_BRANCH_PREFIX = 'core/';
 const API = 'https://api.github.com';
 // A run that has not finished this long after dispatch is recorded not_scored.
 const MAX_RUN_AGE_MS = 6 * 60 * 60_000;
 const MAX_SIGNAL_BYTES = 256 * 1024;
+// GitHub's blob limit is 100 MB and the snapshot is sent base64 (4/3 the size).
+const MAX_CORE_BYTES = 72 * 1024 * 1024;
+const CORE_ROOT = path.join(__dirname, '..', '..');
 const REPO_RE = /^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/;
 const NONCE_RE = /^[0-9a-f]{32}$/;
+const SHA_RE = /^[0-9a-f]{40}$/;
 
 const runName = (versionId, nonce) => `module-tests ${versionId} ${nonce}`;
 const artifactName = (versionId, nonce) => `module-tests-${versionId}-${nonce}`;
 
-function originRepo() {
-  try {
-    const url = execFileSync('git', ['remote', 'get-url', 'origin'], { cwd: __dirname, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim();
-    const m = url.match(/github\.com[/:]([^/]+\/[^/]+?)(?:\.git)?$/);
-    return m ? m[1] : null;
-  } catch { return null; }
-}
-
 // The runner config, or null when it is not set up (the default: Tests stays pending).
-function runnerConfig(env = process.env, { origin = originRepo } = {}) {
+function runnerConfig(env = process.env) {
   const repo = (env.MODULE_TEST_REPO || '').trim();
   const token = (env.MODULE_TEST_TOKEN || '').trim();
   if (!repo || !token) return null;
   if (!REPO_RE.test(repo)) throw new Error(`MODULE_TEST_REPO must be owner/name, got "${repo}"`);
-  const coreRepo = (env.MODULE_TEST_CORE_REPO || '').trim() || origin();
-  if (!coreRepo || !REPO_RE.test(coreRepo)) throw new Error('MODULE_TEST_CORE_REPO is unset and the core repo could not be read from git origin');
   const ref = (env.MODULE_TEST_REF || '').trim() || 'main';
-  return { repo, token, coreRepo, ref };
+  return { repo, token, ref };
 }
 
 // One GitHub REST call. Resolves the parsed body (or null for 204); throws with
@@ -104,7 +114,54 @@ async function gh(cfg, method, urlPath, body, { fetchImpl = fetch } = {}) {
 // The commit the control plane is running, so the runner tests against the same core.
 function currentCoreRef() {
   const { buildInfo } = require('../../src/build-info');
-  return buildInfo().commit || 'main';
+  return buildInfo().commit;
+}
+
+// The core at one commit, as the tar.gz the runner unpacks. Async, so the web
+// process keeps serving while git compresses. It needs the commit in a git
+// checkout here: a vendored core (node_modules/@bongos/core) has none, and gets
+// an error that says so rather than git's own.
+async function archiveCore(sha) {
+  try {
+    const { stdout } = await execFileAsync('git', ['archive', '--format=tar.gz', sha, '--', '.', ':(exclude).impeccable', ':(exclude)node_modules'],
+      { cwd: CORE_ROOT, encoding: 'buffer', maxBuffer: 4 * MAX_CORE_BYTES });
+    return stdout;
+  } catch (e) {
+    const why = String((e.stderr && e.stderr.toString()) || e.message).trim().split('\n')[0];
+    throw new Error(`could not snapshot core commit ${sha.slice(0, 8)}: the core must run from a git checkout that holds it (a vendored install has none) — git said: ${why}`);
+  }
+}
+
+// Push a one-file orphan commit to a new branch of the test repo.
+async function pushOrphanBranch(cfg, branch, file, bytes, message, { fetchImpl } = {}) {
+  const r = `/repos/${cfg.repo}`;
+  const blob = await gh(cfg, 'POST', `${r}/git/blobs`, { content: bytes.toString('base64'), encoding: 'base64' }, { fetchImpl });
+  const tree = await gh(cfg, 'POST', `${r}/git/trees`, { tree: [{ path: file, mode: '100644', type: 'blob', sha: blob.sha }] }, { fetchImpl });
+  const commit = await gh(cfg, 'POST', `${r}/git/commits`, { message, tree: tree.sha, parents: [] }, { fetchImpl });
+  await gh(cfg, 'POST', `${r}/git/refs`, { ref: `refs/heads/${branch}`, sha: commit.sha }, { fetchImpl });
+}
+
+// Make sure branch core/<sha> holds the core snapshot, pushing it only the first
+// time. Resolves { branch, pushed }. Two dispatches racing on a new commit both
+// push; the loser's ref create is refused (422) and it uses the winner's.
+async function ensureCoreSnapshot(cfg, sha, { fetchImpl, archive = archiveCore } = {}) {
+  if (!SHA_RE.test(sha || '')) throw new Error(`the running core commit is unknown ("${sha || ''}"), so there is no core to test against`);
+  const branch = `${CORE_BRANCH_PREFIX}${sha}`;
+  try {
+    await gh(cfg, 'GET', `/repos/${cfg.repo}/git/ref/heads/${branch}`, null, { fetchImpl });
+    return { branch, pushed: false };
+  } catch (e) { if (e.status !== 404) throw e; }
+  const tgz = await archive(sha);
+  if (tgz.length > MAX_CORE_BYTES) {
+    throw new Error(`the core snapshot for ${sha.slice(0, 8)} is ${(tgz.length / 1048576).toFixed(1)} MB, over the ${MAX_CORE_BYTES / 1048576} MB the test repo can take; trim what archiveCore sends in scripts/gds/module-test-runner.js`);
+  }
+  try {
+    await pushOrphanBranch(cfg, branch, 'core.tgz', tgz, `core snapshot ${sha}`, { fetchImpl });
+  } catch (e) {
+    if (e.status === 422) return { branch, pushed: false };
+    throw e;
+  }
+  return { branch, pushed: true };
 }
 
 function readVersionTarball(ver) {
@@ -112,27 +169,26 @@ function readVersionTarball(ver) {
   return fs.promises.readFile(versionArtifactFile(ver));
 }
 
-// Push the tarball to a throwaway orphan branch and dispatch the workflow.
-// Resolves the runner record kept in the pending row: { nonce, branch, dispatched_at }.
-async function dispatchRun(ver, { cfg, fetchImpl, readTarball = readVersionTarball, coreRef = currentCoreRef, now = () => new Date() } = {}) {
+// Make sure the core snapshot is there, push the tarball to a throwaway orphan
+// branch, and dispatch the workflow. Resolves the runner record kept in the
+// pending row: { nonce, branch, core_ref, dispatched_at }.
+async function dispatchRun(ver, { cfg, fetchImpl, readTarball = readVersionTarball, coreRef = currentCoreRef, archive, now = () => new Date() } = {}) {
+  const sha = coreRef();
+  await ensureCoreSnapshot(cfg, sha, { fetchImpl, archive });
   const tgz = await readTarball(ver);
   const nonce = crypto.randomBytes(16).toString('hex');
   const branch = `${BRANCH_PREFIX}${nonce}`;
-  const r = `/repos/${cfg.repo}`;
-  const blob = await gh(cfg, 'POST', `${r}/git/blobs`, { content: tgz.toString('base64'), encoding: 'base64' }, { fetchImpl });
-  const tree = await gh(cfg, 'POST', `${r}/git/trees`, { tree: [{ path: 'module.tgz', mode: '100644', type: 'blob', sha: blob.sha }] }, { fetchImpl });
-  const commit = await gh(cfg, 'POST', `${r}/git/commits`, { message: `module tests: version ${ver.id}`, tree: tree.sha, parents: [] }, { fetchImpl });
-  await gh(cfg, 'POST', `${r}/git/refs`, { ref: `refs/heads/${branch}`, sha: commit.sha }, { fetchImpl });
+  await pushOrphanBranch(cfg, branch, 'module.tgz', tgz, `module tests: version ${ver.id}`, { fetchImpl });
   try {
-    await gh(cfg, 'POST', `${r}/actions/workflows/${WORKFLOW_FILE}/dispatches`, {
+    await gh(cfg, 'POST', `/repos/${cfg.repo}/actions/workflows/${WORKFLOW_FILE}/dispatches`, {
       ref: cfg.ref || 'main',
-      inputs: { version_id: String(ver.id), module_key: ver.module_key, nonce, core_repo: cfg.coreRepo, core_ref: coreRef() },
+      inputs: { version_id: String(ver.id), module_key: ver.module_key, nonce, core_ref: sha },
     }, { fetchImpl });
   } catch (e) {
     await deleteBranch(cfg, branch, { fetchImpl });
     throw e;
   }
-  return { nonce, branch, dispatched_at: now().toISOString() };
+  return { nonce, branch, core_ref: sha, dispatched_at: now().toISOString() };
 }
 
 async function deleteBranch(cfg, branch, { fetchImpl } = {}) {
@@ -162,7 +218,7 @@ async function maybeDispatch(ver, { db, env = process.env, log = console, ...opt
   if (newest && !(newest.outcome === 'pending' && !(newest.detail && newest.detail.runner))) return null;
   let runner;
   try { runner = await dispatchRun(ver, { cfg, ...opts }); }
-  catch (e) { log.warn(`module test run for version ${ver.id} not dispatched: ${e.message}`); return null; }
+  catch (e) { log.error(`module test run for version ${ver.id} not dispatched: ${e.message}`); return null; }
   await db.query(
     `INSERT INTO module_assessment_signals (version_id, part, outcome, score, sample_size, reason, detail)
      VALUES ($1, 'tests', 'pending', NULL, NULL, $2, $3)`,
@@ -355,4 +411,4 @@ if (require.main === module) {
   main(process.argv.slice(2)).then((code) => { process.exitCode = code; }, (e) => { console.error(e.stack || e.message); process.exitCode = 1; });
 }
 
-module.exports = { runnerConfig, maybeDispatch, collectResults, sweepTick, readZipEntry, validateSignal, runName, artifactName };
+module.exports = { runnerConfig, archiveCore, maybeDispatch, collectResults, sweepTick, readZipEntry, validateSignal, runName, artifactName };

package/src/module-api.js

@@ -75,7 +75,7 @@ const { responsibilityFor, ROLE_RESPONSIBILITIES } = require('./role-responsibil
 // MAJOR (see allowBoxScope below): passes the request through untouched.
 function deprecatedNoopMiddleware(_req, _res, next) { next(); }
 
-const CORE_VERSION = '1.21.149'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
+const CORE_VERSION = '1.21.151'; // 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('discord'); log.info('mounted');

package/tests/module_test_runner.mjs

@@ -18,9 +18,12 @@ import { fileURLToPath } from 'node:url';
 const require = createRequire(import.meta.url);
 const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
 const runner = require('../scripts/gds/module-test-runner.js');
-const { runnerConfig, maybeDispatch, collectResults, sweepTick, readZipEntry, validateSignal, runName, artifactName } = runner;
+const { runnerConfig, archiveCore, maybeDispatch, collectResults, sweepTick, readZipEntry, validateSignal, runName, artifactName } = runner;
 
-const CFG = { repo: 'owner/module-tests', token: 't0ken', coreRepo: 'owner/core' };
+const CFG = { repo: 'owner/module-tests', token: 't0ken' };
+const SHA = 'a1'.repeat(20);
+const coreRef = () => SHA;
+const archive = async () => Buffer.from('core-tgz');
 const VER = { id: 7, module_key: 'weather', version: '1.0.0', artifact_path: 'weather/weather-1.0.0.tgz' };
 const quiet = { warn() {}, error() {} };
 
@@ -104,36 +107,75 @@ test('unconfigured: no runner, so Tests stays plain pending and nothing is sent'
   assert.equal(db.signals.length, 0);
 });
 
-test('config: owner/name is required, the core repo falls back to git origin', () => {
+test('config: owner/name is required; there is no core repo to name', () => {
   assert.throws(() => runnerConfig({ MODULE_TEST_REPO: 'nope', MODULE_TEST_TOKEN: 'x' }), /owner\/name/);
-  const c = runnerConfig({ MODULE_TEST_REPO: 'o/r', MODULE_TEST_TOKEN: 'x' }, { origin: () => 'o/core' });
-  assert.deepEqual(c, { repo: 'o/r', token: 'x', coreRepo: 'o/core', ref: 'main' });
-  assert.equal(runnerConfig({ MODULE_TEST_REPO: 'o/r', MODULE_TEST_TOKEN: 'x', MODULE_TEST_REF: 'trunk' }, { origin: () => 'o/core' }).ref, 'trunk');
+  assert.deepEqual(runnerConfig({ MODULE_TEST_REPO: 'o/r', MODULE_TEST_TOKEN: 'x', MODULE_TEST_CORE_REPO: 'o/core' }), { repo: 'o/r', token: 'x', ref: 'main' });
+  assert.equal(runnerConfig({ MODULE_TEST_REPO: 'o/r', MODULE_TEST_TOKEN: 'x', MODULE_TEST_REF: 'trunk' }).ref, 'trunk');
 });
 
-test('dispatch pushes the tarball to a throwaway branch, dispatches, and records the nonce', async () => {
+const short = (c) => `${c.method} ${c.url.replace('https://api.github.com/repos/owner/module-tests', '')}`;
+const PUSH = ['POST /git/blobs', 'POST /git/trees', 'POST /git/commits', 'POST /git/refs'];
+const DISPATCH = 'POST /actions/workflows/module-tests.yml/dispatches';
+
+test('the first dispatch on a core commit pushes the core to core/<sha>, then the tarball, then dispatches', async () => {
   const db = fakeDb();
   const gh = fakeGitHub(dispatchRoutes);
-  const r = await maybeDispatch(VER, { db, cfg: CFG, fetchImpl: gh.fetchImpl, readTarball: async () => Buffer.from('tgz'), coreRef: () => 'abc123', log: quiet });
+  const r = await maybeDispatch(VER, { db, cfg: CFG, fetchImpl: gh.fetchImpl, readTarball: async () => Buffer.from('tgz'), coreRef, archive, log: quiet });
   assert.match(r.nonce, /^[0-9a-f]{32}$/);
   assert.equal(r.branch, `module-test/${r.nonce}`);
-  assert.deepEqual(gh.calls.map((c) => `${c.method} ${c.url.replace('https://api.github.com/repos/owner/module-tests', '')}`), [
-    'POST /git/blobs', 'POST /git/trees', 'POST /git/commits', 'POST /git/refs', 'POST /actions/workflows/module-tests.yml/dispatches']);
-  assert.deepEqual(gh.calls[2].body.parents, [], 'an orphan commit: the branch carries only the tarball');
-  assert.equal(gh.calls[3].body.ref, `refs/heads/module-test/${r.nonce}`);
-  assert.equal(gh.calls[4].body.ref, 'main');
-  assert.deepEqual(gh.calls[4].body.inputs, { version_id: '7', module_key: 'weather', nonce: r.nonce, core_repo: 'owner/core', core_ref: 'abc123' });
+  assert.equal(r.core_ref, SHA);
+  assert.deepEqual(gh.calls.map(short), [`GET /git/ref/heads/core/${SHA}`, ...PUSH, ...PUSH, DISPATCH]);
+  assert.equal(Buffer.from(gh.calls[1].body.content, 'base64').toString(), 'core-tgz');
+  assert.equal(gh.calls[2].body.tree[0].path, 'core.tgz');
+  assert.deepEqual(gh.calls[3].body.parents, [], 'the core snapshot is an orphan commit');
+  assert.equal(gh.calls[4].body.ref, `refs/heads/core/${SHA}`);
+  assert.deepEqual(gh.calls[7].body.parents, [], 'an orphan commit: the branch carries only the tarball');
+  assert.equal(gh.calls[8].body.ref, `refs/heads/module-test/${r.nonce}`);
+  assert.equal(gh.calls[9].body.ref, 'main');
+  assert.deepEqual(gh.calls[9].body.inputs, { version_id: '7', module_key: 'weather', nonce: r.nonce, core_ref: SHA });
   assert.equal(db.signals.length, 1);
   assert.equal(db.signals[0].outcome, 'pending');
   assert.equal(db.signals[0].detail.runner.nonce, r.nonce);
 });
 
+test('a later dispatch on the same core commit reuses core/<sha> and never archives again', async () => {
+  const gh = fakeGitHub({ ...dispatchRoutes, [`GET /git/ref/heads/core/${SHA}$`]: { ref: `refs/heads/core/${SHA}` } });
+  let archived = 0;
+  const r = await maybeDispatch(VER, { db: fakeDb(), cfg: CFG, fetchImpl: gh.fetchImpl, readTarball: async () => Buffer.from('tgz'), coreRef, archive: async () => { archived += 1; return Buffer.from('x'); }, log: quiet });
+  assert.ok(r);
+  assert.equal(archived, 0);
+  assert.deepEqual(gh.calls.map(short), [`GET /git/ref/heads/core/${SHA}`, ...PUSH, DISPATCH]);
+  assert.equal(gh.calls[1].body.content, Buffer.from('tgz').toString('base64'), 'only the module tarball is pushed');
+});
+
+test('two dispatches racing on a new commit: the loser\'s refused ref create still dispatches', async () => {
+  const gh = fakeGitHub({ ...dispatchRoutes, 'POST /git/refs$': (url, init) => (JSON.parse(init.body).ref.startsWith('refs/heads/core/') ? new Response('{"message":"Reference already exists"}', { status: 422 }) : { ref: 'x' }) });
+  assert.ok(await maybeDispatch(VER, { db: fakeDb(), cfg: CFG, fetchImpl: gh.fetchImpl, readTarball: async () => Buffer.from('tgz'), coreRef, archive, log: quiet }));
+  assert.equal(gh.calls.at(-1).url.endsWith('/dispatches'), true);
+});
+
+test('an oversized core snapshot, or an unknown core commit, fails the dispatch loudly and pushes nothing', async () => {
+  for (const opts of [{ archive: async () => Buffer.alloc(73 * 1024 * 1024) }, { coreRef: () => null, archive }]) {
+    const db = fakeDb();
+    const gh = fakeGitHub(dispatchRoutes);
+    const errors = [];
+    assert.equal(await maybeDispatch(VER, { db, cfg: CFG, fetchImpl: gh.fetchImpl, readTarball: async () => Buffer.from('tgz'), coreRef, log: { warn() {}, error: (m) => errors.push(m) }, ...opts }), null);
+    assert.match(errors[0], /over the 72 MB|core commit is unknown/);
+    assert.ok(!gh.calls.some((c) => c.method === 'POST'), 'nothing was pushed or dispatched');
+    assert.equal(db.signals.length, 0);
+  }
+});
+
+test('a core commit git cannot find fails with a cause a person can act on, not git\'s bare error', async () => {
+  await assert.rejects(archiveCore('0'.repeat(40)), /must run from a git checkout that holds it/);
+});
+
 test('a version with a real Tests result, or a run already in flight, is not dispatched again', async () => {
   for (const existing of [{ outcome: 'scored', detail: {} }, { outcome: 'pending', detail: { runner: { nonce: 'a'.repeat(32) } } }]) {
     const db = fakeDb();
     db.signals.push({ id: 1, version_id: 7, part: 'tests', ...existing });
     const gh = fakeGitHub(dispatchRoutes);
-    assert.equal(await maybeDispatch(VER, { db, cfg: CFG, fetchImpl: gh.fetchImpl, readTarball: async () => Buffer.from('x'), coreRef: () => 'c', log: quiet }), null);
+    assert.equal(await maybeDispatch(VER, { db, cfg: CFG, fetchImpl: gh.fetchImpl, readTarball: async () => Buffer.from('x'), coreRef, archive, log: quiet }), null);
     assert.equal(gh.calls.length, 0);
   }
 });
@@ -142,13 +184,13 @@ test('a plain pending (from before the runner was set up) is dispatched', async
   const db = fakeDb();
   db.signals.push({ id: 1, version_id: 7, part: 'tests', outcome: 'pending', detail: {} });
   const gh = fakeGitHub(dispatchRoutes);
-  assert.ok(await maybeDispatch(VER, { db, cfg: CFG, fetchImpl: gh.fetchImpl, readTarball: async () => Buffer.from('x'), coreRef: () => 'c', log: quiet }));
+  assert.ok(await maybeDispatch(VER, { db, cfg: CFG, fetchImpl: gh.fetchImpl, readTarball: async () => Buffer.from('x'), coreRef, archive, log: quiet }));
 });
 
 test('a failed dispatch deletes the branch, records nothing and never throws', async () => {
   const db = fakeDb();
   const gh = fakeGitHub({ ...dispatchRoutes, 'POST /dispatches$': () => new Response('{"message":"nope"}', { status: 422 }), 'DELETE /git/refs/heads/module-test/': null });
-  assert.equal(await maybeDispatch(VER, { db, cfg: CFG, fetchImpl: gh.fetchImpl, readTarball: async () => Buffer.from('x'), coreRef: () => 'c', log: quiet }), null);
+  assert.equal(await maybeDispatch(VER, { db, cfg: CFG, fetchImpl: gh.fetchImpl, readTarball: async () => Buffer.from('x'), coreRef, archive, log: quiet }), null);
   assert.equal(gh.calls.at(-1).method, 'DELETE');
   assert.equal(db.signals.length, 0);
 });
@@ -274,7 +316,18 @@ test('the workflow template: no permissions for the job that runs module code, n
   assert.match(yml, /^run-name: module-tests \$\{\{ inputs\.version_id \}\} \$\{\{ inputs\.nonce \}\}$/m);
   assert.equal(runName(7, 'n'), 'module-tests 7 n', 'collect matches the template\'s run-name');
   const testJob = yml.slice(yml.indexOf('\n  test:'));
+  const fetchJob = yml.slice(yml.indexOf('\n  fetch:'), yml.indexOf('\n  test:'));
   assert.match(testJob, /permissions: \{\}/);
+  // The core repo is private (task 1004739): the test job checks out nothing by
+  // name; the fetch job reads the snapshot dispatch pushed to core/<sha> and hands
+  // it over as an artifact.
+  assert.doesNotMatch(testJob, /actions\/checkout/, 'the job that runs module code checks out no repo');
+  assert.doesNotMatch(yml, /repository:|core_repo/, 'no repo is named anywhere');
+  assert.match(fetchJob, /ref: "core\/\$\{\{ inputs\.core_ref \}\}"/);
+  assert.match(fetchJob, /name: "core-\$\{\{ inputs\.nonce \}\}", path: core-snapshot\/core\.tgz/);
+  assert.match(fetchJob, /\^\[0-9a-f\]\{40\}\$/, 'the core ref is checked before it is used');
+  assert.match(testJob, /name: "core-\$\{\{ inputs\.nonce \}\}", path: core-in/);
+  assert.ok(testJob.indexOf('Unpack the core') < testJob.indexOf('npm ci'), 'the core is unpacked before it is installed');
   assert.match(testJob, /MODULE_TEST_SANDBOX=1/);
   // Module code runs as an unprivileged user whose packets the firewall rejects off loopback.
   const cut = testJob.indexOf('Cut the network');

package/tests/ship_assurance.mjs

@@ -321,5 +321,69 @@ await t('no tip + no PR for the task → the 409 refusal, and getPublishStatus i
   assert.equal(statusCalls, 0);
 });
 
+// task 1004760 — the toast instance merged real work and was refused with a bare
+// "not proven": its GitHub App was never installed on the repo, so every probe threw
+// APP_NOT_INSTALLED and the server could not look. The refusal must NAME that cause
+// and the one-click fix, not leave the builder guessing.
+console.log('\nthe refusal names a server that cannot read GitHub (task 1004760)');
+const notInstalled = () => {
+  const e = new Error('APP_NOT_INSTALLED');
+  e.code = 'APP_NOT_INSTALLED';
+  e.owner = 'acme';
+  e.repo = 'widget';
+  e.install_url = 'https://github.com/apps/widget-app/installations/new';
+  return e;
+};
+await t('App not installed → the refusal says so, with the install link', async () => {
+  const r = await deriveShipAssurance({
+    taskId: 1,
+    body: {},
+    db: { getClaimPublishedSha: async () => TIP },
+    githubPush: {
+      findTaskPullRequest: async () => { throw notInstalled(); },
+      getPublishStatus: async () => null,
+      landProvenForTask: async () => { throw notInstalled(); },
+    },
+  });
+  assert.equal(r.refusal.code, 'ship_land_not_proven');
+  assert.equal(r.refusal.details.cause, 'github_app_not_installed');
+  assert.match(r.refusal.message, /not installed on acme\/widget/);
+  assert.equal(r.refusal.details.install_url, 'https://github.com/apps/widget-app/installations/new');
+  assert.ok(r.refusal.details.your_options.some((o) => o.includes('installations/new')));
+});
+await t('no credential and no checkout → the refusal says the server has no GitHub access', async () => {
+  for (const code of ['PUSH_UNCONFIGURED', 'LOCAL_PROOF_UNAVAILABLE']) {
+    const r = await deriveShipAssurance({
+      taskId: 1,
+      body: {},
+      db: { getClaimPublishedSha: async () => TIP },
+      githubPush: {
+        findTaskPullRequest: async () => null,
+        landProvenForTask: async () => { const e = new Error(code); e.code = code; throw e; },
+      },
+    });
+    assert.equal(r.refusal.details.cause, 'no_github_access', code);
+    assert.match(r.refusal.message, /no GitHub access/);
+  }
+});
+await t('a server that CAN read GitHub keeps the plain refusal (the tip really is not on main)', async () => {
+  const r = await deriveShipAssurance({
+    taskId: 1,
+    body: {},
+    db: { getClaimPublishedSha: async () => TIP },
+    githubPush: {
+      findTaskPullRequest: async () => null,
+      landProvenForTask: async () => ({ proven: false, reason: 'not in main' }),
+    },
+  });
+  assert.equal(r.refusal.code, 'ship_land_not_proven');
+  assert.equal(r.refusal.details.cause, undefined);
+  assert.equal(r.refusal.message, undefined);
+});
+await t('the gate sends the cause as the error MESSAGE, which is what the CLI prints', () => {
+  const src = fs.readFileSync(path.join(ROOT, 'modules/lifecycle/ship-assurance.js'), 'utf8');
+  assert.match(src, /res\.fail\(code, \{ status, message, details \}\)/);
+});
+
 console.log(`\n${passed} passed, ${failed} failed`);
 process.exit(failed ? 1 : 0);