@bongos/core 1.23.22 → 1.24.2

package/modules/government/access-routes.js

@@ -0,0 +1,70 @@
+'use strict';
+
+// modules/government/access-routes.js — the handlers behind the three ACCESS HOLDERS
+// routes (task 1005000). The routes themselves — path, permission gate and pin — are
+// declared in routes/government.js, where route-rank-check reads them; only the bodies
+// live here, so the router file stays under the size ratchet.
+//
+//   GET    /government/access                               (board.vote.cast) — read
+//   POST   /government/access/:accessKey/holders            (government.manage) — record
+//   DELETE /government/access/:accessKey/holders/:builderId (government.manage) — remove
+//
+// ⚠ A record of who to ask, never authority (access.js). Not act-alone routes: they
+// record a fact about the world outside the project; they decide nothing a sitting
+// votes on.
+
+const access = require('./access');
+
+// deps: { db, log, parseId, validateOrRespond } — the router's own, passed in so a
+// test that stubs the db by property reaches these handlers too.
+function accessHandlers({ db, log, parseId, validateOrRespond }) {
+  const keyOf = (req, res) => {
+    const key = String(req.params.accessKey || '');
+    if (access.isAccessKey(key)) return key;
+    res.fail('unknown_access', { status: 400, message: `Name one of: ${access.KEYS.join(', ')}.` });
+    return null;
+  };
+
+  async function read(req, res) {
+    try {
+      res.json({ access: access.accessView(await db.listAccessHolders()) });
+    } catch (err) {
+      log.error('[gds] GET /government/access', err);
+      res.fail('access_read_failed', { status: 500, message: 'internal error' });
+    }
+  }
+
+  async function grant(req, res) {
+    if (validateOrRespond(req, res, { builder_id: { required: true, type: 'integer', min: 1 } })) return;
+    const key = keyOf(req, res);
+    if (key === null) return;
+    const builderId = req.body.builder_id;
+    try {
+      const who = await db.getActiveBuilder(builderId);
+      if (!who) return res.fail('builder_not_found', { status: 404, message: 'No active builder with that id.' });
+      const added = await db.grantAccess(key, builderId, req.builder.id);
+      res.status(added ? 201 : 200).json({ ok: true, access_key: key, builder_id: String(builderId), added });
+    } catch (err) {
+      log.error('[gds] POST /government/access/:accessKey/holders', err);
+      res.fail('access_grant_failed', { status: 500, message: 'internal error' });
+    }
+  }
+
+  async function revoke(req, res) {
+    const key = keyOf(req, res);
+    if (key === null) return;
+    const builderId = parseId(req, res, { param: 'builderId', code: 'bad_builder_id', positiveInt: true });
+    if (builderId === null) return;
+    try {
+      const removed = await db.revokeAccess(key, builderId);
+      res.json({ ok: true, access_key: key, builder_id: String(builderId), removed });
+    } catch (err) {
+      log.error('[gds] DELETE /government/access/:accessKey/holders/:builderId', err);
+      res.fail('access_revoke_failed', { status: 500, message: 'internal error' });
+    }
+  }
+
+  return { read, grant, revoke };
+}
+
+module.exports = { accessHandlers };

package/modules/government/access.js

