Add treasury reserve capacity status

[ramimbo]

Summary

Adds read-only treasury reserve capacity visibility for maintainers and agents:

• public GET /api/v1/treasury/status
• /admin treasury reserve capacity panel with pending create-bounty proposals
• docs for checking capacity before opening fresh rounds
• regression coverage for status output and admin rendering

This is a maintainer PR. I am not claiming or requesting a bounty for it.

Why

Fresh bounty rounds are now proposal-gated and reserve-capped. Maintainers need to see the rolling 24h reserve cap, executed reserves, pending create-bounty reserve, remaining create capacity, and next release time before deciding whether to open or wait on new rounds.

Validation

• ./.venv/bin/python -m pytest (483 passed)
• ./.venv/bin/python -m ruff format --check .
• ./.venv/bin/python -m ruff check .
• ./.venv/bin/python -m mypy app
• ./.venv/bin/python scripts/docs_smoke.py

Summary by CodeRabbit

• New Features

  • New treasury status API reporting 24‑hour executed reserves, pending create-bounty reserves, available create capacity, and next capacity release; admin UI surfaces a “Treasury reserve capacity” section with metrics, pending proposals table, and contextual messaging when capacity is constrained.

• Documentation

  • Added treasury status endpoint to API docs, examples, and admin runbook with curl example and guidance on which fields to check.

• Tests

  • Added tests validating treasury status calculations, 24‑hour boundary behavior, and admin-page rendering for treasury info.

[coderabbitai]

Note

Reviews paused

It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

• @coderabbitai resume to resume automatic reviews.
• @coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

• ▶️ Resume reviews
• 🔍 Trigger review

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: dcf35948-7f72-4ede-99aa-7b25b3e73104

📥 Commits

Reviewing files that changed from the base of the PR and between 6001e50 and ac3ada2.

📒 Files selected for processing (1)

• tests/test_security.py

---

📝 Walkthrough

Walkthrough

This PR computes treasury reserve metrics from recent ledger entries and pending create-bounty proposals via treasury_status(), exposes the result at GET /api/v1/treasury/status, renders the status in the admin UI, adds tests for totals and 24h-boundary behavior, and updates operator and API docs.

Changes

Treasury Status Reporting

Layer / File(s)	Summary
Treasury status query logic app/treasury.py	_recent_bounty_reserve_entries() fetches recent bounty_reserve ledger rows within the epoch window. treasury_status() aggregates executed reserves, sums pending create-bounty proposal reserves, computes remaining capacity against the epoch cap, determines next release time from expirations, and returns metrics plus pending-create metadata and serialized recent-reserve entries.
API endpoint registration app/treasury_routes.py	Import treasury_status and register GET /api/v1/treasury/status route that opens a DB session and returns treasury_status(session).
Admin page display app/admin.py, app/templates/admin.html	Add treasury_status to the admin page context. Template renders 24h reserve cap, executed/pending/available amounts, conditional next-release timestamp or message, and a table of pending create-bounty proposals with links to proposal and issue details.
Test verification tests/test_treasury_proposals.py, tests/test_security.py	Add tests: seed genesis and two bounty_reserve entries, create a pending proposal, call the status endpoint, and assert metrics, pending-create payloads, and recent-reserve entries; verify inclusion at the 24h cutoff; update security/admin tests to assert treasury capacity messaging and tighten webhook summary matching.
Documentation updates docs/admin-runbook.md, docs/agent-guide.md, docs/api-examples.md	Admin runbook adds a curl check for /api/v1/treasury/status and reiterates the 10,000 MRWK per-24h epoch cap and status fields to review. Agent guide and API examples add the new endpoint and example calls and describe returned fields (reserve caps, executed/pending amounts, available capacity, next release time, and pending create proposals).

Possibly related PRs

• ramimbo/mergework#458: The main PR's new treasury_status() endpoint and reporting builds on the treasury governance proposal infrastructure introduced in that PR to surface pending create_bounty proposals and reserve-capacity state.

🚥 Pre-merge checks | ✅ 6

