feat: add codexbar guard — quota-aware exit code to gate automation

[OfficialAbhinavSingh]

Implements the proposal in #2235. Opening it with the code + proof rather than waiting, since it's small and self-contained — happy to iterate on the flag shape or close it if the direction isn't wanted.

Summary

Adds codexbar guard — a quota-aware exit code that turns CodexBar from a passive display into a guardrail scripts and agent loops can gate on.

codexbar guard --provider <id> [--need <percent>] [--window session|weekly] [--json] [--fail-open]

• Exit 0 = safe (relevant window has ≥ --need% remaining), 1 = insufficient headroom, 2 = unknown/unreachable.
• --need defaults to 10. --window defaults to session (primary window); weekly checks the secondary.
• --fail-open exits 0 instead of 2 when quota is unknown.

# don't start the next agent iteration if you can't finish it
while codexbar guard --provider claude --need 15; do run-agent-iteration; done
# gate a long task
codexbar guard --provider codex --need 30 && ./long-task.sh

Design

• The gating decision is a pure function, evaluateGuard(remainingPercent:needPercent:failOpen:), kept free of I/O so it's unit-testable off-network.
• The fetch reuses the existing single-provider pipeline (ProviderFetchContext → fetchProviderUsage), run under .background interaction (no Keychain prompts), exactly like usage.
• No new UI, no changes to existing behavior — purely additive.

Tests

TestsLinux/CLIGuardDecisionTests.swift — 5 deterministic cases: ample→ok/0, insufficient→blocked/1, unknown→2, unknown+fail-open→0, boundary (remaining == need)→ok/0.

Verification (Linux, swift:6.3.3)

$ swift build --product CodexBarCLI
Build of product 'CodexBarCLI' complete! (29.63s)

$ swift test --filter CLIGuardDecision
✔ Test run with 5 tests in 1 suite passed after 0.001 seconds.

$ codexbar guard --provider claude --need 10 --fail-open
claude session: unknown — UNKNOWN (need 10%)          # exit 0
$ codexbar guard --provider claude --need 10
claude session: unknown — UNKNOWN (need 10%)          # exit 2
$ codexbar guard --provider claude --need 10 --json --fail-open
{"exitCode":0,"window":"session","needPercent":10,"provider":"claude","decision":"unknown"}   # exit 0

Built and tested on Linux (swift:6.3.3); the macOS CI job validates the cross-platform build.

---

Review feedback addressed (clawsweeper, commit 4d06f796)

Both P2 findings fixed:

1. Account resolution (CLIGuardCommand.swift) — guard now resolves the configured token account via resolvedAccounts(for:).first and threads it through the fetch (env/settings/source/context), matching usage. Token-only Claude/z.ai/OpenAI configs now return a real decision instead of unknown.
2. Synthetic-window filtering — window selection goes through a pure guardRemainingHeadroom(for:) that returns nil for a nil or isSyntheticPlaceholder window, so a phantom primary (e.g. Claude with no live 5-hour session) is treated as unknown rather than a false 100%-available exit 0.

Added 4 regression tests for the window-headroom path (real / synthetic / absent / fully-used) — 9 guard tests total. Verified in swift:6.3.3: swiftlint --strict 0 violations, swiftformat --lint clean, CodexBarCLI builds, 9/9 tests pass.

Still open for the maintainer (not contributor-fixable): (a) real known-quota terminal proof of safe/blocked from a configured account, and (b) product sign-off on the public flag/exit-code contract.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: d2781f1d53

ℹ️ 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".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

Resolve token accounts before fetching guard usage

When the selected provider is configured only through CodexBar token accounts (for example Claude stored session/OAuth credentials or Zai/OpenAI API-key accounts), this nil account means ProviderEnvironmentResolver never injects the active account token, while runUsage first calls resolvedAccounts and passes that account into the same environment/settings path. In that common configuration codexbar guard --provider <id> reports unknown/exit 2 (or fail-opens) even though codexbar usage can fetch the quota, so the automation gate is unreliable for stored-account users.

Useful? React with 👍 / 👎.

[chatgpt-codex-connector]

Ignore synthetic session placeholders in guard decisions

