[ranxianglei]

Related to #5164 (stopgap / option-B content). Direction + default threshold remain an owner decision in #5262 — if A lands, this PR is its diagnostic foundation (acceptance ②④); if C, reject this PR.

What changed

The first-byte watchdog (armFirstByteWatchdog, src/server/relay.ts) deduped warns with a process-lifetime Set per origin: each origin could ever warn once, claimed at fire time. In #5139 Phase 2 that meant the first post-wedge late fire burned ccproxy's single quota and every later stalled turn of the mega-session went completely silent — zero log lines explaining why turns were held ~300s.

Warns are now throttled per (origin, session) with a cooldown (FIRST_BYTE_WARN_COOLDOWN_MS = 60_000, code constant + test seam, no new config surface):

• every affected turn gets its own log line when stalls are ≥60s apart (realistic turn cadence; host timeout-retry cycles are minutes apart);
• cross-session suppression is gone — one session's stall no longer silences another session on the same upstream;
• Silent upstream stall is invisible in logs: no 'awaiting first byte' warning between forward POST and client disconnect #3434's anti-spam intent survives: a pathological fast stall loop on one origin+session logs at most one line per window;
• there is no permanent quota anymore, so post-wedge quota pre-consumption ([Bug] Stalled upstream before first response byte holds the client silently up to 12 min and burns host retries — first-byte watchdog is warn-only and deduped per origin #5164 acceptance ④) is structurally impossible — the decision is fire-time vs last-warn-time on a decaying timestamp;
• the warn line now carries the ACTUAL pending duration (pending Ns) — under a post-wedge late fire that far exceeds the nominal 30s threshold and is exactly the number triage needs (incident turns were held ~300s while the line said "≥30s").

Behavior change disclosure (old → new)

First-byte stall warn cadence: once per origin per process lifetime → at most once per (origin, session) per 60s. Log volume can increase for origins with repeated stalls (bounded by the cooldown). Client-visible behavior UNCHANGED — diagnostic only: no abort, no new failure path, no config surface (the fail-fast variant stays owner-gated in #5262).

Gate tests (#3617 both directions)

• stall < threshold → no warn, no abort (kept);
• stall > threshold → warn with session/lane/target + actual pending seconds (kept + extended);
• same origin+session, stalls beyond cooldown apart → second warn fires (new positive — regression pin for quota burnout, acceptance ②④);
• same origin+session within cooldown → suppressed (new negative — anti-spam);
• different sessions, same origin → both warn (new positive; old code disarmed the second at arm time);
• different origins → both warn (kept); client-abort / pre-aborted signal / disabled threshold → no warn (kept); state-reset seam re-enabled (renamed _resetFirstByteWarnStateForTest).

Acceptance ③ (healthy long streams crossing the threshold survive) is untouched: this change touches neither fetchWithTimeout's idle re-arm nor any response path — covered by the existing fetch-util/relay suites.

Modes reasoned

Plugin mode and proxy mode both funnel through the single forward chokepoint (the watchdog arms around the initial upstream fetch at relay.ts regardless of lane — lane ∈ main/side/passthrough); the change is lane-agnostic logging only.

kernel: none · pi-subagents: none · config surface: none (constant + test seam, matching how the existing threshold is treated)

[github-actions]

📦 Built Package Artifact

Branch: 2026-10-31_first-byte-warn-cooldown (604f38a)

Latest build — install this exact version

npm install -g billion-context@0.0.7309-pr.5260.842ebc4

This exact version is immutable and reproducible. The rolling pr tag tracks the newest test build across all PRs.

Recent builds (commit → version)

commit	version	build
604f38a	billion-context@0.0.7309-pr.5260.842ebc4	build
b8a4475	billion-context@0.0.7252-pr.5260.df71d5c	build
414e291	billion-context@0.0.7204-pr.5260.74ac75b	build

Download artifact

1. Download the artifact from the Actions run
2. Extract the tarball and install:

tar xzf billion-context-pr5260.tgz
npm install -g package

---

Install instructions are refreshed on each push.