kandev/apps/web/components/threads/AGENTS.md

# Threads deck

`/threads` renders stable conversation tiles in Columns or a two-row Grid.

`selectActiveThreads` (`lib/threads/active-threads.ts`) derives the columns from
the workflow snapshots the board already keeps in the store, so opening the view
costs no extra request and stays live on the same WebSocket updates the cards
use. Its ordering is total (attention bucket, then recency, then task id).

**That ranking decides where a column first appears and nothing after that.**
`useStableThreadOrder` (`lib/threads/stable-order.ts`) pins each column to its
slot, and new threads append rather than sorting in. Do not re-apply the ranking
live: replying to a thread refreshes its activity and flips it out of the
"needs a human" bucket, so a live re-rank slides the column the reader is typing
into across the deck, then slides it back when the turn ends. The E2E
`holds a column's slot and the deck's scroll while you reply to it` fails if this
is undone.

A task reaches the deck through its **primary** session, matching the backend's
`GetPrimarySessionIDsByTaskIDs`. Once that task column is present, the Threads
switcher can select any existing sibling session, including a settled one.
Sessions created by the E2E seed harness are never primary, so a spec has to
run a real agent turn (create the task with an agent, open the task page to
launch the session, then wait) rather than seeding a RUNNING row.

Columns mount `TaskChatPanel` with **no `onSend`**. Its own submit path is what
honours the session's queue input mode, the selected model, plan mode, context
files and the optimistic store update; a custom sender posts straight to
`message.add` and drops all of it, so a reply to a busy thread jumps its queue.
(`PreviewSessionBody` in the kanban preview still passes one and has the same
defect.)

They do pass `isVisible={false}`, for the same reason the kanban preview does: a
wall of columns is a glance across running work, and letting every mounted
column advance its own read cursor would mark threads read that nobody looked
at.

Columns share the board width (`flex-1` above a 360px minimum). Grid uses the
same direct task children in column-major order, two equal rows, and the same
width floor. One task fills the height; fewer than two 300px rows plus the 12px
gap temporarily selects Columns without changing the saved layout. Board
content size owns this fallback and reflow recovery. Both visible rows activate
selected conversations; stale observer callbacks cannot replace the current
window. The phone keeps one full-width snapping column and one active detail,
without overwriting the saved desktop layout.

`ThreadView` and `ThreadViewDraft` own `layout` and `autoHideComposer` through
the existing backend-owned user settings and view actions. Defaults are
Columns, auto-hide off, and five total chats; `maxColumns` still limits admitted
tasks across both rows. Presentation is excluded from `queryFingerprint`.
`ThreadsViewDisplay` is shared by the desktop editor and touch drawer. Layout
selection belongs only inside this configurator, not in the top bar;
do not add another persistence owner or autosave path. Render-only fallbacks
never write over the saved preference.

The phone title button opens one board-owned `MobileThreadPicker` using
admitted task summaries. Selection scrolls an existing shell; viewport
activation still owns transcript mounting. The picker restores focus without
scrolling back to the previous column. Phone headers prioritize task title,
status, and agent selection; workflow and step context remain in the picker.
Titles wrap to two lines. Inline topbar pagination shows position/count for
multiple threads and decorative dots only for decks of up to seven threads.
`ThreadsBoard.renderHeader` receives `mobileTaskId`, derived from board scroll
geometry by `useMobileThreadPosition`, and the board's grid-height fallback
reason for Display. The page derives the ordinal from stable
order without copying selection state. Do not derive pagination from loaded
chat or visibility-ID membership alone: both adjacent columns can stay
intersecting across a swipe midpoint. Position changes also refresh the nearest
visible detail calculation, retaining the one-phone-transcript limit.
Callback refs reconcile column additions/removals on the existing observer.
Do not rebuild it on every membership change: clearing surviving visibility
briefly unmounts readers' chats and loses editor focus. Recreate observation
for layout/width reflow or an empty/nonempty transition that replaces the board
element, measuring current geometry before asynchronous callbacks arrive.

`ThreadTaskActionsProvider` owns one task-action surface above removable
columns. Headers pass explicit task IDs; `useTaskManagementFlow` captures the
workspace/task identity and resolves current eligibility from shared snapshots.
`TaskManagementSurface` composes existing task menus, linking and confirmations;
`useTaskMenuActions({ stayOnListing: true })` shares destructive lifecycle
cleanup with the sidebar without task-detail navigation. Do not add task API
calls or mutation policy to Threads.

The page excludes task IDs from pending `archive` operations in
`taskRemoval.operationsByToken` before `queryThreadView` applies scope, filters,
limits or temporary deep-link admission. This unmounts outgoing chats at
acceptance and keeps counts, the phone picker and pagination consistent. Do not
mutate shared snapshots optimistically or include removal intent in the query
fingerprint/stable-order reset key. Successful reconciliation prunes snapshots
before releasing intent; failure readmits only currently eligible tasks in
normal arrival order. Pending deletion retains its existing timing.

Only noninteractive desktop task-header regions handle context menus. The
visible `TaskMenuButton` is also the keyboard/touch entry; phone and coarse
pointers use one `TaskManagementDrawer` with nested pages. Keep chat, editor,
session and native swipe events outside this boundary.