For Claude web accounts with five_hour: null, the core fetcher intentionally emits primary as a synthetic 0%-used placeholder (isSyntheticPlaceholder) so UI metrics drop it and use the real weekly lane instead. This guard path treats that placeholder as a real session window and returns 100% remaining, so the default codexbar guard --provider claude can exit 0 for weekly-only or exhausted accounts because the phantom session lane passes the headroom check.

Useful? React with 👍 / 👎.

[clawsweeper]

Codex review: needs real behavior proof before merge. Reviewed July 17, 2026, 3:37 PM ET / 19:37 UTC.

Summary
Adds a codexbar guard CLI subcommand with provider quota thresholds, stable exit codes, JSON/text output, timeout handling, tests, and CLI documentation.

Reproducibility: yes. for the timeout defect: source inspection identifies Claude auto mode where a web attempt can consume the same deadline reserved for the outer guard race, preventing the CLI fallback. Real quota proof remains incomplete because the supplied terminal run has no configured account.

Review metrics: 2 noteworthy metrics.

• CLI surface: 1 new subcommand, 7 supporting files changed. The PR introduces a public automation contract rather than an internal-only helper.
• Patch size: 651 added, 13 removed across 9 files. The implementation is broader than the pure decision function and includes dispatch, help, docs, and tests.

Root-cause cluster
Relationship: fixed_by_candidate
Canonical: #2235
Summary: This PR is the implementation candidate for the open feature proposal; the proposal should remain open until a reviewed, proven implementation merges.

Members:

• canonical: Feature proposal: codexbar guard — a quota-aware exit code to gate automation #2235 - The PR body and timeline explicitly identify the open issue as the feature proposal this branch implements.

Proposal only: this assessment does not dispatch repair, suppress jobs, mutate sibling items, close, or merge anything.

Merge readiness
Overall: 🦐 gold shrimp
Proof: 🦐 gold shrimp
Patch quality: 🦐 gold shrimp
Result: blocked until stronger real behavior proof is added.

Overall follows the weaker of proof and patch quality, so missing proof can cap an otherwise strong patch.

Rank-up moves:

• [P2] Repair the timeout budgeting so provider fallbacks remain reachable.
• [P2] Add a focused fallback-after-web-timeout regression test.
• [P1] Post redacted configured-account terminal output for both safe and blocked results, then update the PR body for re-review.

Proof guidance:

• [P1] Needs stronger real behavior proof before merge: The contributor supplied terminal proof for unavailable and fail-open paths plus unit and CI results, but needs redacted configured-account output proving the after-fix safe and blocked decisions before merge. After adding proof, update the PR body; ClawSweeper should re-review automatically. If it does not, the PR author or someone with repository write access can comment @clawsweeper re-review.

Risk before merge

• [P2] For Claude auto mode, the guard-level timeout can consume the entire budget during the web attempt and prevent the existing CLI fallback, returning exit 69 even when quota is available.
• [P1] The stable exit-code contract will be consumed by automation, so the provider/window semantics need an explicit supported boundary before the feature is treated as durable.
• [P1] The provided runtime evidence does not yet show a configured account reaching both safe and blocked guard outcomes.

Maintainer options:

1. Preserve fallback time for guard fetches (recommended)
   Give the web strategy a smaller timeout than the overall guard deadline and add a test proving a timed-out web step can still reach the Claude CLI fallback.
2. Accept unavailable results on slow web attempts
   Merge with the current behavior only if maintainers accept that automation may receive exit 69 despite a usable provider fallback.

Next step before merge

• [P2] A maintainer must confirm the public automation contract and require contributor-supplied configured-account proof; the remaining timeout repair is concrete but should be reviewed within that product boundary.

Maintainer decision needed

• Question: Should CodexBar support guard as a stable public automation contract, including its provider/window naming and documented exit-code semantics?
• Rationale: This is a new CLI capability whose exit statuses will become script dependencies; the implementation can be repaired mechanically, but the durable scope and compatibility promise need maintainer intent.
• Likely owner: steipete — Recent direct commits on the PR cover the guard contract and credential behavior.
• Options:
  • Sponsor the narrow guard contract (recommended): Keep the documented single-provider threshold and primary/secondary-window scope, then require the fallback repair and real configured-account proof before merge.
  • Narrow or defer the public API: Reduce the supported provider/window semantics or close the feature direction before a stable automation contract is published.

