@bongos/core 1.21.149 → 1.21.150

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.150",
+  "core_contract": "1.21.150",
+  "source_commit": "0c869afc46eb5a0841a9406c43fa41f8031c01ad",
   "source_ref": "HEAD",
-  "built_at": "2026-10-19T21:44:07.784Z",
+  "built_at": "2026-10-19T22:01:23.493Z",
   "redaction": {
     "model": "docs-redacted+functional-verbatim",
     "docs_redacted": 608,
@@ -17,7 +17,7 @@
     "gate": "passed"
   },
   "file_count": 3805,
-  "tree_sha256": "2fb626947478be776e71613c82d973ebf073298ea8d6e5561f4e604e1438d661",
+  "tree_sha256": "e7a8a5514591ba5b313a0cc54239367bcfb3f92d0dce344582653a125ecb5d21",
   "files": [
     {
       "path": ".claude/skills/ask-for-help/SKILL.md",
@@ -2927,7 +2927,7 @@
     {
       "path": "docs/module-api-changelog.md",
       "mode": "0000644",
-      "sha256": "af2424a88f8836e7035c00a52637fbbf137bf1b716130a360868fa50bab54b2d"
+      "sha256": "42b00f22670c0c8aa194a2a7c3f22f3bcc9e4a444ff54c398c1254c06e6d5718"
     },
     {
       "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": "d0e2fcb3573e72ebc1d3ba608eeac029763e7fb2f8fad0f459cca42759bb6c5b"
     },
     {
       "path": "package.json",
       "mode": "0000644",
-      "sha256": "9d6713f305cdfe492805906778e171c75c42e4fd8dff5935ad9245d185b6ce22"
+      "sha256": "5348abba02d8b98849a7a6cf83a44f7d3138f00a806edb89ae2616618b15a559"
     },
     {
       "path": "public-docs/index.html",
@@ -10577,7 +10577,7 @@
     {
       "path": "release-notes.json",
       "mode": "0000644",
-      "sha256": "9394c3c784137020e70389b269a68f36f8f2d0757b306a1f64622b8b5886f368"
+      "sha256": "eaf55ec677f00c2212a9fb00f680130dc60974d8e2a199a97337048c567d2706"
     },
     {
       "path": "scripts/cron/style_guide_audit.sh",
@@ -12957,7 +12957,7 @@
     {
       "path": "src/module-api.js",
       "mode": "0000644",
-      "sha256": "b89f1cd4820d3d4257eabf44a666b44c722c9e159dd561bbced94784cceaf8ea"
+      "sha256": "6ff0eaf959df5d39f838ae2b19a960f7f37552e9eedcb91b183b09b38ab6c840"
     },
     {
       "path": "src/module-loader/catalog.js",
@@ -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,7 @@ 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)
 ---------------------------------------------------------------------------
 ```

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.150",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@bongos/core",
-      "version": "1.21.149",
+      "version": "1.21.150",
       "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.150",
   "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,11 @@
       "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'."
+    }
   ]
 }

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.150'; // 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/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);