GET /api/orgs/{id}/work-recommendations accepts optional actor_id
(member UUID, defaults to the caller), project_id, limit (1–5, default 5),
and cursor. Machines can read only their own recommendations. A human can
inspect self, a manageable agent, or another human with shared write access.
All issue and strategy evidence uses the intersection of caller and target
permissions. Missing and forbidden targets both return 404.
The read evaluates the complete bounded authorized project scope before global
ranking. It scans at most 1,000 source issues, 250 scope rows, 200 queries,
25,000 related physical rows, and 4,000 execution or assignment rows per
category. Any exceeded ceiling returns 422 WORK_RECOMMENDATIONS_EVIDENCE_LIMIT
with no partial ranking. Current work is displayed separately, capped at 20
with current_work_truncated. Occupation checks remain complete.
Any assigned, running, waiting, or needs_human execution for the target
suppresses all new-work suggestions across the organization, including work
outside the project filter and projectless work. Occupation uses immutable
execution actor identity and current issue ownership. Hidden occupation yields
only the generic availability_not_established caveat, with no hidden work
identity, title, state, count, or timestamp. Authorized waiting and attention
work has inspection actions. Failure inspection uses newest created-at/UUID
display chronology across actors; it does not establish retry supersession or
permission to dispatch. Succeeded and cancelled executions are terminal.
available_for_recommendation permits eligible read suggestions in this snapshot.
It never reserves an agent, claims runtime capacity, or authorizes execution.
Revalidate with the canonical assignment and execution APIs before any write.
A managed inactive agent returns only its authorized identity and lifecycle,
availability: inactive, empty work, no cursor, can_assign: false, and
scope.project_id: null. Former effective scope and work stay concealed.
Actor cursors are signed, bound to caller, organization, actor kind, target,
and project filter, and expire after 15 minutes. Each page rechecks current
permissions and a fingerprint of ranking and execution evidence. Drift returns
409 WORK_RECOMMENDATIONS_CURSOR_STALE; restart without a cursor. Invalid
scope or signatures return 400 WORK_RECOMMENDATIONS_INPUT_INVALID.
GET /api/orgs/{id}/work-recommendations/actors?project_id=<UUID> returns the
bounded permitted enabled human/agent selector projection. It contains only
self_id and actors with id, display_name, and type.
Use atoll work recommendations [--actor UUID] [--project UUID] --json,
atoll work actors --project UUID --json, or
atoll work project-recommendations --project UUID --json for the existing
project-wide ranking. Full and public MCP expose atoll_get_work_recommendations
with view: recommendations (default), actors, or project. The selected
MCP profile_ref stays the authenticated caller; selecting a target never
changes that caller. These surfaces return the same server order and reasons.