Security
Cleared: The diff adds no dependencies, workflow changes, secret exposure, or new credential writes; the latest branch commit explicitly keeps guard credential checks read-only.

Review findings

• [P2] Reserve timeout budget for fallback strategies — Sources/CodexBarCLI/CLIGuardCommand.swift:252

Review details

Best possible solution:

Reserve part of the guard deadline for provider fallbacks, add a regression test for a timed-out web attempt followed by a successful CLI fallback, then land only after redacted configured-account proof shows safe and blocked decisions under the maintainer-approved CLI contract.

Do we have a high-confidence way to reproduce the issue?

Yes, for the timeout defect: source inspection identifies Claude auto mode where a web attempt can consume the same deadline reserved for the outer guard race, preventing the CLI fallback. Real quota proof remains incomplete because the supplied terminal run has no configured account.

Is this the best way to solve the issue?

No, not yet: the command's additive structure is reasonable, but it must reserve fallback time and receive maintainer agreement on the stable automation contract before it is the best durable solution.

Full review comments:

• [P2] Reserve timeout budget for fallback strategies — Sources/CodexBarCLI/CLIGuardCommand.swift:252
  The Claude auto fetch plan can spend context.webTimeout on its web attempt, but this value matches the outer guard deadline. A slow web attempt can therefore cause the outer race to return timeout and cancel before the supported CLI fallback runs, producing exit 69 even though quota is available. Use a smaller per-web budget or otherwise reserve time for fallbacks, with a regression test.
  Confidence: 0.93

Overall correctness: patch is incorrect
Overall confidence: 0.9

AGENTS.md: found and applied where relevant.

Codex review notes: model internal, reasoning high; reviewed against cfb7b8036087.

Label changes

Label changes:

• add rating: 🦐 gold shrimp: Overall readiness is 🦐 gold shrimp; proof is 🦐 gold shrimp and patch quality is 🦐 gold shrimp.
• remove rating: 🦪 silver shellfish: Current PR rating is rating: 🦐 gold shrimp, so this older rating label is no longer current.

Label justifications:

• P2: The fallback-timeout defect can make the new automation gate report unavailable for a supported provider path, but it has bounded blast radius and a focused repair.
• merge-risk: 🚨 automation: Scripts may treat exit 69 as a stop condition, so an unnecessary unavailable result can interrupt automated workflows.
• rating: 🦐 gold shrimp: Overall readiness is 🦐 gold shrimp; proof is 🦐 gold shrimp and patch quality is 🦐 gold shrimp.
• status: 📣 needs proof: The PR needs real behavior proof before ClawSweeper can clear the contributor ask. Needs stronger real behavior proof before merge: The contributor supplied terminal proof for unavailable and fail-open paths plus unit and CI results, but needs redacted configured-account output proving the after-fix safe and blocked decisions before merge. After adding proof, update the PR body; ClawSweeper should re-review automatically. If it does not, the PR author or someone with repository write access can comment @clawsweeper re-review.

Evidence reviewed

What I checked:

• New feature remains absent from current main: Current main's CLI usage path fetches and renders provider usage, while this PR introduces the distinct script-gating command and its exit-code contract; the central requested capability is therefore not already implemented on main. (Sources/CodexBarCLI/CLIUsageCommand.swift:1, cfb7b8036087)
• Guard implementation and public contract: The PR adds the guard decision/fetch implementation, documents exit codes 0, 1, 64, and 69, and adds focused decision tests. (Sources/CodexBarCLI/CLIGuardCommand.swift:1, 7c452fabadac)
• Fallback timeout defect remains actionable: The latest review identifies that the outer guard deadline and Claude's web-attempt timeout share the same budget, so a slow web attempt can cancel the CLI fallback and produce unavailable even when quota can be fetched through the supported fallback. (Sources/CodexBarCLI/CLIGuardCommand.swift:252, 7c452fabadac)
• Only partial real-behavior proof is present: The contributor's terminal transcript shows the built CLI returning unavailable and fail-open results in an unconfigured environment; tests cover the pure decision branches, but there is no redacted configured-account run demonstrating both safe and blocked outcomes. (TestsLinux/CLIGuardDecisionTests.swift:1, 7c452fabadac)
• Recent feature stewardship: PR history shows steipete directly authored the latest contract-hardening and read-only credential-check commits, making them the strongest routing candidate for the final public CLI contract and provider behavior. (Sources/CodexBarCLI/CLIGuardCommand.swift:1, 7c452fabadac)

