feat: implement issue #1565 — Auto-pause companion: usage-telemetry adapter + scheduled poller that sets/clears AGENTS_PAUSED from the Claude budget

[don-petry]

Problem

Auto-pause companion: usage-telemetry adapter + scheduled poller that sets/clears AGENTS_PAUSED from the Claude budget

From the issue: As the maintainer of the agent fleet, I want a scheduled job that reads the Claude subscription usage windows and flips AGENTS_PAUSED on and off automatically, so that budget conservation stops being a manual act of noticing pressure and withholding a secret — the failure that produced the 2026-08-16→18 opaque fleet outage (#1525).

Risk

Medium — changes GitHub Actions workflow behavior, which is exercised only post-merge; verify via the affected workflow runs.

Test plan

Tests added/updated: tests/dev-lead/integration/test_usage_telemetry_roundtrip.bats,tests/dev-lead/unit/test_usage_telemetry.bats tests/fixtures/agent-rate-limit/README.md,tests/fixtures/agent-rate-limit/agent-rate-limit.sh tests/fixtures/agent-rate-limit/agent-rate-limits.armed.json,tests/fixtures/agent-rate-limit/agent-rate-limits.json. Verification: bash scripts/dev-lead-lint.sh (shellcheck --severity=warning) ran pre-commit; the bats suite runs in CI.

Rollback

Revert this PR. No non-revertible side effects (no tags, migrations, or external state).

Monitoring

Watch the affected workflow run(s) in the Actions tab and this PR's Lint check for regressions.

Refs the #1565 story (adapter slice only; poller, auto-resume and notification remain open, so the issue must stay open on merge)

[chatgpt-codex-connector]

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.

[qodo-code-review]

ⓘ Qodo reviews are paused because your trial has ended. Ask your workspace admin to add credits to resume reviews. Manage billing

[coderabbitai]

Warning

Review limit reached

You've used all free OSS reviews for now. Wait for the free limit to reset to keep reviewing this public repository.

Next included review available in 40 minutes.

Check out review usage here.

View limit details

Limit details: You’ve used the included review currently available.

Learn how review limits work.

Review configuration:

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Advanced

Run ID: 98a30aad-6a0e-4248-a86d-c9f57b99302f

📥 Commits

Reviewing files that changed from the base of the PR and between bb0dd94 and c867941.

📒 Files selected for processing (9)

• .github/workflows/lint.yml
• AGENTS.md
• scripts/lib/usage-telemetry.sh
• tests/dev-lead/integration/test_usage_telemetry_roundtrip.bats
• tests/dev-lead/unit/test_usage_telemetry.bats
• tests/fixtures/agent-rate-limit/README.md
• tests/fixtures/agent-rate-limit/agent-rate-limit.sh
• tests/fixtures/agent-rate-limit/agent-rate-limits.armed.json
• tests/fixtures/agent-rate-limit/agent-rate-limits.json

• Autopilot · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Autopilot is currently an internal CodeRabbit preview.

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[don-petry]

Dev-Lead — waiting on PR blockers (intent: review-changes)

PR: #1888
No changes were committed, but the PR still can't be marked done: required checks SonarCloud, agent-shield / AgentShield, dependency-audit / Detect ecosystems are still pending. The retry cron will re-attempt automatically. Next attempt after: 2026-09-22T17:48:52Z

[don-petry]

Note

@don-petry I reviewed this PR and no code changes were needed, but I can't mark it done yet: required checks SonarCloud, agent-shield / AgentShield, dependency-audit / Detect ecosystems are still pending. I'll re-check automatically.
Next attempt after: 2026-09-22T17:48:52Z

[gemini-code-assist]

Code Review

This pull request introduces a private transport adapter for the Claude subscription OAuth usage endpoint in scripts/lib/usage-telemetry.sh to support automatic budget pausing, along with comprehensive unit and integration tests. The review feedback highlights opportunities to improve script portability and robustness, specifically by adding error handling to mktemp calls, removing non-portable suffixes from temporary file templates, and replacing GNU-specific date commands in tests with hardcoded epoch integers.

[don-petry]

No description provided.

[donpetry-bot]

Advisory bots were rate-limited; auto-approval is withheld until they recover. pr-review-sweep will re-review this PR after 2026-09-22T18:20:25Z.

[donpetry-bot]

Advisory bots were rate-limited; auto-approval is withheld until they recover. pr-review-sweep will re-review this PR after 2026-09-22T18:29:55Z.

[don-petry]

Dev-Lead — fix-bot-comment (no-changes)

Agent reasoning

Issues addressed: 0
- Quality Gate passed: not actionable (neutral status report)
- template-drift CI failure: non-required check per AGENTS.md; does not block merge
- Gemini Code Assist advisory: advisory feedback, not required
Files changed: none
Skipped (informational/non-blocking): 3
```
No changes are needed to this PR.

[don-petry]

Resolved — the `needs-human-review` hold was lifted; dev-lead has picked this item up. Click to expand the prior hold notice.

dev-lead is withholding action on this item.

It is labeled needs-human-review (flagged for human review — this label is applied by automation as well as by people, so an item can become held without anyone noticing), so dev-lead will not pick it up while that label is present. This notice is posted once so the withhold is visible rather than looking like a stalled run.

To re-enable automated pickup: remove the needs-human-review label.

[donpetry-bot]

Advisory bots were rate-limited; auto-approval is withheld until they recover. pr-review-sweep will re-review this PR after 2026-09-22T18:47:12Z.

[donpetry-bot]

Superseded by automated re-review at 42e89facb840a356468e6d0f58ed9a48ad4c1ccb — click to expand prior review.

Review — fix requested (cycle 1/3)

The automated review identified the following issues. Please address each one:

Findings to fix

Automated review — NEEDS HUMAN REVIEW

Risk: MEDIUM
Reviewed commit: e3a60d33f6ac1b6f9a7c222a8957d3c639b85319
Cascade: triage → audit (triage: haiku 4.5 [sonnet 5] → deep: opus 4.8 [sonnet 5] + duck: o4-mini → audit: fable 5)

Summary

Security audit found no exploitable path: the OAuth token is never logged, jq assembly is injection-safe, the 1266-line pinned fixture was verified byte-identical against petry-projects/.github @ b16e764a (armed variant differs only by the documented weekly_all.enabled flip), no owner-locked paths are touched, and the library is not wired into any live workflow in this PR. However the deep review's confirmed major stands: mktemp failure in usage_telemetry_fetch/usage_telemetry_publish_file aborts a set -e caller before the degraded envelope is emitted, violating the library's own documented never-fail contract — flagged by CodeAnt, Gemini, and both prior tiers and still unfixed at head e3a60d3. Escalating for that fix (cycle 0 of 3); the deep review's ci_red_gate reason is refuted — template-drift is not a required check (branch rules list only SonarCloud/CodeQL/AgentShield/dependency-audit/duplicate-decl-gate, all green; AGENTS.md line 206 documents that non-required template-drift failures do not block).

Findings

• major (correctness/error-handling) scripts/lib/usage-telemetry.sh:152 — hdrfile="$(mktemp ...)" in usage_telemetry_fetch and file="$(mktemp ...)" in usage_telemetry_publish_file abort a set -e caller on mktemp failure before any degraded envelope is emitted, violating the documented 'never fails hard' contract. The auto-pause poller would crash instead of failing open. Guard both assignments (e.g. || { usage_telemetry_log ...; usage_telemetry_envelope 0 "" "$now" ""; return 0; }).
• minor (security/credential-exposure) scripts/lib/usage-telemetry.sh:161 — The OAuth bearer is passed in curl argv (-H "Authorization: Bearer ..."), visible in /proc//cmdline for the call's lifetime (CWE-214). On ephemeral single-tenant Actions runners everything in the job already shares the trust boundary with the env var itself, so this does not cross a trust boundary — downgraded from the deep review's major. Recommended hardening: pass the header via a curl config file or -H @file so the secret never lands in argv.
• minor (correctness/api-mismatch) scripts/lib/usage-telemetry.sh:103 — usage_telemetry_retry_after accepts only ^[0-9]+$, so an RFC 7231 HTTP-date Retry-After on a genuine 429 is discarded and the gate fails open instead of deferring. Low likelihood (Anthropic returns integer seconds) and the fail direction matches the documented fail-safe.
• minor (correctness/race) scripts/lib/usage-telemetry.sh:195 — usage_telemetry_publish_file truncate-then-writes the envelope non-atomically; a concurrent reader of AGENT_TOKEN_BUDGET_TELEMETRY_FILE can parse partial JSON and fail open during the exact budget-pause window. Write to a temp file and mv into place.
• info (supply-chain/verified) tests/fixtures/agent-rate-limit/agent-rate-limit.sh — Pinned fixture provenance VERIFIED: tests/fixtures/agent-rate-limit/agent-rate-limit.sh and agent-rate-limits.json are byte-identical to petry-projects/.github @ b16e764a4bd52c7dd3baef3212f072aa58aeff97; agent-rate-limits.armed.json differs only by weekly_all.enabled=true exactly as its README documents. No hidden modifications in the 1266-line vendored script.
• info (ci/gate) .github/workflows/agent-shield.yml — template-drift is red but NOT required: main's branch rules require only SonarCloud, CodeQL, agent-shield/AgentShield, dependency-audit/Detect ecosystems, and duplicate-decl-gate — all SUCCESS. AGENTS.md (line 206, pr-review CI gate counts non-required failing checks — a red dev-lead/dispatch blocks the review that would approve the PR (circular) #1549) documents that non-required template-drift failures do not halt review. The drift is pre-existing repo state (agent-shield.yml/dependency-audit.yml), untouched by this PR; re-seed separately.

---

Reviewed by the PR-review cascade (triage: haiku 4.5 [sonnet 5] → deep: opus 4.8 [sonnet 5] + duck: o4-mini → audit: fable 5). Reply if you need a human review.

Additional tasks

1. Resolve all unresolved review thread comments from other reviewers
2. Ensure all CI checks pass after your changes
3. Rebase on the target branch if behind
4. Do NOT modify files unrelated to the findings above

The review cascade will automatically re-review after new commits are pushed.

[donpetry-bot]

Advisory bots were rate-limited; auto-approval is withheld until they recover. pr-review-sweep will re-review this PR after 2026-09-23T01:48:14Z.

[donpetry-bot]

Advisory bots were rate-limited; auto-approval is withheld until they recover. pr-review-sweep will re-review this PR after 2026-09-23T02:17:29Z.

[don-petry]

Dev-Lead — fix-bot-comment (no-changes)

Agent reasoning

Bot: sonarqubecloud[bot]
Status: Clean-status re-post (Quality Gate passed)
Pattern match: Full SonarCloud clean pattern matched
  - Quality Gate Passed ✓
  - 0 New issues ✓
  - 0 Security Hotspots ✓
Action taken: None (auto-cleared by maintainer-comment gate)
No code changes required
No PR reply posted
```

[cubic-dev-ai]

All reported issues were addressed across 9 files

<sub>Reply with feedback, questions, or to request a fix.

Re-trigger cubic</sub>

[don-petry]

Dev-Lead — fix-reviews (partial)

A commit was pushed, but not every requested change was applied. Per requested item:

• tests/dev-lead/unit/test_usage_telemetry.bats:128 — not applied
• AGENTS.md:650 — applied
• tests/fixtures/agent-rate-limit/agent-rate-limit.sh:894 — not applied
• tests/fixtures/agent-rate-limit/agent-rate-limits.armed.json:68 — not applied
• scripts/lib/usage-telemetry.sh:199 — applied

The unaddressed items above still need work.

[donpetry-bot]

Advisory bots were rate-limited; auto-approval is withheld until they recover. pr-review-sweep will re-review this PR after 2026-10-02T14:20:49Z.

[donpetry-bot]

Advisory bots were rate-limited; auto-approval is withheld until they recover. pr-review-sweep will re-review this PR after 2026-10-02T14:20:52Z.

[don-petry]

Resolved — the `needs-human-review` hold was lifted; dev-lead has picked this item up. Click to expand the prior hold notice.

dev-lead is withholding action on this item.

It is labeled needs-human-review (flagged for human review — this label is applied by automation as well as by people, so an item can become held without anyone noticing), so dev-lead will not pick it up while that label is present. This notice is posted once so the withhold is visible rather than looking like a stalled run.

To re-enable automated pickup: remove the needs-human-review label.

[don-petry]

Test failure: see inline.

[don-petry]

Dev-Lead — fix-reviews (applied)

Changes committed and pushed. Requested items addressed:

• tests/dev-lead/unit/test_usage_telemetry.bats:86 — applied

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

[donpetry-bot]

Advisory bots were rate-limited; auto-approval is withheld until they recover. pr-review-sweep will re-review this PR after 2026-10-02T18:31:40Z.