@bongos/core 1.23.21 → 1.24.1

package/src/bongos/routes.js

@@ -22,6 +22,8 @@ const buildInstanceRouter = require('./routes/instance');
 const buildCoreUpdateRouter = require('./routes/core-update');
 const buildFeedbackRouter = require('./routes/feedback');
 const buildAuthRouter = require('./routes/auth');
+// Google sign-in + the browser page that approves a CLI sign-in (task 1004993).
+const buildAuthGoogleRouter = require('./routes/auth-google');
 const buildGithubRouter = require('./routes/github');
 const buildMeRouter = require('./routes/me');
 // The own-scoped session self-service (list / revoke one / sign out everywhere,
@@ -29,6 +31,11 @@ const buildMeRouter = require('./routes/me');
 // aggregator or the admin pair in routes/auth.js — see that file's header.
 const buildMySessionsRouter = require('./routes/my-sessions');
 const buildMyPasskeysRouter = require('./routes/my-passkeys');
+// The payout approval step and its append-only log (task 1004913, ADR 0385 D4).
+const buildPayoutApprovalsRouter = require('./routes/payout-approvals');
+// Who may be paid at all: age tier, sanctions, a hold that tells the person (task 1004914).
+const buildPayoutGatesRouter = require('./routes/payout-gates');
+const buildMyPayoutsRouter = require('./routes/my-payouts');
 const buildBuildersRouter = require('./routes/builders');
 // The LIFECYCLE routes (tasks · claims · versions · done-when · goals ·
 // dependencies · analytics) carved into modules/lifecycle/
@@ -121,7 +128,10 @@ function buildGdsRouter() {
       /^\/provisioning\/instances\/\d+\/logo$/.test(req.path) ||
       // task 1004496: a reference image on a page feedback doc — up to 4 MB decoded,
       // ~5.3 MB as base64. modules/page-notes/routes/page-notes.js mounts its own 8 MB parser.
-      /^\/page-notes\/\d+\/images$/.test(req.path)
+      /^\/page-notes\/\d+\/images$/.test(req.path) ||
+      // task 1004917: one sketch, image or PDF for an AI studio request — up to
+      // 8 MB decoded. modules/ai-studio/routes/ai-studio.js mounts its own 12 MB parser.
+      req.path === '/ai-studio/uploads'
     ) return next();
     return globalJson(req, res, next);
   });
