From 9413a471cb98a43ce6c653cbc1d76d2fba8e1f10 Mon Sep 17 00:00:00 2001
From: leyoonafr <codeacme17@gmail.com>
Date: Mon, 31 Aug 2026 01:33:38 +0800
Subject: [PATCH] feat: add safe branch switching (#12)

---
 .../src/repository-protocol-adapter.ts        |   6 +
 apps/launcher/src/standalone-runtime.ts       |   5 +
 apps/ui/src/App.tsx                           |   4 +
 .../RepositoryOverview.interactions.test.tsx  | 129 ++++++
 apps/ui/src/RepositoryOverview.tsx            | 123 +++++-
 apps/ui/src/overview-fixtures.ts              |   6 +
 .../ui/src/protocol-repository-source.test.ts |  84 +++-
 apps/ui/src/protocol-repository-source.ts     |  59 ++-
 apps/ui/src/repository-overview-model.ts      |  17 +-
 apps/ui/src/repository-store.ts               | 148 ++++++-
 packages/protocol/src/schemas.ts              |   1 +
 packages/repository-engine/src/index.ts       |   1 +
 .../src/repository-engine.ts                  |   2 +-
 .../src/repository-observation.test.ts        |  21 +
 .../src/repository-observation.ts             |  92 +++-
 .../src/repository-refresh.ts                 |  24 +
 .../src/repository-session.ts                 | 416 +++++++++++++++++-
 tests/e2e/protocol-runtime.e2e.test.ts        |  83 ++++
 .../branch-switching.integration.test.ts      | 393 +++++++++++++++++
 19 files changed, 1590 insertions(+), 24 deletions(-)
 create mode 100644 tests/integration/branch-switching.integration.test.ts

diff --git a/apps/launcher/src/repository-protocol-adapter.ts b/apps/launcher/src/repository-protocol-adapter.ts
index 7333f74..8981e66 100644
--- a/apps/launcher/src/repository-protocol-adapter.ts
+++ b/apps/launcher/src/repository-protocol-adapter.ts
@@ -126,6 +126,12 @@ function worktreeStatus(source: PublishedWorktreeSnapshot) {
           : 'The Worktree status is unavailable.',
     };
   }
