feat(workspace): addressed asks end-to-end in OSS — SQL narrowing, the agent-page leak, and the module itself (ent#428)

[dolho]

The OSS half of ent#428 — the read path for operator_queue.addressed_to_email (shipped in #2300), and the two readers that needed it. One of those turned out to be leaking.

Two commits

1. The primitive. list_items grows an optional addressed_to_email SQL condition.

Not a performance change. list_items orders by status → priority → age and applies limit before the caller sees a row, so filtering the addressee out of the result means "the newest N pending items in the FLEET, of which some happen to be yours". One person's low-priority ask leaves the surface that addressed it as soon as the fleet is busy, while still sitting pending — and by construction nobody else may answer it.

2. The leak /review found. client_portal/agent_page.py::_asks — the client-facing "Waiting on you" block — was scoped by agent_name alone. One agent is routinely shared with several people, so that scope was never the audience; it was the only scope available before ent#364 added the addressee. Reproduced before it was believed:

BOB SEES: [('Invoice Acme at the agreed discount?',
            'Alice, confirm the Q3 discount before I send it.')]

Two clients co-shared on one agent; the second reads the first's ask verbatim. The file already withheld context as a known leak surface, which is what makes it deceptive — it looks like a reader that has thought about disclosure. title/question/options are agent-authored free text and are exactly where an ask meant for someone else says something not meant for this reader.

Pre-existing on dev since ent#364 — that change added the column, its validation and three renderings that honour it, and never taught this older reader. Fixed here rather than filed, because this is the PR that adds the primitive it needs.

Decisions a reviewer should actually check

• viewer_email is required, not defaulted. A default is how the next caller silently gets the unfiltered list back. The two test_ent360 failures this caused were signature-only — both stub the query out, so their subjects (alert-type exclusion, context never forwarded) are untouched.
• Unaddressed operator asks stop rendering on the agent page. Intended, not fallout: it is a client-facing page, an operator ask is agent-authored text written for the operator, and a client cannot act on one from there anyway ("reply in chat" is the only affordance). Operators keep the full queue in Operations, and the page now agrees with what the Workspace's other ask surfaces show that same person.
• The filter fails CLOSED. Every other filter in list_items uses truthiness, so a falsy value means "don't filter" — for this argument that would turn a caller which lost its email into one that sees everyone's asks. None still means no filter (the operator listing); "" matches nothing. The divergence is commented at the condition, since it reads like an inconsistency otherwise.
• Case-insensitive. The ingestion boundary lowercases before storing (_validated_addressee), so every stored value is already lower — but create_item is a public writer and a read must not silently depend on every future caller remembering that.
• respond_to_item(responded_by_id) annotated Optional[str]. It is a users id, and an ask answered by someone with no platform account has no row there. NULL id + the answering email is what distinguishes "answered by a client" from "answered by an operator whose account was since deleted", which keeps its id. No behaviour change — nothing in this repo passes None yet.

Third commit — the module itself is OSS now

workspace_asks was built as an entitled private module. On the standing rule that everything about the Workspace lives in OSS, it moved here: src/backend/client_portal/asks/, mounted unconditionally in main.py, no requires_entitlement, no registered feature id. Same reasoning as the Workspace itself (ent#356) and rooms (ent#443) — PortalAsks.vue, store.fetchAsks() and store.asksAvailable ship in every build and self-disable on a 404, so a community install rendered the ask affordance and then refused it.

Under client_portal/ rather than a new top-level package: it is a client-portal surface, on the client-portal prefix, owning no table — and it inherits client_portal's Dockerfile COPY line instead of needing its own. A new top-level package that main.py imports at module scope builds a clean image and dies at import; that has now been #1033, ent#356 and ent#443.

Verbatim port — service and models unchanged, router loses its entitlement dependency, service loses FEATURE_ID. The /api/enterprise/client-portal/asks prefix stays: ent#83 published it as the headless integration surface and the shipped bundle calls it, so renaming breaks a client for nothing.

Transition-safe, proven live on a pure-OSS build with an un-bumped submodule — both routers mount and the ungated OSS one wins:

/…/asks | client_portal.asks.router                | ['get_portal_principal']
/…/asks | enterprise.backend.workspace_asks.router | ['requires_entitlement…', …]
entitled features (OSS_ONLY): []

The suite moves with it (tests/unit/test_ent428_workspace_asks.py, 22 cases), unchanged beyond import paths and one path calculation, plus three the ported ones structurally cannot see: the routes answer with no entitlement; nothing calls requires_entitlement/register_module (parsed, not grepped — a docstring may still say it used to be gated); the mount precedes the seam.

That last one is anchored on the call, not str.index of the name — main.py mentions register_enterprise(app) in prose above it, so a substring match finds the comment, and it false-failed here on the first run. #2355 carries the same weaker form; it can only false-fail there, never false-pass, and is worth tightening separately.

Not touched

No migration, no route signature change, no new top-level package (so no Dockerfile change). One frontend file is touched — comments only, correcting two that explained the 404/403 guard as "the module is enterprise-gated"; the guard itself still belongs, for an older backend. Both OSS operator-queue routes pass explicit kwargs (routers/operator_queue.py:73, :296), so the new parameter is unreachable from a query string and a platform caller's view of the queue does not move — pinned by test_no_addressee_argument_leaves_the_operator_listing_alone, which is green with and without this diff, deliberately.

Tests

Seven new cases in tests/unit/test_ent364_addressed_asks.py. Six fail without the source change, verified by stashing it:

FAILED test_the_read_path_narrows_to_the_addressee
FAILED test_the_addressee_filter_is_case_insensitive
FAILED test_an_ask_is_not_crowded_out_of_its_own_window
FAILED test_an_empty_addressee_matches_nothing_rather_than_everyone
FAILED test_the_agent_page_does_not_show_one_client_another_clients_ask
FAILED test_the_agent_page_does_not_show_a_client_an_operator_ask

The crowd-out test asserts up front that its own fixture really pushed the ask out of the unfiltered window — a crowd-out test whose fixture doesn't crowd out passes for the wrong reason (my first attempt did exactly that).

Local: portal/queue slice → 678 passed, 1 skipped; guard sweep (centralized|parity|invariant|architecture|wiring|1310|186|293|926|enumeration) → 816 passed, 3 skipped.

Also exercised end-to-end against a real running instance — a pure-OSS build (edition=oss, enterprise_features=[]), two clients signed in through the actual OTP flow, asks raised through the real ingestion boundary. Alice sees hers on both surfaces, bob sees [] on both, the seeded sk-live-… in context appears 0 times, bob answers alice's ask → 404, alice → 200, alice again → 400, audit row responded_by_id=None / responded_by_email=alice@…, and revoking alice's share mid-session emptied her list with no restart. The operator's own /api/operator-queue view was unmoved.

Follow-ups recorded, not silently dropped

• docs/memory/learnings.md — the durable class: a column introduced to narrow who sees a row obliges you to grep every existing reader of that table, because a reader written before the column either filters or discloses, and doing nothing is a choice for the second.
• debt:2026-08-21-workspace-agent-page-duplicate-asks — on an entitled install the agent page now renders the same ask twice (the gated answerable block, and this read-only one). Pre-existing and merely exact now; which block survives is a frontend/product call, so it is not folded into a backend PR.

Merge order

No longer coupled. trinity-enterprise#427 reduces to the design of record (its implementation is here now), so it neither blocks nor is blocked; the submodule bump only picks up a removed registration, and nothing breaks if it lags, because the OSS routes win the match order either way.

Related to ent#428.

🤖 Generated with Claude Code

Second review pass

/review run again after the module move found four more, all created or exposed by the move rather than present in the ported logic — every one fixed in-branch:

1. architecture.md:1241 called the surface "the entitled workspace_asks module". A public doc calling a public module paid is the wrong direction of wrong.
2. stores/clientPortal.js explained its 404/403 guard as "the module is enterprise-gated". Guard still belongs (older backend); the stated reason would have told a reader asks are paid. Comments only.
3. asks/models.py still said Private.
4. An N+1 the move promoted to an OSS polled endpoint — list_asks called the roster check per item, which is 1–2 DB reads each, for an answer that cannot change within one request, on an endpoint polled every 20s per client per tab.

The first attempt at (4) was wrong and the tests said so: hoisting roster_agent_names out of the loop turned six red, because the suite's seam is agent_on_roster — which is the access predicate, and re-implementing membership beside it is how the two drift. Redone as a per-request memo over that same predicate. Pinned on call count, not timing, and non-vacuous:

AssertionError: roster consulted 8 times for 8 asks across 2 agents

[vybe]

Validated after two rebases onto dev. All 22 non-skipped checks pass; regression diff clean across all six seeds (base 12156 → head 12195, 0 failures either side, No new failures). e2e ran and passed (5m6s) despite the absent ui label, so the frontend half is exercised — better than the merge gate requires.

Packaging. src/backend/client_portal/asks/ is a nested package under client_portal/, which docker/backend/Dockerfile already COPYs as a directory (recursively). So no Dockerfile change is needed — and this is worth stating explicitly, because the sibling case one PR over (shared_sessions, a new top-level package in #2355) did need a line and crash-looped prod-image-smoke without it. Top-level packages are listed one per line; nested ones ride their parent. prod-image-smoke green here confirms it.

Substance. The read path for operator_queue.addressed_to_email, plus the two readers that needed it — and the honest part of this PR is that one of them was leaking: the agent page listed every client's asks rather than the viewer's. list_items growing an addressed_to_email SQL condition is correctly framed as a correctness change, not a performance one — the listing orders by status → priority → age and applies limit before the caller sees a row, so filtering in the caller means "the newest N pending items, then discard", which silently drops a client's older ask behind an unrelated flood. Filtering in SQL is the only shape that returns the right rows.

Tests: test_ent428_workspace_asks.py, test_ent364_addressed_asks.py, test_ent360_workspace_agent_page.py (the leak's named regression), plus workspaceAsks.spec.js on the frontend. architecture.md updated.

Rebase note. Conflicted twice on docs/memory/learnings.md — after #2333 and again after #2357 — both pure append-vs-append at the same insertion point. Resolved keep-both, ordered by entry date. Verified the resulting out-of-order positions are byte-identical to origin/dev's own (the file has pre-existing ordering breaks at 2026-07-08/07 and 07-15/12 among others), so the resolution added entries without perturbing anything.

Security scan clean (Client@Example.COM is a test fixture). No new env var, no host paths, no mode flips.

Cross-tracker note: references ent#428/ent#429 with no closing keyword, and the automation is same-repo only — so the private issues need their status-in-dev label set by hand. Doing that now.