Problem
rate-limit-guard's entire observability chain is machine-local and statusline-driven: statusline refresh → shim → tee → ~/.claude/rate-limit-guard/rate-limits.json, which consumers read per reference/reader-contract.md. Cloud/remote execution environments (Claude Code on the web / remote-session containers) have no statusline wiring and an ephemeral filesystem, so the snapshot never exists there.
Verified empirically in a live cloud session (2026-08-15): ~/.claude/rate-limit-guard/ is absent in the container. Under the reader contract's fail-open capability detection, that reads as unknown → consumers correctly refuse to throttle on fabricated data and degrade to reactive-only.
Why it matters
- Orchestration-heavy work (subagent fan-outs, loop lanes launched from cloud) is exactly where proactive pause-before-the-limit matters most, and cloud is increasingly where that work runs. Today a cloud session's only honest option is a fixed conservative concurrency cap chosen blind — it cannot dynamically scale worker count to actual window state. This surfaced concretely while sizing a deliberately low-concurrency remediation fan-out for
/docs-hygiene:audit-encapsulation.
- The subscription windows are account-scoped and shared across the operator's local machines and cloud sessions. A blind cloud session doesn't just risk its own turn failing — it can silently drain the same windows that locally-running lanes are pacing themselves against, defeating the guard's purpose machine-wide even where it is wired.
Scope of this issue
Problem statement only — deliberately. The solution shape is undecided and needs its own planning pass (interview → exploration → brainstorming → design) before any implementation. Open questions that pass would need to settle, without presupposing answers here: where cloud telemetry could even come from (harness/API exposure, a synced snapshot, something else entirely), whether the machine-scope contract path generalizes to an account-scope contract, and how this interacts with the single-account assumption already tracked in #1218.
Not agent-ready; requires human-in-the-loop design decisions.
Problem
rate-limit-guard's entire observability chain is machine-local and statusline-driven: statusline refresh → shim → tee →~/.claude/rate-limit-guard/rate-limits.json, which consumers read perreference/reader-contract.md. Cloud/remote execution environments (Claude Code on the web / remote-session containers) have no statusline wiring and an ephemeral filesystem, so the snapshot never exists there.Verified empirically in a live cloud session (2026-08-15):
~/.claude/rate-limit-guard/is absent in the container. Under the reader contract's fail-open capability detection, that reads as unknown → consumers correctly refuse to throttle on fabricated data and degrade to reactive-only.Why it matters
/docs-hygiene:audit-encapsulation.Scope of this issue
Problem statement only — deliberately. The solution shape is undecided and needs its own planning pass (interview → exploration → brainstorming → design) before any implementation. Open questions that pass would need to settle, without presupposing answers here: where cloud telemetry could even come from (harness/API exposure, a synced snapshot, something else entirely), whether the machine-scope contract path generalizes to an account-scope contract, and how this interacts with the single-account assumption already tracked in #1218.
Not agent-ready; requires human-in-the-loop design decisions.