@bongos/core 1.24.69 → 1.24.70

package/scripts/bongos/fitness-lib.js

@@ -11,7 +11,7 @@
 
 const fs = require('node:fs');
 const path = require('node:path');
-const { resolveCoreRoot, resolveInstanceRoot } = require('../../src/instance-config'); // ADR 0108 §1: configurable-root
+const { resolveCoreRoot, resolveInstanceRoot, resolveInstanceRootExplicit } = require('../../src/instance-config'); // ADR 0108 §1: configurable-root
 
 
 // ADR 0108 §Consequences #4 (configurable-root W6 / task 1886) — the guardrail walks TWO trees.
@@ -97,6 +97,23 @@ function isInstalledCore(root = CORE_ROOT) {
   } catch { return true; } // a package with no repo around it at all
 }
 
+// resolveWorkRoot — the tree a repo-wide tool (docs-entropy, ship-check) works on (task 1005100).
+// A core CHECKOUT works on itself, whatever the cwd, exactly as path.resolve(__dirname,'..','..')
+// always did. An INSTALLED core's package dir is not the project — `git ls-files` there finds
+// nothing and the generators read the package's own files — so it works on the project instead:
+// an explicit pointer (<PREFIX>_INSTANCE_ROOT / bongos.config.json), else the git top of the cwd
+// (`npx bongos exec` runs from the project), else the cwd.
+function gitTopOf(cwd) {
+  try {
+    return require('node:child_process').execFileSync('git', ['rev-parse', '--show-toplevel'], { cwd, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim() || null;
+  } catch { return null; }
+}
+function resolveWorkRoot({ installed, cwd = process.cwd(), explicit = resolveInstanceRootExplicit, gitTop = gitTopOf } = {}) {
+  if (installed === undefined) installed = isInstalledCore();
+  if (!installed) return CORE_ROOT;
+  return explicit() || gitTop(cwd) || cwd;
+}
+
 // runChecks — run every fitness check, or none (task 1004737). Every check guards the core's
 // own source, and an INSTALLED core's source is not the project's to change: the core repo's
 // CI ran this gate before publishing it (the same stance ship-merge-gate.js takes for a
@@ -115,6 +132,7 @@ function runChecks(checks, { installed = isInstalledCore() } = {}) {
 
 module.exports = {
   isInstalledCore,
+  resolveWorkRoot,
   runChecks,
   keyTokenRe,
   CORE_ROOT,

package/scripts/bongos/paste-token.js

@@ -8,6 +8,8 @@
 //
 // Usage:
 //   bongos paste-token <token>          # what the hall hands you (task 1003961)
+//   bongos paste-token                  # no argument: asks for the token without echo,
+//                                       # or reads it from stdin when piped (task 1005033)
 //   node scripts/bongos/paste-token.js <token>   # equivalent, inside a core checkout
 //
 // The portal returns the exact invocation as the "paste_command" field, so a
@@ -83,10 +85,71 @@ const ARGS = parseArgs(process.argv.slice(2));
 const RESOLVED = resolveBaseForPaste({ flag: ARGS.apiBase });
 const API_BASE = RESOLVED.base;
 
+// READ THE TOKEN WITHOUT PUTTING IT ON THE COMMAND LINE (task 1005033). A token passed
+// as an argument lands in shell history. With no argument we ask for it: on a terminal
+// the read is raw and nothing is echoed (a 64-char secret has no business on screen
+// either); piped (`... | bongos paste-token`) we take the first word of stdin. The
+// argument form still works — the hall's one-liner uses it, and older instances hand
+// out nothing else. Exported so the no-echo read is tested, not assumed.
+function readTokenFromInput({ input = process.stdin, output = process.stderr } = {}) {
+  if (!input.isTTY) {
+    // Piped: settle on the FIRST line, not at end of stream — a pipe that never closes
+    // must not hang the paste, and nothing after the token is ours to buffer.
+    return new Promise((resolve, reject) => {
+      let data = '';
+      let settled = false;
+      const settle = () => {
+        if (settled) return;
+        settled = true;
+        input.removeListener('data', onData);
+        input.pause();
+        resolve(data.trim().split(/\s+/)[0] || '');
+      };
+      function onData(c) {
+        data += c;
+        if (data.replace(/^\s+/, '').includes('\n')) settle();
+      }
+      input.setEncoding('utf8');
+      input.on('data', onData);
+      input.on('end', settle);
+      input.on('error', (err) => { if (!settled) { settled = true; reject(err); } });
+    });
+  }
+  output.write('Paste your CLI token (Settings → CLI Access) and press Enter: ');
+  return new Promise((resolve, reject) => {
+    let buf = '';
+    const raw = typeof input.setRawMode === 'function';
+    if (raw) input.setRawMode(true);
+    input.setEncoding('utf8');
+    input.resume();
+    function finish(err) {
+      input.removeListener('data', onData);
+      if (raw) input.setRawMode(false);
+      input.pause();
+      output.write('\n');
+      if (err) reject(err); else resolve(buf.trim());
+    }
+    function onData(chunk) {
+      for (const ch of String(chunk)) {
+        if (ch === '\r' || ch === '\n') { finish(); return; }
+        // Ctrl+C always cancels; Ctrl+D (end of input) cancels too unless a token is typed.
+        if (ch === '\u0003' || (ch === '\u0004' && !buf.trim())) { finish(new Error('cancelled — nothing was saved')); return; }
+        if (ch === '\u0004') { finish(); return; }
+        if (ch === '\u007f' || ch === '\b') { buf = buf.slice(0, -1); continue; }
+        buf += ch;
+      }
+    }
+    input.on('data', onData);
+  });
+}
+
 function usage(extra) {
   if (extra) console.error(extra);
   console.error('');
-  console.error('Usage: npx bongos paste-token <token> [--api-base <url>]');
+  console.error('Usage: npx bongos paste-token [<token>] [--api-base <url>]');
+  console.error('   Leave out <token> and it asks for it, so the token stays out of shell history.');
+  console.error('   Run it from inside your project folder (cd there first).');
+  console.error('   In Windows PowerShell type npx.cmd instead of npx.');
   console.error('   (inside a core checkout: node scripts/bongos/paste-token.js <token>)');
   console.error('');
   // Fall back to the inferred base for this hint when --api-base was the thing that
@@ -103,9 +166,17 @@ async function main() {
     usage(`--api-base must be an http(s) URL, got: ${ARGS.apiBase}`);
     process.exit(2);
   }
-  const token = ARGS.token;
+  let token = ARGS.token;
+  if (!token) {
+    try {
+      token = await readTokenFromInput();
+    } catch (err) {
+      console.error(`paste-token: ${err.message}`);
+      process.exit(2);
+    }
+  }
   if (!token) {
-    usage('No token argument provided.');
+    usage('No token given.');
     process.exit(2);
   }
   // Tokens are hex-encoded crypto.randomBytes(32) → 64 lowercase hex chars.
@@ -209,4 +280,4 @@ if (require.main === module) {
   });
 }
 
-module.exports = { parseArgs, resolveBaseForPaste };
+module.exports = { parseArgs, resolveBaseForPaste, readTokenFromInput };

package/scripts/bongos/ship-check.js

@@ -21,7 +21,12 @@ const { spawnSync } = require('node:child_process');
 const fs = require('node:fs');
 const path = require('node:path');
 
-const REPO_ROOT = path.resolve(__dirname, '..', '..');
+// Two roots (task 1005100). CORE_ROOT is where the step scripts live; WORK_ROOT is the tree they
+// check. In a project that installs the core they differ: running the generators from the
+// package dir checked the package's files, so gen-api-docs read STALE while the same --check
+// run from the project said up to date. In a core checkout both are this checkout.
+const CORE_ROOT = path.resolve(__dirname, '..', '..');
+const WORK_ROOT = require('./fitness-lib.js').resolveWorkRoot();
 
 // Each step: a label, the argv to run (node scripts run with THIS node), the command that heals it,
 // and how to read a non-zero exit. `optional` steps are skipped when their script is absent. An `advisory`
@@ -45,8 +50,11 @@ const STEPS = [
   { key: 'tests', label: 'DB-free unit lane (npm test)', argv: ['scripts/bongos/run-unit-tests.js'], fix: 'read the FAIL lines; compare against origin/main before calling any of them environmental', onlyWith: '--tests', slow: true },
 ];
 
-function runStep(step, { cwd = REPO_ROOT } = {}) {
-  const script = path.join(cwd, step.argv[0]);
+// A caller that passes only `cwd` (tests) gets scripts resolved there too, as before.
+function runStep(step, { cwd, coreRoot } = {}) {
+  coreRoot = coreRoot || cwd || CORE_ROOT;
+  cwd = cwd || WORK_ROOT;
+  const script = path.join(coreRoot, step.argv[0]);
   if (!fs.existsSync(script)) return { ...step, status: step.optional ? 'skipped' : 'missing', ms: 0, tail: `${step.argv[0]} not present` };
   const t0 = Date.now();
   const r = spawnSync(process.execPath, [script, ...step.argv.slice(1)], { cwd, encoding: 'utf8', timeout: step.slow ? 15 * 60 * 1000 : 5 * 60 * 1000, env: { ...process.env, GDS_QUIET: '1' } });

package/src/bongos/device-flow-blocker.js

@@ -0,0 +1,56 @@
+'use strict';
+// src/bongos/device-flow-blocker.js — tell the OWNER, loudly, that terminal sign-in is off
+// (task 1005033).
+//
+// WHY. GitHub creates an App from a manifest with Device Flow OFF and has no API to switch it
+// on — only a checkbox in the App's settings. Until the owner ticks it, every builder's
+// `bongos setup` / `bongos login` is refused, and the only person told was that builder, in a
+// terminal, who cannot fix it. The provisioning checklist shows the step as optional
+// ("later"), which no owner reads as urgent. So the first time this server sees GitHub's
+// device_flow_disabled refusal it files ONE blocker for the owner, through the ideas
+// module's `ideas.fileBlocker` port (core never imports a module). The writer is idempotent
+// on (source, source_ref), so a thousand refused sign-ins still make one blocker.
+//
+// Best effort by construction: no ideas module, a refused write or a DB hiccup changes
+// nothing about the sign-in reply the builder gets. Never throws, never rejects.
+
+const seams = require('../module-seams');
+
+const SOURCE = 'auth';
+const SOURCE_REF = 'github-device-flow-disabled';
+
+function isDeviceFlowDisabledReason(reason) {
+  return /device_flow_disabled/i.test(String(reason || ''));
+}
+
+function blockerFor(origin) {
+  const settings = origin ? `${origin}/builders/settings` : 'Settings → CLI Access';
+  return {
+    title: 'Terminal sign-in is off: tick "Enable Device Flow" on the GitHub App',
+    bodyMd: [
+      'A builder just tried to sign in from a terminal (`bongos setup` or `bongos login`) and GitHub refused:',
+      'this project\'s GitHub App has **Device Flow switched off**. Apps made by the one-click setup start',
+      'that way, and GitHub offers no way for the setup to switch it on.',
+      '',
+      '**Fix (the project owner, once, about a minute):** GitHub → Settings → Developer settings →',
+      'GitHub Apps → this project\'s app → tick **Enable Device Flow** → Save. Web sign-in is unaffected.',
+      '',
+      `Until then builders can still sign in through the web: ${settings}, "Re-issue CLI token".`,
+    ].join('\n'),
+    source: SOURCE,
+    sourceRef: SOURCE_REF,
+  };
+}
+
+async function raiseDeviceFlowOffBlocker({ reason, origin, resolveOptional = seams.resolveOptional } = {}) {
+  try {
+    if (!isDeviceFlowDisabledReason(reason)) return null;
+    const file = resolveOptional('ideas.fileBlocker', null);
+    if (typeof file !== 'function') return null;
+    return (await file(blockerFor(origin))) || null;
+  } catch (_) {
+    return null;
+  }
+}
+
+module.exports = { raiseDeviceFlowOffBlocker, isDeviceFlowDisabledReason, SOURCE, SOURCE_REF };

package/src/bongos/routes/auth.js

@@ -42,6 +42,7 @@ const { accountExistenceReadRateLimit } = require('../middleware/rate-limit');
 const { branding } = require('../../branding');
 const { resolveEnv, envPrefix } = require('../../instance-config');
 const seams = require('../../module-seams');
+const { raiseDeviceFlowOffBlocker } = require('../device-flow-blocker');
 // task 1003208: structured logging — was console.*. A core file logs through
 // the kernel logger directly; only MODULES go via api.logger (the doorway).
 const log = require('../logger').logger.child({ src: 'auth' });
@@ -623,6 +624,7 @@ module.exports = function buildAuthRouter() {
       // fresh-instance auth failure could only be read via curl on the box itself
       // (finding W2, task 1003052). A 4xx passes the proxy with the JSON intact.
       const reason = String(err && err.message ? err.message : 'internal error').slice(0, 300);
+      raiseDeviceFlowOffBlocker({ reason, origin: WEB_REDIRECT_ORIGIN }); // owner blocker, once (task 1005033)
       res.fail('device_start_failed', { status: 424, message: reason });
     }
   });
@@ -1353,6 +1355,9 @@ module.exports = function buildAuthRouter() {
         paste_command: issuer
           ? `npx bongos paste-token ${token} --api-base ${issuer}`
           : `npx bongos paste-token ${token}`,
+        paste_command_windows: issuer
+          ? `npx.cmd bongos paste-token ${token} --api-base ${issuer}`
+          : `npx.cmd bongos paste-token ${token}`, // task 1005033: PowerShell blocks npx.ps1 by default
       });
     } catch (err) {
       log.error('[gds] POST /auth/cli-token/issue', err);

package/src/module-api.js

@@ -81,7 +81,7 @@ const { sleep } = require('./sleep');
 // MAJOR (see allowBoxScope below): passes the request through untouched.
 function deprecatedNoopMiddleware(_req, _res, next) { next(); }
 
-const CORE_VERSION = '1.24.69'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
+const CORE_VERSION = '1.24.70'; // 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/bongos_cli.mjs

@@ -76,7 +76,8 @@ test('the server emits exactly the verb the CLI registers', () => {
   assert.ok(cmds.length > 0, 'auth.js should emit at least one paste_command template literal');
   for (const cmd of cmds) {
     // `npx bongos <verb> …` since task 1004575 — a clone has no bare `bongos` on PATH.
-    const verb = cmd.replace(/^npx /, '').split(' ')[1];
+    // npx.cmd is the Windows PowerShell form (task 1005033) — same verb after it.
+    const verb = cmd.replace(/^npx(\.cmd)? /, '').split(' ')[1];
     assert.ok(cli.VERBS[verb], `server emits "bongos ${verb}" but the CLI has no such verb`);
   }
 });

package/tests/cli_token_reissue.mjs

@@ -174,11 +174,13 @@ t('paste_command names a CLI VERB, never a filesystem path', () => {
   // applying without anyone editing it.
   const tail = issueBlock.slice(issueBlock.indexOf('paste_command:'));
   const cmds = [...tail.matchAll(/`([^`]*bongos paste-token[^`]*)`/g)].map((m) => m[1]);
-  assert.equal(cmds.length, 2, `expected both ternary branches, got ${cmds.length}`);
+  // Four since task 1005033: paste_command's two branches, then paste_command_windows'
+  // two — the same line with npx.cmd, because npx.ps1 is blocked in a default PowerShell.
+  assert.equal(cmds.length, 4, `expected both ternary branches of both fields, got ${cmds.length}`);
   for (const cmd of cmds) {
   // Through npx (task 1004575): a builder's clone does not put bare `bongos` on
   // PATH, so a bare verb was "command not found" when pasted in the project folder.
-  assert.ok(/^npx bongos paste-token /.test(cmd),
+  assert.ok(/^npx(\.cmd)? bongos paste-token /.test(cmd),
     `paste_command must start with the npx verb form, got: ${cmd}`);
   // The invariant is "names no FILE ON THE RECIPIENT'S DISK", which the original
   // spelling approximated as "contains no slash". That was too broad once the command

package/tests/hall_onboarding_bongos_setup.mjs

@@ -87,7 +87,9 @@ test('Settings CLI access says where to paste the npx command', () => {
   const js = read('modules/hall-ui/public/settings.js');
   assert.match(html, /into a terminal in your project folder/);
   assert.doesNotMatch(html, /bypasses Device Flow/);
-  assert.match(js, /Paste this into a terminal in your project folder:/);
+  // Both spellings (task 1005033) name the project folder AND the cd that gets there.
+  assert.match(js, /Open a terminal, cd into your project folder first \(the command only runs there\), then paste this:/);
+  assert.match(js, /Open PowerShell, cd into your project folder first \(the command only runs there\), then paste this:/);
 });
 
 test('the npx paste command Settings hands out is pre-approved for a Claude session', () => {

package/tests/hall_settings_world.mjs

@@ -338,8 +338,8 @@ test('the CLI token reaches the page as text, not as markup', () => {
   // The secret and the clipboard read the SAME resolved value, so the button can
   // never copy a different string than the one on screen — nor the literal
   // "undefined", which writeText(body.paste_command) produced on a body without one.
-  assert.match(fn[0], /const pasteCommand = body\.paste_command \|\| ''/, 'one resolved value');
-  assert.match(fn[0], /writeText\(pasteCommand\)/, 'the clipboard copies that same value');
+  assert.match(fn[0], /const pasteCommand = \(windows && body\.paste_command_windows\) \|\| body\.paste_command \|\| ''/, 'one resolved value');
+  assert.match(fn[0], /copy\(pasteCommand, /, 'the clipboard copies that same value');
   assert.match(fn[0], /result\.textContent = ''/, 're-issuing replaces the previous token rather than stacking a second');
 });
 

package/tests/paste_token_windows.mjs

@@ -0,0 +1,165 @@
+// tests/paste_token_windows.mjs — a first-time CLI sign-in on Windows took four failed
+// attempts (task 1005033). Three of the four failure points are in code:
+//
+//   2. The hall's one-liner starts with `npx`. In Windows PowerShell `npx` resolves to
+//      npx.ps1, which the DEFAULT execution policy refuses to run ("running scripts is
+//      disabled on this system"). `npx.cmd` is the same program without the script
+//      host, and works in PowerShell and cmd alike. The hall now hands a Windows
+//      browser the npx.cmd form.
+//   3. The one-liner only resolves `bongos` inside the project folder (npx finds the
+//      project's own bin); from anywhere else npm says "could not determine executable
+//      to run". Nothing said so — the hall now says it in the instruction itself.
+//   4. The token sat on the command line (shell history). paste-token now also reads it
+//      from a hidden prompt, or from stdin when piped, when no token argument is given.
+//
+//   1. The App's Device Flow switch was off. GitHub has no API to tick it, so the fix is
+//      telling the OWNER: the first refusal files one idempotent blocker
+//      (src/bongos/device-flow-blocker.js). Task 1005118 later replaces the paste route
+//      with a browser approval.
+//
+// Run:  node --test tests/paste_token_windows.mjs
+
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import fs from 'node:fs';
+import path from 'node:path';
+import { PassThrough } from 'node:stream';
+import { createRequire } from 'node:module';
+import { fileURLToPath } from 'node:url';
+
+const require = createRequire(import.meta.url);
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const { readTokenFromInput } = require(path.join(ROOT, 'scripts', 'bongos', 'paste-token.js'));
+
+const sink = () => { const s = new PassThrough(); s.text = ''; s.on('data', (c) => { s.text += c; }); return s; };
+
+// ── 4. the token can arrive without touching the command line ────────────────
+
+test('a piped token is read from stdin and trimmed', async () => {
+  const input = new PassThrough();
+  const p = readTokenFromInput({ input, output: sink() });
+  input.end('  abcdef0123456789abcdef0123456789  \r\n');
+  assert.equal(await p, 'abcdef0123456789abcdef0123456789');
+});
+
+test('an interactive prompt reads one line and never echoes the token', async () => {
+  const input = new PassThrough();
+  input.isTTY = true;
+  const modes = [];
+  input.setRawMode = (on) => { modes.push(on); input.isRaw = on; };
+  const output = sink();
+  const p = readTokenFromInput({ input, output });
+  input.write('abcdef01234567');
+  input.write('X\u007f'); // a typo, then backspace
+  input.write('89abcdef\r');
+  const token = await p;
+  assert.equal(token, 'abcdef0123456789abcdef');
+  assert.ok(!output.text.includes('abcdef'), `the token must not be echoed, got: ${JSON.stringify(output.text)}`);
+  assert.match(output.text, /token/i, 'it asks for the token');
+  assert.deepEqual(modes, [true, false], 'raw mode is switched on for the read and back off after');
+});
+
+test('Ctrl+C at the prompt cancels instead of saving a half-typed token', async () => {
+  const input = new PassThrough();
+  input.isTTY = true;
+  input.setRawMode = () => {};
+  const p = readTokenFromInput({ input, output: sink() });
+  input.write('abc\u0003');
+  await assert.rejects(p, /cancel/i);
+});
+
+test('paste-token falls back to the prompt when no token argument is given', () => {
+  const src = fs.readFileSync(path.join(ROOT, 'scripts', 'bongos', 'paste-token.js'), 'utf8');
+  const main = src.slice(src.indexOf('async function main()'));
+  assert.match(main, /readTokenFromInput\(/, 'main reads the token from input when argv has none');
+});
+
+// ── 2 + 3. the hall's one-liner works in a default Windows PowerShell ─────────
+
+const routeSrc = fs.readFileSync(path.join(ROOT, 'src', 'bongos', 'routes', 'auth.js'), 'utf8');
+const issueBlock = (() => {
+  const start = routeSrc.indexOf("'/auth/cli-token/issue'");
+  const next = routeSrc.indexOf('\n  router.', start);
+  return routeSrc.slice(start, next === -1 ? routeSrc.length : next);
+})();
+
+test('the issue route also composes a Windows one-liner that avoids npx.ps1', () => {
+  const m = issueBlock.match(/paste_command_windows:\s*issuer\s*\?\s*`([^`]+)`\s*:\s*`([^`]+)`/);
+  assert.ok(m, 'paste_command_windows should be a readable template literal pair');
+  for (const cmd of [m[1], m[2]]) {
+    assert.match(cmd, /^npx\.cmd bongos paste-token \$\{token\}/, `npx.cmd, not npx — got: ${cmd}`);
+  }
+  assert.match(m[1], /--api-base \$\{issuer\}/, 'the Windows form carries the issuer too');
+});
+
+const settingsJs = fs.readFileSync(path.join(ROOT, 'modules', 'hall-ui', 'public', 'settings.js'), 'utf8');
+const issueFn = (settingsJs.match(/async function issueCliToken\([\s\S]*?\n  \}\n/) || [''])[0];
+
+test('the hall shows the Windows one-liner to a Windows browser', () => {
+  assert.ok(issueFn, 'issueCliToken is a whole function');
+  assert.match(issueFn, /paste_command_windows/, 'it reads the Windows form');
+  assert.match(settingsJs, /function isWindowsBrowser\(/, 'it decides by the browser platform');
+});
+
+test('the hall says the command only runs from inside the project folder', () => {
+  assert.match(issueFn, /cd/, 'the instruction names cd');
+  assert.match(issueFn, /only (runs|works) (from )?(there|inside)/i, 'and says why');
+});
+
+// ── grade round 2 (task 1005033) ─────────────────────────────────────────────
+
+test('a pipe that never closes still settles on the first line', async () => {
+  const input = new PassThrough();
+  const p = readTokenFromInput({ input, output: sink() });
+  input.write('abcdef0123456789abcdef\nsomething else that never ends');
+  assert.equal(await p, 'abcdef0123456789abcdef');
+});
+
+test('Ctrl+D on an empty prompt cancels instead of saving nothing', async () => {
+  const input = new PassThrough();
+  input.isTTY = true;
+  input.setRawMode = () => {};
+  const p = readTokenFromInput({ input, output: sink() });
+  input.write('\u0004');
+  await assert.rejects(p, /cancel/i);
+});
+
+test('the hall offers the token-free command with the token on its own button', () => {
+  assert.match(issueFn, /bongos paste-token\$\{body\.api_base/, 'a command with no token in it');
+  assert.match(issueFn, /Copy token/, 'the token is copied separately');
+  assert.match(issueFn, /Keep the token out of your shell history/, 'and it says why');
+});
+
+// ── 1. the owner hears about Device Flow being off ────────────────────────────
+
+const { raiseDeviceFlowOffBlocker, SOURCE, SOURCE_REF } = require(path.join(ROOT, 'src', 'bongos', 'device-flow-blocker.js'));
+
+test('a device_flow_disabled refusal files ONE owner blocker through ideas.fileBlocker', async () => {
+  const filed = [];
+  const resolveOptional = (port) => (port === 'ideas.fileBlocker' ? async (b) => { filed.push(b); return { id: 1 }; } : null);
+  const out = await raiseDeviceFlowOffBlocker({ reason: 'device_flow_disabled', origin: 'https://x.example', resolveOptional });
+  assert.deepEqual(out, { id: 1 });
+  assert.equal(filed.length, 1);
+  assert.equal(filed[0].source, SOURCE);
+  assert.equal(filed[0].sourceRef, SOURCE_REF, 'a fixed source_ref makes the writer idempotent');
+  assert.match(filed[0].title, /Enable Device Flow/);
+  assert.match(filed[0].bodyMd, /https:\/\/x\.example\/builders\/settings/);
+});
+
+test('any other start failure files nothing', async () => {
+  let called = false;
+  const resolveOptional = () => async () => { called = true; };
+  assert.equal(await raiseDeviceFlowOffBlocker({ reason: 'bad_client_id', resolveOptional }), null);
+  assert.equal(called, false);
+});
+
+test('no ideas module, or a failing write, never breaks the sign-in reply', async () => {
+  assert.equal(await raiseDeviceFlowOffBlocker({ reason: 'device_flow_disabled', resolveOptional: () => null }), null);
+  const boom = () => async () => { throw new Error('db down'); };
+  assert.equal(await raiseDeviceFlowOffBlocker({ reason: 'device_flow_disabled', resolveOptional: boom }), null);
+});
+
+test('the device/start route raises it on the refusal', () => {
+  const start = routeSrc.slice(routeSrc.indexOf("'/auth/device/start'"), routeSrc.indexOf("'/auth/device/start'") + 2500);
+  assert.match(start, /raiseDeviceFlowOffBlocker\(\{ reason/);
+});

package/tests/vendored_work_root.mjs

@@ -0,0 +1,72 @@
+// tests/vendored_work_root.mjs
+//
+// task 1005100 - feedback instance vendors: in a project that installs the core from npm
+// (toast, core 1.21.115), docs-entropy.js and ship-check.js took their root from
+// path.resolve(__dirname, '..', '..') — the PACKAGE dir under node_modules/@bongos/core.
+// docs-entropy then ran `git ls-files '*.md'` there, enumerated 0 files and died with a
+// "scan defect"; ship-check ran every generator from the package dir, so gen-api-docs read
+// STALE while `npx bongos exec scripts/bongos/gen-api-docs.js --check` from the project
+// said up to date. resolveWorkRoot() is the root these tools work on: the core checkout when
+// the core is a checkout, the project (pointer, else the git top of cwd, else cwd) when it
+// is installed. ship-check spawns the script from the core and runs it in that root.
+//
+// Run:  node tests/vendored_work_root.mjs
+
+import assert from 'node:assert/strict';
+import { test } from 'node:test';
+import { execFileSync } from 'node:child_process';
+import { createRequire } from 'node:module';
+import { fileURLToPath } from 'node:url';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+const require = createRequire(import.meta.url);
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const { resolveWorkRoot, CORE_ROOT } = require('../scripts/bongos/fitness-lib.js');
+const { runStep } = require('../scripts/bongos/ship-check.js');
+
+const real = (p) => fs.realpathSync.native(p);
+const tmp = (name) => fs.mkdtempSync(path.join(os.tmpdir(), `vwr-${name}-`));
+
+test('a core checkout works on the core root, whatever the cwd', () => {
+  assert.equal(resolveWorkRoot({ installed: false, cwd: os.tmpdir() }), CORE_ROOT);
+});
+
+test('an installed core with a pointer works on the pointed-at project', () => {
+  assert.equal(resolveWorkRoot({ installed: true, cwd: os.tmpdir(), explicit: () => '/proj' }), '/proj');
+});
+
+test('an installed core with no pointer works on the git top of cwd, not the package dir', () => {
+  const repo = tmp('repo');
+  execFileSync('git', ['init', '-q'], { cwd: repo });
+  const sub = path.join(repo, 'docs');
+  fs.mkdirSync(sub);
+  const got = resolveWorkRoot({ installed: true, cwd: sub, explicit: () => null });
+  assert.equal(real(got), real(repo));
+});
+
+test('an installed core outside any repo falls back to cwd', () => {
+  const dir = tmp('norepo');
+  const got = resolveWorkRoot({ installed: true, cwd: dir, explicit: () => null, gitTop: () => null });
+  assert.equal(got, dir);
+});
+
+test('ship-check runs a step from the core but inside the work root', () => {
+  const core = tmp('core');
+  const inst = tmp('inst');
+  fs.mkdirSync(path.join(core, 'scripts', 'bongos'), { recursive: true });
+  fs.writeFileSync(path.join(core, 'scripts', 'bongos', 'where.js'), 'console.log("cwd=" + process.cwd());\n');
+  const r = runStep({ key: 'w', label: 'w', argv: ['scripts/bongos/where.js'], fix: 'f' }, { coreRoot: core, cwd: inst });
+  assert.equal(r.status, 'ok', r.tail);
+  assert.match(r.tail, /cwd=/);
+  assert.equal(real(r.tail.trim().replace(/^cwd=/, '')), real(inst));
+});
+
+test('docs-entropy and ship-check no longer hardwire their root to the package dir', () => {
+  for (const f of ['scripts/bongos/docs-entropy.js', 'scripts/bongos/ship-check.js']) {
+    const src = fs.readFileSync(path.join(ROOT, f), 'utf8');
+    assert.doesNotMatch(src, /const REPO_ROOT = path\.resolve\(__dirname, '\.\.', '\.\.'\)/, f);
+    assert.match(src, /resolveWorkRoot\(\)/, f);
+  }
+});