@bongos/core 1.19.470 → 1.19.471

package/scripts/gds/pulse.js

@@ -22,8 +22,15 @@
 //
 // -------------------------------------------------------------------------
 // Release-stale-mode notes (V3.R49):
-//   - Threshold is HOURS by default (env var GDS_STALE_CLAIM_HOURS, default
-//     6). The underlying sweepStaleClaims() helper takes minutes; we convert.
+//   - Threshold is HOURS, and it is THE PROJECT'S — resolved by src/stale-timer.js
+//     (--threshold-hours -> <PREFIX>_STALE_CLAIM_HOURS, legacy GDS_ honoured -> 6),
+//     the same reader the Archon roster uses so the surface that REPORTS staleness
+//     and this sweep that ACTS on it can no longer disagree (task 1003476; they were
+//     24h and 6h apart). The underlying sweepStaleClaims() helper takes minutes;
+//     staleClaimMinutes() converts, in one place.
+//   - An unreadable timer STOPS the sweep rather than falling back. Releasing another
+//     builder's claim is not undone by reloading a page, so this mode refuses where a
+//     read-only surface degrades — see the posture note in src/stale-timer.js.
 //   - We talk to Postgres directly via the existing src/db.js pool (peer auth
 //     on the droplet). No HTTP session needed — this routine ships with the
 //     server and runs in the same trust boundary.
@@ -45,6 +52,13 @@ const fs = require('node:fs');
 const path = require('node:path');
 const { execFileSync } = require('node:child_process');
 const { cliClient, requireSession, arg } = require('./cli-lib');
+// The project's stale-claim timer — one number, one precedence, shared with the
+// roster and the lib defaults (task 1003476). Scripts sit outside the kernel
+// boundary, so a direct require is the idiom here.
+const {
+  resolveStaleClaimHours, staleClaimMinutes, describeStaleTimer,
+  MIN_STALE_CLAIM_HOURS, MAX_STALE_CLAIM_HOURS,
+} = require('../../src/stale-timer');
 
 const REPO_ROOT = path.resolve(__dirname, '..', '..');
 
@@ -63,23 +77,31 @@ function loadDeps() {
   return { pool, sweepStaleClaims };
 }
 
+// Resolve the timer THIS SWEEP will act on, and refuse rather than guess.
+//
+// Task 1003476 (goal 1000072) moved the precedence itself into src/stale-timer.js so
+// the roster that REPORTS staleness and this sweeper that ENFORCES it read one number
+// (they were 24h and 6h apart). What stays here is the posture: the resolver reports an
+// unusable value instead of throwing, because a read-only surface should degrade to the
+// default and SAY SO — but this sweeper releases other people's claims and stamps their
+// session logs, and no reload undoes that. So an unreadable timer stops the sweep.
+//
+// `--threshold-hours` keeps behaving exactly as it did: an explicit per-run lens that
+// overrides the project's timer for this invocation only, and a bad one is a usage error.
 function parseThresholdHours(args) {
   const cliVal = arg('--threshold-hours', args);
-  if (cliVal != null) {
-    const n = Number(cliVal);
-    if (!Number.isFinite(n) || n <= 0) {
-      throw new Error(`--threshold-hours must be a positive number (got ${cliVal})`);
-    }
-    return n;
-  }
-  if (process.env.GDS_STALE_CLAIM_HOURS) {
-    const n = Number(process.env.GDS_STALE_CLAIM_HOURS);
-    if (!Number.isFinite(n) || n <= 0) {
-      throw new Error(`GDS_STALE_CLAIM_HOURS must be a positive number (got "${process.env.GDS_STALE_CLAIM_HOURS}")`);
-    }
-    return n;
+  const resolved = resolveStaleClaimHours({ override: cliVal });
+  if (resolved.invalid) {
+    const where = resolved.invalid.where === 'override'
+      ? '--threshold-hours'
+      : resolved.invalid.varName;
+    throw new Error(
+      `${where}="${resolved.invalid.raw}" is unusable (${resolved.invalid.reason}) — `
+      + `refusing to sweep on a timer this project cannot read. `
+      + `Fix it, or pass --threshold-hours ${MIN_STALE_CLAIM_HOURS}..${MAX_STALE_CLAIM_HOURS} for this run.`
+    );
   }
-  return 6;
+  return resolved;
 }
 
 // Post a single broadcast about an auto-released claim. Best-effort —
@@ -98,9 +120,9 @@ function postDiscordPing(text) {
   }
 }
 