Likely related people:

• steipete: Authored the latest fix: harden guard automation contract and fix: keep guard credential checks read-only commits on this PR, directly covering its public contract and credential-interaction behavior. (role: recent area contributor; confidence: high; commits: d8c282bbbaff, 7c452fabadac; files: Sources/CodexBarCLI/CLIGuardCommand.swift, Sources/CodexBarCLI/CLIHelp.swift, docs/cli.md)

What the crustacean ranks mean

• 🦀 challenger crab: rare, exceptional readiness with strong proof, clean implementation, and convincing validation.
• 🦞 diamond lobster: very strong readiness with only minor maintainer review expected.
• 🐚 platinum hermit: good normal PR, likely mergeable with ordinary maintainer review.
• 🦐 gold shrimp: useful signal, but proof or patch confidence is still limited.
• 🦪 silver shellfish: thin signal; proof, validation, or implementation needs work.
• 🧂 unranked krab: not merge-ready because proof is missing/unusable or there are serious correctness or safety concerns.
• 🌊 off-meta tidepool: rating does not apply to this item.

Shiny media proof means a screenshot, video, or linked artifact directly shows the changed behavior. Runtime, network, CSP, and security claims still need visible diagnostics.

How this review workflow works

• ClawSweeper keeps one durable marker-backed review comment per issue or PR.
• Re-runs edit this comment so the latest verdict, findings, and automation markers stay together instead of adding duplicate bot comments.
• A fresh review can be triggered by eligible @clawsweeper re-review comments, exact-item GitHub events, scheduled/background review runs, or manual workflow dispatch.
• PR/issue authors and users with repository write access can comment @clawsweeper re-review or @clawsweeper re-run on an open PR or issue to request a fresh review only.
• Maintainers can also comment @clawsweeper review to request a fresh review only.
• Fresh-review commands do not start repair, autofix, rebase, CI repair, or automerge.
• Maintainer-only repair and merge flows require explicit commands such as @clawsweeper autofix, @clawsweeper automerge, @clawsweeper fix ci, or @clawsweeper address review.
• Maintainers can comment @clawsweeper explain to ask for more context, or @clawsweeper stop to stop active automation.

Review history (6 earlier review cycles)

• reviewed 2026-07-16T21:50:04.768Z sha 3ca9952 :: needs real behavior proof before merge. :: [P2] Resolve the selected token account before fetching | [P1] Reject synthetic windows before declaring quota safe
• reviewed 2026-07-16T23:50:00.971Z sha 3ca9952 :: needs real behavior proof before merge. :: [P2] Resolve configured accounts before fetching guard usage | [P2] Exclude synthetic primary windows from guard decisions
• reviewed 2026-07-17T04:19:27.432Z sha 4d06f79 :: needs real behavior proof before merge. :: [P1] Validate provider lanes before calling them session and weekly | [P3] Document the new automation contract
• reviewed 2026-07-17T07:27:50.533Z sha 86b3fd1 :: needs real behavior proof before merge. :: [P1] Validate provider lanes before naming them session and weekly | [P3] Document the new automation contract
• reviewed 2026-07-17T08:09:27.837Z sha 86b3fd1 :: needs real behavior proof before merge. :: [P1] Validate provider lanes before naming them session and weekly | [P3] Document the new automation contract
• reviewed 2026-07-17T09:19:15.478Z sha 86b3fd1 :: needs real behavior proof before merge. :: [P1] Validate provider lanes before naming them session and weekly | [P3] Document the new automation contract

[OfficialAbhinavSingh]

Proof (for status: needs proof)

guard is a pure decision function plus CLI wiring, so it's verifiable end-to-end without a signed runtime.

1. Native macOS CI — green. Both swift-test-macos shards pass on the current head, guard suite included.