✅ Passed checks (6 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title 'Add treasury reserve capacity status' directly names the main surface change—a new treasury reserve capacity status feature across API, admin UI, and docs.
Description check	✅ Passed	The description includes all key template sections: Summary, Why (rationale), and Validation (with test results and tool checks completed). Evidence section outlines confusion addressed and intended surfaces.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Mergework Public Artifact Hygiene	✅ Passed	PR contains no investment, price, cash-out, or payout claims. All text uses factual operational language about treasury reserve capacity.
Bounty Pr Focus	✅ Passed	PR does not reference a Bounty #N or Refs #N—explicitly stated as maintainer PR with no bounty claimed. Check is conditional on bounty reference and does not apply.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

---

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

[ramimbo]

Maintainer note: this PR is intended as the first operational step after the treasury proposal changes, not as a cap-policy change.

The path I suggest is:

1. Land capacity visibility so maintainers can see the rolling reserve cap, pending create-bounty proposals, remaining create capacity, and next release time before opening fresh rounds.
2. Keep proposed bounty issues clearly non-live until their treasury proposal executes. No mrwk:bounty label and no Reserved on MergeWork comment before execution.
3. Follow up with automation for post-execution issue updates, so executed proposals can be finalized consistently.
4. Consider a later admin/planning improvement for queued capacity or bounty top-ups, especially for evergreen review, smoke-check, bug-verification, and docs rounds.
5. Revisit cap policy only after the current transparent flow has been observed in production.

This PR is a maintainer PR and has no bounty request.

[coderabbitai]

Actionable comments posted: 1

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: 0119e1b1-abc8-4742-8672-693d512816b0

📥 Commits

Reviewing files that changed from the base of the PR and between e00dc75 and fb50bfa.

📒 Files selected for processing (9)

• app/admin.py
• app/templates/admin.html
• app/treasury.py
• app/treasury_routes.py
• docs/admin-runbook.md
• docs/agent-guide.md
• docs/api-examples.md
• tests/test_security.py
• tests/test_treasury_proposals.py

[Thanhdn1984]

Review of PR #625: Add treasury reserve capacity status

Head commit: checked against current HEAD
CI: all checks pass (Quality/readiness/docs/image checks ✅, CodeRabbit review skipped)
Merge state: clean

Files inspected (9 files, +279/-4)

1. app/treasury.py (+66): New _recent_bounty_reserve_entries() and treasury_status() functions.

   • _recent_bounty_reserve_entries correctly filters by bounty_reserve entry type, treasury account, and 24h window with proper ordering.
   • treasury_status() aggregates executed reserves, pending create-bounty proposals, available capacity, and next capacity release time.
   • max(... , 0) correctly floors available capacity at zero.
   • min(release_times) returns the soonest upcoming release — correct.
   • Edge case: replace(tzinfo=None) in tests suggests DB stores naive UTC; the code handles this consistently.

2. app/treasury_routes.py (+6): New GET /api/v1/treasury/status endpoint — clean, uses session_scope properly, returns dict directly (FastAPI JSON serialization).

3. app/admin.py (+1/-1): Adds treasury_status to admin page context — minimal, clean import.

4. app/templates/admin.html (+51): Treasury reserve capacity section with semantic HTML, aria-label, conditional rendering for pending proposals table. Proper use of {% if %} guards.

5. tests/test_treasury_proposals.py (+131): Two thorough tests:

   • test_treasury_status_includes_recent_reserves_and_pending_proposals: verifies cap, executed, pending, available, next release, and pending bounty list.
   • test_treasury_status_includes_reserve_at_exact_24h_boundary: boundary condition — entry at exactly 24h ago is included but next_capacity_release_at is None (correct, since it expires at now).

6. tests/test_security.py (+6/-1): Updated admin page assertions to verify treasury section renders, and tightened regex for webhook summary aria-label disambiguation.

7. docs/ (+13/-1): Updated agent-guide, api-examples, and admin-runbook with new endpoint documentation.

Findings

• No security issues: endpoint is read-only, no auth required (consistent with other public treasury endpoints).
• No conflicts with active maintainer branches observed.
• Code quality: consistent with existing patterns, proper type annotations, clean separation of concerns.
• Minor observation: _pending_action_payloads is reused — good code reuse rather than duplicating query logic.

LGTM. Clean, well-tested feature addition.

[soheiyagi]

Reviewed for #578 at current head 5051d8a3f7d8400983dec980cfb485831ed33980 from a local checkout.

treasury_status() subtracts pending create_bounty proposals from available_create_reserve_mrwk, but next_capacity_release_at only looks at executed reserve ledger entries. On the admin page, that means a state like "no recent reserve entries" plus pending creates consuming the full cap renders as available_create_reserve_mrwk = 0 while also showing "No recent reserve entries are currently limiting create-bounty capacity."

So the operator can be told that nothing is limiting create capacity even though pending proposals are the limiter. This needs either a distinct pending-proposal blocking message in app/templates/admin.html or a status field that explains why available reserve is zero when the blocker is not a recent executed reserve.

[ramimbo]

Addressed the pending-create capacity wording finding in 6001e50.

The admin page now explicitly says pending create-bounty proposals are using current create-bounty capacity when available_create_reserve_mrwk is 0 because of pending creates, and it suppresses the misleading no-recent-reserve message in that state.

Validation:

• ./.venv/bin/python -m pytest tests/test_security.py::test_admin_page_renders_safe_webhook_events_for_cookie_admin tests/test_security.py::test_admin_page_calls_out_pending_create_proposals_when_they_limit_capacity tests/test_treasury_proposals.py::test_treasury_status_reports_reserve_capacity_and_pending_create_proposals tests/test_treasury_proposals.py::test_treasury_status_includes_reserve_at_exact_24h_boundary -q -> 4 passed
• ./.venv/bin/python -m ruff format --check tests/test_security.py -> already formatted
• ./.venv/bin/python -m ruff check tests/test_security.py -> passed
• git diff --check -> clean

[coderabbitai]

Actionable comments posted: 1

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: b6811479-8733-4a25-8cd4-40c98da0d6c4

📥 Commits

Reviewing files that changed from the base of the PR and between 5051d8a and 6001e50.

📒 Files selected for processing (2)

• app/templates/admin.html
• tests/test_security.py

[ramimbo]

Addressed CodeRabbit's test nit in ac3ada2 by scoping the assertion to the Available create reserve card instead of checking for any 0 MRWK on the page.

Validation:

• ./.venv/bin/python -m pytest tests/test_security.py::test_admin_page_calls_out_pending_create_proposals_when_they_limit_capacity -q -> 1 passed
• ./.venv/bin/python -m ruff format --check tests/test_security.py -> already formatted
• ./.venv/bin/python -m ruff check tests/test_security.py -> passed
• git diff --check -> clean