Write an operator runbook for stuck circuit breakers

[greatest0fallt1me]

Summary

README's 'Circuit Breaker Stuck Open' section suggests waiting for cooldown, but does not mention the breaker state metric, the Postgres-backed store table, or how to reset state safely.

Why this matters

During incidents operators need concrete steps; restarting the process is currently the only option and drops traffic.

Scope

Expand the section into docs/ with: how to read gateway upstream breaker state from /api/metrics, SQL to inspect the breaker table created by PostgresCircuitBreakerStore, the admin reset endpoint once mounted, and env tuning (PROXY_BREAKER_*).

Relevant code in CalloraOrg/Callora-Backend:

• README.md
• RESILIENCE.md
• src/lib/circuitBreaker.ts
• src/config/env.ts

Priority

Low

Acceptance criteria

• The runbook lists metric names exactly as registered in src/metrics.ts
• SQL uses the actual table name and columns
• Tuning variables match src/config/env.ts
• README links to the runbook

Validation

Validate metric names against curl /api/metrics output in a local run.

Non-goals

• Typo-only, formatting-only, or cosmetic changes.
• Unrelated refactors, dependency upgrades, or broad rewrites.
• Removing safeguards or weakening validation to make tests pass.

Contributor application

Before coding, describe the affected modules, proposed state/invariant changes, test strategy, compatibility considerations, and an estimate. Wait for assignment before starting implementation.

PR requirements

Use a feature branch and include Closes #<issue-number>. Address every criterion, map criteria to code and tests, explain security and failure-mode handling, and ensure CI passes.

Quality review

A maintainer will assess correctness, completeness, test depth, compatibility, observability, and adverse-case handling. A substantive implementation is required; merge or CI status alone does not guarantee reward eligibility.

---

Generated by Claude Code

[shobhamerabacha-star]

Hi everyone,

I would like to resolve this issue. Here is my proposed execution plan:

• Implementation: Implement Write an operator runbook for stuck circuit breakers following the existing UI design system, accessibility standards, and responsive styling.
• Testing: Test across viewport breakpoints and ensure 0 TypeScript or linting errors.

Looking forward to contributing—please assign whenever convenient!

[bobaidestiny87]

@bobaidestiny87 has applied to work on this issue as part of the Stellar Wave Program's 9th wave.

Hi Maintainer,
I hope you’re doing well.
I would really appreciate the opportunity to work on this issue. Having carefully reviewed the acceptance criteria, I’m confident that I can work on it and submit a PR after being assigned.
Please kindly consider assigning this issue to me. I would be grateful for the opportunity to contribute.
Thank you very much for your time and consideration.

ℹ️ Repo Maintainers: To accept this application, review their application or assign @bobaidestiny87 to this issue.

[drips-wave]

Congratulations, @bobaidestiny87! 🎉 Your application was accepted by the repo's maintainers, and the issue is due on September 30, 2026.

🧑‍💻 @bobaidestiny87: Please resolve the issue such that the repo's maintainers have enough time to review your contribution before the due date. You'll earn Points for completing the issue on-time, which will make you eligible for a share of the Stellar Wave Program's reward pool.

Warning

When opening a PR, please link it to this issue to ensure it gets tracked accurately. Points are awarded when this issue is marked as completed by the maintainer.

🤠 Repo maintainers: Please keep an eye on the contributor's progress and review their work before the due date. You can manage this issue, including adjusting its complexity and points, here.

🌊 Happy Wave 🌊