@bongos/core 1.19.206 → 1.19.208

package/modules/provisioning/routes/provisioning.js

@@ -591,6 +591,69 @@ module.exports = function provisioningRoutes() {
     }
   });
 
+  // ── Per-project settings (task 1003040, goal 1000058) ─────────────────────
+  // The foundation the manage-page wave hangs off: effective settings are the
+  // DEFAULTS (today's behavior — public surfaces, apply-to-join) overlaid with
+  // the instance's stored keys. Own-scoped with an Archon override: the owner
+  // manages their own project; an Archon may act on any (fleet support). 404
+  // for everyone else — no existence leak (the GET-by-id precedent).
+  function settingsAccessDenied(inst, builder) {
+    if (!inst) return true;
+    if (builder.rank === 'archon') return false;
+    return String(inst.owner_builder_id) !== String(builder.id);
+  }
+
+  // GET /provisioning/instances/:id/settings — read a project's effective
+  // settings + the allowed values (so a form can render its choices).
+  // rank: any authenticated builder (own resource; archon may read any).
+  router.get('/provisioning/instances/:id/settings', auth.requireBuilder, async (req, res) => {
+    const id = parseId(req, res); // (req, res) — parseId sends 400 bad_id + returns null on failure
+    if (!id) return;
+    try {
+      const inst = await provisioning.getInstanceById(pool, id);
+      if (settingsAccessDenied(inst, req.builder)) return res.fail('instance_not_found', 404);
+      res.json({ ok: true, settings: provisioning.effectiveSettings(inst), options: provisioning.SETTINGS_VOCAB });
+    } catch (err) {
+      console.error('[provisioning] GET /provisioning/instances/:id/settings', err);
+      res.fail('settings_read_failed', { status: 500, message: 'internal error' });
+    }
+  });
+
+  // PATCH /provisioning/instances/:id/settings — change a project's settings.
+  // Body: any subset of the known keys; strict validation refuses unknown keys
+  // and off-vocabulary values. rank: any authenticated builder (own resource;
+  // archon may change any — the override is audited via the event's actor).
+  router.patch('/provisioning/instances/:id/settings', auth.requireBuilder, async (req, res) => {
+    const id = parseId(req, res); // (req, res) — parseId sends 400 bad_id + returns null on failure
+    if (!id) return;
+    if (validateOrRespond(req, res, {
+      platform_visibility: { type: 'string', enum: provisioning.SETTINGS_VOCAB.platform_visibility },
+      joinability: { type: 'string', enum: provisioning.SETTINGS_VOCAB.joinability },
+    })) return;
+    const patch = {};
+    for (const key of Object.keys(provisioning.SETTINGS_VOCAB)) {
+      if ((req.body || {})[key] !== undefined) patch[key] = req.body[key];
+    }
+    if (!Object.keys(patch).length) {
+      return res.fail('bad_settings', { status: 400,
+        message: `The body carries no settings to change — send any of: ${Object.keys(provisioning.SETTINGS_VOCAB).join(', ')}.` });
+    }
+    try {
+      const inst = await provisioning.getInstanceById(pool, id);
+      if (settingsAccessDenied(inst, req.builder)) return res.fail('instance_not_found', 404);
+      const updated = await provisioning.updateInstanceSettings(pool, id, patch);
+      await provisioning.recordEvent(pool, {
+        instanceId: id, ownerBuilderId: inst.owner_builder_id, event: 'settings',
+        detail: `settings changed: ${Object.entries(patch).map(([k, v]) => `${k}=${v}`).join(', ')}`,
+        actor: String(inst.owner_builder_id) === String(req.builder.id) ? 'api:self' : 'api:archon',
+      }).catch(() => {});
+      res.json({ ok: true, settings: provisioning.effectiveSettings(updated) });
+    } catch (err) {
+      console.error('[provisioning] PATCH /provisioning/instances/:id/settings', err);
+      res.fail('settings_update_failed', { status: 500, message: 'internal error' });
+    }
+  });
+
   // POST /provisioning/instances/:id/teardown — request teardown of the caller's
   // OWN instance. rank: any authenticated builder (own resource). Enqueues a
   // 'teardown' intent; the runner executes it (web tier holds no tokens). 404 when

package/modules/provisioning/tests/provisioning.mjs

@@ -260,5 +260,43 @@ await ta('recordDnsNote / clearErrorNote are NARROW single-column updates — no
   assert.doesNotMatch(sql, /status\s*=|updated_at/, 'releasing the latch must not touch the lifecycle');
 });
 
