@bongos/core 1.19.724 → 1.19.726

package/.bongos-core.json

@@ -2,22 +2,22 @@
   "artifact": "bongos-core",
   "manifest_schema": 1,
   "generator": "scripts/gds/package-core.js",
-  "core_version": "1.19.724",
-  "core_contract": "1.19.724",
-  "source_commit": "26fe0e32ab8d71694d4a83ebd8aec4d442ce8da0",
+  "core_version": "1.19.726",
+  "core_contract": "1.19.726",
+  "source_commit": "d8623af04d5a30742d38eb9ba239a3f63f775a36",
   "source_ref": "HEAD",
-  "built_at": "2026-09-13T13:15:36.801Z",
+  "built_at": "2026-09-13T14:41:51.726Z",
   "redaction": {
     "model": "docs-redacted+functional-verbatim",
     "docs_redacted": 478,
     "agent_docs_stubbed": 24,
-    "functional_verbatim": 2162,
+    "functional_verbatim": 2163,
     "rules": 3,
     "gate_literals": 3,
     "gate": "passed"
   },
-  "file_count": 2664,
-  "tree_sha256": "444d762aa2ed1f4ebcc9269d0542680f83ed9da1a928a98ac6a36ebe09c691da",
+  "file_count": 2665,
+  "tree_sha256": "a9b351048d2b02f92d5d3a8a5639a19ab5ed6731a39eb8ac8a937ac19eb22448",
   "files": [
     {
       "path": ".claude/skills/ask-for-help/SKILL.md",
@@ -2807,7 +2807,7 @@
     {
       "path": "docs/module-api-changelog.md",
       "mode": "0000644",
-      "sha256": "690b1a1f85cb9eb8e3b9e326b39cd56724bd0e3287d96539a7e84c6267231507"
+      "sha256": "1d9b38322833641b859bcf8e401135219788455e5aa0d5082d7044551beefd08"
     },
     {
       "path": "docs/modules-contract.md",
@@ -6137,7 +6137,7 @@
     {
       "path": "modules/onboarding/approval-broadcast.js",
       "mode": "0000644",
-      "sha256": "5d88c9b42e5f76b0959a543d097456a00c3ec1f4ef1a75ca8de6334b826ba983"
+      "sha256": "2225b1a2196f6195bdf1b24f38da5295e0f44cbd95395d09c6109d8680fc5b01"
     },
     {
       "path": "modules/onboarding/db.js",
@@ -7837,12 +7837,12 @@
     {
       "path": "package-lock.json",
       "mode": "0000644",
-      "sha256": "10ce0347095f2fef439846e19eee1535447edac0fd659fb0ef8703f50df6e60f"
+      "sha256": "7637583d4d85202afbf079b2db2c89fb687377c8478d5baa8c058dc282e6d141"
     },
     {
       "path": "package.json",
       "mode": "0000644",
-      "sha256": "ddfcaa576b63f9169be34c591a1c0dccd629ca0399b0e27bf514a4a54fc21c6d"
+      "sha256": "c9ee4d8541a9fb546d0556b13d3814e132b301e606676d6d23c2416c8c3b23b7"
     },
     {
       "path": "public-docs/index.html",
@@ -7907,7 +7907,7 @@
     {
       "path": "scripts/gds/adopt-preflight.js",
       "mode": "0000644",
-      "sha256": "07ff338beac12979eba50e4a6fe9c2f6dbfd842fa01abe1c412b19888d10c4a0"
+      "sha256": "1e2c8a70aec49eaa0d95a9cbf37145fa1c851b46e2ec27f72f773d4198356ab9"
     },
     {
       "path": "scripts/gds/adr-namespace.js",
@@ -8067,7 +8067,7 @@
     {
       "path": "scripts/gds/build-cli-package.js",
       "mode": "0000644",
-      "sha256": "bd7509b408b56ded44c07f3cbad8cf361211fd8349e5139c75c49d31fcaa07a9"
+      "sha256": "314004ef2af628fca5f572daca5e2404d1c2129b3ad650d715294cc26cc2fe13"
     },
     {
       "path": "scripts/gds/bump-version.js",
@@ -8117,7 +8117,7 @@
     {
       "path": "scripts/gds/claude-md-template.js",
       "mode": "0000644",
-      "sha256": "68f2c65ac9297328f44927ccb9a40a0fa536b91d9056aaa980a92149a64ce47c"
+      "sha256": "afd825409590fa0c81cdc072bb925555e70bd543f819b8c68110760919ca67e1"
     },
     {
       "path": "scripts/gds/cleanup-orphans.js",
@@ -8219,6 +8219,11 @@
       "mode": "0000644",
       "sha256": "79effdf07519d26153f6fe846fd052cd4a37fa1e25b6b1a278146c9d8bcf6766"
     },
+    {
+      "path": "scripts/gds/device-flow-help.js",
+      "mode": "0000644",
+      "sha256": "802b8875e2aa7e51b1b95800aae461c5d289d7684ef57e6da95bebc458aa0f5e"
+    },
     {
       "path": "scripts/gds/diagnose-achievements.js",
       "mode": "0000644",
@@ -8327,7 +8332,7 @@
     {
       "path": "scripts/gds/gate-review.js",
       "mode": "0000644",
-      "sha256": "19d739354ed6f485a842ce77379ed4b63f9b86ba848c3b9d7528809a79ad74f1"
+      "sha256": "183c4592b68f059ef89b4d516ae589526af08901543ded0183b8854cd9b1e5a2"
     },
     {
       "path": "scripts/gds/gating.js",
@@ -8452,7 +8457,7 @@
     {
       "path": "scripts/gds/init.js",
       "mode": "0000644",
-      "sha256": "b0971625852fca93ca474d2f9e31e3601397f1b9efbef3241a0b0c47f17d925f"
+      "sha256": "e81ab71bcd7d2f06b5aaf462dd099776c966f9840a109846a9753f12482b5281"
     },
     {
       "path": "scripts/gds/install-git-hooks.js",
@@ -8522,7 +8527,7 @@
     {
       "path": "scripts/gds/login.js",
       "mode": "0000644",
-      "sha256": "bdc7fcc0876a1185fb15339740793944c755d716d998bb68533ab3a721d39ab2"
+      "sha256": "b5e00007cf68a5fa719d2603fdd7405dbc2e474a41721acde274e43bcec59ab0"
     },
     {
       "path": "scripts/gds/main-audit.js",
@@ -8972,7 +8977,7 @@
     {
       "path": "scripts/gds/setup.js",
       "mode": "0000644",
-      "sha256": "15243de5b4bde57313c601bf96bd2a10bb86dedceb18cb0a31495b998d1ca835"
+      "sha256": "bd78df6f5f296588721afd9ebf2e477b5d463ca3d12cbee8894e115a0a6779f7"
     },
     {
       "path": "scripts/gds/shell.js",
@@ -9462,7 +9467,7 @@
     {
       "path": "src/bongos/permission-path-check.js",
       "mode": "0000644",
-      "sha256": "5116468286f737a3421dbcdfdc48f78ecc8f25496f7db0382f9af9e1a0110e9c"
+      "sha256": "14ba2ffb603cbea7d8388c196b74f8e7db92b777fb0da7c69c7d3c7c9e27f386"
     },
     {
       "path": "src/bongos/platform-visibility-gate.js",
@@ -9492,7 +9497,7 @@
     {
       "path": "src/bongos/repo-info.js",
       "mode": "0000644",
-      "sha256": "ae6cd8950ec8e23935febcc14c4ba65ff39f045c01202a1237d1ad79a39153f2"
+      "sha256": "38c98f7cdb9dbc9d73dc53d0ad29466bc2fc8f762cd8db3961ab40df44dae11c"
     },
     {
       "path": "src/bongos/route-rank-check.js",
@@ -9632,7 +9637,7 @@
     {
       "path": "src/module-api.js",
       "mode": "0000644",
-      "sha256": "e4a9cdca849f840e277b0632217f9a8aec42d570d96373548f47d04bd1fce0bd"
+      "sha256": "958848fd9515e4e2c7544579ba4023f136ab5d1e5d521964ae12404682fc193c"
     },
     {
       "path": "src/module-loader/catalog.js",
@@ -9727,7 +9732,7 @@
     {
       "path": "tests/adopt_preflight.mjs",
       "mode": "0000644",
-      "sha256": "125edcec8c7d7536365b9675daa1fceb9fe072a30e2a4a68ee2911cd258a8c10"
+      "sha256": "2489a19e7c36f53c4046a4a6fab54a55dbdfe8da6daa3452316f9e0abea01742"
     },
     {
       "path": "tests/adr_renumber_integrity.mjs",
@@ -10052,7 +10057,7 @@
     {
       "path": "tests/bongos_login.mjs",
       "mode": "0000644",
-      "sha256": "f273c511d9c42093da170572a0db55f78cada57787e7631aefdd622228c2fad9"
+      "sha256": "abad290fe23b159a6c42a70fbc6cec68bfc0406c90776a96b57513e9b4b8ef04"
     },
     {
       "path": "tests/box_access.mjs",
@@ -10272,7 +10277,7 @@
     {
       "path": "tests/claude_materialize.mjs",
       "mode": "0000644",
-      "sha256": "9ae022d9051937e80b0d3a4baf3840d57560fa9d441b93beff746cfa11871d35"
+      "sha256": "8292d8c7a788e7839599d38f6c78a5dbb68f6ae50a58771a66e6481a562f0ace"
     },
     {
       "path": "tests/clawback_confirmed_backlog.mjs",
@@ -10572,7 +10577,7 @@
     {
       "path": "tests/discord_approvals.mjs",
       "mode": "0000644",
-      "sha256": "f5acf8bac78844a0015ecec64d3f85c0546bb3e186eabb19311cb9e33cd6dc64"
+      "sha256": "1b4df0a8cd7dc48f393cd2c3ca7ec91759270c7df87a50397fb3d18d3b6a29fe"
     },
     {
       "path": "tests/discord_autojoin.mjs",
@@ -11122,7 +11127,7 @@
     {
       "path": "tests/government_protected_surfaces.mjs",
       "mode": "0000644",
-      "sha256": "d11562d59861a5f5d294c072b3aa15f03703ddbb2102210ff92f7ccbcff5b5f6"
+      "sha256": "dfde7ca6e223324317a0d56960db7adc9b30bdfc35f718269e9d6978344545ac"
     },
     {
       "path": "tests/government_rank_sync.mjs",
@@ -11557,7 +11562,7 @@
     {
       "path": "tests/init.mjs",
       "mode": "0000644",
-      "sha256": "4a79313db6d6393415ace3e24f985be397156c10845b6543fdfbda3944ddeec0"
+      "sha256": "5b0eaf9cee1a51a4ff41197c4af844a0ba89e5a44f23d0f00de09e5ca8900f08"
     },
     {
       "path": "tests/instance_config.mjs",
@@ -11842,7 +11847,7 @@
     {
       "path": "tests/module_api.mjs",
       "mode": "0000644",
-      "sha256": "ac7d0fd4eb478b79cf9e72994f133e5d6bcca9caef3efd3a388779a18c58292d"
+      "sha256": "53aa3732865dfce17a3216390b057dae825a6a7a8056309f3f31654c06636bee"
     },
     {
       "path": "tests/module_api_lazy.mjs",
@@ -12477,7 +12482,7 @@
     {
       "path": "tests/repo_info_binding.mjs",
       "mode": "0000644",
-      "sha256": "f6a95140fc8e99a7045cf8d3ccc41606fe911138fd915f40061437f2b2cc283a"
+      "sha256": "384a494fab8da8cab77e1241ce8ebd954b658bcc56c578065c6f80bc0fd74f7d"
     },
     {
       "path": "tests/repo_map.mjs",
@@ -12742,7 +12747,7 @@
     {
       "path": "tests/setup_device_flow_fallback.mjs",
       "mode": "0000644",
-      "sha256": "f047b209ec3b0ea2fcffbee7c3b36d8cf01bb18e19cfcfa9d32267db672d834d"
+      "sha256": "f59a1381d0f71f5eb25c8e691cda2347fc34ae2569db191ae074fe2f07c87f1a"
     },
     {
       "path": "tests/setup_smoke.mjs",

package/docs/module-api-changelog.md

@@ -1922,5 +1922,9 @@ is load-bearing: the script throws rather than guess if it is missing, and
         landed since 1.19.722 with no explicit bump. run 34758720786. (task 1002620)
   1.19.724 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
         landed since 1.19.723 with no explicit bump. run 34759302425. (task 1002620)
+  1.19.725 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+        landed since 1.19.724 with no explicit bump. run 34760272743. (task 1002620)
+  1.19.726 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+        landed since 1.19.725 with no explicit bump. run 34763380132. (task 1002620)
 ---------------------------------------------------------------------------
 ```

package/modules/onboarding/approval-broadcast.js

@@ -48,12 +48,39 @@ async function postLine(channel, line, deps = {}) {
   }
 }
 
+// Is the half that CLOSES this loop actually loaded? The line we post invites a 👍,
+// and that reaction is only ever applied by modules/discord/discord-approvals.js —
+// which lives in the `discord` module. onboarding is default-ON and discord is
+// default-OFF, and nothing gated one on the other, so a default instance posted an
+// approve/decline control with nothing listening: an Archon reacts, watches the
+// reaction land, and believes they admitted someone. Nobody is told otherwise.
+//
+// A control that cannot work is worse than no message, so the outbound half now
+// refuses to post without its inbound half. The hall queue is the source of truth
+// either way, so nothing is lost — only a false affordance is withheld.
+// Reached through the published doorway (the one core file a module may require,
+// ADR 0083), never a direct require of src/modules.js. Fails CLOSED: if enablement
+// can't be resolved we do not post, because that is the state we cannot vouch for.
+function discordHandlerLoaded(deps = {}) {
+  try {
+    const isEnabled = deps.isModuleEnabled || require('../../src/module-api').isModuleEnabled;
+    return isEnabled('discord') === true;
+  } catch (_) {
+    return false;
+  }
+}
+
 async function postMemberApprovalRequest(request, deps = {}) {
   if (!request || request.id == null) return { posted: false, skipped: 'no_request' };
+  if (!discordHandlerLoaded(deps)) {
+    (deps.log || console.log)('[gds] approval broadcast: skipped — the `discord` module is off, so no reaction handler would apply a 👍. Approve from the hall queue.');
+    return { posted: false, skipped: 'discord_module_off' };
+  }
   return postLine('member_approvals', memberApprovalLine(request), deps);
 }
 
 module.exports = {
   memberApprovalLine,
   postMemberApprovalRequest,
+  discordHandlerLoaded, // exported for unit tests — the gate is the whole fix
 };

package/package-lock.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bongos/core",
-  "version": "1.19.724",
+  "version": "1.19.726",
   "description": "Cloud Bongos — the AI-first build platform core (GDS + platform surfaces + module system), installed as a versioned dependency (ADR 0108).",
   "license": "AGPL-3.0-or-later",
   "main": "src/platform-server.js",

package/scripts/gds/adopt-preflight.js

@@ -11,11 +11,20 @@
 //     floor (ADR 0043, via gate-review.js's canonical matchesHardFloor).
 //   • CI collisions — the repo's workflows vs core's expected unit/secret-scan/
 //     gate-review checks.
+//   • IGNORED incoming files — a pre-existing .gitignore rule that would swallow what
+//     adopt is about to commit (task 1003400). This is the check that was missing when
+//     Cloud Bongos was adopted onto a repo whose .gitignore already carried `.claude/`:
+//     the skills, hooks and settings.json were materialized onto disk and then dropped
+//     by `git add`, so the adopt commit landed 8 files with no methodology surface at
+//     all. Nothing failed, nothing was logged, and every clone of that repo has been
+//     missing its /builder-* commands since. BLOCKING, because the result is a
+//     non-functional instance that looks fine.
 // READ-ONLY: it computes findings; the accept-gate that decides whether to proceed
 // lives in init.js runAdopt. Pure check functions + a thin fs-reading orchestrator.
 
 const nodeFs = require('node:fs');
 const nodePath = require('node:path');
+const { execFileSync: nodeExecFileSync } = require('node:child_process');
 const { filenameViolation, INSTANCE_NS } = require('./migration-namespace');
 const { matchesHardFloor } = require('./gate-review');
 
@@ -79,10 +88,66 @@ function checkCiCollisions(workflows = []) {
   return [{ category: 'ci', severity: SEV.INFO, message: `${workflows.length} existing CI workflow(s); core will ADD its own unit/secret-scan/gate-review checks alongside them — confirm no required-check conflict.` }];
 }
 
+// PURE — [{ path, rule }] of incoming files a .gitignore rule would swallow → findings.
+// BLOCKING: an ignored incoming file is not a style problem, it is silent data loss at
+// `git add` time, and the instance that results is broken in a way nothing reports.
+function checkIgnoredIncoming(ignored = [], { checked = true } = {}) {
+  if (!checked) {
+    return [{ category: 'ignored-incoming', severity: SEV.INFO, message: 'could not run `git check-ignore` here (no git, or not a repo yet) — cannot confirm the incoming files are committable. Re-check after `git init` if adopt lands nothing under .claude/.' }];
+  }
+  if (!ignored.length) {
+    return [{ category: 'ignored-incoming', severity: SEV.INFO, message: 'no existing ignore rule swallows the files adopt writes — they will all reach the commit.' }];
+  }
+  const lines = ignored.map((i) => (i.rule ? `${i.path} (ignored by ${i.rule})` : i.path));
+  return [{
+    category: 'ignored-incoming',
+    severity: SEV.BLOCK,
+    message: `${ignored.length} file(s) adopt writes are IGNORED by this repo and would be silently dropped from the commit: ${lines.join('; ')}. `
+      + 'Adopt would appear to succeed and produce an instance missing that surface — a repo ignoring `.claude/` gets no /builder-* commands on any clone. '
+      + 'Fix the rule (delete it, or add a negation such as `!.claude/` after it), then re-run.',
+  }];
+}
+
+// Which of `incoming` does this repo's ignore rules match? Uses `git check-ignore -v`,
+// which reports the SOURCE RULE for each match, so the finding can name the exact line
+// the owner has to change rather than leaving them to hunt for it.
+//
+// Returns { ignored:[{path, rule}], checked:boolean }. `checked:false` means the probe
+// could not run at all (no git, not a repo) — deliberately distinct from "nothing is
+// ignored", because the two warrant different advice. execFileSync is injectable for
+// tests; git exits 1 when nothing matches, which is a normal answer and not an error.
+function probeIgnoredIncoming({ dir, incoming = INCOMING_PATHS, execFileSync = nodeExecFileSync } = {}) {
+  // Trailing slashes are ours (they mark dirs in the list); git wants plain pathnames.
+  const paths = incoming.map((p) => String(p).replace(/\/+$/, ''));
+  let out = '';
+  try {
+    out = execFileSync('git', ['check-ignore', '-v', '--stdin'], {
+      cwd: dir, input: paths.join('\n'), encoding: 'utf8', timeout: 5000,
+      stdio: ['pipe', 'pipe', 'ignore'],
+    }) || '';
+  } catch (err) {
+    // Exit 1 = "no path is ignored" (a real answer, stdout empty). Anything else means
+    // the probe itself could not run.
+    if (err && err.status === 1) return { ignored: [], checked: true };
+    return { ignored: [], checked: false };
+  }
+  const ignored = [];
+  for (const line of out.split('\n')) {
+    if (!line.trim()) continue;
+    // `<source>:<line>:<pattern>\t<pathname>`
+    const tab = line.lastIndexOf('\t');
+    if (tab === -1) continue;
+    const rule = line.slice(0, tab).trim();
+    const pathname = line.slice(tab + 1).trim();
+    ignored.push({ path: pathname, rule });
+  }
+  return { ignored, checked: true };
+}
+
 // Read the repo (migrations, src/bongos, workflows) and run every check. `stack` is the
 // adopt-detect summary (task 2043); we re-read only what the checks need. Returns
 // { findings, counts:{blocking,warning,info}, hasBlocking }.
-function preflightAdopt({ dir, stack = {}, fs = nodeFs, path = nodePath } = {}) {
+function preflightAdopt({ dir, stack = {}, fs = nodeFs, path = nodePath, execFileSync = nodeExecFileSync } = {}) {
   const listFiles = (rel) => { try { return fs.readdirSync(path.join(dir, rel)).filter((f) => { try { return fs.statSync(path.join(dir, rel, f)).isFile(); } catch { return false; } }); } catch { return []; } };
   const exists = (rel) => { try { return fs.existsSync(path.join(dir, rel)); } catch { return false; } };
 
@@ -105,6 +170,7 @@ function preflightAdopt({ dir, stack = {}, fs = nodeFs, path = nodePath } = {})
     ...checkFitnessBoundary({ topLevelDirs: stack.topLevelDirs || [], hasSrcBongos: exists('src/bongos') }),
     ...checkProtectedPaths(INCOMING_PATHS),
     ...checkCiCollisions(workflows),
+    ...(() => { const { ignored, checked } = probeIgnoredIncoming({ dir, execFileSync }); return checkIgnoredIncoming(ignored, { checked }); })(),
   ];
   const counts = { blocking: 0, warning: 0, info: 0 };
   for (const f of findings) counts[f.severity === SEV.BLOCK ? 'blocking' : f.severity === SEV.WARN ? 'warning' : 'info']++;
@@ -118,4 +184,4 @@ function formatPreflight(report) {
   return report.findings.map((f) => `  ${mark[f.severity] || '·'}  [${f.category}] ${f.message}`);
 }
 
-module.exports = { preflightAdopt, formatPreflight, checkMigrationNamespace, checkFitnessBoundary, checkProtectedPaths, checkCiCollisions, INCOMING_PATHS, CORE_EXPECTED_CHECKS, SEV };
+module.exports = { preflightAdopt, formatPreflight, checkMigrationNamespace, checkFitnessBoundary, checkProtectedPaths, checkCiCollisions, checkIgnoredIncoming, probeIgnoredIncoming, INCOMING_PATHS, CORE_EXPECTED_CHECKS, SEV };

package/scripts/gds/build-cli-package.js

@@ -51,6 +51,7 @@ const FILES = [
   'scripts/gds/login.js',
   'scripts/gds/reauth.js',
   'scripts/gds/setup.js',
+  'scripts/gds/device-flow-help.js', // shared leaf: login.js + setup.js both require it (task 1003881)
   'scripts/gds/onboarding-config.js', // lazy dep of setup.js
   'scripts/gds/install-git-hooks.js', // lazy dep of setup.js
   'scripts/gds/preflight.js',

package/scripts/gds/claude-md-template.js

@@ -12,6 +12,14 @@
 // of a mature instance's CLAUDE.md — the instance grows its own. Coordinates with
 // task 1963 (neutralizing the core's own CLAUDE.md into the portable template).
 //
+// FIRST-RUN SECTION. The template used to open by instructing the agent to run
+// `bongos start` without ever saying the CLI ships inside an uninstalled dependency,
+// so an agent opening a fresh clone followed its first instruction straight into
+// `command not found`. The root README carries the same signpost for humans — but only
+// when the repo had no README to begin with, which an ADOPTED repo always does. This
+// file lands on BOTH paths and loads in full every session, so it is the one place the
+// bootstrap is guaranteed to be read.
+//
 // PURE (branding in → markdown out), so it unit-tests standalone and carries no
 // hardcoded host identity (everything comes from the branding object — R76-safe).
 
@@ -48,6 +56,16 @@ function renderInstanceClaudeMd(branding = {}) {
 
 Read this at the start of every session. Keep it lean — it loads in full every time.
 
+## First run — before any \`bongos\` command
+
+**If \`node_modules/@bongos/core\` is missing, run \`npm install\` first.** The \`bongos\` CLI ships *inside* that dependency, so until the install completes there is no \`bongos\` command and every instruction below fails with \`command not found\`:
+
+\`\`\`bash
+npm install
+\`\`\`
+
+Once per machine, per clone — it is not committed (\`node_modules/\` is ignored on purpose), so a fresh \`git clone\` always needs it. If a \`bongos\` command then still misbehaves, \`bongos doctor\` checks the toolchain and session and prints the fix.
+
 ## What this is
 
 ${ident}

package/scripts/gds/device-flow-help.js

@@ -0,0 +1,72 @@
+#!/usr/bin/env node
+'use strict';
+// scripts/gds/device-flow-help.js — the one explanation of a Device-Flow refusal, shared
+// by `bongos setup` and `bongos login` (task 1003400).
+//
+// WHY IT EXISTS AT ALL. GitHub creates an App from a manifest with Device Flow OFF and
+// exposes no API to switch it on — only a checkbox in the App's settings. So on every
+// wizard-born instance the documented terminal sign-in is hard-broken from birth, for
+// every builder, until the owner ticks that box. Nothing in the product can do it for
+// them; the least we can do is say so precisely, and name a route that works meanwhile.
+//
+// WHY IT IS ITS OWN FILE. setup.js grew the detector + the guidance first; login.js threw
+// a bare "could not start sign-in (HTTP 424)" — a dead end sitting directly downstream of
+// the CLI's OWN wrong-instance advice to run `bongos login`. setup.js already requires
+// login.js for runDeviceFlow, so having login.js require setup.js back would close a
+// require cycle. Both now depend on this leaf instead: one source of truth, no cycle.
+//
+// PURE — no fs, no network, no process state; both functions unit-test standalone.
+
+// Does this /auth/device/start response carry GitHub's device_flow_disabled refusal?
+//
+// Matches on TEXT, not status, deliberately: the CLI talks to many core versions, and the
+// server envelope moved from 502 to 424 (a 502 body was being eaten by the CDN). Both
+// register. Must NOT match auth_not_configured or any other upstream failure — those have
+// different cures, and a wrong cure is worse than a generic error.
+function isDeviceFlowDisabled(start) {
+  if (!start || start.ok) return false;
+  const err = start.data && start.data.error;
+  const text = [
+    typeof err === 'string' ? err : '',
+    err && typeof err === 'object' ? `${err.code || ''} ${err.message || ''}` : '',
+    start.data && start.data.message ? String(start.data.message) : '',
+  ].join(' ');
+  return /device_flow_disabled/i.test(text);
+}
+
+// The plain-language guidance: what happened, the web route that works RIGHT NOW, and the
+// owner's one-checkbox repair. Returns an array of lines (the callers join them).
+//
+// `finish` names the caller, because only the closing move differs: setup prompts for the
+// token inline ("paste it below"), login has no such prompt and must tell you to run the
+// one-liner instead. Everything above that step is genuinely shared and stays shared.
+function deviceFlowFallbackLines(base, { finish = 'setup' } = {}) {
+  const settings = `${base}/builders/settings`;
+  const close = finish === 'login'
+    ? [
+      '  3. Copy the one-liner it shows and run it in this shell — that writes',
+      '     the same session `bongos login` would have.',
+    ]
+    : [
+      '  3. Copy the token it shows and paste it below (or run the printed',
+      '     one-liner in another shell, then re-run setup).',
+    ];
+  return [
+    '',
+    "This project's GitHub App has Device Flow switched off, so terminal sign-in",
+    'cannot start. Apps created by the one-click setup begin this way — GitHub',
+    'only offers the switch as a checkbox in the App settings; no setup flow can',
+    'tick it automatically.',
+    '',
+    'Sign in through the web instead (works right now):',
+    `  1. Open ${settings} and sign in with GitHub.`,
+    '  2. Under "CLI Access", click "Re-issue CLI token".',
+    ...close,
+    '',
+    'To repair terminal sign-in for everyone (the project owner, once):',
+    '  GitHub → Settings → Developer settings → GitHub Apps → your app →',
+    '  check "Enable Device Flow" → Save. Web sign-in is unaffected either way.',
+  ];
+}
+
+module.exports = { isDeviceFlowDisabled, deviceFlowFallbackLines };

package/scripts/gds/gate-review.js

@@ -38,8 +38,11 @@
 
 const { execFileSync } = require('node:child_process');
 const fs = require('node:fs');
-const permPath = require('../../src/bongos/permission-path-check');
-const { PROTECTED_GLOBS, globToRegExp } = permPath;
+// Destructured AT the require, not off a held module object: knip's static pass
+// cannot follow `const x = require(...); const { y } = x;` and reports `y` as an
+// unused export, which reds the CI knip step (this file's own CLAUDE.md records
+// the same trap for src/instance-config.js).
+const { PROTECTED_GLOBS, compileGlobMatcher } = require('../../src/bongos/permission-path-check');
 
 // --- HARD FLOOR (rank-independent ESCALATE) -------------------------------------------
 // A subset of PROTECTED_GLOBS: the surfaces that, if a compromised/injected senior
@@ -89,12 +92,17 @@ const AUTO_NARROWING = {
   '.husky/secrets-allowlist.txt': certifyAllowlistNarrowing,
 };
 
-const COMPILED_HARD = HARD_FLOOR_GLOBS.map((g) => ({ glob: g, re: globToRegExp(g) }));
-const matchesHardFloor = (f) => COMPILED_HARD.some((c) => c.re.test(f));
+// task 1002874: compile through the authoritative module's FOLDING matcher, not
+// globToRegExp directly. Both of these used to build their own byte-exact regexes
+// from the raw globs and test raw candidates, so after protected-path matching
+// gained NFC + case-folding, an uppercased spelling of a gate surface still walked
+// past THIS classifier — the CI auto-merge gate — which is the bypass the fix
+// exists to close. isCanonicalPath below rejects non-NFC and non-ASCII, but it
+// does not case-fold, so it never covered this.
+const matchesHardFloor = compileGlobMatcher(HARD_FLOOR_GLOBS);
 
 // A path is "protected" per the authoritative module.
-const protectedRe = PROTECTED_GLOBS.map((g) => ({ glob: g, re: globToRegExp(g) }));
-const matchesProtected = (f) => protectedRe.some((c) => c.re.test(f));
+const matchesProtected = compileGlobMatcher(PROTECTED_GLOBS);
 
 // Only [\x20-\x7e] path chars, NFC-stable, no leading/trailing whitespace. Defeats the
 // unicode-homoglyph + whitespace-alias evasions (red-team Holes 6/8).