-async function releaseStale({ thresholdHours, dryRun }) {
+async function releaseStale({ timer, dryRun }) {
   const { pool, sweepStaleClaims } = loadDeps();
-  const thresholdMin = Math.round(thresholdHours * 60);
+  const thresholdMin = staleClaimMinutes(timer.hours);
 
   let stale;
   try {
@@ -111,8 +133,10 @@ async function releaseStale({ thresholdHours, dryRun }) {
     process.exit(1);
   }
 
+  // The header names the timer AND where it came from. A bare "6h" is what let the
+  // sweeper's 6 and the roster's 24 sit side by side unnoticed for a year of ops logs.
   const header =
-    `stale-claim sweep (threshold=${thresholdHours}h / ${thresholdMin}m` +
+    `stale-claim sweep (threshold=${describeStaleTimer(timer)} / ${thresholdMin}m` +
     `${dryRun ? ', dry-run' : ''}): ${stale.length} claim(s) eligible`;
   console.log(header);
 
@@ -168,7 +192,7 @@ async function releaseStale({ thresholdHours, dryRun }) {
       const claimedAtSql = cur[0].claimed_at;
       const notesMd =
         `${NOTE_TAG} session_pulses heartbeat went silent for ` +
-        `>= ${thresholdHours}h (threshold ${thresholdMin}m). ` +
+        `>= ${timer.hours}h (threshold ${thresholdMin}m, ${timer.source}). ` +
         (last_pulse_at
           ? `Last pulse: ${new Date(last_pulse_at).toISOString()}.`
           : `No pulse ever recorded; claimed_at ${new Date(claimedAtSql).toISOString()}.`) +
@@ -232,7 +256,7 @@ async function releaseStale({ thresholdHours, dryRun }) {
     const msg =
       `@${builderName} your claim on task #${outcome.task_id} ` +
       `("${outcome.taskTitle}") was auto-released because the session ` +
-      `heartbeat went silent for >= ${thresholdHours}h. ` +
+      `heartbeat went silent for >= ${timer.hours}h. ` +
       `No credits awarded. Task is back to ready — reclaim with ` +
       `\`/builder-claim ${outcome.task_id}\` if you're back.`;
 
@@ -261,15 +285,15 @@ async function releaseStale({ thresholdHours, dryRun }) {
   const args = process.argv.slice(2);
 
   if (args.includes('--release-stale')) {
-    let thresholdHours;
+    let timer;
     try {
-      thresholdHours = parseThresholdHours(args);
+      timer = parseThresholdHours(args);
     } catch (e) {
       console.error(e.message);
       process.exit(1);
     }
     const dryRun = args.includes('--dry-run');
-    await releaseStale({ thresholdHours, dryRun });
+    await releaseStale({ timer, dryRun });
     return;
   }
 

package/src/bongos/routes/builders.js

@@ -35,9 +35,47 @@ const { pool } = require('../pool');
 const { publicReadRateLimitMiddleware } = require('../middleware/rate-limit');
 const seams = require('../../module-seams');
 const { branding } = require('../../branding');
+// The project's stale-claim timer (task 1003476, goal 1000072) — kernel config, so a
+// direct require, the same as branding above. What the roster CALLS stale is now the
+// same number the sweeper ACTS on.
+const { resolveStaleClaimHours, MIN_STALE_CLAIM_HOURS, MAX_STALE_CLAIM_HOURS } = require('../../stale-timer');
+
 // task 1003208: structured logging — was console.*. A core file logs through
 // the kernel logger directly; only MODULES go via api.logger (the doorway).
 const log = require('../logger').logger.child({ src: 'builders' });
+// staleHoursFor(req) — the stale-claim threshold this roster read should use, and where
+// it came from (task 1003476, goal 1000072). The two Archon staleness reads below (the
+// roster and its per-builder expand view) had a byte-identical copy of this block each,
+// both hardcoding 24 while the sweeper acted at 6 — so the screen an Archon uses to
+// decide whether to intervene disagreed with the machine that had already intervened,
+// twice, in two places. One helper, one number.
+//
+// The project timer answers by default; `?stale_hours=N` is a LENS ("what would 48h
+// show me?") and is labelled as one. It NEVER throws on a misconfigured project timer:
+// these are read-only surfaces, so a bad <PREFIX>_STALE_CLAIM_HOURS degrades to the
+// default and is named in the response, putting the typo on the screen of the person
+// who can fix it instead of 500-ing the page they opened to find it. (The sweeper takes
+// the opposite posture and refuses to run — it releases claims; these only read.)
+//
+// Returns { hours, source } on success, or { fail: true } after answering 400 — a
+// caller returns immediately on `fail`, the parseId convention already used here.
+function staleHoursFor(req, res) {
+  if (req.query && req.query.stale_hours != null) {
+    const n = Number(req.query.stale_hours);
+    if (!Number.isFinite(n) || n < MIN_STALE_CLAIM_HOURS || n > MAX_STALE_CLAIM_HOURS) {
+      res.fail('bad_stale_hours', 400, { expected: `${MIN_STALE_CLAIM_HOURS}..${MAX_STALE_CLAIM_HOURS}` });
+      return { fail: true };
+    }
+    return { hours: n, source: 'query' };
+  }
+  const timer = resolveStaleClaimHours();
+  return {
+    hours: timer.hours,
+    source: timer.invalid
+      ? `default (invalid ${timer.invalid.varName}="${timer.invalid.raw}": ${timer.invalid.reason})`
+      : timer.source,
+  };
+}
 // The lifecycle (tasks · claims · ship) carved to modules/lifecycle/ (BV1.R86 /
 // ADR 0093 §3): the Archon roster, the per-builder stale-claim view, the
 // per-builder grade breakdown, and the shipped-count read resolve the `lifecycle`
@@ -308,26 +346,24 @@ module.exports = function buildBuildersRouter() {
   // /builders hall so the Archon can promote / demote / release-stale-claim
   // without dropping into psql.
   //
-  // Optional query param: ?stale_hours=N (default 24). Defines what counts
-  // as "stale" for the per-row stale_claim flag — mirrors the threshold the
-  // stale-claim-release sweeper uses but exposed as a roster knob so the
-  // Archon can dial it in if needed.
+  // Optional query param: ?stale_hours=N. Defines what counts as "stale" for the
+  // per-row stale_claim flag. The DEFAULT is the project's configured stale-claim
+  // timer (task 1003476, goal 1000072) — literally the number the sweeper releases
+  // on, not a lookalike: this route defaulted to a hardcoded 24 while the sweeper
+  // acted at 6, so the Archon's screen called a claim healthy for eighteen hours
+  // after the machine had already taken it away. The param stays as a LENS ("what
+  // would 48h show me?"), and the response reports both the number and where it
+  // came from so the two can never quietly diverge again.
   //
   // rank: archon — surfaces every builder's onboarding state. Gate:
   // requirePermission('builder.roster.read') — BV1.R104; the same atom
   // /grades/by-builder and /builders/:id/active-claims already gate on (ADR 0151).
   router.get('/builders/roster', auth.requireBuilder, auth.requirePermission('builder.roster.read'), async (req, res) => {
-    let staleHours = 24;
-    if (req.query && req.query.stale_hours != null) {
-      const n = Number(req.query.stale_hours);
-      if (!Number.isFinite(n) || n <= 0 || n > 720) {
-        return res.fail('bad_stale_hours', 400, { expected: '1..720' });
-      }
-      staleHours = n;
-    }
+    const stale = staleHoursFor(req, res);
+    if (stale.fail) return;
     try {
-      const builders = await lc().getBuildersRoster({ staleHours });
-      res.json({ builders, stale_hours: staleHours });
+      const builders = await lc().getBuildersRoster({ staleHours: stale.hours });
+      res.json({ builders, stale_hours: stale.hours, stale_hours_source: stale.source });
     } catch (err) {
       log.error('[gds] GET /builders/roster', err);
       res.fail('roster_failed', { status: 500, message: 'internal error' });
@@ -393,17 +429,13 @@ module.exports = function buildBuildersRouter() {
   router.get('/builders/:id/active-claims', auth.requireBuilder, auth.requirePermission('builder.roster.read'), async (req, res) => {
     const targetId = parseId(req, res, { code: 'bad_builder_id', positiveInt: true });
     if (targetId === null) return;
-    let staleHours = 24;
-    if (req.query && req.query.stale_hours != null) {
-      const n = Number(req.query.stale_hours);
-      if (!Number.isFinite(n) || n <= 0 || n > 720) {
-        return res.fail('bad_stale_hours', 400, { expected: '1..720' });
-      }
-      staleHours = n;
-    }
+    // Same timer as the roster it expands from — a claim the roster called stale must
+    // still be stale one click later (task 1003476).
+    const stale = staleHoursFor(req, res);
+    if (stale.fail) return;
     try {
-      const claims = await lc().getActiveClaimsForBuilderWithStale(targetId, { staleHours });
-      res.json({ builder_id: targetId, claims, stale_hours: staleHours });
+      const claims = await lc().getActiveClaimsForBuilderWithStale(targetId, { staleHours: stale.hours });
+      res.json({ builder_id: targetId, claims, stale_hours: stale.hours, stale_hours_source: stale.source });
     } catch (err) {
       log.error('[gds] GET /builders/:id/active-claims', err);
       res.fail('active_claims_failed', { status: 500, message: 'internal error' });

package/src/module-api.js

@@ -16,6 +16,7 @@ const { logger: coreLogger } = require('./bongos/logger');
 const { pool, instanceDbName } = require('./bongos/pool');
 const branding = require('./branding');
 const instanceConfig = require('./instance-config');
+const staleTimer = require('./stale-timer');
 const seams = require('./module-seams');
 const { buildInfo } = require('./build-info');
 const { validateOrRespond, LIMITS, parseId, asyncHandler, corsPublicGet, parsePagination, pageMeta, PAGINATION } = require('./bongos/routes/_helpers');
@@ -33,7 +34,7 @@ const { validateOrRespond, LIMITS, parseId, asyncHandler, corsPublicGet, parsePa
 // there. scripts/gds/bump-version.js still rewrites the literal below; it appends
 // the entry to that file. Look for a version's history there, not here.
 // ---------------------------------------------------------------------------
-const CORE_VERSION = '1.19.470'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
+const CORE_VERSION = '1.19.471'; // 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('dev-box'); log.info('mounted');
@@ -235,6 +236,20 @@ module.exports = {
   // it instead of reaching into src/branding.js directly (BV1.R86).
   userAgent: branding.userAgent,
   resolveEnv: instanceConfig.resolveEnv,
+  // --- the project's STALE-CLAIM TIMER (task 1003476, goal 1000072) — how long a
+  //     claim may go silent before this project calls it abandoned. ONE number for
+  //     every surface that reports or enforces it: before this, the sweeper that
+  //     actually releases claims used 6h while the Archon roster that reports them
+  //     used 24h, so the screen said "healthy" for eighteen hours after the machine
+  //     had already taken the claim away. Read here, never re-derived from the env
+  //     by a module: the precedence, the 1..720 bound and the invalid-value
+  //     reporting live in that one reader. See src/stale-timer.js for the
+  //     reporting-degrades / enforcement-refuses split a caller must choose between.
+  //     Only the two a module actually needs: the doorway is a stability contract,
+  //     so the CLI-facing describeStaleTimer / DEFAULT_STALE_CLAIM_HOURS stay behind
+  //     a direct require in scripts/ rather than joining the published surface.
+  resolveStaleClaimHours: staleTimer.resolveStaleClaimHours,
+  staleClaimMinutes: staleTimer.staleClaimMinutes,
   readConfigFileSync: instanceConfig.readConfigFileSync,
   configHome: instanceConfig.configHome,
   configPath: instanceConfig.configPath,

package/src/stale-timer.js

@@ -0,0 +1,177 @@
+'use strict';
+
+// src/stale-timer.js — the project's stale-claim timer: ONE number for "how long
+// may a claim go silent before this project calls it abandoned", resolved once and
+// read by everything that reports or enforces staleness.
+//
+// WHY THIS FILE EXISTS (task 1003476, goal 1000072 "Human legibility", criterion
+// legibility-sort-and-staleness). "Stale" had three answers and no owner:
+//
+//   scripts/gds/pulse.js --release-stale        6h     GDS_STALE_CLAIM_HOURS, else 6
+//   getBuildersRoster / GET /builders/roster    24h    hardcoded
+//   sweepStaleClaims / getStaleClaimsForBuilder 30min  hardcoded lib default
+//
+// The sweep is the one that ACTS — it auto-releases the claim, tags the session log
+// `[auto-released:stale]` and hands the task back to the queue. The roster is what a
+// person LOOKS AT to decide whether to intervene. They disagreed by eighteen hours,
+// so the Archon's roster reported a claim healthy for the better part of a day after
+// the sweeper had already taken it away. A steering surface that reports a different
+// rule from the one the machine enforces is precisely the failure this goal is named
+// for, and no amount of reading either file alone reveals it.
+//
+// So: one resolver, one number, one documented precedence, and every surface says
+// WHERE its number came from.
+//
+// THE FAIL POSTURE IS ASYMMETRIC, AND DELIBERATELY SO. A misconfigured timer must not
+// silently become a different policy, but the two kinds of caller cannot want the same
+// thing from it:
+//   • REPORTING degrades. A read-only surface takes the default and labels the source
+//     `default (invalid …)`, so a typo shows up on the screen of the person who can fix
+//     it instead of 500-ing the roster they were using to find the problem.
+//   • ENFORCEMENT refuses. The sweep releases other people's claims and a reload does
+//     not undo that, so it declines to run at all on a timer it cannot read.
+// `resolve()` never throws; it reports. Which of the two postures to take is the
+// caller's call, and each caller states it (see scripts/gds/pulse.js).
+//
+// This is a KERNEL file (fitness.js KERNEL_FILES): host configuration a module reads
+// rather than hardcodes, in the same category as instance-config.js and branding.js.
+// It imports only the kernel + node built-ins.
+
+const instanceConfig = require('./instance-config');
+
+// The env suffix, resolved through the branded prefix — so this reads
+// <PREFIX>_STALE_CLAIM_HOURS (CLOUDBONGOS_ on vanilla) while instance-config's legacy
+// prefix chain still honours the GDS_STALE_CLAIM_HOURS the live sweeper has always
+// used. Nothing in a running deployment has to change for this to resolve to what it
+// resolves to today.
+const ENV_SUFFIX = 'STALE_CLAIM_HOURS';
+
+// The last-resort timer, in hours. 6 because that is what the SWEEP has always used,
+// and the sweep is the surface that acts — adopting the roster's cosmetic 24 would
+// have quietly made every project three times more patient with a dead claim.
+const DEFAULT_STALE_CLAIM_HOURS = 6;
+
+// The accepted range, in hours. Not taste: `GET /builders/roster` has published
+// `1..720` as its `stale_hours` contract since V3.R14, and one timer means one bound.
+// 720h is 30 days — past that a "timer" is an off switch, and an off switch should be
+// asked for out loud rather than typed as a big number.
+const MIN_STALE_CLAIM_HOURS = 1;
+const MAX_STALE_CLAIM_HOURS = 720;
+
+// Parse one candidate into hours, or say why it is unusable. Pure.
+// Returns { hours } or { reason } — never throws, because both callers below want to
+// decide for themselves what an unusable value means.
+function parseHours(raw) {
+  if (raw == null || raw === '') return { reason: 'empty' };
+  const n = Number(raw);
+  if (!Number.isFinite(n)) return { reason: 'not a number' };
+  if (n <= 0) return { reason: 'must be positive' };
+  if (n < MIN_STALE_CLAIM_HOURS || n > MAX_STALE_CLAIM_HOURS) {
+    return { reason: `out of range (${MIN_STALE_CLAIM_HOURS}..${MAX_STALE_CLAIM_HOURS})` };
+  }
+  return { hours: n };
+}
+
+// Which env var actually supplied the value — for the receipt only.
+// instanceConfig.resolveEnv() returns the VALUE and not the name it came from, so the
+// name is re-derived by walking the SAME exported prefix order it walks and taking the
+// first non-empty hit, which is by construction the one it returned. The value is never
+// read from here: this decides what to PRINT, so a drift in the chain costs a label and
+// never the timer.
+function envVarNameFor(suffix, env) {
+  const order = [instanceConfig.envPrefix(), ...instanceConfig.LEGACY_ENV_PREFIXES];
+  const seen = new Set();
+  for (const pfx of order) {
+    if (!pfx || seen.has(pfx)) continue;
+    seen.add(pfx);
+    const name = `${pfx}_${suffix}`;
+    const v = env[name];
+    if (v !== undefined && v !== '') return name;
+  }
+  return `${instanceConfig.envPrefix()}_${suffix}`;
+}
+
+// resolveStaleClaimHours({ override, env }) — the project's stale-claim timer, and the
+// provenance of the number, for any surface that reports or enforces staleness.
+//
+// Precedence, widest-scope last:
+//   1. `override`  — a per-invocation lens (`--threshold-hours`, `?stale_hours=`). A
+//                    person asking "what would 48h show me?" is not reconfiguring the
+//                    project, so this never becomes the project's answer.
+//   2. env         — <PREFIX>_STALE_CLAIM_HOURS (legacy GDS_/OTB_/PMS_ honoured). This
+//                    IS the project's configured timer: the provisioning runner writes
+//                    it into the instance's web.env (ADR 0190), so an owner changing it
+//                    reaches a running project without a checkout.
+//   3. the default — DEFAULT_STALE_CLAIM_HOURS.
+//
+// Returns { hours, source, invalid }:
+//   hours   — always a usable positive number, whatever went wrong
+//   source  — 'override' | 'env:<VARNAME>' | 'default', for a surface to show a reader
+//   invalid — null, or { where, varName, raw, reason }: something was SET and could not
+//             be used. `hours` has already fallen through to the next tier; a reporting
+//             caller should say so, an enforcing caller should refuse (see the header).
+function resolveStaleClaimHours({ override, env = process.env } = {}) {
+  if (override != null && override !== '') {
+    const got = parseHours(override);
+    if (got.hours != null) return { hours: got.hours, source: 'override', invalid: null };
+    return {
+      hours: DEFAULT_STALE_CLAIM_HOURS,
+      source: 'default',
+      invalid: { where: 'override', varName: null, raw: String(override), reason: got.reason },
+    };
+  }
+
+  const raw = instanceConfig.resolveEnv(ENV_SUFFIX, { env });
+  if (raw != null && raw !== '') {
+    const varName = envVarNameFor(ENV_SUFFIX, env);
+    const got = parseHours(raw);
+    if (got.hours != null) return { hours: got.hours, source: `env:${varName}`, invalid: null };
+    return {
+      hours: DEFAULT_STALE_CLAIM_HOURS,
+      source: 'default',
+      invalid: { where: 'env', varName, raw: String(raw), reason: got.reason },
+    };
+  }
+
+  return { hours: DEFAULT_STALE_CLAIM_HOURS, source: 'default', invalid: null };
+}
+
+// staleClaimMinutes(hours) — the same timer in the unit the SQL predicates take.
+// Exists so the hours→minutes rounding happens in one place: the two pulse.js sweeper
+// queries count in minutes while every human-facing surface counts in hours, and a
+// second copy of `* 60` is how the two drift apart again.
+function staleClaimMinutes(hours) {
+  const n = Number(hours);
+  if (!Number.isFinite(n) || n <= 0) {
+    throw new Error('staleClaimMinutes: hours must be a positive number');
+  }
+  return Math.max(1, Math.round(n * 60));
+}
+
+// describeStaleTimer(resolved) — one sentence naming the timer and where it came from,
+// for a CLI header or an API receipt. A number with no provenance is what let the 6h
+// and the 24h coexist unnoticed, so every surface that prints the timer prints this.
+function describeStaleTimer(resolved) {
+  const r = resolved || {};
+  const base = `${r.hours}h (${r.source})`;
+  if (!r.invalid) return base;
+  const who = r.invalid.varName || r.invalid.where;
+  return `${base} — ignoring ${who}="${r.invalid.raw}" (${r.invalid.reason})`;
+}
+
+// ENV_SUFFIX and parseHours are deliberately NOT exported: every caller reads the
+// timer through resolveStaleClaimHours (that is the whole point of this file — one
+// resolver, no second reader), so exporting the pieces it resolves FROM would
+// re-open the door ADR 0226 closed. The default and the bound ARE exported, and
+// for the same reason: the tests assert "no env falls back to the project default"
+// and "the bound is the 1..720 the roster already publishes", and a test that
+// re-typed 6 or 720 would be the second copy of the number this ADR exists to
+// delete.
+module.exports = {
+  DEFAULT_STALE_CLAIM_HOURS,
+  MIN_STALE_CLAIM_HOURS,
+  MAX_STALE_CLAIM_HOURS,
+  resolveStaleClaimHours,
+  staleClaimMinutes,
+  describeStaleTimer,
+};

package/tests/module_api.mjs

@@ -33,6 +33,7 @@ const PUBLISHED_SURFACE = [
   'llmCache', // BV1.R73: shared LLM-cost cache (1.6.0; tracked domain leak)
   'llmPricing', // BV1.R77: shared token→USD pricing (1.7.0; tracked domain leak — economy carve)
   'branding', 'clientBranding', 'userAgent', 'resolveEnv', 'readConfigFileSync', 'configHome', 'configPath', // userAgent added 1.12.0 (BV1.R86; github-push UA)
+  'resolveStaleClaimHours', 'staleClaimMinutes', // added by task 1003476 (ADR 0226; goal 1000072): the PROJECT's stale-claim timer — the sweep that releases a silent claim and the Archon roster that reports one read the same number through here, after eighteen hours of disagreeing (6 vs 24)
   'joinabilityMode', // added by task 1003044 (ADR 0194; the carrier after 1.19.374): the project's membership door, one reader for the sign-in gate AND the onboarding module's public POST
   'enabledDisciplines', // BV1.R81: instance offered-disciplines (1.9.0; onboarding restock backstop)
   'registerProvider', 'hasProvider', 'resolve', 'resolveOptional', 'listPorts', 'verifyPortsSatisfied',

package/tests/onboarding_observability.mjs

@@ -248,7 +248,46 @@ await t('GET /builders/roster as archon → 200', async () => {
   });
   assert.equal(r.status, 200);
   assert.ok(Array.isArray(r.json?.builders));
-  assert.equal(r.json?.stale_hours, 24);
+  // The default is the PROJECT's stale-claim timer, not a number this route owns
+  // (task 1003476, goal 1000072). It used to assert a hardcoded 24 while the sweeper
+  // released at 6 — this assertion WAS the eighteen-hour lie, written down.
+  const timer = require('../src/stale-timer.js');
+  assert.equal(r.json?.stale_hours, timer.resolveStaleClaimHours().hours);
+  assert.equal(r.json?.stale_hours_source, 'default');
+});
+
+await t('GET /builders/roster → the timer follows the project env', async () => {
+  const prev = process.env.GDS_STALE_CLAIM_HOURS;
+  process.env.GDS_STALE_CLAIM_HOURS = '9';
+  try {
+    const r = await send({
+      port, method: 'GET', path: '/api/gds/builders/roster',
+      headers: { 'x-stub-builder-id': '1', 'x-stub-builder-rank': 'archon' },
+    });
+    assert.equal(r.json?.stale_hours, 9, 'resolved per request, not frozen at boot');
+    assert.equal(r.json?.stale_hours_source, 'env:GDS_STALE_CLAIM_HOURS');
+  } finally {
+    if (prev === undefined) delete process.env.GDS_STALE_CLAIM_HOURS;
+    else process.env.GDS_STALE_CLAIM_HOURS = prev;
+  }
+});
+
+await t('GET /builders/roster → a bad project timer degrades, it does not 500', async () => {
+  // The Archon opened this page to find the problem; 500-ing it hides the problem.
+  const prev = process.env.GDS_STALE_CLAIM_HOURS;
+  process.env.GDS_STALE_CLAIM_HOURS = 'six-ish';
+  try {
+    const r = await send({
+      port, method: 'GET', path: '/api/gds/builders/roster',
+      headers: { 'x-stub-builder-id': '1', 'x-stub-builder-rank': 'archon' },
+    });
+    assert.equal(r.status, 200);
+    assert.equal(r.json?.stale_hours, 6);
+    assert.match(String(r.json?.stale_hours_source), /^default \(invalid GDS_STALE_CLAIM_HOURS="six-ish"/);
+  } finally {
+    if (prev === undefined) delete process.env.GDS_STALE_CLAIM_HOURS;
+    else process.env.GDS_STALE_CLAIM_HOURS = prev;
+  }
 });
 
 await t('GET /builders/roster?stale_hours=48 → echoes 48', async () => {
@@ -258,6 +297,7 @@ await t('GET /builders/roster?stale_hours=48 → echoes 48', async () => {
   });
   assert.equal(r.status, 200);
   assert.equal(r.json?.stale_hours, 48);
+  assert.equal(r.json?.stale_hours_source, 'query', 'a lens is labelled as a lens');
 });
 
 await t('GET /builders/roster?stale_hours=0 → 400', async () => {