---
id: WF-PFM-CSH-003
title: Switch to another workspace
trigger: The header switcher selects another reachable workspace.
product_area: platform
module: console-shell
revision: 1
status: draft
design_intent: confirmed
origin: >-
  react-console:docs/url-architecture.md#6. Tenant from the URL (decided by
  Andrew 2026-10-14; final acceptance 2026-10-15)
implementation_evidence: observed
source_sha:
  react-console: baf6dae382d6f41dce976c7f848667ccc37e076f
  services-platform: ad3f6a6582843008ed0f5a17b131878d15829af1
implements:
  - CAP-PFM-CSH-011
moves:
  - STATE-PFM-CSH-002
crosses:
  - SVC-PFM-CSH-console-shell
inference: []
idempotency: >-
  Selecting the current workspace skips navigation; repeated target selections
  resolve through address entry.
concurrency: >-
  Choices are disabled while switching is active; navigation before that flag
  settles can still race and entry tickets order the resulting context changes.
hops:
  - 'n': 1
    actor_or_service: person
    action: >-
      Choose a reachable workspace from the header popover, using search when
      the list exceeds six.
    anchor: 'react-console:components/console/tenant-switcher.tsx:TenantSwitcher'
    seam: sync
    on_failure: Selection itself has no recovery branch.
    left_inconsistent: No context change occurs until a choice is made.
    observer: Person through workspace choices.
    provenance: observed
    source: 'react-console:components/console/tenant-switcher.tsx:TenantSwitcher'
  - 'n': 2
    actor_or_service: console (switcher)
    action: >-
      Ignore the current selection; otherwise remove the just-left marker and
      build the target area-and-list address without records or query.
    anchor: >-
      react-console:components/console/tenant-switcher.tsx:choose;
      lib/routes/match.ts:switchTenantPath
    seam: sync
    on_failure: The local address computation declares no retry.
    left_inconsistent: No record identity or query is carried into the target address.
    observer: No dedicated observer.
    provenance: test
    source: >-
      react-console:lib/routes/__tests__/routes.test.ts#keeps the workspace and
      resource list and drops record ids and queries
  - 'n': 3
    actor_or_service: console (switcher)
    action: Push the target address and display an immediate switch-success toast.
    anchor: 'react-console:components/console/tenant-switcher.tsx:choose'
    seam: sync
    on_failure: There is no entry-result check before acknowledgement.
    left_inconsistent: The person can receive confirmation before access is established.
    observer: Person through the success toast.
    provenance: observed
    source: >-
      react-console:components/console/tenant-switcher.tsx:choose
      (toast.success)
  - 'n': 4
    actor_or_service: console (workspace entry)
    action: Resolve the new address through strict workspace entry.
    anchor: 'react-console:components/console/tenant-id-gate.tsx:TenantIdGate'
    seam: sync
    on_failure: Show the entry refusal after the earlier success toast.
    left_inconsistent: The earlier acknowledgement can describe an entry that is later refused.
    observer: Person through the entry result.
    provenance: observed
    source: 'react-console:components/console/tenant-id-gate.tsx:TenantIdGate'
branches:
  - An unmatched planned path is retained during switching.
waits: []
evidence:
  - >-
    react-console at baf6dae: components/console/tenant-switcher.tsx;
    lib/routes/match.ts; components/console/tenant-id-gate.tsx.
controls: [TC-AVL-001, TC-AVL-004, TC-AVL-005, TC-AZ-001, TC-AZ-002, TC-AZ-003, TC-AZ-004, TC-AZ-005, TC-AZ-006, TC-DAT-001, TC-DAT-002, TC-DAT-003, TC-DAT-004, TC-IAM-001, TC-IAM-002, TC-IAM-003, TC-IAM-004, TC-IAM-005, TC-LOG-001, TC-LOG-004, TC-LOG-005, TC-MON-001, TC-PI-001, TC-PI-002, TC-PI-003, TC-PI-004, TC-PI-005, TC-PRV-001, TC-PRV-002, TC-TEN-001, TC-TEN-002, TC-TEN-003, TC-VEN-001, TC-VEN-002, TC-VEN-003]
---
# Switch to another workspace

## What It Does

The header switcher navigates to a reachable workspace while retaining the area and resource list. Record identities and the query are discarded, and the address-entry flow resolves authority again.

## The Flow

```mermaid
sequenceDiagram
  participant C as Switcher
  participant S as Workspace gate
  Note over C: choose workspace
  C->>S: navigate without records or query
  S-->>C: entry result after immediate toast
  Note over C: render destination or refusal
```

## When Something Fails

A workspace can become inaccessible after appearing in the list. Entry then explains the refusal even though the switcher already displayed success. The navigation action has no automatic retry.

## Open Design Questions

The confirmation should follow confirmed entry. The unused provider switch has a different unavailable-workspace fallback and should either be retired or share the chosen entry policy.