2. Decision logic — 9/9 unit tests (CLIGuardDecisionTests), covering every branch:

• ample headroom → ok (exit 0); remaining exactly == need → ok (exit 0)
• insufficient / fully-used → blocked (exit 1)
• unknown → exit 2 (default), exit 0 (--fail-open)
• synthetic-placeholder window & absent window → treated as unknown

3. Built release binary — exit-code contract (release CodexBarCLI):

$ codexbar guard --provider claude --need 5
claude session: unknown — UNKNOWN (need 5%)
exit=2

$ codexbar guard --provider claude --need 5 --fail-open
claude session: unknown — UNKNOWN (need 5%)
exit=0

$ codexbar guard --provider claude --need 5 --json
{"window":"session","decision":"unknown","exitCode":2,"provider":"claude","needPercent":5}
exit=2

(unknown here is because the clean build environment has no configured account; the ok/blocked exit paths are driven by the pure evaluateGuard(remainingPercent:needPercent:failOpen:), covered by the unit tests above and by the green macOS CI.)

@clawsweeper re-review

[clawsweeper]

🦞🧹
ClawSweeper re-review requested.

I asked ClawSweeper to review this item again.
Action: item re-review queued (workflow sweep.yml, event repository_dispatch).
Result: the existing ClawSweeper review comment will be edited in place when the review finishes.

Re-review progress:

• State: Complete
• Detail: The durable review comment was published and its verdict was queued for target-serialized routing.
• Run: https://github.com/openclaw/clawsweeper/actions/runs/29569545272
• Updated: 2026-07-17T09:22:41.461Z

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 7c452fabad

ℹ️ 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".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

Reserve timeout budget for fallback strategies

When Claude is in CLI auto mode, its fetch plan tries the web step before the CLI fallback, and that web step can consume context.webTimeout. Here that per-provider web timeout is set to the exact same value as the outer guard deadline, so a slow/timed-out web attempt can use the entire --timeout; the outer runGuardFetch race then returns .timeout and cancels before the CLI fallback that codexbar usage would still try can run. In that auto/Claude-CLI setup, guard reports unavailable even though quota is available via CLI; use a separate/smaller per-web timeout or otherwise leave budget for fallbacks.

Useful? React with 👍 / 👎.

[steipete]

Merged as 562f9f2fc333f3528033245e06c3df5a333717f7 after verification on exact head 7c452fabadace65e4fac6e8cae20a31320c87283.

Verification:

• swift test --filter CLIGuardDecision: 13/13 tests passed, including inclusive threshold boundary, blocked exit 1, fetch failure exit 69, fail-open exit 0, timeout, missing provider, and unknown provider.
• make check: SwiftFormat 0/1535 files requiring changes; SwiftLint 0 violations across 1534 files; documentation/package/release checks passed.
• make test: first full run passed all 697 selections in 59/59 groups with zero retries. A post-hardening rerun passed the guard shard but encountered an unrelated local CodexUsageFetcherFallbackTests timeout/failure under fleet contention; exact-head CI subsequently passed both macOS shards plus both Linux builds.
• Source-blind built-CLI checks from /tmp: unknown provider exited 64; unavailable quota exited 69 with decision: "unknown"; --fail-open exited 0 while retaining unknown JSON; deadline exited 69; JSON argument errors exited 64 with structured output.
• Final live read-only run: .build/debug/CodexBarCLI guard --provider codex --min-remaining 0 --window session --timeout 60 --json --verbose reached codex.oauth without a credential prompt and exited 69 because the current local sessions contain no rate-limit events. This confirms the distinct fail-closed fetch-error path against a real Codex account; deterministic tests cover exits 0 and 1.
• Autoreview: initial findings fixed (explicit provider, EX_USAGE 64, bounded timeout); whole-branch credential-safety findings fixed (background policy covers resolution/fetch, credential writers omitted, structured argument errors); final review clean.
• Exact-head CI: changes, lint, Linux x64, Linux ARM64, macOS shard 0/2, macOS shard 1/2, aggregate lint-build-test, and GitGuardian all green. PR was CLEAN and MERGEABLE before merge.

No changelog file changed here; batch changelog follows separately.