fix: UI/UX improvements, mode/branch fixes, and docs update

[ChrisRomp]

Changes

UI/UX Improvements

• Mobile scrolling: Added overflow-hidden + overscroll-behavior: none on html/body, overflow-x-hidden on chat panel, content containment on message bubbles
• Mobile sidebar: Auto-closes on session selection using direct window.matchMedia check (avoids stale closure)
• Scroll to bottom: Double requestAnimationFrame ensures scroll after DOM renders history
• Branch display: Moved from session cards to folder list (DirectoryPicker), shown below folder name in muted color with git icon
• Background tasks: Track subagent.started/completed events, broadcast via WS, show count badge in header

Session State Sync

• Handle session.mode_changed events from events.jsonl (data.newMode field)
• config_changed WS broadcast when mode changes
• sessionConfigs fallback map for CLI-owned sessions where bridge RPCs return stale defaults
• ensureConfigSeeded() lazy reader to handle REST/WS timing race
• /directories endpoint uses getLiveBranch() for real git branch instead of stale metadata
• Graceful defaults when RPC and fallback both unavailable

Documentation

• README: Added 5 missing env vars
• AGENTS.md: Added TLS vars, fixed event types (assistant.turn_end not session.idle)
• API.md: Added 3 missing REST endpoints, 8 missing WS message types
• ARCHITECTURE.md: Added DirectoryPicker to component listing

Testing

• Build passes (npm run build)
• All 61 tests pass (npx vitest run)
• Adversarial code review caught and fixed: wrong event field names (data.mode → data.newMode), stale idle-refetch race, missing sessionId validation on config_changed

[Copilot]

Pull request overview

This PR improves the web UI’s mobile usability and keeps the UI in sync with CLI-driven session state by expanding the server/client WebSocket protocol (config + background task count) and updating documentation accordingly.

Changes:

• Add mobile scrolling/layout fixes (scroll containment, markdown overflow handling, double-RAF scroll-to-bottom).
• Sync session mode changes from events.jsonl to the UI via new config_changed WS messages; add tasks_changed WS messages for background task count.
• Move git branch display to the directory picker and enrich /directories with live branch resolution; update docs (API/events/env vars).

Reviewed changes

Copilot reviewed 16 out of 16 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
server/src/types.ts	Adds new event + WS message types for config_changed and tasks_changed.
server/src/core/session-manager.ts	Tracks session config fallback from events.jsonl; emits new WS events; tracks subagent task counts.
server/src/channels/web/ws-handler.ts	Broadcasts new config_changed / tasks_changed events to subscribed clients.
server/src/channels/web/routes.ts	Enriches /directories response with live git branch values.
client/src/types.ts	Extends client WS message union + directory info shape with branch.
client/src/hooks/useWebSocket.ts	Handles new WS message types and exposes activeTaskCount + onConfigChanged.
client/src/components/layout/AppShell.tsx	Reacts to config updates, improves mobile sidebar closing, refetches config on idle transitions, shows background task badge.
client/src/components/sessions/SessionList.tsx	Removes branch display from session cards.
client/src/components/sessions/DirectoryPicker.tsx	Displays branch beneath directory name with git icon.
client/src/components/chat/ChatPanel.tsx	Improves scroll-to-bottom reliability and horizontal overflow behavior.
client/src/components/chat/MessageBubble.tsx	Improves markdown overflow/word-breaking; adds table scrolling behavior.
client/src/app.css	Locks body/html scrolling and overscroll behavior for mobile.
docs/API.md	Documents additional REST endpoints and WS message types.
docs/ARCHITECTURE.md	Updates component listing to include DirectoryPicker.
README.md	Documents additional environment variables.
AGENTS.md	Updates env var list and corrects CLI event type guidance.

Comments suppressed due to low confidence (2)

client/src/hooks/useWebSocket.ts:249

• Similarly, this config_changed handler can use the strongly-typed msg.sessionId/msg.mode/msg.modelId/msg.agent fields directly instead of casting to any. Keeping the typed access helps catch server/client protocol drift at compile time.

        case 'config_changed':
          if (configChangedCallback.current) {
            configChangedCallback.current({
              sessionId: (msg as any).sessionId,
              mode: (msg as any).mode,
              modelId: (msg as any).modelId,
              agent: (msg as any).agent,
            });
          }
          break;

server/src/core/session-manager.ts:848

• getSessionAgent() claims to prefer an events.jsonl-derived agent, but sessionConfigs is never populated with an agent anywhere (only mode is seeded/updated). As written, if (config?.agent) can never be true, and the comment/field are misleading. Either implement seeding/updating agent from an event that carries it, or remove the agent fallback path and related sessionConfigs.agent field/comment to avoid confusion.

  async getSessionAgent(sessionId: string): Promise<{ name?: string; displayName?: string }> {
    // Prefer events.jsonl value — ground truth for CLI-owned sessions
    this.ensureConfigSeeded(sessionId);
    const config = this.sessionConfigs.get(sessionId);
    if (config?.agent) return { name: config.agent };
    try {

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.