+console.log('\nPer-project settings (task 1003040):');
+
+t('effectiveSettings: defaults for a bare/empty row = today\'s behavior; stored keys overlay; junk falls back', () => {
+  assert.deepEqual(P.effectiveSettings(null), { platform_visibility: 'public', joinability: 'apply' });
+  assert.deepEqual(P.effectiveSettings({}), { platform_visibility: 'public', joinability: 'apply' });
+  assert.deepEqual(P.effectiveSettings({ settings: {} }), { platform_visibility: 'public', joinability: 'apply' });
+  assert.deepEqual(
+    P.effectiveSettings({ settings: { platform_visibility: 'gated' } }),
+    { platform_visibility: 'gated', joinability: 'apply' },
+    'a stored key overlays only itself'
+  );
+  assert.deepEqual(
+    P.effectiveSettings({ settings: { platform_visibility: 'bogus', joinability: 'invite_only', future_key: 'x' } }),
+    { platform_visibility: 'public', joinability: 'invite_only' },
+    'off-vocabulary values fall back to the default; unknown keys never leak out'
+  );
+  assert.deepEqual(P.effectiveSettings({ settings: ['not', 'an', 'object'] }),
+    { platform_visibility: 'public', joinability: 'apply' }, 'a non-object settings value reads as defaults');
+});
+
+t('SETTINGS_VOCAB / DEFAULT_SETTINGS: every default is on its own vocabulary (lockstep guard)', () => {
+  for (const [key, dflt] of Object.entries(P.DEFAULT_SETTINGS)) {
+    assert.ok(P.SETTINGS_VOCAB[key], `default key '${key}' has a vocabulary`);
+    assert.ok(P.SETTINGS_VOCAB[key].includes(dflt), `default '${dflt}' is a legal '${key}' value`);
+  }
+  assert.deepEqual(Object.keys(P.SETTINGS_VOCAB).sort(), Object.keys(P.DEFAULT_SETTINGS).sort(),
+    'every known key has a default (an undefaulted key would read as undefined)');
+});
+
+await ta('updateInstanceSettings: jsonb MERGE (||) + updated_at, parameterized, returns the row', async () => {
+  let sql = '', params = null;
+  const db = { query: async (q, p) => { sql = q; params = p; return { rows: [{ id: 18, settings: { joinability: 'open' } }] }; } };
+  const row = await P.updateInstanceSettings(db, 18, { joinability: 'open' });
+  assert.equal(row.settings.joinability, 'open');
+  assert.match(sql, /SET settings = settings \|\| \$2::jsonb, updated_at = now\(\)/, 'merges — never clobbers other keys');
+  assert.deepEqual(params, [18, JSON.stringify({ joinability: 'open' })]);
+});
+
 console.log(`\nprovisioning module: ${passed} passed, ${failed} failed`);
 process.exit(failed ? 1 : 0);

package/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "@bongos/core",
-  "version": "1.19.206",
+  "version": "1.19.208",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@bongos/core",
-      "version": "1.19.206",
+      "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.206",
+  "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

