@bongos/core 1.19.724 → 1.19.726

package/scripts/gds/init.js

@@ -525,6 +525,62 @@ function buildReadme(branding = {}) {
   ].join('\n');
 }
 
+// The START-HERE content as an APPENDABLE section, for a repo that already has a
+// README of its own. Fenced by a stable marker so re-running init is idempotent and so
+// an owner can find (and delete) the block we added.
+//
+// WHY this is not just buildReadme: an ADOPTED repo always has a README, and the
+// write-if-absent rule below therefore skipped the first-run guide on every single adopt
+// — silently, logging "already present — left untouched" as though nothing were owed.
+// That removed the one human-facing instruction to run `npm install`, without which the
+// repo has no `bongos` command at all. Appending mirrors how the adopt path already
+// treats .gitignore: keep what the owner wrote, add only what the instance needs.
+const README_MARKER = '<!-- cloud-bongos:start-here -->';
+
+function buildReadmeSection(branding = {}) {
+  const guide = buildReadme(branding);
+  // Reuse the canonical guide, demoted one heading level so it nests under the owner's
+  // own README, and drop its H1 title (their README already has one).
+  const body = guide
+    .split('\n')
+    .slice(1)                                   // drop "# <product>"
+    .join('\n')
+    .replace(/^## /gm, '### ')
+    .trim();
+  return `${README_MARKER}\n\n## Working on this project (Cloud Bongos)\n\n${body}\n`;
+}
+
+// Append the START-HERE section to an existing README unless it is already there.
+// PURE (text in → text out) so the idempotence is unit-testable without fs.
+// Returns { text, action } where action is 'appended' | 'present'.
+function appendReadmeSection(existing, section) {
+  const prev = String(existing == null ? '' : existing);
+  if (prev.includes(README_MARKER)) return { text: prev, action: 'present' };
+  return { text: `${prev.replace(/\n*$/, '\n')}\n---\n\n${section}`, action: 'appended' };
+}
+
+// Put the first-run guide in the repo's README whichever state it is in: mint the whole
+// guide when there is no README, else append the marked section. Shared by the greenfield
+// and adopt paths so neither can silently owe it. Returns the action taken.
+function layerReadme(branding, { dir, dryRun, log = console.log } = {}) {
+  const readmePath = path.join(dir, 'README.md');
+  if (!fs.existsSync(readmePath)) {
+    if (dryRun) { log(`  [dry-run] would write README.md (first-run START-HERE)`); return 'created'; }
+    fs.writeFileSync(readmePath, buildReadme(branding));
+    log(`  ✓ wrote README.md (first-run START-HERE)`);
+    return 'created';
+  }
+  const { text, action } = appendReadmeSection(fs.readFileSync(readmePath, 'utf8'), buildReadmeSection(branding));
+  if (action === 'present') {
+    log('  • README.md already carries the Cloud Bongos start-here section — left untouched.');
+    return 'present';
+  }
+  if (dryRun) { log('  [dry-run] would append the Cloud Bongos start-here section to the existing README.md'); return 'appended'; }
+  fs.writeFileSync(readmePath, text);
+  log('  ✓ appended the Cloud Bongos start-here section to README.md (your own content is untouched)');
+  return 'appended';
+}
+
 function writeConfigs(spec, { dir, force, dryRun, coreDep, log = console.log }) {
   const configDir = path.join(dir, 'config');
   const brandingPath = path.join(configDir, 'branding.json');
@@ -572,14 +628,9 @@ function writeConfigs(spec, { dir, force, dryRun, coreDep, log = console.log })
   log(`  ✓ wrote ${path.relative(dir, modulesPath)}`);
   log(`  ✓ wrote ${path.relative(dir, hierarchyPath)}`);
   log(`  ✓ wrote ${path.relative(dir, pkgPath)} (pins ${CORE_PKG} → ${pinNote})`);
-  // README START-HERE (task 1002404): write-if-absent so a --force re-init or an
-  // owner's own README is never clobbered.
-  if (!fs.existsSync(readmePath)) {
-    fs.writeFileSync(readmePath, buildReadme(branding));
-    log(`  ✓ wrote ${path.relative(dir, readmePath)} (first-run START-HERE)`);
-  } else {
-    log(`  • ${path.relative(dir, readmePath)} already present — left untouched`);
-  }
+  // README START-HERE (task 1002404): mint it when absent, else APPEND the marked
+  // section. Never a blind overwrite — an owner's own README content always survives.
+  layerReadme(branding, { dir, dryRun: false, log });
   return { brandingPath, modulesPath, hierarchyPath, pkgPath, readmePath, wrote: true };
 }
 
@@ -816,6 +867,10 @@ async function runAdopt(spec, { dir, dryRun, noSeed = false, accept = false, cor
 
   const cfg = layerConfigs(spec, { dir, dryRun, log });
   const pkg = layerPackageJson(spec, { dir, dryRun, log, ...(coreDep ? { coreRange: coreDep } : {}) });
+  // The first-run guide, which adopt used to skip entirely: an adopted repo always has a
+  // README, so the greenfield write-if-absent rule never fired and the one instruction to
+  // run `npm install` was silently owed on every adopt.
+  layerReadme(buildBrandingConfig(spec), { dir, dryRun, log });
 
   // Vendor the pinned core tarball + generate the lockfile, mirroring the greenfield
   // --vendor-core steps, so the adopted repo is `npm ci --omit=dev`-installable (ADR 0108).
@@ -1061,6 +1116,7 @@ module.exports = {
   provisioningSlug, provisioningRequest, productionTopologyKickoff,
   // --adopt (brownfield layering, ADR 0121 / task 2042)
   mergeCoreDependency, coreDepRange, layerConfigs, layerPackageJson, runAdopt,
+  buildReadmeSection, appendReadmeSection, layerReadme, README_MARKER,
   KNOWN_MODULES, HOSTING_SHAPES, CORE_PKG,
   // greenfield installability (ADR 0108 gap 1/4, task 2053)
   buildInstancePackageJson, coreVersionSafe, INSTANCE_START_SCRIPT, INSTANCE_MIGRATE_SCRIPT,

package/scripts/gds/login.js

@@ -23,6 +23,10 @@
 const readline = require('node:readline');
 const { spawnSync } = require('node:child_process');
 const { saveSession, loadStoredSession, listStoredSessions } = require('./cli-lib');
+// The device-flow refusal detector + its plain-language cure (task 1003400). A leaf
+// module, NOT setup.js: setup requires this file for runDeviceFlow, so requiring it
+// back would close a require cycle. Both callers depend on the leaf instead.
+const { isDeviceFlowDisabled, deviceFlowFallbackLines } = require('./device-flow-help');
 const { branding } = require('../../src/branding');
 
 // --- pure helpers (unit-tested) ---------------------------------------------
@@ -102,6 +106,20 @@ async function runDeviceFlow(base, { log, idp = null }) {
   if (start.status === 503 || (start.data && (start.data.error === 'auth_not_configured' || (start.data.error && start.data.error.code === 'idp_signing_unconfigured')))) {
     throw new Error('that instance has no sign-in configured yet — ask its Archon to set it up.');
   }
+  // Device Flow is OFF on every GitHub App born from a manifest, and GitHub exposes no
+  // API to enable it — so terminal sign-in is broken from birth on a fresh instance,
+  // for everyone, until its owner ticks one checkbox. This threw a bare
+  // "could not start sign-in (HTTP 424)", which is where the CLI's OWN wrong-instance
+  // refusal sends every multi-project user: a dead end at the end of our own advice.
+  // In federated mode the device flow runs against the HUB, so the cure is on the hub's
+  // app — point the guidance at whichever origin actually refused.
+  if (isDeviceFlowDisabled(start)) {
+    const refusedBy = idp ? idp.origin : base;
+    throw new Error([
+      'GitHub refused the device-code request for this project.',
+      ...deviceFlowFallbackLines(refusedBy, { finish: 'login' }),
+    ].join('\n'));
+  }
   if (!start.ok || !start.data || !start.data.device_code) {
     throw new Error(`could not start sign-in (HTTP ${start.status}).`);
   }

package/scripts/gds/setup.js

@@ -274,45 +274,11 @@ async function promptOnboardingConsent() {
 }
 
 // ── W1: the manifest-born App has Device Flow OFF (task 1003051) ─────────────
-// GitHub creates an App from a manifest with Device Flow unchecked and offers
-// no API to enable it (only a settings checkbox), so on a fresh wizard-born
-// instance the documented CLI sign-in is hard-broken until the owner ticks the
-// box. Detect the proxied refusal (POST /auth/device/start surfaces GitHub's
-// device_flow_disabled — task 2126's envelope) and fall back to the hall's
-// CLI-token path so setup still completes. Pure; exported for tests.
-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 fallback guidance (task 1003051): what happened, the web
-// path that works right now, and the one-checkbox owner fix. Pure; exported.
-function deviceFlowFallbackLines(base) {
-  const settings = `${base}/builders/settings`;
-  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".',
-    '  3. Copy the token it shows and paste it below (or run the printed',
-    '     one-liner in another shell, then re-run setup).',
-    '',
-    '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.',
-  ];
-}
+// The detector + the guidance moved to ./device-flow-help (task 1003400) so
+// `bongos login` can use the same words without closing a require cycle back
+// through this file (setup requires login for runDeviceFlow). Re-exported here
+// because both are part of setup.js's tested public surface.
+const { isDeviceFlowDisabled, deviceFlowFallbackLines } = require('./device-flow-help');
 
 // Verify a hall-minted CLI token against /me and save the session (the
 // paste-token.js contract: nothing is written unless the token verifies).

package/src/bongos/permission-path-check.js

@@ -140,13 +140,80 @@ function escapeRe(s) {
   return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
 }
 
-const COMPILED = PROTECTED_SURFACES.map((s) => ({ ...s, re: globToRegExp(s.glob) }));
+// task 1002874: the glob is normalised ONCE here, at build, not per candidate —
+// there are 51 surfaces and `matchProtected` runs over every changed file on the
+// push/claim/grade path. `s.glob` itself is kept VERBATIM on the entry, because it
+// is what gets reported back to a refused builder and in the registry's own docs;
+// only the compiled matcher is folded.
+const COMPILED = PROTECTED_SURFACES.map((s) => ({ ...s, re: globToRegExp(foldForMatch(s.glob)) }));
 
 // Normalize a path the way git reports it (forward slashes, no leading ./).
+// normalize — put a path in the ONE spelling matching happens in.
+//
+// task 1002874 (ADR 0151 §4, the last piece of R101's scope): this used to do
+// only backslash→slash and strip a leading './', so matching was exact-BYTES. On
+// a case-insensitive filesystem — macOS by default, and Windows, i.e. the two
+// platforms most builders use — `Src/Bongos/Auth.js` and `src/bongos/auth.js` name
+// the SAME file, and only one of them matched the protected-surface glob. Unicode
+// composition does the same thing invisibly: NFD (`e` + U+0301) and NFC (`é`) are
+// different byte strings for one filename, and a checkout can hand you either.
+// A protected-path wall you can step over by spelling is not a wall.
+//
+// BOTH SIDES go through this — the candidate here, and every registry glob ONCE at
+// COMPILED build — so the transform is applied symmetrically and matching cannot
+// become narrower. It is a strict widening: any pair that matched byte-for-byte
+// still matches after both are folded the same way. The only regression shape is
+// OVER-protection, surfacing as an unexpected claim/push refusal, never a silent
+// un-protection.
+//
+// CASE FOLD: `toLowerCase()`, and that IS the invariant fold here. The Turkish-I
+// hazard the ADR warns about belongs to `toLocaleLowerCase('tr')`, which maps
+// 'I' → 'ı' (dotless) — measured. Plain `toLowerCase()` is Unicode Default Case
+// Conversion and is locale-independent by specification, so it is the correct
+// primitive and `toLocaleLowerCase` is the one that must never appear on this
+// path. A test asserts it does not.
+//
+// ORDER: NFC first, then fold. Measured equivalent to folding first for the
+// composed-accent cases, and NFC-first keeps the input in one canonical form
+// before any other transform reasons about it.
 function normalize(p) {
   return String(p || '').replace(/\\/g, '/').replace(/^\.\//, '').trim();
 }
 
+// foldForMatch — the spelling MATCHING happens in. Separate from normalize() on
+// purpose: normalize() still produces the path we REPORT, and that must keep its
+// original case. A finding, a refusal message and a grader issue all carry
+// `file`, and on a case-sensitive filesystem (Linux, i.e. CI) a lowercased path
+// names nothing — a consumer that tried to read it would get ENOENT for a file
+// that exists.
+function foldForMatch(p) {
+  return normalize(p).normalize('NFC').toLowerCase();
+}
+
+// compileGlobMatcher(globs) → (file) => boolean, with the fold applied to BOTH
+// sides: each glob once here, the candidate on every call.
+//
+// task 1002874: this exists because `globToRegExp` + the raw `PROTECTED_GLOBS`
+// are BOTH exported, and a consumer that compiles them itself gets a byte-exact
+// matcher — which is precisely the wall this task removed, rebuilt by accident.
+// gate-review.js had done exactly that (its ESCALATE / HARD_FLOOR classifier),
+// so an uppercased spelling still slipped past CI's auto-merge gate after the
+// matcher here was fixed. Anything matching a PROTECTED-surface list should
+// compile through this, not through globToRegExp directly.
+//
+// NOT a blanket replacement for globToRegExp, deliberately. Folding widens what
+// matches, and that is only safe when matching more means protecting more. On an
+// ALLOW-list — publish-manifest's PUBLISH_ALLOWLIST, which decides what reaches
+// the public OSS mirror — widening would publish MORE files. Those lists keep
+// the exact matcher on purpose.
+function compileGlobMatcher(globs) {
+  const compiled = (globs || []).map((g) => globToRegExp(foldForMatch(g)));
+  return (file) => {
+    const folded = foldForMatch(file);
+    return folded ? compiled.some((re) => re.test(folded)) : false;
+  };
+}
+
 // Which of `files` are permission-sensitive? Returns
 // [{ file, glob, floor, permission }] — floor + permission come straight from the
 // registry entry that matched, so a governance re-map flows through every caller.
@@ -155,7 +222,11 @@ function matchProtected(files) {
   for (const raw of files || []) {
     const f = normalize(raw);
     if (!f) continue;
-    const hit = COMPILED.find((c) => c.re.test(f));
+    // Match on the FOLDED spelling, report the original one — see foldForMatch.
+    // Hoisted OUT of the predicate on purpose: inside it, the fold re-runs once
+    // per registry surface (51 today) for every candidate file.
+    const folded = foldForMatch(raw);
+    const hit = COMPILED.find((c) => c.re.test(folded));
     if (hit) out.push({ file: f, glob: hit.glob, floor: hit.floor, permission: hit.permission });
   }
   return out;
@@ -164,7 +235,8 @@ function matchProtected(files) {
 // The registry entry governing `file`, or null when the path is unprotected.
 function surfaceFor(file) {
   const f = normalize(file);
-  const hit = f ? COMPILED.find((c) => c.re.test(f)) : null;
+  const folded = f ? foldForMatch(file) : '';
+  const hit = f ? COMPILED.find((c) => c.re.test(folded)) : null;
   return hit ? { glob: hit.glob, floor: hit.floor, permission: hit.permission, group: hit.group, why: hit.why } : null;
 }
 
@@ -271,6 +343,11 @@ module.exports = {
   REGISTRY_PATH,
   SPECIALTY,
   globToRegExp,
+  compileGlobMatcher,
+  // foldForMatch is deliberately NOT exported: it is the internal spelling rule,
+  // and every caller should go through compileGlobMatcher so the fold is applied
+  // to BOTH sides. Handing it out invites a consumer to fold one side only, which
+  // is the asymmetry that breaks matching outright.
   matchProtected,
   surfaceFor,
   floorFor,

package/src/bongos/repo-info.js

@@ -12,10 +12,11 @@
 // transfers, the deploy's git remote changes and the served links follow,
 // with zero code edits required.
 //
-// Cached on first call. Falls back to env vars (OTB_GITHUB_OWNER /
-// OTB_GITHUB_REPO / OTB_GITHUB_BRANCH) for environments where git isn't
-// available (e.g. a stripped-down container deploy). Returns { error } when
-// neither source resolves, so callers can degrade gracefully.
+// Cached on first call. Three sources, in order: env vars (OTB_GITHUB_OWNER /
+// OTB_GITHUB_REPO / OTB_GITHUB_BRANCH — the operator's explicit override), the git
+// remote when this package IS the repo, then the instance's committed branding pack
+// (config/branding.json `repo`) — the source a standalone instance actually has.
+// Returns { error } when none resolves, so callers can degrade gracefully.
 
 const { execSync } = require('node:child_process');
 const path = require('node:path');
@@ -44,6 +45,34 @@ function loadFromEnv() {
   return null;
 }
 
+// The instance's OWN declared GitHub binding, read from the committed branding pack
+// (`config/branding.json` -> `repo: { owner, name }` — a first-class key in the
+// branding contract). `bongos init` writes it at scaffold time, so a standalone
+// instance carries the correct answer on disk from birth.
+//
+// WHY it exists: an installed core (ADR 0140) lives in node_modules/@bongos/core, so
+// loadFromGit's anchor rule correctly returns null — and nothing sets
+// <PREFIX>_GITHUB_OWNER/REPO on a provisioned instance. EVERY standalone instance
+// therefore resolved no_repo_info and served a 503 from /public/repo-info, with public
+// build status and every repo-linked surface dead. The identity was one file away the
+// whole time, simply never read.
+//
+// Placed LAST in the chain on purpose: the env pin stays the operator's explicit
+// override and git stays authoritative for the core dev checkout, so this source can
+// only ever turn an ERROR into an answer — it can never change one that already
+// resolved. Required lazily so module load order never depends on branding, and
+// fail-soft: a malformed or absent pack must degrade to no_repo_info, not crash boot.
+function loadFromBranding(deps = {}) {
+  try {
+    const read = deps.branding || require('../branding').branding;
+    const pack = read() || {};
+    const owner = pack.repo && String(pack.repo.owner || '').trim();
+    const name = pack.repo && String(pack.repo.name || '').trim();
+    if (owner && name) return { owner, repo: name };
+  } catch (_) { /* fall through — an unreadable pack is not an answer */ }
+  return null;
+}
+
 // The directory this file's package occupies: <root>/src/bongos -> <root>. In the core
 // dev checkout that is the repo root; installed, it is node_modules/@bongos/core.
 const PACKAGE_ROOT = path.resolve(__dirname, '..', '..');
@@ -92,12 +121,13 @@ function loadFromGit(deps = {}) {
 function loadRepoInfo(deps = {}) {
   if (cached) return cached;
   const branch = ic.resolveEnv('GITHUB_BRANCH') || 'main';
-  const parsed = loadFromEnv() || loadFromGit(deps);
+  const parsed = loadFromEnv() || loadFromGit(deps) || loadFromBranding(deps);
   if (!parsed) {
     cached = {
       error: 'no_repo_info',
       detail:
-        'git remote origin not resolvable from this package (an installed core does not sit inside the repo it publishes to) and <PREFIX>_GITHUB_OWNER/REPO unset',
+        'git remote origin not resolvable from this package (an installed core does not sit inside the repo it publishes to), '
+        + 'config/branding.json has no repo.owner/repo.name, and <PREFIX>_GITHUB_OWNER/REPO unset',
     };
     return cached;
   }
@@ -123,5 +153,6 @@ module.exports = {
   loadRepoInfo,
   parseRemote,
   loadFromGit, // exported for unit tests — the anchor rule is the whole fix
+  loadFromBranding, // exported for unit tests — the standalone-instance source
   _resetCacheForTests,
 };

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.724'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
+const CORE_VERSION = '1.19.726'; // 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');
@@ -427,6 +427,13 @@ module.exports = {
   //     directly. Resolved lazily so requiring the doorway never forces a config
   //     read at module-load (BV1.R81 / ADR 0093 §1).
   enabledDisciplines: (...a) => require('./modules').enabledDisciplines(...a),
+  //     isModuleEnabled(name) — is THIS module on for this instance? A module needs
+  //     it when its own behaviour depends on ANOTHER module being present: onboarding
+  //     posts a Discord approve/decline control whose 👍 is only ever applied by the
+  //     `discord` module's reaction handler, so with discord off the control is a lie
+  //     and must not be posted at all. Throws on an unknown name (a typo is a bug, not
+  //     a silent false). Lazy, like its sibling above.
+  isModuleEnabled: (...a) => require('./modules').isModuleEnabled(...a),
 
   // --- the seam registry — how modules cooperate without importing each other.
   //     Three primitives: PORTS (one required provider), EVENTS (many optional

package/tests/adopt_preflight.mjs

@@ -101,5 +101,77 @@ t('preflightAdopt: a clean repo → no blocking; every category reports', () =>
   } finally { rmSync(dir, { recursive: true, force: true }); }
 });
 
+// ---- ignored-incoming: the check that was missing (task 1003400) ----------
+//
+// The failure it exists to stop: adopt onto a repo whose .gitignore already carries
+// `.claude/`. The skills/hooks/settings are written to disk, `git add` drops them, the
+// commit looks clean, and every clone of that repo is missing its /builder-* commands
+// with nothing anywhere saying why.
+
+t('checkIgnoredIncoming: an ignored incoming file BLOCKS and names the rule to change', () => {
+  const f = pf.checkIgnoredIncoming([{ path: '.claude/skills', rule: '.gitignore:7:.claude/' }]);
+  assert.equal(f.length, 1);
+  assert.equal(f[0].severity, pf.SEV.BLOCK, 'silent data loss at git add is not a warning');
+  assert.match(f[0].message, /\.claude\/skills/, 'names the swallowed path');
+  assert.match(f[0].message, /\.gitignore:7/, 'names the exact rule line so the owner need not hunt');
+});
+
+t('checkIgnoredIncoming: nothing ignored → INFO, not blocking', () => {
+  const f = pf.checkIgnoredIncoming([]);
+  assert.equal(f[0].severity, pf.SEV.INFO);
+  assert.equal(f.filter((x) => x.severity === pf.SEV.BLOCK).length, 0);
+});
+
+t('checkIgnoredIncoming: probe could not run → INFO that says so, never a false all-clear', () => {
+  const f = pf.checkIgnoredIncoming([], { checked: false });
+  assert.equal(f[0].severity, pf.SEV.INFO);
+  assert.match(f[0].message, /could not run/, 'unknown must not be reported as clean');
+});
+
+t('probeIgnoredIncoming: parses git check-ignore -v into path + rule', () => {
+  const execFileSync = () => '.gitignore:7:.claude/\t.claude/skills\n.gitignore:7:.claude/\t.claude/hooks\n';
+  const { ignored, checked } = pf.probeIgnoredIncoming({ dir: '/x', execFileSync });
+  assert.equal(checked, true);
+  assert.deepEqual(ignored, [
+    { path: '.claude/skills', rule: '.gitignore:7:.claude/' },
+    { path: '.claude/hooks', rule: '.gitignore:7:.claude/' },
+  ]);
+});
+
+t('probeIgnoredIncoming: git exit 1 means NOTHING ignored — a real answer, not a failure', () => {
+  const execFileSync = () => { const e = new Error('exit 1'); e.status = 1; throw e; };
+  assert.deepEqual(pf.probeIgnoredIncoming({ dir: '/x', execFileSync }), { ignored: [], checked: true });
+});
+
+t('probeIgnoredIncoming: no git / not a repo → checked:false, distinct from "clean"', () => {
+  const execFileSync = () => { const e = new Error('not a git repository'); e.status = 128; throw e; };
+  assert.deepEqual(pf.probeIgnoredIncoming({ dir: '/x', execFileSync }), { ignored: [], checked: false });
+});
+
+t('probeIgnoredIncoming: strips our trailing dir slashes before handing paths to git', () => {
+  let input = null;
+  const execFileSync = (_cmd, _args, opts) => { input = opts.input; return ''; };
+  pf.probeIgnoredIncoming({ dir: '/x', incoming: ['.claude/hooks/', 'package.json'], execFileSync });
+  assert.equal(input, '.claude/hooks\npackage.json', 'git check-ignore wants plain pathnames');
+});
+
+t('preflightAdopt (end to end): mercury\'s .gitignore would have BLOCKED the adopt', () => {
+  const dir = mkdtempSync(join(tmpdir(), 'pf-ignored-'));
+  try {
+    // The exact rule that swallowed the methodology surface on the real repo.
+    writeFileSync(join(dir, '.gitignore'), '.env\nvenv/\n\n#claude code\n.claude/\n');
+    const report = pf.preflightAdopt({
+      dir,
+      stack: { migrationsDirs: [], topLevelDirs: [], ci: [] },
+      // Stand in for git so the case is hermetic (no repo needed in tmp).
+      execFileSync: () => '.gitignore:5:.claude/\t.claude/settings.json\n.gitignore:5:.claude/\t.claude/skills\n',
+    });
+    assert.ok(report.hasBlocking, 'adopt must stop rather than produce a silently broken instance');
+    const found = cats(report.findings, 'ignored-incoming');
+    assert.equal(found.length, 1);
+    assert.equal(found[0].severity, pf.SEV.BLOCK);
+  } finally { rmSync(dir, { recursive: true, force: true }); }
+});
+
 console.log(`\nadopt_preflight: ${passed} passed, ${failed} failed`);
 process.exit(failed ? 1 : 0);

package/tests/bongos_login.mjs

@@ -1,11 +1,20 @@
-// tests/bongos_login.mjs — pure helpers behind `bongos login <instance>`
-// (V4.R83 / task 1250). DB-free + network-free. Picked up by run-unit-tests.js.
+// tests/bongos_login.mjs — the helpers and the failure surface behind
+// `bongos login <instance>` (V4.R83 / task 1250). DB-free; the one end-to-end case
+// drives the real CLI against a 127.0.0.1 stub, so it needs no network either.
+// Picked up by run-unit-tests.js.
 import assert from 'node:assert/strict';
 import { test } from 'node:test';
 import { createRequire } from 'node:module';
+import { spawn } from 'node:child_process';
+import http from 'node:http';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
 
 const require = createRequire(import.meta.url);
 const { normalizeInstanceBase, pollDecision } = require('../scripts/gds/login.js');
+const LOGIN_JS = path.join(path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..'), 'scripts', 'gds', 'login.js');
 
 test('normalizeInstanceBase adds https, strips trailing slashes + a pasted /api/gds', () => {
   assert.equal(normalizeInstanceBase('amazonprimea.com'), 'https://amazonprimea.com');
@@ -32,3 +41,61 @@ test('pollDecision maps the /access-requests/status body to a loop action', () =
   assert.equal(pollDecision(null), 'wait');
   assert.equal(pollDecision({}), 'wait');
 });
+
+// ---- the Device-Flow dead end (task 1003400) -------------------------------
+//
+// Device Flow is OFF on every GitHub App created from a manifest and GitHub offers no
+// API to switch it on, so terminal sign-in is broken from birth on a fresh instance —
+// for every builder. `bongos login` used to answer that with a bare
+// "could not start sign-in (HTTP 424)": no cause, no cure, and sitting directly
+// downstream of the CLI's own wrong-instance advice to run `bongos login`.
+//
+// Drives the REAL CLI against a stub replaying the exact body a live instance returned.
+
+test('login on a Device-Flow-disabled instance explains the cause and the cure', async () => {
+  const server = http.createServer((req, res) => {
+    const send = (code, body) => {
+      res.writeHead(code, { 'Content-Type': 'application/json' });
+      res.end(JSON.stringify(body));
+    };
+    if (req.url.endsWith('/api/gds/instance')) {
+      return send(200, { schema: 'instance-manifest/v1', name: 'Stub', admission: { policy: 'invite-only' } });
+    }
+    if (req.url.endsWith('/api/gds/auth/device/start')) {
+      // Byte-for-byte what a real instance returned when its App had the box unticked.
+      return send(424, { error: { code: 'device_start_failed', message: 'device/code failed (400): {"error":"device_flow_disabled","error_description":"Device Flow must be explicitly enabled for this App"}' } });
+    }
+    return send(404, { error: { code: 'not_found' } });
+  });
+  server.listen(0, '127.0.0.1');
+  await new Promise((r) => server.once('listening', r));
+  const base = `http://127.0.0.1:${server.address().port}`;
+  // A throwaway HOME so the run can never read or write the real session.
+  const home = fs.mkdtempSync(path.join(os.tmpdir(), 'login-df-'));
+
+  // spawn, not execFileSync: the stub server lives in THIS process, so a synchronous
+  // child would block the event loop that has to answer it — a deadlock, not a failure.
+  let out = '';
+  try {
+    out = await new Promise((resolve, reject) => {
+      const child = spawn(process.execPath, [LOGIN_JS, base], {
+        stdio: ['ignore', 'pipe', 'pipe'],
+        env: { ...process.env, HOME: home, USERPROFILE: home },
+      });
+      let buf = '';
+      child.stdout.on('data', (d) => { buf += d; });
+      child.stderr.on('data', (d) => { buf += d; });
+      const timer = setTimeout(() => { child.kill('SIGKILL'); reject(new Error('login did not exit')); }, 30000);
+      child.on('close', () => { clearTimeout(timer); resolve(buf); });
+      child.on('error', (e) => { clearTimeout(timer); reject(e); });
+    });
+  } finally {
+    server.close();
+    fs.rmSync(home, { recursive: true, force: true });
+  }
+
+  assert.doesNotMatch(out, /could not start sign-in \(HTTP 424\)/, 'the bare dead end is gone');
+  assert.match(out, /Device Flow switched off/, 'names the actual cause');
+  assert.match(out, /Enable Device Flow/, 'names the owner\'s one-checkbox repair');
+  assert.match(out, /works right now/, 'names a route that works while the owner fixes it');
+});

package/tests/claude_materialize.mjs

@@ -510,6 +510,15 @@ t('renderInstanceClaudeMd: brand-substituted — names the instance + its hall/c
   assert.ok(!md.toLowerCase().includes('amazonprimea') && !md.includes('~/.config/otb'), 'no founder literal in the starter');
 });
 
+t('renderInstanceClaudeMd: the first-run bootstrap precedes every bongos instruction', () => {
+  const md = tmpl.renderInstanceClaudeMd({ identity: { productName: 'Acme' } });
+  const iNpm = md.indexOf('npm install');
+  const iStart = md.indexOf('bongos start');
+  assert.ok(iNpm > 0, 'names npm install at all — without it a fresh clone has no bongos command');
+  assert.ok(iStart > iNpm, 'npm install comes BEFORE the first bongos instruction, or the agent hits command not found');
+  assert.ok(/@bongos\/core/.test(md), 'explains WHY: the CLI ships inside the dependency');
+});
+
 t('renderInstanceClaudeMd: degrades cleanly on a minimal branding (no world dup, defaults currency)', () => {
   const md = tmpl.renderInstanceClaudeMd({ identity: { productName: 'Solo', worldName: 'Solo' } });
   assert.ok(md.startsWith('# Solo — Project Memory'));

package/tests/discord_approvals.mjs

@@ -170,5 +170,50 @@ await t('a DB error returns {error}, never throws', async () => {
   assert.equal(r.outcome, 'error');
 });
 
+// ---- the outbound half must not outlive the inbound half (task 1003400) ----
+//
+// The 👍 this line invites is applied ONLY by discord-approvals.js, which lives in the
+// `discord` module. onboarding (which posts) is default-ON; discord is default-OFF; and
+// nothing gated one on the other. A default instance therefore posted a working-looking
+// approve/decline control into a channel where no handler was listening — an Archon
+// reacts, sees it land, and believes they admitted a builder who is still locked out.
+
+await t('discord module OFF → the control is NOT posted', async () => {
+  let posted = false;
+  const r = await bcast.postMemberApprovalRequest(
+    { id: 7, github_login: 'carol' },
+    { postWebhook: async () => { posted = true; }, log: () => {}, isModuleEnabled: () => false },
+  );
+  assert.equal(posted, false, 'a 👍 nobody applies must never be invited');
+  assert.equal(r.skipped, 'discord_module_off');
+  assert.equal(r.posted, false);
+});
+
+await t('discord module ON → the control posts exactly as before', async () => {
+  let line = null;
+  const r = await bcast.postMemberApprovalRequest(
+    { id: 7, github_login: 'carol' },
+    { postWebhook: async (_ch, l) => { line = l; }, log: () => {}, isModuleEnabled: () => true },
+  );
+  assert.equal(r.posted, true, 'the working path is untouched');
+  assert.deepEqual(ap.parseApprovalMarker(line), { kind: 'member', id: 7 }, 'and still round-trips');
+});
+
+await t('enablement unresolvable → fails CLOSED (no post)', async () => {
+  let posted = false;
+  const r = await bcast.postMemberApprovalRequest(
+    { id: 7, github_login: 'carol' },
+    { postWebhook: async () => { posted = true; }, log: () => {}, isModuleEnabled: () => { throw new Error('config unreadable'); } },
+  );
+  assert.equal(posted, false, 'a state we cannot vouch for is not a state we post into');
+  assert.equal(r.skipped, 'discord_module_off');
+});
+
+await t('the gate is reachable through the published doorway, not a direct core require', async () => {
+  const doorway = require('../src/module-api.js');
+  assert.equal(typeof doorway.isModuleEnabled, 'function', 'ADR 0083: modules read enablement here');
+  assert.throws(() => doorway.isModuleEnabled('no-such-module'), /unknown module/, 'a typo must be a bug, not a silent false');
+});
+
 console.log(`\n${passed} passed, ${failed} failed`);
 process.exit(failed ? 1 : 0);