@@ -159,10 +169,14 @@ function buildGdsRouter() {
   router.use(buildCoreUpdateRouter());
   router.use(buildFeedbackRouter());
   router.use(buildAuthRouter());
+  router.use(buildAuthGoogleRouter());
   router.use(buildGithubRouter());
   router.use(buildMeRouter());
   router.use(buildMySessionsRouter());
   router.use(buildMyPasskeysRouter());
+  router.use(buildPayoutApprovalsRouter());
+  router.use(buildPayoutGatesRouter());
+  router.use(buildMyPayoutsRouter());
   router.use(buildBuildersRouter());
   // tasks · claims · versions · done-when · goals · dependencies · analytics now
   // mount via moduleLoader.mountModuleRoutes below (lifecycle module, BV1.R86) —

package/src/bongos/secret-box.js

@@ -26,6 +26,7 @@ const crypto = require('node:crypto');
 const fs = require('node:fs');
 const path = require('node:path');
 const ic = require('../instance-config');
+const { readConfigFileCached, clearConfigReadCache } = require('../instance-config'); // destructured: knip credits only this form
 
 const VERSION = 'v1';
 const IV_BYTES = 12;
@@ -58,9 +59,22 @@ function decodeMasterKey(raw) {
   return null;
 }
 
+// task 1004924: encrypt/decrypt/isConfigured run on request paths, and each used
+// to decode the key afresh and, with no env key, read the key file from disk —
+// a sync read blocking the event loop on every call. The decode is memoised on
+// the raw string (one entry per source: an env change is simply a new string),
+// and the file goes through the cached config read (60 s TTL, keyed by the
+// resolved paths, dropped by provisionMasterKey).
+const _decoded = { env: { raw: undefined, key: null }, file: { raw: undefined, key: null } };
+function decodeMemo(slot, raw) {
+  const m = _decoded[slot];
+  if (m.raw !== raw) { m.raw = raw; m.key = decodeMasterKey(raw); }
+  return m.key;
+}
+
 // Load the master key from env, then the local operator file. Returns Buffer|null.
 function loadMasterKey() {
-  const fromEnv = decodeMasterKey(process.env.BUILDER_SECRET_KEY);
+  const fromEnv = decodeMemo('env', process.env.BUILDER_SECRET_KEY);
   if (fromEnv) return fromEnv;
   // A set-but-malformed env value is an operator mistake worth one loud line —
   // but we still fail closed (return null) rather than fall back to something weak.
@@ -69,8 +83,8 @@ function loadMasterKey() {
     console.error('[gds] BUILDER_SECRET_KEY is set but is not a 32-byte hex/base64 value — secret storage disabled until fixed.');
   }
   try {
-    const raw = ic.readConfigFileSync('builder-secret.key');
-    const fromFile = raw && decodeMasterKey(raw);
+    const raw = readConfigFileCached('builder-secret.key');
+    const fromFile = raw && decodeMemo('file', raw);
     if (fromFile) return fromFile;
   } catch (_) { /* not configured */ }
   return null;
@@ -121,6 +135,7 @@ function provisionMasterKey(opts = {}) {
     return { ok: false, error: (e && (e.code || e.message)) || 'write_failed' };
   }
   try { fs.chmodSync(file, 0o600); } catch (_) { /* best-effort tighten */ }
+  clearConfigReadCache(); // a cached "no key file" must not outlive the write
   return { ok: true, created: true };
 }
 

package/src/bongos/serve-internal.js

@@ -41,7 +41,7 @@ const gdsAuth = require('./auth');
 const { loadIdpConfig } = require('./auth-config');
 const { buildStampedHtml, hashFile } = require('../asset-version');
 const { buildInfo } = require('../build-info');
-const { buildBongosDownloads } = require('../bongos-downloads');
+const { buildBongosDownloads, installScriptReader } = require('../bongos-downloads');
 const { clientBranding, branding, applyBrandConditionals } = require('../branding');
 const { nightTintCss } = require('../night-tint');
 const { prelaunchGate } = require('./prelaunch-gate');
@@ -500,8 +500,22 @@ function injectModuleHallWidgets(html, scripts = hallWidgetScripts({ isEnabled:
 // while the builders host keeps its own isBuildersHost guard (it's served by the
 // richer dedicated block, not the generic loop).
 function isStatusHost(req) {
-  const host = (req.headers.host || '').toLowerCase().split(':')[0];
-  return host.startsWith('status.');
+  return siteOf(req).host.startsWith('status.');
+}
+
+// WHICH SITE IS THIS REQUEST FOR, worked out ONCE per request (task 1004963) into
+// req.bongosSite, which every host predicate reads instead of re-parsing the Host
+// header (and the buildersOrigin URL) in each of ~15 handlers. Keyed on the raw
+// Host it came from, so a changed header is re-classified, never answered stale.
+// `surface` is filled by the mounted app's surfaceOf(), which knows its surfaces.
+function siteOf(req) {
+  const raw = req.headers.host || '';
+  const cached = req.bongosSite;
+  if (cached && cached.raw === raw) return cached;
+  const host = raw.toLowerCase().split(':')[0];
+  const cfg = host.startsWith('builders.') ? '' : configuredBuildersHost();
+  const builders = host.startsWith('builders.') || (cfg !== '' && host === cfg);
+  return (req.bongosSite = { raw, host, builders, surface: null, surfaceFor: null });
 }
 // A single-host instance — one with no dedicated builders.<apex> subdomain, e.g. a
 // co-located instance on a one-level subdomain like emersonian-circles.cloudbongos.com
@@ -521,10 +535,7 @@ function configuredBuildersHost() {
   } catch { return ''; }
 }
 function isBuildersHost(req) {
-  const host = (req.headers.host || '').toLowerCase().split(':')[0];
-  if (host.startsWith('builders.')) return true;
-  const cfg = configuredBuildersHost();
-  return cfg !== '' && host === cfg;
+  return siteOf(req).builders;
 }
 
 // Is this instance served entirely from ONE host — publicOrigin and buildersOrigin
@@ -575,6 +586,13 @@ function mountInternalSurfaces(app) {
   // It sits ABOVE the metrics middleware deliberately: a refused knock is still
   // a request this instance served, and hiding gate 401s would make the traffic
   // graph lie about how much attention an unannounced instance is getting.
+  // Ahead of even the gate: classify the request's site ONCE (siteOf, task 1004963).
+  // Pure string work, no I/O. Both gates were checked for per-request I/O then, and
+  // need no new cache: they read process.env and the memoised branding singleton; a
+  // 'gated' instance's session lookup is already memoised per request (RESOLVED_SESSIONS
+  // in auth.js), and caching it across requests would let a revoked session through.
+  app.use((req, _res, next) => { surfaceOf(req); next(); });
+
   app.use(prelaunchGate());
 
   app.use(metrics.httpMiddleware());
@@ -706,11 +724,11 @@ function mountInternalSurfaces(app) {
     // a spoofed Host can't redirect a `curl | sh`). The fallback comes from the
     // branding pack, not a hardcoded host brand (ADR 0062 §3).
     const BONGOS_PUBLIC_ORIGIN = resolveEnv('PUBLIC_ORIGIN') || branding().domains.publicOrigin;
-    const readBongosInstallScript = (name) => {
-      try {
-        return fs.readFileSync(path.join(ROOT, 'infra', name), 'utf8').split('__GDS_API_BASE__').join(BONGOS_PUBLIC_ORIGIN);
-      } catch { return null; }
-    };
+    // Read + substituted once per name, not per request (task 1004924).
+    const readBongosInstallScript = installScriptReader({
+      readFile: (name) => fs.readFileSync(path.join(ROOT, 'infra', name), 'utf8'),
+      origin: BONGOS_PUBLIC_ORIGIN,
+    });
     app.get('/downloads/bongos/latest.json', (_req, res) => {
       res.set('Cache-Control', 'public, max-age=60');
       res.json(bongosDownloads.latestJson());
@@ -790,6 +808,17 @@ function mountInternalSurfaces(app) {
       // hall's). urlPrefix '/' because the surface is served at the host root.
       html: injectBrandingInto(buildStampedHtml(s.dir, '/')),
     }));
+  // The generic module surface this request's Host is for (first match, as the old
+  // some()/find() pair), or null — kept on req.bongosSite (task 1004963). First called
+  // by the top-of-chain classifier, which only runs once webSurfaces is built.
+  function surfaceOf(req) {
+    const site = siteOf(req);
+    if (site.surfaceFor !== webSurfaces) {
+      site.surface = webSurfaces.find((s) => site.host.startsWith(s.host)) || null;
+      site.surfaceFor = webSurfaces;
+    }
+    return site.surface;
+  }
   // True iff this request's Host matches a GENERIC module web surface (status-style,
   // served by the loop below) — replaces the literal isStatusHost() guard the
   // /builders middleware used, so those guards skip every generic surface host with
@@ -797,13 +826,11 @@ function mountInternalSurfaces(app) {
   // partitioned out above), so the dedicated /builders blocks below do NOT self-skip
   // the builders host — they are what serves it.
   function isModuleSurfaceHost(req) {
-    const host = (req.headers.host || '').toLowerCase().split(':')[0];
-    return webSurfaces.some((s) => host.startsWith(s.host));
+    return surfaceOf(req) !== null;
   }
 
   app.use((req, res, next) => {
-    const host = (req.headers.host || '').toLowerCase().split(':')[0];
-    const surface = webSurfaces.find((s) => host.startsWith(s.host));
+    const surface = surfaceOf(req);
     if (!surface) return next();
     // /api/* already handled above; everything else on a surface host serves from
     // the module's static dir. The index page comes from the stamped in-memory copy
@@ -909,7 +936,7 @@ function mountInternalSurfaces(app) {
   app.use((req, res, next) => {
     if (isModuleSurfaceHost(req) || isBuildersHost(req)) return next();
     if (req.path !== '/builders' && !req.path.startsWith('/builders/')) return next();
-    const apex = (req.headers.host || '').toLowerCase().split(':')[0];
+    const apex = siteOf(req).host;
     const rest = req.path.replace(/^\/builders\/?/, '');            // '/builders'→'', '/builders/watch'→'watch'
     const qs = req.url.includes('?') ? req.url.slice(req.url.indexOf('?')) : '';
     return res.redirect(301, `https://builders.${apex}/${rest}${qs}`);
@@ -1296,8 +1323,9 @@ function mountInternalSurfaces(app) {
   // Claude works for them. Every read behind it is the viewer's own and
   // requireBuilder (GET /me and its /me/* prefs, /specialities), so sign-in is the
   // whole gate; the governing reads it adds are gated by their own routes.
+  // task 1004921: `ai-studio`, the studio's AI pages; every route behind it is the viewer's own.
   const SIGNEDIN_BUILDERS_PAGE_RE =
-    /^\/builders\/(?:work|settings|atlas|modules|goals|goal-map|roadmap|copy-desk|studio|tweak-editor|ideas|thinking|collab|task|idea|primer(?:\.md)?|diagrams|my-agents|commands)(?:\.html)?\/?$/;
+    /^\/builders\/(?:work|settings|atlas|modules|goals|goal-map|roadmap|copy-desk|studio|ai-studio|tweak-editor|ideas|thinking|collab|task|idea|primer(?:\.md)?|diagrams|my-agents|commands)(?:\.html)?\/?$/;
   // The diagram image assets under /builders/diagrams/ ride the same tier as the
   // page that embeds them.
   const SIGNEDIN_BUILDERS_PREFIX_RE = /^\/builders\/diagrams\//;
@@ -1467,4 +1495,4 @@ function mountInternalSurfaces(app) {
   return app;
 }
 
-module.exports = { mountInternalSurfaces, isStatusHost, isBuildersHost, injectBrandingGlobal, injectBrandingInto, injectModuleHallWidgets, themeMarkup, applyBrandTokens, resolveOpenapiJson, openapiJson, resolveClientBundleJs, generateClientBundleJs, clientBundleJs, tryLoadInstanceConfig };
+module.exports = { mountInternalSurfaces, isStatusHost, isBuildersHost, siteOf, injectBrandingGlobal, injectBrandingInto, injectModuleHallWidgets, themeMarkup, applyBrandTokens, resolveOpenapiJson, openapiJson, resolveClientBundleJs, generateClientBundleJs, clientBundleJs, tryLoadInstanceConfig };

package/src/bongos/sign-in-pages.js

@@ -0,0 +1,138 @@
+// src/bongos/sign-in-pages.js — the small server-rendered pages a sign-in shows
+// before a session exists: the "Continue with GitHub / Continue with Google"
+// chooser, and the page where a person approves a command-line sign-in in their
+// browser (task 1004993, ADR 0396).
+//
+// WHY ITS OWN FILE. Both are pure over their inputs and the branding pack, so a
+// test can render them without a server, and routes/auth.js (which shows the
+// chooser) and routes/auth-google.js (which shows the approval page) can share
+// one look without requiring each other. Same palette and stylesheet as the
+// auth error page in routes/auth.js, so every sign-in screen reads as one place.
+'use strict';
+
+const { branding } = require('../branding');
+const { escapeHtml } = require('../html-escape');
+
+const GITHUB_MARK = '<svg aria-hidden="true" width="18" height="18" viewBox="0 0 16 16" style="vertical-align:-3px;margin-right:8px"><path fill="currentColor" d="M8 0C3.58 0 0 3.58 0 8c0 3.54 2.29 6.53 5.47 7.59 .4 .07 .55-.17 .55-.38 0-.19-.01-.82-.01-1.49-2.01 .37-2.53-.49-2.69-.94-.09-.23-.48-.94-.82-1.13-.28-.15-.68-.52-.01-.53 .63-.01 1.08 .58 1.23 .82 .72 1.21 1.87 .87 2.33 .66 .07-.52 .28-.87 .51-1.07-1.78-.2-3.64-.89-3.64-3.95 0-.87 .31-1.59 .82-2.15-.08-.2-.36-1.02 .08-2.12 0 0 .67-.21 2.2 .82 .64-.18 1.32-.27 2-.27 .68 0 1.36 .09 2 .27 1.53-1.04 2.2-.82 2.2-.82 .44 1.1 .16 1.92 .08 2.12 .51 .56 .82 1.27 .82 2.15 0 3.07-1.87 3.75-3.65 3.95 .29 .25 .54 .73 .54 1.48 0 1.07-.01 1.93-.01 2.2 0 .21 .15 .46 .55 .38A8.013 8.013 0 0016 8c0-4.42-3.58-8-8-8z"/></svg>';
+const GOOGLE_MARK = '<svg aria-hidden="true" width="18" height="18" viewBox="0 0 48 48" style="vertical-align:-3px;margin-right:8px"><path fill="#EA4335" d="M24 9.5c3.54 0 6.71 1.22 9.21 3.6l6.85-6.85C35.9 2.38 30.47 0 24 0 14.62 0 6.51 5.38 2.56 13.22l7.98 6.19C12.43 13.72 17.74 9.5 24 9.5z"/><path fill="#4285F4" d="M46.98 24.55c0-1.57-.15-3.09-.38-4.55H24v9.02h12.94c-.58 2.96-2.26 5.48-4.78 7.18l7.73 6c4.51-4.18 7.09-10.36 7.09-17.65z"/><path fill="#FBBC05" d="M10.53 28.59c-.48-1.45-.76-2.99-.76-4.59s.27-3.14.76-4.59l-7.98-6.19C.92 16.46 0 20.12 0 24c0 3.88.92 7.54 2.56 10.78l7.97-6.19z"/><path fill="#34A853" d="M24 48c6.48 0 11.93-2.13 15.89-5.81l-7.73-6c-2.15 1.45-4.92 2.3-8.16 2.3-6.26 0-11.57-4.22-13.47-9.91l-7.98 6.19C6.51 42.62 14.62 48 24 48z"/></svg>';
+
+function worldName() {
+  try { return branding().identity?.worldName || 'Sign in'; } catch { return 'Sign in'; }
+}
+
+// One page shell: the hall stylesheet, a header, and a body the caller built
+// (already escaped). Never a script: these pages work with forms and links alone.
+function renderPage({ title, heading, subtitle, bodyHtml }) {
+  return `<!doctype html>
+<html lang="en"><head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<meta name="referrer" content="no-referrer">
+<title>${escapeHtml(worldName())} — ${escapeHtml(title)}</title>
+<link rel="stylesheet" href="/builders/style.css">
+<style>
+  .signinChoices{display:flex;flex-direction:column;gap:12px;max-width:340px;margin:8px auto 0}
+  .signinChoices .landing__btn{display:block;text-align:center}
+  .signinCode{font:600 1.6rem/1.2 ui-monospace,Menlo,Consolas,monospace;letter-spacing:.12em;text-align:center;margin:12px 0}
+  .signinRow{display:flex;gap:12px;justify-content:center;flex-wrap:wrap}
+  .signinRow form{margin:0}
+  .signinRow button{cursor:pointer}
+  .signinCodeForm{display:flex;gap:8px;justify-content:center;flex-wrap:wrap}
+  .signinCodeForm input{font:inherit;padding:8px 10px;text-transform:uppercase;letter-spacing:.1em;max-width:12em}
+</style>
+</head><body>
+<header class="hall">
+  <h1>${escapeHtml(heading)}</h1>
+  ${subtitle ? `<p class="hall__sub">${escapeHtml(subtitle)}</p>` : ''}
+</header>
+<main>
+  <section class="scroll">
+    <div class="landing">
+${bodyHtml}
+    </div>
+  </section>
+</main>
+</body></html>`;
+}
+
+// The two ways in, side by side. Both hrefs are built by the caller from
+// validated values; they are escaped here all the same.
+function choiceButtons({ githubHref, googleHref }) {
+  return `      <div class="signinChoices">
+        <a class="landing__btn" href="${escapeHtml(githubHref)}">${GITHUB_MARK}Continue with GitHub</a>
+        <a class="landing__btn" href="${escapeHtml(googleHref)}">${GOOGLE_MARK}Continue with Google</a>
+      </div>`;
+}
+
+// The sign-in chooser /auth/web/start shows when Google sign-in is switched on.
+function renderSignInChooser({ githubHref, googleHref }) {
+  return renderPage({
+    title: 'sign in',
+    heading: 'Sign in',
+    subtitle: 'New here? Either button creates your account.',
+    bodyHtml: `${choiceButtons({ githubHref, googleHref })}
+      <p class="landing__note">GitHub is only needed to create a project or to write code. Ideas, art and reviews work with either.</p>`,
+  });
+}
+
+// The command-line approval page, in its four states:
+//   'enter'    — no code, or one that is unknown or expired: ask for it
+//   'signin'   — a live code, nobody signed in: offer both ways in
+//   'confirm'  — a live code and a signed-in person: show it, Approve or Cancel
+//   'done'     — after the person decided (approved or cancelled)
+function renderDeviceApprovalPage(view) {
+  const { state } = view;
+  if (state === 'signin') {
+    return renderPage({
+      title: 'approve command-line sign-in',
+      heading: 'Sign in to continue',
+      subtitle: 'Your command line is waiting for you to sign in.',
+      bodyHtml: `      <p class="signinCode">${escapeHtml(view.userCode)}</p>
+${choiceButtons(view)}
+      <p class="landing__note">After you sign in you come straight back here to approve it.</p>`,
+    });
+  }
+  if (state === 'confirm') {
+    return renderPage({
+      title: 'approve command-line sign-in',
+      heading: 'Approve this sign-in?',
+      subtitle: `A command line is asking to sign in as ${view.name}.`,
+      bodyHtml: `      <p>Check this code matches the one in your terminal:</p>
+      <p class="signinCode">${escapeHtml(view.userCode)}</p>
+      <div class="signinRow">
+        <form method="post" action="${escapeHtml(view.action)}">
+          <input type="hidden" name="user_code" value="${escapeHtml(view.userCode)}">
+          <input type="hidden" name="decision" value="approve">
+          <button class="landing__btn" type="submit">Approve</button>
+        </form>
+        <form method="post" action="${escapeHtml(view.action)}">
+          <input type="hidden" name="user_code" value="${escapeHtml(view.userCode)}">
+          <input type="hidden" name="decision" value="deny">
+          <button class="landing__btn" type="submit">Cancel</button>
+        </form>
+      </div>
+      <p class="landing__note">Only approve if you just started a sign-in on your own computer. If someone sent you this link, press Cancel.</p>`,
+    });
+  }
+  if (state === 'done') {
+    return renderPage({
+      title: view.approved ? 'signed in' : 'cancelled',
+      heading: view.approved ? 'You’re signed in' : 'Sign-in cancelled',
+      subtitle: view.approved ? 'Go back to your terminal — it carries on by itself.' : 'Nothing was signed in. You can close this page.',
+      bodyHtml: '      <p class="landing__note">You can close this page.</p>',
+    });
+  }
+  return renderPage({
+    title: 'approve command-line sign-in',
+    heading: 'Enter your code',
+    subtitle: view.problem || 'Type the code your terminal shows.',
+    bodyHtml: `      <form class="signinCodeForm" method="get" action="${escapeHtml(view.action)}">
+        <label for="code" class="landing__note" style="width:100%;text-align:center">Code</label>
+        <input id="code" name="code" autocomplete="off" autocapitalize="characters" spellcheck="false" placeholder="ABCD-EFGH" maxlength="12">
+        <button class="landing__btn" type="submit">Continue</button>
+      </form>
+      <p class="landing__note">Codes last ten minutes. If yours ran out, start the sign-in again in your terminal.</p>`,
+  });
+}
+
+module.exports = { renderSignInChooser, renderDeviceApprovalPage };

package/src/bongos/task-needs.js

@@ -0,0 +1,146 @@
+// A task says what it NEEDS; a builder has CAPABILITIES (task 1004950, ADR 0395).
+//
+// Most work needs nothing beyond the ordinary build loop. Some needs a person who
+// holds something an agent on a builder machine does not:
+//
+//   owner   — a decision, account or permission only the project owner holds.
+//   server  — hands on the live host: its DNS, its secrets, its database by hand.
+//
+// `tasks.needs` is its OWN set, deliberately not a value of `automation_tag`.
+// That tag answers "can this run unattended overnight?" (it feeds the session-fit
+// projection); needs answers "who can do this at all?". A task can be
+// overnight-safe and need the server, or need the owner and be live-only — one
+// field cannot carry both answers without making one of them lie.
+//
+// A builder's capabilities are resolved server-side, per request, uncached — like
+// rank (ADR 0016). Nothing in a request body can assert one:
+//   owner   from the government's owner seat (positionsFor), with the founding
+//           builder as the fallback — read exactly the way the criterion UAT
+//           sign-off reads it (criterion-uat-db.holdsOwnerSeat).
+//   server  from builders.capability_grants, which only the owner sets. Default
+//           off. Holding the owner seat does NOT imply it: the owner's own agent
+//           runs on a builder machine too.
+//
+// What narrows and what does not: the lists that RECOMMEND work (the claimable
+// feed, the session optimizer, the autonomous runner) leave out a task whose
+// needs the viewer lacks. Every task stays readable everywhere else. The claim
+// itself is refused only on `server` (an agent without the grant cannot do it);
+// `owner` work stays claimable, because the owner claims it.
+
+'use strict';
+
+const TASK_NEEDS = Object.freeze(['owner', 'server']);
+// The capabilities an owner can grant by hand. `owner` is never granted — it is
+// the seat itself.
+const GRANTABLE_CAPABILITIES = Object.freeze(['server']);
+
+// normalizeNeeds — validate a request value into a sorted, de-duplicated array.
+// Accepts an array, a comma-separated string, null/'' (= none). Returns
+// { ok: true, needs } or { ok: false, bad: [...] } naming the unknown values.
+function normalizeNeeds(value) {
+  if (value === null || value === undefined || value === '') return { ok: true, needs: [] };
+  const list = Array.isArray(value) ? value : (typeof value === 'string' ? value.split(',') : null);
+  if (!list) return { ok: false, bad: [String(value)] };
+  const cleaned = list.map((v) => (typeof v === 'string' ? v.trim().toLowerCase() : v)).filter((v) => v !== '');
+  const bad = cleaned.filter((v) => !TASK_NEEDS.includes(v));
+  if (bad.length > 0) return { ok: false, bad: bad.map(String) };
+  return { ok: true, needs: TASK_NEEDS.filter((n) => cleaned.includes(n)) };
+}
+
+// missingNeeds — the needs of a task the holder of `capabilities` lacks. Pure.
+// An unknown need on a row (a value written by a newer release) counts as
+// missing: fail closed, never advertise work nobody here can do.
+function missingNeeds(needs, capabilities) {
+  const have = new Set(Array.isArray(capabilities) ? capabilities : []);
+  return (Array.isArray(needs) ? needs : []).filter((n) => !have.has(n));
+}
+
+// claimRefusalNeeds — the subset of missing needs that REFUSES a claim. Only
+// `server`: owner work is claimable (by the owner, who the feed shows it to).
+function claimRefusalNeeds(needs, capabilities) {
+  return missingNeeds(needs, capabilities).filter((n) => n !== 'owner');
+}
+
+const SERVER_REFUSAL_MESSAGE =
+  'This task needs server access, which you do not have yet, so pick another task or ask the project owner for it.';
+
+// holdsOwnerSeatVia — the government port's answer. No port or a failed read
+// answers false; the founding-builder fallback still applies.
+async function holdsOwnerSeatVia(government, builderId) {
+  if (!government || typeof government.positionsFor !== 'function') return false;
+  try {
+    const p = await government.positionsFor(builderId);
+    return !!(p && Array.isArray(p.held) && p.held.some((h) => h && h.kind === 'owner'));
+  } catch {
+    return false;
+  }
+}
+
+// resolveCapabilities — the capabilities `builderId` holds right now, as a sorted
+// array. `deps` (tests): { pool, government, getFoundingBuilder }.
+async function resolveCapabilities(builderId, deps = {}) {
+  if (builderId === null || builderId === undefined) return [];
+  const pool = deps.pool || require('./pool').pool;
+  const government = deps.government !== undefined
+    ? deps.government
+    : require('../module-seams').resolveOptional('government');
+  const getFounder = deps.getFoundingBuilder || require('./db-kernel').getFoundingBuilder;
+
+  const caps = new Set();
+  let isOwner = await holdsOwnerSeatVia(government, builderId);
+  if (!isOwner) {
+    const founder = await Promise.resolve().then(getFounder).catch(() => null);
+    isOwner = !!(founder && String(founder.id) === String(builderId));
+  }
+  if (isOwner) caps.add('owner');
+
+  const { rows } = await pool.query('SELECT capability_grants FROM builders WHERE id = $1', [builderId]);
+  const grants = rows[0] && Array.isArray(rows[0].capability_grants) ? rows[0].capability_grants : [];
+  for (const g of grants) if (GRANTABLE_CAPABILITIES.includes(g)) caps.add(g);
+
+  return TASK_NEEDS.filter((c) => caps.has(c));
+}
+
+// setCapabilityGrants — the owner grants or withdraws a builder's capabilities
+// (PATCH /builders/:id/capabilities). The owner check lives HERE, at the write,
+// not only in the route: `actorBuilderId` must hold the owner seat right now, or
+// it throws NOT_PROJECT_OWNER — so no other caller can grant server access by
+// reaching this function. It is deliberately NOT on the module doorway (see
+// READ_SURFACE). A machine principal holds none: an agent's access is the
+// person's it runs for. Returns the row, null when absent; throws
+// TARGET_IS_SYSTEM_PRINCIPAL like setBuilderTester.
+async function setCapabilityGrants({ actorBuilderId, builderId, grants }, deps = {}) {
+  const pool = deps.pool || require('./pool').pool;
+  const actorCaps = await resolveCapabilities(actorBuilderId, deps);
+  if (!actorCaps.includes('owner')) throw { code: 'NOT_PROJECT_OWNER' };
+  const { rows: found } = await pool.query('SELECT id, system_role FROM builders WHERE id = $1', [builderId]);
+  if (!found[0]) return null;
+  if (found[0].system_role) throw { code: 'TARGET_IS_SYSTEM_PRINCIPAL' };
+  const { rows } = await pool.query(
+    `UPDATE builders SET capability_grants = $2::text[] WHERE id = $1
+     RETURNING id, github_login, display_name, capability_grants`,
+    [builderId, GRANTABLE_CAPABILITIES.filter((g) => grants.includes(g))]
+  );
+  return rows[0] || null;
+}
+
+// feedNeedsClause — the SQL predicate a recommend list applies: the row's needs
+// are a subset of the viewer's capabilities. `param` is the placeholder holding
+// the capabilities text[]. A NULL needs reads as none.
+function feedNeedsClause(alias, param) {
+  return `COALESCE(${alias}.needs, '{}'::text[]) <@ ${param}::text[]`;
+}
+
+// READ_SURFACE — what the module doorway publishes (src/module-api.js taskNeeds):
+// the vocabulary, the reads and the SQL predicate. Never the grant write.
+const READ_SURFACE = Object.freeze({
+  TASK_NEEDS, GRANTABLE_CAPABILITIES, SERVER_REFUSAL_MESSAGE,
+  normalizeNeeds, claimRefusalNeeds, resolveCapabilities, feedNeedsClause,
+});
+
+module.exports = {
+  READ_SURFACE,
+  resolveCapabilities,
+  setCapabilityGrants,
+  feedNeedsClause,
+};

package/src/bongos-downloads.js

@@ -62,4 +62,21 @@ function buildBongosDownloads(cfg) {
   return { redirectFor, latestJson, versionJson, version };
 }
 
-module.exports = { buildBongosDownloads };
+// installScriptReader — the one-line installers (/downloads/bongos/install.sh and
+// install.ps1) with the API base substituted in, read from disk ONCE per name
+// (task 1004924). They were re-read and re-substituted on every request, a sync
+// read blocking the event loop. The files only change on a deploy, which restarts
+// the process, so a per-process memo is exact. A missing file (null) is memoised
+// too. `readFile(name)` returns the raw text or throws; it is the test seam.
+function installScriptReader({ readFile, origin }) {
+  const memo = new Map();
+  return function read(name) {
+    if (memo.has(name)) return memo.get(name);
+    let out = null;
+    try { out = String(readFile(name)).split('__GDS_API_BASE__').join(origin); } catch { out = null; }
+    memo.set(name, out);
+    return out;
+  };
+}
+
+module.exports = { buildBongosDownloads, installScriptReader };

package/src/instance-config.js

@@ -178,6 +178,32 @@ function readConfigFileSync(name, { encoding = 'utf8', b = safeBrand() } = {}) {
   return null;
 }
 
+// readConfigFileCached — readConfigFileSync for the REQUEST path (task 1004924).
+// authConfigured()/discordConfigured() and the secret box run per request, and on
+// a box with no env creds each call was up to four sync ENOENT reads blocking the
+// event loop. This answers from memory for `ttlMs` (default 60 s, so a creds file
+// an operator drops in still takes effect without a restart), caching a miss
+// (null) as well as a hit. The key is the resolved read-path list, so a changed
+// home or config dir is a fresh read, never a stale answer from another dir.
+// A non-ENOENT error is not cached: it propagates, exactly as the uncached read.
+const CONFIG_READ_TTL_MS = 60_000;
+const _configReadCache = new Map(); // key -> { value, at }
+function readConfigFileCached(name, { ttlMs = CONFIG_READ_TTL_MS, now = Date.now } = {}) {
+  const b = safeBrand();
+  const key = configReadPaths(name, b).join('\n');
+  const hit = _configReadCache.get(key);
+  const t = now();
+  if (hit && t - hit.at < ttlMs) return hit.value;
+  const value = readConfigFileSync(name, { b });
+  _configReadCache.set(key, { value, at: t });
+  return value;
+}
+// Drop the cached reads (all of them). For a writer that just changed a config
+// file in this process (provisionMasterKey) and for tests.
+function clearConfigReadCache() {
+  _configReadCache.clear();
+}
+
 // Resolve an env var by SUFFIX across the configured prefix + legacy prefixes.
 // resolveEnv('API_BASE') tries <PREFIX>_API_BASE (BONGOS_ on vanilla, OTB_ on
 // the OTB instance), then CLOUDBONGOS_/OTB_/GDS_/PMS_API_BASE. Returns undefined
@@ -349,6 +375,8 @@ module.exports = {
   configPath,
   configReadPaths,
   readConfigFileSync,
+  readConfigFileCached,
+  clearConfigReadCache,
   SESSION_FILENAMES,
   readSessionConfigSync,
   resolveEnv,

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.23.21'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
+const CORE_VERSION = '1.24.1'; // 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');
@@ -197,6 +197,12 @@ module.exports = {
   //     which a module cannot enforce without being able to ask who that is. It is
   //     a READ of an existing row; it grants nothing by itself.
   getFoundingBuilder: (...a) => require('./bongos/db-kernel').getFoundingBuilder(...a),
+  // taskNeeds — what a task needs (owner, server) and what a builder can do
+  //     (task 1004950, ADR 0395). Core because the session optimizer applies the
+  //     same feed rule and cannot require a module; capabilities are read fresh
+  //     per call, like rank. The READ surface only — granting server access is
+  //     core's owner-seat route, never a module's call.
+  get taskNeeds() { const { READ_SURFACE } = require('./bongos/task-needs'); return READ_SURFACE; },
   insertAuditLog: (...a) => require('./bongos/db-kernel').insertAuditLog(...a),
   get LIVE_RANK_LADDER() { return require('./bongos/db-kernel').LIVE_RANK_LADDER; },
   // The ladder as the canonical 1-based rank → tier map (BV1.R108) — modules
@@ -244,6 +250,13 @@ module.exports = {
   //     therefore reaches via the exposed `pool` and its own client instead.
   get grantedScopeCoversRepos() { return require('./bongos/auth-config').grantedScopeCoversRepos; },
 
+  // --- prelaunchActive() — is this instance in pre-launch (stealth: the shared
+  //     password gate is on)? Exposed for the provisioning module's adopt preflight
+  //     (task 1004998): while it is on, a project may not adopt a PUBLIC repo. Read
+  //     here rather than from the env vars so the gate and its callers can never
+  //     disagree about which variables switch it on.
+  get prelaunchActive() { return require('./bongos/prelaunch-switch').enabled; },
+
   // --- KERNEL trust classifiers (ADR 0091 §1, KERNEL_FILES) — the deterministic
   //     route→rank + protected-path matchers. They are KERNEL (the trust
   //     boundary, never "called" by a domain), exposed so a module that runs the