@@ -839,8 +839,12 @@ const { validateOrRespond, LIMITS, parseId, asyncHandler, corsPublicGet, parsePa
 //         landed since 1.19.204 with no explicit bump. run 32061149280. (task 1002620)
 //   1.19.206 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
 //         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.206'; // 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/provisioning_settings.mjs

@@ -0,0 +1,200 @@
+// tests/provisioning_settings.mjs
+//
+// Per-project settings foundation (task 1003040, goal 1000058) — the surface the
+// manage-page wave hangs off:
+//   • GET  /provisioning/instances/:id/settings  — effective settings + options
+//   • PATCH /provisioning/instances/:id/settings — validated, own-scoped change
+//
+// The load-bearing assertions:
+//   • the OWN-SCOPE WALL: another builder's GET/PATCH answers 404 and the write
+//     path is NEVER reached (no existence leak, no cross-owner mutation)
+//   • the Archon override works and is audited as api:archon
+//   • strict validation: off-vocabulary values and unknown keys are 400s
+//   • defaults = today's behavior (public / apply) for rows that predate the column
+//
+// DB-free: data-access fns are stubbed on the cached module object (the
+// provisioning_domain_attach.mjs pattern). No network beyond localhost.
+//
+// Run:  node tests/provisioning_settings.mjs
+
+import { strict as assert } from 'node:assert';
+import { createRequire } from 'node:module';
+import http from 'node:http';
+
+const require = createRequire(import.meta.url);
+const provisioning = require('../modules/provisioning/provisioning.js');
+
+let passed = 0, failed = 0;
+async function ta(name, fn) {
+  try { await fn(); passed++; console.log(`  PASS  ${name}`); }
+  catch (e) { failed++; console.log(`  FAIL  ${name}\n        ${e.message}`); }
+}
+
+// ── stubbed data access on the cached module object ──────────────────────────
+let instance = null;            // the row getInstanceById answers with
+let updateCalls = [];           // recorded updateInstanceSettings calls
+let events = [];                // recorded provisioning_events
+provisioning.getInstanceById = async (_db, id) => (instance ? { ...instance, id } : null);
+provisioning.updateInstanceSettings = async (_db, id, patch) => {
+  updateCalls.push({ id, patch });
+  instance = { ...instance, settings: { ...(instance.settings || {}), ...patch } };
+  return { ...instance, id };
+};
+provisioning.recordEvent = async (_db, e) => { events.push(e); };
+provisioning.getOpenIntent = async () => null;
+
+const api = require('../src/module-api.js');
+let builder = { id: 7, github_login: 'owner', rank: 'thetes' };
+api.requireBuilder = (req, _res, next) => { req.builder = builder; next(); };
+api.requirePermission = () => (_req, _res, next) => next();
+api.branding = () => ({
+  domains: { publicOrigin: 'https://cb.test' },
+  identity: { productName: 'Cloud Bongos' },
+});
+
+const express = require('express');
+const provisioningRoutes = require('../modules/provisioning/routes/provisioning.js');
+const app = express();
+app.use(express.json());
+app.use((_req, res, next) => {
+  res.fail = (code, opts, details) => {
+    const status = typeof opts === 'number' ? opts : (opts && opts.status) || 400;
+    res.status(status).json({ error: { code, ...(typeof opts === 'object' ? opts : {}), ...(details || {}) } });
+  };
+  next();
+});
+app.use('/api/bongos', provisioningRoutes());
+
+const server = app.listen(0);
+await new Promise((r) => server.once('listening', r));
+const base = `http://127.0.0.1:${server.address().port}/api/bongos`;
+
+function call(method, path, body) {
+  return new Promise((resolve, reject) => {
+    const payload = body === undefined ? null : JSON.stringify(body);
+    const req = http.request(`${base}${path}`, {
+      method,
+      headers: payload
+        ? { 'Content-Type': 'application/json', 'Content-Length': Buffer.byteLength(payload) }
+        : {},
+    }, (res) => {
+      let d = '';
+      res.on('data', (c) => { d += c; });
+      res.on('end', () => { let j = null; try { j = JSON.parse(d); } catch { /* non-JSON */ } resolve({ status: res.statusCode, body: j, raw: d }); });
+    });
+    req.on('error', reject);
+    req.end(payload || undefined);
+  });
+}
+const get = (p) => call('GET', p);
+const patch = (p, b) => call('PATCH', p, b);
+
+function reset({ inst, as } = {}) {
+  instance = inst !== undefined ? inst
+    : { owner_builder_id: 7, slug: 'spike', status: 'active', domain: 'spike.cloudbongos.com', settings: {} };
+  builder = as || { id: 7, github_login: 'owner', rank: 'thetes' };
+  updateCalls = [];
+  events = [];
+}
+
+console.log('GET /provisioning/instances/:id/settings:');
+
+await ta('owner reads DEFAULTS (public / apply) on a row with empty settings — today\'s behavior', async () => {
+  reset();
+  const r = await get('/provisioning/instances/18/settings');
+  assert.equal(r.status, 200, r.raw);
+  assert.deepEqual(r.body.settings, { platform_visibility: 'public', joinability: 'apply' });
+  assert.deepEqual(r.body.options, { platform_visibility: ['public', 'gated'], joinability: ['open', 'apply', 'invite_only'] });
+});
+
+await ta('stored keys overlay the defaults', async () => {
+  reset({ inst: { owner_builder_id: 7, slug: 'spike', status: 'active', settings: { joinability: 'invite_only' } } });
+  const r = await get('/provisioning/instances/18/settings');
+  assert.equal(r.status, 200, r.raw);
+  assert.deepEqual(r.body.settings, { platform_visibility: 'public', joinability: 'invite_only' });
+});
+
+await ta('ANOTHER builder\'s GET → 404 (no existence leak)', async () => {
+  reset({ as: { id: 8, github_login: 'stranger', rank: 'thetes' } });
+  const r = await get('/provisioning/instances/18/settings');
+  assert.equal(r.status, 404, r.raw);
+  assert.equal(r.body.error.code, 'instance_not_found');
+});
+
+await ta('an Archon may read ANY instance (the override)', async () => {
+  reset({ as: { id: 999, github_login: 'archon', rank: 'archon' } });
+  const r = await get('/provisioning/instances/18/settings');
+  assert.equal(r.status, 200, r.raw);
+});
+
+await ta('unknown instance id → 404 for everyone', async () => {
+  reset({ inst: null });
+  const r = await get('/provisioning/instances/999/settings');
+  assert.equal(r.status, 404, r.raw);
+});
+
+console.log('\nPATCH /provisioning/instances/:id/settings:');
+
+await ta('owner changes one key — merged, returned effective, audited api:self', async () => {
+  reset();
+  const r = await patch('/provisioning/instances/18/settings', { joinability: 'open' });
+  assert.equal(r.status, 200, r.raw);
+  assert.deepEqual(r.body.settings, { platform_visibility: 'public', joinability: 'open' });
+  assert.deepEqual(updateCalls, [{ id: 18, patch: { joinability: 'open' } }], 'exactly the sent key, nothing else');
+  assert.equal(events.length, 1);
+  assert.equal(events[0].event, 'settings');
+  assert.equal(events[0].actor, 'api:self');
+  assert.match(events[0].detail, /joinability=open/);
+});
+
+await ta('owner changes both keys in one call', async () => {
+  reset();
+  const r = await patch('/provisioning/instances/18/settings', { platform_visibility: 'gated', joinability: 'invite_only' });
+  assert.equal(r.status, 200, r.raw);
+  assert.deepEqual(r.body.settings, { platform_visibility: 'gated', joinability: 'invite_only' });
+});
+
+await ta('the OWN-SCOPE WALL: another builder\'s PATCH → 404 and the write path is never reached', async () => {
+  reset({ as: { id: 8, github_login: 'stranger', rank: 'thetes' } });
+  const r = await patch('/provisioning/instances/18/settings', { joinability: 'open' });
+  assert.equal(r.status, 404, r.raw);
+  assert.equal(r.body.error.code, 'instance_not_found');
+  assert.equal(updateCalls.length, 0, 'no cross-owner mutation');
+  assert.equal(events.length, 0, 'no event for a refused write');
+});
+
+await ta('an Archon may change ANY instance — audited api:archon', async () => {
+  reset({ as: { id: 999, github_login: 'archon', rank: 'archon' } });
+  const r = await patch('/provisioning/instances/18/settings', { platform_visibility: 'gated' });
+  assert.equal(r.status, 200, r.raw);
+  assert.equal(events[0].actor, 'api:archon', 'the override is distinguishable in the audit ledger');
+  assert.equal(events[0].ownerBuilderId, 7, 'the event still belongs to the instance owner');
+});
+
+await ta('an off-vocabulary value → 400 validation_failed (nothing written)', async () => {
+  reset();
+  const r = await patch('/provisioning/instances/18/settings', { joinability: 'closed' });
+  assert.equal(r.status, 400, r.raw);
+  assert.equal(r.body.error.code, 'validation_failed');
+  assert.equal(updateCalls.length, 0);
+});
+
+await ta('an unknown key → 400 (strict: a typo fails loudly, never silently dropped)', async () => {
+  reset();
+  const r = await patch('/provisioning/instances/18/settings', { joinabilty: 'open' });
+  assert.equal(r.status, 400, r.raw);
+  assert.equal(r.body.error.code, 'validation_failed');
+  assert.equal(updateCalls.length, 0);
+});
+
+await ta('an empty body → 400 bad_settings with a plain sentence naming the keys', async () => {
+  reset();
+  const r = await patch('/provisioning/instances/18/settings', {});
+  assert.equal(r.status, 400, r.raw);
+  assert.equal(r.body.error.code, 'bad_settings');
+  assert.match(r.body.error.message, /platform_visibility, joinability/);
+});
+
+server.close();
+console.log(`\nprovisioning_settings: ${passed} passed, ${failed} failed`);
+process.exit(failed ? 1 : 0);