+  if (source.status.inProgressOperation !== undefined) {
+    return {
+      kind: 'in_progress' as const,
+      operation: source.status.inProgressOperation,
+    };
+  }
   if (source.status.clean) return { kind: 'clean' as const };
   return {
     kind: 'changed' as const,
diff --git a/apps/launcher/src/standalone-runtime.ts b/apps/launcher/src/standalone-runtime.ts
index 3d27d57..6bfc179 100644
--- a/apps/launcher/src/standalone-runtime.ts
+++ b/apps/launcher/src/standalone-runtime.ts
@@ -67,6 +67,11 @@ export async function startStandaloneRuntime(
         repositorySession === undefined || options.projectPath === undefined
           ? undefined
           : {
+              branchSearch: (request) =>
+                repositorySession!.searchBranches(request),
+              commands: (request) => repositorySession!.dispatch(request),
+              operationRecovery: (operationId) =>
+                repositorySession!.recoverOperation(operationId),
               snapshot: async () =>
                 toProtocolRepositorySnapshot(
                   await repositorySession!.requestRefresh(),
diff --git a/apps/ui/src/App.tsx b/apps/ui/src/App.tsx
index 5d06637..bd84b6c 100644
--- a/apps/ui/src/App.tsx
+++ b/apps/ui/src/App.tsx
@@ -7,6 +7,10 @@ const loadingStore = createRepositoryStore({
   subscribe: () => () => undefined,
   requestRefresh: () => undefined,
   requestFetch: () => undefined,
+  searchBranches: async () => ({ refsRevision: 0, candidates: [] }),
+  switchBranch: async () => {
+    throw new Error('Branch switching is unavailable while loading.');
+  },
 });
 
 export function App({
diff --git a/apps/ui/src/RepositoryOverview.interactions.test.tsx b/apps/ui/src/RepositoryOverview.interactions.test.tsx
index 35607dd..eccd231 100644
--- a/apps/ui/src/RepositoryOverview.interactions.test.tsx
+++ b/apps/ui/src/RepositoryOverview.interactions.test.tsx
@@ -3,6 +3,7 @@
 import { act } from 'react';
 import { createRoot, type Root } from 'react-dom/client';
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { operationIdSchema, refIdSchema } from '@codex-git/protocol';
 
 import { App } from './overview.js';
 import { createOverviewFixture } from './overview-fixtures.js';
@@ -381,6 +382,134 @@ describe('Repository overview interactions', () => {
     );
   });
 
+  it('separates Branch groups, disables occupied Local Branches, and navigates to their Worktree', async () => {
+    const fixture = createOverviewFixture('many-worktrees');
+    const fixtureState = fixture.source.getSnapshot();
+    const occupiedWorktree =
+      fixtureState.kind === 'repository'
+        ? fixtureState.snapshot.worktrees.find(
+            ({ displayName }) => displayName === 'agent-alpha',
+          )
+        : undefined;
+    if (occupiedWorktree === undefined) throw new Error('Missing Worktree');
+    const source = {
+      ...fixture.source,
+      async searchBranches() {
+        return {
+          refsRevision: 2,
+          candidates: [
+            {
+              refId: refIdSchema.parse('ref_0123456789abcdef0123456789abcdef'),
+              kind: 'local' as const,
+              displayName: 'available',
+              occupiedBy: null,
+            },
+            {
+              refId: refIdSchema.parse('ref_1123456789abcdef0123456789abcdef'),
+              kind: 'local' as const,
+              displayName: 'feat/agent-alpha',
+              occupiedBy: occupiedWorktree.worktreeId,
+            },
+            {
+              refId: refIdSchema.parse('ref_2123456789abcdef0123456789abcdef'),
+              kind: 'remote_tracking' as const,
+              displayName: 'origin/review-ready',
+              occupiedBy: null,
+            },
+          ],
+        };
+      },
+    };
+    const store = createRepositoryStore(source);
+    act(() => root.render(<App store={store} />));
+
+    await act(async () => button('Switch Branch for codex-git').click());
+
+    expect(container.textContent).toContain('Local Branches');
+    expect(container.textContent).toContain('Remote-tracking Branches');
+    expect(button('Switch codex-git to feat/agent-alpha').disabled).toBe(true);
+    act(() => button('Go to Worktree occupying feat/agent-alpha').click());
+    expect(container.querySelector('#worktree-title')?.textContent).toBe(
+      'agent-alpha',
+    );
+  });
+
+  it('submits an exact Branch target and clears the picker after reconciled success', async () => {
+    const fixture = createOverviewFixture('one-worktree');
+    const targetRefId = refIdSchema.parse(
+      'ref_3123456789abcdef0123456789abcdef',
+    );
+    const switchBranch = vi.fn(async () => {
+      const current = fixture.source.getSnapshot();
+      if (current.kind !== 'repository') throw new Error('Expected Repository');
+      fixture.publish({
+        kind: 'repository',
+        snapshot: {
+          ...current.snapshot,
+          repositoryRevision: current.snapshot.repositoryRevision + 1,
+          refsRevision: current.snapshot.refsRevision + 1,
+          worktrees: current.snapshot.worktrees.map((worktree) => ({
+            ...worktree,
+            worktreeRevision: worktree.worktreeRevision + 1,
+            head: {
+              kind: 'local_branch' as const,
+              displayName: 'review-ready',
+              objectId: '1123456789abcdef0123456789abcdef01234567',
+            },
+          })),
+        },
+      });
+      return {
+        kind: 'succeeded' as const,
+        operationId: operationIdSchema.parse(
+          'operation_0123456789abcdef0123456789abcdef',
+        ),
+        result: {
+          kind: 'branch_switch' as const,
+          displayName: 'review-ready',
+        },
+      };
+    });
+    const source = {
+      ...fixture.source,
+      async searchBranches() {
+        return {
+          refsRevision: 1,
+          candidates: [
+            {
+              refId: targetRefId,
+              kind: 'local' as const,
+              displayName: 'review-ready',
+              occupiedBy: null,
+            },
+          ],
+        };
+      },
+      switchBranch,
+    };
+    const store = createRepositoryStore(source);
+    act(() => root.render(<App store={store} />));
+    await act(async () => button('Switch Branch for codex-git').click());
+
+    await act(async () => button('Switch codex-git to review-ready').click());
+
+    expect(switchBranch).toHaveBeenCalledWith(
+      expect.objectContaining({
+        expectedRefsRevision: 1,
+        expectedWorktreeRevision: 1,
+        refId: targetRefId,
+      }),
+    );
+    expect(container.querySelector('#worktree-title')?.textContent).toBe(
+      'codex-git',
+    );
+    expect(container.textContent).toContain('Local Branch review-ready');
+    expect(container.textContent).not.toContain('Search cached Branches');
+    expect(container.querySelector('[role="status"]')?.textContent).toContain(
+      'Branch or HEAD changed',
+    );
+  });
+
   it('does not dispose a caller-owned store when the overview unmounts', () => {
     const fixture = createOverviewFixture('one-worktree');
     const store = createRepositoryStore(fixture.source);
diff --git a/apps/ui/src/RepositoryOverview.tsx b/apps/ui/src/RepositoryOverview.tsx
index 456c676..34df3ea 100644
--- a/apps/ui/src/RepositoryOverview.tsx
+++ b/apps/ui/src/RepositoryOverview.tsx
@@ -16,6 +16,7 @@ export function RepositoryOverview({
     store.getSnapshot,
     store.getSnapshot,
   );
+  const branchPicker = state.branchPicker;
   const worktreeButtons = useRef(new Map<string, HTMLButtonElement>());
   const searchInput = useRef<HTMLInputElement>(null);
   const worktreeTitle = useRef<HTMLHeadingElement>(null);
@@ -321,7 +322,8 @@ export function RepositoryOverview({
               <button
                 aria-label={`Switch Branch for ${selected.displayName}`}
                 type="button"
-                disabled
+                disabled={!branchSwitchAllowed(selected, snapshot.operations)}
+                onClick={() => store.openBranchPicker()}
               >
                 Switch Branch
               </button>
@@ -333,6 +335,109 @@ export function RepositoryOverview({
                 Upstream actions
               </button>
             </div>
+            {branchPicker.kind === 'closed' ? null : (
+              <section aria-label={`Switch Branch for ${selected.displayName}`}>
+                <h3>Switch Branch</h3>
+                <label>
+                  Search cached Branches
+                  <input
+                    type="search"
+                    value={branchPicker.query}
+                    onChange={(event) =>
+                      store.setBranchQuery(event.currentTarget.value)
+                    }
+                  />
+                </label>
+                <button type="button" onClick={() => store.closeBranchPicker()}>
+                  Close
+                </button>
+                {branchPicker.kind === 'loading' ? (
+                  <p role="status">Loading cached Branches…</p>
+                ) : branchPicker.kind === 'failed' ? (
+                  <p role="alert">{branchPicker.message}</p>
+                ) : (
+                  <>
+                    {branchPicker.message === null ? null : (
+                      <p role="alert">{branchPicker.message}</p>
+                    )}
+                    {(['local', 'remote_tracking'] as const).map((kind) => {
+                      const branches = branchPicker.candidates.filter(
+                        (candidate) => candidate.kind === kind,
+                      );
+                      return (
+                        <section key={kind}>
+                          <h4>
+                            {kind === 'local'
+                              ? 'Local Branches'
+                              : 'Remote-tracking Branches'}
+                          </h4>
+                          {branches.length === 0 ? (
+                            <p>No matching Branches.</p>
+                          ) : (
+                            <ul>
+                              {branches.map((branch) => {
+                                const occupiedElsewhere =
+                                  branch.occupiedBy !== null &&
+                                  branch.occupiedBy !== selected.worktreeId;
+                                const occupyingWorktree =
+                                  branch.occupiedBy === null
+                                    ? undefined
+                                    : snapshot.worktrees.find(
+                                        ({ worktreeId }) =>
+                                          worktreeId === branch.occupiedBy,
+                                      );
+                                return (
+                                  <li key={branch.refId}>
+                                    <button
+                                      aria-label={`Switch ${selected.displayName} to ${branch.displayName}`}
+                                      disabled={
+                                        occupiedElsewhere ||
+                                        branchPicker.switchingRefId !== null
+                                      }
+                                      type="button"
+                                      onClick={() =>
+                                        store.switchBranch(branch.refId)
+                                      }
+                                    >
+                                      {branch.displayName}
+                                    </button>
+                                    {branch.warning == null ? null : (
+                                      <span role="note">{branch.warning}</span>
+                                    )}
+                                    {!occupiedElsewhere ? null : (
+                                      <>
+                                        <span>
+                                          Occupied by{' '}
+                                          {occupyingWorktree?.displayName ??
+                                            'another Worktree'}
+                                        </span>
+                                        <button
+                                          aria-label={`Go to Worktree occupying ${branch.displayName}`}
+                                          type="button"
+                                          onClick={() => {
+                                            if (branch.occupiedBy !== null) {
+                                              store.selectWorktree(
+                                                branch.occupiedBy,
+                                              );
+                                            }
+                                          }}
+                                        >
+                                          Go to Worktree
+                                        </button>
+                                      </>
+                                    )}
+                                  </li>
+                                );
+                              })}
+                            </ul>
+                          )}
+                        </section>
+                      );
+                    })}
+                  </>
+                )}
+              </section>
+            )}
             <label>
               Commit Draft for {selected.displayName}
               <textarea
@@ -360,6 +465,22 @@ export function RepositoryOverview({
   );
 }
 
+function branchSwitchAllowed(
+  worktree: WorktreeOverviewSnapshot,
+  operations: RepositoryOverviewSnapshot['operations'],
+): boolean {
+  return (
+    (worktree.availability === undefined ||
+      worktree.availability.kind === 'available') &&
+    worktree.freshness.kind === 'current' &&
+    worktree.status.kind === 'clean' &&
+    !operations.some(
+      ({ category, phase }) =>
+        category === 'branch_switch' && phase !== 'terminal',
+    )
+  );
+}
+
 function compareWorktrees(
   left: WorktreeOverviewSnapshot,
   right: WorktreeOverviewSnapshot,
diff --git a/apps/ui/src/overview-fixtures.ts b/apps/ui/src/overview-fixtures.ts
index a22833d..d4b58da 100644
--- a/apps/ui/src/overview-fixtures.ts
+++ b/apps/ui/src/overview-fixtures.ts
@@ -74,6 +74,12 @@ function createMutableFixture(
       requestFetch(remoteId) {
         fetch.push(remoteId);
       },
+      async searchBranches() {
+        return { refsRevision: 0, candidates: [] };
+      },
+      async switchBranch() {
+        throw new Error('Branch switching is not configured for this fixture.');
+      },
     },
     publish(nextState) {
       state = nextState;
diff --git a/apps/ui/src/protocol-repository-source.test.ts b/apps/ui/src/protocol-repository-source.test.ts
index fe2f09c..5c0f84b 100644
--- a/apps/ui/src/protocol-repository-source.test.ts
+++ b/apps/ui/src/protocol-repository-source.test.ts
@@ -1,6 +1,10 @@
 import { describe, expect, it } from 'vitest';
 
-import { PROTOCOL_VERSION, PROTOCOL_VERSION_HEADER } from '@codex-git/protocol';
+import {
+  PROTOCOL_VERSION,
+  PROTOCOL_VERSION_HEADER,
+  worktreeIdSchema,
+} from '@codex-git/protocol';
 
 import { createProtocolRepositorySource } from './protocol-repository-source.js';
 
@@ -193,6 +197,60 @@ describe('ProtocolRepositorySource', () => {
       );
     });
   });
+
+  it('searches cached Branches and waits for an authoritative switch result', async () => {
+    const requests: string[] = [];
+    const source = createProtocolRepositorySource({
+      projectPath: '/projects/codex-git',
+      sessionUrl: 'http://127.0.0.1:4173/instance/fixture-token/v1/session',
+      createEventSource: () => new FakeEventSource(),
+      fetch: async (input) => {
+        const url = String(input);
+        requests.push(url.split('/').at(-1) ?? '');
+        if (url.endsWith('/session')) {
+          return jsonResponse({
+            ...sessionMetadata,
+            capabilities: {
+              ...sessionMetadata.capabilities,
+              branchSearch: true,
+              commands: true,
+              operationRecovery: true,
+            },
+          });
+        }
+        if (url.endsWith('/branches')) return jsonResponse(branchSearchResult);
+        if (url.endsWith('/commands')) return jsonResponse(operationReceipt);
+        if (url.endsWith('/operations')) return jsonResponse(operationResult);
+        return jsonResponse(repositorySnapshot);
+      },
+    });
+    await until(() => source.getSnapshot().kind === 'repository');
+
+    const branches = await source.searchBranches(
+      worktreeIdSchema.parse(repositorySnapshot.worktrees[0]!.worktreeId),
+      'review',
+    );
+    const result = await source.switchBranch({
+      worktreeId: worktreeIdSchema.parse(
+        repositorySnapshot.worktrees[0]!.worktreeId,
+      ),
+      expectedWorktreeRevision:
+        repositorySnapshot.worktrees[0]!.worktreeRevision,
+      expectedRefsRevision: branches.refsRevision,
+      refId: branches.candidates[0]!.refId,
+    });
+
+    expect(branches).toEqual(branchSearchResult);
+    expect(result).toEqual(operationResult);
+    expect(requests).toEqual([
+      'session',
+      'snapshot',
+      'branches',
+      'commands',
+      'operations',
+      'snapshot',
+    ]);
+  });
 });
 
 class FakeEventSource {
@@ -270,6 +328,30 @@ const repositorySnapshot = {
   operations: [],
 };
 
+const branchSearchResult = {
+  refsRevision: 1,
+  candidates: [
+    {
+      refId: 'ref_0123456789abcdef0123456789abcdef',
+      kind: 'local',
+      displayName: 'review-ready',
+      occupiedBy: null,
+    },
+  ],
+};
+
+const operationReceipt = {
+  operationId: 'operation_0123456789abcdef0123456789abcdef',
+  clientCommandId: 'command_0123456789abcdef0123456789abcdef',
+  disposition: 'accepted',
+};
+
+const operationResult = {
+  kind: 'succeeded',
+  operationId: operationReceipt.operationId,
+  result: { kind: 'branch_switch', displayName: 'review-ready' },
+};
+
 function jsonResponse(value: unknown): Response {
   return new Response(JSON.stringify(value), {
     headers: { 'content-type': 'application/json' },
diff --git a/apps/ui/src/protocol-repository-source.ts b/apps/ui/src/protocol-repository-source.ts
index 7e4a86a..eb2e585 100644
--- a/apps/ui/src/protocol-repository-source.ts
+++ b/apps/ui/src/protocol-repository-source.ts
@@ -1,10 +1,14 @@
 import {
   PROTOCOL_VERSION,
   PROTOCOL_VERSION_HEADER,
+  branchSearchResultSchema,
+  operationReceiptSchema,
+  operationResultSchema,
   repositorySnapshotResultSchema,
   sessionMetadataSchema,
   sseInvalidationSchema,
 } from '@codex-git/protocol';
+import type { BranchSearchRequest, ProductCommand } from '@codex-git/protocol';
 
 import type {
   RepositoryOverviewSource,
@@ -130,6 +134,38 @@ export function createProtocolRepositorySource(
     requestFetch() {
       // Fetch is enabled by Issue #13. The overview remains truthful until then.
     },
+    async searchBranches(worktreeId, query) {
+      const response = await protocolPost(
+        fetcher,
+        endpointUrl(options.sessionUrl, 'branches'),
+        { worktreeId, query } satisfies BranchSearchRequest,
+      );
+      if (!response.ok) throw new Error('Branch search failed.');
+      return branchSearchResultSchema.parse(await response.json());
+    },
+    async switchBranch(request) {
+      const clientCommandId = createClientCommandId();
+      const command = {
+        kind: 'switch_branch',
+        ...request,
+      } satisfies ProductCommand;
+      const submitted = await protocolPost(
+        fetcher,
+        endpointUrl(options.sessionUrl, 'commands'),
+        { clientCommandId, command },
+      );
+      if (!submitted.ok) throw new Error('Branch switch submission failed.');
+      const receipt = operationReceiptSchema.parse(await submitted.json());
+      const recovery = await protocolPost(
+        fetcher,
+        endpointUrl(options.sessionUrl, 'operations'),
+        { operationId: receipt.operationId },
+      );
+      if (!recovery.ok) throw new Error('Branch switch recovery failed.');
+      const result = operationResultSchema.parse(await recovery.json());
+      await requestSnapshot();
+      return result;
+    },
   };
 }
 
@@ -182,6 +218,27 @@ function protocolFetch(fetcher: typeof fetch, url: string) {
   });
 }
 
-function endpointUrl(sessionUrl: string, endpoint: 'events' | 'snapshot') {
+function protocolPost(fetcher: typeof fetch, url: string, body: unknown) {
+  return fetcher(url, {
+    method: 'POST',
+    headers: {
+      'content-type': 'application/json',
+      [PROTOCOL_VERSION_HEADER]: String(PROTOCOL_VERSION),
+    },
+    body: JSON.stringify(body),
+  });
+}
+
+function endpointUrl(
+  sessionUrl: string,
+  endpoint: 'branches' | 'commands' | 'events' | 'operations' | 'snapshot',
+) {
   return sessionUrl.replace(/\/session$/u, `/${endpoint}`);
 }
+
+function createClientCommandId() {
+  const bytes = globalThis.crypto.getRandomValues(new Uint8Array(16));
+  return `command_${Array.from(bytes, (byte) =>
+    byte.toString(16).padStart(2, '0'),
+  ).join('')}` as const;
+}
diff --git a/apps/ui/src/repository-overview-model.ts b/apps/ui/src/repository-overview-model.ts
index 03038e3..14bcacb 100644
--- a/apps/ui/src/repository-overview-model.ts
+++ b/apps/ui/src/repository-overview-model.ts
@@ -1,4 +1,9 @@
-import type { RepositorySnapshot } from '@codex-git/protocol';
+import type {
+  BranchSearchResult,
+  OperationResult,
+  RefId,
+  RepositorySnapshot,
+} from '@codex-git/protocol';
 
 type ProtocolWorktree = RepositorySnapshot['worktrees'][number];
 type ProtocolOperation = RepositorySnapshot['operations'][number];
@@ -90,4 +95,14 @@ export interface RepositoryOverviewSource {
   subscribe(listener: () => void): () => void;
   requestRefresh(): void;
   requestFetch(remoteId: ProtocolRemote['remoteId'] | null): void;
+  searchBranches(
+    worktreeId: ProtocolWorktree['worktreeId'],
+    query: string,
+  ): Promise<BranchSearchResult>;
+  switchBranch(request: {
+    readonly worktreeId: ProtocolWorktree['worktreeId'];
+    readonly expectedWorktreeRevision: number;
+    readonly expectedRefsRevision: number;
+    readonly refId: RefId;
+  }): Promise<OperationResult>;
 }
diff --git a/apps/ui/src/repository-store.ts b/apps/ui/src/repository-store.ts
index fd02cea..a014208 100644
--- a/apps/ui/src/repository-store.ts
+++ b/apps/ui/src/repository-store.ts
@@ -1,4 +1,26 @@
-import type { FileId, WorktreeId } from '@codex-git/protocol';
+import type {
+  BranchSearchResult,
+  FileId,
+  RefId,
+  WorktreeId,
+} from '@codex-git/protocol';
+
+export type BranchPickerState =
+  | { readonly kind: 'closed' }
+  | { readonly kind: 'loading'; readonly query: string }
+  | {
+      readonly kind: 'ready';
+      readonly query: string;
+      readonly refsRevision: number;
+      readonly candidates: BranchSearchResult['candidates'];
+      readonly switchingRefId: RefId | null;
+      readonly message: string | null;
+    }
+  | {
+      readonly kind: 'failed';
+      readonly query: string;
+      readonly message: string;
+    };
 
 import type {
   RepositoryOverviewSnapshot,
@@ -15,6 +37,7 @@ export interface RepositoryStoreSnapshot {
   readonly selectedFileId: FileId | null;
   readonly selectionNotice: string | null;
   readonly focusRecoveryRevision: number;
+  readonly branchPicker: BranchPickerState;
 }
 
 export interface RepositoryStore {
@@ -30,6 +53,10 @@ export interface RepositoryStore {
   requestFetch(
     remoteId: RepositoryOverviewSnapshot['remotes'][number]['remoteId'] | null,
   ): void;
+  openBranchPicker(): void;
+  closeBranchPicker(): void;
+  setBranchQuery(query: string): void;
+  switchBranch(refId: RefId): void;
 }
 
 export function createRepositoryStore(
@@ -46,6 +73,8 @@ export function createRepositoryStore(
   let selectedFileId: FileId | null = null;
   let selectionNotice: string | null = null;
   let focusRecoveryRevision = 0;
+  let branchPicker: BranchPickerState = { kind: 'closed' };
+  let branchRequestGeneration = 0;
   let storeSnapshot = buildSnapshot();
   let disposed = false;
 
@@ -73,11 +102,13 @@ export function createRepositoryStore(
             ? 'The selected Worktree is no longer available.'
             : `The selected Worktree changed. ${replacement.displayName} is now selected.`;
       if (previousSelection !== null) focusRecoveryRevision += 1;
+      closeBranches();
     } else if (branchChanged) {
       selectedHeadKey = headSelectionKey(selected);
       selectedFileId = null;
       selectionNotice =
         'Branch or HEAD changed; the previous file selection was cleared.';
+      closeBranches();
     } else {
       selectionNotice = null;
     }
@@ -108,6 +139,7 @@ export function createRepositoryStore(
       selectedHeadKey = headSelectionKey(worktree);
       selectedFileId = null;
       selectionNotice = null;
+      closeBranches();
       emit();
     },
     setSearchQuery(query) {
@@ -134,8 +166,121 @@ export function createRepositoryStore(
     requestFetch: (remoteId) => {
       if (!disposed) source.requestFetch(remoteId);
     },
+    openBranchPicker() {
+      if (disposed || selectedWorktreeId === null) return;
+      void loadBranches('');
+    },
+    closeBranchPicker() {
+      if (disposed) return;
+      closeBranches();
+      emit();
+    },
+    setBranchQuery(query) {
+      if (disposed || selectedWorktreeId === null) return;
+      void loadBranches(query);
+    },
+    switchBranch(refId) {
+      if (
+        disposed ||
+        selectedWorktreeId === null ||
+        branchPicker.kind !== 'ready' ||
+        branchPicker.switchingRefId !== null
+      ) {
+        return;
+      }
+      const worktree = findWorktree(sourceState, selectedWorktreeId);
+      const candidate = branchPicker.candidates.find(
+        (branch) => branch.refId === refId,
+      );
+      if (
+        worktree === null ||
+        candidate === undefined ||
+        (candidate.occupiedBy !== null &&
+          candidate.occupiedBy !== worktree.worktreeId)
+      ) {
+        return;
+      }
+      const currentPicker = branchPicker;
+      branchPicker = { ...currentPicker, switchingRefId: refId, message: null };
+      emit();
+      void source
+        .switchBranch({
+          worktreeId: worktree.worktreeId,
+          expectedWorktreeRevision: worktree.worktreeRevision,
+          expectedRefsRevision: currentPicker.refsRevision,
+          refId,
+        })
+        .then((result) => {
+          if (disposed) return;
+          if (result.kind === 'succeeded') {
+            closeBranches();
+            emit();
+            return;
+          }
+          const message =
+            'message' in result
+              ? result.message
+              : 'The Branch switch did not complete.';
+          branchPicker = {
+            ...currentPicker,
+            switchingRefId: null,
+            message,
+          };
+          emit();
+          void loadBranches(currentPicker.query);
+        })
+        .catch(() => {
+          if (disposed) return;
+          branchPicker = {
+            ...currentPicker,
+            switchingRefId: null,
+            message: 'The Branch switch could not be submitted.',
+          };
+          emit();
+        });
+    },
   };
 
+  async function loadBranches(query: string) {
+    const worktreeId = selectedWorktreeId;
+    if (worktreeId === null) return;
+    const ownGeneration = ++branchRequestGeneration;
+    branchPicker = { kind: 'loading', query };
+    emit();
+    try {
+      const result = await source.searchBranches(worktreeId, query);
+      if (
+        disposed ||
+        ownGeneration !== branchRequestGeneration ||
+        selectedWorktreeId !== worktreeId
+      ) {
+        return;
+      }
+      branchPicker = {
+        kind: 'ready',
+        query,
+        refsRevision: result.refsRevision,
+        candidates: result.candidates,
+        switchingRefId: null,
+        message: null,
+      };
+      emit();
+    } catch {
+      if (disposed || ownGeneration !== branchRequestGeneration) return;
+      branchPicker = {
+        kind: 'failed',
+        query,
+        message: 'Cached Branches could not be loaded.',
+      };
+      emit();
+    }
+  }
+
+  function closeBranches() {
+    branchRequestGeneration += 1;
+    branchPicker = { kind: 'closed' };
+  }
+
   function buildSnapshot(): RepositoryStoreSnapshot {
     return {
       source: sourceState,
@@ -145,6 +290,7 @@ export function createRepositoryStore(
       selectedFileId,
       selectionNotice,
       focusRecoveryRevision,
+      branchPicker,
     };
   }
 
diff --git a/packages/protocol/src/schemas.ts b/packages/protocol/src/schemas.ts
index a172b87..6005987 100644
--- a/packages/protocol/src/schemas.ts
+++ b/packages/protocol/src/schemas.ts
@@ -77,6 +77,7 @@ export const branchSearchResultSchema = z.strictObject({
         kind: z.enum(['local', 'remote_tracking']),
         displayName: z.string().min(1).max(1_024),
         occupiedBy: worktreeIdSchema.nullable(),
+        warning: z.string().min(1).max(512).nullable().optional(),
       }),
     )
     .max(5_000)
diff --git a/packages/repository-engine/src/index.ts b/packages/repository-engine/src/index.ts
index 74ac802..78372bc 100644
--- a/packages/repository-engine/src/index.ts
+++ b/packages/repository-engine/src/index.ts
@@ -8,6 +8,7 @@ export {
   type WorktreeAvailability,
 } from './repository-engine.js';
 export {
+  type InProgressGitOperation,
   type IndexSnapshot,
   type RefSnapshot,
   type UpstreamSnapshot,
diff --git a/packages/repository-engine/src/repository-engine.ts b/packages/repository-engine/src/repository-engine.ts
index d03a638..ff5d60f 100644
--- a/packages/repository-engine/src/repository-engine.ts
+++ b/packages/repository-engine/src/repository-engine.ts
@@ -224,7 +224,7 @@ export function createRepositoryEngine(): RepositoryEngine {
         },
       });
       return createRefreshingRepositorySession(
-        createRepositorySession(publication),
+        createRepositorySession(publication, { runGit }),
       );
     },
   };
diff --git a/packages/repository-engine/src/repository-observation.test.ts b/packages/repository-engine/src/repository-observation.test.ts
index a3ea4fa..812a786 100644
--- a/packages/repository-engine/src/repository-observation.test.ts
+++ b/packages/repository-engine/src/repository-observation.test.ts
@@ -134,6 +134,27 @@ describe('Repository observation Git recipes', () => {
         ],
         false,
       ),
+      recipe(
+        [
+          '-C',
+          path,
+          'rev-parse',
+          '--path-format=absolute',
+          '--git-path',
+          'rebase-merge',
+          '--git-path',
+          'rebase-apply',
+          '--git-path',
+          'MERGE_HEAD',
+          '--git-path',
+          'CHERRY_PICK_HEAD',
+          '--git-path',
+          'REVERT_HEAD',
+          '--git-path',
+          'BISECT_LOG',
+        ],
+        false,
+      ),
       ...sharedRecipes,
     ]);
     expect(observation.shared.remotes[0]).toMatchObject({
diff --git a/packages/repository-engine/src/repository-observation.ts b/packages/repository-engine/src/repository-observation.ts
index 13da6d3..d2b5679 100644
--- a/packages/repository-engine/src/repository-observation.ts
+++ b/packages/repository-engine/src/repository-observation.ts
@@ -44,11 +44,15 @@ export interface IndexSnapshot {
 export interface WorktreeStatusSummary {
   readonly clean: boolean;
   readonly conflicted: number;
+  readonly inProgressOperation?: InProgressGitOperation;
   readonly staged: number;
   readonly unstaged: number;
   readonly untracked: number;
 }
 
+export type InProgressGitOperation =
+  'bisect' | 'cherry-pick' | 'merge' | 'rebase' | 'revert';
+
 export type UpstreamSnapshot =
   | {
       readonly kind: 'tracking';
@@ -282,24 +286,43 @@ async function observeWorktree(
       readKeyPrefix,
       signal,
     );
-    const indexPathOutput = await runRead(
-      reads,
-      readGit,
-      [
-        '-C',
-        worktree.canonicalPath,
-        'rev-parse',
-        '--path-format=absolute',
-        '--git-path',
-        'index',
-      ],
-      false,
-      undefined,
-      readKeyPrefix,
-      signal,
-    );
+    const [indexPathOutput, operationPathsOutput] = await Promise.all([
+      runRead(
+        reads,
+        readGit,
+        [
+          '-C',
+          worktree.canonicalPath,
+          'rev-parse',
+          '--path-format=absolute',
+          '--git-path',
+          'index',
+        ],
+        false,
+        undefined,
+        readKeyPrefix,
+        signal,
+      ),
+      runRead(
+        reads,
+        readGit,
+        [
+          '-C',
+          worktree.canonicalPath,
+          'rev-parse',
+          '--path-format=absolute',
+          ...inProgressMarkers.flatMap(({ path }) => ['--git-path', path]),
+        ],
+        false,
+        undefined,
+        readKeyPrefix,
+        signal,
+      ),
+    ]);
     const observed = summarizeStatus(statusOutput, worktree.head);
     const indexPath = decodeLine(indexPathOutput);
+    const inProgressOperation =
+      await detectInProgressOperation(operationPathsOutput);
     return {
       kind: 'fresh',
       worktreeId: worktree.worktreeId,
@@ -310,7 +333,13 @@ async function observeWorktree(
         fingerprint: fingerprintBytes(indexOutput),
         locked: await pathExists(`${indexPath}.lock`),
       },
-      status: observed.status,
+      status:
+        inProgressOperation === null
+          ? observed.status
+          : {
+              ...observed.status,
+              inProgressOperation,
+            },
       upstream: resolveUpstream(observed.upstream, shared),
     };
   } catch (error) {
@@ -322,6 +351,35 @@ async function observeWorktree(
   }
 }
 
+const inProgressMarkers = [
+  { path: 'rebase-merge', operation: 'rebase' },
+  { path: 'rebase-apply', operation: 'rebase' },
+  { path: 'MERGE_HEAD', operation: 'merge' },
+  { path: 'CHERRY_PICK_HEAD', operation: 'cherry-pick' },
+  { path: 'REVERT_HEAD', operation: 'revert' },
+  { path: 'BISECT_LOG', operation: 'bisect' },
+] as const;
+
+async function detectInProgressOperation(
+  pathsOutput: Uint8Array,
+): Promise<InProgressGitOperation | null> {
+  const paths = decode(pathsOutput)
+    .replace(/\r?\n$/u, '')
+    .split(/\r?\n/u);
+  for (let index = 0; index < inProgressMarkers.length; index += 1) {
+    const marker = inProgressMarkers[index];
+    const path = paths[index];
+    if (
+      marker !== undefined &&
+      path !== undefined &&
+      (await pathExists(path))
+    ) {
+      return marker.operation;
+    }
+  }
+  return null;
+}
+
 async function readCoherentWorktree(
   canonicalPath: NonNullable<DiscoveredWorktree['canonicalPath']>,
   reads: GitReadPolicy,
diff --git a/packages/repository-engine/src/repository-refresh.ts b/packages/repository-engine/src/repository-refresh.ts
index db5e2bf..cad28ee 100644
--- a/packages/repository-engine/src/repository-refresh.ts
+++ b/packages/repository-engine/src/repository-refresh.ts
@@ -176,6 +176,28 @@ export function createRefreshingRepositorySession(
     }
   };
 
+  const dispatch = async (
+    request: Parameters<RepositorySession['dispatch']>[0],
+  ): ReturnType<RepositorySession['dispatch']> => {
+    foregroundRefreshes += 1;
+    try {
+      await Promise.all([backgroundRefresh, requestedRefresh]);
+      const receipt = await delegate.dispatch(request);
+      void delegate
+        .recoverOperation(receipt.operationId)
+        .catch(() => undefined)
+        .finally(() => {
+          foregroundRefreshes -= 1;
+          startPendingBackgroundRefresh();
+        });
+      return receipt;
+    } catch (error) {
+      foregroundRefreshes -= 1;
+      startPendingBackgroundRefresh();
+      throw error;
+    }
+  };
+
   return {
     snapshot: () => foreground(() => delegate.snapshot()),
     requestRefresh() {
@@ -188,6 +210,8 @@ export function createRefreshingRepositorySession(
       return requestedRefresh;
     },
     subscribe: () => delegate.subscribe(),
+    searchBranches: (request) => delegate.searchBranches(request),
+    dispatch,
     cancelOperation: (operationId) => delegate.cancelOperation(operationId),
     recoverOperation: (operationId) => delegate.recoverOperation(operationId),
     async close() {
diff --git a/packages/repository-engine/src/repository-session.ts b/packages/repository-engine/src/repository-session.ts
index 6288a61..6d41b2b 100644
--- a/packages/repository-engine/src/repository-session.ts
+++ b/packages/repository-engine/src/repository-session.ts
@@ -1,4 +1,14 @@
-import type { OperationId, OperationResult } from '@codex-git/protocol';
+import {
+  createOpaqueIdAuthority,
+  type BranchSearchRequest,
+  type BranchSearchResult,
+  type CommandEnvelope,
+  type OperationReceipt,
+  type OperationId,
+  type OperationResult,
+  type RefId,
+  type RemoteId,
+} from '@codex-git/protocol';
 
 import { InvalidationStream } from './invalidation-stream.js';
 import {
@@ -17,6 +27,8 @@ import type {
 const OPERATION_TIMEOUT_MILLISECONDS = 30_000;
 
 export interface RepositorySession extends RepositoryPublicationSession {
+  searchBranches(request: BranchSearchRequest): Promise<BranchSearchResult>;
+  dispatch(request: CommandEnvelope): Promise<OperationReceipt>;
   cancelOperation(operationId: OperationId): Promise<OperationResult>;
   recoverOperation(operationId: OperationId): Promise<OperationResult>;
 }
@@ -24,9 +36,42 @@ export interface RepositorySession extends RepositoryPublicationSession {
 export interface InternalRepositorySession
   extends RepositorySession, ScopedRepositoryPublicationSession {}
 
+type GitProcessRunner = (
+  args: readonly string[],
+  allowLargeOutput: boolean,
+  acceptedEmptyExitCode?: 1,
+  signal?: AbortSignal,
+) => Promise<Uint8Array>;
+
+interface RepositorySessionOptions {
+  readonly runGit?: GitProcessRunner;
+}
+
+interface BranchBinding {
+  readonly fullName: string;
+  readonly kind: 'local' | 'remote_tracking';
+  readonly objectId: string;
+  readonly occupiedBy: BranchSearchResult['candidates'][number]['occupiedBy'];
+  readonly remoteId: RemoteId | null;
+  readonly refsRevision: number;
+}
+
+type BranchSwitchEvidence =
+  | {
+      readonly kind: 'rejected';
+      readonly result: Omit<
+        Extract<OperationResult, { readonly kind: 'rejected' }>,
+        'operationId'
+      >;
+    }
+  | { readonly kind: 'attempted'; readonly displayName: string };
+
 export function createRepositorySession(
   delegate: ScopedRepositoryPublicationSession,
+  options: RepositorySessionOptions = {},
 ): InternalRepositorySession {
+  const branchIds = createOpaqueIdAuthority();
+  const branchBindings = new Map<RefId, BranchBinding>();
   const invalidations = new InvalidationStream<RepositoryInvalidation>();
   const operationSummaries = new Map<OperationId, OperationSessionSummary>();
   let closed = false;
@@ -96,6 +141,316 @@ export function createRepositorySession(
     requestScopedRefresh: (scope: RepositoryRefreshScope) =>
       observe(() => delegate.requestScopedRefresh(scope)),
     subscribe: () => invalidations.subscribe(),
+    async searchBranches(request) {
+      const observed = await observe(() => delegate.requestRefresh());
+      if (observed.kind !== 'repository') {
+        throw new Error('Branch search requires an open Repository.');
+      }
+      const repository = observed.repository;
+      if (
+        !repository.worktrees.some(
+          ({ worktreeId }) => worktreeId === request.worktreeId,
+        )
+      ) {
+        throw new Error('Branch search named a stale Worktree.');
+      }
+      const occupancy = new Map(
+        repository.worktrees.flatMap((worktree) =>
+          worktree.head.kind === 'local_branch'
+            ? [[worktree.head.fullName, worktree.worktreeId] as const]
+            : [],
+        ),
+      );
+      const query = request.query.trim().toLocaleLowerCase();
+      const selectedWorktree = repository.worktrees.find(
+        ({ worktreeId }) => worktreeId === request.worktreeId,
+      );
+      const warning = await detachedHeadWarning(
+        selectedWorktree,
+        options.runGit,
+      );
+      branchBindings.clear();
+      return {
+        refsRevision: repository.refsRevision,
+        candidates: repository.refs
+          .map((ref) => {
+            const refId = branchIds.issue('ref');
+            const remote =
+              ref.kind === 'remote_tracking'
+                ? repository.remotes
+                    .toSorted(
+                      (left, right) =>
+                        right.displayName.length - left.displayName.length,
+                    )
+                    .find(({ displayName }) =>
+                      ref.fullName.startsWith(`refs/remotes/${displayName}/`),
+                    )
+                : undefined;
+            const occupiedBy =
+              ref.kind === 'local'
+                ? (occupancy.get(ref.fullName) ?? null)
+                : null;
+            branchBindings.set(refId, {
+              ...ref,
+              occupiedBy,
+              remoteId: remote?.remoteId ?? null,
+              refsRevision: repository.refsRevision,
+            });
+            return {
+              refId,
+              kind: ref.kind,
+              displayName:
+                ref.kind === 'local'
+                  ? ref.fullName.slice('refs/heads/'.length)
+                  : ref.fullName.slice('refs/remotes/'.length),
+              occupiedBy,
+              warning,
+            };
+          })
+          .filter(
+            ({ refId, kind }) =>
+              kind === 'local' || branchBindings.get(refId)?.remoteId !== null,
+          )
+          .filter(
+            ({ displayName }) =>
+              query.length === 0 ||
+              displayName.toLocaleLowerCase().includes(query),
+          )
+          .slice(0, 5_000),
+      };
+    },
+    async dispatch(request) {
+      if (request.command.kind !== 'switch_branch') {
+        throw new Error(
+          'This Repository Session does not support that command.',
+        );
+      }
+      const command = request.command;
+      const binding = branchBindings.get(command.refId);
+      const target = binding ?? {
+        fullName: 'refs/heads/stale',
+        kind: 'local' as const,
+        objectId: '',
+        occupiedBy: null,
+        remoteId: null,
+        refsRevision: command.expectedRefsRevision,
+      };
+      const initial = latestBase?.worktrees.find(
+        ({ worktreeId }) => worktreeId === command.worktreeId,
+      );
+      if (initial === undefined) {
+        throw new Error(
+          'Branch switching requires a current Worktree snapshot.',
+        );
+      }
+      const admission = await operations.dispatch({
+        kind: 'branch_switch',
+        worktreeGeneration: initial.generation,
+        currentRef:
+          initial?.head.kind === 'local_branch' ? initial.head.fullName : null,
+        target:
+          target.kind === 'remote_tracking' && target.remoteId !== null
+            ? {
+                kind: 'remote_tracking',
+                fullName: target.fullName,
+                remoteId: target.remoteId,
+              }
+            : { kind: 'local', fullName: target.fullName },
+        async reconcileBusy() {
+          await observe(() => delegate.requestRefresh()).catch(() => undefined);
+        },
+        async execute({ signal }) {
+          const current = await observe(() => delegate.requestRefresh()).catch(
+            () => undefined,
+          );
+          if (current === undefined) {
+            return reject(
+              'stale',
+              'Branch state could not be revalidated; refresh and choose again.',
+            );
+          }
+          if (current.kind !== 'repository') {
+            return reject('stale', 'The Repository is no longer available.');
+          }
+          const repository = current.repository;
+          const worktree = repository.worktrees.find(
+            ({ worktreeId }) => worktreeId === command.worktreeId,
+          );
+          if (
+            binding === undefined ||
+            binding.refsRevision !== command.expectedRefsRevision ||
+            repository.refsRevision !== command.expectedRefsRevision ||
+            worktree === undefined ||
+            worktree.worktreeRevision !== command.expectedWorktreeRevision
+          ) {
+            return reject(
+              'stale',
+              'Branch or Worktree state changed; refresh and choose again.',
+            );
+          }
+          const currentRef = repository.refs.find(
+            ({ fullName }) => fullName === binding.fullName,
+          );
+          const occupiedBy = repository.worktrees.find(
+            ({ head }) =>
+              head.kind === 'local_branch' &&
+              head.fullName === binding.fullName,
+          )?.worktreeId;
+          if (
+            currentRef?.objectId !== binding.objectId ||
+            (binding.kind === 'local' &&
+              (occupiedBy ?? null) !== binding.occupiedBy)
+          ) {
+            return reject(
+              'stale',
+              'Branch Occupancy or target ref changed; refresh and choose again.',
+            );
+          }
+          const localTargetName =
+            binding.kind === 'local'
+              ? localDisplayName(binding.fullName)
+              : remoteTrackingLocalName(binding.fullName, repository, binding);
+          if (localTargetName === null) {
+            return reject(
+              'precondition_failed',
+              'The Remote-tracking Branch no longer maps to a configured Remote.',
+            );
+          }
+          if (
+            binding.kind === 'remote_tracking' &&
+            repository.refs.some(
+              ({ kind, fullName }) =>
+                kind === 'local' &&
+                fullName === `refs/heads/${localTargetName}`,
+            )
+          ) {
+            return reject(
+              'precondition_failed',
+              'A same-name Local Branch already exists.',
+            );
+          }
+          if (
+            worktree.availability.kind !== 'available' ||
+            worktree.canonicalPath === null ||
+            worktree.freshness.kind !== 'fresh' ||
+            worktree.status?.clean !== true ||
+            worktree.status.conflicted !== 0 ||
+            worktree.status.inProgressOperation !== undefined ||
+            worktree.index?.locked !== false ||
+            worktree.gitLock.kind !== 'unlocked'
+          ) {
+            return reject(
+              'precondition_failed',
+              'Branch switching requires a clean, available Worktree with no Git lock.',
+            );
+          }
+          if (
+            binding.kind === 'local' &&
+            binding.occupiedBy !== null &&
+            binding.occupiedBy !== worktree.worktreeId
+          ) {
+            return reject(
+              'precondition_failed',
+              'The Local Branch is occupied by another Worktree.',
+            );
+          }
+          if (options.runGit === undefined) {
+            return reject(
+              'unsupported_state',
+              'Branch switching is unavailable in this Repository Session.',
+            );
+          }
+          await options.runGit(
+            binding.kind === 'local'
+              ? [
+                  '-C',
+                  worktree.canonicalPath,
+                  'switch',
+                  '--no-guess',
+                  '--',
+                  localTargetName,
+                ]
+              : [
+                  '-C',
+                  worktree.canonicalPath,
+                  'switch',
+                  '--no-guess',
+                  '--track=direct',
+                  '-c',
+                  localTargetName,
+                  binding.fullName,
+                ],
+            false,
+            undefined,
+            signal,
+          );
+          return { kind: 'attempted' as const, displayName: localTargetName };
+        },
+        async reconcile(context) {
+          const evidence =
+            context.execution.kind === 'returned'
+              ? (context.execution.evidence as BranchSwitchEvidence)
+              : undefined;
+          if (evidence?.kind === 'rejected') {
+            await observe(() => delegate.requestRefresh()).catch(
+              () => undefined,
+            );
+            return evidence.result;
+          }
+          const reconciled = await observe(() =>
+            delegate.requestRefresh(),
+          ).catch(() => undefined);
+          if (reconciled === undefined) {
+            return {
+              kind: 'unknown_outcome',
+              code: 'reconciliation_incomplete',
+              message:
+                'The Branch switch could not be reconciled to authoritative state.',
+              recoveryAvailable: true,
+            };
+          }
+          const worktree =
+            reconciled.kind === 'repository'
+              ? reconciled.repository.worktrees.find(
+                  ({ worktreeId }) => worktreeId === command.worktreeId,
+                )
+              : undefined;
+          if (
+            evidence?.kind === 'attempted' &&
+            worktree?.head.kind === 'local_branch' &&
+            worktree.head.fullName ===
+              (binding?.kind === 'local'
+                ? binding.fullName
+                : `refs/heads/${evidence.displayName}`)
+          ) {
+            return {
+              kind: 'succeeded',
+              result: {
+                kind: 'branch_switch',
+                displayName: evidence.displayName,
+              },
+            };
+          }
+          return {
+            kind: 'failed_known',
+            code: 'process_failed',
+            message: 'Git did not complete the Branch switch.',
+          };
+        },
+      });
+      if (admission.kind === 'closed') {
+        throw new Error('The Repository Session is closed.');
+      }
+      const operationId =
+        admission.kind === 'accepted'
+          ? admission.operation.operationId
+          : admission.result.operationId;
+      return {
+        operationId,
+        clientCommandId: request.clientCommandId,
+        disposition: 'accepted',
+      };
+    },
     async cancelOperation(operationId) {
       const result = await operations.cancel(operationId);
       await observe(() => delegate.requestRefresh());
@@ -111,11 +466,70 @@ export function createRepositorySession(
       closed = true;
       await operations.close();
       await delegate.close();
+      branchIds.revokeAll();
       invalidations.close();
     },
   };
 }
 
+function localDisplayName(fullName: string): string {
+  return fullName.slice('refs/heads/'.length);
+}
+
+function remoteTrackingLocalName(
+  fullName: string,
+  repository: RepositorySnapshot,
+  binding: BranchBinding,
+): string | null {
+  const remote = repository.remotes.find(
+    ({ remoteId }) => remoteId === binding.remoteId,
+  );
+  if (remote === undefined) return null;
+  const prefix = `refs/remotes/${remote.displayName}/`;
+  return fullName.startsWith(prefix) ? fullName.slice(prefix.length) : null;
+}
+
+async function detachedHeadWarning(
+  worktree: RepositorySnapshot['worktrees'][number] | undefined,
+  runGit: GitProcessRunner | undefined,
+): Promise<string | null> {
+  if (
+    worktree?.head.kind !== 'detached' ||
+    worktree.canonicalPath === null ||
+    runGit === undefined
+  ) {
+    return null;
+  }
+  const output = await runGit(
+    [
+      '-C',
+      worktree.canonicalPath,
+      'for-each-ref',
+      '--format=%(refname)',
+      '--contains',
+      worktree.head.objectId,
+      'refs/heads',
+      'refs/remotes',
+      'refs/tags',
+    ],
+    true,
+  );
+  return new TextDecoder('utf-8', { fatal: true }).decode(output).trim()
+    .length > 0
+    ? null
+    : 'This detached Commit is not reachable from another named ref and may become difficult to recover after switching.';
+}
+
+function reject(
+  code: Extract<OperationResult, { kind: 'rejected' }>['code'],
+  message: string,
+) {
+  return {
+    kind: 'rejected' as const,
+    result: { kind: 'rejected' as const, code, message },
+  };
+}
+
 function deepFreeze<T>(value: T): T {
   if (value === null || typeof value !== 'object') return value;
   for (const child of Object.values(value)) deepFreeze(child);
diff --git a/tests/e2e/protocol-runtime.e2e.test.ts b/tests/e2e/protocol-runtime.e2e.test.ts
index 2a6a5a7..a6d76a9 100644
--- a/tests/e2e/protocol-runtime.e2e.test.ts
+++ b/tests/e2e/protocol-runtime.e2e.test.ts
@@ -10,6 +10,9 @@ import {
 } from '@codex-git/launcher';
 import {
   PROTOCOL_VERSION_HEADER,
+  branchSearchResultSchema,
+  operationReceiptSchema,
+  operationResultSchema,
   repositorySnapshotSchema,
 } from '@codex-git/protocol';
 
@@ -187,8 +190,88 @@ describe('protocol runtime composition', () => {
       status: 200,
     });
   });
+
+  it('searches and switches Branches through typed protocol endpoints', async () => {
+    const repository = await createRepositoryWithCommit();
+    await repository.git('branch', 'review-ready');
+    const runtime = await startStandaloneRuntime({
+      projectPath: repository.path,
+      surfacePort: 0,
+    });
+    runtimes.push(runtime);
+    const snapshot = repositorySnapshotSchema.parse(
+      await protocolRequest(runtime, 'snapshot'),
+    );
+    const worktree = snapshot.worktrees[0]!;
+    const branches = branchSearchResultSchema.parse(
+      await protocolRequest(runtime, 'branches', {
+        worktreeId: worktree.worktreeId,
+        query: 'review-ready',
+      }),
+    );
+    const target = branches.candidates[0]!;
+
+    const receipt = operationReceiptSchema.parse(
+      await protocolRequest(runtime, 'commands', {
+        clientCommandId: 'command_0123456789abcdef0123456789abcdef',
+        command: {
+          kind: 'switch_branch',
+          worktreeId: worktree.worktreeId,
+          expectedWorktreeRevision: worktree.worktreeRevision,
+          refId: target.refId,
+          expectedRefsRevision: branches.refsRevision,
+        },
+      }),
+    );
+    let result = operationResultSchema.parse(
+      await protocolRequest(runtime, 'operations', {
+        operationId: receipt.operationId,
+      }),
+    );
+    for (
+      let attempt = 0;
+      result.kind === 'unknown_outcome' && attempt < 5;
+      attempt += 1
+    ) {
+      result = operationResultSchema.parse(
+        await protocolRequest(runtime, 'operations', {
+          operationId: receipt.operationId,
+        }),
+      );
+    }
+
+    expect(result).toMatchObject({
+      kind: 'succeeded',
+      result: { kind: 'branch_switch', displayName: 'review-ready' },
+    });
+    expect(
+      (await repository.git('branch', '--show-current')).stdout.trim(),
+    ).toBe('review-ready');
+  });
 });
 
+async function protocolRequest(
+  runtime: StandaloneRuntime,
+  endpoint: 'branches' | 'commands' | 'operations' | 'snapshot',
+  body?: unknown,
+): Promise<unknown> {
+  const url = new URL(
+    runtime.sessionUrl.pathname.replace(/\/session$/u, `/${endpoint}`),
+    runtime.sessionUrl,
+  );
+  const response = await fetch(url, {
+    body: body === undefined ? undefined : JSON.stringify(body),
+    headers: {
+      origin: runtime.surfaceUrl.origin,
+      [PROTOCOL_VERSION_HEADER]: '1',
+      ...(body === undefined ? {} : { 'content-type': 'application/json' }),
+    },
+    method: body === undefined ? 'GET' : 'POST',
+  });
+  expect(response.status).toBe(200);
+  return response.json();
+}
+
 function protocolBootstrap(surface: string): unknown {
   const match = surface.match(
     /globalThis\.__CODEX_GIT_PROTOCOL__ = (\{.*?\});/u,
diff --git a/tests/integration/branch-switching.integration.test.ts b/tests/integration/branch-switching.integration.test.ts
new file mode 100644
index 0000000..f79fc64
--- /dev/null
+++ b/tests/integration/branch-switching.integration.test.ts
@@ -0,0 +1,393 @@
+import { rm, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+
+import type { AbsolutePath, ClientCommandId } from '@codex-git/protocol';
+import { createRepositoryEngine } from '@codex-git/repository-engine';
+import { afterEach, describe, expect, it } from 'vitest';
+
+import {
+  createTemporaryGitRepository,
+  type TemporaryGitRepository,
+} from '../fixtures/temporary-git-repository.js';
+
+const repositories: TemporaryGitRepository[] = [];
+const externalPaths: string[] = [];
+
+afterEach(async () => {
+  await Promise.all(
+    repositories.splice(0).map((repository) => repository.dispose()),
+  );
+  await Promise.all(
+    externalPaths.splice(0).map((path) =>
+      rm(path, {
+        force: true,
+        recursive: true,
+      }),
+    ),
+  );
+});
+
+describe('Repository Branch switching', () => {
+  it('discovers cached Local Branches with Repository-wide occupancy', async () => {
+    const repository = await createRepositoryWithCommit();
+    await repository.git('branch', 'available');
+    await repository.git('branch', 'occupied');
+    const linkedPath = `${repository.path}-occupied`;
+    externalPaths.push(linkedPath);
+    await repository.git('worktree', 'add', '--quiet', linkedPath, 'occupied');
+    const session = await createRepositoryEngine().open(
+      repository.path as AbsolutePath,
+    );
+    const opened = await session.requestRefresh();
+    if (opened.kind !== 'repository') throw new Error('Expected Repository');
+    const selectedWorktreeId = opened.repository.selectedWorktreeId;
+    if (selectedWorktreeId === null) throw new Error('Expected Worktree');
+    const occupiedWorktree = opened.repository.worktrees.find(
+      ({ role }) => role === 'linked',
+    );
+
+    const result = await session.searchBranches({
+      worktreeId: selectedWorktreeId,
+      query: '',
+    });
+
+    expect(result.refsRevision).toBe(opened.repository.refsRevision);
+    expect(result.candidates).toEqual(
+      expect.arrayContaining([
+        expect.objectContaining({
+          kind: 'local',
+          displayName: 'available',
+          occupiedBy: null,
+        }),
+        expect.objectContaining({
+          kind: 'local',
+          displayName: 'occupied',
+          occupiedBy: occupiedWorktree?.worktreeId,
+        }),
+      ]),
+    );
+    expect(
+      result.candidates.every(({ refId }) => refId.startsWith('ref_')),
+    ).toBe(true);
+    await session.close();
+  });
+
+  it('switches a clean Worktree to an unoccupied Local Branch', async () => {
+    const repository = await createRepositoryWithCommit();
+    await repository.git('branch', 'available');
+    const session = await createRepositoryEngine().open(
+      repository.path as AbsolutePath,
+    );
+    const opened = await session.requestRefresh();
+    if (opened.kind !== 'repository') throw new Error('Expected Repository');
+    const worktree = opened.repository.worktrees[0];
+    if (worktree === undefined) throw new Error('Expected Worktree');
+    const branches = await session.searchBranches({
+      worktreeId: worktree.worktreeId,
+      query: 'available',
+    });
+    const target = branches.candidates.find(
+      ({ displayName }) => displayName === 'available',
+    );
+    if (target === undefined) throw new Error('Expected target Branch');
+    const receipt = await session.dispatch({
+      clientCommandId:
+        'command_0123456789abcdef0123456789abcdef' as ClientCommandId,
+      command: {
+        kind: 'switch_branch',
+        worktreeId: worktree.worktreeId,
+        expectedWorktreeRevision: worktree.worktreeRevision,
+        refId: target.refId,
+        expectedRefsRevision: branches.refsRevision,
+      },
+    });
+    const result = await session.recoverOperation(receipt.operationId);
+
+    expect(result).toMatchObject({
+      kind: 'succeeded',
+      result: { kind: 'branch_switch', displayName: 'available' },
+    });
+    const refreshed = await session.requestRefresh();
+    expect(refreshed).toMatchObject({
+      kind: 'repository',
+      repository: {
+        worktrees: [
+          expect.objectContaining({
+            head: expect.objectContaining({
+              kind: 'local_branch',
+              displayName: 'available',
+            }),
+            status: expect.objectContaining({ clean: true }),
+          }),
+        ],
+      },
+    });
+    await session.close();
+  });
+
+  it('blocks a dirty Worktree without carrying or discarding changes', async () => {
+    const repository = await createRepositoryWithCommit();
+    await repository.git('branch', 'available');
+    await writeFile(join(repository.path, 'dirty.txt'), 'keep me\n');
+    const session = await createRepositoryEngine().open(
+      repository.path as AbsolutePath,
+    );
+    const opened = await session.requestRefresh();
+    if (opened.kind !== 'repository') throw new Error('Expected Repository');
+    const worktree = opened.repository.worktrees[0]!;
+    const branches = await session.searchBranches({
+      worktreeId: worktree.worktreeId,
+      query: 'available',
+    });
+    const target = branches.candidates[0]!;
+
+    const receipt = await session.dispatch({
+      clientCommandId:
+        'command_1123456789abcdef0123456789abcdef' as ClientCommandId,
+      command: {
+        kind: 'switch_branch',
+        worktreeId: worktree.worktreeId,
+        expectedWorktreeRevision: worktree.worktreeRevision,
+        refId: target.refId,
+        expectedRefsRevision: branches.refsRevision,
+      },
+    });
+    const result = await session.recoverOperation(receipt.operationId);
+
+    expect(result).toMatchObject({
+      kind: 'rejected',
+      code: 'precondition_failed',
+    });
+    expect((await repository.git('status', '--short')).stdout).toContain(
+      'dirty.txt',
+    );
+    expect(
+      (await repository.git('branch', '--show-current')).stdout.trim(),
+    ).not.toBe('available');
+    await session.close();
+  });
+
+  it('creates only the same-name Local tracking Branch for a cached Remote-tracking target', async () => {
+    const repository = await createRepositoryWithCommit();
+    await repository.git('remote', 'add', 'origin', repository.path);
+    await repository.git(
+      'update-ref',
+      'refs/remotes/origin/team/remote-only',
+      'HEAD',
+    );
+    const session = await createRepositoryEngine().open(
+      repository.path as AbsolutePath,
+    );
+    const opened = await session.requestRefresh();
+    if (opened.kind !== 'repository') throw new Error('Expected Repository');
+    const worktree = opened.repository.worktrees[0]!;
+    const branches = await session.searchBranches({
+      worktreeId: worktree.worktreeId,
+      query: 'remote-only',
+    });
+    const target = branches.candidates.find(
+      ({ kind }) => kind === 'remote_tracking',
+    );
+    if (target === undefined)
+      throw new Error('Expected Remote-tracking Branch');
+
+    const receipt = await session.dispatch({
+      clientCommandId:
+        'command_2123456789abcdef0123456789abcdef' as ClientCommandId,
+      command: {
+        kind: 'switch_branch',
+        worktreeId: worktree.worktreeId,
+        expectedWorktreeRevision: worktree.worktreeRevision,
+        refId: target.refId,
+        expectedRefsRevision: branches.refsRevision,
+      },
+    });
+    const result = await session.recoverOperation(receipt.operationId);
+
+    expect(result).toMatchObject({
+      kind: 'succeeded',
+      result: { kind: 'branch_switch', displayName: 'team/remote-only' },
+    });
+    expect(
+      (await repository.git('branch', '--show-current')).stdout.trim(),
+    ).toBe('team/remote-only');
+    expect(
+      (
+        await repository.git(
+          'for-each-ref',
+          '--format=%(upstream)',
+          'refs/heads/team/remote-only',
+        )
+      ).stdout.trim(),
+    ).toBe('refs/remotes/origin/team/remote-only');
+    await session.close();
+  });
+
+  it('warns before leaving a detached Commit unreachable from another named ref', async () => {
+    const repository = await createRepositoryWithCommit();
+    await repository.git('switch', '--quiet', '-c', 'temporary');
+    await writeFile(join(repository.path, 'detached.txt'), 'detached\n');
+    await repository.git('add', 'detached.txt');
+    await repository.git('commit', '--quiet', '-m', 'Detached fixture');
+    const detachedCommit = (
+      await repository.git('rev-parse', 'HEAD')
+    ).stdout.trim();
+    await repository.git('switch', '--quiet', '-');
+    await repository.git('branch', '-D', 'temporary');
+    await repository.git('switch', '--quiet', '--detach', detachedCommit);
+    const session = await createRepositoryEngine().open(
+      repository.path as AbsolutePath,
+    );
+    const opened = await session.requestRefresh();
+    if (opened.kind !== 'repository') throw new Error('Expected Repository');
+    const worktree = opened.repository.worktrees[0]!;
+
+    const result = await session.searchBranches({
+      worktreeId: worktree.worktreeId,
+      query: '',
+    });
+
+    expect(result.candidates[0]?.warning).toContain(
+      'not reachable from another named ref',
+    );
+    await session.close();
+  });
+
+  it('rejects stale Branch Occupancy after an external Worktree claims the target', async () => {
+    const repository = await createRepositoryWithCommit();
+    await repository.git('branch', 'available');
+    const session = await createRepositoryEngine().open(
+      repository.path as AbsolutePath,
+    );
+    const opened = await session.requestRefresh();
+    if (opened.kind !== 'repository') throw new Error('Expected Repository');
+    const worktree = opened.repository.worktrees[0]!;
+    const branches = await session.searchBranches({
+      worktreeId: worktree.worktreeId,
+      query: 'available',
+    });
+    const target = branches.candidates[0]!;
+    const linkedPath = `${repository.path}-late-occupancy`;
+    externalPaths.push(linkedPath);
+    await repository.git('worktree', 'add', '--quiet', linkedPath, 'available');
+
+    const receipt = await session.dispatch({
+      clientCommandId:
+        'command_3123456789abcdef0123456789abcdef' as ClientCommandId,
+      command: {
+        kind: 'switch_branch',
+        worktreeId: worktree.worktreeId,
+        expectedWorktreeRevision: worktree.worktreeRevision,
+        refId: target.refId,
+        expectedRefsRevision: branches.refsRevision,
+      },
+    });
+    const result = await session.recoverOperation(receipt.operationId);
+
+    expect(result).toMatchObject({ kind: 'rejected', code: 'stale' });
+    const refreshed = await session.searchBranches({
+      worktreeId: worktree.worktreeId,
+      query: 'available',
+    });
+    expect(refreshed.candidates[0]?.occupiedBy).not.toBeNull();
+    await session.close();
+  });
+
+  it('blocks a clean Worktree with an In-progress Git Operation', async () => {
+    const repository = await createRepositoryWithCommit();
+    await writeFile(join(repository.path, 'second.txt'), 'second\n');
+    await repository.git('add', 'second.txt');
+    await repository.git('commit', '--quiet', '-m', 'Second fixture');
+    await repository.git('branch', 'available');
+    await repository.git('bisect', 'start', 'HEAD', 'HEAD~1');
+    const session = await createRepositoryEngine().open(
+      repository.path as AbsolutePath,
+    );
+    const opened = await session.requestRefresh();
+    if (opened.kind !== 'repository') throw new Error('Expected Repository');
+    const worktree = opened.repository.worktrees[0]!;
+    expect(worktree.status).toMatchObject({
+      clean: true,
+      inProgressOperation: 'bisect',
+    });
+    const branches = await session.searchBranches({
+      worktreeId: worktree.worktreeId,
+      query: 'available',
+    });
+
+    const receipt = await session.dispatch({
+      clientCommandId:
+        'command_4123456789abcdef0123456789abcdef' as ClientCommandId,
+      command: {
+        kind: 'switch_branch',
+        worktreeId: worktree.worktreeId,
+        expectedWorktreeRevision: worktree.worktreeRevision,
+        refId: branches.candidates[0]!.refId,
+        expectedRefsRevision: branches.refsRevision,
+      },
+    });
+    const result = await session.recoverOperation(receipt.operationId);
+
+    expect(result).toMatchObject({
+      kind: 'rejected',
+      code: 'precondition_failed',
+    });
+    await repository.git('bisect', 'reset');
+    await session.close();
+  });
+
+  it('blocks a clean Worktree while its Index is locked', async () => {
+    const repository = await createRepositoryWithCommit();
+    await repository.git('branch', 'available');
+    const indexPath = (
+      await repository.git(
+        'rev-parse',
+        '--path-format=absolute',
+        '--git-path',
+        'index',
+      )
+    ).stdout.trim();
+    await writeFile(`${indexPath}.lock`, 'locked\n');
+    const session = await createRepositoryEngine().open(
+      repository.path as AbsolutePath,
+    );
+    const opened = await session.requestRefresh();
+    if (opened.kind !== 'repository') throw new Error('Expected Repository');
+    const worktree = opened.repository.worktrees[0]!;
+    const branches = await session.searchBranches({
+      worktreeId: worktree.worktreeId,
+      query: 'available',
+    });
+
+    const receipt = await session.dispatch({
+      clientCommandId:
+        'command_5123456789abcdef0123456789abcdef' as ClientCommandId,
+      command: {
+        kind: 'switch_branch',
+        worktreeId: worktree.worktreeId,
+        expectedWorktreeRevision: worktree.worktreeRevision,
+        refId: branches.candidates[0]!.refId,
+        expectedRefsRevision: branches.refsRevision,
+      },
+    });
+    const result = await session.recoverOperation(receipt.operationId);
+
+    expect(result).toMatchObject({
+      kind: 'rejected',
+      code: 'precondition_failed',
+    });
+    await rm(`${indexPath}.lock`, { force: true });
+    await session.close();
+  });
+});
+
+async function createRepositoryWithCommit() {
+  const repository = await createTemporaryGitRepository();
+  repositories.push(repository);
+  await repository.git('config', 'user.email', 'codex-git@example.invalid');
+  await repository.git('config', 'user.name', 'Codex Git');
+  await writeFile(join(repository.path, 'README.md'), 'fixture\n');
+  await repository.git('add', 'README.md');
+  await repository.git('commit', '--quiet', '-m', 'Initial fixture');
+  return repository;
+}