fix(workspace): the chat tab strip — a visible New chat, a Main that is there, titles that are titles, and tabs that hold their width (#2579)

[AndriiPasternak31]

Fixes #2579

Merge order — step 1 of 7

This is step 1 of 7 of the Workspace sequence. It merges after — nothing merges before it. Everything downstream in the sequence rebases on this one, and ent#547 + #2580 follows next.

The reason it is first is mechanical, not ceremonial: this PR introduces the single adoptSession() seam, OverflowTabs.fixedWidth, and the concurrent title spawn — three things the later steps build on. Landing any of them second means resolving the same conflicts in the other direction.

What was wrong

An operator test on dev after ent#451/#473/#523 found four things wrong with the tab strip above a Workspace conversation. None of them was the sort rule, and two the issue suspected of being build lag turned out to be structural.

What was seen	The actual cause
New chat produced no tab	By design — the 2026-09-06 ruling ("a chat exists once its first message is sent") applied to the strip
New chat did not focus the composer	The press bumps convGen, which remounts PortalConversation; its onMounted never focused, and defineExpose({ focusComposer }) had zero callers
The pinned Main tab was absent	Main is minted only by the per-agent list_sessions; the Workspace lists from the cross-agent batch, which deliberately never mints. The one per-agent read — landOnAgent's repair branch — destructured { sessions } off an array (fetchSessions returns data.sessions || []), so it was always undefined and that branch never once ran
Titles showed the first message	Generation was spawned as the turn returned, so the client's turn-done refresh always read the derived fallback

What changed

A fresh chat is a tab, provisionally. agentChatTabs inserts one New chat tab with thread: null directly after Main — the slot the real row takes, so adoption swaps it in place rather than making it jump. It is keyed off explicit intent (startingNewChat, ORed with the conversation's bornHere), never off "the active id is not in the list", which would label a cold deep link. bornHere is raised in the one adoptSession() seam all three adoption sites share; raising it at one site drops the tab exactly when streaming is unavailable, or for the whole round trip of starting a voice call.

New chat focuses the composer, from onMounted's else-branch — it has to happen in the remounted instance.

Main is ensured by ensureMainListed, through the per-agent read that already mints it. It is a GET that inserts, deduped in flight, capped at two attempts, and cleared at sign-out (that handler resets state in place, so client B would inherit client A's promises).

Tabs are a fixed width via an opt-in OverflowTabs.fixedWidth.

The title spawn moves to run concurrently with the turn — the root cause, fixed at the source rather than papered over. Plus a bounded client-side settle re-read as the belt, and the existing titleGenerationNotice raised into the Workspace for platform admins.

⚠️ This amends a binding design contract — please look at that specifically

design-system-contract.md line 30 and principle 10 say "never wrap or truncate". This PR amends both.

The amendment: that rule governs the set — the strip still overflows into a counted "N more" menu and never drops or wraps tabs. It does not require every label to be laid out at its intrinsic width. A strip whose labels are unbounded user and model text may opt into fixed-width tabs whose labels clamp, with the full text on hover and in the overflow menu.

Recorded in design-system-contract.md, design-system.md (with the recipe), and agent-detail-tab-overflow.md. fixedWidth defaults to false, so Agent Detail, Library and the portal rail are unchanged by construction. This wants the design authority's eyes, not a docs bullet.

Behaviour changes, stated

1. Titles are generated from the client's opening message alone. The reply was the disambiguator for a terse opener; the existing retry attempt is the safety net that remains.
2. A turn that fails now still titles its thread — consistent with _persist_user_turn's own ruling that a user message on record with no reply is the honest record.
3. ensureMainListed is a GET that inserts. Visiting N agents creates N empty enterprise_portal_sessions rows. That is ent#523's stated intent, said out loud so it is not a surprise in review.

Both title changes are pinned by test so they stay decisions rather than drift.

Accepted limitations (documented, not deferred)

1. Title health is per uvicorn worker. _title_health is a module global and prod runs --workers 2, so an admin's probe can land on a worker that ran no generation and answer unknown → no notice. Honest under-reporting; cross-worker means new Redis-shared state for a diagnostic. Recorded in workspace.md.
2. A permanently failed list refresh leaves a real thread labelled "New chat". The list is stale in that state anyway and sessionsFailed says so honestly.

No follow-up issues filed — that was the gate's ruling.

Not frontend-only

src/backend/client_portal/service.py is touched: one moved call site, one new prompt constant, one branch. Chosen small deliberately — that file is also edited by ent#535 (step 5 of this sequence), so the rebase should be mechanical.

Verification

Re-run after merging origin/dev into the branch (da2aa6ef), because that merge touched two files this PR also touches — views/Portal.vue and tests/unit/portalVoiceMode.spec.js. The earlier numbers predated it.

• npm run test:unit — 101 files, 2276 passed
• Backend test_ent473_chat_titles.py + test_ent79_portal_exposure.py — 130 passed
• npm run check:tokens — OK (11 tokens equivalent, all references resolve, dark ink ladder holds)
• Raw-color ratchet: flat on every touched file, measured branch-vs-dev per file (OverflowTabs 22→22, PortalConversation 98→98, Portal.vue 36→36, PortalChatTabs 1→1). Deliberately not measured against raw-color-baseline.json, which is stale from 2026-07-31 and already exceeded by dozens of files this PR never touches. Loading-gate ratchet green (it runs inside test:unit).
• /verify-local --skip-unit --skip-agent — PASS (build+import-smoke → boot → integration 70 passed / 13 skipped)
• Live sign-off done on a real stack: e2e/workspace-chat-tabs.spec.js plus the two neighbouring tab-strip specs — 12/12 passed, zero skipped (PORTAL_TEST_AGENT=sage). The zero is the point: the geometry cases self-skip on a thin fixture, and a skip reads as green.

No schema change, no new route, no new os.getenv, no new top-level backend module — so no dual-track migration, no MCP surface, and no packaging gap to check.

Draft because Andrii flips it, not because verification is outstanding.

One open product question — found live, not asserted anywhere

Opener-only generation means a greeting opener produces refusal prose as the title: "Hi!" → 'I need more context to create an appropriate title. The ope…', "Hi! How are you?" → 'Unclear - awaiting client message content'.

_title_plan's is_greeting(opener) retry does rescue it — proved live, the same thread became 'Q3 Vendor Contracts Auto-Renewal Review' after a second turn. So the residual is only a thread that opens with a greeting and never gets a second message, which keeps the prose permanently.

Candidate fix if wanted: skip the first attempt when the opener is greeting-shaped and let the retry own it (needs client_message passed to _title_plan, which today only sees pre-turn history). Not implemented, not filed — flagging it for the reviewer's call rather than deciding it here.

🤖 Generated with Claude Code

[dolho]

/review — PR #2600 (AndriiPasternak31/issue-2579 → dev)

Files: 24 (+1730/−117) · Scope: CLEAN — all five ACs addressed, nothing beyond them.

Verified locally:

• pytest tests/unit/test_ent473_chat_titles.py test_ent79_portal_exposure.py → 130 passed
• full frontend unit suite → 101 files / 2276 passed, including loadingGateRatchet
• raw-colour scan clean on the touched files
• and I compiled OverflowTabs.vue through @vue/compiler-sfc to settle the one thing the tests cannot: FIXED_TAB_WIDTH resolves as literal-const and emits $setup.FIXED_TAB_WIDTH in both rows. The companion-<script> export genuinely works.

The best thing in this PR is not in the ACs:

landOnAgent used to destructure { sessions } off a value that is an array, so sessions was always undefined, landingThread always missed, and the repair branch never ran once.

That is a dead branch that had been silently shaping first-visit behaviour, found while fixing something adjacent, and named plainly rather than quietly rewritten. ensureMainListed replacing it with one seam shared by the landing path and the watcher is the right shape, and being honest that it is a GET that INSERTS — with ent#523's intent cited — is exactly the disclosure a future reader needs.

Two other calls worth recording as correct:

• The provisional tab is keyed off draft, never off "the active id is not in the list." A cold deep link to a thread the batch has not listed yet would otherwise wear a "New chat" label over a real conversation. And onSelect returning early on !tab?.thread rather than emitting a null into openThread (which reads t.is_room) closes the obvious crash.
• The settle cycle is cleared in three places, and watch(convKey) is the one that matters. Neither onBeforeUnmount nor the event handler fires on a thread switch, so without it a cycle armed in chat A would keep replacing threads.value for 16s under chat B. The re-check of shouldMarkTurnRead inside armTitleSettle — because the caller decides it synchronously and then arms after two awaits — is the kind of thing that is only found by asking "what happens in the window between these two lines".
• settleTick re-runs store.seedAgentRecency because it replaces threads exactly as refreshThreads does. Easy to miss; it would have quietly unranked agents for 16 seconds at a time.

Critical

None.

Informational

[I1] The retry pass no longer sees the exchange ent#473 designed it around, and two comments read as though it does (Confidence: 7/10)
src/backend/client_portal/service.py (_TITLE_PROMPT header vs the portal_chat spawn comment)

There is now exactly one call site and it always passes reply="" — for the first attempt and the retry. So:

• _TITLE_PROMPT's header keeps the two-block prompt because "the reply is the disambiguator for a terse opener" — but nothing reaches that branch any more, which the same comment concedes two lines earlier.
• The portal_chat comment then says "the existing retry attempt remains the disambiguator for a terse opener" — true, but by a different mechanism: it disambiguates using the second turn's client message, not a reply.

ent#473 specified that second pass as feeding "THIS exchange — the one after a greeting or a failed first attempt is the first one with a topic in it." It now feeds a message, not an exchange. I think that is fine and probably right (the disambiguating content is usually the follow-up question, not the agent's answer), but it is a real narrowing of #473's input and it is currently recorded only as an aside inside a comment about a different constant. Worth one sentence saying so where _title_plan documents retry, so the next person changing this does not "restore" the reply on the assumption it was lost by accident.

[I2] The fixed-width AC's only render-level proof is an @interactive e2e test, which CI does not run (Confidence: 8/10)
src/frontend/tests/unit/portalChatTabsAndTitles.spec.js:285-308 vs src/frontend/e2e/workspace-chat-tabs.spec.js:116

The unit assertions are source-greps over the SFC text:

expect(s()).toMatch(/export const FIXED_TAB_WIDTH = 'w-40'/)
expect(visible).toMatch(/\$\{FIXED_TAB_WIDTH\} shrink-0/)

They pin the source, so they would pass unchanged if the binding never resolved in the template and the class never reached the DOM — which is precisely the risk a companion-<script> named export carries. The real assertion ("every visible tab is exactly one fixed width") lives in the @interactive e2e spec, and this repo's e2e job runs @smoke only, behind the ui label.

To be fair about it: the frontend unit harness has no mount capability (@vue/test-utils is not a dependency and vitest runs environment: 'node' — the constraint architecture.md already records for ent#392), so a render assertion is not available to the author, and source-greps are the best the harness allows. I confirmed by compilation that the binding does resolve, so this is not a live bug. The point is only that the AC "tabs are fixed width" is not currently covered by anything CI evaluates — worth either tagging one of those e2e cases @smoke, or saying in the flow doc that this property is verified out-of-band.

[I3] settleTick refreshes the list without chatState (Confidence: 6/10)
src/frontend/src/views/Portal.vue (settleTick)

refreshThreads fetches both and assigns both; settleTick assigns threads only. Deliberate and cheap (three extra reads per turn, not six), and chatState converges on the next real refresh. Noting it because the two functions now diverge in what "refresh the list" means, and the divergence is not stated where the second one lives — a comment on settleTick saying "list only; chatState is intentionally not re-read here" would stop someone unifying them later and doubling the traffic.

Clean

• AC coverage: (1) provisional tab + nextTick(focusComposer) in the fresh instance, with the correct reason — convGen remounts the component so focus set before the press is discarded; (2) ensureMainListed + the Main-first comparator; (3) the admin-only titleNotice, gated by shouldFetchTitleHealth so a portal client never even asks for the admin endpoint (the #2128 lesson applied); (4) fixedWidth on both rows with truncate + title=; (5) specs and workspace-chat-tabs-and-titles.md updated.
• fixedWidth as its own prop rather than a rider on dense — density and label-boundedness are different questions, and every width class is gated on it, so the four existing strips are byte-identical (including no stray native tooltip on "Overview").
• The mirror/visible asymmetry is reasoned, not copied: the mirror takes the width class and nothing else because getBoundingClientRect() returns the border box and the mirror is width: max-content; the visible row needs shrink-0 + overflow-hidden because inlineCount starts at +Infinity and flex would squeeze every tab for one frame. That is the sort of detail that is wrong in every hand-rolled version of this.
• Prompt hardening preserved: _TITLE_PROMPT_OPENER keeps the never-follow-instructions fence over author-controlled text, and dropping the empty <assistant_reply> block rather than formatting "" into it is the right call — an empty block invites the model to describe the emptiness.
• Timer hygiene: cleared on unmount, on convKey, and on the next turn-done; mainEnsured/mainAttempts/titleHealth/titleNoticeDismissed all reset in onSignOut, because the OTP form is a branch of the same never-remounted component — the #2258 principal-bleed class, caught for the new state rather than rediscovered later.
• Design system: semantic status tokens only in the notice, role="status" + aria-live="polite", raw-colour and loading-gate ratchets both green.

Summary

Critical: 0 · Informational: 3 · Scope: clean.

Approving. All three are comments/coverage rather than behaviour; [I1] is the one I'd most like written down, because it is the only place a real semantic change to #473 is recorded.