git:20261021.3c7a08e to git:20261022.3a5e6a7

# DOX — packages/client/src/components/session

Files in this directory. One row per source file. See change: fold-oversized-agents-directories.

| File | Purpose |

|------|---------|

| `ContextRing.tsx` | Exports `ContextRing` (desktop `role=meter`, 16 px arc + `<pct>%`, tooltip `<used> of <window> tokens`), `ContextRingButton` (mobile 44 px, non-modal popover `<pct>% · tokens · $cost`), `contextPercent`, `ringTier`. Tiers by rounded %: neutral ≤30, blue ≤50, green ≤70, orange ≤90, red 91+. Null when usage unknown. See change: reorganize-session-header. |

| `FileAccessToastHost.tsx` | Own toast tray + `useFileAccessToasts` for the whole app (both layouts); App-level `useToast` tray renders only in the mobile branch. See change: ask-agent-file-access-in-chat. |

| `session-hover-intent.ts` | `createHoverIntent(doc, host)`: ONE document `pointermove` listener, refs only. 32 px right-edge strip, 300 ms dwell + speed < 0.4 px/ms (100 ms window), union-rect bridge, 300 ms close grace. Constants `HOVER_STRIP_PX`, `HOVER_DWELL_MS`, `HOVER_SPEED_CUTOFF`, `HOVER_CLOSE_GRACE_MS`. See change: add-session-actions-flyout. |

| `SessionActionsPanel.tsx` | Menu panel of the session actions flyout (`SessionActionsPanel`, grouped items, `MenuEntry`, `LifecycleRow`, `GroupHeading`). Contract floors: headings 11 px semibold `--text-secondary`; items + actionable lifecycle segments `min-h-[36px] max-sm:min-h-[44px]`; enabled labels, `More…` primary, count 12 px secondary; disabled = secondary + `aria-disabled`, reason a wrapping 12 px block line referenced by `aria-describedby`; PLUGINS container sets `text-[var(--text-primary)]`. Hooks, taxonomy and folding unchanged. See change: add-session-actions-flyout, align-ui-contract-recipes. `MenuEntry` renders `item.tone` via client-utils `tone` helpers (icon colour, `data-action-tone`; enabled danger → red hover/focus row); NEXT = blue outline, no tone; `focus:bg` per-branch (`FOCUS_BG`). `LifecycleRow` glyph + text-role colour per state (`SEGMENT_LOOK`). See change: colorize-actions-menus. |

| `SessionCardDialogs.tsx` | Per-card dialog host for menu items (Explore, Archive confirms, Tasks, New change, Propose, Attach picker, Bulk archive, Merge, Close worktree, Switch branch). Menu only sets `dialog`; dialogs outlive the menu at `z-dialog`. See change: add-session-actions-flyout. |

| `SessionClock.tsx` | Exports `SessionClock` (own 1 s interval; `running <d>` live, `ended · ran <d>` / `ended` ended) + `formatDuration`. Keeps the tick out of `SessionHeader`. See change: reorganize-session-header. |

| `SessionTitleMenu.tsx` | Exports `SessionTitleMenu`: title button + APG menu (Rename F2, Reveal in sidebar, Edit tags, separator, Reload transcript `data-testid="refresh-chat"`). Items omitted when callback absent; Escape → focus title button; throwing action caught. See change: reorganize-session-header. |

| `VaultBindingsChip.tsx` | Header chip + dialog: this session's vault binding NAMES with a state pill and one-line explanation each (≥ 12 px), project line (or why the vault does not deliver), checkout-confirm callout (`vault-confirm`, trust copy, "Confirm and deliver N keys"), `vault-ungranted` section with `vault-grant-from-session` (repo grant when a repoKey exists, else folder grant), last hub contact, manage link via wouter `navigate`. Shown when bindings or ungranted names exist (`data-pending` when a confirm is due); polls 2.5 s. Tests: `__tests__/VaultBindingsChip.test.tsx`, e2e `vault-session-bindings.spec.ts` (F2, F4). See change: add-credential-vault, retro-ux-credential-vault. |

| `ArchivedSessionRow.tsx` | Lightweight row for an archived session inside folder `Archive (N)` fold or `Archive matches` search. Exports `ArchivedSessionRow`. Never in live `sessions` Map; click opens read-only `?archived=1`. Testids `archived-session-row`, `session-unarchive-btn`, `archived-delete-btn`. See change: archive-sessions-lazy-load. |

| `ComposerSessionActions.tsx` | OpenSpec lane of the composer dock (the strip is gone). Exports `useOpenSpecAttachment`, `isOpenSpecLaneVisible` (readiness gate + `showTrace`), `useOpenSpecLane` → `DockLane`. → see `ComposerSessionActions.tsx.AGENTS.md` See changes: add-openspec-init-affordances, add-composer-dock. |

| `ContextUsageBar.tsx` | Progress bar showing context-window usage. Exports `ContextUsageBar`. → see `ContextUsageBar.tsx.AGENTS.md` |

| `CountBadges.tsx` | Shared `+adds −dels` count badges. See change: add-change-summary-table. |

