feat(workspace): agents at the centre — the pinned Main chat, Reset, and files onto the conversation (abilityai/trinity-enterprise#523, abilityai/trinity-enterprise#524)

[dolho]

Journey Impact: extends J04 — the execution lifecycle, via the parent epic abilityai/trinity-enterprise#472. Workspace chat itself still has no journey in the current deck — the same finding as ent#451 / ent#472 / ent#523.

Fixes abilityai/trinity-enterprise#523
Fixes abilityai/trinity-enterprise#524
Fixes abilityai/trinity-enterprise#468

Summary

Two rulings from the 2026-09-06 operator session, in one PR because ent#524's drop target lands on the very surface ent#523 rebuilds and the operator asked for one design pass over both.

ent#523 — agents at the centre. Clicking an agent opened a report about it, with the conversation one click further behind Start a chat. Ruled inverse 2026-09-05 ("make agents the central entity, so people think of the agents they talked to"), design approved 2026-09-06 (board A3). Clicking an agent now opens the chat you were last in; every (user, agent) pair gets one pinned Main chat — the place the agent reaches you — and Reset archives it and starts the agent cold.

ent#524 — files onto the conversation. The one surface people work on was the one surface you could not drop a file onto, and both existing upload paths silently discarded every file after the first.

ent#360's reasoning is not reverted: an agent still has a home with its history, what it can do, and a place to ask you something. It is simply no longer a stop on the way to the conversation.

Main and Reset

enterprise_portal_sessions gains is_main and archived_at on both tracks (SQLite portal_session_main_chat + Alembic 0053), plus the partial unique index idx_portal_sessions_main.

• The index is the invariant, not an optimisation. ensure_main_session is reachable from two request paths and runs in every uvicorn worker, so a check-then-insert races two Mains into existence for one pair — after which "the pinned first tab" has no single answer. The loser catches IntegrityError and adopts the winner's row.
• WHERE is_main = 1 is load-bearing. An archived row keeps its (agent_name, client_email) pair forever, so an unconditional unique index would refuse the second Reset.
• No backfill (the ent#473 title_source precedent one revision back). Backfilling would have to anoint one existing thread per pair, and "whichever was most recent when we migrated" is not a fact anyone asked for. Main is minted lazily by list_sessions and _resolve_session_id, and deliberately not by the cross-agent batch (bug: Agent Detail and Workspace over-fetch on load (21 redundant requests, N+1 roster) #2198), which runs on every sidebar refresh and would write a row per agent the person never opened.
• Reset needs no second reset primitive. A fresh row carries no cached_claude_session_id and the turn engine resumes only on a cached id, so cold is the new row's property rather than an action against the old one. routers/sessions.py::reset_session_memory is untouched and uncalled — clearing a cache and keeping the thread is a different verb from retiring the thread. The archive keeps its own cached id (still resumable, still in session_cleanup_service's keep-set) and its own title. Per-user memory (MEM-001) is not touched. No confirmation dialog (operator, 2026-09-06 09:27) — ConfirmDialog is not a caller.
• Refused with a named 409 while a turn is in flight (turn_in_flight) or when a concurrent Reset won (reset_raced). Resetting an untouched Main is a no-op reported as archived_session_id: null — archiving anyway mints an empty thread per click and files it under a name nobody chose.
• The landing rule is one edit. _resolve_session_id(agent, email, None) resolves to Main, which covers an agent-initiated message, an ask raised outside a chat (ent#364/refactor: collapse 9-path cleanup pyramid once agent is authoritative #429) and a scheduled brief (ent#498) — all three already funnel through it. An explicit session id still wins.

One page

PortalAgentPage.vue is dismantled, not deleted — every section has a named home, so "no capability is lost" is checkable rather than asserted:

Was on the agent page	Is now
stats strip + Activity chart	PortalAgentBand.vue, always visible above the thread
Your chats / What it can do / Reports	PortalAgentDetails.vue
Canvas · Files	already rail tabs (ent#475)
Recent work / Activity	already the rail's Work tab (ent#525)
asks	the conversation's mount — the surviving one after #2449
health + availability	the details header, still two separate facts (#2196)
Start a chat	gone; the row opens the chat

• Agent details is a sibling of the rail, not a rail tab (ruled 2026-09-05): the rail is participant-scoped with a fixed five-tab set, this is about one agent and is dismissed rather than switched away from. portalRail.js is untouched; the rail's state is a setup ref, so closing details returns it on the tab it was showing.
• landingThread is the ONE rule for which chat you land in, and the ?agent= deep link's resolveAgentLanding now defers to it. It used to take the first row of a sorted list — which agreed with "most recent" by accident, and an unused Main sorts last on recency, which is exactly where that accident would have surfaced.
• Main is named by its role in the tab strip and the header and is not renameable: it is the same thread for the life of the pair, and a derived or typed title would make the two disagree about which chat you are in.
• Archived chats leave the tab strip (Reset would otherwise add a permanent tab per use) and stay in the sidebar and in details. An unused Main is filtered from the sidebar only — a projection, not a filter on threads, because the strip must show Main from the first visit.
• The roster is ordered before the collapse; bounding first would sort a slice chosen by the old order. This is not ent#491 (incubating) — it ships the order the AC states and leaves primaryName as that issue's seam.
• The composer labels an unavailable agent, never disables: a client whose agents are all stopped gets an inert Workspace otherwise.

Files onto the conversation

composables/usePortalFileDrop.js is the ONE implementation, used by the conversation, the room and the rail's Files tab — the issue forbids a second, and the reason is in the defect: the gesture already existed on the Files panel and the [0] bug existed there too, because each surface had written its own.

• both <input type="file"> gain multiple; no path reads [0]
• one chip per file with its own progress and outcome; a refused file names itself and the limit; a 429 batch says which files landed and when to retry
• uploads run sequentially — twenty parallel requests is the surest way to trip the per-email limiter (ent#287) on a gesture that would have succeeded spread over a second
• a room's drop fans out to every participating agent's inbox and the chip names the recipients (operator decision 13)
• dragenter/dragleave are depth-counted (they fire per child element); the overlay is pointer-events-none so it cannot swallow the drop it announces; isFileDrag keeps a dragged link or text selection from lighting it
• the destination stays the caller's upload, so ent#484/fix(security): patch 4 Dependabot alerts (happy-dom RCE + vite file read) (#485) #486's working folder can take it over without the gesture changing

The #1927 ratchet caught v-if="f.uploading" and was right to — a scanner cannot tell that from the bare fetch-in-flight gate it exists to stop. Fixed the way the ratchet asks rather than by renaming: a chip has three outcomes and no fourth, so both surfaces render from one derived attachmentState, and PortalConversation's baseline entry drops 1 → 0.

An answered ask says whether work started (ent#468)

ent#468 asked for a decision, render or drop. Render — recorded on the issue with its reason. Dropping loses a fact the person is entitled to: on an operator_resume_enabled agent their answer sets real work in motion and spends the owner's budget, and the client causing that spend was the one party getting no acknowledgement. ent#364's AC ("the answer reaches the agent and it resumes") was true in the backend and invisible in the product.

• portalUtils.js::answerConfirmation consumes both fields, which is that issue's "either both or neither": status === 'answered' is the gate, resume_requested is the wording.
• Opt-in ON → "Sent — <agent> is picking this up."; OFF / false / absent → "Sent." The tense follows _resume_requested's own contract — a report of intent, since the dispatch is backgrounded — so never "has done it". Reading null as "started" would re-introduce the over-claim ent#430 spent a blocker removing.
• The confirmation cannot live on the ask row, because answering removes it — that AC bullet is the structural difficulty. PortalAsks.visible gated on items.length > 0, so the surface unmounted at the same instant the confirmation was created and the message would have rendered for zero frames. It now stays mounted while one is up, clears itself, and clears its timers on unmount (this surface unmounts on every chat switch).
• No backend change — the fields were already correct and already on the wire. This is the consumer they were missing.

Folded in here because it lands on the same surface: PortalAsks renders above the composer of the conversation ent#523 rebuilt.

Changes

• Backend: client_portal/{db,service,router,models}.py, db/{schema,tables,migrations}.py, migrations/versions/0053_portal_session_main_chat.py
• Frontend new: composables/{usePortalAgentPage,usePortalFileDrop}.js, portal/{PortalAgentBand,PortalAgentDetails}.vue
• Frontend edited: views/Portal.vue, portal/{PortalConversation,PortalRoom,PortalSidebar,PortalRailFiles}.vue, portal/portalUtils.js, stores/clientPortal.js
• Frontend deleted: portal/PortalAgentPage.vue
• Docs: requirements §5.23 (and a pre-existing duplicate §5.21 fixed), new feature-flows/workspace-agents-at-the-centre.md + both index entries, architecture/workspace.md, workspace-agent-page.md marked superseded with the mapping, workspace-chat-tabs-and-titles.md closed out
• ent#468: portal/portalUtils.js (answerConfirmation), portal/PortalAsks.vue
• Tests: test_ent523_main_chat.py (new, 22), portalAgentsAtCentre.spec.js (new, 48), ten existing specs re-pointed

Ten specs re-pointed rather than deleted. Where a rule MOVED, the guard follows it (portalRatings, portalReportsRendering, portalAvailabilityChip, portalAskSingleSource). Where a rule was RETIRED on purpose, the guard asserts the replacement and names the old one, per the #2169 convention in that file (portalAgentPageUx's two-column Overview guards). Where a guard pinned a v-if / v-else-if spelling on a chain whose membership this changes, it now asserts the rule — keyed on the verdict, branches are its v-else — not the ordinal (portalRail, portalLoadingTreatment, workspaceRoomsGate F23, portalRosterRow, portalSidebarSearch).

Test Plan

• pytest tests/unit/test_ent523_main_chat.py — 22 passed. Both migration tracks and the index predicate; ensure_main_session idempotency + the lost-race path against a real sqlite carrying the real partial index; the landing rule through _resolve_session_id and ensure_thread_for_ask; Reset's archive/mint/system-line, cold-by-construction (asserting the ARCHIVE keeps its cached id), the in-flight 409, the untouched-Main no-op, repeatability, uniform 404. The index DDL is read out of schema.py rather than retyped, so the test cannot pass against an index the product no longer creates.
• Neighbours: test_ent451/473/525/358/364, test_2196, test_2198 — 254 passed, and the one break was a test asserting the rule this PR deliberately reverses (updated, not deleted).
• npm run test:unit — 2036 passed (90 files). Both ratchets green: loading-gate baseline paid down 1 → 0 and diffed (nothing grew); raw-color measured against origin/dev — no touched file grew raw_nongray or hardcoded_colors (0 everywhere), only gray chrome, which the scanner itself calls partially sanctioned.
• vite build clean. New spec mutation-checked: removing the Main pin fails 2 of its assertions.
• Live on the Docker stack (backend --reload, PostgreSQL): migration applied with the partial index present; Main minted on first open and pinned first; Reset archives with the title kept, mints a cold Main and writes the system line; a second Reset works (the predicate); reset on an untouched Main is a no-op; unknown agent → 404; exactly one live Main in SQL. In the browser: clicking the agent lands in the conversation with no Start-a-chat button, band shows stats + chart + window + Agent details, Main is the first tab, the archive appears as an ordinary chat, Agent details opens in the rail's place and closing returns the rail, the sidebar row carries the preview and the unused Main is not double-listed. ent#524: dragging files lights the affordance, and dropping two files produces two chips.
• Reviewer: light + dark pass over the band, the details panel and the drop overlay; a room drop with two participants (recipients named on the chip); --skip-agent verify-local.

Not in this PR

Recorded so the narrowing is never inferred later from the fact that it merged (the ent#474 convention):

• the State tab (ent#439)
• the working-folder destination for dropped files (ent#484 / ent#486) — this ships against the existing upload path and the gesture does not change when they land
• ent#498's brief delivery, which consumes this landing rule but is its own issue
• ent#492's resize handles; the tab strip repacks without them because OverflowTabs re-measures on ResizeObserver
• ent#491's roster ordering (incubating) — a deterministic order ships and leaves the seam

🤖 Generated with Claude Code

https://claude.ai/code/session_01WLerYYUUEEmf43UKF2VVRY

[dolho]

/review report — pre-landing structural review

Branch: dolho/issue-523 → dev · merge-base 1d5c0422
Files: 40 (+3164 / −785) · Scope: CLEAN, with one requirements deviation found and fixed (C2)
Plan completion: 11 AC done · 0 partial · 0 not done · 3 changed-and-stated · 2 unverifiable (light/dark pass, room drop with two participants — left for the reviewer)

Every finding below was fixed on this branch; the commit is 7a75e0dd.

---

Critical

[C1] Enum completeness — the system line was replayed to the model as the agent's own words (Confidence: 9/10)
src/backend/client_portal/service.py:1654 (_format_history_context)

who = "Client" if m.get("role") == "user" else "You"

The speaker split is binary, so Reset's new role='system' row fell into the else branch and came back as "You: Main was reset. The previous conversation is saved as …". Not theoretical: the turn after a Reset is cold by construction (fresh row, no cached_claude_session_id), and a cold turn is exactly the one that carries the history prefix — so every Reset was followed by a turn that told the agent it had said something it never said.

Found by 4.12: reading the consumers of a new enum value outside the diff. Three other readers were checked and are safe — _title_plan's opener scan keys on "user", the dedup at service.py:2195 keys on "user", and ratings at service.py:3888 key on "assistant". message_count is bumped by touch_portal_session, not add_portal_message, so the system row also does not inflate it — which is what keeps "an untouched Main is a no-op" reading 0 after a Reset.

Fix: skip role == "system" in the context renderer.

[C2] Requirements deviation — I hid the archived chat the operator ruled must be a tab (Confidence: 10/10)
src/frontend/src/components/portal/portalUtils.js (agentChatTabs)

The ruling, verbatim (ent#523, operator 2026-09-06): "one system line in Main names the archived chat, which becomes the newest tab". This branch filtered archived_at rows out of the strip, on the reasoning that Reset would otherwise grow it by one permanent entry per use.

That reasoning was wrong twice: OverflowTabs already bounds the strip with a counted "N more", so the growth costs nothing visually — and it contradicted an explicit ruling to solve a problem that did not exist. Worse, it hid precisely the thing the system line had just pointed at, in the moment the person is most likely to look for it.

Fix: archived chats are tabs again. landingThread is deliberately left excluding them — you can go to an archive, you are never put in one. Two rules, two questions. Docs and the spec follow.

---

Informational

[I1] Race — a late landing could move you off a chat you had chosen (Confidence: 8/10)
src/frontend/src/views/Portal.vue (landOnAgent)

The landing watcher fires on activeAgentPageName and on threads.length, so on a cold deep link two calls are in flight: the first misses (no threads yet) and awaits fetchSessions, the second finds the list and navigates. Nothing re-checked the route after the await, so the first one's late resolution navigated too — harmless when it lands on the same chat, wrong when the person had since picked a different one.

Fix: re-check activeAgentPageName.value === name after each await before navigating — the same staleness guard usePortalAgentPage already makes for its own late response.

[I2] Documentation staleness — ensure_thread_for_ask (Confidence: 10/10)
Its docstring still described the pre-#523 resolution ("reuses the client's latest thread"). Rewritten to state that it lands in Main and inherits that without knowing about Main at all.

[I3] Test coupling — an existing test reached its fixture through the rule this PR changes (Confidence: 9/10)
tests/unit/test_ent79_portal_exposure.py::test_portal_chat_feeds_prior_history_as_context seeded history into a thread and called portal_chat with no session id, relying on "no session id resumes the latest thread" to reach it. That resolution is the thing ent#523 replaces, so the test failed — correctly.

It is now re-anchored on an explicit session_id. Its subject is that prior turns are fed back as context; which thread gets chosen is test_ent523_main_chat.py's subject, and a test should not fail for a reason it is not about.

---

Verified clean

• SQL & data safety — every new statement is text() with bound parameters (db.py get_main_portal_session_id, archive_main_and_mint, the widened SELECTs). No interpolation, no f-strings in SQL. The migration is additive: two nullable/defaulted columns and one index, no data rewritten, no backfill.
• Concurrency — the one check-then-act (ensure_main_session) is resolved by the database, not by a check: idx_portal_sessions_main lets exactly one INSERT land and the loser re-reads. archive_main_and_mint is one transaction with the flag cleared before the insert (the index refuses it otherwise) and a WHERE is_main = 1 precondition, so a concurrent Reset yields a named 409 instead of a second Main.
• Auth boundaries — the new route is Depends(get_portal_principal) with include_owned = principal.is_platform (the ent#358 see/do rule), the service gates on agent_on_roster before touching the table, and every miss is the uniform 404 (Invariant security: implement safe tar extraction with symlink/hardlink validation #8). The UPDATE is additionally scoped to (agent, client). Rate-limited per viewer at 10/60s. main/reset is two path segments and is declared above the {session_id} PATCH neighbour anyway.
• Credential exposure — nothing new logged; the one new WARNING logs an agent name.
• Frontend XSS — no v-html added; the system line renders as interpolated text.
• Performance — the sidebar's cross-agent batch (bug: Agent Detail and Workspace over-fetch on load (21 redundant requests, N+1 roster) #2198) is untouched and deliberately does not mint Main; no per-row fetch was added. The band and the details panel share one payload through usePortalAgentPage, so the split did not double the agent-page read. The band's cached-paint-then-refetch on a chat switch is the ent#253 pattern, not a defect.
• Error handling — no bare except:; the two broad catches are documented best-effort paths (ensuring Main must not blank a chat list; the system line must not fail a committed Reset) and both log with a stack trace.
• Product quality bar — new refusals are named 400/409 with a code, not generic 500s; the composer degrades with a label rather than dead-ending; the new columns are defaulted and additive.

Summary

• Critical: 2 — both fixed on this branch
• Informational: 3 — all fixed
• Scope: clean; one deviation from an operator ruling found and reverted to the ruling

Verification after the fixes: npm run test:unit 2029 passed / 90 files; vite build clean; backend 3021 passed, 20 skipped across the whole portal/workspace-adjacent suite (portal|workspace|ask|client|ent1xx–ent5xx). Both ratchets green.

Still on the reviewer: light + dark pass over the band, the details panel and the drop overlay; a room drop with two participants (recipients named on the chip); /verify-local --skip-agent.

[dolho]

/review — second pass (the delta since the first review)

Scope: 88056c3d..a9184e7d — ent#468, the dev merge, and the board-A3 alignment. The first pass covered the original diff; this one covers what landed after it, plus a check that its own fixes survived.

Merge-base moved. After merging dev in, the merge-base is dev's tip, so this diff is 46 files that are actually mine — not the 52 a stale merge-base showed, which included four of dev's own commits.

The first pass's fixes are still in place

• C1 _format_history_context still skips role == "system" — service.py:1663
• C2 archived_at appears only in landingThread, not in agentChatTabs — archived chats are tabs, as ruled
• I1 three route-staleness guards in landOnAgent

---

Findings

[P1] Performance: the sidebar did four whole-list scans per row (Confidence: 9/10) — fixed
src/frontend/src/components/portal/PortalSidebar.vue

agentPreview and agentRowTime each scan the entire thread list, and the template called them per row and twice each — a v-if and an interpolation:

<span v-if="previewFor(a.name)" …>{{ previewFor(a.name) }}</span>
<span v-if="rowTime(a.name)" …>{{ rowTime(a.name) }}</span>

A 10-agent roster over 200 threads is ~8k iterations per render, on a surface that re-renders on every store tick. Mine, introduced in the A3 commit and in the sidebar-preview commit before it.

Fix: agentRowMeta computes both for every agent in one pass, memoized in a computed — O(threads + agents) instead of O(rows × threads × 4). The two per-agent helpers stay exported and tested, and a new test asserts the map agrees with them, so "which chat is newest" keeps one definition. The tight time format is split into a shared compactAge so the two callers cannot drift on what 2d means.

[P2] A fired timer's handle accumulated for the life of the mount (Confidence: 7/10) — fixed
PortalAsks.vue. Minor, bounded by answers-per-mount, but onBeforeUnmount was then clearing a pile of expired ids. The handle is now dropped when the timer fires.

---

Verified, with the line that proves it

The riskiest assumption in ent#468 — checked against the server, not against my own literal. answerConfirmation gates on status === 'answered'. A wrong literal would make the whole feature silently dead and my tests would still pass, since they use the same constant. The projection maps it (asks/service.py:56,73):

_ANSWERED_STATUSES = frozenset({"responded", "acknowledged"})
...
if (item.get("status") or "") in _ANSWERED_STATUSES:
    return "answered"

So the gate matches the contract, and it correctly treats the operator-side acknowledged terminal as answered too.

Blast radius of the two shared primitives is bounded, and I checked rather than assumed.

• StackedBarChart — three callers (OverviewPanel, TrendLineChart, the band); grep 'legend=' finds it passed only by the band. Every other caller takes the 'below' default and renders exactly as before. The new wrapper div is a plain block in default mode, so block stacking is unchanged.
• OverflowTabs — five callers; only PortalChatTabs' Main sets pinned, and an unset pinned renders nothing. The remeasure key includes it, and the glyph is in all three render sites including the hidden mirror row — a glyph the visible row draws and the measuring row does not is a tab measured narrower than it renders, which overflows the strip one tab too late.

The band overflow was a real bug and is fixed at the cause. StackedBarChart is height + ~38px (bars + day labels + legend) and the band clipped it into a fixed 52px box, so with any real activity the legend drew on top of the chat tabs. It was invisible in the first screenshots because that agent had zero executions. The row now sizes to the chart, and legend="side" is what keeps that from doubling the band's height.

Clean categories (nothing found): SQL/data safety and concurrency — no backend change in this delta beyond the two-line history-context skip; auth boundaries — no new route or gate; credential exposure — none; XSS — no v-html added, the confirmation is interpolated text; error handling — no new swallow; enum completeness — role='system' consumers were swept in the first pass, and the new status/resume_requested reads are the first consumers of fields that had none.

Summary

• Critical: 0
• Informational: 2 — both fixed on the branch
• Scope: clean. ent#468 is folded in with its decision recorded on the issue (its own AC Fix: Add missing Docker labels to system agent container #1); the A3 work is alignment with the design approved 2026-09-06, not new scope.

Verification: npm run test:unit 2059 passed / 92 files (11 new since the first pass); vite build clean; backend 172 passed across ent#79 / ent#451 / ent#473 / ent#523 plus dev's new test_2110_widget_type_parity.py. Raw-color vs origin/dev: no file grew raw_nongray or hardcoded_colors; gray chrome only.

CI: 15 checks green including journey-impact, schema-parity, pg-migrations, gitleaks, verify-non-root and the compose/docs guards. The pytest seed matrix, e2e, CodeQL and the image smokes are still running.

Still on the reviewer: light + dark over the band, details panel and drop overlay; a room drop with two participants; /verify-local --skip-agent. Both cross-tracker issues need a manual status-in-dev at merge — the automation is same-repo only.

[vybe]

Validated via /validate-pr — APPROVE.

• Both migration tracks present (SQLite portal_session_main_chat + Alembic 0054), heads check on the branch resolves to one head; schema-parity and pg-migrations green.
• Re-ran locally on the branch head: backend test_ent523_main_chat + ent451/ent79/2196/2198 neighbours — 161 passed; vitest run (both ratchets) — 95 files, 2147 passed.
• Security greps clean; no compose/Dockerfile/getenv packaging surface.
• Doc drift on the Alembic revision number was already corrected in 95e4203.

Cross-tracker refs do not auto-promote — setting status-in-dev on ent#523, ent#524, ent#468 by hand at merge.