Skip to content

feat(asks): admin seat, re-address by rule, and refusals that name who a card waits for (abilityai/trinity-enterprise#1096) - #4559

Merged
vybe merged 11 commits into
devfrom
feature/1096-consent-readdress
Nov 14, 2026
Merged

vybe merged 11 commits into
devfrom
feature/1096-consent-readdress

Conversation

@vybe

@vybe vybe commented Nov 13, 2026

Copy link
Copy Markdown
Contributor

What

Approval cards that ask a person can be stranded today: when the seat they were addressed to empties or moves, nobody can answer them, and the refusal does not say who the card is waiting for. This PR gives the platform the pieces to fix that (part of abilityai/trinity-enterprise#1096):

  • A platform-stamped admin seat. A gate approval whose platform context carries the decider-seat stamp admin and has no named people can be decided by an instance admin who is a person. Agents cannot write the stamp (it is a platform context key, stripped from agent-authored context). A row without the stamp stays undecidable, as before.
  • Re-address by rule, admin only. New POST /api/operator-queue/{id}/readdress (require_admin + require_person, human-only, no MCP tool). Body {to: rule|admin, reason}. It re-resolves the card's audience by the rule that raised it — there is no free person picker. An extension package may register a resolver for its own ask family (ask_service.register_readdress_resolver(prefix, fn); a prefix that could start a skill-gate id is refused). Unchanged audience → 409 audience_unchanged; a rule that raises or yields an empty primary/owner seat → 409 rule_refused, row untouched.
  • Endings hold the address. Answer and cancel compare-and-set on the address read just before the write (resolved_to, addressed_to_email, and the seat stamp on admin-seated rows). A card re-addressed in between ends neither way: 409 readdressed.
  • Admin cancel of a card they are not on needs a reason (422 reason_required); bulk cancel skips such rows and counts them in skipped_fenced.
  • Every refusal says who the card waits for. The 403 not-addressee and the 409 readdressed bodies carry the seat and, on person-addressed gate approvals only, the people; a role-addressed row names the role, never a person. The Workspace door names no one. UI: the queue card and mobile admin show the server's message (notAddresseeMessage), falling back to the old string on older backends.

/readdress is API-only for admins until a per-card admin UI ships. No schema change: everything lives in existing operator_queue columns.

Review + security

Reading review: MERGEABLE AFTER FIXES, 0 critical; both must-fix items (a role row's 409 body named a person; tests/registry.json conflict with dev) and the cheap items are fixed in d31941c2c, 4c2ad01a8, 55f098556, 318804b39. Evidence sweep: one surviving mutation (dropping resolved_to from the ending compare-and-set) is now killed by two db-level tests (12e1177d8), shown red for the answer and the cancel path separately. /cso --diff: 0 findings. .claude and src/backend/enterprise untouched.

Tests

At 318804b39, one file per process, foreground: 19 backend files, 1012 passed, 0 failed (the two new test_1096_* files, the operator-queue / ask neighbours, test_2338 registry reader, test_2996 human-only routes, test_293 admin gate). Frontend: the three not-addressee specs. Not run locally, left to CI: test_3785_operator_queue_package (timed out locally), the full pinned-guard list.

Before merge

🤖 Generated with Claude Code

Trinity Agent (trinity) and others added 8 commits November 13, 2026 13:49
… (abilityai/trinity-enterprise#1096, C1)

The decider order (primary → owner → instance admin) had no answering path
for its third arm: a gate approval with an empty snapshot waited on nobody.
OSS sink half:

- R1: a gate raise may address nobody only with the platform's new
  `workspace_decider_seat = admin` stamp (a `_PLATFORM_CONTEXT_KEYS` member,
  stripped from agent content).
- R8: `may_end`'s admin arm decides a stamped, empty gate approval only for
  a principal passing the admin gate and the person rule; `addressed_view`
  reports the same answer plus `waiting_on_seat` on stamped rows.
- R4: `readdress_item` compares stamps, a None stamp removes its key; an
  `actor` makes the audit row carry the admin and `has_reason`.
  `ADMIN_READDRESSED` joins the readdress reasons.
- R5: answer/cancel on a seat-fenced row compare the stored address in the
  CAS; a lost compare is `AskConflict("readdressed")`.
- R6: `bulk_cancel` skips fenced rows the actor is not addressed on
  (`Ending.skipped_fenced`).
- R7: `AskNotAddressee` carries `waiting_on`/`seat`; the message names the
  person for gate approvals only; role refusals stay person-free.
- R9: the admin arm records `admin:<username>` for an admin with no email.
- Resolver registry (`register_readdress_resolver`) for platform families
  under `gate-`; R12 docstring on `readdress_role`.

Tests: tests/unit/test_1096_admin_seat_fence.py (62); the ent#715 reader
table classifies the two new row readers.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
… refusals (abilityai/trinity-enterprise#1096, C2)

- POST /api/operator-queue/{id}/readdress {to: rule|admin, reason}:
  require_admin + require_person (grant-vs-use: human-only), row visibility
  as the read's, `ask_service.admin_readdress` re-runs the rule that raised
  the card (registered family resolver, or the role) or takes a registered
  family's gate approval to the admin seat (R2/T2, no person picker; a
  skill-gate approval is refused the admin seat, T3). 409
  audience_unchanged names who it waits for; 422 unknown_family.
- /cancel: an admin ending a fenced card they are not on must give a
  reason (422 reason_required, `AskReasonRequired` in the sink).
- /bulk-cancel returns `skipped_fenced` (R6).
- 403 not_addressee on Operations and Workspace carries `seat` and, except
  on role refusals (the ent#1042/#1053 "never a person" contract),
  `waiting_on`; admin verbs on Operations only (R11). An ending that lost
  to a re-address is 409 `readdressed` (people named on Operations only).
- R14: `# mcp:` header names readdress as a human-only admin verb.

Re-pinned in this checkpoint: test_ent751_gate_dispatch (admin cancel now
needs a reason), test_ent611_ask_endings (bulk body gains skipped_fenced),
test_ent715_queue_person_fields (new door + readers classified).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…ts for (abilityai/trinity-enterprise#1096, C3)

The server's 403 `not_addressee` now names the seat and the person
(C2). `notAddresseeMessage(err)` prefers `detail.message` and keeps the
generic line when the server sends none (an older backend); the desktop
store keeps it beside `notAddresseeItemId` for QueueCard, and /m uses it
directly. One string path, no new component; raw-color counts unchanged
(QueueCard 28/59/0, MobileAdmin 0/4/130 — equal to the baseline).

Re-pinned: mobileAdminNotAddressee.spec (the server's message, plus the
fallback case); queueCardNotAddressee.spec gains the named and fallback
mount cases; new operatorQueueNotAddressee.spec for the helper.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Resolves tests/registry.json by keeping dev's test_4475 entry and both
1096 entries (both sides appended at the tail).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…person (abilityai/trinity-enterprise#1096, M1)

readdressed_detail built its message from waiting_on for every seat-fenced
row, so a role, approver or project row's 409 named people and carried
waiting_on, while the same row's 403 stays person-free. It now returns the
AskNotAddressee.detail shape for those rows: the role message and seat, no
waiting_on, no email. New role:cfo case in test_1096_admin_seat_fence was
red before the change (waiting_on present, email in the message).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…d-set (abilityai/trinity-enterprise#1096, S1)

No test reached the window the CAS exists for: a re-address landing after
the service read the address and before the ending's UPDATE. Two db-level
tests take the expectation the service builds, move resolved_to while
addressed_to_email stays NULL ([alice,bob] -> [alice,carol]), then call
respond_to_operator_queue_item / cancel_operator_queue_item with
expect_address: each returns _status_conflict and the row stays pending.

Mutation: dropping resolved_to from the respond CAS turns
test_an_answer_read_before_the_move_does_not_land red; dropping it from the
cancel CAS turns test_a_cancel_read_before_the_move_does_not_land red. Both
reverted byte-identical.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
… id is refused (abilityai/trinity-enterprise#1096, L1)

admin_readdress looks a registered resolver up before the skill-gate shape,
so a prefix of hex digits only (gate-a...) would match gate-<40 hex> ids
and let to: admin put a skill-gate approval on the admin seat. The
registration now raises ValueError for any prefix fully matching
gate-[0-9a-f]*. New parametrized test was red (DID NOT RAISE) before.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…rule_refused (abilityai/trinity-enterprise#1096, L3)

admin_readdress trusted the registered family rule: a resolver that raised
surfaced as a 500, and one that returned a primary or owner seat with no
people wrote a card nobody could decide. Both now return 409 rule_refused
and leave the row untouched; only the admin seat may be empty. Two new route
tests (raising rule; primary/owner seat with nobody) were red before (an
uncaught RuntimeError, and 200 instead of 409).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@vybe vybe added the ui PR touches the frontend UI — triggers Playwright e2e tests label Nov 13, 2026
@trinity-ability

Copy link
Copy Markdown
Contributor

/validate-pr — APPROVE

Validated at 318804b39, lane B, with the PR standing alone (no extension-package resolver registered).

Merge gate ✅. Tier 1 is green: the four required contexts, pytest (head, seed 12345), regression diff, gitleaks, both lints, pg-migrations, frontend build and e2e. dev-ci reports success, and the PR merges cleanly against the current dev tip (548e1ff79).

Checks

  • Commits, base branch and size ✅
  • Journey Impact ✅ (check_journey_impact.py exits 0)
  • Security greps ✅: no keys, emails, IPs, host paths or mode changes
  • Audit rows ✅: readdress_queue_item writes its row through readdress_item (ADMIN_READDRESSED, actor, has_reason)
  • Cross-surface ✅: the # mcp: header declares readdress → none. respond_to_operator_queue passes {code, message, …extras} through generically, so the new 403 fields and the 409 readdressed reach callers unchanged. Cancel is not MCP-exposed.
  • Product fit ✅: the operator queue is OSS on both tiers.

Execution coverage. Mutations run in the PR worktree for this validation, each reverted:

  • Drop the admin-gate predicate from the may_end admin arm → test_no_other_principal_may_decide_it[admin_agent_key] goes red.
  • Remove the decider-seat key from _PLATFORM_CONTEXT_KEYS → 33 tests go red, including test_an_agent_cannot_author_the_stamp.
  • Let an empty-audience gate raise through without the stamp → test_an_empty_audience_without_the_admin_stamp_is_still_refused goes red.

The three frontend specs mount the real components.

Standalone behaviour. With no resolver registered, to: rule on a gate approval returns 422 unknown_family and to: admin returns 422 admin_seat_unsupported. Rows without the stamp behave as on dev, and the boot check without the submodule passes.

Warnings (not blocking)

  1. The body says "part of" with no closing keyword, which looks deliberate: the issue also needs the other half. The ref is cross-tracker, so set status-in-dev on it by hand after merge.
  2. No feature flow was updated for the new verb, the admin seat, reason-required cancel or the named refusals (role-assignments, skill-gate, workspace-inbox).
  3. The structural review and /cso --diff ran but are not posted on this PR.
  4. Merge order with fix(access): a platform continuation turn stands as the turn it continues (abilityai/trinity-enterprise#1225) #4546: both add platform context keys in operator_queue_service/__init__.py, and both append to the tail of tests/registry.json. Whichever lands second keeps both.

Suggestion. A registered resolver that returns seat admin together with a non-empty audience gets the admin stamp on a row with people. The stamp is then inert, but it misleads. Worth a test once a resolver exists.

Not run: full suites (CI ran them), the PR-side journey-smoke (not required for lane B), and an integration with the extension-package half (not built yet).

This is posted as a comment, not a GitHub review, so merge order stays the maintainer's call.

@vybe
vybe marked this pull request as ready for review November 13, 2026 20:14
Union resolution of the two #4546 conflicts: bulk_cancel keeps the
branch's skipped_fenced ending and adds dev's actor_user_id; the
operator-queue platform keys keep both _WORKSPACE_DECIDER_SEAT_KEY and
_CONTINUES_TURN_KEY.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@github-actions

Copy link
Copy Markdown

⚠️ 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.

trinity-ability and others added 2 commits November 14, 2026 17:17
…ervice/__init__.py is back at the 800-line cap (#4559)

test_3785's size threshold failed the regression diff at 804 lines. Comment only; no code change.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
@vybe

vybe commented Nov 14, 2026

Copy link
Copy Markdown
Contributor Author

merge-train: two commits pushed to this branch (fb2481d5c → cee45b347)

Local at cee45b347: test_3785_operator_queue_package, test_1096_admin_seat_fence, test_1096_readdress_route — 137 passed.

@trinity-ability trinity-ability left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

merge-train: validated at 318804b (/validate-pr APPROVE); delta to cee45b3 is two clean dev merges and a comment-only trim. Tier 1 green on cee45b3.

@vybe
vybe merged commit cb29afd into dev Nov 14, 2026
28 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

ui PR touches the frontend UI — triggers Playwright e2e tests

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants