@bongos/core 1.23.22 → 1.24.1

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,
+};

package/src/bongos/device-approval.js

@@ -0,0 +1,140 @@
+// src/bongos/device-approval.js — command-line sign-in approved in the browser
+// (task 1004993, ADR 0396).
+//
+// WHY. The CLI's sign-in has always been GitHub's own device flow: the terminal
+// shows a code and the person types it at github.com. A person who signs in with
+// Google has no GitHub account to type it into. So when this instance offers
+// Google sign-in, the CLI's device flow is served HERE instead: the terminal gets
+// a code and a link to this instance's own approval page, the person signs in
+// there with GitHub or Google as they would in the browser, checks the code and
+// presses Approve, and the terminal's next poll receives a CLI session.
+//
+// The CLI needs no change for this: /auth/device/start and /auth/device/poll keep
+// their request and response shapes, and the CLI already opens whatever
+// `verification_uri` it is handed.
+//
+// WHAT HOLDS IT SAFE. Approving is a cookie-session POST (the same rule as
+// /auth/cli-token/issue: a bearer cannot mint a bearer), it binds the CLI session
+// to whoever approved, and the page tells the person to check the code matches
+// their terminal and to cancel a link someone sent them — the device-code
+// phishing risk GitHub's own page carries, stated the same way. A code is
+// single-use, lives FLOW_TTL_MS and is forgotten once polled to completion.
+//
+// In-memory, like GitHub's device flows in auth-config.js: a restart drops a
+// pending sign-in and the person runs it again.
+'use strict';
+
+const crypto = require('node:crypto');
+
+const FLOW_TTL_MS = 10 * 60 * 1000;
+const POLL_INTERVAL_S = 5;
+const FLOWS_MAX = 10000;
+// No vowels, so a code never spells a word; no look-alike letters.
+const USER_CODE_ALPHABET = 'BCDFGHJKLMNPQRSTVWXZ';
+
+const flows = new Map(); // device_code → flow
+const byUserCode = new Map(); // user_code → device_code
+
+function prune(now) {
+  for (const [deviceCode, f] of flows) {
+    if (f.expiresAt <= now) forget(deviceCode);
+  }
+}
+
+function forget(deviceCode) {
+  const f = flows.get(deviceCode);
+  if (f) byUserCode.delete(f.userCode);
+  flows.delete(deviceCode);
+}
+
+function newUserCode() {
+  let out = '';
+  for (let i = 0; i < 8; i++) out += USER_CODE_ALPHABET[crypto.randomInt(USER_CODE_ALPHABET.length)];
+  return `${out.slice(0, 4)}-${out.slice(4)}`;
+}
+
+// A code as a person might type it (lower case, spaces, no dash) → canonical
+// XXXX-XXXX, or null when it cannot be one.
+function normalizeUserCode(raw) {
+  const letters = String(raw || '').toUpperCase().replace(/[^A-Z]/g, '');
+  if (letters.length !== 8 || [...letters].some((c) => !USER_CODE_ALPHABET.includes(c))) return null;
+  return `${letters.slice(0, 4)}-${letters.slice(4)}`;
+}
+
+// Start a sign-in for the terminal → the same shape GitHub's device/code answers,
+// so the CLI reads it unchanged. `pageUrl` is this instance's approval page.
+function startBrowserDeviceFlow({ pageUrl, now = Date.now() }) {
+  prune(now);
+  while (flows.size >= FLOWS_MAX) forget(flows.keys().next().value);
+  const deviceCode = crypto.randomBytes(32).toString('hex');
+  let userCode = newUserCode();
+  while (byUserCode.has(userCode)) userCode = newUserCode();
+  flows.set(deviceCode, { userCode, expiresAt: now + FLOW_TTL_MS, lastPolledAt: 0, result: null });
+  byUserCode.set(userCode, deviceCode);
+  const complete = `${pageUrl}?code=${encodeURIComponent(userCode)}`;
+  return {
+    device_code: deviceCode,
+    user_code: userCode,
+    // The CLI opens verification_uri, so it carries the code: the page opens
+    // with it filled in. verification_uri_complete is the standard name for it.
+    verification_uri: complete,
+    verification_uri_complete: complete,
+    expires_in: Math.round(FLOW_TTL_MS / 1000),
+    interval: POLL_INTERVAL_S,
+  };
+}
+
+// The pending flow a typed code names, or null (unknown, expired, already decided).
+function pendingFlow(userCode, now = Date.now()) {
+  const code = normalizeUserCode(userCode);
+  const deviceCode = code && byUserCode.get(code);
+  const f = deviceCode && flows.get(deviceCode);
+  if (!f || f.expiresAt <= now || f.result) return null;
+  return { deviceCode, userCode: code };
+}
+
+// The signed-in person approved (or cancelled) the code. On approve, `mint` is
+// called once to create the CLI session for THIS person and its result is held
+// for the terminal's next poll. → true when a pending code was decided.
+async function decideDeviceFlow({ userCode, approve, mint, now = Date.now() }) {
+  const p = pendingFlow(userCode, now);
+  if (!p) return false;
+  const f = flows.get(p.deviceCode);
+  // Decide before the await, so a double-submit cannot mint twice.
+  f.result = { state: 'deciding' };
+  try {
+    f.result = approve ? { state: 'ok', ...(await mint()) } : { state: 'denied' };
+  } catch (err) {
+    f.result = null; // undecided again: the person can retry
+    throw err;
+  }
+  return true;
+}
+
+// Is this a device code this file issued (rather than GitHub's)?
+function isBrowserDeviceCode(deviceCode) {
+  return typeof deviceCode === 'string' && flows.has(deviceCode);
+}
+
+// The terminal's poll → { state: 'pending' | 'slow_down' | 'ok' | 'denied' | 'expired', … }.
+// The same states pollDeviceFlow answers for GitHub's flow.
+function pollBrowserDeviceFlow(deviceCode, now = Date.now()) {
+  const f = flows.get(deviceCode);
+  if (!f) return { state: 'expired' };
+  if (f.expiresAt <= now) { forget(deviceCode); return { state: 'expired' }; }
+  if (now - f.lastPolledAt < POLL_INTERVAL_S * 1000) return { state: 'slow_down', interval: POLL_INTERVAL_S };
+  f.lastPolledAt = now;
+  if (!f.result || f.result.state === 'deciding') return { state: 'pending' };
+  forget(deviceCode); // the token leaves exactly once
+  return f.result;
+}
+
+module.exports = {
+  FLOW_TTL_MS,
+  normalizeUserCode,
+  startBrowserDeviceFlow,
+  pendingFlow,
+  decideDeviceFlow,
+  isBrowserDeviceCode,
+  pollBrowserDeviceFlow,
+};