`useThreadSelectionRecovery` preserves the surviving reader's column offset
and uses `resolveRemainingThreadId` for successor/predecessor/first-new/empty recovery
when membership changes. Layout/width changes retain that identity too;
resize-generated scroll or same-membership snapshots must not overwrite it
before reflow recovery. This does not replace stable ordering, the parent's
scroll-derived pagination, or transcript activation. Action focus restoration
resolves a currently visible trigger and never scrolls to a removed opener.

The page reads `?workspace=` into the route it hands `useKanbanRouteBootstrap`.
Without it a cross-workspace link loads whichever workspace the cookie last
named. Scope changes from the shared header go through `listingHistoryHref`,
which keeps the deck's own path: those handlers `pushState` without routing, so
a task-overview href would leave the deck rendered under a Home URL.

## Composer disclosure

`ThreadColumn` owns a selected-session-scoped `useComposerDisclosure` controller
and `ComposerDisclosureContext`. Only fine-pointer desktop layouts apply
auto-hide. Phone/coarse-pointer layouts retain the normal composer and stored
preference. Tile hover and keyboard focus reveal without autofocus; explicit
Collapse cancels the current hover dwell and returns focus without reopening.

Native owners report drafts, attachments, pending operations, required actions,
and owned overlays through `useComposerActivity`. `useComposerFocus` reveals
before native or plugin focus requests. Keep these reports scoped to the
selected session and clean up holds/timers on deactivation. React-owned portal
focus belongs to the tile even when its DOM is outside the tile.

`ComposerDisclosureRegion` wraps the entire non-CI `ChatInputArea` content in
one interruptible grid-track/opacity transition (200ms in, 160ms out). Inert
and `aria-hidden` change immediately; visual hiding waits for exit completion.
Reduced motion disables transitions. Keep editor and plugin instances mounted,
with no nested disclosure wrappers or separate animation timers. The existing
provider-specific `ComposerCIStatus` sits outside the animated region while
auto-hide is effective; `ChatStatusBar` retains inline CI for other hosts.
An empty CI row occupies no height. No Reply, Stop, plugin, or queue strip remains when
collapsed. Opaque plugin activity does not hold the composer open; hiding must
not cancel operations or revoke plugin capabilities. Required native actions
and recovery force the regular surface open. Cancellation stays in the native
composer, including its pending-state hold.

`ComposerFooterAllocation` bounds the entire Threads footer, including required
questions and when auto-hide is off, leaving an 80px transcript floor. Long
footer content scrolls inside that allocation. The native transcript owner in
`message-list-native-scroll.ts` uses `transcript-viewport-resize.ts` to preserve
bottom-follow across height-only allocation changes without overriding history,
frozen scroll, or width reflow. Do not add a competing tile scroll loop or pin
offscreen details to retain a composer; session draft restoration owns return.

## Round trip with the task page

`linkToThreads(workspaceId, taskId, sessionId)` produces `/threads?taskId=…` and,
when supplied, the target session id. The link asks the deck to scroll that
column into view and ring it. The focus id is resolved against the rendered
deck (`resolveFocusedThreadId`), never trusted from the URL: the thread may
have settled between the link being offered and followed.

The scroll effect is keyed on `isFocused` and the board's layout/width key;
the column is keyed by task id. Initial measurement or resizing can interrupt
smooth scroll, so the still-marked target is reasserted after reflow. Ordinary
message updates do not scroll the deck.

The mark retires on the first pointer, wheel, or focus interaction with the deck,
since it only ever answered "where is the column I asked for". Dismissal is keyed to
the raw workspace/task/session request identity, independently of its currently
resolved column. Temporary exclusion and failed archive readmission must not
revive a consumed mark; an actual new deep link still earns a fresh mark.
`useThreadFocusRequest` keeps the initial activation fallback alive after mark
dismissal until its target leaves the deck. Early interaction must not unmount
that chat before the first visibility callback, and failed readmission must
not restore a consumed fallback. URL-driven callers pass `focusRequestKey`;
the optional task-ID default deliberately retains legacy dismissal semantics.

`OpenInThreadsButton` is the other half, living in the chat status row. It has
two gates, and both matter:

- `useIsDeckThread` — the session must belong to a task with a Threads column,
  which can come from a live primary or a task-level review outcome. It reads
  already-loaded sessions and the cached task summary/state and must not fetch;
  a status-row control triggering a request would be a surprise. A settled
  sibling is therefore eligible when that task keeps a column in the deck.
- pathname — the deck's own columns render the same chat panel, so without this
  the button would appear inside every column offering a jump to the view
  already on screen.

## Adding a task-listing view

`kanban`, `pipeline`, `list` and `threads` share one device-local preference in
`lib/task-listing/view-preference.ts`. `resolveTaskListingNavigation`
(`lib/task-listing/view-navigation.ts`) is the single mapping from a toggle pick
to the view to remember and the page to go to; the desktop topbar
(`components/kanban/kanban-header.tsx`) and the phone menu sheet
(`hooks/use-mobile-menu-sheet-state.ts`) both call it, so a new view means one
entry there plus a toggle item on each surface.

A view that owns its own route also needs an entry in
`ROUTED_TASK_LISTING_VIEWS`, so Home hands off to it instead of rendering the
board, and one in `lib/navigation/core-destinations.ts` — a guardrail test fails
when a top-level route has no navigation destination. `currentPage` is
`TaskListingPage` internally; `toPluginTopBarPage` narrows it to the two values
the plugin contract has always published.