fix(ui): keep budget declarations stable after turns (#325)

[Bindy-lbb]

Tracking record

Closes #325

Consumed requirement revision: R2 (DEC-ROLEWEAVE-325-002).

Summary

• Keep the employee card's “Budget declaration” section in declaration mode after turns instead of projecting latest-turn usage into it.
• Preserve truthful usage percentages in reports while bounding meter fill and aria-valuenow to 100%; expose the actual percentage through visible text and aria-valuetext.
• Update the control-plane specification, changelog, and regression coverage for the reported 309% case.

Token accounting and persisted turn records are intentionally unchanged: the observed 309% is the truthful ratio of 61,765 recorded tokens to the declared 20,000-token per-task cap.

Environment and reproduction

Reported desktop reproduction

• Client: locally started RoleWeave desktop client.
• Employee: Issue Researcher (问题研究员).
• Conversation: 4ce8fa66-3e2d-41d1-80cb-3d40a5ad886d (UI suffix a5ad886d).
• Declared budget: 20,000 tokens / 8 iterations per task; 200,000 tokens / 64 iterations per day.
• Persisted turn: 1cb04174-d451-4575-af3f-668f8493c6e6, with one usage event: 60,855 input + 910 output = 61,765 total tokens.

Steps:

1. Start the desktop client locally and open the Issue Researcher employee.
2. Send one request and wait for the turn to complete.
3. Return to the employee card's “Budget declaration” section.
4. Before this fix, the fixed 20,000-token declaration is replaced by 309%, and the red fill escapes its track. After this fix, the employee card retains both declarations; Reports → Usage & budgets still shows the truthful 309%, with a fill bounded to the track.

Local validation environment

• Ubuntu 24.04.1 LTS on WSL2, Linux 5.15.146.1-microsoft-standard-WSL2, x86_64.
• Node.js v22.23.2, npm 10.9.8; 20 logical processors and 31.2 GiB RAM; CI unset.
• Repository layout: /root/projects/fullstack-ai-infra/org-workbench with a real sibling /root/projects/fullstack-ai-infra/design-system checkout.
• PR head: 3a02150d7dc5b184089b3817f65544449c58cb9e; exact PR base used by the completed checks: eb01db298bb4b7b37840b288e03671a6b5fc5982.

Acceptance criteria

Acceptance criterion	Status	Implementation / evidence
AC-001: Employee card always renders per-task and per-day declarations	Pass	Removed report-derived consumption from App/PositionCard; covered by position-card.test.tsx.
AC-002: Reports continue to show actual over-budget percentage	Pass	BudgetBar visible text still renders the unbounded percentage; existing D4 report test passes.
AC-003: 309% text remains while fill and aria-valuenow are 100%	Pass	budget-bar.test.tsx asserts the exact 309% regression.
AC-004: Actual percentage is exposed via aria-valuetext	Pass	Meter now exposes aria-valuetext="309%".
AC-005: Regression coverage and relevant checks pass	Pass with repository-gate notes	Focused/full UI, target renderer, typechecks, build, desktop-main, and security gate pass. Existing unrelated isolation failures are documented below.

Validation ledger

Command or check	Expected	Actual	Evidence
npx vitest run --config packages/ui/vitest.config.ts packages/ui/test/budget-bar.test.tsx packages/ui/test/position-card.test.tsx	Regression tests pass	Pass	2 files, 13 tests passed.
npm run test:ui	UI suite passes	Pass	3 files, 37 tests passed.
Target D4 renderer test (-t "renders D4 tabs")	Report usage remains visible	Pass	1 passed, 79 skipped.
npm run typecheck:ui and npm run typecheck:renderer	No type errors	Pass	Both commands exited 0.
npm run test:desktop-main	Desktop build and main-process suite pass	Pass	Production renderer build succeeded; 360/360 tests passed.
npm run security:check	No high-severity finding	Pass	Exited 0; reports two existing moderate Vitest advisories.
GitHub required checks	All hosted gates pass	Pass	11/11 completed successfully, including Node 24 on Ubuntu/macOS, CodeQL, dependency review, package staging smoke, unsigned installers, and layout parity.
npm run check on the local environment above	Full repository gate passes	Stops in test:scripts before product tests	202/203 script tests pass. dedupe-react.test.mjs expects its synthetic “no design-system ancestor” layout, but discovers the real /root/projects/fullstack-ai-infra/design-system; this also leaves two dangling test-created React links, restored with node scripts/dedupe-react.mjs.
node --test --test-timeout=120000 "apps/server/dist/test/*.test.js"	Server suite passes	Local fixture baseline unavailable: 442 pass, 48 fail, 3 cancelled, 2 skipped	Failures span unrelated restore/session/reports/workspace fixtures; three files hit 120-second timeouts. Repeating with --test-concurrency=1 produces the same totals and failing set, so this is not changed by serialization.
Exact base/head server boundary comparison	Product branch does not alter server fixtures	Pass	git diff --quiet eb01db2 HEAD -- apps/server packages/shared scripts package.json package-lock.json exits 0. apps/server tree is 9ae0bbd5... and packages/shared tree is 09fe0a70... at both commits. The same server sources, fixtures, scripts, manifest, and lockfile are used by base and head.
Gemini fixture scope audit	Explain the reported six Gemini fixture failures	Not reproducible from this PR/base	git grep -i gemini returns no server/package matches at either eb01db2 or HEAD. Gemini server fixtures exist only on the unmerged origin/feat/315-gemini-cli-agent-host branch, so they cannot be a #326 head-vs-base regression.
Full App.test.tsx run	Renderer suite passes	Existing timeout instability	67/80 passed before chained timeouts; the changed D4 target passes independently.

Tests and coverage

• Tests added or changed: 309% bounded-meter regression and employee-card declaration stability.
• Coverage before / after, when measured: not measured; behavior is covered by focused component tests and the existing report integration test.
• Intentionally uncovered behavior and reason: no engine or reports aggregation changes are included because persisted usage was verified as correct.

Change classification

• User-visible behavior
• Internal refactor or maintenance
• Documentation only
• Build, CI, dependency, or repository configuration
• Breaking change
• Security-sensitive change

Risk and rollback

• Risk level and affected components: low; employee position card and shared budget meter presentation only.
• Compatibility, migration, privacy, performance, or operational impact: PositionCard.consumption is removed from this internal monorepo component; no persisted data, API, usage accounting, privacy, or performance behavior changes.
• Rollback procedure: revert commit 3a02150; no data migration is required.

Breaking or security notes

None.

Author checklist

• A maintainer confirmed that the linked issue or tracking record was ready before implementation began, or the automation was pre-authorized under GOVERNANCE.md.
• This branch was created from an up-to-date default branch and contains no unrelated changes.
• I ran the repository's applicable tests, lint, type checks, builds, coverage, and security checks.
• I added a regression test for a bug fix, or explained why one is impractical.
• I updated relevant documentation and changelog files.
• I reviewed the diff for secrets, personal data, generated artifacts, and dependency risk.
• The PR is ready for CI and review by someone other than the sole author.
• All reported results are reproducible.

Reviewer notes

Please independently verify the separation between declaration and consumption: the employee card should keep the configured caps after a turn, while Reports → Usage & budgets should still show the truthful over-budget percentage. Also inspect the 309% meter's visible text, bounded fill, and ARIA attributes.

The local full-gate limitations above are environment-specific and explicitly not claimed as a green baseline. The hosted Node 24 checks are green. If the six Gemini fixture failures were produced from a synthetic merge with feat/315-gemini-cli-agent-host, please provide that merge SHA or command so the same tree can be reproduced; neither the PR head nor its exact base contains those fixtures.

[PeterGuy326]

APPROVE

独立复核当前 head 3a02150：

• CI 必需检查全绿（含 Node 24 Linux/macOS、两端 staging smoke、installer/layout parity、CodeQL 与安全基线）。
• 隔离工作树复跑 npx vitest run --config packages/ui/vitest.config.ts packages/ui/test/budget-bar.test.tsx packages/ui/test/position-card.test.tsx：2 files / 13 tests passed。
• npm run typecheck:ui 与 npm run typecheck:renderer 均通过，git diff --check 通过。
• Diff、CHANGELOG、控制面规格和 309% 回归断言与 PR 的 AC/validation ledger 一致；已披露的全量仓库环境阻塞不涉及本 PR 改动。

LGTM。PR 当前仍 BEHIND main，合并前请先 rebase/update branch 后再按仓库流程 squash。

[waterbro-8]

Re-review after the post-#331 rebase (a299f1d). Over-budget fill is clamped to the track while the label and aria-valuetext stay truthful (e.g. 309%). CI is green. PositionCard no longer takes a unused consumption prop — matches the budget-bar-only contract.