@bongos/core 1.19.207 → 1.19.208

package/.bongos-core.json

@@ -2,22 +2,22 @@
   "artifact": "bongos-core",
   "manifest_schema": 1,
   "generator": "scripts/gds/package-core.js",
-  "core_version": "1.19.207",
-  "core_contract": "1.19.207",
-  "source_commit": "f67179175e23c7d9144c3ede28fd365783eed34f",
+  "core_version": "1.19.208",
+  "core_contract": "1.19.208",
+  "source_commit": "6dabd2e84af8785ac779f8a6801b951d80ecad3b",
   "source_ref": "HEAD",
-  "built_at": "2026-08-17T20:29:20.492Z",
+  "built_at": "2026-08-17T20:55:34.065Z",
   "redaction": {
     "model": "docs-redacted+functional-verbatim",
     "docs_redacted": 310,
     "agent_docs_stubbed": 21,
-    "functional_verbatim": 1298,
+    "functional_verbatim": 1299,
     "rules": 3,
     "gate_literals": 3,
     "gate": "passed"
   },
-  "file_count": 1629,
-  "tree_sha256": "fb6abbc6818ae6e399e4154a08816d3aeeaf4d9cd65ab89ff1bb3ce3f33428b5",
+  "file_count": 1630,
+  "tree_sha256": "63df68d9f034ba54b42011a4bfc310a811d2c53cb550a586bf40d5d35228a258",
   "files": [
     {
       "path": ".claude/skills/blocker-review/SKILL.md",
@@ -187,7 +187,7 @@
     {
       "path": ".claude/skills/new-project/SKILL.md",
       "mode": "0000644",
-      "sha256": "9b36d441850c335fa634d892088e4c15a2a87acaa9e52808b74a8b2e6e9af39f"
+      "sha256": "1d6f60e8fa3cbf06cc5f8901ccf21fd8cac8050f81b3296039b659d700eba242"
     },
     {
       "path": ".claude/skills/otb-character-review/SKILL.md",
@@ -3962,7 +3962,7 @@
     {
       "path": "modules/provisioning/onboard-plan.js",
       "mode": "0000644",
-      "sha256": "de7927d2a3c1aac0d40ec5b1ac6c2e98e87cb593c4d3d2bd6ddfe3696371bff6"
+      "sha256": "4aae27c3c56de480e9cc4f19405572a96c6bf0246fdd859adceae629c7a71842"
     },
     {
       "path": "modules/provisioning/pollers/liveness-sweep.js",
@@ -4282,12 +4282,12 @@
     {
       "path": "package-lock.json",
       "mode": "0000644",
-      "sha256": "fc64c06226801735546c101af64db40d30492a4ce855303e538bac1111a18930"
+      "sha256": "df481ba4f5057938d85fadf4e5551602cb50c68f78358dc110d03ebfb99ff278"
     },
     {
       "path": "package.json",
       "mode": "0000644",
-      "sha256": "d3457496b5c76bab949eb1693518d88745db75eb7bd3afb4299d68e545cdb0bd"
+      "sha256": "5b6943de459044d4545437bd4941abadbdefcedc0063e291f72205e46956beb3"
     },
     {
       "path": "public-docs/index.html",
@@ -4547,7 +4547,7 @@
     {
       "path": "public-landing/projects.html",
       "mode": "0000644",
-      "sha256": "494d1aa1a6ff006a8e8f239c29d90c052f735919937c9dc6fb6b8eeff4902e91"
+      "sha256": "20dd4fcb471c8d5a4dced2788ca6fffecaba241207bc0087d918d15b60bcc1a1"
     },
     {
       "path": "public-landing/world/assets/clouds/cloud-island-large.png",
@@ -5447,7 +5447,7 @@
     {
       "path": "scripts/gds/setup.js",
       "mode": "0000644",
-      "sha256": "8e512a07ed885666722a216951dfad7f57fbfd92923bdf5079ce1c6f7b5c0abc"
+      "sha256": "98671f5666ae6bdafa7691bd519367345772c3041680b59c24ec83c56b99f419"
     },
     {
       "path": "scripts/gds/shell.js",
@@ -5897,7 +5897,7 @@
     {
       "path": "src/module-api.js",
       "mode": "0000644",
-      "sha256": "167ead50611054c2a0d46ebb14510c993e7c05e9c86428cad2d15d78aae0bad4"
+      "sha256": "d20ec520ccfe8d1ac72910455f97f728feaf179b265f79ebf6f9a2ca21f1e424"
     },
     {
       "path": "src/module-loader/catalog.js",
@@ -7382,7 +7382,7 @@
     {
       "path": "tests/onboard.mjs",
       "mode": "0000644",
-      "sha256": "c6823a6f0f81bcb4f01ccbd2364d6dcf76eb21e3ff10972738f792438939dee0"
+      "sha256": "71eeb42b47ad2ba11b8379cce263ceac2da42b00b9fe55aab64546027b193364"
     },
     {
       "path": "tests/onboarding_gate.mjs",
@@ -7829,6 +7829,11 @@
       "mode": "0000644",
       "sha256": "a630ac72981f230e8aa6609152765c13e8928ac329cb0ff3fe615371f31208d2"
     },
+    {
+      "path": "tests/setup_device_flow_fallback.mjs",
+      "mode": "0000644",
+      "sha256": "9a9df92b732b4f13d222329877ab17f8f972ef01370c9a918b00635716c76b5e"
+    },
     {
       "path": "tests/setup_smoke.mjs",
       "mode": "0000644",

package/.claude/skills/new-project/SKILL.md

@@ -9,7 +9,7 @@ You are guiding a new owner from **zero to a live, owned Cloud Bongos instance**
 
 A new instance is **standalone** (ADR 0108): it runs from its **own git repo** with `@cloudbongos/core` installed as a **pinned npm dependency**, not a fork of this monorepo. Central updates are a `bongos upgrade` version-pin bump, not a merge. Every step below assumes this shape (`hosting_shape=standalone`).
 
-Five steps are **irreducibly human** and must be rendered as **precise, UI-first, copy-paste-safe prompts** (a non-technical owner does them with browser clicks, no terminal guessing): (1) create the GitHub repo, (2) approve the pre-filled **GitHub App** for sign-in (ONE click — the App Manifest flow, task 2080; no secret to paste), (3) install that App on the repo (ONE click — the publish credential, task 1003049), (4) own a domain, (5) the first sign-in. Everything else is automated. Never ask the owner to do in a terminal what they can do with a click.
+Six steps are **irreducibly human** and must be rendered as **precise, UI-first, copy-paste-safe prompts** (a non-technical owner does them with browser clicks, no terminal guessing): (1) create the GitHub repo, (2) approve the pre-filled **GitHub App** for sign-in (ONE click — the App Manifest flow, task 2080; no secret to paste), (3) tick **Enable Device Flow** in that App's settings (ONE checkbox — terminal sign-in, task 1003051; until then `bongos setup` falls back to a web token), (4) install that App on the repo (ONE click — the publish credential, task 1003049), (5) own a domain, (6) the first sign-in. Everything else is automated. Never ask the owner to do in a terminal what they can do with a click.
 
 ## The canonical sequence
 

package/modules/provisioning/onboard-plan.js

@@ -44,6 +44,7 @@ function onboardPlan(mode = 'greenfield', opts = {}) {
     { key: 'seed-version', kind: 'auto', label: 'Seed the first version (V1) so the instance can take tasks immediately (task 2119)' },
     { key: 'oauth-app', kind: 'human', label: 'Wire GitHub sign-in — one-click GitHub App (task 2080), or a manual OAuth app' },
     { key: 'oauth-place', kind: 'auto', shapes: CONTROL_PLANE_SHAPES, label: 'Place the OAuth secret — auto via the Manifest flow, or verified manual (task 1979)' },
+    { key: 'device-flow', kind: 'human', label: 'Enable Device Flow in the GitHub App settings — one checkbox, so terminal sign-in (bongos login) works (task 1003051)' },
     { key: 'app-install', kind: 'human', label: 'Install the GitHub App on the repo — the publish credential that lets shipped work land itself (task 1003049, ADR 0055)' },
     { key: 'first-sign-in', kind: 'human', label: 'First sign-in (seats the founding Archon)' },
     { key: 'verify', kind: 'auto', label: 'Verify /healthz auth_configured' },

package/package-lock.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bongos/core",
-  "version": "1.19.207",
+  "version": "1.19.208",
   "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/public-landing/projects.html

@@ -2861,6 +2861,22 @@ h1[tabindex="-1"]:focus{outline:none;}
         '<button type="button" class="ghbtn" data-action="manifest-start">' + GH_ICON + 'Set up GitHub sign-in</button>' + manualOauthDetails() + '</li>';
     }
 
+    /* device-flow — the one-checkbox repair for terminal sign-in (task 1003051):
+       GitHub creates a manifest-born App with Device Flow OFF and offers no API to
+       enable it, so `bongos setup` in a terminal is refused until the owner ticks
+       the box. Web sign-in works either way; the CLI also has a web-token fallback. */
+    function renderStepDeviceFlow() {
+      if (live.manifest !== 'done') {
+        return '<li class="slocked" data-onboard-step="device-flow"><b>Enable Device Flow — one checkbox</b><p>Unlocks once GitHub sign-in above is wired. It lets builders sign in from a terminal (<code style="font-family:var(--font-mono)">bongos setup</code>); web sign-in works without it.</p></li>';
+      }
+      var appUrl = live.appSlug ? 'https://github.com/settings/apps/' + esc(live.appSlug) : null;
+      return '<li data-onboard-step="device-flow"><b>Enable Device Flow — one checkbox</b><p>' +
+        (appUrl
+          ? 'Open <a href="' + appUrl + '" target="_blank" rel="noopener">your app’s settings</a>, check <strong>Enable Device Flow</strong>, and save. '
+          : 'GitHub → Settings → Developer settings → GitHub Apps → your app → check <strong>Enable Device Flow</strong> → save. ') +
+        'GitHub leaves it off on new apps and only offers it as this checkbox — until it’s ticked, terminal sign-in falls back to a web token from the hall’s Settings page.</p></li>';
+    }
+
     /* app-install — the ADR 0055 publish credential (task 1003049): the sign-in App
        doubles as it, but only an INSTALLED App can mint push tokens; without this
        one click every finished task waits at confirmed for a manual merge. */
@@ -2894,6 +2910,7 @@ h1[tabindex="-1"]:focus{outline:none;}
     var STEP_RENDERERS = {
       'github-repo': renderStepGithubRepo,
       'oauth-app': renderStepOauthApp,
+      'device-flow': renderStepDeviceFlow,
       'app-install': renderStepAppInstall,
       'first-sign-in': renderStepFirstSignIn,
       'enter-hall': renderStepEnterHall

package/scripts/gds/setup.js

@@ -273,7 +273,129 @@ async function promptOnboardingConsent() {
   }
 }
 
-(async () => {
+// ── 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.',
+  ];
+}
+
+// Verify a hall-minted CLI token against /me and save the session (the
+// paste-token.js contract: nothing is written unless the token verifies).
+// Returns { ok:true, builder } or { ok:false, status }. Exported for tests.
+async function redeemCliToken(token) {
+  let res;
+  try {
+    res = await fetch(`${API_BASE}/api/gds/me`, { headers: { Authorization: `Bearer ${token}` } });
+  } catch (err) {
+    console.error(`Could not reach ${API_BASE}: ${err.message}`);
+    return { ok: false, status: 0 };
+  }
+  if (!res.ok) {
+    console.error(res.status === 401
+      ? `Token rejected by ${API_BASE} (HTTP 401) — copy the full token from the Settings page and try again.`
+      : `Verification call failed (HTTP ${res.status}).`);
+    return { ok: false, status: res.status };
+  }
+  const me = await res.json();
+  await saveSession({ token, builder: me.builder, api_base: API_BASE });
+  return { ok: true, builder: me.builder };
+}
+
+// Everything setup does AFTER a session is saved — shared verbatim by the
+// Device Flow success path and the W1 CLI-token fallback, so the fallback
+// completes the SAME onboarding end to end (task 1003051).
+async function finishSetup(builder) {
+  console.log('');
+  console.log(`Authenticated as ${builder.github_login} (#${builder.id})`);
+  if (builder.display_name != null) console.log(`Display name: ${builder.display_name}`);
+  if (builder.total_credits != null) console.log(`Total credits: ${builder.total_credits}`);
+  console.log(`Session saved to ${SESSION_PATH}`);
+  // SEC #863: activate the project git hooks (core.hooksPath → .husky) so
+  // the tracked hooks run — here that's the pre-push permission gate
+  // (task 1002608); an instance may track more. Best effort — an activation
+  // hiccup must never fail an otherwise-good setup; the post-push main
+  // audit is the fail-closed net regardless.
+  try {
+    const { activate } = require('./install-git-hooks');
+    const r = activate();
+    const live = (r.hooks && r.hooks.length) ? r.hooks.join(', ') : 'none tracked';
+    if (r.status === 'activated') console.log(`Git hooks activated (live hooks: ${live})`);
+    else if (r.status === 'already-active') console.log(`Git hooks already active (live hooks: ${live})`);
+    else console.log(`Note: ${r.message}`);
+  } catch (e) {
+    console.log(`Note: could not activate git hooks (${e.message}); run: git config core.hooksPath .husky`);
+  }
+  await promptGeminiKey();
+  // #1281: deliver the GDS shared art key to entitled newcomers right now, so
+  // a brand-new Xenos's first art task works without waiting for the next
+  // session start. Best-effort, bounded — never block setup. (Phase 2 will
+  // make the promptGeminiKey copy above rank-aware — "we cover your first art
+  // tasks; add your own key when you reach Thetes".)
+  try {
+    const { spawnSync } = require('node:child_process');
+    const path = require('node:path');
+    spawnSync(process.execPath, [path.join(__dirname, 'fetch-art-key.js')],
+      { stdio: 'ignore', timeout: 8000 });
+  } catch (_) { /* non-fatal — the session-start sync will deliver it later */ }
+  await promptAnthropicLink();
+  await promptDisciplines();
+  await promptOnboardingConsent();
+  // #766: explicit "what's next?" footer. The Xenos path is action-only —
+  // no primer to read first — so a newcomer goes straight from setup to
+  // surveying the works. Ship three and the city makes you a Thetes.
+  try {
+    const meRes = await (await cliClient()).me.getMe();
+    if (meRes.ok) {
+      console.log('');
+      printOnboardingNudge(meRes.data);
+      console.log('');
+      console.log('Newcomer path:');
+      console.log(`  1. Choose thy craft:  open ${hallBase()} (creative / engineering)`);
+      console.log('  2. Survey work:       /builder-start');
+      console.log('  3. Claim + ship:      /builder-claim N    →    /builder-ship');
+      console.log('  4. Ship three works and you rise to Thetes — the whole queue opens.');
+    }
+  } catch (_) {
+    // never let a UX footer break a successful setup
+  }
+}
+
+async function main() {
   const forceFlag = process.argv.includes('--force');
 
   // Environment preflight (task 1002401, onboarding-audit area 4). Before auth,
@@ -310,6 +432,7 @@ async function promptOnboardingConsent() {
       dryRunStep(`No existing session at ${SESSION_PATH}; would proceed straight to Device Flow.`);
     }
     dryRunStep('Would POST /api/gds/auth/device/start to get a user_code + verification_uri from GitHub.');
+    dryRunStep('If GitHub refuses with device_flow_disabled (a one-click App whose checkbox is unticked, task 1003051): would print the web sign-in guidance (hall Settings → CLI Access) and prompt for a pasted CLI token instead of dead-ending.');
     dryRunStep('Would print the verification_uri and user_code, then poll /api/gds/auth/device/poll every few seconds until the user approves or the code expires.');
     dryRunStep(`On approval, would write the bearer token + builder profile to ${SESSION_PATH} (chmod 600).`);
     if (SKIP_KEYS) {
@@ -448,6 +571,31 @@ async function promptOnboardingConsent() {
   console.log('Starting GitHub Device Flow...');
   const start = await (await cliClient()).auth.postAuthDeviceStart();
   if (!start.ok) {
+    // W1 (task 1003051): a manifest-born App refuses Device Flow until its owner
+    // ticks the checkbox — fall back to the hall's CLI-token path instead of
+    // dead-ending the documented setup command.
+    if (isDeviceFlowDisabled(start)) {
+      for (const line of deviceFlowFallbackLines(API_BASE)) console.log(line);
+      console.log('');
+      const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+      // Resolve '' on stdin EOF too, so a non-interactive run exits with the
+      // guidance instead of hanging on a question nobody can answer.
+      const token = (await new Promise((resolve) => {
+        rl.question('Paste the CLI token here (or press Enter to quit): ', resolve);
+        rl.once('close', () => resolve(''));
+      })).trim();
+      rl.close();
+      if (!token) {
+        console.error('No token pasted — run the Settings page one-liner, then re-run setup.');
+        process.exit(1);
+      }
+      const redeemed = await redeemCliToken(token);
+      if (!redeemed.ok) process.exit(1);
+      console.log('');
+      console.log('Signed in via the web token — terminal Device Flow stays broken until the owner ticks the checkbox.');
+      await finishSetup(redeemed.builder);
+      process.exit(0);
+    }
     console.error(`device/start failed (${start.status}):`, start.data);
     if (start.data?.error === 'auth_not_configured') {
       console.error('');
@@ -509,65 +657,19 @@ async function promptOnboardingConsent() {
       const { token, builder } = poll.data;
       await saveSession({ token, builder, api_base: API_BASE });
       console.log('');
-      console.log('');
-      console.log(`Authenticated as ${builder.github_login} (#${builder.id})`);
-      console.log(`Display name: ${builder.display_name}`);
-      console.log(`Total credits: ${builder.total_credits}`);
-      console.log(`Session saved to ${SESSION_PATH}`);
-      // SEC #863: activate the project git hooks (core.hooksPath → .husky) so
-      // the tracked hooks run — here that's the pre-push permission gate
-      // (task 1002608); an instance may track more. Best effort — an activation
-      // hiccup must never fail an otherwise-good setup; the post-push main
-      // audit is the fail-closed net regardless.
-      try {
-        const { activate } = require('./install-git-hooks');
-        const r = activate();
-        const live = (r.hooks && r.hooks.length) ? r.hooks.join(', ') : 'none tracked';
-        if (r.status === 'activated') console.log(`Git hooks activated (live hooks: ${live})`);
-        else if (r.status === 'already-active') console.log(`Git hooks already active (live hooks: ${live})`);
-        else console.log(`Note: ${r.message}`);
-      } catch (e) {
-        console.log(`Note: could not activate git hooks (${e.message}); run: git config core.hooksPath .husky`);
-      }
-      await promptGeminiKey();
-      // #1281: deliver the GDS shared art key to entitled newcomers right now, so
-      // a brand-new Xenos's first art task works without waiting for the next
-      // session start. Best-effort, bounded — never block setup. (Phase 2 will
-      // make the promptGeminiKey copy above rank-aware — "we cover your first art
-      // tasks; add your own key when you reach Thetes".)
-      try {
-        const { spawnSync } = require('node:child_process');
-        const path = require('node:path');
-        spawnSync(process.execPath, [path.join(__dirname, 'fetch-art-key.js')],
-          { stdio: 'ignore', timeout: 8000 });
-      } catch (_) { /* non-fatal — the session-start sync will deliver it later */ }
-      await promptAnthropicLink();
-      await promptDisciplines();
-      await promptOnboardingConsent();
-      // #766: explicit "what's next?" footer. The Xenos path is action-only —
-      // no primer to read first — so a newcomer goes straight from setup to
-      // surveying the works. Ship three and the city makes you a Thetes.
-      try {
-        const meRes = await (await cliClient()).me.getMe();
-        if (meRes.ok) {
-          console.log('');
-          printOnboardingNudge(meRes.data);
-          console.log('');
-          console.log('Newcomer path:');
-          console.log(`  1. Choose thy craft:  open ${hallBase()} (creative / engineering)`);
-          console.log('  2. Survey work:       /builder-start');
-          console.log('  3. Claim + ship:      /builder-claim N    →    /builder-ship');
-          console.log('  4. Ship three works and you rise to Thetes — the whole queue opens.');
-        }
-      } catch (_) {
-        // never let a UX footer break a successful setup
-      }
+      await finishSetup(builder);
       process.exit(0);
     }
   }
   console.error('\nTimed out waiting for approval.');
   process.exit(1);
-})().catch((err) => {
-  console.error('fatal:', err);
-  process.exit(1);
-});
+}
+
+if (require.main === module) {
+  main().catch((err) => {
+    console.error('fatal:', err);
+    process.exit(1);
+  });
+}
+
+module.exports = { isDeviceFlowDisabled, deviceFlowFallbackLines, redeemCliToken };

package/src/module-api.js

@@ -841,8 +841,10 @@ const { validateOrRespond, LIMITS, parseId, asyncHandler, corsPublicGet, parsePa
 //         landed since 1.19.205 with no explicit bump. run 32064728346. (task 1002620)
 //   1.19.207 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
 //         landed since 1.19.206 with no explicit bump. run 32065995444. (task 1002620)
+//   1.19.208 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+//         landed since 1.19.207 with no explicit bump. run 32068332007. (task 1002620)
 // ---------------------------------------------------------------------------
-const CORE_VERSION = '1.19.207'; // CI auto-patch carrier (ADR 0161); see changelog above
+const CORE_VERSION = '1.19.208'; // CI auto-patch carrier (ADR 0161); see changelog above
 
 // A namespaced logger so a module's log lines are attributable + consistent.
 // Usage: const log = api.logger('dev-box'); log.info('mounted');

package/tests/onboard.mjs

@@ -15,7 +15,7 @@ test('onboardPlan is the canonical sequence: name+address first, the builders ha
   assert.equal(keys[keys.length - 2], 'brand');
   // the irreducibly-human steps (must be UI-first prompts)
   const human = plan.filter((s) => s.kind === 'human').map((s) => s.key);
-  assert.deepEqual(human, ['github-repo', 'oauth-app', 'app-install', 'first-sign-in', 'enter-hall']);
+  assert.deepEqual(human, ['github-repo', 'oauth-app', 'device-flow', 'app-install', 'first-sign-in', 'enter-hall']);
   // the DNS preflight comes BEFORE provision (task 1980: before the address step)
   assert.ok(keys.indexOf('dns-preflight') < keys.indexOf('provision'), 'dns preflight precedes provision');
   // OAuth secret placement comes after the OAuth app + before first sign-in
@@ -25,6 +25,10 @@ test('onboardPlan is the canonical sequence: name+address first, the builders ha
   // must be prompted before the owner walks away into the hall.
   assert.ok(keys.indexOf('oauth-place') < keys.indexOf('app-install'), 'the App exists before it can be installed');
   assert.ok(keys.indexOf('app-install') < keys.indexOf('first-sign-in'), 'install prompted before sign-in');
+  // The Device Flow checkbox (task 1003051 / gap W1) also needs the App to exist,
+  // and belongs with the sign-in wiring it repairs.
+  assert.ok(keys.indexOf('oauth-place') < keys.indexOf('device-flow'), 'the App exists before its checkbox can be ticked');
+  assert.ok(keys.indexOf('device-flow') < keys.indexOf('first-sign-in'), 'checkbox prompted before sign-in');
 });
 
 test('onboardPlan(adopt): same sequence + human steps, but the scaffold-leg labels branch (task 2046)', () => {

package/tests/setup_device_flow_fallback.mjs

@@ -0,0 +1,179 @@
+// tests/setup_device_flow_fallback.mjs
+//
+// W1 (task 1003051): on a wizard-born instance the GitHub App has Device Flow
+// OFF (the manifest can't enable it, GitHub offers only a settings checkbox),
+// so `bongos setup` — the documented CLI sign-in — dead-ended on a proxied
+// GitHub refusal. setup.js now detects that exact refusal and falls back to the
+// hall's CLI-token path.
+//
+// Covers the fallback branch's machinery, each leg against the stubbed refusal
+// or a stubbed instance API:
+//   • isDeviceFlowDisabled — the detector against the REAL server envelope
+//     (device_start_failed 502 carrying GitHub's device_flow_disabled), a legacy
+//     flat shape, and the shapes it must NOT match (auth_not_configured, other
+//     upstream failures, success)
+//   • deviceFlowFallbackLines — the guidance names the hall Settings page,
+//     CLI Access, and the owner's one-checkbox repair
+//   • redeemCliToken — driven in a CHILD process (hermetic HOME/USERPROFILE +
+//     GDS_API_BASE at a local stub): a good token verifies via /me and writes
+//     the session; a bad token is refused and writes NOTHING
+//
+// The interactive TTY walk (prompt → paste) is deliberately not spawned here:
+// the spawn-the-whole-CLI harness (setup_smoke.mjs) is already environment-
+// sensitive, and every seam the prompt wires together is covered above.
+//
+// Run:  node tests/setup_device_flow_fallback.mjs
+
+import { strict as assert } from 'node:assert';
+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 setup = require('../scripts/gds/setup.js');
+
+const REPO_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const SETUP_JS = path.join(REPO_ROOT, 'scripts', 'gds', 'setup.js');
+
+let passed = 0, failed = 0;
+const t = (name, fn) => {
+  try { fn(); passed++; console.log(`  PASS  ${name}`); }
+  catch (e) { failed++; console.log(`  FAIL  ${name}\n        ${e.message}`); }
+};
+const ta = async (name, fn) => {
+  try { await fn(); passed++; console.log(`  PASS  ${name}`); }
+  catch (e) { failed++; console.log(`  FAIL  ${name}\n        ${e.message}`); }
+};
+
+console.log('isDeviceFlowDisabled — the refusal detector:');
+
+// The REAL shape: routes/auth.js res.fail('device_start_failed', {status:502,
+// message: 'GitHub rejected device-flow start: device_flow_disabled — …'}).
+const REAL_REFUSAL = {
+  ok: false, status: 502,
+  data: { error: { code: 'device_start_failed', message: 'GitHub rejected device-flow start: device_flow_disabled — terminal sign-in needs Device Flow enabled on the app: open https://github.com/settings/apps, open your app, check "Enable Device Flow", and save. Web sign-in is unaffected.' } },
+};
+
+t('matches the real device_start_failed envelope carrying device_flow_disabled', () => {
+  assert.equal(setup.isDeviceFlowDisabled(REAL_REFUSAL), true);
+});
+
+t('matches a legacy flat error shape too', () => {
+  assert.equal(setup.isDeviceFlowDisabled({ ok: false, status: 502, data: { error: 'device_start_failed', message: 'x device_flow_disabled y' } }), true);
+});
+
+t('does NOT match auth_not_configured, other upstream failures, or success', () => {
+  assert.equal(setup.isDeviceFlowDisabled({ ok: false, status: 503, data: { error: { code: 'auth_not_configured', message: 'GitHub OAuth App credentials missing on the server.' } } }), false);
+  assert.equal(setup.isDeviceFlowDisabled({ ok: false, status: 502, data: { error: { code: 'device_start_failed', message: 'GitHub rejected device-flow start: incorrect_client_credentials' } } }), false);
+  assert.equal(setup.isDeviceFlowDisabled({ ok: true, status: 200, data: { device_code: 'x' } }), false);
+  assert.equal(setup.isDeviceFlowDisabled(null), false);
+});
+
+console.log('\ndeviceFlowFallbackLines — the guidance:');
+
+t('names the Settings page, CLI Access, and the owner checkbox repair', () => {
+  const text = setup.deviceFlowFallbackLines('https://spike.cloudbongos.com').join('\n');
+  assert.match(text, /https:\/\/spike\.cloudbongos\.com\/builders\/settings/, 'points at the hall Settings page');
+  assert.match(text, /CLI Access/, 'names the section');
+  assert.match(text, /Re-issue CLI token/, 'names the button');
+  assert.match(text, /Enable Device Flow/, 'names the owner checkbox');
+  assert.match(text, /Web sign-in is unaffected/i, 'says what still works');
+});
+
+// ── redeemCliToken in a hermetic child against a stubbed instance API ────────
+// A child process because API_BASE + the session path resolve at module load:
+// the child gets GDS_API_BASE → the stub and HOME/USERPROFILE → a throwaway
+// dir, so the real session can never be touched. The driver prints the JSON
+// result and lets node exit naturally (no process.exit — the Windows async.c
+// abort gotcha), so assertions read stdout, not the exit code.
+
+const GOOD_TOKEN = 'a'.repeat(64);
+const server = http.createServer((req, res) => {
+  const send = (status, body) => {
+    res.writeHead(status, { 'Content-Type': 'application/json' });
+    res.end(JSON.stringify(body));
+  };
+  if (req.method === 'GET' && req.url.endsWith('/api/gds/me')) {
+    if ((req.headers.authorization || '') === `Bearer ${GOOD_TOKEN}`) {
+      return send(200, { builder: { id: 6, github_login: 'newbuilder', display_name: 'New Builder' } });
+    }
+    return send(401, { error: { code: 'unauthenticated' } });
+  }
+  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}`;
+
+const driverPath = path.join(fs.mkdtempSync(path.join(os.tmpdir(), 'w1-driver-')), 'driver.cjs');
+fs.writeFileSync(driverPath, [
+  `const s = require(${JSON.stringify(SETUP_JS)});`,
+  `s.redeemCliToken(process.argv[2]).then((r) => { console.log('RESULT ' + JSON.stringify(r)); });`,
+].join('\n'));
+
+// ASYNC spawn, not spawnSync: the stub server lives in THIS process, and a sync
+// spawn would block the event loop — the child's fetch would deadlock waiting
+// for a server that can never accept.
+function redeemInChild(token, home) {
+  return new Promise((resolve) => {
+    const child = spawn(process.execPath, [driverPath, token], {
+      env: { ...process.env, HOME: home, USERPROFILE: home, GDS_API_BASE: BASE, OTB_API_BASE: BASE },
+    });
+    let stdout = '', stderr = '';
+    child.stdout.on('data', (c) => { stdout += c; });
+    child.stderr.on('data', (c) => { stderr += c; });
+    const timer = setTimeout(() => child.kill(), 30_000);
+    child.on('close', (code, signal) => {
+      clearTimeout(timer);
+      const line = stdout.split('\n').find((l) => l.startsWith('RESULT '));
+      resolve({ result: line ? JSON.parse(line.slice(7)) : null, raw: { stdout, stderr, code, signal } });
+    });
+  });
+}
+
+function findSessions(home) {
+  const hits = [];
+  (function walk(dir) {
+    let entries = [];
+    try { entries = fs.readdirSync(dir, { withFileTypes: true }); } catch { return; }
+    for (const f of entries) {
+      const p = path.join(dir, f.name);
+      if (f.isDirectory()) walk(p);
+      else if (f.name === 'gds-session.json') hits.push(p);
+    }
+  })(home);
+  return hits;
+}
+
+console.log('\nredeemCliToken — verify-then-save against the stub:');
+
+await ta('a good token verifies via /me and writes the session under the hermetic HOME', async () => {
+  const home = fs.mkdtempSync(path.join(os.tmpdir(), 'w1-home-'));
+  const { result, raw } = await redeemInChild(GOOD_TOKEN, home);
+  assert.ok(result, `driver printed no RESULT\nstdout:\n${raw.stdout}\nstderr:\n${raw.stderr}`);
+  assert.equal(result.ok, true);
+  assert.equal(result.builder.github_login, 'newbuilder');
+  const sessions = findSessions(home);
+  assert.equal(sessions.length, 1, `exactly one session file expected under ${home}`);
+  const session = JSON.parse(fs.readFileSync(sessions[0], 'utf8'));
+  assert.equal(session.token, GOOD_TOKEN);
+  assert.equal(session.api_base, BASE, 'the session points at the instance that minted the token');
+});
+
+await ta('a bad token is refused (401) and NOTHING is written', async () => {
+  const home = fs.mkdtempSync(path.join(os.tmpdir(), 'w1-home-'));
+  const { result, raw } = await redeemInChild('b'.repeat(64), home);
+  assert.ok(result, `driver printed no RESULT\nstdout:\n${raw.stdout}\nstderr:\n${raw.stderr}`);
+  assert.equal(result.ok, false);
+  assert.equal(result.status, 401);
+  assert.match(raw.stderr, /Token rejected/, 'says the token was refused');
+  assert.equal(findSessions(home).length, 0, 'no session written for an unverified token');
+});
+
+server.close();
+console.log(`\nsetup_device_flow_fallback: ${passed} passed, ${failed} failed`);
+process.exit(failed ? 1 : 0);