feat(tandem): the layer on top of Main — brief delivery, the user-facing room signal, report-a-problem (abilityai/trinity-enterprise#498, abilityai/trinity-enterprise#363, abilityai/trinity-enterprise#499)

[dolho]

Journey Impact

Journey Impact: new: J11

A companion's brief reaches me where I already work, without me asking. Every other
journey is a promise the user reaches for; J11 is the first that reaches for them. J05
("I can schedule work, walk away, and find out what happened") ends at the executions list
— the operator's surface — so it does not cover this. Catalog row + regenerated
JOURNEYS.md + a strict=True xfail skeleton are in the diff; the harness is
#2565.

Summary

The Tandem layer (abilityai/trinity-enterprise#497), stacked on Main (ent#523). Three small
features that only make sense once every (user, agent) pair has one constant chat.

Based on dolho/issue-523 (PR #2558), which must merge first.

ent#498 — the brief lands in Main

A schedule names one Workspace user (agent_schedules.deliver_to_workspace_email); when it
fires, the output lands as a turn in that person's Main chat with the agent. API/MCP
only this cut — the schedule form is untouched.

Almost all of it already existed: report_completion is trigger-agnostic and schedule is
deliberately not in INLINE_CHANNEL_TRIGGERS, because a scheduled run has no surface
that already answered. The only missing fact was that a scheduled execution row never
carried source_channel='portal'. So this is a stamp and nothing else — no new delivery
path, no second applier, no terminal writer changed.

The scheduler carries the address only, for two independent reasons: it cannot import
the portal package to resolve a session, and it always sends execution_id, so
execute_task's channel-persisting branch can never run for a cron fire and channel columns
passed as kwargs would be silently inert (the #2426 class). execute_task_internal
resolves Main and stamps the pre-created row before dispatch.

• stamp_execution_channel_context is the first UPDATE of those columns — every other
  writer sets them at INSERT. Guarded on source_channel IS NULL, so it only ever adds
  a destination and can never repoint an inbound channel turn whose adapter is waiting on
  that reply.
• Access is checked against where the message will land — agent_on_roster(..., include_owned=True), the Workspace's own roster — not email_has_agent_access, which
  admits any admin; an admin who neither owns the agent nor is shared it cannot open that
  thread, so a brief delivered there would be invisible.
• Every refusal (blocked client, unreachable address, unreadable roster → fail closed,
  unavailable session, already-stamped row) fails the pre-created row with a named reason
  and releases the idempotency claim. A visible failure, never a silent no-op — running
  the turn anyway spends the tokens and puts the answer where nobody can read it.
• C9 — the portal leg now waits, bounded, on the ent#286 in-flight marker and then
  writes regardless. PortalConversation detects a reply by an assistant-row count
  delta, so a report landing mid-turn can be read as that turn's answer; deferring removes
  that for the common case, while a wait that could refuse would trade a cosmetic misread
  for a lost brief. Applies to every portal report, not only scheduled ones.
• At-most-once per fire is inherited, not rebuilt: the effect guard is keyed on the
  execution id and a fire is one execution.

ent#363 — the user-facing room signal

An agent woken in a room containing a human gets an explicit signal that a person outside
the fleet reads every line, plus guidance on what that changes. Filed theme-security, and
it is one: full transcript visibility is only safe while the agents know they are watched.

• Derived from membership (room_is_user_facing), never asserted by a participant.
  NON_HUMAN_PARTICIPANT_KINDS is the complement of "human" on purpose — a kind added later
  (ent#171's external A2A sender) is likelier to be a person than a machine, and an
  allow-list of human kinds would silently classify it as fleet-internal.
• The block names no participant: it is handed to every woken agent, so an address would
  be disclosed sideways to agents that person never addressed.
• Derived per wake rather than threaded from post_message (which does hold the list) —
  _wake_agent calls post_message back, so a threaded value could go stale when a reply
  recruits a human.
• An unreadable roster assumes a person is reading — the inverse of the usual capability
  default, because the mistakes are not symmetrical.
• The turn header stops claiming "Other agents and people are in this room" unconditionally.

ent#499 — report-a-problem

A thumbs-down raises a rate-bounded operator_queue item naming the agent, the person, what
was rated and their comment. ent#366's redaction is untouched: the operator sees the words,
the rated agent still does not.

• Routed through create_bounded_alert, never a direct create — the volume is driven by
  a client clicking, which is the agent-influenceable side of the bug: platform operator-queue alert emitters bypass #1632 ingestion caps — skill-not-found is agent-triggerable (flood residual, gates pull default-ON) #1677 classification. Its
  own registered type, because the budget counts pending rows of that type including ones
  other emitters wrote; reusing alert would let five unrelated alerts silence every problem
  report. Reserved id prefix so an agent cannot pre-create the id of a complaint about itself.
• Fires on every thumbs-down, not only commented ones: "this was not useful" is the
  report, the words are the elaboration, and gating on them means the quietest complaints
  reach nobody.

Two live bugs fixed on the way

Operator-queue items of an unrecognised type could never be closed. type is free TEXT
and the platform has emitted skill_not_found since #1410, but QueueCard.vue and
QueueItemDetail.vue each hardcoded an approval → question → alert chain and rendered no
control for anything else. For a budgeted type, five such items jam the pending cap
permanently — so ent#499 could not ship without this. Both cards now consume
utils/operatorQueue.js::queueResponseKind (the module that already declares itself the one
home of the controls-kind switch), whose unknown-type default moves from question to
acknowledge. An approval without options still gets a text box.

A test that has never run. test_ent362_workspace_participant.py's (human) assertion
called _render_transcript — a name that has never existed; the renderer is _format_delta
— behind a hasattr guard that skipped silently, leaving the exact labelling ent#363 builds
on unprotected. It now calls the real function and asserts the label discriminates.

Documentation

• requirements/scheduling.md §10.18; requirements/core-agent.md §5.24, §5.25, §5.26
• New flow feature-flows/schedule-workspace-delivery.md + the flows index
• architecture/workspace.md (a Tandem section) and architecture/database.md (the DDL)

Testing

• tests/unit/test_ent498_workspace_delivery.py — 38 tests
• tests/unit/test_ent363_user_facing_room.py — 15 tests
• tests/unit/test_ent499_problem_report.py — 17 tests
• src/frontend/tests/unit/operatorQueueUnknownType.spec.js — 9 tests
• tests/journeys/test_j11_brief_delivery_journey.py — the J11 skeleton
• Two inventory guards fired and were satisfied with justified entries: the bug: recovery paths write execution terminals without closing the paired activity — agent shows as running for up to 2h, then logs a fabricated 120-min failure #1804
  terminal-activity allowlist (admission-path terminal) and _EXPECTED_UPDATE_SITES
  (non-status writer). MCP tsc --noEmit clean.

Upgrade note for anyone who ran #2558 before its dev merge

0053_portal_session_main_chat was renamed to 0054 when #2561 landed
0053_user_ui_preferences on the same parent — two revisions sharing a
down_revision is two heads, and alembic upgrade head is singular, so a forked
graph applies zero revisions.

A database stamped with the old id crash-loops the backend on boot:

alembic.util.exc.CommandError: Can't locate revision identified by '0053_portal_session_main_chat'

The DDL the two revisions apply is identical, so the marker is re-stamped, not the
data:

UPDATE alembic_version SET version_num='0054_portal_session_main_chat'
 WHERE version_num='0053_portal_session_main_chat';

This affects local branch checkouts only — 0053_portal_session_main_chat
never reached dev or main, so no deployed instance can hold it. Hit on my own
dev stack while bringing it onto this branch.

Not in this cut — stated so it is not inferred from the merge

• No schedule-form UI for the delivery target (API/MCP only, by decision).
• Rooms are not a delivery destination, and there is no agent-initiated post_to_room —
  both remain trinity-enterprise#442.
• Delivery is durable, not live-pushed: the Workspace does not poll thread history, so a
  brief appears on the next load or thread switch. Acceptable at daily cadence.
• create_item has no UPDATE path, so an edited rating comment does not reach an item
  already raised — the same residual ent#434's alert carries; the fix belongs at the sink.

Fixes abilityai/trinity-enterprise#498
Fixes abilityai/trinity-enterprise#363
Fixes abilityai/trinity-enterprise#499
Related to #2565

🤖 Generated with Claude Code

https://claude.ai/code/session_01WLerYYUUEEmf43UKF2VVRY

[dolho]

/review — #2568 (self-review + independent adversarial pass)

I wrote this code, so a self-review has an obvious blind spot. I ran an independent
adversarial pass over the merge-base diff alongside my own and reconciled the two.
It found three real defects, two of them disclosures. All three are fixed in
48a2f5c4; I verified each myself before acting rather than taking the finding at
face value.

Scope: 43 files, +2245/−34 against merge-base 95e42030.

---

[C1] The complaint travelled back to the agent it was about — FIXED

raise_problem_report's docstring promised "the operator sees the comment; the
agent still does not". Two pre-existing consumers of operator_queue
falsified it, and neither sits anywhere near the emitter:

# services/operator_queue_service.py — _write_responses_to_agent
for resp in responded_items:
    requests.append({..., "question": resp.get("question", ""),
                          "context": resp.get("context"), ...})

# db/operator_queue.py — get_responded_items_for_agent
and_(operator_queue.c.agent_name == agent_name,
     operator_queue.c.status == "responded")      # ← no origin filter

So: operator clicks Got it → status becomes responded → within one 5s sync
cycle the item's question (the client's address and verbatim words) is written
into ~/.trinity/operator-queue.json on the rated agent, which reads that file
routinely. And separately:

# routers/operator_queue.py
if item:
    operator_resume_service.spawn_resume_dispatch(item, ...)
# services/operator_resume_service.py
f"Question: {item.get('question') or item.get('title') or '(none recorded)'}",

"Got it" posts to /respond like any other answer, so on an agent with
operator_resume_enabled (ent#329) acknowledging spends one of that agent's
turns on a prompt containing the complaint. Both the ent#366 disclosure this
feature exists to avoid, and an untrusted-text-into-prompt path.

It also falsified my own comment in operatorQueue.js, which argued acknowledge
was safe because "under ent#329 an answer can spend a turn" — acknowledge is
an answer.

Fix, at the sink rather than the emitter. Both paths exist to close a loop the
agent opened: it parked a question, a human answered, the answer returns. A
platform alarm opened no such loop, and for a problem report the agent is the
subject. One shared predicate, is_platform_minted, keyed on the reserved id
prefixes that already mean "an agent may not mint this" (#1632), gates both so they
cannot drift. It discriminates — an agent-authored item still round-trips, or every
parked question would silently go dead — and that discrimination is tested.

skill_not_found has ridden these same paths for months without harm because its
body is platform text about the agent's own missing skill. This is the first
budgeted type whose body is third-party PII, which is what made the class bite.

Also narrowed the alert's context to identifiers — no comment text, no address.
The operator reads who is unhappy from question; context is the field most
likely to be forwarded or logged.

[C2] ent#363 fired in every room, including an operator's own — FIXED

The ticket says, three times, "a room containing a workspace user". I
generalised it to "any non-agent kind", with a comment arguing the complement was
safer for future kinds. Half right — an unrecognised kind is likelier to be an
outside person — but it swept in the platform user, i.e. the operator.

That is not cosmetic, because the generalisation is unfalsifiable in production:

creator_kind, creator_identity = _caller(current_user)   # create_room, always seats them
removed = db.remove_participant(room_id, "agent", agent_name, ...)  # the ONLY removal path

A human participant can never leave. So every room was client-facing, the
else branch was unreachable, and an operator's own ops room got its agents told
to "keep platform mechanics out of it — infrastructure, container and model
internals, costs and token spend, queue and scheduling plumbing" — the subject
those rooms exist for.

And nothing could catch it: I had shipped test_a_platform_user_makes_the_room_user_facing
asserting the generalisation, and every other test fed room_is_user_facing
synthetic dicts rather than the shape create_room emits. That test is now
inverted and joined by one driving the real constructor's shape.

This is the second instance of this shape in one session — an implementation
changing a stated requirement, with a comment justifying it and a test pinning it.
The first was ent#523's archived-tab rule. Logged as a class in learnings.md.

[C3] The refusal terminal skipped the secret-scrub seam — FIXED earlier (9edb2d63)

Caught not by review but by the suite, and only because I dispatched it manually:
test_ent279_scrub_parity went red on head across all three seeds while every
other check stayed green. _fail_execution_row persisted an error via
update_execution_status without passing it through runtime_secret_scrub.

Scrubbed rather than allowlisted, though an allowlist entry would have been
defensible (the only caller passes a platform-composed string, pre-dispatch — the
shape the guard already allowlists for _admission_gate). An allowlist entry is
pinned to a function name, and that signature takes an arbitrary error: str,
so it would silently extend the exemption to a future caller that does pass agent
output.

---

Findings I checked and dismissed

• literal_eval-style narrow except — not applicable here, but the same
  instinct: I nearly filed the queueResponseKind default change as risky before
  enumerating its consumers. All four (QueueCard, QueueItemDetail,
  MobileAdmin ×2, PortalAsks) still reach every branch; PortalAsks cannot see
  an unknown kind at all (client_portal/asks/service.py filters to
  ("question","approval","alert")), and buildQueueResponse is untouched.
• The stamp is not a TOCTOU. stamp_execution_channel_context is a single
  UPDATE … WHERE id = :id AND source_channel IS NULL returning rowcount > 0 — a
  real CAS — and the caller refuses on a lost race rather than assuming.
• The recipient check cannot disagree with the stamp. source_channel_client
  and source_channel_chat_id both derive from the same normalised address, and
  both create_portal_session and get_main_portal_session_id lower-case it, so
  _norm_email(context_client) != _norm_email(client_email) cannot fire on a case
  difference.
• The bounded in-flight wait is correctly scoped. report_completion has one
  caller, spawn_completion_report, reached only from three spawn_* sites — no
  request-serving coroutine awaits it.

Known residuals, stated rather than buried

• resolve_and_stamp runs synchronous DB calls on the event loop. It widens an
  exposure the same handler already has (idempotency_service.begin writes
  synchronously two lines above), and the canonical use case fires at ~03:30 UTC
  when db_backup_service holds SQLite's lock. Worth a follow-up; not worth
  blocking on, since it is pre-existing on this path.
• A cancellation inside the ≤120s in-flight wait loses that report.
  CancelledError is a BaseException, so except Exception does not catch it and
  nothing re-applies the terminal. My comment claims "never dropped, only deferred"
  — true of the timeout path, not of a restart landing in the window.
• A resolved complaint suppresses later ones about the same target.
  ON CONFLICT DO NOTHING ignores the existing row's status, so once acknowledged
  that person cannot raise another report about that target. Same shape as the
  documented edited-comment residual; the fix belongs at the sink.
• A shared (non-owner) user can schedule a delivery into another roster member's
  Workspace. Schedule creation is assert_agent_access, not owner-only, and
  allow_proactive is not consulted. Bounded by roster co-membership, so not
  cross-tenant — but it is a third party the ent#457 "no third party to protect"
  reasoning did not anticipate. Worth a decision before this reaches a customer.

Acceptance criteria

All three tickets' ACs are met. Two I had marked done on reasoning and have since
closed with evidence: ent#498's "stated in the user docs" (now in
docs/user-docs/automation/scheduling.md) and "rateable like any agent message"
(now pinned from both ends, including a discriminating negative case).

Two deliberate deviations, both stated in the PR body rather than inferred:
ent#499's alert fires on every thumbs-down rather than only commented ones, and
the item does not carry the "acted on at the next wake-up" wording, because ent#329
has shipped and is per-agent opt-in.

Behavioural proof of C2, on a live stack

Before the fix, in an operator's own room (creator = a platform user, plus one
agent), asking the agent about token spend produced hedging — it had been told to
keep costs and platform internals out of the conversation. After it:

"Rough estimate: my last response was around 150–200 output tokens. The input
context — system prompt, CLAUDE.md, conversation history, all the system
reminders — was probably 3,000–5,000 tokens."

Direct, in the room where that is exactly what the operator wanted. The signal now
fires only where a workspace client is present.

Verification

Backend pytest matrix green on head across all three seeds with the regression
diff clean on the run covering the scrub fix; the run covering the three fixes
above is in flight as I post this and I will report it below; 361 passed locally across every affected suite; frontend 96 files /
2158 tests; vite build clean; tsc --noEmit clean on the MCP server. All three
features exercised end-to-end on a live stack against PostgreSQL, including the new
Alembic revision applying to a real database.

🤖 Generated with Claude Code

https://claude.ai/code/session_01WLerYYUUEEmf43UKF2VVRY

[dolho]

/review — re-review of #2568 (b85cad25)

Six defects have been fixed since the first pass. Two of them were in the fixes
themselves, which is the part of this worth reading — the residual list I posted
was not a to-do list I could work through mechanically.

From the review: three defects, all fixed

C1	the complaint travelled back to the agent it was about	48a2f5c4
C2	ent#363 fired in every room, including an operator's own	48a2f5c4
C3	the refusal terminal skipped the secret-scrub seam	9edb2d63

C2 has a behavioural proof on a live stack: in an operator's own room the agent now
answers "my last response was around 150–200 output tokens; the input context was
probably 3,000–5,000" — direct, where before it had been told to keep costs and
platform internals out of the conversation.

From the residuals: four more, all fixed (74a2e79b)

A shared user could deliver into a colleague's Workspace. I posted this as
needing your decision. It didn't — the safe rule costs nothing. Schedule creation is
assert_agent_access (owner or shared or admin) and the target may be any roster
member, so a merely-shared user could schedule a recurring message, with a prompt of
their choosing, into a colleague's Main chat as an ordinary turn from the agent. Rule
now: address yourself freely, address anyone else only as the owner — which leaves
the common self-service case open to shared users. On create and update, because
create-only is a formality (create without the field, PUT it a second later).

A resolved complaint suppressed every later one about the same target.
ON CONFLICT DO NOTHING ignores the existing row's status, so once acknowledged that
person could never report that target again — silently, forever, which is worse than
a duplicate. Id quantised to the UTC day (ent#434's bucketing).

A cancellation inside the in-flight wait lost the report, and two synchronous DB
paths ran on the event loop — resolve_and_stamp (4–6 blocking calls, two of them
writes) and the marker read (a blocking Redis GET up to 60× per report). Both moved
to asyncio.to_thread; the delivery case fires at ~03:30 UTC, inside the window
where db_backup_service holds SQLite's lock.

The two the fixes introduced

[F1] The authority gate was broken, not merely narrow (4df4dd72).

can_own = db.can_user_share_agent(str(current_user.id), name)   # ← id

def can_user_share_agent(self, username: str, agent_name: str) -> bool:
    user = self._user_ops.get_user_by_username(username)
    if not user:
        return False

An id finds no user → False → the owner is refused too. A gate meant to narrow
who may address a colleague would instead have blocked everyone, including the person
it exists to permit. Every other call site in the codebase passes
current_user.username.

All six tests I wrote for that gate stubbed can_user_share_agent, so every one
passed against the broken argument. The test that catches this inspects what is
passed rather than what comes back — a shape none of the others had.

[F2] The cancel fix was itself unreliable (b85cad25).

After catching CancelledError it fell through to await asyncio.to_thread(_write).
But a task is cancelled because the loop is going away, so planning to reach another
await point is planning on the thing that just stopped being available. _write is now
hoisted above the wait and called synchronously in the handler, then the
cancellation is re-raised — swallowing it would leave the task running against a
closing loop and rob the caller's shutdown path of its exception.

A pattern worth naming

Three times on this branch a structural test failed because I sliced source on a
neighbouring token — and each time that token appeared inside a comment explaining
the very thing being asserted: create_operator_queue_item named in a docstring to
say why it is forbidden; def _write() after I moved it; except Exception inside
the cancel handler's own note about why it does not catch. All three are now ast
reads. A structure question deserves a structural read; string-slicing over commented
code produces a test that fails for reasons unrelated to its subject.

Both review classes are recorded in docs/memory/learnings.md: a new item on a
shared queue inherits every consumer that queue already had, and generalising a
requirement's noun is a deviation, and a conditional that can never be false is how
you find out.

Still standing — stated, not buried

• create_item has no UPDATE path, so an edited comment does not reach an item
  already raised that day. Shared with ent#434; belongs at the sink.
• _fail_execution_row's pre-read is redundant — db/schedules/executions.py
  already guards non-success terminal writes inside the transaction. Harmless, and I
  left it rather than widen the diff.
• The agent-only room branch is now reachable but only via an operator-created
  room; a room whose creator is a workspace client is always client-facing, which is
  correct and worth knowing when reading room_is_user_facing's tests.

Verification

Green: 361 backend tests locally across every affected file; frontend 96 files /
2158 tests; vite build clean; MCP tsc --noEmit clean; all 13 PR checks including
pg-migrations, schema-parity, e2e and gitleaks. All three features exercised
end-to-end on a live stack against PostgreSQL — the new Alembic revision applying to
a real database, a real scheduled brief landing in a Main chat, a thumbs-down raising
a queue item, and the ent#363 signal correctly absent from an operator's own room.

Still running as I post this: the backend unit matrix on b85cad25
(run 34128948926). The previous matrix was green on head across all three seeds
with the regression diff clean, on 48a2f5c4 — every commit since is the residual
fixes plus their tests, all of which pass locally, but I have not yet seen a full
matrix on the final commit and am not claiming one. I will report it here either way.

Note on this PR's CI: backend-unit-test.yml gates pull_request on
branches: [dev, main], and this PR is stacked on dolho/issue-523 — so the unit
matrix does not run automatically here and every result above came from a manual
workflow_dispatch. Once #2558 merges and this rebases onto dev, it runs on every
push. Worth knowing when reading the green check list: pg-migrations and
schema-parity cover the migration, but the ~90 new tests are not in it.

Out of draft at the operator's request; #2558 still merges first.

🤖 Generated with Claude Code

https://claude.ai/code/session_01WLerYYUUEEmf43UKF2VVRY

[dolho]

Final matrix: green ✅

The run I flagged as outstanding in the re-review above has completed on b85cad25
— run 34128948926:

conclusion: success
  lint (sys.modules pollution check): success
  pytest (base, seed 12345):  success      pytest (head, seed 12345):  success
  pytest (base, seed 67890):  success      pytest (head, seed 67890):  success
  pytest (base, seed 99999):  success      pytest (head, seed 99999):  success
  regression diff:            success

regression diff is the one that matters here: it compares head against base across
all three seeds and fails on any test failing under HEAD that did not fail under
BASE. It is what caught the ent#279 scrub regression earlier in this branch, and it
is clean.

Every claim in the re-review is now backed. Nothing outstanding on my side.

[vybe]

Validated via /validate-pr: docs (requirements §5.24–5.26, scheduling §10.18, flow + index, workspace/database architecture), both migration tracks (renumbered to Alembic 0056 off 0055_portal_session_main_chat in the dev merge), security greps clean, 70+ named tests. Merging.