paseo/PLAN_WORKSPACE_SOT_CLEANUP.md

Workspace Source-Of-Truth Cleanup Plan

Scope

Only this worktree: /Users/moboudra/.paseo/worktrees/1luy0po7/workspace-sot-hard-cut

Objectives

1. One server-owned source of truth for workspace identity.
2. Header and sidebar render the same workspace name field.
3. Remove client-side workspace construction from agent data.
4. Hard cut legacy paths (no dual-read compatibility layer).

Non-Objectives

1. No UI-only taxonomy in canonical model (subtitle, titleKind).
2. No React derivation from branch/path basename for workspace naming.
3. No silent fallbacks masking missing state (?? "", cwd fallback label).

Phase 0: Audit Existing Worktree Changes

1. Inventory all modified files in this worktree.
2. For each hunk, classify as keep, delete, or rewrite.
3. Build a bad-pattern list and remove all of these:

• Workspace naming fallback in React.
• Canonical payload fields that are presentation-only.
• Any primary label logic equivalent to Unknown branch.
• Any sidebar workspace list constructed from live agent rows.

Acceptance

1. Full inventory exists before further refactor work.
2. Every bad pattern has a mapped removal location.

Phase 1: Canonical Model Simplification

Define a minimal server canonical workspace entity:

• id: normalized cwd (single identity field)
• projectId: stable grouping key
• name: canonical workspace name (server computed)
• status: dominant state bucket
• activityAt: nullable ISO timestamp

Do not include UI/presentation fields in canonical payload.

Acceptance

1. No duplicate identity fields (workspaceId + cwd) in canonical contract.
2. No subtitle/title-kind fields in canonical contract.

Phase 2: Server Aggregation and RPC

1. Build workspace aggregation in session.ts from authoritative server state.
2. Compute workspace name once in server policy code.
3. Provide:

• fetch_workspaces_request/response snapshot RPC
• workspace_update incremental upsert/remove stream

4. Keep update semantics aligned with existing directory subscription behavior.

Acceptance

1. Non-git and git workspaces both resolve deterministic name.
2. No Unknown branch emitted by server.
3. Workspace update stream reflects agent lifecycle/state changes.

Phase 3: Client Store Wiring

1. Add workspace map in session store keyed by canonical id.
2. Hydrate only from fetch_workspaces.
3. Apply only workspace_update events for incremental updates.
4. Keep workspace state channel separate from agent-list derivation.

Acceptance

1. Workspace map is populated strictly from workspace RPCs.
2. No workspace assembly logic from agent lists in runtime/store.

Phase 4: UI Hard Cut

1. Sidebar row label reads only workspace.name.
2. Header title reads only workspace.name.
3. Remove all local workspace naming helpers based on cwd/branch.
4. Missing descriptor after hydration must render explicit missing-state UI, not fallback text.

Acceptance

1. Header and sidebar names are guaranteed identical source field.
2. No ?? ""/cwd/branch fallback paths for workspace name.

Phase 5: Legacy Deletion

1. Delete prior client sidebar workspace-building path(s).
2. Remove Unknown branch primary naming logic.
3. Remove any query/helper used only for old workspace naming.
4. Delete dead types/helpers from failed intermediate designs.

Acceptance

1. No app code path builds workspace rows from agent lists.
2. Legacy naming/building code fully removed in same change set.

Phase 6: Verification

1. Protocol/schema tests for workspace request/response/update.
2. Server aggregation tests:

• non-git workspace
• git branch workspace
• detached/headless workspace
• removal/update behavior

3. UI tests:

• selected workspace header name equals sidebar workspace name
• explicit missing-state rendering when descriptor absent post-hydration

4. Run npm run typecheck.
5. Manual validation in this worktree daemon+expo stack.

Acceptance

1. Tests pass.
2. Typecheck passes.
3. Manual verification confirms name parity and status correctness.

Execution Guardrails

1. Work only in workspace-sot-hard-cut.
2. No destructive git operations.
3. No fallback naming logic in React.
4. One naming policy and source of truth: server.
5. Hard cut means old code removed, not left dormant.