@@ -0,0 +1,88 @@
+'use strict';
+
+// modules/government/access.js — ACCESS HOLDERS: who holds the keys that live OUTSIDE
+// Bongos, so a blocker that needs one reaches the person who has it (task 1005000,
+// goal 1000111).
+//
+// WHY. Some blockers can only be cleared by whoever holds access no rank or Lead
+// models: the GitHub repository's admin (token scopes, branch protection, the App's
+// permissions), the server, the domain's DNS, the hosting account, package publishing,
+// payments. An Archon in Bongos may not hold the GitHub admin, and a Lead never does.
+// It lived only in prose (docs/credentials.md "account logins the owner holds") and in
+// blocker text — blocker 1000199, the publish token missing GitHub's `workflow` scope,
+// could only be filed to "the owner". The builder's words: repo owner is a category of
+// blockers that go beyond normality.
+//
+// WHAT IT IS. A fixed vocabulary of outside-access keys (ACCESS, extendable here and in
+// the migration's CHECK together), a record of which builders hold each
+// (government_access_holders, written by the owner only), and a seat, `access:<key>`,
+// that an ask can wait on. routing.js resolves that seat to the recorded holders, and
+// to the owner when nobody is recorded — the same fall every other seat takes.
+//
+// ⚠ A RECORD OF WHO TO ASK, NEVER AN AUTHORITY GRANT. Holding github-admin here unlocks
+// no Bongos route and no rank: this module is not read by requireRank, the permission
+// resolver, or any gate, and an access key is not a permission atom. No secret is
+// stored either — the row says WHO holds an access, never a credential or a token.
+//
+// PURE: no db.
+
+const ACCESS = Object.freeze([
+  // name: how the seat reads after "waits on the"; needs: what a blocker on it needs.
+  Object.freeze({ key: 'github-admin', name: 'repo owner', needs: 'repo-owner access', what: 'Admin on the GitHub repository: token scopes, branch protection, the GitHub App.' }),
+  Object.freeze({ key: 'server-ssh', name: 'server access', needs: 'server access', what: 'A login on the server the project runs on.' }),
+  Object.freeze({ key: 'dns', name: 'domain settings', needs: 'access to the domain settings', what: 'The DNS account for the project\'s domain.' }),
+  Object.freeze({ key: 'hosting', name: 'hosting account', needs: 'access to the hosting account', what: 'The account that pays for and runs the project\'s servers.' }),
+  Object.freeze({ key: 'npm-publish', name: 'package publishing', needs: 'package publishing rights', what: 'Publishing rights for the project\'s packages.' }),
+  Object.freeze({ key: 'payments', name: 'payments', needs: 'access to payments', what: 'The account money moves through.' }),
+]);
+const KEYS = Object.freeze(ACCESS.map((a) => a.key));
+const isAccessKey = (k) => KEYS.includes(String(k || ''));
+const byKey = (k) => ACCESS.find((a) => a.key === k) || null;
+
+// The seat grammar's access half, for asks.js SEAT and the migration's CHECK.
+const SEAT_PART = `access:(${KEYS.join('|')})`;
+
+// "the repo owner" — how the seat reads after "waits on".
+function accessLabel(key) {
+  const a = byKey(key);
+  return a ? `the ${a.name}` : 'the owner';
+}
+
+// "needs repo-owner access" — how a blocker on this seat reads under its holder.
+function needsWords(key) {
+  const a = byKey(key);
+  return a ? `needs ${a.needs}` : 'needs outside access';
+}
+
+// The holders read as the seat resolver wants them: { key: [{ builder_id, github_login, display_name }] }.
+function holdersByKey(rows) {
+  const out = {};
+  for (const k of KEYS) out[k] = [];
+  for (const r of rows || []) {
+    if (r && isAccessKey(r.access_key) && r.builder_id != null) out[r.access_key].push(r);
+  }
+  return out;
+}
+
+// The read GET /government/access answers: every access, its words, who holds it.
+function accessView(rows) {
+  const held = holdersByKey(rows);
+  return ACCESS.map((a) => ({
+    key: a.key,
+    name: a.name,
+    // the one display form, for the list and the picker alike
+    title: a.name.charAt(0).toUpperCase() + a.name.slice(1),
+    what: a.what,
+    seat: `access:${a.key}`,
+    holders: held[a.key].map((r) => ({
+      id: String(r.builder_id),
+      login: r.github_login || null,
+      name: r.display_name || r.github_login || null,
+      since: r.granted_at || null,
+    })),
+    // nobody recorded: the seat falls to the owner, as every unheld seat does
+    falls_to_owner: held[a.key].length === 0,
+  }));
+}
+
+module.exports = { ACCESS, KEYS, SEAT_PART, isAccessKey, accessLabel, needsWords, holdersByKey, accessView };

package/modules/government/asks.js