| `DashboardSpawnButtons.tsx` | Sidebar spawn-button stack. Exports `DashboardSpawnButtons`. → see `DashboardSpawnButtons.tsx.AGENTS.md` |

| `ElapsedBadge.tsx` | Elapsed-time badge. Exports `ElapsedBadge`, `formatElapsed`. Static when `duration` set; live ticking (1s interval) when only `startedAt` set. Formats <1s / Ns / Nm Ns / Nh Nm. Registered as `ui:elapsed-badge` (`UiElapsedBadgeProps`). See change: decouple-plugins-from-core. |

| `FocusToggle.tsx` | Sidebar-header focus-mode toggle. Exports `FocusToggle`; drives `useFocusActions().setEnabled`, reflects state via `aria-pressed`, testid `focus-toggle-btn`. See change: add-focus-mode-and-card-block-toggles. |

| `GroupByChip.tsx` | Folder-header grouping indicator (`folder-group-by-chip-<cwd>`). Hidden for `none`; `<Mode>` / `<Mode> · default` when inherited; click (stopPropagation) opens folder menu. `.group-by-chip` 44px coarse hit area. Exports `GroupByChip`, `groupByModeLabel`. See change: session-list-group-by. |

| `LaneHeader.tsx` | Lane header `<button aria-expanded aria-controls>` (`lane-toggle-<cwd>::<lane>`): glyph on rail (lane color), label in `--text-secondary` (never status color), sub (branch), selected marker when collapsed, inert rollup (collapsed location lanes only, capsule segments/shapes), count pill, right chevron. Exports `LaneHeader`, `laneMeta(lane)` (label/color/icon, per render), `isLocationLane`, `laneRailStyle` (`--lane-rail`). See change: session-list-group-by. |

| `MissingRequiredBanner.tsx` | Top banner for missing `required` recommended extensions (`useRecommendedExtensions`). → see `MissingRequiredBanner.tsx.AGENTS.md` |

| `PiBelowFloorWarning.tsx` | Warning chip for a session whose running pi is below the lockstep floor. Exports `PiBelowFloorWarning({session, className?})`; renders nothing unless `session.piBelowFloor`; text names `piVersion` + `piBelowFloor.minimum` (`session.piBelowFloor` i18n key); `role="status"`, `--severity-warning-*` tokens, icon `aria-hidden`. See change: update-pi-core-1-0-adopt-apis. |

| `PlaceholderSessionCard.tsx` | Skeleton card shown while a new session spawns. Exports `PlaceholderSessionCard`. Pulse-animated bars mimicking `SessionCard` layout; shows "Starting new session…" text. |

| `QueuePanel.tsx` | Read-only follow-up cycler. Pi ExtensionAPI exposes no queue mutation (verified through pi 0.76.0). → see `QueuePanel.tsx.AGENTS.md` `embedded` prop (dock Queue lane) hides subtitle + Clear all and the panel chrome. See change: add-composer-dock. |

| `RecoveryOfferHost.tsx` | Sticky top-right cold-start recovery-offer notification; never auto-dismisses. Reopen routes candidates through resume; dismiss DURABLE (`recovery_dismiss` consumes the on-disk liveness marker — no re-appear on reconnect/reload/restart). See change: fix-recovery-offer-dismiss-and-phantom-reopen. |

| `RetriedErrorBadge.tsx` | Compact badge collapsing a tool error→retry pair into one line. Click expands to full `ToolCallStep`. → see `RetriedErrorBadge.tsx.AGENTS.md` |

| `SessionActivityBar.tsx` | Pure component. Renders one row per unresolved `bash` toolCall: `⏵ <command> <elapsed> [⏹]`. → see `SessionActivityBar.tsx.AGENTS.md` |

| `SessionBanner.tsx` | Composed session-status banner. Error anchor (red) + retry sub-line (amber) in one surface, driven by… → see `SessionBanner.tsx.AGENTS.md` |

| `SessionCard.tsx` | Gates both `<ContextUsageBar>` mounts on `useDisplayPrefs(session.id).contextUsageBar` → see `SessionCard.tsx.AGENTS.md` OPENSPEC subcard gates on `openspecReadiness` (legacy fallback preserved); BROKEN/STALE render the inert `OpenSpecDisabledPanel` — controls out of the DOM, per-reason text, one control routed folder↔settings. See change: add-openspec-init-affordances. Archive affordance replaces hide/unhide; idle-alive prompts confirmation, running suppressed. See change: archive-sessions-lazy-load. Desktop card condensed to state: chip row, OpenSpec primary/`⋯`/combo, worktree actions row, legend `⋯`, Rename pencil and footer slot removed; all actions are `SessionActionsMenu` items; action-bar claims stay mounted via a detached-container portal. See change: add-session-actions-flyout. |

| `SessionHeader.tsx` | Session chat header (desktop 48 px three-zone row + mobile one-row `MobileHeader`). Title is a menu button (`SessionTitleMenu`), meta line has `SessionClock` + `ContextRing`; Attach removed → see `SessionHeader.tsx.AGENTS.md`. See change: reorganize-session-header. |

