feat: optionally stagger periodic usage probes after 5h reset

[LJC-god]

Summary

Related to #488 (partial scheduling support, not a claim that provider-side 5h windows are now desynchronized).

• Add opt-in usage_probe.reset_delay_sec and reset_jitter_sec (each 0–3600 seconds, default 0).
• After a valid Extra 5h reset, defer an already-due periodic probe until reset + delay + stable(account identity, reset) offset. No sleeping worker, per-tick random redraw, new probe, or new mutable scheduler state.
• Preserve official usage backoff, worker bounds/single-flight, legacy default timing, manual /api/panel/probe, event probeNow, and the separate Messages health monitor. Expose pending next_probe_at in the existing usage-probe snapshot.
• Document API/routing configuration and trade-offs; no new UI control.

Trace and scope

server.mjs wires createUsageProbeMonitor to buildProbeOne. buildProbeOne runs the existing official usage/Fable decision path. The normal lookup uses official usage GET, but existing entitlement-recheck conditions can also run Fable Messages. This change only gates entry into that periodic chain after a known Extra 5h reset; it does not alter entitlement-probe conditions or the independent Messages health scheduler.

It does not guarantee distinct upstream window start/reset times. Whether a plain official usage GET starts an upstream window was not verified; real traffic, event/manual probes, and independent Messages health checks may run earlier. Timer granularity and hash collisions can still put several accounts on the same tick. Delaying the quota read also delays panel/recovery freshness. The proposal therefore references, rather than automatically closes, #488.

Example routing patch:

{"usage_probe":{"enabled":true,"reset_delay_sec":120,"reset_jitter_sec":600}}

This sets an earliest eligibility time 120–720 seconds after the Extra 5h reset, still subject to the existing timer/concurrency/backoff. Defaults retain existing behavior.

Validation

Pinned upstream base: 4fe27cfa96408c0504c59830f1788f01dddccdfb.

• RED: identical final regression test against the untouched pinned base: 27 tests, 18 pass / 9 expected assertion failures (missing configuration and deferral behavior).
• GREEN: 8 related test files, 114/114 pass, 0 fail/cancelled/skipped. This is a focused suite, not the full repository suite or live-provider acceptance.
• Fake-clock coverage: zero defaults, bounded config, per-account stable deadlines, restart/list reorder, boundary release, active/Pro paths, official and local backoff, manual/event bypass, post-reset successful sample, 7d/missing/invalid/future resets, config hot update and routing-runtime propagation.
• Biome and git diff --check pass.

node --test --test-concurrency=1 \
  test/unit/usage-probe-reset-delay.test.mjs \
  test/unit/usage-probe-monitor.test.mjs \
  test/unit/crs-usage-probe.test.mjs \
  test/unit/health-probe.test.mjs \
  test/unit/probe-status.test.mjs \
  test/unit/routing-runtime-load.test.mjs \
  test/unit/routing-file.test.mjs \
  test/unit/usage-profile.test.mjs

Tests ran with synthetic HOME/TMPDIR/KIN_HOME inside network/mount namespaces, loopback only and /run//opt masked. No production state, real accounts, paid probes, or deployments were used.

[chatgpt-codex-connector]

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review	Status	Commit	Review trigger
📝 Code Review	✅ Completed 2026-10-17T02:16:01.006804Z	20ec772	PR opened

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.