@@ -44,10 +44,12 @@ const MARKUP = /\*\*|`|^#|\[[^\]]*\]\(|https?:\/\/|<\/?[a-z]/im;
 // Control characters other than tab and line breaks (line breaks have their own rule).
 // eslint-disable-next-line no-control-regex
 const CONTROL = /[\u0000-\u0008\u000b\u000c\u000e-\u001f\u007f]/;
+const access = require('./access');
 const BUILDINGS = Object.freeze(['charter', 'rules', 'disputes', 'people', 'planning', 'automation', 'review', 'release', 'treasury']);
 // The seats an ask can wait on (gov-living.js seatResolver's grammar). An
 // unseated building falls to the owner when it is routed (owner ruling).
-const SEAT = new RegExp(`^(owner|(lead|board):(${BUILDINGS.join('|')})|committee:(${BUILDINGS.join('|')})\\.[a-z][a-z0-9_]{0,31})$`);
+// `access:<key>` (task 1005000): whoever holds that outside access (access.js).
+const SEAT = new RegExp(`^(owner|(lead|board):(${BUILDINGS.join('|')})|committee:(${BUILDINGS.join('|')})\\.[a-z][a-z0-9_]{0,31}|${access.SEAT_PART})$`);
 // An answer's key: what a tap sends. Its act, optional: the matter's own act it
 // takes ('go ahead', 'record', 'force:tested_by_hand'); the deck maps it onto
 // the desk row's real route and refuses one the row does not offer.
@@ -150,7 +152,7 @@ function checkAsk(raw) {
   // ---- who it waits on: a seat the direction desk can route ----
   const seat = str(c.waits_on).trim();
   if (!seat) err('waits_on', 'missing', 'Say who this waits on.');
-  else if (!SEAT.test(seat)) err('waits_on', 'unknown_seat', `"${seat.slice(0, 40)}" is not a seat: say owner, lead:<building>, committee:<building>.<name> or board:<building>.`);
+  else if (!SEAT.test(seat)) err('waits_on', 'unknown_seat', `"${seat.slice(0, 40)}" is not a seat: say owner, lead:<building>, committee:<building>.<name>, board:<building> or access:<key>.`);
 
   // ---- what happens if nobody answers ----
   lineRule('if_nobody_answers', c.if_nobody_answers, 'Say what happens if nobody answers.');
@@ -206,6 +208,7 @@ const ASK_REQUIRED_MESSAGE = 'An AI session files a blocker with an ask: a quest
 function seatWords(seat) {
   const s = str(seat);
   if (s === 'owner') return 'the owner';
+  if (/^access:/.test(s)) return access.accessLabel(s.slice(7));
   const m = /^(lead|board|committee):([a-z]+)(?:\.([a-z0-9_]+))?$/.exec(s);
   if (!m) return s;
   const building = m[2].charAt(0).toUpperCase() + m[2].slice(1);

package/modules/government/catalog.js

@@ -238,6 +238,12 @@ const PERMISSIONS = [
   // Review the store's proposed sub-categories (task 1004355, ADR 0342 D3): approve,
   // rename then approve, or merge into an existing one (a merge moves its modules).
   { key: 'module.subcategory.review', system: false, floor: 'metic', guards: 'GET /store/subcategories/queue, POST /store/subcategories/:id/approve, POST /store/subcategories/:id/merge' },
+  // The project's authorised person for money (task 1004913, ADR 0385 D4): sign,
+  // narrow or revoke a standing payout rule, hold a noticed run, approve one payout,
+  // sign one equity grant or contract, and read the approval log. Archon by default;
+  // not a system key, so a project may hand it to a treasurer rank of its own. The
+  // routes additionally refuse anything but a person's own web session.
+  { key: 'payout.approve', system: false, floor: 'archon', guards: 'GET /payouts/approvals, GET /payouts/rules, POST /payouts/rules[/:id/{narrow,revoke,runs,runs/:runKey/hold}], POST /payouts/{approve,grants,contracts}' },
   // Take a module out of the store (task 1003797, ADR 0338 D2). Stops new installs,
   // versions and downloads; never reaches an instance that already holds it.
   { key: 'module.delist', system: false, floor: 'metic', guards: 'POST /store/modules/:key/delist, POST /store/modules/:key/versions/:version/release (a version the promotion gate held on tester — task 1003804), POST /store/modules/:key/versions/:version/withdraw (take a version back — task 1004895)' },

package/modules/government/db.js

@@ -429,9 +429,26 @@ async function openBoardItem({ subjectType, subjectId, openedBy = null, constitu
      RETURNING *`,
     [subjectType, subjectId, openedBy, windowMinutes, JSON.stringify(constitution || {})],
   );
+  // Tell the expiry poller (task 1004960): it sleeps until the soonest deadline
+  // it knows of, so a window shorter than its idle wait must wake it sooner.
+  // closes_at is now() + the window, so the window IS the time until close.
+  // A listener the poller registers (not a require: the poller requires this
+  // file). Never let a hint fail an open.
+  if (rows[0] && windowMinutes != null) {
+    for (const fn of deadlineListeners) {
+      try { fn(Number(windowMinutes) * 60_000); } catch (_) { /* best-effort */ }
+    }
+  }
   return rows[0] || null;
 }
 
