@bongos/core 1.23.21 → 1.24.1

package/scripts/bongos/strand-watch.js

@@ -31,7 +31,8 @@
 //
 // Usage:
 //   node scripts/bongos/strand-watch.js                 # human-readable report
-//   node scripts/bongos/strand-watch.js --line          # ONE line, or nothing; always exit 0
+//   node scripts/bongos/strand-watch.js --line          # ONE line, or nothing; always exit 0 (cached; see linePlan)
+//   node scripts/bongos/strand-watch.js --refresh-line  # refresh that cache; prints nothing (spawned detached by --line)
 //   node scripts/bongos/strand-watch.js --json          # machine shape
 //   node scripts/bongos/strand-watch.js --hours N       # override the `completed` threshold
 //
@@ -240,7 +241,28 @@ function line(r, { max = 3 } = {}) {
     // Name the skill, not just the diagnosis: 19 of the last 30 days' session logs mention a strand,
     // and the next claim is refused REBASE_REQUIRED until one is landed or released (task 1003548).
     + `Run /strand-fix ${worst.id} to walk it. `
-    + 'A strand produces no signal of its own; this line is the only one.';
+    + 'A strand produces no signal of its own; this line is the only one. '
+    // Agents kept relaying this to the owner on every session (owner, 2026-10-28; task 1004952).
+    + RELAY_RULE;
+}
+
+// This line is context for the AGENT. Fixed text only — it is injected every session.
+// "Fix it yourself" sent EVERY session at the same strand (task 1004956): /strand-fix now takes a
+// lease first, so the rule says one session fixes it and the others are told who has it.
+const RELAY_RULE = 'This note is for you, not the builder: do not repeat it to them. ONE session fixes a strand — '
+  + '/strand-fix takes it first and stops if another session already has it; tell the builder only if it needs a person or they ask.';
+
+// The lease clause, appended at PRINT time, never cached: the line text is shared across
+// sessions for up to two hours (linePlan), while who holds a strand changes by the minute and
+// differs per worktree. Fail-open: no lease folder, no clause.
+function withLeases(text, { now = Date.now() } = {}) {
+  if (!text) return text;
+  try {
+    const lease = require('./strand-lease.js');
+    const me = lease.currentHolder();
+    const clause = lease.othersClause(lease.liveLeases({ dir: lease.leaseDir(), now }), me && me.holder, now);
+    return clause ? `${text} ${clause}` : text;
+  } catch { return text; }
 }
 
 function report(r) {
@@ -273,6 +295,77 @@ function report(r) {
   console.log('');
 }
 
+// ---- the SessionStart line, kept off the critical path (task 1004928) --------
+//
+// THE MEASUREMENT. The credit-burn audit timed this hook at 8.2 s — the slowest SessionStart
+// producer, and so the floor for every session start. The shared cache it used (task 1003689)
+// lived 60 s, which only helps sessions opened together; the next session an hour later paid
+// the whole ledger read again, up to 8 s per call (and the held-tweak pass can add another).
+//
+// THE FIX. A strand is measured in hours (one hour for `confirmed`, twelve for `completed`), so
+// an answer a few minutes old is as true as a fresh one. So: keep the answer LINE_FRESH_MS and
+// print it at once; past that, up to LINE_STALE_MAX_MS, print it at once LABELLED WITH ITS AGE
+// and refresh the cache in a detached child for the next session; with nothing usable, read the
+// ledger but give up after LINE_DEADLINE_MS. An undetermined read is never cached — a stored
+// silence would pass for a clean board for the whole fresh window.
+const LINE_CACHE_KEY = 'strand-watch-line';
+const LINE_FRESH_MS = 15 * 60 * 1000;
+const LINE_STALE_MAX_MS = 2 * 60 * 60 * 1000;
+const LINE_DEADLINE_MS = 4000;
+
+// PURE — what to do with the cached record: 'fresh' (print it), 'stale' (print it with its age
+// and refresh in the background) or 'miss' (read the ledger now, time-boxed). A record from the
+// future means the clock moved, and is treated as a miss rather than trusted.
+function linePlan(record, nowMs, { freshMs = LINE_FRESH_MS, staleMaxMs = LINE_STALE_MAX_MS } = {}) {
+  if (!record || typeof record.at !== 'number' || !Number.isFinite(nowMs)) return 'miss';
+  const age = nowMs - record.at;
+  if (age < 0) return 'miss';
+  if (age < freshMs) return 'fresh';
+  if (age < staleMaxMs) return 'stale';
+  return 'miss';
+}
+
+// PURE — the line as printed from a stale cache: the same words, plus how old they are, so a
+// reader can weigh them. A clean (null) answer stays silent: there is nothing to label.
+function labelStale(text, ageMs) {
+  if (!text) return null;
+  return `${text} (Checked ${humanAge(ageMs)} ago; refreshing for the next session.)`;
+}
+
+// The ledger read for the line, bounded as a WHOLE (check() bounds each call, not the sum).
+// Throws on an undetermined read so probe-cache stores nothing.
+async function produceLine(opts, deadlineMs) {
+  let timer;
+  const deadline = new Promise((_, rej) => { timer = setTimeout(() => rej(new Error('deadline')), deadlineMs); });
+  try {
+    const r = await Promise.race([check({ ...opts, timeoutMs: Math.min(deadlineMs, DEFAULT_TIMEOUT_MS) }), deadline]);
+    if (!r || r.undetermined) throw new Error('undetermined');
+    return line(r);
+  } finally { clearTimeout(timer); }
+}
+
+function readLineRecord() {
+  try {
+    const { cachePath } = require('./probe-cache.js');
+    return JSON.parse(require('node:fs').readFileSync(cachePath(LINE_CACHE_KEY), 'utf8'));
+  } catch { return null; }
+}
+
+// Detached + unref'd + hidden, so the session start never waits on it (windowsHide: a detached
+// child on Windows otherwise flashes a console window). --hours is passed through so the
+// refreshed answer uses the same threshold.
+function spawnRefresh() {
+  try {
+    const args = [__filename, '--refresh-line'];
+    const hours = arg('--hours');
+    if (hours) args.push('--hours', String(hours));
+    const child = require('node:child_process').spawn(process.execPath, args, {
+      detached: true, stdio: 'ignore', windowsHide: true, cwd: process.cwd(),
+    });
+    child.unref();
+  } catch { /* the next session reads the ledger itself */ }
+}
+
 async function main() {
   const hours = Number(arg('--hours'));
   const opts = Number.isFinite(hours) && hours > 0 ? { completedStaleMs: hours * 3600000 } : {};
@@ -285,16 +378,39 @@ async function main() {
   // deploy-divergence's identical comment).
   if (hasFlag('--line')) {
     try {
-      // SHARED ACROSS CONCURRENT SESSION STARTS (task 1003689). Four sessions opened
-      // within three seconds — one worktree per claim, the normal pattern here — used
-      // to make this same call four times and ALL of them timed out, which produces no
-      // line at all. Silence from a truth-teller is indistinguishable from 'nothing to
-      // report', so the brief was lost without a symptom. The first session to ask now
-      // answers for the rest.
+      // SHARED ACROSS SESSION STARTS (task 1003689, widened by task 1004928). Four sessions
+      // opened within three seconds — one worktree per claim, the normal pattern here — used
+      // to make this same call four times and ALL of them timed out, which produces no line
+      // at all. The first session to ask answers for the rest; see linePlan for how long.
+      const rec = readLineRecord();
+      const plan = linePlan(rec, Date.now());
+      if (plan === 'fresh') {
+        if (rec.value) console.log(withLeases(rec.value));
+      } else if (plan === 'stale') {
+        const one = labelStale(rec.value, Date.now() - rec.at);
+        if (one) console.log(withLeases(one));
+        spawnRefresh();
+      } else {
+        const { cached } = require('./probe-cache.js');
+        const { value: one, from } = await cached(LINE_CACHE_KEY, () => produceLine(opts, LINE_DEADLINE_MS), { ttlMs: LINE_FRESH_MS });
+        // A sibling holds the lock and the cache handed back its last answer, however old:
+        // say how old, so a long-expired line is never passed off as current.
+        const shown = from === 'stale-while-locked' && rec && typeof rec.at === 'number'
+          ? labelStale(one, Date.now() - rec.at) : one;
+        if (shown) console.log(withLeases(shown));
+      }
+    } catch { /* no session, offline, unreadable, past the deadline — all silence */ }
+    process.exitCode = 0;
+    return;
+  }
+
+  // --refresh-line: the detached child spawnRefresh starts. ttlMs 0 forces a fresh read; a
+  // sibling already refreshing holds the lock, and then this child simply stops. Prints nothing.
+  if (hasFlag('--refresh-line')) {
+    try {
       const { cached } = require('./probe-cache.js');
-      const { value: one } = await cached('strand-watch-line', async () => line(await check(opts)));
-      if (one) console.log(one);
-    } catch { /* no session, offline, unreadable — all silence */ }
+      await cached(LINE_CACHE_KEY, () => produceLine(opts, DEFAULT_TIMEOUT_MS * 2), { ttlMs: 0 });
+    } catch { /* the next session reads the ledger itself */ }
     process.exitCode = 0;
     return;
   }
@@ -310,6 +426,7 @@ if (require.main === module) {
 }
 
 module.exports = {
-  check, line, report, classifyStrand, rankStrands, humanAge,
+  check, line, withLeases, report, classifyStrand, rankStrands, humanAge,
+  linePlan, labelStale, produceLine, LINE_FRESH_MS, LINE_STALE_MAX_MS, LINE_DEADLINE_MS,
   CONFIRMED_STALE_MS, COMPLETED_STALE_MS, STRAND_REASON_PREFIX, WATCHED, PAGE_LIMIT,
 };

package/scripts/bongos/version-literal-guard.js

@@ -11,8 +11,8 @@
 //
 // WHAT IT CHECKS, narrowly: a version-shaped literal ASSIGNED TO A VERSION FIELD
 // or used as a version DEFAULT, in an executable script. Not any mention of a
-// version anywhere — smoke-claim-consistency.sh legitimately says "PMS-V2 P6 not
-// live yet" in a comment and an echo, and flagging that would be the over-broad
+// version anywhere — a script may legitimately say "PMS-V2 P6 not live yet" in a
+// comment or an echo, and flagging that would be the over-broad
 // source assertion this repo has learned to avoid (learning 1000196). Comment
 // lines are stripped before matching for the same reason.
 //

package/scripts/discord/post.js

@@ -16,10 +16,11 @@
 // modules/discord/ship-broadcast.js, whose kind filter decides which ships are
 // news. What does pass through here is the project's own news in plain words,
 // which is what #ship-news promises: a builder graduating
-// (modules/onboarding/onboarding-state.js), a rank change
-// (src/bongos/routes/builders.js), an outage heads-up
+// (modules/onboarding/onboarding-state.js), an outage heads-up
 // (modules/provisioning/pollers/liveness-notify.js) and the style-guide audit
-// (scripts/cron/style_guide_audit.sh). Builder housekeeping names its channel:
+// (scripts/cron/style_guide_audit.sh). A rank change posts the same #ship-news line
+// in-process through the discord.post port instead (task 1004962,
+// src/bongos/routes/builders.js). Builder housekeeping names its channel:
 // scripts/bongos/pulse.js's reclaim nudge passes --channel ship_feed.
 
 const fs = require('node:fs');

package/scripts/gds/seed-tasks.js

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+// scripts/gds/seed-tasks.js — @bongos-forwarder (task 1004848). Generated by
+// scripts/bongos/codemod-rename-scripts-gds.js; do not edit.
+// The real script is scripts/bongos/seed-tasks.js. This forwarder keeps callers that still name
+// the old path working, and warns once so they get repointed. Task 1003706 removes it.
+'use strict';
+require('../bongos/forwarder.js').forward(module, 'seed-tasks.js');

package/scripts/gds/{build-bongos.js → strand-lease.js}

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
-// scripts/gds/build-bongos.js — @bongos-forwarder (task 1004848). Generated by
+// scripts/gds/strand-lease.js — @bongos-forwarder (task 1004848). Generated by
 // scripts/bongos/codemod-rename-scripts-gds.js; do not edit.
-// The real script is scripts/bongos/build-bongos.js. This forwarder keeps callers that still name
+// The real script is scripts/bongos/strand-lease.js. This forwarder keeps callers that still name
 // the old path working, and warns once so they get repointed. Task 1003706 removes it.
 'use strict';
-require('../bongos/forwarder.js').forward(module, 'build-bongos.js');
+require('../bongos/forwarder.js').forward(module, 'strand-lease.js');

package/scripts/hall-preview/server.js

@@ -156,6 +156,15 @@ const FIXTURE_FALLBACKS = [
   // a store version's how-to page (task 1004366): one reading serves any key and
   // version, since the Modules tab's how-to view shows one document.
   [/^store\/modules\/[a-z0-9-]+\/versions\/[^/]+\/howto$/, 'store__modules__howto'],
+  // the studio's AI pages (task 1004921): one request per STATE, picked by id,
+  // so the waiting page, a result on the balance, a result on a Gemini key and a
+  // failed run each render: 1002 is running, 1003 failed, 1004 ran on the
+  // builder's own Gemini key, and any other id is the finished result on the
+  // balance.
+  [/^ai-studio\/requests\/1002$/, 'ai-studio__requests__running'],
+  [/^ai-studio\/requests\/1003$/, 'ai-studio__requests__failed'],
+  [/^ai-studio\/requests\/1004$/, 'ai-studio__requests__own'],
+  [/^ai-studio\/requests\/\d+$/, 'ai-studio__requests__done'],
 ];
 
 // CANNED WRITES (task 1004321). The tweak editor's whole flow is writes (the
@@ -186,6 +195,11 @@ const CANNED_WRITES = [
   // Settings → Software update's "Ask for this upgrade" (task 1004595), so the
   // pending line the panel draws after the press renders here too.
   ['POST', /^software-update\/request$/, 'software-update__request.post'],
+  // the studio's AI pages (task 1004921): a file uploads, a request is sent
+  // (it answers as 1002, the running one), and money is added.
+  ['POST', /^ai-studio\/uploads$/, 'ai-studio__uploads.post'],
+  ['POST', /^ai-studio\/requests$/, 'ai-studio__requests.post'],
+  ['POST', /^ai-studio\/topup$/, 'ai-studio__topup.post'],
 ];
 
 // A DATE THAT ROTS CANNOT DEMO AN AGE SIGNAL (task 1004041). The help-request
@@ -316,6 +330,13 @@ app.use((req, res, next) => {
   // Studio's review card, where the picture IS the card — previews as a broken
   // frame, so the one thing being reviewed is the one thing you cannot see.
   // A generated stand-in; see scripts/hall-preview/task-visual.js.
+  // The studio's AI files (task 1004921) are images too: an upload's thumbnail
+  // and the pictures a request made. The same generated stand-in.
+  if (/^ai-studio\/files\/\d+$/.test(apiPath) && req.method === 'GET') {
+    const png = require('./task-visual').placeholderPng();
+    res.set({ 'content-type': 'image/png', 'cache-control': 'no-store' });
+    return res.end(png);
+  }
   if (/^task-visuals\/[A-Za-z0-9._-]+$/.test(apiPath) && req.method === 'GET') {
     // HALL_PREVIEW_VISUALS=<dir> serves a REAL image of that name from <dir>
     // instead (task 1004323): the Approval queue's review sheet shows the renders

package/src/bongos/auth-config.js

@@ -10,6 +10,7 @@
 'use strict';
 
 const ic = require('../instance-config');
+const { readConfigFileCached } = require('../instance-config'); // destructured: knip credits only this form
 const { branding, userAgent } = require('../branding');
 
 const SCOPE = 'read:user';
@@ -62,6 +63,29 @@ function grantedScopeCoversRepos(granted) {
 // (the user just re-runs the setup skill). Acceptable for V1 — scaling up means
 // moving this to Redis or a tiny `device_flows` table.
 const deviceFlows = new Map();
+// Task 1004964: expired flows used to be reaped only when a NEW flow started, so the
+// map held its last burst forever on a quiet instance. Now it is also pruned on an
+// unref'd five-minute timer (rare enough not to keep an idle server awake), and
+// hard-capped: at the cap the oldest-inserted flow is evicted, the newest survive.
+const DEVICE_FLOW_MAX = 50000;
+const DEVICE_FLOW_PRUNE_MS = 5 * 60 * 1000;
+
+function pruneDeviceFlows(now = Date.now()) {
+  for (const [k, v] of deviceFlows) {
+    if (v.expires_at < now) deviceFlows.delete(k);
+  }
+}
+
+// trackDeviceFlow(code, flow) — record a pending flow, evicting oldest-first at the cap.
+// O(1): expiry is the timer's job, so a burst of starts never rescans the whole map.
+function trackDeviceFlow(code, flow) {
+  deviceFlows.delete(code);
+  while (deviceFlows.size >= DEVICE_FLOW_MAX) deviceFlows.delete(deviceFlows.keys().next().value);
+  deviceFlows.set(code, flow);
+}
+
+const deviceFlowPruneTimer = setInterval(pruneDeviceFlows, DEVICE_FLOW_PRUNE_MS);
+if (typeof deviceFlowPruneTimer.unref === 'function') deviceFlowPruneTimer.unref();
 
 function loadGithubCreds() {
   // Resolve the configured instance prefix first (CLOUDBONGOS_ on a fresh
@@ -77,7 +101,7 @@ function loadGithubCreds() {
   // across the configured config dir and the legacy ~/.config/otb dir.
   for (const name of ['gds-github.json', 'pms-github.json']) {
     try {
-      const raw = ic.readConfigFileSync(name);
+      const raw = readConfigFileCached(name); // task 1004924: per-request path, cached (60 s TTL)
       if (raw) {
         const creds = JSON.parse(raw);
         if (creds.client_id && creds.client_secret) return creds;
@@ -143,6 +167,10 @@ module.exports = {
   SCOPE,
   authConfigured,
   deviceFlows,
+  trackDeviceFlow,
+  pruneDeviceFlows,
+  DEVICE_FLOW_MAX,
+  DEVICE_FLOW_PRUNE_MS,
   grantedScopeCoversRepos,
   idpConfigured,
   idpEnabled,

package/src/bongos/auth-discord.js

@@ -8,7 +8,7 @@
 
 'use strict';
 
-const ic = require('../instance-config');
+const { readConfigFileCached } = require('../instance-config'); // destructured: knip credits only this form
 
 const DISCORD_SCOPE = 'identify guilds.join';
 
@@ -17,7 +17,7 @@ function loadDiscordCreds() {
   const clientSecret = process.env.DISCORD_CLIENT_SECRET;
   if (clientId && clientSecret) return { client_id: clientId, client_secret: clientSecret };
   try {
-    const raw = ic.readConfigFileSync('discord-bot.json');
+    const raw = readConfigFileCached('discord-bot.json'); // task 1004924: per-request path, cached (60 s TTL)
     if (raw) {
       const creds = JSON.parse(raw);
       if (creds.client_id && creds.client_secret) {
@@ -43,7 +43,7 @@ function loadDiscordBotToken() {
   const envToken = process.env.DISCORD_BOT_TOKEN;
   if (envToken) return envToken;
   try {
-    const raw = ic.readConfigFileSync('discord-bot.json');
+    const raw = readConfigFileCached('discord-bot.json'); // task 1004924: per-request path, cached (60 s TTL)
     if (raw) {
       const creds = JSON.parse(raw);
       if (creds.bot_token) return creds.bot_token;

package/src/bongos/auth-github.js

@@ -25,7 +25,7 @@ const { pool } = require('./pool');
 const seams = require('../module-seams');
 const { branding, userAgent } = require('../branding');
 const { firstTimeAdmissionBlocked, maybeSeatFirstAdmin, openEnrollmentEnabled, safeSyncRankRole } = require('./auth-admission.js');
-const { SCOPE, deviceFlows, loadGithubCreds, scopeForWebFlow } = require('./auth-config.js');
+const { SCOPE, deviceFlows, trackDeviceFlow, loadGithubCreds, scopeForWebFlow } = require('./auth-config.js');
 const log = require('./logger').logger.child({ src: 'auth-github' });
 
 function newSessionToken() {
@@ -121,15 +121,12 @@ async function startDeviceFlow() {
     throw new Error('GitHub device/code returned no device_code (unexpected response shape).');
   }
   // data: { device_code, user_code, verification_uri, expires_in, interval }
-  deviceFlows.set(data.device_code, {
+  // Evicts oldest-first at the size cap; an unref'd timer reaps expired flows (auth-config.js).
+  trackDeviceFlow(data.device_code, {
     interval: data.interval || 5,
     expires_at: Date.now() + data.expires_in * 1000,
     last_polled_at: 0,
   });
-  // Reap expired flows (cheap)
-  for (const [k, v] of deviceFlows) {
-    if (v.expires_at < Date.now()) deviceFlows.delete(k);
-  }
   return {
     device_code: data.device_code,
     user_code: data.user_code,

package/src/bongos/auth-google.js

@@ -0,0 +1,217 @@
+// src/bongos/auth-google.js — signing in with Google (task 1004993, ADR 0396).
+//
+// WHY. A person with no GitHub account could not sign up at all. The owner chose
+// Google as the one new way in (no email codes, no passwords, no other
+// providers). This file holds the Google half of the browser sign-in: the
+// authorize URL, the code exchange, checking the ID token Google returns, and
+// turning that identity into a session on this instance.
+//
+// WHO THE PERSON IS. Google's own stable user id (`sub`) is the only thing that
+// finds a person. The hub's account-logins table maps it to the person key
+// (ADR 0393); an email is shown, never looked up, so owning an address that
+// matches someone's account reaches nothing. The lookup lives on the hub, so this
+// only works where the platform-identity module answers the `signInWithGoogle`
+// port function — on every other instance Google sign-in is simply not offered.
+//
+// THE BUILDER ROW. Core's `builders.github_login` cannot be empty, and a person
+// who signed up with Google has no GitHub login. They get a stand-in that can
+// never be a GitHub login — `~` and the handle they choose on their account page
+// (`standInLogin`) — so no admission rule, invite or GitHub call keyed on a login
+// can ever reach a real GitHub user through them. Once GitHub is linked (task
+// 1004995) the real login is used instead.
+//
+// THE ID TOKEN. It comes straight from Google's token endpoint over TLS in
+// exchange for our client secret, so its signature is not re-checked (OpenID
+// Connect Core's "ID Token Validation" allows TLS in its place); its issuer,
+// audience, expiry and nonce are.
+'use strict';
+
+const crypto = require('node:crypto');
+const ic = require('../instance-config');
+const { createSession, getBuilderByGithubId, upsertBuilder } = require('./db-kernel');
+const { pool } = require('./pool');
+const seams = require('../module-seams');
+const { firstTimeAdmissionBlocked, maybeSeatFirstAdmin, safeSyncRankRole } = require('./auth-admission.js');
+const log = require('./logger').logger.child({ src: 'auth-google' });
+
+const GOOGLE_AUTHORIZE_URL = 'https://accounts.google.com/o/oauth2/v2/auth';
+const GOOGLE_TOKEN_URL = 'https://oauth2.googleapis.com/token';
+const GOOGLE_ISSUERS = Object.freeze(['https://accounts.google.com', 'accounts.google.com']);
+// Identity only: who they are, the address Google vouches for, a name and a picture.
+const GOOGLE_SCOPE = 'openid email profile';
+// Clock skew allowed when checking the token's expiry.
+const EXPIRY_SKEW_MS = 60 * 1000;
+
+// The Google sign-in app's credentials, from env (<PREFIX>_GOOGLE_CLIENT_ID /
+// _GOOGLE_CLIENT_SECRET), or null. Env only — never a committed file.
+function loadGoogleCreds() {
+  const clientId = ic.resolveEnv('GOOGLE_CLIENT_ID');
+  const clientSecret = ic.resolveEnv('GOOGLE_CLIENT_SECRET');
+  return clientId && clientSecret ? { client_id: clientId, client_secret: clientSecret } : null;
+}
+
+// The hub port that finds or creates a person by their Google id, or null.
+function googleHub() {
+  try {
+    const hub = seams.resolveOptional('platform-identity.hub');
+    return hub && typeof hub.signInWithGoogle === 'function' ? hub : null;
+  } catch {
+    return null;
+  }
+}
+
+// Is "Continue with Google" offered here? Both halves must be present: the
+// owner's Google app, and the hub that keeps who signs in with it.
+function googleConfigured() {
+  return !!loadGoogleCreds() && !!googleHub();
+}
+
+// The Google authorize URL for one sign-in. `nonce` is echoed back inside the ID
+// token and checked, binding the token to this browser's sign-in.
+function buildGoogleAuthorizeUrl({ state, nonce, redirectUri }) {
+  const creds = loadGoogleCreds();
+  if (!creds) throw new Error('Google sign-in is not configured');
+  const u = new URL(GOOGLE_AUTHORIZE_URL);
+  u.searchParams.set('client_id', creds.client_id);
+  u.searchParams.set('redirect_uri', redirectUri);
+  u.searchParams.set('response_type', 'code');
+  u.searchParams.set('scope', GOOGLE_SCOPE);
+  u.searchParams.set('state', state);
+  u.searchParams.set('nonce', nonce);
+  // Let a person with several Google accounts pick one, instead of Google
+  // silently using whichever is signed in (the GitHub "New account" lesson).
+  u.searchParams.set('prompt', 'select_account');
+  return u.toString();
+}
+
+// The claims inside an ID token (the middle, base64url part), or null.
+function decodeIdToken(idToken) {
+  const parts = String(idToken || '').split('.');
+  if (parts.length !== 3) return null;
+  try {
+    return JSON.parse(Buffer.from(parts[1], 'base64url').toString('utf8'));
+  } catch {
+    return null;
+  }
+}
+
+// Check an ID token's claims → the identity this sign-in carries
+// { subject, email, emailVerified, displayName, avatarUrl }. Throws on anything
+// that makes the token not ours, not Google's, stale, or not this sign-in's.
+function verifyGoogleClaims(claims, { clientId, nonce, nowMs = Date.now() }) {
+  if (!claims || typeof claims !== 'object') throw new Error('Google returned no identity');
+  if (!GOOGLE_ISSUERS.includes(claims.iss)) throw new Error('the identity was not issued by Google');
+  const aud = Array.isArray(claims.aud) ? claims.aud : [claims.aud];
+  if (!clientId || !aud.includes(clientId)) throw new Error('the identity was issued for another app');
+  if (aud.length > 1 && claims.azp !== clientId) throw new Error('the identity was issued for another app');
+  if (!Number.isFinite(claims.exp) || claims.exp * 1000 + EXPIRY_SKEW_MS < nowMs) throw new Error('the identity has expired');
+  if (!nonce || typeof claims.nonce !== 'string' || !timingSafeEqualStr(claims.nonce, nonce)) {
+    throw new Error('the identity does not belong to this sign-in');
+  }
+  const subject = typeof claims.sub === 'string' ? claims.sub : '';
+  if (!/^[\x21-\x7e]{1,255}$/.test(subject)) throw new Error('Google returned no account id');
+  return {
+    subject,
+    email: typeof claims.email === 'string' ? claims.email : null,
+    emailVerified: claims.email_verified === true || claims.email_verified === 'true',
+    displayName: typeof claims.name === 'string' ? claims.name.slice(0, 100) : null,
+    avatarUrl: typeof claims.picture === 'string' ? claims.picture : null,
+  };
+}
+
+function timingSafeEqualStr(a, b) {
+  const x = Buffer.from(String(a));
+  const y = Buffer.from(String(b));
+  return x.length === y.length && crypto.timingSafeEqual(x, y);
+}
+
+// Trade the code Google redirected back with for the ID token, and check it →
+// the identity. `fetchImpl` is injectable so a test needs no network.
+async function exchangeGoogleCode({ code, redirectUri, nonce, fetchImpl = fetch, nowMs = Date.now() }) {
+  const creds = loadGoogleCreds();
+  if (!creds) throw new Error('Google sign-in is not configured');
+  const res = await fetchImpl(GOOGLE_TOKEN_URL, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/x-www-form-urlencoded', Accept: 'application/json' },
+    body: new URLSearchParams({
+      code,
+      client_id: creds.client_id,
+      client_secret: creds.client_secret,
+      redirect_uri: redirectUri,
+      grant_type: 'authorization_code',
+    }).toString(),
+  });
+  const data = await res.json().catch(() => ({}));
+  if (!res.ok || data.error || !data.id_token) {
+    throw new Error(`Google token exchange: ${data.error_description || data.error || `HTTP ${res.status}`}`);
+  }
+  return verifyGoogleClaims(decodeIdToken(data.id_token), { clientId: creds.client_id, nonce, nowMs });
+}
+
+// The builder-row login for a person with no GitHub linked: `~` plus their
+// handle. `~` is never in a GitHub login, so this can never name a real GitHub
+// user (ADR 0396). The handle is the one they choose on their account page.
+function standInLogin(handle, personKey) {
+  const h = String(handle || '').toLowerCase().replace(/[^a-z0-9-]/g, '').slice(0, 39);
+  return `~${h || `builder${String(personKey || '').replace(/\D/g, '')}`}`;
+}
+
+function signInError(code, extra = {}) {
+  const err = new Error(code.toLowerCase());
+  err.code = code;
+  Object.assign(err, extra);
+  return err;
+}
+
+// Turn a checked Google identity into a web session here → { token, builder,
+// expiresAt, created }. The same gates as the GitHub web sign-in
+// (completeWebFlow): a first-timer is admitted only under open enrollment (they
+// have no GitHub login an Archon could have invited), and a switched-off
+// builder gets no session.
+async function completeGoogleFlow({ identity, userAgent }) {
+  const hub = googleHub();
+  if (!hub) throw signInError('GOOGLE_NOT_AVAILABLE');
+  const person = await hub.signInWithGoogle(identity);
+  const existing = await getBuilderByGithubId(person.personKey);
+  if (!existing && firstTimeAdmissionBlocked({ existing, approved: false, login: null })) {
+    throw signInError('NOT_APPROVED');
+  }
+  const login = person.githubLogin || standInLogin(person.handle, person.personKey);
+  let builder = await upsertBuilder({
+    githubId: person.personKey,
+    githubLogin: login,
+    displayName: identity.displayName || person.handle || login,
+    avatarUrl: identity.avatarUrl,
+  });
+  builder = await maybeSeatFirstAdmin(builder);
+  if (builder.status === 'inactive') throw signInError('BUILDER_INACTIVE', { login });
+  await safeSyncRankRole(builder);
+  const token = crypto.randomBytes(32).toString('hex');
+  const expiresAt = new Date(Date.now() + 30 * 24 * 60 * 60 * 1000);
+  await createSession({ builderId: builder.id, token, source: 'web', userAgent: userAgent ?? null, expiresAt });
+  await seams.resolveOptional('onboarding')?.safeMarkStage(pool, builder.id, 'auth_complete', builder);
+  // The hub's own browser sign-in accepts the platform terms (ADR 0217 D3), as
+  // for GitHub. Best-effort: a failed stamp never costs the sign-in.
+  try {
+    if (typeof hub.recordHubSignin === 'function') {
+      await hub.recordHubSignin({
+        githubId: String(person.personKey),
+        githubLogin: person.githubLogin,
+        displayName: identity.displayName,
+        avatarUrl: identity.avatarUrl,
+      });
+    }
+  } catch (err) {
+    log.error({ err: err && err.message }, 'hub sign-in terms acceptance not recorded (google)');
+  }
+  return { token, builder, expiresAt, created: !!person.created };
+}
+
+module.exports = {
+  googleConfigured,
+  buildGoogleAuthorizeUrl,
+  verifyGoogleClaims,
+  exchangeGoogleCode,
+  standInLogin,
+  completeGoogleFlow,
+};