package/src/bongos/llm-pricing.js

@@ -283,4 +283,20 @@ function componentsFromModelUsage(modelUsage) {
   };
 }
 
-module.exports = { PRICES, FAMILY_CURRENT_MODEL, familyFor, priceUsage, canonicalizeModelId, priceModelUsage, componentsFromModelUsage };
+// SERVER-TOOL FEES (task 1004937, ADR 0394 §3). The Messages API's web search is
+// billed per search on top of tokens: $10 per 1,000 searches, i.e. $0.01 each.
+// Web fetch has no fee of its own; the fetched page is billed as input tokens,
+// which priceUsage already prices. This is the one place the search price is
+// spelled. Source: Anthropic's published web-search price as cached in the
+// claude-api reference (2026-10-06), NOT re-verified against the live pricing
+// page; the first real Market Watch run (task 1004942) is the measurement.
+const WEB_SEARCH_USD_PER_REQUEST = 0.01;
+
+// priceWebSearches(n) — USD for n web searches (usage.server_tool_use.web_search_requests).
+// A missing or garbage count prices as zero searches, never NaN.
+function priceWebSearches(n) {
+  const k = Number(n);
+  return Number.isFinite(k) && k > 0 ? k * WEB_SEARCH_USD_PER_REQUEST : 0;
+}
+
+module.exports = { PRICES, FAMILY_CURRENT_MODEL, familyFor, priceUsage, canonicalizeModelId, priceModelUsage, componentsFromModelUsage, WEB_SEARCH_USD_PER_REQUEST, priceWebSearches };

package/src/bongos/metrics.js

@@ -51,9 +51,28 @@ function renderLabels(labels) {
   return '{' + keys.map((k) => `${k}="${escapeLabelValue(labels[k])}"`).join(',') + '}';
 }
 
