paseo/PLAN_ITERATION_4_WORKSPACE_HEADER_LAYOUT_RESTORE.md

Iteration 4 — Workspace header/layout restore (tabs + explorer parity)

Goal

Fix regressions introduced by the workspace-tabs migration by restoring the legacy workspace/agent screen layout and gestures, while keeping the new workspace tab model (agent + terminal tabs).

This iteration focuses on header controls + panel layout parity, and fixing the broken New tab menu on desktop.

Context (what must remain true)

• Left sidebar stays as-is (projects/workspaces list) and keeps existing swipe/gesture behavior.
• Right sidebar stays as-is (Changes/Files explorer) and keeps existing swipe/gesture behavior.
• Terminals and agents are first-class tabs:
  • Terminal tabs are not “special” or in a different layout region.
  • New tab creation UI must treat agent + terminal options equally (same menu surface).
• Workspace header shows workspace name (branch name when git, otherwise workspace name).
• No “legacy view” routing or duplicate UI kept around; everything uses the new workspace-tabs flow.
• Do not touch/restart the main daemon on :6767. Tests/dev servers must use isolated ports/homes.

UX Requirements (desktop + mobile)

Header structure (parity with legacy AgentReadyScreen)

Workspace screen header must include:

1. Left sidebar toggle (same component/gesture behavior as before).
2. Title = branch name if git & branch is known; otherwise workspace name.
3. Right explorer toggle (same behavior as before):
   • Desktop icon: panel/right icon
   • Mobile icon: GitBranch if git checkout, else Folder
   • Correct aria-expanded state and open/closed coloring
4. New tab dropdown button that reliably opens on-screen (desktop + mobile).
5. Overflow (kebab / 3-dot) menu for agent chat:
   • Visible only when the active tab is an agent (i.e. “chat context”).
   • Menu items should mirror legacy intent (at minimum: open chat view with full header).

Tabs

• Tabs remain horizontally scrollable (browser-style).
• Tabs must include an icon per tab type:
  • Agent tabs show provider icon (Claude/Codex; fallback bot).
  • Terminal tabs show terminal icon.
• Tabs must support closing terminal tabs via X (desktop):
  • Confirm destructive close.
  • Killing terminal updates the list and selects a valid remaining tab (or falls back to workspace root).

Panel layout

• Keep the screen layout: header → tabs row → content center → explorer right panel.
• Do not nest the explorer UI inside tab content in a way that changes layout/gesture wiring.

Gestures (must not regress)

• Left sidebar open/close gestures unchanged.
• Explorer (right sidebar) open/close gestures unchanged.
• Mobile “open explorer” pan gesture on content remains wired the same as before.

Acceptance Criteria

New tab dropdown

• Clicking the New tab header button opens a dropdown that is visible on-screen on desktop (not positioned off-screen).
• Dropdown contains two options:
  • Agent tab → opens draft agent flow for that workspace.
  • Terminal tab → creates a terminal and opens its tab.

Workspace header parity

• Header shows both sidebar toggles (left menu + right explorer toggle).
• Right explorer toggle icon matches legacy behavior:
  • Mobile: git vs folder icon
  • Desktop: panel-right icon
• Explorer toggle opens/closes the explorer reliably and updates aria-expanded.

Agent kebab menu

• When an agent tab is active, the kebab menu is visible and opens correctly.
• When a terminal tab is active, the kebab menu is not shown.

Tab close

• Terminal tabs display an X close affordance on desktop (hover or active).
• Closing a terminal:
  • Confirms close
  • Calls kill terminal RPC
  • Removes the tab from the list
  • Focuses a valid remaining tab (or navigates to workspace root if none)

Regression checks

• Explorer panel remains on the right and behaves the same as before (including gestures).
• Left sidebar gestures remain unchanged.

Verification

Automated

• npm run typecheck (must pass)
• npm run test --workspace=@getpaseo/app (must pass)
• Playwright E2E:
  • Add/ensure a spec that asserts New tab dropdown opens and is within the viewport.
  • Add/ensure a spec that toggles explorer via header button and asserts open/close.

Manual (agent-browser)

Desktop (Metro web):

• Confirm header shows: left toggle, title, explorer toggle, New tab dropdown, kebab menu (agent only).
• Confirm New tab dropdown opens and is visible.
• Confirm terminal tab shows X close and closes correctly.

Mobile viewport (Metro web responsive):

• Confirm explorer toggle uses git/folder icon.
• Confirm swipes/gestures for sidebars still work.

Non-goals (explicitly out of scope for this iteration)

• Panel splitting / drag-to-split implementation (architectural compatibility only).
• New workspace creation UX, workspace archiving rules beyond existing behavior.
• Agent hydration/indexing redesign (local SQL DB) beyond current in-memory hydration.