| `SessionList.tsx` | Main sidebar session list. DnD-ordered (`@dnd-kit`) pinned/unpinned + workspace tiers, folder grouping,…… → see `SessionList.tsx.AGENTS.md` Folder section render gate readiness-driven; `openspecOfferInitialization`/`openspecEnabled` props; conditional “Enable OpenSpec for this folder” DIRECTORY menu item; `seekToFolderOpenSpec` (expand+scroll+focus, no dialog). See change: add-openspec-init-affordances. `folderIsGitRepo` + the folder `+ New Worktree` gate both delegate to `resolveWorktreeAvailability` (fail-open, `folderGitMap`-aware), so a zero-session pinned git folder keeps the button. See change: fix-openspec-board-worktree-button-gating. Adds stub groups from `endedTotals` + ended expander/paging (`sessions_page`, per-group in-flight). See change: fix-connect-snapshot-frame-loss. Adds per-folder `Archive (N)` fold, lazy pagination, include-archive search filter, and swaps hide/unhide for archive/unarchive. See change: archive-sessions-lazy-load. In-flight page mark releases on a `pageReplyGen` change (any reply, incl. empty) rather than on `pagedCount`; `pageExhausted` hides the "more" affordance and suppresses `sessions_page`. See change: close-registry-frame-shed-gaps. List `<ul>` `p-2 pr-4`: right gutter clears the selected card's 14px outside glow halo (scroller clips x). See change: fix-selected-card-light-wash. Owns the shared `SessionMenuScopeContext` (`folder:<cwd>` | `session:<id>`) and the hover-intent listener; list region carries `data-session-list-region`. See change: add-session-actions-flyout. |

| `SessionSidebar.tsx` | Legacy compact session sidebar. Active + ended (`<details>`) lists with status dots, source icons, model,… → see `SessionSidebar.tsx.AGENTS.md` |

| `SessionStatusChip.tsx` | Card status chip (`variant` desktop/mobile), children = source icon + `StatusShapeBadge`. History ring span BEFORE children: loading = `animate-spin` ¾ arc `--accent-text` after `REPLAY_PILL_DELAY_MS` (delay keyed on session+`historyStartedAt`, so Retry re-runs it), waiting = dashed `--text-tertiary`, failed = solid `--tint-red-fg` (3:1 on every card bg). Owns `title` (+ ring text, `· Ns` past `SLOW_LOAD_MS` via `useNow`). sr-only static text, `role="status"` only when selected. Test ids `session-history-ring[data-history-phase]`, `session-history-ring-text`. See change: show-session-history-load-state. Exports `DESKTOP_CHIP_WIDTH_CLASS`, `TITLE_ROW_GAP_CLASS`, `SESSION_TEXT_COLUMN_CLASS` (`ml-6` = chip + gap; text column of card header rows 2–4). See change: compact-session-card-header. |

| `SessionSubcard.tsx` | Inset titled panel wrapper grouping session-card sections (OPENSPEC, WORKSPACE, PROCESS, MEMORY, FLOWS). → see `SessionSubcard.tsx.AGENTS.md` Legend `⋯` menu removed (`menu` prop gone); section options live in the menu's VIEW group. See change: add-session-actions-flyout. |

| `SortablePinnedGroup.tsx` | dnd-kit sortable wrapper for a pinned folder group (`data.type: "pinned-group"`), drop indicator via… → see `SortablePinnedGroup.tsx.AGENTS.md` |

| `SortableSessionCard.tsx` | dnd-kit sortable wrapper for a session card (`data.type: "session"`). Drag handle props fed to descendant `SessionCard` via `DragHandleCtx` — they now land on the card’s hover-revealed grip bead in the directory-rail band, not the deleted left gutter (see change: session-card-directory-rail). Exports `SortableSessionCard`, `useSessionCardDragHandle`. Wrapper carries `data-session-dragging` while dragging (hover strip + right-click stand down). See change: add-session-actions-flyout. |

| `SpawnErrorBanner.tsx` | Renders structured spawn error: code→hint, preflight reasons, stderr details, timeout banner. → see `SpawnErrorBanner.tsx.AGENTS.md` |

| `SpawnErrorToastHost.tsx` | App-level toast container for off-screen `spawn_error` events. Raw red → `--severity-error-*`. → see `SpawnErrorToastHost.tsx.AGENTS.md` |

| `TasksPopover.tsx` | Modal popover listing parseable tasks from an attached change's `tasks.md`, grouped by heading, native… → see `TasksPopover.tsx.AGENTS.md` |

| `TokenStatsBar.tsx` | Exports `TokenStatsBar`. Per-turn butterfly chart + stats panel; context bar removed (header `ContextRing`) → see `TokenStatsBar.tsx.AGENTS.md`. |

| `AcpEndedCallout.tsx` | Info callout for an ENDED ACP session: states it can't resume; one action = new session with the same agent. See change: add-acp-session-driver. |

| `DriverChip.tsx` | `ACP · <agent>` chip (icon+text). Nothing for pi. See change: add-acp-session-driver. |