feat(access): who an agent serves, its seat, and what reads it (abilityai/trinity-enterprise#810–#814, #817)

[dolho]

Summary

Who an agent serves, which seat it holds, and what it owns because of it: one feature, managed from Agent Detail › Access. This PR is the public half of six private-tracker tickets:

• ent#810: the admin UI;
• ent#811: seats;
• ent#812: the objective join reads the seat;
• ent#813: the readiness gate reads the seat;
• ent#817: canon seats, three-state consent, and drift checked on read;
• ent#814: a shared companion serves the seat of the person each run is for.

Its private pair is Abilityai/trinity-enterprise#818, the assignments module changes for ent#811. Neither PR depends on the other to build or pass tests.

ent#810: "People this agent serves" (above the operator list)

• Admin view: the primary shown apart from the stakeholders, each row with its kind, proactive-brief consent and role-check state.
• Add a person: picked by name from the instance's users (never a typed email; suspended users are not offered). Change a kind in one action on the row, or remove the row.
• Replace primary is one flow. The old primary is re-kinded, or deleted if they already hold that kind or are being removed, before the new one is written, so the agent never has two. If the new one can't be written, the old one is put back.
• Errors and loading: every refused write shows the backend's own reason. A failed first load gets LoadFailed with retry; a failed refresh keeps the data and shows a stale banner.
• Empty and missing states: the empty state names the next action, and the add form starts on Primary. With no primary, a warning says briefs and approvals have nowhere to go.
• Non-admins see the section read-only, controls hidden. The section is absent when the instance isn't entitled to the module. Admin controls are gated on the server-verified profile (bug: Agent Detail and Workspace over-fetch on load (21 redundant requests, N+1 roster) #2198).

ent#811: seats (operator ruling 2026-10-06, R50 + R50a)

• services/assignment_provider.resolve_seat(agent) answers which seat an agent holds itself or serves through its primary, with no triggering user. It's for the readiness gate (ent#813), the objective join (ent#812) and the role card. It always returns a dict and never raises: every degraded case reads as "no seat" with a named reason. It reads the provider's optional seat_for through getattr.
• Header:
  • "Holds the seat: <id>" when the agent holds it itself (this wins when both apply);
  • "Serves the seat of its primary: <id> ()";
  • "No seat yet".
• Admins can record, change or clear the seat the agent holds. A refusal names the agent that already holds it; a person's row naming the same seat does not block it.
• The seat on a row is optional when adding or replacing the primary, and can be added, changed or cleared per row (an explicit null clears).

ent#812: owned objectives come from the seat on record

• The objective join resolves "owned" through resolve_seat, not x-role.role. That means the seat the agent holds (that seat only), else the seats its assigned people hold, primary first; a shared companion owns the union.
• x-canon alone enables the join; x-role is neither required nor read. Behaviour change: an agent with x-role but no x-canon no longer joins, as the issue specifies.
• No seat, no owned objectives. A no_seat finding says why and what to do (assign the primary with their seat on the Access tab). It replaces role_id_invalid, and supporting objectives still show. The Workspace role card renders that sentence.
• supporting_agents is read as before, documented as frozen.
• Response: the role now carries case and seats (model updated, so response_model doesn't drop them).
• Re-pinned suites: ent#527, ent#666, ent#676, ent#727 and the route model test declared their seat through x-role. They now record it through a registered provider, which is what an assigned primary does. Assertions about objectives, numbers and findings are unchanged.
• The objective-join requirements (requirements/lifecycle-observability.md §50) are updated.

ent#813: the readiness gate asks the seat, not the template

• Who counts as a companion: for an unstamped agent, "is this a companion?" is now answered by resolve_seat. A companion is an agent whose primary holds a seat (serves).
  • An agent that holds a seat itself (autonomous), has no primary with a seat, has no lookup, or gets a lookup error is "not a companion", so the brief fires (fails open, bug: retention floor (#1065) silently deletes pre-existing execution history on upgrade — currently dev-only, ships to everyone at next release #1638).
  • Each decision is logged with its reason.
• What stays the same: the owner's stamp still decides first, and a stamped agent's seat isn't looked up. The ent#689 rollout seed and held-schedule behaviour are unchanged; a stamped "calibrating" companion with a primary is still held.
• The template is no longer read: one container read less per brief, and an agent can't take itself out of scope by editing its own files.
• Behaviour change: a companion template with no assigned primary now sends its brief while calibrating, until its primary is assigned. The requirements (core-agent.md §5.36) say so.

ent#817: canon seats, three-state consent, drift on read

• Canon seats (OSS-core, operator ruling 2026-10-06): GET /api/agents/{name}/canon/roles (services/canon_roles_service.py) lists <canon>/roles/*.yaml with id, title and updated.
  • It reads through the agent door the objective join uses, on the same per-agent budget, and agent keys can read only their own canon.
  • Every empty answer is named: stopped, no canon, no roles/, unreadable, timeout.
  • It's classified in the bug(auth): agent-scoped keys can toggle their own agent's autonomy — PUT /api/agents/{name}/autonomy lacks reject_agent_principal #2996 route census.
• Three-state consent: agent_sharing.allow_proactive NULL = not asked, 0 = declined, 1 = consented.
  • New shares are written NULL.
  • A data migration on both tracks (SQLite + Alembic 0098_proactive_consent_not_asked, re-chained onto 0097_operator_queue_replace at the 2026-10-11 merge of dev) moves the legacy DEFAULT-0 rows to NULL. Data only; the DDL is untouched, so there's no table rebuild.
  • Who may be messaged is unchanged: only 1 allows it.
  • Shares and the Access list carry proactive_consent.
• UI:
  • seat fields suggest the canon's seats through a datalist, and a typed id still works;
  • the header and rows show the role's title, and the header shows the file's updated stamp;
  • drift reads current / changed / missing / unknown with its reason, and nothing for a row with no seat;
  • consent reads in three states;
  • when there's nothing to suggest, admins are told why.
• Requirements: updated in requirements/infrastructure.md.

ent#814: a shared companion serves each person's own seat

• Seam: assignment_provider.resolve_served_seat(agent, email) returns the person's own seat. The agent's own seat wins when it holds one (holds wins), and the primary's is the fallback. It never raises. A provider without the OPTIONAL served_seat_for falls back to seat_for.
• Seat decisions (ent#638) are stamped with the served seat. The agent's decided_by_role is used only when nobody's seat is on record, because the old prompt named the primary's seat on every run.
• Prompt: the Primary human line is unchanged. A Seat this run serves line is added only when the run serves a different seat: a chat user, or the Workspace a scheduled brief is delivered to. That address is read off the execution row and never rendered. Suppressed audiences still render nothing.
• UI: the add form no longer pre-fills the primary's seat for every new person.
• Unchanged: the one-primary rule, the primary display name and the primary address.

Role card (closed 2026-10-07, 797a6c3af)

The Workspace role card reads the seat on record through resolve_served_seat(agent, viewer), not x-role: seat_source says where the seat came from in words and never names a person; x-role is read only for its readiness status, so a legacy companion keeps its readiness control. "Your relationship" reads the provider's kinds_for when one is registered (trinity-enterprise#818 leaves it unregistered until readable_seats is narrowed to the reader's own seat, so it reads "no assignment recorded" until then).

The drift loop is replaced by the check on read (ent#817).

Changes

• src/backend/services/assignment_provider.py: the optional seat_for method and resolve_seat()
• src/backend/services/objective_join_service.py, models.py (ObjectiveRoleRead), client_portal's PortalAgentRole.vue copy (ent#812)
• src/backend/services/role_readiness_gate.py (ent#813)
• services/assignment_provider.py, routers/seat_decisions.py, services/platform_prompt_service.py, services/task_execution_service.py (ent#814)
• src/backend/services/canon_roles_service.py (new), routers/agent_files.py, db/agent_settings/sharing.py, db_models.py, db/migrations.py, migrations/versions/0098_proactive_consent_not_asked.py (ent#817)
• docs/memory/architecture/{api-endpoints,backend,database}.md: the new read, the seat resolvers and the three-state column are catalogued
• src/frontend/src/components/AgentAssignmentsSection.vue (new), mounted in AccessPanel.vue
• src/frontend/src/stores/assignments.js (new, through the single api client)
• src/frontend/src/utils/assignments.js (new, pure: seat line, replace-primary steps + rollback, consent/drift labels, error text)
• Tests: tests/unit/test_ent811_resolve_seat.py, tests/unit/test_ent812_objective_join_seat.py, src/frontend/tests/unit/agentAssignmentsSection.mount.spec.js

Test Plan

• tests/unit/test_ent811_resolve_seat.py: 17 passed. Each answer passes through; no provider, no agent, unsupported provider, a raise, no answer and eight malformed shapes all read "no seat". The neighbouring ent#500 provider suites: 72 passed together.

• tests/unit/test_ent812_objective_join_seat.py: 12 passed, through the real read_objective_join with the ent#666 fakes. Covers:

  • a held seat owns only itself;
  • a companion owns the union, primary first;
  • a lying x-role is not read;
  • x-canon alone enables the join;
  • no seat (provider says none, answers nothing, or no provider) owns nothing, gives no_seat, and still shows supporting work.

  Five mutations each turn tests red:

  • holds owning the union;
  • a companion owning only the primary's seat;
  • x-role still enabling the join;
  • no no_seat finding;
  • the owned flag matching only the first seat.

• tests/unit/test_ent689_readiness_gate.py (TestBriefReadiness rewritten for seats): 32 passed. Covers:

  • an unstamped companion is held;
  • a stamped "calibrating" companion with a primary is still held;
  • a stamped agent never asks for its seat;
  • holds and none fire with their reason;
  • no provider, a lookup error, no answer and a malformed answer fire;
  • an unreadable stamp fails open;
  • the template is never read;
  • the decision is logged.

  Four mutations each turn tests red:

  • holds counted as a companion;
  • an unknown seat holding the brief;
  • the seat consulted for a stamped agent (caught after I strengthened the test);
  • the decision not logged.

• The 24 unit files touching the join, role card, provider interface, seat decisions and readiness gate: 847 passed on seeds 12345 and 106.

• tests/unit/test_ent817_proactive_consent.py (8) and test_ent817_canon_roles.py (14) pass, on real SQLite and the agent-door fakes. The 42 consent and sharing files, including schema parity, pass: 1,139. The bug(auth): agent-scoped keys can toggle their own agent's autonomy — PUT /api/agents/{name}/autonomy lacks reject_agent_principal #2996 route census passes.

• tests/unit/test_ent814_served_seat.py: 22 passed. A mutation check reverting each half (the decision stamp, the prompt line, the seat-run address) turns it red.

• Full public unit suite: 21,973 passed. The 42 failures (payments pin parity, a2a, ssrf, mcp_validator, ipv6) fail identically on a clean dev checkout, caused by local venv package versions (e.g. 1.12.0 vs the 1.18.0 pin); the other 6 are order-flaky in those same files.

• Live on a local instance:

  • a chat with the non-primary person gets Seat this run serves: project-lead, with no email in the prompt;
  • a decision on a brief delivered to them is stored as project-lead, though the agent claimed cfo;
  • an agent that holds a seat serves it for everyone.

• agentAssignmentsSection.mount.spec.js: 32 passed (mounted, jsdom). These mutations each turn tests red:

  • admin gate always true;
  • entitlement gate removed;
  • no rollback;
  • ignoring an existing kind in the replace plan;
  • no drift warning;
  • suspended users offered;
  • no seat line.

• Full frontend unit suite: 274 files, 4,769 tests passed, including the raw-colour, loading-gate and source-text ratchets. check:tokens OK.

• Live on a local instance with the assignments module enabled (this branch + ent#818), light and dark:

  • empty state;
  • add a primary and an approver;
  • a duplicate add refused with the backend's message;
  • a real primary replacement;
  • the agent holding a seat;
  • a second agent refused, naming the holder;
  • a viewer added without a seat, then given one through the row editor.

  The live run also caught that the routes are mounted at /api/enterprise/assignments, not /api/assignments as the issue's notes say. The spec pins the real paths.

Live walkthrough (2026-10-06)

Every claim above was driven end to end on a local instance:

• Setup: seeded people (one of them suspended), canon roles and objectives, three agents, a non-admin owner.
• Browser: Playwright, recording layout shift at every step. 64 of 65 scripted checks pass across 24 steps. The miss is a phone overflow from the existing "Add operator" button, which predates this PR.
• Backend: prompts, decisions and the readiness gate were checked in the running backend.

The run found seven defects the unit suites missed. All are fixed here, each with a test that fails when the fix is reverted:

• Replacing the primary with someone already on the agent now promotes their row, instead of listing them twice with two seats.
• The add form clears the seat after an add. Before, the next person added silently got it.
• A person on several rows serves the primary row's seat first (fix(security): sandbox voice panel HTML in iframe (CRITICAL XSS) #818). Before, the answer depended on read order.
• The first load keeps the loaded shape and doesn't say "No seat yet" while loading. On a slow network the list below used to jump 133px; it now moves 5–24px.
• The Workspace role card shows the no_seat sentence. Before, it was mapped as a role error and never appeared.
• On a phone each row stacks, so the kind dropdown no longer covers the person's name.
• A failed replacement says who the primary is now, from a fresh read.

During actions (add, edit, replace, seat changes) the section causes no layout shift.

Merge of dev (2026-10-11)

Merged dev at d127132b4 (c108addf8): keep-both on migrations.py, the agent_files.py imports, platform_prompt_service.py (#3247's pending asks beside ent#814's served seat) and tests/registry.json, dev's entries first. The Alembic revision is 0098_proactive_consent_not_asked on 0097_operator_queue_replace, one head. dev's ent#839 self-gate on the seat-decision router reads current_user.agent_name, so the ent#814 test's user stub now carries it as the real User does (8eda88239).

After merge

Trinity dev needs an enterprise pointer bump once ent#818 lands.

Related to abilityai/trinity-enterprise#810, #811, #812, #813, #814 and #817 (cross-tracker: closed by hand at release)

🤖 Generated with Claude Code

[github-actions]

⚠️ Alembic head fork if this PR is merged into dev.

dev has advanced since this PR's checks last ran. GitHub recomputes the merge ref when the base moves but does not re-trigger workflows, so a green schema-parity here can describe a base that no longer exists (#2533).

scripts/ci/check_alembic_heads.py against dev + this PR, merged in memory

alembic-heads: FAIL — src/backend/migrations/versions resolves to 2 heads across 99 revision(s); exactly 1 is required.
  • 0095_proactive_consent_not_asked  (0095_proactive_consent_not_asked.py)
  • 0097_operator_queue_replace  (0097_operator_queue_replace.py)

They fork at: 0094_agent_skill_gates  (0094_agent_skill_gates.py)

`alembic upgrade head` is singular and resolves its target BEFORE applying anything,
so this graph applies ZERO revisions — every revision since the fork stops arriving,
not only the one that forked. Fix by chaining the newer revision off the real head,
or — if the forked revision may already be applied somewhere — by adding a merge
revision (`alembic merge -m "…" <head-a> <head-b>`), whose tuple `down_revision`
converges the line from any starting state. See Architectural Invariant #3.
alembic-heads: src/backend/enterprise/backend/migrations/versions — version directory absent (submodule not initialised) — skipped.

Evaluated on the version line only — this PR also conflicts with dev in 4 unrelated file(s), which do not change this verdict but must be resolved before merge:

src/backend/db/migrations.py
src/backend/routers/agent_files.py
src/backend/services/platform_prompt_service.py
tests/registry.json

Fix: rechain this PR's revision off 0097_operator_queue_replace (the current dev head), or — if the forked revision may already be applied somewhere — add a merge revision (alembic merge -m "…" 0095_proactive_consent_not_asked 0097_operator_queue_replace), whose tuple down_revision converges the line from any starting state. See Architectural Invariant #3.

Push the fix and schema-parity re-checks it against the merge ref immediately; this comment clears on the next push to dev touching src/backend/migrations/versions/**.

Advisory — this check does not block merge. · head_sha: 96673aae6ef1c87128af891dea1d32ec2d05d458 · run

[AndriiPasternak31]

@dolho a heads-up from #3304 (draft): with it, agent file download and preview no longer open a path that is a link, for every caller, the platform's own reads included. A template.yaml that a template ships as a link becomes unreadable to role_readiness_gate and the objective join, which treat it like any other unreadable template; the backend logs a warning naming the file. Templates should ship template.yaml as a regular file. Nothing to change in this PR unless you want the gate to handle that case differently.

[dolho]

The three "Still open" items from the 2026-10-06 live check are fixed in 797a6c3af. The enterprise half is abilityai/trinity-enterprise#818 a043f6770.

1. The Workspace role card now reads the seat on record, not x-role.

• Before, the role came from x-role.role and the "Seat ·" line from x-role.seat, which is an email. So Maya's card said "sales-lead · role file not in the canon · Seat · admin@local.test" while the Access tab said Head of Sales.
• build_role_card now asks resolve_served_seat(agent, viewer). That is the same answer the agent's prompt gets: the seat it holds itself, else the viewer's own seat, else its primary's. It reads that seat's role file.
• The new seat_source field says where the seat came from, in words: "The agent holds this seat itself", "Your seat on this agent" or "Its primary's seat". It never names a person. The seat field is gone.
• When the card shows: the agent serves a seat, has a canon, or still declares x-role. The last condition stays only so a legacy companion keeps its readiness control. x-role.status is still the template's readiness claim. x-role.role and x-role.seat are no longer read.
• No seat: the card says role.error = no_seat once, on the role, and the objectives block no longer repeats it. Supporting objectives still list.

2. "Your relationship" now shows the viewer's assignment kind.

• It comes from the provider's kinds_for (added in fix(security): sandbox voice panel HTML in iframe (CRITICAL XSS) #818), via seat_decision_service.reader_kind. The values are primary, approver, collaborator or viewer. "No assignment recorded" now appears only when there really is none.
• It's answered for a stopped agent too, because the record isn't in the container.

3. "Add operator" no longer overflows on phones. The email input gets min-w-0 and the button shrink-0 whitespace-nowrap. Colour classes are untouched, so the colour ratchet is unchanged. It needs a 390px look in the browser; jsdom has no layout to test it.

Tests

• test_ent527_role_card.py is rewritten to the seat rule, with seven new or re-pinned tests, all red with role_card.py reverted. They cover:
  • a card with a seat even without x-role;
  • a lying x-role not being read;
  • each viewer seeing their own served seat (Maya → CFO);
  • no seat → no_seat with supported objectives;
  • the relationship from kinds_for, including a stopped agent;
  • a traversal-shaped seat id refused.
• portalAgentRole.spec.js: the seat-source words, the relationship text (an unknown kind falls back to "no assignment recorded"), and the no-seat sentence shown once.
• 108 backend tests (ent527, ent676, readiness-on-lists) and 93 frontend specs, plus the ratchets, pass locally. Full suites are left to CI.

Docs: feature-flows/workspace-role-card.md and requirements/core-agent.md §5.36.

⚠️ Behaviour that #818's kinds_for switches on (needs your attention): ent#638's reader gate readable_seats already gave "a provider-declared stakeholder" read-only access to every seat's decisions. No provider answered until now. With kinds_for live, anyone with a row on the agent can read every seat's decision records. That is the documented per-agent v1 rule (DEBT_INBOX 2026-09-22), not new policy, but it is live now.

🤖 Generated with Claude Code

[github-actions]

⚠️ Nightly unit-suite check skipped — merge conflict against dev.

Resolve by running git merge dev locally and pushing the result. The next nightly run will re-test once the conflict is gone.

[github-actions]

⚠️ Live-instance suite skipped — merge conflict against dev.

Resolve by merging dev locally and pushing the result; the next nightly re-tests.

[dolho]

Merged dev (0f97d1171). Fixes the alembic-head-watch fork: 0092_proactive_consent_not_asked is now 0095_proactive_consent_not_asked, with down_revision = "0094_agent_skill_gates" (96 revisions, 1 head). The migrations.py and tests/registry.json conflicts are resolved by keeping both, dev's entries first. test_ent817_proactive_consent.py: 8 passed.

Heads-up: #2984 now chains 0096_seat_ask_class_state off the same 0094, so whichever of the two merges second has to re-chain onto the other.

Related: trinity-enterprise#818 now leaves kinds_for unregistered until readable_seats here is narrowed to the reader's own seat. Until then, "Your relationship" reads "no assignment recorded".

🤖 Generated with Claude Code

[vybe]

Validated (/validate-pr, Lane B+schema) and brought up to date with dev — four commits pushed.

1. c108addf8 Merge origin/dev (d127132b4). Keep-both on migrations.py, the agent_files.py imports, platform_prompt_service.py (Scheduled runs re-ask what is already pending — show an agent its open asks and let it replace one #3247's pending asks beside ent#814's served seat) and tests/registry.json, dev's entries first. The Alembic revision is re-chained 0095 → 0098_proactive_consent_not_asked on 0097_operator_queue_replace; check_alembic_heads.py: 99 revisions, 1 head.
2. 8eda88239 Test stub after the merge. dev's ent#839 self-gate on the seat-decision router reads current_user.agent_name before any lookup, so test_ent814_served_seat.py's SimpleNamespace(id=1) raised AttributeError; the stub now carries agent_name=None as the real User does.
3. dce477a95 Architecture catalogs. api-endpoints.md gains GET /api/agents/{name}/canon/roles; backend.md gains canon_roles_service and the resolve_seat / resolve_served_seat contract on the assignment seam; database.md marks allow_proactive as NULL/0/1 with both migration names. None of the three mentioned the new surfaces.
4. eeccbb80c A defect the structural review found. Since ent#814 the seat on record wins over the agent's decided_by_role, but seat_decision_service.validate_record checked it with the ask_class slug ([a-z0-9_-], no dots) while canon role ids follow objective_join_service._ID_RE (roles/head.of.sales.yaml is a valid seat). A dotted seat on record refused every decision for that agent with 422, and the agent could not work around it. decided_by_role now takes the lowercased canon id shape; ask_class keeps the strict slug. Regression tests (dotted id validates; traversal-shaped, spaced, leading-dot and over-long ids still refused; ask_class unchanged) go red with the fix reverted.

Verified locally: the 60 unit files touching the join, role card, provider seam, seat decisions, readiness gate, sharing, consent, migrations and the route census — 1,382 passed on seed 12345 (+3 new); frontend vitest run 345 files / 5,630 tests including the raw-colour and loading-gate ratchets against the committed baselines; the enterprise-docs guard pattern is clean over the edited docs and assignment_provider.py.

Reviewed and left as designed (documented in the requirements or the PR body): the 0→NULL data migration cannot tell a legacy default from an explicit decline (operator ruling 2026-10-06); an unstamped companion with no seat provider now fires its brief (ent#813 fails open); schema.py keeps DEFAULT 0 on allow_proactive while the code writes NULL — nothing omits the column today, but a future writer that does would record a decline nobody made, worth a follow-up when the column is next rebuilt.

PR description: 0090 → 0098 and the "Still open" block folded into the 2026-10-07 role-card fix.

🤖 Generated with Claude Code

[vybe]

One more after CI on eeccbb80c: the regression diff caught test_ent731_guard_metrics::test_a_guard_is_fetched_through_the_whole_read (new on dev). The ent#731 suite reuses the ent#666 fakes but not the autouse _seat_on_record fixture ent#812 added there, so after the merge the whole read owned nothing (x-role is no longer read) and indexed an empty list. e6271b15a imports the fixture, which registers it for that module — ent#731 + ent#666 + ent#812: 122 passed on seed 12345. No product code changed.

🤖 Generated with Claude Code

[vybe]

Validated with /validate-pr (Lane B+schema); merge, fixes and CI are recorded in the comments above.