@humwick/server 0.0.0-stage → 0.130.0

package/src/config.ts

@@ -0,0 +1,939 @@
+import { relayEnv } from "@humwick/sdk/env";
+// Shared runtime constants. Import from here rather than redefining.
+
+import { readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import { DEFAULT_RELAY_URL, RELAY_TOKEN_HEADER } from "@humwick/sdk";
+import { CONTRACT_VERSIONS } from "./contracts";
+import { resolveCliRelayToken } from "./cli/credentials";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const pkg = JSON.parse(readFileSync(join(__dirname, "../package.json"), "utf8"));
+export const VERSION: string = pkg.version;
+export const ORCHESTRATOR_PROTOCOL_VERSION = CONTRACT_VERSIONS.orchestratorProtocol;
+
+/** One-time plan blurb migration can be inspected without changing persisted data. */
+export function planBlurbMigrationDryRun(): boolean {
+  return relayEnv(process.env, "AGENT_RELAY_PLAN_BLURB_MIGRATION_DRY_RUN") === "1";
+}
+
+export function checkoutRefreshEnabled(): boolean { return relayEnv(process.env, "AGENT_RELAY_CHECKOUT_REFRESH") === "1"; }
+
+/** #2982 — log the profile slim-down migration's plan at startup instead of applying it. */
+export function profileSlimMigrationDryRun(): boolean {
+  return relayEnv(process.env, "AGENT_RELAY_PROFILE_SLIM_MIGRATION_DRY_RUN") === "1";
+}
+
+export function versionedPromptsEnabled(): boolean {
+  return relayEnv(process.env, "AGENT_RELAY_VERSIONED_PROMPTS") !== "0";
+}
+
+/**
+ * #1963 N10 — makes the migrated v2 Source × Capability matrix the AUTHORITATIVE profile read.
+ * Default OFF for one release: while off, `builtInProfileEntry` serves the pristine
+ * `agent-profile-override-v1-backup` bytes, so the override migration is byte-invisible and reversible.
+ * Read dynamically (not a module const) so the flag can be flipped per-profile during a live rollout
+ * (order reviewer → worker/coordinator).
+ */
+export function profileMatrixEnabled(): boolean {
+  return relayEnv(process.env, "AGENT_RELAY_PROFILE_MATRIX") === "1";
+}
+
+/** #2932: relay_plan_create refuses a plan without acceptance unless AGENT_RELAY_PLAN_ACCEPTANCE=0. Read at call time. */
+export function planAcceptanceRequired(): boolean {
+  return relayEnv(process.env, "AGENT_RELAY_PLAN_ACCEPTANCE") !== "0";
+}
+
+export const DAY_MS = 86_400_000;
+function envPositiveInt(name: string, fallback: number): number {
+  const raw = relayEnv(process.env, name);
+  if (!raw) return fallback;
+  const parsed = Number(raw);
+  if (!Number.isFinite(parsed) || parsed <= 0) return fallback;
+  return Math.floor(parsed);
+}
+
+/** Like `envPositiveInt` but 0 is a MEANINGFUL value (a disable switch), not a fall-through. */
+function envNonNegativeInt(name: string, fallback: number): number {
+  const raw = relayEnv(process.env, name);
+  if (raw === undefined || raw === "") return fallback;
+  const parsed = Number(raw);
+  if (!Number.isFinite(parsed) || parsed < 0) return fallback;
+  return Math.floor(parsed);
+}
+
+function envNumberOrDefault(name: string, fallback: number): number {
+  return Number(relayEnv(process.env, name)) || fallback;
+}
+
+function envNonNegativeNumber(name: string, fallback: number): number {
+  // Number("") is 0: an empty/blank value must fall back, never become a zero budget.
+  const raw = relayEnv(process.env, name)?.trim();
+  if (!raw) return fallback;
+  const parsed = Number(raw);
+  return Number.isFinite(parsed) && parsed >= 0 ? parsed : fallback;
+}
+
+function envPositiveNumber(name: string, fallback: number): number {
+  const parsed = envNonNegativeNumber(name, fallback);
+  return parsed > 0 ? parsed : fallback;
+}
+
+function envSafePositiveInteger(name: string, fallback: number): number {
+  const raw = relayEnv(process.env, name);
+  if (!raw) return fallback;
+  const parsed = Number(raw);
+  return Number.isSafeInteger(parsed) && parsed > 0 ? parsed : fallback;
+}
+
+function envTrimmed(name: string): string {
+  return (relayEnv(process.env, name) || "").trim();
+}
+
+function envTrimmedOrUndefined(name: string): string | undefined {
+  const value = relayEnv(process.env, name)?.trim();
+  return value || undefined;
+}
+
+export const STALE_TTL_MS = envPositiveInt("STALE_TTL_MS", 120_000); // 2min without heartbeat → offline
+// Observation horizon for agent-initiated spawns whose runner has not registered with Relay.
+// This is deliberately non-terminal: a late runner can still register. The invariant it rests on —
+// the watchdog judges only a row that has already STOPPED — used to be maintained by keeping this
+// horizon above the command TTL. #2275 made the spawn execution lease longer than this horizon (it
+// is derived from the orchestrator's real ~13min budget), so the ordering is now enforced directly
+// at the watchdog instead: a non-terminal spawn row inside its lease is skipped outright
+// (spawnRowStillRunning, services/spawn-registration-watchdog.ts). This horizon therefore still
+// measures a settled row, exactly as before, and a healthy long launch is never judged mid-flight.
+export const SPAWN_REGISTRATION_DEADLINE_MS = envPositiveInt("AGENT_RELAY_SPAWN_REGISTRATION_DEADLINE_MS", 300_000);
+export const SPAWN_REGISTRATION_NOTIFY_MAX_AGE_MS = envPositiveInt("AGENT_RELAY_SPAWN_REGISTRATION_NOTIFY_MAX_AGE_MS", 15 * 60_000);
+// #2104 — the SHORT deadline for a spawn whose loss is CONFIRMED (never dispatched, or its claiming
+// orchestrator process restarted): those need no observation horizon at all, only a small grace so a
+// claim/register interleaving inside one tick can't be misread as a loss. Deliberately well below
+// SPAWN_REGISTRATION_DEADLINE_MS — the 300s horizon exists for the AMBIGUOUS "may still start" case,
+// and making a provably-dead spawn wait it out is exactly the multi-minute silent limbo #2104 is about.
+export const SPAWN_LOST_ESCALATION_DEADLINE_MS = envPositiveInt("AGENT_RELAY_SPAWN_LOST_ESCALATION_DEADLINE_MS", 30_000);
+// #2104 round 3 — the grace an owning orchestrator's `offline` status must clear, MEASURED FROM ITS
+// LAST HEARTBEAT (not from the moment the reaper flips `status`), before a claimed spawn under it is
+// fail-fast'd. `status === "offline"` alone is NOT safe to fail-fast on: STALE_TTL_MS (120s) is a
+// heartbeat-loss detector, not a liveness verdict, and a ROUTINE relay restart makes every
+// orchestrator's heartbeat go stale AT ONCE while it reconnects — observed reconnect gaps run up to
+// ~150s, comfortably past STALE_TTL_MS. Fail-fasting at the 120s reaper mark would terminal-fail a
+// healthy spawn on every ordinary CD deploy.
+//
+// 450s, not 300s (round-3 re-review): this is the TOTAL upgrade-in-flight window a legitimate deploy
+// can occupy, not a bare "how long a restart takes" estimate — release verification itself polls up to
+// MAX_POLLS=90 x 5s = 450s (scripts/release.ts) before it gives up on a slow-re-attesting host, and
+// that whole span can pass with the orchestrator's heartbeat stale before it either lands or the deploy
+// itself times out. 300s (300s ≈ the restart/reconnect gap alone, no re-attestation slack) had ZERO
+// headroom against that documented ceiling. Safety over speed here: a false-fail of a HEALTHY spawn
+// during the frequent CD restarts this floor is guarding against is worse than a slower genuine-loss
+// detection — a sub-minute safe fail needs #2094's claimInstanceId liveness signal (a definitive
+// same-process-or-not fact, not an elapsed-time guess) instead; this floor is the interim backstop
+// until that signal is wired into spawn-loss escalation too (currently only the merge reclaim in
+// commands-db.ts/merge-drain.ts consumes it).
+export const SPAWN_EXECUTOR_OFFLINE_ESCALATION_GRACE_MS = envPositiveInt("AGENT_RELAY_SPAWN_EXECUTOR_OFFLINE_ESCALATION_GRACE_MS", 450_000);
+// #1304 — max member cards serialized into a `relay_team_get` payload. A long-lived coordinator's
+// team accumulates every worker it ever spawned (the roster row survives the agent going offline),
+// so an unbounded roster — and the whole team payload — grows across a session until it can blow the
+// MCP result token cap and hard-error the caller's team fetch. The contract is a *live* roster:
+// live members are always kept, then the most-recently-seen offline members fill the remaining
+// budget; anything past the cap is reported (not silently dropped) via the payload's rosterSummary.
+export const MAX_TEAM_ROSTER_ENTRIES = envPositiveInt("AGENT_RELAY_MAX_TEAM_ROSTER_ENTRIES", 50);
+// #451 — default TTL for fire-and-forget FAN-OUT messages (broadcast/tag/cap/label/team) that the
+// sender didn't bound. A stale fan-out push must not wake an agent that matches the target hours
+// later (the cold-session-woken-by-old-coordination-thread bug). Direct DMs, reply-obligations, and
+// claimable work are exempt (never auto-expire) so store-ahead (#234) still delivers them.
+export const DEFAULT_FANOUT_TTL_SECONDS = envPositiveInt("AGENT_RELAY_FANOUT_TTL_SECONDS", 2 * 60 * 60); // 2h
+export const OFFLINE_PRUNE_MS = envPositiveInt("OFFLINE_PRUNE_MS", DAY_MS); // 24h offline → delete
+export const REAP_INTERVAL_MS = envPositiveInt("REAP_INTERVAL_MS", 60_000); // reaper cadence
+// #1468 — heartbeat presence write-coalescing flush interval. The buffered `last_seen` advance is
+// persisted at most this often (one batched UPDATE for the whole dirty set), so max-staleness of a
+// live agent's persisted last_seen ≤ this. Kept FAR below STALE_TTL_MS (120s) — 24× margin at the
+// 5s default — so the stale reaper never mis-reaps a coalesced-but-live agent. Presence-critical
+// transitions (status change / resurrection) bypass the buffer and write synchronously.
+export const PRESENCE_FLUSH_MS = envPositiveInt("AGENT_RELAY_PRESENCE_FLUSH_MS", 5_000);
+// #2111 — how long the hot lifecycle/registration writes (agents.setStatus, agents.markReady,
+// orchestrators.heartbeat, hosts.upsertFromRegistration) are buffered before being submitted to the
+// writer as ONE batch job. A fleet reconnection storm otherwise costs one BEGIN IMMEDIATE per event
+// on the main loop. Deliberately tiny — 3 orders of magnitude under STALE_TTL_MS (120s) and 200×
+// under PRESENCE_FLUSH_MS — so no liveness/staleness decision can shift because of it. Set to 0 to
+// disable buffering and write straight through (the pre-#2111 behavior).
+export const LIFECYCLE_WRITE_WINDOW_MS = envNonNegativeInt("AGENT_RELAY_LIFECYCLE_WRITE_WINDOW_MS", 25);
+export const STUCK_BUSY_THRESHOLD_MS = envPositiveInt("AGENT_RELAY_STUCK_BUSY_THRESHOLD_MS", 15 * 60_000);
+export const STUCK_BUSY_PROVIDER_TURN_MS = envPositiveInt("AGENT_RELAY_STUCK_BUSY_PROVIDER_TURN_MS", STUCK_BUSY_THRESHOLD_MS);
+export const STUCK_BUSY_STARTUP_MS = envPositiveInt("AGENT_RELAY_STUCK_BUSY_STARTUP_MS", STUCK_BUSY_THRESHOLD_MS);
+export const STUCK_BUSY_RECONNECT_MS = envPositiveInt("AGENT_RELAY_STUCK_BUSY_RECONNECT_MS", STUCK_BUSY_THRESHOLD_MS);
+export const STUCK_BUSY_SHUTDOWN_MS = envPositiveInt("AGENT_RELAY_STUCK_BUSY_SHUTDOWN_MS", STUCK_BUSY_THRESHOLD_MS);
+// #2043 F3 — the hard-backstop force-compact normally waits for the agent to be idle (a busy agent's
+// typed /compact could queue as chat). But a RUNAWAY agent is precisely one stuck busy, so cap that
+// busy-defer: once the agent has been over the hard-backstop threshold for this long while still
+// busy, force the compaction anyway. F1 makes the forced compact safe even mid-turn (the runner
+// waits for the live turn to clear before submitting the keystrokes, so they can't queue as chat).
+export const HARD_BACKSTOP_BUSY_GRACE_MS = envPositiveInt("AGENT_RELAY_HARD_BACKSTOP_BUSY_GRACE_MS", 2 * 60_000);
+// ADR 0002 §6.5 (#895 acceptance item 6, "NO HARDCODING") — every threshold `hostPressureBand()`
+// (§5.2) consults, resolved here with the documented defaults as fallbacks. `sampleStalenessMs` is
+// the ONE staleness constant (RC-11): the admission gate's freshness bound (2×) and the band's
+// `unknown` threshold (3×) are DERIVED from it in the SDK, never separately tuned — two
+// independently-drifting staleness numbers is how a host reports `normal` while the gate degrades.
+// Deliberately a plain object rather than a frozen import in src/host/: keeping env parsing in this
+// one module is what lets H9's settings screen replace the source without touching the ladder.
+export const HOST_BAND_CONFIG = {
+  // 30s, NOT the orchestrator's 15s sampling cadence, because this is a TRANSPORT-side bound: a
+  // sample reaches the relay on the 30s heartbeat, and it can already be one sampler tick old when
+  // the beat leaves. Worst-case age just before the next beat is therefore ~45s on a perfectly
+  // healthy host — which a 15s constant would flag stale at 3x, flapping every host in the fleet
+  // between healthy and degraded forever. At 30s the ladder means "missed two beats", which is a
+  // real signal. The gate's own 15s constant is unaffected: it ages a LOCAL refinement against a
+  // local probe with no network in between.
+  sampleStalenessMs: envPositiveInt("AGENT_RELAY_HOST_SAMPLE_STALENESS_MS", 30_000),
+  trendMinSamples: envPositiveInt("AGENT_RELAY_HOST_TREND_MIN_SAMPLES", 20),
+  trendRisingSlope: envNonNegativeNumber("AGENT_RELAY_HOST_TREND_RISING_SLOPE", 0.1),
+  idleLoadPerCpu: envNonNegativeNumber("AGENT_RELAY_HOST_IDLE_LOAD_PER_CPU", 0.25),
+  busyLoadPerCpu: envNonNegativeNumber("AGENT_RELAY_HOST_BUSY_LOAD_PER_CPU", 0.7),
+  saturatedLoadPerCpu: envNonNegativeNumber("AGENT_RELAY_HOST_SATURATED_LOAD_PER_CPU", 1),
+  minFreeMemMb: envPositiveInt("AGENT_RELAY_HOST_MIN_FREE_MEM_MB", 1_024),
+  busyFreeMemMb: envPositiveInt("AGENT_RELAY_HOST_BUSY_FREE_MEM_MB", 3_072),
+  swapUsedSaturatedPct: envNonNegativeNumber("AGENT_RELAY_HOST_SWAP_SATURATED_PCT", 0.6),
+  diskFreeBusyMb: envPositiveInt("AGENT_RELAY_HOST_DISK_BUSY_FREE_MB", 10_240),
+  diskFreeSaturatedMb: envPositiveInt("AGENT_RELAY_HOST_DISK_SATURATED_FREE_MB", 2_048),
+};
+// #2694 — the default per-host live-agent cap when the operator sets no `policy.maxAgents`:
+// min(physical cores × agentsPerCore, total RAM / memMbPerAgent), never below 1.
+export const HOST_AGENT_CAP_CONFIG = {
+  agentsPerCore: envPositiveNumber("AGENT_RELAY_HOST_AGENTS_PER_CORE", 2),
+  memMbPerAgent: envPositiveInt("AGENT_RELAY_HOST_MEM_MB_PER_AGENT", 2_048),
+};
+export const EVENT_LOOP_LAG_SAMPLE_MS = envPositiveInt("AGENT_RELAY_EVENT_LOOP_LAG_SAMPLE_MS", 1_000);
+// #1055 invariant: retain STRICTLY MORE than one reaper interval of lag history. The
+// stale/bus reaper reads the cumulative lag grace once per REAP_INTERVAL_MS; if the ring
+// held only one interval's worth (the old 60×1s == 60s == REAP_INTERVAL coincidence),
+// the oldest stall samples could rotate out the instant before the first post-recovery
+// reaper run and collapse the grace exactly when it's needed. Keep a half-interval margin
+// (1.5× reaper interval) so recent overload always survives to the next reaper tick.
+export const EVENT_LOOP_LAG_WINDOW_SAMPLES = envPositiveInt(
+  "AGENT_RELAY_EVENT_LOOP_LAG_WINDOW_SAMPLES",
+  Math.ceil((REAP_INTERVAL_MS / EVENT_LOOP_LAG_SAMPLE_MS) * 1.5),
+);
+export const EVENT_LOOP_LAG_WARN_MS = envNonNegativeNumber("AGENT_RELAY_EVENT_LOOP_LAG_WARN_MS", 250);
+export const EVENT_LOOP_LAG_LOG_MS = envNonNegativeNumber("AGENT_RELAY_EVENT_LOOP_LAG_LOG_MS", EVENT_LOOP_LAG_WARN_MS);
+// #1883 (S7, ADR 0001 §10) — the PERCENTILE window, deliberately SEPARATE from the #1055 ring above.
+// Two different questions need two different windows and one ring cannot serve both:
+//   - EVENT_LOOP_LAG_WINDOW_SAMPLES (90 @1s) answers "how much heartbeat debt just accumulated" for
+//     the reaper's grace. Widening it would silently widen `eventLoopLagGraceMs()` — the SUM over the
+//     ring — and with it the stale-reaper grace. That is a behaviour change to reaping, not a metric.
+//   - this window answers "is loop lag SUSTAINED under the p99 target". At 90 samples the 99th
+//     percentile is the 1st-worst sample, i.e. indistinguishable from `maxMs` — a single GC pause
+//     would read as a p99 breach. p99 only becomes a percentile (rather than a max in disguise) once
+//     n ≫ 100.
+// 15 minutes (900 samples @1s) is the choice: the top 1% is then the ~9th-worst sample, so one-off
+// jitter cannot move it while a genuinely degraded period does; it spans several reaper intervals and
+// a full maintenance cycle, which is what "sustained" means for this epic; and it costs one 900-entry
+// Float64Array (7.2 KB, fixed) with an O(1) hot-path write. Raise it for a longer sustained view;
+// the memory cost is linear and the read cost is an O(n log n) sort on the health poll only.
+export const EVENT_LOOP_LAG_PERCENTILE_WINDOW_SAMPLES = envPositiveInt(
+  "AGENT_RELAY_EVENT_LOOP_LAG_PERCENTILE_WINDOW_SAMPLES",
+  Math.ceil((15 * 60_000) / EVENT_LOOP_LAG_SAMPLE_MS),
+);
+// The S7 exit criterion itself, from ADR 0001 §10 ("Event-loop-lag p99 becomes a tight, enforceable
+// tripwire (S7 #1883 exit criterion: p99 < 100 ms)") and §5. Config, not a literal, so #1883 can
+// tighten it without a code change. REPORTED ONLY at this stage: it rides the health payload as a
+// metric so the exit criterion can be evaluated, and deliberately does NOT move the health check's
+// status — pre-seam (S2/S3 not landed) p99 is EXPECTED to breach, so warning on it now would pin
+// every relay's health to `warn` and train operators to ignore it. #1883 owns flipping it to a gate.
+export const EVENT_LOOP_LAG_P99_TARGET_MS = envNonNegativeNumber("AGENT_RELAY_EVENT_LOOP_LAG_P99_TARGET_MS", 100);
+// #1724 stage 1 — the event-loop-lag circuit breaker. When a maintenance run overlaps a lag sample
+// at or above this threshold, that run takes a breaker "strike": the loop was starved while it ran.
+// Set WELL above EVENT_LOOP_LAG_WARN_MS (which is only a diagnostic warn) so the breaker fires on a
+// genuine freeze — the 60-91s incident shape — not on ordinary jitter. A single spike is not proof:
+// a strike only trips the breaker after MAX_STRIKES of them accumulate (see below).
+export const MAINTENANCE_BREAKER_LAG_MS = envPositiveInt("AGENT_RELAY_MAINTENANCE_BREAKER_LAG_MS", 1_000);
+// Consecutive breaker strikes (a lag spike attributed to the job, OR a run that timed out past its
+// deadline) before the job is auto-paused. Three, not one, for the same reason the critical-job
+// health check waits for two consecutive failures: one freeze can be a GC pause or a one-off; a
+// REPEATEDLY misbehaving job is a pattern worth durably stopping. A clean run resets the count.
+export const MAINTENANCE_BREAKER_MAX_STRIKES = envPositiveInt("AGENT_RELAY_MAINTENANCE_BREAKER_MAX_STRIKES", 3);
+// #1882 (S5, ADR 0001 §5) — Pillar 3: per-callsite on-loop-block attribution + the >50ms regression
+// alarm. Post-seam (S2/S3) the DB runs OFF the loop, so a synchronous on-loop block at/above this
+// threshold is by construction NOT a DB call — it is CPU/fs BETWEEN awaits (a stray site that slipped
+// the ratchet, or heavy in-loop CPU). It is therefore anomalous and self-diagnosing: it names its
+// originating `file:line` and ALARMS as a REGRESSION (routed to the escalation sink), not a passive
+// console.warn. This is the runtime tripwire the S7 #1883 p99 loop-lag exit criterion depends on.
+export const ON_LOOP_BLOCK_REGRESSION_MS = envNonNegativeNumber("AGENT_RELAY_ON_LOOP_BLOCK_REGRESSION_MS", 50);
+// A synchronous frame at/above this is RECORDED (with its attributed callsite) into the overlap ring
+// the lag attributor queries — so a block just over the regression threshold is composed of ring
+// frames the attributor can name. Deliberately WELL below the regression threshold. Sub-floor frames
+// (the overwhelming majority of loop turns) pay only two monotonic-clock reads and a subtract — no
+// allocation, no ring write — so the tripwire is cheap enough to leave armed in production.
+export const ON_LOOP_BLOCK_RECORD_MS = envNonNegativeNumber("AGENT_RELAY_ON_LOOP_BLOCK_RECORD_MS", 5);
+// Bounded ring of recently-recorded frames. A residual on-loop block is RARE post-seam, so this stays
+// tiny; it is a diagnostic overlap buffer, not a metrics store.
+export const ON_LOOP_BLOCK_RING_SIZE = envPositiveInt("AGENT_RELAY_ON_LOOP_BLOCK_RING_SIZE", 64);
+// Maintenance health warns when measured main-thread block time exceeds this budget.
+export const MAINTENANCE_BLOCK_BUDGET_MS = envPositiveInt("AGENT_RELAY_MAINTENANCE_BLOCK_BUDGET_MS", 200);
+// #713 — provider-token silence ALONE is not a wedge signal for Claude (long turns, extended
+// thinking, and native compaction all go token-silent while healthy). Before declaring stuck we
+// ALSO require the transport heartbeat to be genuinely dead: no server frame / heartbeat-ack within
+// this window. The runner heartbeats every 30s, so 2min (4 missed beats) is a clear "transport gone"
+// signal, well above jitter and far below the 15min provider threshold — a real wedge (transport dead
+// AND provider silent AND no lifecycle progress) still fires. A live heartbeat ⇒ not wedged.
+export const STUCK_BUSY_TRANSPORT_STALE_MS = envPositiveInt("AGENT_RELAY_STUCK_BUSY_TRANSPORT_STALE_MS", 2 * 60_000);
+// #2036 (#2031 L5) — the agent-hang self-check ladder. Every knob goes through `envPositiveInt`,
+// which REJECTS a non-finite / zero / negative override and falls back to the default: a
+// `baseRungMs` of 0 would make every rung due at elapsed 0 and spin `highestDueRung` forever, so
+// invalid config must degrade to the default rather than reach the decision core (the core clamps
+// again, defensively — see `resolveConfig` in services/agent-hang-watchdog.ts).
+// DEFAULT-OFF, opt in with `AGENT_RELAY_HANG_WATCHDOG=1` (#2036 review GAP 3b): this watchdog wakes
+// agents with `forceDelivery` + wake-true, so the blast radius of a first tick on a live fleet is
+// every idle agent holding an old obligation. It ships dark like the other kernel-class rollouts and
+// gets switched on deliberately after a gate run, not silently at deploy.
+export function agentHangWatchdogEnabled(): boolean {
+  return relayEnv(process.env, "AGENT_RELAY_HANG_WATCHDOG") === "1";
+}
+/** R1 fires at this episode age; the ladder doubles from here (R2 = 3×, R3 = 7× …). */
+export const HANG_WATCHDOG_RUNG_BASE_MS = envPositiveInt("AGENT_RELAY_HANG_WATCHDOG_BASE_RUNG_MS", 10 * 60_000);
+/** A genuine agent turn within this window of a delivered rung counts as an ack. */
+export const HANG_WATCHDOG_ACK_WINDOW_MS = envPositiveInt("AGENT_RELAY_HANG_WATCHDOG_ACK_WINDOW_MS", 5 * 60_000);
+/** Consecutive delivered-but-unacked rungs that hand the agent to its coordinator. */
+export const HANG_WATCHDOG_ESCALATE_AFTER_UNACKED = envPositiveInt("AGENT_RELAY_HANG_WATCHDOG_ESCALATE_AFTER_UNACKED", 2);
+export const CLAIM_LEASE_MS = envPositiveInt("AGENT_RELAY_CLAIM_LEASE_MS", 1_800_000); // 30min claim lease
+export const POOL_CLAIM_LEASE_MS = envPositiveInt("AGENT_RELAY_POOL_CLAIM_LEASE_MS", STALE_TTL_MS * 3); // pool binding lease
+// Per-repo merge serialization lease — only one base merge may run at a time per
+// repo. Held from when a workspace.merge command is dispatched until it settles
+// (or this TTL expires, in case the orchestrator never reports back).
+export const WORKSPACE_MERGE_LEASE_MS = envPositiveInt("AGENT_RELAY_WORKSPACE_MERGE_LEASE_MS", 900_000); // 15min
+// Opt-in release/build critical-section pause for relay-owned auto-merge sweeps.
+// This narrows the race window while the release script creates and pushes a tag;
+// expiry is the safety net so a killed holder cannot wedge the repo.
+export const MAIN_MERGE_PAUSE_TTL_MS = envPositiveInt("AGENT_RELAY_MAIN_MERGE_PAUSE_TTL_MS", 5 * 60_000); // 5min
+
+// Max body size for any POST/PATCH request (64 KiB).
+export const MAX_BODY_BYTES = 64 * 1024;
+export const INTEGRATION_RATE_LIMIT_PER_MINUTE = envPositiveInt("AGENT_RELAY_INTEGRATION_RATE_LIMIT_PER_MINUTE", 120);
+
+export const AUTOMATION_INTERVAL_MS = envNumberOrDefault("AGENT_RELAY_AUTOMATION_INTERVAL_MS", 30 * 1000);
+export const SCHEDULER_TICK_MS = envNumberOrDefault("AGENT_RELAY_SCHEDULER_TICK_MS", 5 * 1000);
+export const SCHEDULER_CLAIM_LEASE_MS = envNumberOrDefault("AGENT_RELAY_SCHEDULER_CLAIM_LEASE_MS", 60 * 1000);
+export const SCHEDULER_RETRY_MS = envNumberOrDefault("AGENT_RELAY_SCHEDULER_RETRY_MS", 60 * 1000);
+export const SCHEDULER_MAX_FAILURES = envNumberOrDefault("AGENT_RELAY_SCHEDULER_MAX_FAILURES", 3);
+export const SCHEDULER_MIN_RECURRING_INTERVAL_MS = envNumberOrDefault("AGENT_RELAY_SCHEDULER_MIN_RECURRING_INTERVAL_MS", 60 * 1000);
+// Stage 2 of the MESSAGE-authority flip splits the old shared timer budget. Keep the legacy env as
+// the fallback so an existing operator override remains behavior-preserving, while allowing either
+// timer type to be tuned independently from this landing onward.
+const SCHEDULER_LEGACY_MAX_ACTIVE_TIMERS = envNumberOrDefault("AGENT_RELAY_SCHEDULER_MAX_ACTIVE_TIMERS", 100);
+export const SCHEDULER_MAX_ACTIVE_MESSAGE_TIMERS = envNumberOrDefault(
+  "AGENT_RELAY_SCHEDULER_MAX_ACTIVE_MESSAGE_TIMERS",
+  SCHEDULER_LEGACY_MAX_ACTIVE_TIMERS,
+);
+export const SCHEDULER_MAX_ACTIVE_COMMAND_TIMERS = envNumberOrDefault(
+  "AGENT_RELAY_SCHEDULER_MAX_ACTIVE_COMMAND_TIMERS",
+  SCHEDULER_LEGACY_MAX_ACTIVE_TIMERS,
+);
+export const SCHEDULER_MAX_PAYLOAD_BYTES = envNumberOrDefault("AGENT_RELAY_SCHEDULER_MAX_PAYLOAD_BYTES", 16 * 1024);
+// Stage 6 MESSAGE-authority coordinator. No operator action is exposed yet; these bounds are used
+// only by internal proof/recovery of an already-journaled shadow cutover.
+export const KERNEL_TIMERS_CUTOVER_TICK_MS = envPositiveInt("AGENT_RELAY_KERNEL_TIMERS_CUTOVER_TICK_MS", 1_000);
+export const KERNEL_TIMERS_CUTOVER_LEASE_MS = envPositiveInt("AGENT_RELAY_KERNEL_TIMERS_CUTOVER_LEASE_MS", 15_000);
+export const KERNEL_TIMERS_CUTOVER_QUIESCE_TIMEOUT_MS = envPositiveInt("AGENT_RELAY_KERNEL_TIMERS_CUTOVER_QUIESCE_TIMEOUT_MS", 30_000);
+export const KERNEL_TIMERS_CUTOVER_WORST_CASE_MS = envPositiveInt("AGENT_RELAY_KERNEL_TIMERS_CUTOVER_WORST_CASE_MS", 60_000);
+export const KERNEL_TIMERS_DUAL_READ_GRACE_MS = envPositiveInt("AGENT_RELAY_KERNEL_TIMERS_DUAL_READ_GRACE_MS", 5 * 60_000);
+// The bus has its own application-level heartbeat and reconnect protocol. Bun's global server
+// idle timeout is a transport-level kill switch (max 255s), so it can flap an otherwise healthy
+// long-lived bus connection when a heartbeat is delayed by host/event-loop pressure (#1367).
+// Zero disables Bun's timeout; operators can still opt into a finite value explicitly.
+export const IDLE_TIMEOUT_SECONDS = envNumberOrDefault("AGENT_RELAY_IDLE_TIMEOUT_SECONDS", 0);
+export const LOG_REQUESTS = relayEnv(process.env, "AGENT_RELAY_LOG_REQUESTS") === "1";
+
+const AUTH_TOKEN = relayEnv(process.env, "AGENT_RELAY_TOKEN") || "";
+export const CORS_ORIGINS = (relayEnv(process.env, "AGENT_RELAY_CORS_ORIGINS") || "")
+  .split(",")
+  .map((origin) => origin.trim())
+  .filter(Boolean);
+
+export function relayToken(): string {
+  return relayEnv(process.env, "AGENT_RELAY_TOKEN") ?? AUTH_TOKEN;
+}
+
+export function relayAuthHeaders(base: Record<string, string> = {}): Record<string, string> {
+  const token = relayToken();
+  return token ? { ...base, [RELAY_TOKEN_HEADER]: token } : base;
+}
+
+// #1024 — origins the orchestrator proxy may forward the relay MASTER token (relayToken()) to.
+// A dynamically-registered orchestrator can carry an attacker-controlled apiUrl; forwarding the
+// master token there leaks full relay admin. This is the defense-in-depth backstop behind the
+// registration lock: even if some path seeds an orchestrator row, the proxy refuses to talk to an
+// untrusted apiUrl at all (never sending the token OR the caller's query string). Explicit
+// operator overrides — comma-separated origins, e.g. "https://orch.example.com".
+export const TRUSTED_ORCHESTRATOR_ORIGINS = (relayEnv(process.env, "AGENT_RELAY_TRUSTED_ORCHESTRATOR_ORIGINS") || "")
+  .split(",")
+  .map((origin) => origin.trim())
+  .filter(Boolean);
+
+// A private/LAN/tailnet IP literal — never a public, attacker-reachable address.
+function isPrivateIpLiteral(host: string): boolean {
+  const v4 = /^(\d{1,3})\.(\d{1,3})\.(\d{1,3})\.(\d{1,3})$/.exec(host);
+  if (v4) {
+    const a = Number(v4[1]), b = Number(v4[2]);
+    if (a === 10 || a === 127) return true;              // 10.0.0.0/8, loopback
+    if (a === 172 && b >= 16 && b <= 31) return true;    // 172.16.0.0/12
+    if (a === 192 && b === 168) return true;             // 192.168.0.0/16
+    if (a === 169 && b === 254) return true;             // 169.254.0.0/16 link-local
+    if (a === 100 && b >= 64 && b <= 127) return true;   // 100.64.0.0/10 CGNAT (tailnet)
+    return false;
+  }
+  if (/^f[cd][0-9a-f]*:/.test(host)) return true;         // IPv6 ULA fc00::/7
+  if (/^fe[89ab][0-9a-f]*:/.test(host)) return true;      // IPv6 link-local fe80::/10
+  return false;
+}
+
+// Whether the relay master token may be forwarded to this orchestrator apiUrl (#1024). Trusts
+// loopback, bare single-label hostnames (LAN/MagicDNS — never a public FQDN), private DNS
+// suffixes, private/CGNAT/ULA IP literals, and any explicit AGENT_RELAY_TRUSTED_ORCHESTRATOR_ORIGINS
+// entry. A public IP or public FQDN (e.g. http://attacker.example) is refused unless allowlisted.
+export function isTrustedOrchestratorApiUrl(apiUrl: string | undefined): boolean {
+  if (!apiUrl) return false;
+  let url: URL;
+  try {
+    url = new URL(apiUrl);
+  } catch {
+    return false;
+  }
+  if (TRUSTED_ORCHESTRATOR_ORIGINS.includes(url.origin)) return true;
+  let host = url.hostname.toLowerCase();
+  if (host.startsWith("[") && host.endsWith("]")) host = host.slice(1, -1); // unwrap IPv6 literal
+  if (host === "localhost" || host === "127.0.0.1" || host === "::1") return true;
+  // A bare single-label host (no dot, not an IPv6 literal) is a LAN/MagicDNS name, never public.
+  if (!host.includes(".") && !host.includes(":")) return true;
+  if (/\.(local|internal|lan|home|ts\.net|tailnet)$/.test(host)) return true;
+  return isPrivateIpLiteral(host);
+}
+
+export function allowUnauthenticated(): boolean {
+  return relayEnv(process.env, "AGENT_RELAY_ALLOW_UNAUTH") === "1";
+}
+
+export function tokenSecretFromEnv(): string | undefined {
+  return relayEnv(process.env, "AGENT_RELAY_TOKEN_SECRET");
+}
+
+export function corsOriginsFromEnv(): string[] | undefined {
+  const raw = relayEnv(process.env, "AGENT_RELAY_CORS_ORIGINS");
+  if (raw === undefined) return undefined;
+  return raw.split(",").map((origin) => origin.trim()).filter(Boolean);
+}
+
+export function connectorsDirFromEnv(): string | undefined {
+  return relayEnv(process.env, "AGENT_RELAY_CONNECTORS_DIR");
+}
+
+export function connectorRelayUrl(): string {
+  const url = new URL(DEFAULT_RELAY_URL);
+  url.port = String(Number(process.env.PORT) || Number(url.port));
+  return url.origin;
+}
+
+/** Source repo for a symlink-runtime self-upgrade's gitSha attestation (#1457). */
+export function artifactRepoUrlFromEnv(): string | undefined {
+  return relayEnv(process.env, "AGENT_RELAY_ARTIFACT_REPO");
+}
+
+export function connectorActionTimeoutMs(fallback: number): number {
+  const raw = Number(relayEnv(process.env, "AGENT_RELAY_CONNECTOR_ACTION_TIMEOUT_MS"));
+  return Number.isFinite(raw) && raw > 0 ? raw : fallback;
+}
+
+export function rateLimitFallbackMs(): number {
+  return envNumberOrDefault("AGENT_RELAY_RATE_LIMIT_FALLBACK_MS", 60 * 60 * 1000);
+}
+
+export function artifactsDir(): string {
+  return relayEnv(process.env, "AGENT_RELAY_ARTIFACTS_DIR") || "~/.agent-relay/artifacts";
+}
+
+export const OUTBOX_RETENTION_MS = envNumberOrDefault("AGENT_RELAY_OUTBOX_RETENTION_MS", 60 * 60 * 1000);
+// Per-provider quota history retention (#609) — durable burn-rate history for the sparkline/analytics
+// charts (#607/#608). Default 30 days; the quota-history-prune maintenance reaper drops older entries.
+export const QUOTA_HISTORY_RETENTION_MS = envNumberOrDefault("AGENT_RELAY_QUOTA_HISTORY_RETENTION_MS", 30 * DAY_MS);
+export const QUOTA_HISTORY_PRUNE_INTERVAL_MS = envNumberOrDefault("AGENT_RELAY_QUOTA_HISTORY_PRUNE_INTERVAL_MS", 6 * 60 * 60 * 1000);
+// #1959 — listProviderQuotas()/routingSnapshot short-TTL matrix cache. The matrix is ~3 accounts and
+// only changes on a providerQuotas.upsert (which invalidates it immediately regardless of TTL); this
+// just bounds how long a burst of same-scope calls (spawn-sizing, dispatch) reuse one computed matrix.
+export const PROVIDER_QUOTA_MATRIX_CACHE_TTL_MS = envNumberOrDefault("AGENT_RELAY_PROVIDER_QUOTA_MATRIX_CACHE_TTL_MS", 1_000);
+export const CODEX_WHAM_QUOTA_INTERVAL_MS = envNumberOrDefault("AGENT_RELAY_CODEX_WHAM_QUOTA_INTERVAL_MS", 5 * 60 * 1000);
+export const CONFLICT_SCAN_INTERVAL_MS = envNumberOrDefault("AGENT_RELAY_CONFLICT_SCAN_INTERVAL_MS", 10 * 60 * 1000);
+export const WORKSPACE_RETENTION_MS = envNumberOrDefault("AGENT_RELAY_WORKSPACE_RETENTION_MS", DAY_MS);
+// #1726 — max expired-terminal workspace rows workspaceGC reclaims (deletes) per run. GC can be
+// paused for long stretches, so the expired-terminal backlog (cleaned/merged/abandoned rows past
+// the retention cutoff) can grow large; draining it in one synchronous pass is an unbounded write
+// batch. Bounding it lets an hourly GC clear any backlog over a few cadences instead of one big tick.
+export const WORKSPACE_GC_DELETE_BATCH = envPositiveInt("AGENT_RELAY_WORKSPACE_GC_DELETE_BATCH", 500);
+export const DB_MAINTENANCE_INTERVAL_MS = envNumberOrDefault("AGENT_RELAY_DB_MAINTENANCE_INTERVAL_MS", DAY_MS);
+// #3086 — exact sqlite_stat1 rows for EXACT_STATS_TABLES; the hub plans with them from its next start.
+export const DB_PLANNER_STATS_INTERVAL_MS = envPositiveInt("AGENT_RELAY_DB_PLANNER_STATS_INTERVAL_MS", 6 * 60 * 60_000);
+// Lightweight WAL housekeeping is deliberately independent of the daily ANALYZE/VACUUM pass.
+// PASSIVE checkpoints are non-blocking; the optional TRUNCATE attempt is zero-wait and one-shot.
+export const DB_WAL_RECLAIM_INTERVAL_MS = envPositiveInt("AGENT_RELAY_DB_WAL_RECLAIM_INTERVAL_MS", 5 * 60_000);
+/** #3612 — Litestream must seal the WAL before checkpointing; competing checkpoints extend its barrier. */
+export function dbCheckpointOwner(): "relay" | "litestream" {
+  const owner = relayEnv(process.env, "AGENT_RELAY_DB_CHECKPOINT_OWNER") ?? "relay";
+  if (owner !== "relay" && owner !== "litestream") throw new Error(`Invalid DB checkpoint owner: ${owner}`);
+  return owner;
+}
+// #3022 — cadence of the hub's off-loop WAL checkpointer (src/db/wal-checkpointer.ts). Each round copies
+// only the frames committed since the last one, so a short cadence keeps both the WAL and each round small.
+export const DB_WAL_CHECKPOINT_INTERVAL_MS = envPositiveInt("AGENT_RELAY_DB_WAL_CHECKPOINT_INTERVAL_MS", 1000);
+export const DB_WAL_RECLAIM_THRESHOLD_BYTES = envSafePositiveInteger(
+  "AGENT_RELAY_DB_WAL_RECLAIM_THRESHOLD_BYTES",
+  64 * 1024 * 1024,
+);
+// #2276 — WAL-size alarm arms for the `database-wal` health check. Before this there was NO metric,
+// check or alarm on WAL size anywhere in the server, so a WAL that outgrew its bound was a silent
+// disk fill behind a green dashboard.
+//
+// The arms are set from MEASURED overshoot, not from the nominal ceiling. `wal_autocheckpoint` bounds
+// the WAL only where reader-free instants exist: SQLite rewinds a WAL when a writer finds
+// `nBackfill == mxFrame` and NO reader holds a mark, so a connection pool reading almost
+// continuously leaves almost no instant at which a rewind is possible. Measured against a reader
+// SUBPROCESS at three cadences (60k × 4KB commits; peak WAL / multiple of the nominal ceiling):
+//
+//                     read every 2ms     every 20ms     every 100ms
+//   pages = 8192      287.8MB (9.0×)     41.1MB (1.3×)   34.9MB (1.1×)
+//   pages = 1000      416.5MB (106×)     13.0MB (3.3×)    5.8MB (1.5×)
+//
+// Note the saturating column: heavy overshoot is a property of reader saturation, NOT of the raised
+// ceiling — the 1000-page default overshoots FURTHER there in absolute bytes. So WARN must sit well
+// above a legitimately busy relay or it pages a human for a healthy state; it is a "the bound failed"
+// signal, not a "readers are busy" signal.
+export const DB_WAL_WARN_BYTES = envSafePositiveInteger("AGENT_RELAY_DB_WAL_WARN_BYTES", 512 * 1024 * 1024);
+export const DB_WAL_ERROR_BYTES = envSafePositiveInteger("AGENT_RELAY_DB_WAL_ERROR_BYTES", 1024 * 1024 * 1024);
+/**
+ * #2276 — how many CONSECUTIVE `db-wal-reclaim` passes must find the WAL past the WARN arm without
+ * reclaiming before the job reports a failure. A single `reclaimed: false` is benign and
+ * self-correcting (any reader holding a mark at that instant produces one), so escalating on it would
+ * page a human for normal load. At the 5-minute cadence this is ~15 minutes of sustained failure.
+ */
+export const DB_WAL_RECLAIM_FAILURE_STREAK = envPositiveInt("AGENT_RELAY_DB_WAL_RECLAIM_FAILURE_STREAK", 3);
+// #3000 — off by default: VACUUM holds the write lock for the whole file rewrite (minutes on a
+// multi-GB hub DB), and auto_vacuum=0 with a tiny freelist leaves nothing to reclaim. Opt in per host.
+export const DB_VACUUM_EVERY = envNumberOrDefault("AGENT_RELAY_DB_VACUUM_EVERY", 0);
+export const WORKSPACE_REVIEW_TTL_MS = envNumberOrDefault("AGENT_RELAY_WORKSPACE_REVIEW_TTL_MS", 3 * DAY_MS);
+export const WORKSPACE_GC_INTERVAL_MS = envNumberOrDefault("AGENT_RELAY_WORKSPACE_GC_INTERVAL_MS", 60 * 60 * 1000);
+export const WORKSPACE_ORPHAN_REAPER_INTERVAL_MS = envNumberOrDefault("AGENT_RELAY_WORKSPACE_ORPHAN_REAPER_INTERVAL_MS", 30 * 60 * 1000);
+// #2408 — while a reaper pass leaves probe-bound candidates unvisited (its per-tick batch cap), the
+// next pass reschedules this soon instead of waiting the full interval, so a backlog of stale
+// worktrees drains across many short passes rather than one pass that can approach the breaker's
+// deadline. Comfortably above SCHEDULER_TICK_MS so it lands on a normal tick.
+export const WORKSPACE_ORPHAN_REAPER_BACKLOG_INTERVAL_MS = envNumberOrDefault("AGENT_RELAY_WORKSPACE_ORPHAN_REAPER_BACKLOG_INTERVAL_MS", 60 * 1000);
+// #2554 — the fleet-wide stale-workspace cleanup sweep (the cleanupStaleWorkspaces primitive):
+// reclaims isolated workspaces whose owner is dead and whose tree is provably landed/empty/absent —
+// including the dead-owner `active` rows every other sweep skipped. 30 minutes sits between the
+// 10-min conflict scan and the hourly GC; the reclaim is dead-owner + land-safe gated, never
+// age-based (#977 safeguard).
+export const WORKSPACE_STALE_CLEANUP_INTERVAL_MS = envNumberOrDefault("AGENT_RELAY_WORKSPACE_STALE_CLEANUP_INTERVAL_MS", 30 * 60 * 1000);
+// #2554 — while a sweep pass leaves probe-budget overflow (`moreWork`), reschedule this soon so a
+// large dead-owner backlog drains across short passes instead of one marathon run.
+export const WORKSPACE_STALE_CLEANUP_BACKLOG_INTERVAL_MS = envNumberOrDefault("AGENT_RELAY_WORKSPACE_STALE_CLEANUP_BACKLOG_INTERVAL_MS", 60 * 1000);
+export const WORKSPACE_AUTO_MERGE_INTERVAL_MS = envNumberOrDefault("AGENT_RELAY_WORKSPACE_AUTO_MERGE_INTERVAL_MS", CONFLICT_SCAN_INTERVAL_MS);
+export const WORKSPACE_IDLE_REFRESH_INTERVAL_MS = envNumberOrDefault("AGENT_RELAY_WORKSPACE_IDLE_REFRESH_INTERVAL_MS", CONFLICT_SCAN_INTERVAL_MS);
+export const ORPHAN_REAPER_INTERVAL_MS = envNumberOrDefault("AGENT_RELAY_ORPHAN_REAPER_INTERVAL_MS", 5 * 60 * 1000);
+// #1939 — the CLAUDE.md re-ingest sweep's standing interval. Daily: CLAUDE.md edits are not
+// frequent enough to need faster tracking, and `runOnStart` (see project-claudemd-sweep.ts)
+// already covers the "just deployed / just registered" case without waiting out this interval.
+export const CLAUDEMD_REINGEST_INTERVAL_MS = envNumberOrDefault("AGENT_RELAY_CLAUDEMD_REINGEST_INTERVAL_MS", DAY_MS);
+export const STEWARD_WAKE_COOLDOWN_MS = envNumberOrDefault("AGENT_RELAY_STEWARD_WAKE_COOLDOWN_MS", 10 * 60 * 1000);
+// #1440 — a steward hand-off ("🛟 …now with a steward, will land or escalate") is only real if a
+// live steward acts on it. This is the bounded window after which the handoff watchdog re-checks a
+// still-unlanded workspace's steward liveness and re-wakes / escalates if it isn't healthy-running.
+// MUST stay > STEWARD_WAKE_COOLDOWN_MS so a watchdog re-wake is never swallowed by the wake cooldown.
+export const STEWARD_HANDOFF_WATCHDOG_MS = envNumberOrDefault("AGENT_RELAY_STEWARD_HANDOFF_WATCHDOG_MS", 15 * 60 * 1000);
+// #1440 — how many times the watchdog re-wakes an unhealthy steward before escalating to the branch
+// agent's coordinator (or raising a durable "needs a steward, none available" alarm). A provider-hold
+// steward will not recover on re-wake, so this bound is what guarantees escalation instead of a loop.
+export const STEWARD_HANDOFF_REWAKE_MAX = envNumberOrDefault("AGENT_RELAY_STEWARD_HANDOFF_REWAKE_MAX", 2);
+// #2704 — a steward that still looks alive this long after the hand-off, without landing, is not
+// resolving the conflict either: the land goes back to its owner, who may rebase and re-deliver.
+export const STEWARD_HANDOFF_DEADLINE_MS = envNumberOrDefault("AGENT_RELAY_STEWARD_HANDOFF_DEADLINE_MS", 60 * 60 * 1000);
+// #1745 — hard ceiling on how many steward agents may be LIVE for one repo at once (across all
+// hosts). The runaway spiral spawned 8+ codex stewards for a single repo's stranded lands; this cap
+// bounds the blast radius. When the cap is hit a new spawn is denied (the durable hand-off obligation
+// persists and the hand-off watchdog escalates to a human after its re-wake budget) instead of
+// stacking yet another process. Per-(repo,host) dedup still lives in onMessageForPolicy's
+// already-active check; this is the cross-host ceiling on top of it.
+export const MAX_LIVE_STEWARDS_PER_REPO = envNumberOrDefault("AGENT_RELAY_MAX_STEWARDS_PER_REPO", 2);
+// #1761 — fleet-wide hard ceiling on the TOTAL number of LIVE steward agents at once, across every
+// repo and host. The per-repo cap above bounds a single repo's blast radius but not the aggregate:
+// a burst that stranded lands across N repos (e.g. the #1760 command-loop freeze) spawned one steward
+// per repo/host and piled 12 idle stewards fleet-wide, none individually over the per-repo cap. This
+// counts LIVE steward AGENTS (by tag) rather than policy managed-state, so an ORPHANED steward whose
+// managed state was overwritten by a respawn still counts — the exact runaway the per-repo cap missed.
+// At the cap a new spawn is denied (the durable hand-off obligation persists and the hand-off watchdog
+// escalates) instead of stacking another process.
+export const MAX_LIVE_STEWARDS_FLEET = envNumberOrDefault("AGENT_RELAY_MAX_STEWARDS_FLEET", 8);
+// #1761 — the operator's authoritative bound: AT MOST ONE steward per (repo, host). The gate is
+// evaluated per steward policy, which IS a (repo, host), so this is a cap of 1 on live steward AGENTS
+// attributable to that (repo, host) — counting agents (not managed policy state) so a WEDGED steward
+// (stuck `stopping`, alive, invisible to the state-based cap after the 5e0cf070 regression) or an
+// ORPHAN still blocks a duplicate spawn on the same host. The fleet cap above is then a genuine
+// aggregate backstop, not the only bound.
+export const MAX_LIVE_STEWARDS_PER_REPO_HOST = envNumberOrDefault("AGENT_RELAY_MAX_STEWARDS_PER_REPO_HOST", 1);
+// #1761 — bounded forceful re-issue of a steward stop that did not confirm dead. The 5e0cf070 #1725
+// fix-forward left a `stopping` steward pinned INDEFINITELY (never re-issuing the kill) whenever the
+// agent stayed alive/kill-failed; that wedged process is the mechanical cause of the same-host pile-up.
+// After STOP_TIMEOUT_MS with the process still alive, reconcilePolicy re-issues a FORCEFUL stop up to
+// this many times before giving up to `failed` and releasing the handle (the per-(repo,host) agent cap
+// then still bounds any spawn, so releasing the handle can't reopen the #1745 spiral).
+export const MAX_STEWARD_STOP_RETRIES = envNumberOrDefault("AGENT_RELAY_MAX_STEWARD_STOP_RETRIES", 3);
+// How long a managed policy may sit in `starting` before the transition counts as WEDGED (the spawn
+// never reached "running": runner crashed, never registered, host partition). Lives here — not in
+// lifecycle-manager — because the steward per-(repo,host) cap must apply the SAME freshness rule the
+// lifecycle manager's `managedProcessActive` does (#1955, #1953-review nit 3); a stale `starting`
+// counted as live would transiently deny a genuine-conflict steward spawn.
+export const MANAGED_START_TIMEOUT_MS = 120_000;
+// #1761 — the orphan idle-reap grace FLOOR. The reaper's grace is driven by the dashboard-configurable
+// `keepaliveSeconds` (so the operator's "Keepalive seconds" governs the orphan population too, not just
+// tracked stewards); this floor guards against a zero/small keepalive reaping a just-created orphan
+// with no grace at all (the reaper also floors idle-age by the agent's createdAt for the same reason).
+export const STEWARD_ORPHAN_REAP_FLOOR_MS = envNumberOrDefault("AGENT_RELAY_STEWARD_ORPHAN_REAP_FLOOR_MS", 60 * 1000);
+// #1761 — the orphan reaper RATE-LIMITS its retries rather than firing once and giving up: a zombie
+// that ignores the graceful shutdown must be retried (escalating to a FORCEFUL kill) on this cadence,
+// then — because the one-per-(repo,host) cap would otherwise let it silently lock the slot forever —
+// surfaced as an operator alarm after STEWARD_REAP_MAX_ATTEMPTS instead of a silent console.warn.
+export const STEWARD_REAP_RETRY_INTERVAL_MS = envNumberOrDefault("AGENT_RELAY_STEWARD_REAP_RETRY_INTERVAL_MS", 2 * 60 * 1000);
+export const STEWARD_REAP_MAX_ATTEMPTS = envNumberOrDefault("AGENT_RELAY_STEWARD_REAP_MAX_ATTEMPTS", 3);
+// #1745 — respawn-rate backstop. A steward that spawns, registers, then dies (e.g. exhausted
+// provider quota) is not a "spawn failure" (it registered), so the policy backoff never engages and
+// the reconcile tick respawns it from `stopped` the moment there is queued work — an unbounded
+// process churn independent of the per-workspace watchdog. Cap actual spawns of one steward policy to
+// STEWARD_SPAWN_RATE_MAX within STEWARD_SPAWN_RATE_WINDOW_MS; further spawns are denied until the
+// window rolls off, so a repeatedly-dying steward can't burn a host or a provider's quota.
+export const STEWARD_SPAWN_RATE_MAX = envNumberOrDefault("AGENT_RELAY_STEWARD_SPAWN_RATE_MAX", 5);
+export const STEWARD_SPAWN_RATE_WINDOW_MS = envNumberOrDefault("AGENT_RELAY_STEWARD_SPAWN_RATE_WINDOW_MS", 10 * 60 * 1000);
+export const STEWARD_CLAIM_TTL_MS = envNumberOrDefault("AGENT_RELAY_WORKSPACE_CLAIM_TTL_MS", 15 * 60_000);
+// #1474 facet 1 — post-land grace. A land CONSUMES the steward's claim, so the moment it finishes
+// the steward loses the claim-bound authorization it needs to report the outcome (what landed) to
+// the coordinator. This bounded window lets the just-landed steward still reach the coordinator for
+// a short time AFTER the land, without granting any standing capability. Kept well under the claim
+// TTL — long enough to file a post-land summary, short enough that it can't be leaned on.
+export const STEWARD_LAND_GRACE_MS = envNumberOrDefault("AGENT_RELAY_STEWARD_LAND_GRACE_MS", 10 * 60_000);
+export const DB_SLOW_QUERY_MS = envNumberOrDefault("AGENT_RELAY_DB_SLOW_MS", 0);
+
+// Reader pool (ADR 0001 §3.2/§3.6/§11.1 — S2.2 #1872). Centralized here so the seam's env access
+// has one home (the env-access ratchet forbids scattered AGENT_RELAY_* reads).
+/** FIXED small default: `min(hardwareConcurrency − 1, 4)`, floored at 1 (§11.1 — dynamic sizing
+ *  oscillates, and each RO connection carries an 8 MB cache + lazy 256 MB mmap). */
+export function defaultReaderPoolSize(): number {
+  const hc = typeof navigator !== "undefined" && navigator.hardwareConcurrency ? navigator.hardwareConcurrency : 2;
+  return Math.max(1, Math.min(hc - 1, 4));
+}
+export const DB_READER_POOL_SIZE = envPositiveInt("AGENT_RELAY_DB_READER_POOL_SIZE", defaultReaderPoolSize());
+/** Backpressure high-water on reader-pool QUEUE depth: past it, reads shed (503-mappable, §3.6). */
+export const DB_READER_QUEUE_HIGH_WATER = envPositiveInt("AGENT_RELAY_DB_READER_QUEUE_HIGH_WATER", 512);
+/** Per-read job timeout: a timed-out reader worker is torn down + respawned (pure reads, no risk). */
+export const DB_READER_JOB_TIMEOUT_MS = envPositiveInt("AGENT_RELAY_DB_READER_JOB_TIMEOUT_MS", 30_000);
+/** Exercise the marshaling seam in the in-process backend under `bun test`/flag (H1 §3.8.1); prod
+ *  `:memory:` bootstrap pays nothing. */
+export const DB_READER_MARSHAL_IN_PROCESS =
+  process.env.NODE_ENV === "test" || relayEnv(process.env, "AGENT_RELAY_DB_MARSHAL") === "1";
+
+/**
+ * Phase-R rollout gate (#1960 T2 — ADR 0001 §7 Phase 1) for the gateway's READER half only. The
+ * writer stays in-process unconditionally: Phase W (a worker writer taking the sole RW connection) is
+ * a separate, much larger burn-down (#1870) and is deliberately NOT wired here. Any value other than
+ * the literal `"worker"` — unset included — resolves to `"in-process"`, so this is behavior-preserving
+ * by default; an operator opts in explicitly per the same string-literal convention as
+ * `parseKernelTimersMode`.
+ */
+export type GatewayReaderBackendMode = "in-process" | "worker";
+
+export function parseGatewayReaderBackend(value: string | undefined): GatewayReaderBackendMode {
+  return value === "worker" ? "worker" : "in-process";
+}
+
+export function gatewayReaderBackendFromEnv(): GatewayReaderBackendMode {
+  return parseGatewayReaderBackend(relayEnv(process.env, "AGENT_RELAY_GATEWAY_READER_BACKEND"));
+}
+
+export function stewardEscalationMs(): number {
+  return envNumberOrDefault("AGENT_RELAY_WORKSPACE_STEWARD_ESCALATION_MS", 60 * 60 * 1000);
+}
+
+export function stewardFallbackTarget(): string {
+  return envTrimmed("AGENT_RELAY_WORKSPACE_STEWARD_FALLBACK");
+}
+
+export function envMsOrDefault(name: string, fallback: number): number {
+  return envNonNegativeNumber(name, fallback);
+}
+
+export function orphanGraceMs(): number {
+  return envMsOrDefault("AGENT_RELAY_ORPHAN_GRACE_MS", 30 * 60 * 1000);
+}
+
+export function orphanReapCooldownMs(): number {
+  return envMsOrDefault("AGENT_RELAY_ORPHAN_REAP_COOLDOWN_MS", 5 * 60 * 1000);
+}
+
+export function orphanReapEnabled(): boolean {
+  return relayEnv(process.env, "AGENT_RELAY_ORPHAN_REAP") !== "0";
+}
+
+export function orphanWorktreeReapEnabled(): boolean {
+  return relayEnv(process.env, "AGENT_RELAY_ORPHAN_WORKTREE_REAP") !== "0";
+}
+
+export const PROVIDER_HOME_GC_INTERVAL_MS = envNumberOrDefault("AGENT_RELAY_PROVIDER_HOME_GC_INTERVAL_MS", 30 * 60 * 1000);
+// #2283 — hourly, was 6h. Hosts mint ~460MB per deployed SHA and fill ~10-15GB/day, so the cadence
+// (times maxDeletes, see scripts/artifact-checkout-gc.ts) is the actual reclaim RATE; four passes a
+// day could not keep up even once the predicate started clearing. The pass is detached and bounded by
+// its own maxScanMs, so the deadline only has to cover that plus the deletes it authorises.
+export const ARTIFACT_CHECKOUT_GC_INTERVAL_MS = envPositiveInt("AGENT_RELAY_ARTIFACT_CHECKOUT_GC_INTERVAL_MS", 60 * 60 * 1000);
+export const ARTIFACT_CHECKOUT_GC_DEADLINE_MS = 300 * 1000;
+export function artifactCheckoutGcEnabled(): boolean { return relayEnv(process.env, "AGENT_RELAY_ARTIFACT_CHECKOUT_GC_ENABLED") !== "0"; }
+
+// #1256 — deliberately well under OFFLINE_PRUNE_MS's 24h default. A provider-home is
+// attributed to an agent via that agent's DB row (instance_id + last_seen); once
+// pruneOfflineAgents deletes the row (at OFFLINE_PRUNE_MS), the home becomes
+// unattributable and this reaper will never touch it again. Firing hours ahead of
+// that deletion is what keeps the sweep able to reclaim disk at all — an operator
+// who shortens OFFLINE_PRUNE_MS should shorten this to stay under it too.
+export function providerHomeGraceMs(): number {
+  return envMsOrDefault("AGENT_RELAY_PROVIDER_HOME_GRACE_MS", 6 * 60 * 60 * 1000);
+}
+
+export function providerHomeGcEnabled(): boolean {
+  return relayEnv(process.env, "AGENT_RELAY_PROVIDER_HOME_GC") !== "0";
+}
+
+// #1256 safety gate — age-based orphan GC remains dormant unless explicitly enabled.
+// The positively-attributed offline-agent reaper is controlled separately by
+// providerHomeGcEnabled() and stays active by default.
+export function providerHomeAgeGcEnabled(): boolean {
+  const value = relayEnv(process.env, "AGENT_RELAY_PROVIDER_HOME_AGE_GC")?.trim().toLowerCase();
+  return value === "1" || value === "true";
+}
+
+// #1256 age-tier — how long a genuinely-orphaned home (no registered agent) whose
+// owner-marker names THIS host must have gone untouched (newest tree mtime) before the
+// reaper age-reaps it. Much longer than providerHomeGraceMs's 6h: that tier acts on a
+// POSITIVE offline attribution, this one on age alone, so it stays deliberately cautious.
+// Gated behind providerHomeAgeGcEnabled(); it is default-off pending the #1256
+// age-tier rearchitecture.
+export function providerHomeOrphanTtlMs(): number {
+  return envMsOrDefault("AGENT_RELAY_PROVIDER_HOME_ORPHAN_TTL_MS", 14 * DAY_MS);
+}
+
+// #1256 quarantine window — the reaper NEVER rm's a home in the same pass it becomes
+// eligible. Pass A atomically renames an eligible orphan to a reclaim-able tombstone; only
+// a LATER pass (Pass B) rm's a tombstone, and only once it has sat quarantined at least
+// this long AND still has no live owner. The window is what lets a reconnecting/resuming
+// agent's spawn-side reclaim recover its home before any destructive rm — so the residual
+// worst case is "a long-dead agent that reconnects in the final delete window gets a
+// freshly-rebuilt empty home", never "a live/reconnecting agent's home deleted out from
+// under it". Default 1h: long enough to cover a spawn/reconnect, short enough to reclaim
+// disk promptly. A tombstone is also always reclaim-able on spawn regardless of this TTL.
+export function providerHomeQuarantineMs(): number {
+  return envMsOrDefault("AGENT_RELAY_PROVIDER_HOME_QUARANTINE_MS", 60 * 60 * 1000);
+}
+
+export function workspaceAutoMergeEnabled(): boolean {
+  return relayEnv(process.env, "AGENT_RELAY_WORKSPACE_AUTO_MERGE") !== "0";
+}
+
+// #1408 K7 Phase-2 timers cutover — the reversible switch that gates whether the kernel-served
+// durable timers path (kernel/timers.pilot.ts firing on the workflow runtime) runs. DEFAULT-OFF
+// (opt-in): unset ⇒ legacy `src/db/scheduled-timers.ts` is the sole timers path, so merely landing
+// this code is a prod no-op. The coordinator flips this to "1" deliberately, after review, to
+// activate the kernel path. Reversible with no data loss: the two paths use disjoint tables
+// (legacy `scheduled_timers` vs kernel-owned `kernel_entity__timers__*` + the workflow journal), so
+// flipping back to legacy leaves legacy state wholly intact. NOTE: enabling it today activates the
+// kernel timers *model* (schedule/cancel/list/fire + `timers.fired`); it is NOT yet a functional
+// replacement for legacy message/command dispatch (that parity bridge is the follow-up cutover step).
+export type KernelTimersMode = "off" | "shadow" | "dual-read" | "kernel";
+
+/** Future durable-protocol desired-mode parser. `1` is permanently the compatibility spelling of
+ * `shadow`; parsing it does not itself confer authority or activate the durable protocol. */
+export function parseKernelTimersMode(value: string | undefined): KernelTimersMode {
+  if (value === "1" || value === "shadow") return "shadow";
+  if (value === "dual-read" || value === "kernel") return value;
+  return "off";
+}
+
+export function kernelTimersMode(): KernelTimersMode {
+  return parseKernelTimersMode(relayEnv(process.env, "AGENT_RELAY_KERNEL_TIMERS"));
+}
+
+export function kernelServedTimersEnabled(): boolean {
+  // Until a durable cutover protocol row/version is activated, preserve the existing switch
+  // semantics exactly: only the historical literal `1` enables today's shadow kernel path.
+  return relayEnv(process.env, "AGENT_RELAY_KERNEL_TIMERS") === "1";
+}
+
+// #3353: delegated token budgets are on by default; AGENT_RELAY_DELEGATION_TOKEN_BUDGETS=0 ignores budget fields.
+export function delegationTokenBudgetsEnabled(): boolean { return relayEnv(process.env, "AGENT_RELAY_DELEGATION_TOKEN_BUDGETS") !== "0"; }
+
+export function childWorkflowsEnabled(): boolean { return relayEnv(process.env, "AGENT_RELAY_CHILD_WORKFLOWS") === "1"; }
+
+export function workflowDecisionsEnabled(): boolean { return relayEnv(process.env, "AGENT_RELAY_WORKFLOW_DECISIONS") === "1"; }
+
+export function workflowCompositionEnabled(): boolean { return relayEnv(process.env, "AGENT_RELAY_WORKFLOW_COMPOSITION") === "1"; }
+
+export function workflowScriptsEnabled(): boolean {
+  return relayEnv(process.env, "AGENT_RELAY_WORKFLOW_SCRIPTS") === "1";
+}
+
+// #1452 — auto-publish an isolated worker's committed-but-unlanded tip to origin's
+// refs/review/* namespace on deliver, so a fresh reviewer can `git fetch` it immediately
+// instead of waiting on a manual author push + coordinator handshake. DEFAULT-OFF (opt-in):
+// unset ⇒ deliverTask publishes nothing and workspace cleanup drops nothing, so merely
+// landing this code is a prod no-op — the review/land/protected-tip flows are untouched. The
+// coordinator flips this to "1" deliberately, after review, to activate publishing. Reversible
+// with no residue: refs/review/* is REVIEW-ONLY (never lands, disjoint from refs/heads/* and
+// the protected-tip guard's refs/agent-relay/workspace-tips/*), and flipping back OFF simply
+// stops publishing — any already-published ref is still dropped on the next workspace reap.
+export function reviewPublishEnabled(): boolean {
+  return relayEnv(process.env, "AGENT_RELAY_REVIEW_PUBLISH") === "1";
+}
+
+export function continuationArchiveFtsEnabled(): boolean {
+  return relayEnv(process.env, "AGENT_RELAY_DISABLE_CONTINUATION_ARCHIVE_FTS") !== "1";
+}
+
+export function busStaleGraceMs(): number {
+  return envNumberOrDefault("AGENT_RELAY_STALE_GRACE_MS", 120_000);
+}
+
+export function defaultIssueRepo(): string | undefined {
+  return relayEnv(process.env, "AGENT_RELAY_DEFAULT_ISSUE_REPO") || process.env.GITHUB_REPOSITORY || undefined;
+}
+
+export function codexWhamQuotaEnabled(): boolean {
+  return relayEnv(process.env, "AGENT_RELAY_CODEX_WHAM_QUOTA") !== "0";
+}
+
+export function cliRelayUrl(): string {
+  return relayEnv(process.env, "AGENT_RELAY_URL") || DEFAULT_RELAY_URL;
+}
+
+/** The runner-provisioned per-session scratch dir of an agent shell. */
+export function cliScratchDir(): string | undefined {
+  return relayEnv(process.env, "AGENT_RELAY_SCRATCH_DIR") || undefined;
+}
+
+export function cliRelayToken(): string | undefined {
+  return resolveCliRelayToken({
+    inline: relayEnv(process.env, "AGENT_RELAY_TOKEN"),
+    launchJti: relayEnv(process.env, "AGENT_RELAY_TOKEN_JTI"),
+    file: relayEnv(process.env, "AGENT_RELAY_TOKEN_FILE"),
+  });
+}
+
+// Mirrors runner/src/config.ts's textEnvOrFile — the orchestrator may set only the
+// _FILE variant instead of the inline env (#1231).
+function textEnvOrFile(name: string): string | undefined {
+  const inline = relayEnv(process.env, name);
+  if (inline) return inline;
+  const file = relayEnv(process.env, `${name}_FILE`);
+  if (!file) return undefined;
+  try {
+    const text = readFileSync(file, "utf8");
+    return text.length > 0 ? text : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+export function workspaceJsonFromEnv(): string | undefined {
+  return textEnvOrFile("AGENT_RELAY_WORKSPACE_JSON");
+}
+
+export function providerSessionIdFromEnv(): string | undefined {
+  return relayEnv(process.env, "AGENT_RELAY_PROVIDER_SESSION_ID");
+}
+
+export function projectFromEnv(): string | undefined {
+  return relayEnv(process.env, "AGENT_RELAY_PROJECT");
+}
+
+export function agentIdFromEnv(): string | undefined {
+  return relayEnv(process.env, "AGENT_RELAY_ID");
+}
+
+export function codexStatePathFromEnv(): string | undefined {
+  return relayEnv(process.env, "AGENT_RELAY_CODEX_STATE_PATH");
+}
+
+export function contextPathFromEnv(): string | undefined {
+  return relayEnv(process.env, "AGENT_RELAY_CONTEXT_PATH");
+}
+
+export function localOrchestratorIdFromEnv(): string | undefined {
+  return envTrimmedOrUndefined("AGENT_RELAY_ORCHESTRATOR_ID");
+}
+
+export function providerConfigHomeFromEnv(): string {
+  return relayEnv(process.env, "AGENT_RELAY_HOME") || join(process.env.HOME || ".", ".agent-relay");
+}
+
+// Base dir all ephemeral full-stack roots live under (RFC 0001 Phase 1 §2). Live
+// read so tests/tools can retarget it; the ephemeral library falls back to a
+// tmpdir path when unset.
+export function ephemeralRootFromEnv(): string | undefined {
+  return relayEnv(process.env, "AGENT_RELAY_EPHEMERAL_ROOT")?.trim() || undefined;
+}
+
+export type IntegrationTokenConfig = {
+  name: string;
+  token: string;
+  scopes: string[];
+  targets?: string[];
+  channels?: string[];
+  callbackUrl?: string;
+  displayName?: string;
+  description?: string;
+  type?: string;
+  icon?: string;
+  accentColor?: string;
+  tags?: string[];
+  homepageUrl?: string;
+  repositoryUrl?: string;
+  docsUrl?: string;
+  manifest?: Record<string, unknown>;
+};
+
+export function getIntegrationTokens(): IntegrationTokenConfig[] {
+  const raw = relayEnv(process.env, "AGENT_RELAY_INTEGRATIONS");
+  if (!raw) return [];
+  try {
+    const parsed = JSON.parse(raw) as unknown;
+    if (!Array.isArray(parsed)) return [];
+    return parsed
+      .filter((item): item is Record<string, unknown> => typeof item === "object" && item !== null)
+      .map((item) => ({
+        name: typeof item.name === "string" ? item.name : "",
+        token: typeof item.token === "string" ? item.token : "",
+        scopes: Array.isArray(item.scopes) ? item.scopes.filter((scope): scope is string => typeof scope === "string") : [],
+        targets: Array.isArray(item.targets) ? item.targets.filter((target): target is string => typeof target === "string") : undefined,
+        channels: Array.isArray(item.channels) ? item.channels.filter((channel): channel is string => typeof channel === "string") : undefined,
+        callbackUrl: typeof item.callbackUrl === "string" ? item.callbackUrl : undefined,
+        displayName: typeof item.displayName === "string" ? item.displayName : undefined,
+        description: typeof item.description === "string" ? item.description : undefined,
+        type: typeof item.type === "string" ? item.type : undefined,
+        icon: typeof item.icon === "string" ? item.icon : undefined,
+        accentColor: typeof item.accentColor === "string" ? item.accentColor : undefined,
+        tags: Array.isArray(item.tags) ? item.tags.filter((tag): tag is string => typeof tag === "string") : undefined,
+        homepageUrl: typeof item.homepageUrl === "string" ? item.homepageUrl : undefined,
+        repositoryUrl: typeof item.repositoryUrl === "string" ? item.repositoryUrl : undefined,
+        docsUrl: typeof item.docsUrl === "string" ? item.docsUrl : undefined,
+        manifest: typeof item.manifest === "object" && item.manifest !== null && !Array.isArray(item.manifest) ? item.manifest as Record<string, unknown> : undefined,
+      }))
+      .filter((item) => item.name && item.token);
+  } catch {
+    return [];
+  }
+}
+
+export function webSearchBackendUrl(backend: "tavily" | "brave"): string {
+  return relayEnv(process.env, `AGENT_RELAY_${backend.toUpperCase()}_SEARCH_URL`) ?? (backend === "tavily" ? "https://api.tavily.com/search" : "https://api.search.brave.com/res/v1/web/search");
+}