+// Who wants to hear that a timed window opened (the expiry poller's start()).
+const deadlineListeners = new Set();
+function onBoardDeadline(fn) {
+  deadlineListeners.add(fn);
+  return () => deadlineListeners.delete(fn);
+}
+
 async function getOpenBoardItem(subjectType, subjectId) {
   const { rows } = await pool.query(
     `SELECT * FROM government_board_items
@@ -871,6 +888,41 @@ async function listActiveArchons() {
   return rows;
 }
 
+// ACCESS HOLDERS (task 1005000, government_036): who holds each outside access.
+// Active builders only — someone who left the project is nobody to ask. A record
+// of who to ask, never authority: no gate reads these rows (access.js).
+async function listAccessHolders() {
+  const { rows } = await pool.query(
+    `SELECT h.access_key, h.builder_id, h.granted_at, b.github_login, b.display_name
+       FROM government_access_holders h
+       JOIN builders b ON b.id = h.builder_id
+      WHERE b.status = 'active' AND b.system_role IS NULL
+      ORDER BY h.access_key, h.granted_at, h.builder_id`,
+  );
+  return rows;
+}
+
+// Record that a builder holds an access. Idempotent: an existing row is kept as it
+// was (its original granted_at/by). → true when a row was added.
+async function grantAccess(accessKey, builderId, grantedBy) {
+  const { rowCount } = await pool.query(
+    `INSERT INTO government_access_holders (access_key, builder_id, granted_by)
+     VALUES ($1, $2, $3)
+     ON CONFLICT (access_key, builder_id) DO NOTHING`,
+    [accessKey, builderId, grantedBy],
+  );
+  return rowCount > 0;
+}
+
+// → true when a row was removed.
+async function revokeAccess(accessKey, builderId) {
+  const { rowCount } = await pool.query(
+    'DELETE FROM government_access_holders WHERE access_key = $1 AND builder_id = $2',
+    [accessKey, builderId],
+  );
+  return rowCount > 0;
+}
+
 // One builder of this project, or null: who a Lead appointment names. Only an
 // active person (no machine identity) can be appointed.
 async function getActiveBuilder(builderId) {
@@ -1114,6 +1166,21 @@ async function getExpiredOpenBoardItems(limit = 100) {
   return rows;
 }
 
+// The expiry poller's alarm clock (task 1004960): how many milliseconds until
+// the soonest OPEN deadline, measured on the DATABASE clock (so a skewed
+// process clock can never make the poller wake early or late), or null when no
+// open item has a clock. ONE read, served by the same partial index as the
+// sweep — the poller sleeps until this deadline instead of asking every minute.
+async function msUntilSoonestOpenDeadline() {
+  const { rows } = await pool.query(
+    `SELECT EXTRACT(EPOCH FROM (MIN(closes_at) - now())) * 1000 AS ms
+       FROM government_board_items
+      WHERE closed_at IS NULL AND closes_at IS NOT NULL`,
+  );
+  const ms = rows[0] ? rows[0].ms : null;
+  return ms == null ? null : Number(ms);
+}
+
 // The summons read (task 1003271): every OPEN item this builder could still
 // vote on, with the two facts that decide it — who authored the subject, and
 // whether this builder has already cast. Membership is NOT decided here: it
@@ -1260,6 +1327,8 @@ module.exports = {
   withdrawBoardItem,
   getIdeaCompleteness,
   getExpiredOpenBoardItems,
+  msUntilSoonestOpenDeadline,
+  onBoardDeadline,
   getLatestReturnedItemWithObjection,
   getLatestPassedItem,
   listPassedSubjectIds,
@@ -1272,6 +1341,9 @@ module.exports = {
   applyLaws,
   listLeads,
   listActiveArchons,
+  listAccessHolders,
+  grantAccess,
+  revokeAccess,
   getActiveBuilder,
   applyLeadAct,
   listBuildouts,

package/modules/government/docket.js

@@ -85,6 +85,8 @@ const docketFloors = require('./docket-floors');
 const governmentConfig = require('./config');
 const asksDb = require('./asks-db');
 const routing = require('./routing');
+const waiting = require('./waiting');
+const access = require('./access');
 const { ownerOf } = require('./leads');
 
 const log = api.logger('government');
@@ -839,14 +841,57 @@ async function docketFor(builder) {
 // nothing — the docket then says `routed: false` rather than guess whose it is.
 async function loadSeats(government) {
   try {
-    const [leads, archons] = await Promise.all([db.listLeads(), db.listActiveArchons()]);
-    return { leads, owner: ownerOf(archons), holders: (government && government.holders) || {} };
+    // task 1005000: who holds each outside access. Its own read fails OPEN to nobody
+    // recorded (every access seat then falls to the owner), so a missing table on an
+    // instance that has not migrated yet never stops the City routing. Started inside
+    // a .then so a db layer without the function (an older stub, the walk's store)
+    // fails open too rather than throwing before the catch is attached.
+    const accessRows = Promise.resolve().then(() => db.listAccessHolders()).catch((err) => {
+      log.warn({ err: err && err.message }, 'governor docket: access holders unreadable, access seats fall to the owner');
+      return [];
+    });
+    const [leads, archons, held] = await Promise.all([db.listLeads(), db.listActiveArchons(), accessRows]);
+    return { leads, owner: ownerOf(archons), holders: (government && government.holders) || {}, access: access.holdersByKey(held) };
   } catch (err) {
     log.warn({ err: err && err.message }, 'governor docket: seats unreadable, nothing routed');
     return null;
   }
 }
 
+// OPEN BLOCKERS UNDER THE PEOPLE THEY WAIT ON (task 1004999). The blockers source is
+// read exactly as the docket reads it (the ideas module's contribution, under its own
+// `anyBuilder` gate — the list is public), each one carries its stored ask, and the
+// seats are read once, uncached (ADR 0016). waiting.js groups them with routing.js's
+// rule, so this answers "whose is it" exactly as the City does. A board seat's holders
+// are read only when some blocker names one. → { available, people, nobody, yours }
+// `available: false` names why nothing could be grouped — never an empty list
+// standing in for "nobody is waiting".
+async function blockersByPerson(builder, { contributions = registeredContributions(), now = Date.now(), timeoutMs = SOURCE_TIMEOUT_MS } = {}) {
+  const c = contributions.sources.get('blockers');
+  if (!c) return { available: false, reason: 'off', people: [], nobody: [], yours: waiting.forViewer(null, builder.id) };
+  const permissions = await resolver.resolveBuilderPermissions(builder.id);
+  const held = new Set(permissions || []);
+  const ctx = Object.freeze({ builderId: String(builder.id), rank: builder.rank || null, has: (p) => held.has(p) });
+  if (!gateAllows(c.gate, ctx)) return { available: false, reason: 'not_yours', people: [], nobody: [], yours: waiting.forViewer(null, builder.id) };
+  let matters;
+  try {
+    const raw = await withTimeout(Promise.resolve(c.read(ctx, { now })), timeoutMs);
+    matters = (Array.isArray(raw) ? raw : []).map((m) => normalizeMatter(m, { source: 'blockers', building: c.building || 'planning' })).filter(Boolean);
+  } catch (err) {
+    log.warn({ err: err && err.message }, 'blockers by person: blockers unreadable');
+    return { available: false, reason: 'unavailable', people: [], nobody: [], yours: waiting.forViewer(null, builder.id) };
+  }
+  await attachAsks(matters, asksDb.asksFor, timeoutMs);
+  const boardSeat = matters.some((m) => /^board:/.test(routing.seatOf(m)));
+  const government = boardSeat
+    ? await loadGovernment({ decisions: await board.decisionRulesView().catch(() => null) })
+    : { holders: {} };
+  const seats = await loadSeats(government);
+  if (!seats) return { available: false, reason: 'unavailable', people: [], nobody: [], yours: waiting.forViewer(null, builder.id) };
+  const grouped = waiting.groupByPerson(matters, seats);
+  return { available: true, ...grouped, yours: waiting.forViewer(grouped, builder.id) };
+}
+
 // One matter with its stored ask and the seats, for passing it on to `toSeat`
 // (task 1004705): → { matter, seats } | { reason } as findMatter answers. A
 // board's holders are read only when a board seat is involved.
@@ -927,5 +972,6 @@ module.exports = {
   findMatter,
   findMatterFor,
   loadSeats,
+  blockersByPerson,
   matterWithSeats,
 };

package/modules/government/migrations/government_035_payout_approve.sql

@@ -0,0 +1,29 @@
+-- government_035_payout_approve.sql — grant the new `payout.approve` atom to
+-- Archon (task 1004913, goal 1000092 N9; ADR 0385 D4).
+--
+-- WHAT IT IS. The project's authorised person for money: signs a standing payout
+-- rule, narrows or revokes it, holds a run in its pause window, approves a single
+-- payout, signs an equity grant or a contract, and reads the approval log
+-- (core_283_payout_approvals). The routes also demand the person's own web
+-- session, so holding the atom on a CLI token is not enough to sign.
+--
+-- WHY THIS FILE EXISTS. RANK_SEED is derived from the catalog's floors, and the
+-- drift guard (tests/government_seed.mjs) compares it against the union of the
+-- run-once seed plus every later grant migration, per rank. An archon-floor key
+-- is held by archon only.
+--
+-- Additive only: one new permission key granted to one rank; nothing is revoked.
+-- Idempotent (ON CONFLICT DO NOTHING); forward-safe (INSERT only).
+--
+-- The `SELECT '<rank>', unnest(ARRAY[…])` shape is load-bearing: the drift guard
+-- scans for it literally.
+
+BEGIN;
+
+INSERT INTO government_rank_permissions (rank_key, permission_key)
+SELECT 'archon', unnest(ARRAY[
+  'payout.approve'
+])
+ON CONFLICT (rank_key, permission_key) DO NOTHING;
+
+COMMIT;

package/modules/government/migrations/government_036_access_holders.sql

@@ -0,0 +1,33 @@
+-- government_036_access_holders.sql — who holds the keys OUTSIDE Bongos, and an ask
+-- that waits on them (task 1005000, goal 1000111).
+--
+-- WHAT THIS ADDS
+--
+--   government_access_holders — one row per (outside access, builder): the GitHub
+--   repository's admin, the server, the domain's DNS, the hosting account, package
+--   publishing, payments. The vocabulary is modules/government/access.js `ACCESS`,
+--   held equal to the CHECK below by tests/access_holders.mjs. Written by the owner
+--   only (the routes gate government.manage); who granted it and when ride the row.
+--
+--   It is a RECORD OF WHO TO ASK, never an authority grant: no permission atom, rank
+--   check or gate reads this table, and it stores no credential — only who holds one.
+--
+--   government_asks.waits_on gains the seat `access:<key>`, so an ask can wait on
+--   whoever holds an outside access (routing.js; nobody recorded → the owner).
+
+BEGIN;
+
+CREATE TABLE IF NOT EXISTS government_access_holders (
+  access_key  text        NOT NULL
+              CHECK (access_key IN ('github-admin', 'server-ssh', 'dns', 'hosting', 'npm-publish', 'payments')),
+  builder_id  bigint      NOT NULL REFERENCES builders(id) ON DELETE CASCADE,
+  granted_by  bigint      REFERENCES builders(id) ON DELETE SET NULL,
+  granted_at  timestamptz NOT NULL DEFAULT now(),
+  PRIMARY KEY (access_key, builder_id)
+);
+
+ALTER TABLE government_asks DROP CONSTRAINT IF EXISTS government_asks_waits_on_check;
+ALTER TABLE government_asks ADD CONSTRAINT government_asks_waits_on_check
+  CHECK (waits_on ~ '^(owner|(lead|board):(charter|rules|disputes|people|planning|automation|review|release|treasury)|committee:(charter|rules|disputes|people|planning|automation|review|release|treasury)\.[a-z][a-z0-9_]{0,31}|access:(github-admin|server-ssh|dns|hosting|npm-publish|payments))$');
+
+COMMIT;

package/modules/government/pollers/board-expiry.js

@@ -19,17 +19,32 @@
 // minute-cadence poller logging every tick would bury the journal (the
 // reconciler's own warn-once lesson).
 //
-// CADENCE: windows are minutes-granular (the recommended sitting is 90
-// minutes), so a one-minute sweep bounds lateness at ~1 minute — tight enough
-// that "closes on time" is honest, cheap enough that the query (one indexed
-// read; government_board_items_open_by_deadline exists for exactly this, per
-// government_003's own comment) is negligible. Concurrent windows are normal
+// CADENCE (task 1004960): the poller SLEEPS UNTIL THE SOONEST DEADLINE instead
+// of asking every minute. After each sweep it makes one MIN(closes_at) read
+// (msUntilSoonestOpenDeadline, the same partial index) and arms its next run
+// for just after that deadline — capped at MAX_WAIT_MS (5 minutes) so an item
+// opened by some other process is still caught. A window opened in THIS process
+// wakes it sooner through noteDeadline (db.openBoardItem calls it), so a
+// one-minute window still closes on time. An idle instance with no open clock
+// therefore reads twice per 5 minutes, not once a minute; a vote still closes
+// within ~1 second of its deadline. While something is OVERDUE after a sweep
+// (its close threw and rolled back) the retry waits RETRY_MS (the old one-minute
+// cadence), never a hot loop. Runs never overlap: a tick that fires while the
+// previous sweep is still in flight is skipped. Concurrent windows are normal
 // (owner decision 10): the sweep closes every due item, oldest deadline first.
 
 const board = require('../board');
 const db = require('../db');
 
-const INTERVAL_MS = Number(process.env.BOARD_EXPIRY_SWEEP_MS) || 60_000;
+// The longest the poller ever sleeps (BOARD_EXPIRY_SWEEP_MS overrides it). It
+// only bounds an item opened by ANOTHER process; this process's opens wake it.
+const MAX_WAIT_MS = Number(process.env.BOARD_EXPIRY_SWEEP_MS) || 5 * 60_000;
+// Kept as an alias: INTERVAL_MS was the fixed cadence before task 1004960.
+const INTERVAL_MS = MAX_WAIT_MS;
+// While an item is overdue after a sweep (its close failed and rolled back).
+const RETRY_MS = 60_000;
+// Wake just AFTER a deadline, since the sweep reads closes_at < now().
+const GRACE_MS = 1_000;
 // A first sweep shortly after boot, so windows that expired while the process
 // was down (a deploy restart mid-sitting) close promptly rather than one full
 // interval late.
@@ -38,8 +53,21 @@ const FIRST_SWEEP_DELAY_MS = Number(process.env.BOARD_EXPIRY_FIRST_MS) || 15_000
 // handful of open windows (the board's subjects are rare by construction).
 const SWEEP_LIMIT = 100;
 
-let intervalTimer = null;
-let firstTimer = null;
+let timer = null;
+let dueAt = null;      // when the armed timer fires (process clock, ms)
+let started = false;
+let running = false;
+let hintAt = null;     // soonest deadline (process clock) noted mid-sweep
+let startDeps = {};
+let unlisten = null;
+
+// When to run next, given the ms until the soonest open deadline (null: none).
+function nextDelayMs(msUntilSoonest) {
+  if (msUntilSoonest == null || !Number.isFinite(Number(msUntilSoonest))) return MAX_WAIT_MS;
+  const ms = Number(msUntilSoonest);
+  if (ms <= 0) return RETRY_MS; // still overdue after a sweep: retry, never spin
+  return Math.min(MAX_WAIT_MS, ms + GRACE_MS);
+}
 
 // One sweep. Injectable deps keep it DB-free testable: listFn yields the due
 // items, closeFn closes one, log receives the disposition lines.
@@ -82,20 +110,80 @@ function start(deps = {}) {
     console.log('[board-expiry] disabled (BOARD_EXPIRY_DISABLED=1)');
     return;
   }
-  if (intervalTimer) return; // already started
-  const tick = () => {
-    runSweep(deps).catch((e) => console.error(`[board-expiry] sweep crashed: ${e && e.message}`));
-  };
-  firstTimer = setTimeout(tick, FIRST_SWEEP_DELAY_MS);
-  if (firstTimer.unref) firstTimer.unref();
-  intervalTimer = setInterval(tick, INTERVAL_MS);
-  if (intervalTimer.unref) intervalTimer.unref(); // never hold the process open on a restart
-  console.log(`[board-expiry] started (every ${Math.round(INTERVAL_MS / 1000)}s; first sweep in ${Math.round(FIRST_SWEEP_DELAY_MS / 1000)}s)`);
+  if (started) return; // already started
+  started = true;
+  startDeps = deps;
+  unlisten = db.onBoardDeadline(noteDeadline); // a window opened here wakes us sooner
+  arm(FIRST_SWEEP_DELAY_MS);
+  console.log(`[board-expiry] started (sleeps until the soonest deadline, at most ${Math.round(MAX_WAIT_MS / 1000)}s; first sweep in ${Math.round(FIRST_SWEEP_DELAY_MS / 1000)}s)`);
+}
+
+function arm(delay) {
+  if (timer) clearTimeout(timer);
+  dueAt = Date.now() + delay;
+  timer = setTimeout(() => {
+    timer = null;
+    dueAt = null;
+    tick().catch((e) => console.error(`[board-expiry] sweep crashed: ${e && e.message}`));
+  }, delay);
+  if (timer.unref) timer.unref(); // never hold the process open on a restart
+}
+
+// One run: the sweep, then the one MIN(closes_at) read that sets the alarm.
+// A run that starts while the previous one is still in flight is skipped —
+// the running one re-arms when it finishes, so nothing is lost.
+async function tick(deps = startDeps) {
+  if (running) return { skipped: true };
+  running = true;
+  let soonest = null;
+  try {
+    const out = await runSweep(deps);
+    try {
+      soonest = await (deps.soonestFn || db.msUntilSoonestOpenDeadline)();
+    } catch (e) {
+      (deps.error || console.error)(`[board-expiry] soonest-deadline read failed: ${e && e.message}`);
+      soonest = 0; // unknown: fall back to the one-minute retry, not the 5-minute cap
+    }
+    return out;
+  } finally {
+    running = false;
+    if (hintAt != null) {
+      const hint = hintAt - Date.now();
+      soonest = soonest == null ? hint : Math.min(soonest, hint);
+      hintAt = null;
+    }
+    if (started) arm(nextDelayMs(soonest));
+  }
+}
+
+// A window was opened that closes msUntilClose from now: wake sooner if the
+// armed alarm is later than that deadline. Mid-sweep, remember it for the re-arm.
+function noteDeadline(msUntilClose) {
+  if (!started || msUntilClose == null || !Number.isFinite(Number(msUntilClose))) return;
+  const ms = Math.max(0, Number(msUntilClose));
+  if (running) {
+    const at = Date.now() + ms;
+    hintAt = hintAt == null ? at : Math.min(hintAt, at);
+    return;
+  }
+  const delay = Math.min(MAX_WAIT_MS, ms + GRACE_MS);
+  if (dueAt == null || Date.now() + delay < dueAt) arm(delay);
 }
 
 function stop() {
-  if (firstTimer) { clearTimeout(firstTimer); firstTimer = null; }
-  if (intervalTimer) { clearInterval(intervalTimer); intervalTimer = null; }
+  started = false;
+  hintAt = null;
+  if (unlisten) { unlisten(); unlisten = null; }
+  if (timer) { clearTimeout(timer); timer = null; }
+  dueAt = null;
+}
+
+// For tests: what is armed right now.
+function _state() {
+  return { started, running, msUntilNextRun: dueAt == null ? null : dueAt - Date.now() };
 }
 
-module.exports = { start, stop, runSweep, INTERVAL_MS, SWEEP_LIMIT };
+module.exports = {
+  start, stop, runSweep, tick, noteDeadline, nextDelayMs, _state,
+  INTERVAL_MS, MAX_WAIT_MS, RETRY_MS, GRACE_MS, SWEEP_LIMIT,
+};

package/modules/government/protected-surfaces.json

@@ -30,6 +30,7 @@
     { "glob": "src/bongos/auth-config.js", "group": "authz", "why": "task 1004024. Carved out of auth.js (task 1003206): the OAuth flows, session-token minting, admission and IdP checks auth.js now delegates to. Registering auth.js alone protected the facade and none of them." },
     { "glob": "src/bongos/auth-discord.js", "group": "authz", "why": "task 1004024. Carved out of auth.js (task 1003206): the OAuth flows, session-token minting, admission and IdP checks auth.js now delegates to. Registering auth.js alone protected the facade and none of them." },
     { "glob": "src/bongos/auth-github.js", "group": "authz", "why": "task 1004024. Carved out of auth.js (task 1003206): the OAuth flows, session-token minting, admission and IdP checks auth.js now delegates to. Registering auth.js alone protected the facade and none of them." },
+    { "glob": "src/bongos/auth-google.js", "group": "authz", "why": "task 1004993 (ADR 0396). The Google sign-in beside auth-github.js: it checks Google's ID token, runs the admission gate for a Google person and mints their web session, so it is the same trust surface as the GitHub flow." },
     { "glob": "src/bongos/auth-idp.js", "group": "authz", "why": "task 1004024. Carved out of auth.js (task 1003206): the OAuth flows, session-token minting, admission and IdP checks auth.js now delegates to. Registering auth.js alone protected the facade and none of them." },
     { "glob": "src/bongos/db.js", "group": "authz", "why": "rank tiers, REQUIRES_RANK_TIER — the CASE edited in the SEC #863 incident" },
     { "glob": "src/bongos/db-kernel.js", "group": "authz", "why": "task 1004024. The kernel db slice carved out of db.js (BV1.R69 / ADR 0091): builder identity and the rank reads the SEC #863 entry above exists for." },