feat(workspace): the role card reads the objective ↔ metric join (abilityai/trinity-enterprise#676)

[webmixgamer]

Summary

• The Workspace role card stops computing its own objective ↔ metric join and its own 30-day metric staleness. It calls the one join (objective_join_service.read_objective_join) and serves a field-picking client projection of it. Its old number source (the agent server's /api/metrics) has answered 410 since ent#479, so rows read "— / target · stale" before this change.
• The card's objective read draws on the same per-agent budget as GET /api/agents/{name}/objectives, spelled once in services/objectives_read_budget.py, behind a per-viewer cap of a third of that limit (20/min at the default). The budget is spent only when the card is about to read objectives.
• PortalAgentRole.vue renders actual/target by declared type, gap.status as a badge, freshness from the backend's verdict, a sentence per finding code, a named line when the objectives could not be read, and a line under a list that may be incomplete.

Deliberate departures from the issue text

• The card never answers 429. The issue's acceptance line says "Portal role route returns 429 under the shared key". Decided at plan review: the agent's own get_objectives spends the same bucket and the card also carries the role, the readiness stamp and the owner's flip, so a whole-route 429 would let an agent hide its owner's control. A refused read is a 200 without objectives (objectives_error: objectives_rate_limited) and without a container fan-out. The operator route still answers 429.
• type and unit are on the projection, beyond the issue's field list, so numbers format through utils/metricFormat.js.
• summary is not projected; card-level findings cross as finding_codes (codes only), per the ruling at claim time.
• A placement change was tried and reverted. An ent#527 follow-up decided at the eyeball moved the Role block above "Suggested for you". The PR review found that the block renders only after its role read answers, so it pushed the already-painted suggestions down; it is back below them (f8377831a), and PortalAgentDetails.vue is unchanged against dev.

Changes from the PR review

• Docs and test seams: the public user guide still said metrics go stale after 30 days; two memory docs contradicted the code; the flow doc overclaimed; one route test patched a seam the route no longer calls; the two-doors tests now pin the limit they do arithmetic on.
• The budget is spent only when the card is about to read objectives: the router passes a required admit_objectives callable, and the builder calls it after the role file, just before the join.
• The per-viewer cap is derived (max(1, limit // 3)), so an operator who lowers OBJECTIVES_READ_RATE_LIMIT cannot leave one viewer able to empty it.
• A partial list says so: objectives_partial plus one line when objectives joined but some objective files were not read.
• After merging ent#727 (cross-agent metrics) from dev: the card passes no can_view, so the join's fail-closed default holds and a Workspace viewer never sees a number served by another agent. A test pins this against a store that does hold such a grant.

Changes

• src/backend/client_portal/role_card.py — local join, metric staleness and /api/metrics read removed; portal_metric, portal_objective, objectives_error, finding_codes; objectives_partial; build_role_card takes a required admit_objectives callable.
• src/backend/services/objectives_read_budget.py (new) — key, limit, window; enforce (429) and admit (bool).
• src/backend/client_portal/router.py, routers/agent_files.py, client_portal/models.py.
• src/frontend/src/components/portal/PortalAgentRole.vue.
• Docs: requirements §5.36 and §50, the two feature flows, architecture/{workspace,backend,api-endpoints}.md, the public user guide (docs/user-docs/sharing-and-access/workspace.md), three learnings fragments, the /cso --diff report.

Test Plan

• tests/unit/test_ent676_role_card_join.py (40): the projection's key sets as literals, the card through the real join, every named "no objectives" state, the two doors on the real in-process limiter.
• test_ent666_objective_join.py::test_there_is_exactly_one_stale_rule_and_this_module_imports_it extended to role_card.py.
• src/frontend/tests/unit/portalAgentRole.spec.js (mounted, 35): every gap, freshness, finding and error state, and the partial-list line.
• Mutations: 10 on role_card.py / router.py and 7 on the component at first; each review fix carries its own (budget asked at the door, a fixed viewer cap, dropping the partial flag or its line, a can_view on the card's join, the limiter above the self-gate). Every one turned a named test red.
• Operator eyeball on localhost, light and dark: the seeded fixture rendered every row as expected, the budget tripped on the 21st read and recovered, the copy was approved. The partial-list line added at review: copy approved by the owner; not eyeballed on localhost.
• /verify-local --skip-agent --skip-unit on 649400ab0: PASS — prod backend image built and import main inside it, isolated stack booted healthy, integration 70 passed / 13 skipped / 2 deselected (the two registry false-fails). The sequential unit stage was skipped; the unit suite was run separately.
• On the final tree (dev fff19824c merged): 255 unit files touching metrics, objectives, the portal, the limiter or the docs, 7,641 passed. The 5 failures are the order-dependent test_2703_skill_assign_delivery.py set (25 passed alone; this branch touches no skill code). Ten frontend specs and ratchets, 257 passed.

No migrations. No MCP, agent-server or dependency change.

Fixes abilityai/trinity-enterprise#676

🤖 Generated with Claude Code

[webmixgamer]

/review summary

Full structural review of this branch against dev, run as two independent passes (backend, and frontend + docs) with every finding checked against the lines it cites. Head at review time: 433280f57. Fixes landed through c8466c470.

Critical findings: none. Checked:

• Auth: the roster gate (uniform 404) runs before either limiter key is built, and both keys use the validated name.
• Disclosure: the projected field sets are pinned as literals, and operator sentences, objective file paths and owner: role:<id> never cross to the Workspace.
• Credentials, SQL, enterprise docs: no credential handling or SQL added; the enterprise-docs guard has 0 hits.

Fixed on this PR

Finding	Commit
The Role block moved above "Suggested for you" rendered only after its role read answered, so it pushed the already-painted suggestions down (design-system principles 4 and 30). It is back below them	f8377831a
The public user guide still said a metric goes stale after 30 days. Two memory docs contradicted the code, and the flow doc overclaimed when an empty objectives block is silent. One route test patched a seam the route no longer calls, and the two-doors tests did arithmetic on an env-tunable limit	fc7204318
The objectives budget was spent on every Info-tab open, before the card knew whether it would read anything. It is now spent only after the role file is read, just before the join	a3c1fd6d6
The per-viewer cap was a fixed 20 in front of an env-tunable shared limit, so a lowered limit let one viewer empty the budget. It is now max(1, limit // 3), still 20 at the default	bcdd0deb8
A partial list (some objective files failed to read) looked complete. objectives_partial now adds one line under the list	65abe5d99
After merging ent#727 (cross-agent metrics): pinned that the card passes no can_view, so a Workspace viewer never sees a number served by another agent	c8466c470

Each fix carries a mutation that turned a named test red before the fix went in.

Left as is, low

• A metric-store outage shows the general "couldn't be read" line rather than a distinct one; this is deliberate, a single catch-all code.
• The role route itself has no rate limit beyond the objectives budget. That predates this PR, and the fan-out is now bounded. It is registered for follow-up.
• A failed role read still renders nothing, and "Try again" has no retry control. This predates the PR and is registered for follow-up.
• The new "no points yet" text uses the file's existing text-gray-400.
• The compose-file comments on OBJECTIVES_READ_RATE_LIMIT still describe GET /objectives only; .env.example is updated.

Verification

• Unit: on the final tree, 255 unit files touching metrics, objectives, the portal, the limiter or the docs gave 7,641 passed. The 5 failures are the order-dependent test_2703_skill_assign_delivery.py set; it passes alone and this branch touches no skill code.
• Frontend: the specs and ratchets pass, 257 tests.
• CI: green on c8466c470, including regression diff, e2e, journey-smoke, prod-image-smoke, CodeQL and schema-parity.
• /validate-pr: APPROVE. After merge, set status-in-dev on abilityai/trinity-enterprise#676 by hand, because the closing keyword does not cross repos.

[vybe]

merge-train (#3143): on this train. /validate-pr came back READY with no criticals, and the claims in your /review summary checked out.

Non-blocking, for a follow-up:

• finding_codes (card-level, models.py:646) is served and tested on the backend, but nothing in PortalAgentRole.vue reads it. Either render it or stop serving it.
• The compose comments at docker-compose.yml:108, docker-compose.prod.yml:169 and docker-compose.hosted.yml:222 still describe the old OBJECTIVES_READ_RATE_LIMIT scope.

[vybe]

merge-train: batch validated on train/#3143 (all Tier 1 + Tier 2 green)