+// --- series cap (task 1004924) ---------------------------------------------
+// Every distinct label set is a series held in memory forever, so a label fed by
+// request input can grow the heap without bound. Past this many series a metric
+// takes no NEW label set: it folds into an overflow series instead. A metric with
+// a route label folds only the route to 'other' (method and status are bounded
+// sets already, so the overflow is a handful of series); any other metric folds
+// every label to 'other', one series.
+const MAX_SERIES_PER_METRIC = 2000;
+const OVERFLOW = 'other';
+
+function capLabels(series, labels) {
+  if (series.size < MAX_SERIES_PER_METRIC || series.has(labelKey(labels))) return labels;
+  if ('route' in labels) return { ...labels, route: OVERFLOW };
+  const all = {};
+  for (const k of Object.keys(labels)) all[k] = OVERFLOW;
+  return all;
+}
+
 function incCounter(name, help, labels = {}, by = 1) {
   let c = counters.get(name);
   if (!c) { c = { help, series: new Map() }; counters.set(name, c); }
+  labels = capLabels(c.series, labels);
   const key = labelKey(labels);
   const s = c.series.get(key);
   if (s) s.value += by;
@@ -63,6 +82,7 @@ function incCounter(name, help, labels = {}, by = 1) {
 function observeHistogram(name, help, labels, value) {
   let h = histograms.get(name);
   if (!h) { h = { help, series: new Map() }; histograms.set(name, h); }
+  labels = capLabels(h.series, labels);
   const key = labelKey(labels);
   let s = h.series.get(key);
   if (!s) { s = { labels, buckets: new Array(HIST_BUCKETS.length).fill(0), sum: 0, count: 0 }; h.series.set(key, s); }
@@ -74,8 +94,14 @@ function observeHistogram(name, help, labels, value) {
 }
 
 // --- event-loop lag sampler (unref'd so it never holds the process open) ---
+// Sampled every 10 s, not every second (task 1004961): a 1 s timer woke an idle
+// hosted instance once a second forever, which burns CPU credits on a small
+// droplet. perf_hooks.monitorEventLoopDelay() was considered and rejected — its
+// native sampler is itself a repeating libuv timer firing every `resolution` ms
+// (default 10 ms), so it would wake the loop far MORE often, not less. The gauge
+// keeps its name and meaning: the most recent sampled lag, in seconds.
 let _lagSeconds = 0;
-const _LAG_INTERVAL_MS = 1000;
+const _LAG_INTERVAL_MS = 10_000;
 const _lagTimer = setInterval(() => {
   const start = process.hrtime.bigint();
   setImmediate(() => {
@@ -100,6 +126,26 @@ function normalizeRoute(p) {
   return '/' + parts.join('/');
 }
 
+// routeLabel — the route label for one finished request (task 1004924). The
+// literal path is caller-chosen (every scanner hit on /wp-admin/x.php or /.env
+// is a new path), so it is never the label on its own:
+//   - a matched Express route labels by its PATTERN (mount path + route path),
+//     a fixed set only the code can grow;
+//   - a 404 with no matched route is the single label 'unmatched';
+//   - anything else unrouted (static files) keeps the normalized path, and the
+//     per-metric series cap above bounds even that.
+const UNMATCHED = 'unmatched';
+function routeLabel(req, status) {
+  const r = req.route;
+  if (r && r.path != null) {
+    const base = req.baseUrl && req.baseUrl !== '/' ? normalizeRoute(req.baseUrl) : '';
+    const p = typeof r.path === 'string' ? r.path : String(r.path);
+    return (base + p) || '/';
+  }
+  if (status === 404) return UNMATCHED;
+  return normalizeRoute(req.path);
+}
+
 // --- HTTP middleware ------------------------------------------------------
 function httpMiddleware() {
   return (req, res, next) => {
@@ -107,9 +153,9 @@ function httpMiddleware() {
     if (req.path === '/metrics' || req.path === '/healthz') return next();
     const start = process.hrtime.bigint();
     res.on('finish', () => {
-      const route = normalizeRoute(req.path);
       const method = req.method;
       const status = res.statusCode;
+      const route = routeLabel(req, status);
       incCounter('gds_http_requests_total', 'Total HTTP requests by method, normalized route, and status code.',
         { method, route, status: String(status) });
       const dur = Number(process.hrtime.bigint() - start) / 1e9;