Local repos: display the checked-out branch, drop the branch axis (#110)

* feat(source): drop the branch axis for local repos

A local source scans whatever is checked out on disk, so a stored branch
is a lie: it must not namespace the cache, the URL, or recents. Add
identityBranch(src, branch) as the single "does this source carry a
branch" rule (undefined for local, branch for remote) and route sourceKey,
CURRENT_SOURCE, the deep-link URL, the fetch/overlay, and recents dedupe
through it.

- Recents now key + dedupe a local path by src alone, so switching its
  checkout no longer spawns a second row, and the row shows no @Branch
  identity pill.
- The header branch pill still shows the live checked-out branch: it falls
  back to manifest.repo.branch via resolveBranch/SOURCE_INFO (display only).

Backend already populates repo.branch from HEAD for every scan, so no
change there.

Closes #92

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* refactor(source): normalize local branch at the commit boundary only

Follow-up to the local-branch-axis work: the "local has no branch" rule
was being re-decided on every read (sourceKey, recents dedupe, the active
match all called identityBranch(...) ?? ''). Collapse it to one boundary.

- Add sourceIdentity(src, branch): the canonical identity string, one place
  the src\0branch join + empty-branch coercion lives. sourceKey hashes it;
  recents dedupe and the active match compare it.
- identityBranch now applies only at the commit boundary (loadSource +
  setCurrentSource), so CURRENT_SOURCE and every stored recent are already
  branch-less for local. sourceIdentity trusts that and does a plain join —
  no per-read source-kind switch.
- Bump the recents localStorage slot to recents.v2. Pre-v2 local entries
  stored a checkout branch; dropping the slot once is cheaper than migrating
  an MRU list, and it removes the only stale-data case the read guard existed
  for.
- RecentsList matches active rows against CURRENT_SOURCE (the canonical
  applied source) instead of SOURCE_INFO (which exposes the manifest's live
  checkout for display). Post-v2 a recent's branch equals CURRENT_SOURCE's on
  both kinds, so the match is exact; a local row no longer needs the display
  branch normalized away. Drop the now-redundant !isLocal pill guard.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* refactor(source): share sameSourceIdentity for the active-row match

The recents-dedupe predicate was private and RecentsList re-spelled the
same identity comparison inline. Export it as sameSourceIdentity (it takes
any two {src, branch?} refs, not just recents) and use it in the active-row
match, so pushRecent, removeRecent, and isActive all go through one "are
these the same source?" check. sourceIdentity (the string) still backs the
React key.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* refactor(source): move pure source-identity helpers to utils/sources

sourceKey (+ djb2), sourceIdentity, and sameSourceIdentity are pure
functions on a source's (src, branch) identity with no signal dependency,
so they belong beside their siblings identityBranch/resolveBranch in
utils/sources, not in the stateful store. state/stores/source keeps the
signals, the recents mutations, and the URL effect built on them.

RecentsList now imports the two identity helpers from utils instead of
reaching into the store for pure logic; excludes + useManifestSource import
sourceKey from utils. Unit tests for the moved functions live in
tests/utils/sources.test.ts (mirroring the new home), with focused
sourceIdentity/sameSourceIdentity coverage added.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Fable 5 <noreply@anthropic.com>

Author: thalida

app/src/components/RecentsList/RecentsList.tsx

@@ -1,16 +1,16 @@
 // components/RecentsList/RecentsList.tsx — recent projects: a heading and the
-// list. Active state derives from SOURCE_INFO (the resolved branch, matching
-// how recents store it — CURRENT_SOURCE keeps the raw submitted branch, which is
-// undefined for a local repo whose recent carries its resolved HEAD).
-// Remove is non-destructive: it forgets the entry only, it does not
-// clear the scan cache (that's the skip-cache control's job). Renders nothing
-// when there are no recents.
+// list. Active state matches each row against CURRENT_SOURCE by source identity
+// (the canonical applied source, not the manifest's display fields): a local
+// path is branch-less on both sides, so a checkout change never re-keys the row
+// or drops its active badge. Remove is non-destructive: it forgets the entry
+// only, it does not clear the scan cache (that's the skip-cache control's job).
+// Renders nothing when there are no recents.
 
 import './RecentsList.css';
 import { useState } from 'preact/hooks';
-import { listRecents, removeRecent, SOURCE_INFO } from '@/state/stores/source';
+import { listRecents, removeRecent, CURRENT_SOURCE } from '@/state/stores/source';
 import { SERVER_CONFIG } from '@/state/stores/serverConfig';
-import { srcKind, SourceKind } from '@/utils/sources';
+import { srcKind, SourceKind, sourceIdentity, sameSourceIdentity } from '@/utils/sources';
 import type { SourcePayload } from '@/state/stores/ui';
 import { RecentRow } from './RecentRow';
 
@@ -20,13 +20,12 @@ export interface RecentsListProps {
 
 export function RecentsList({ onOpen }: RecentsListProps) {
   const recents = listRecents(); // reads RECENTS signal
-  const si = SOURCE_INFO.value;
+  const cur = CURRENT_SOURCE.value;
   const allowLocal = SERVER_CONFIG.value.allowLocalRepos;
   const [confirming, setConfirming] = useState<string | null>(null); // key of row
 
-  const keyOf = (r: { src: string; branch?: string }) => `${r.src}:${r.branch ?? ''}`;
-  const isActive = (r: { src: string; branch?: string }) =>
-    !!si.src && r.src === si.src && (r.branch ?? '') === (si.branch ?? '');
+  const keyOf = (r: { src: string; branch?: string }) => sourceIdentity(r.src, r.branch);
+  const isActive = (r: { src: string; branch?: string }) => !!cur && sameSourceIdentity(r, cur);
   // A local recent while local repos are off can't load; still clickable (the
   // server error explains why), just flagged with a hint glyph.
   const isUnavailable = (r: { src: string }) => srcKind(r.src) === SourceKind.Local && !allowLocal;

app/src/constants/storage.ts

@@ -13,8 +13,11 @@ export const STORAGE_PREFIX = 'cc.';
  *  e.g. `cc.recents`. All persisted UI/session state flows through here; there
  *  is no separate raw-localStorage key table. */
 export const PERSISTED_KEYS = {
-  /** Recently-opened sources list (source-picker MRU). */
-  RECENTS: 'recents',
+  /** Recently-opened sources list (source-picker MRU). The `.v2` bump resets the
+   *  slot once: pre-v2 local entries stored a `branch` (their checkout), which a
+   *  local source no longer carries — dropping the stale slot is cheaper than
+   *  migrating an MRU convenience list. */
+  RECENTS: 'recents.v2',
   /** Left (tree/info/controls) sidebar drag-handle width in px. */
   LEFT_SIDEBAR_WIDTH: 'leftSidebarWidth',
   /** Right (file/commit/street pane) sidebar drag-handle width in px. */

app/src/hooks/useManifestSource.ts

@@ -39,8 +39,7 @@ import { SERVER_CONFIG } from '@/state/stores/serverConfig';
 import { MANIFEST, setManifest, markError } from '@/state/stores/manifest';
 import { SCAN_PROGRESS } from '@/state/stores/scanProgress';
 import { activeExcludePathsFor, ACTIVE_EXCLUDES } from '@/state/stores/excludes';
-import { sourceKey } from '@/state/stores/source';
-import { srcKind, SourceKind, srcNeedsBranch } from '@/utils/sources';
+import { srcKind, SourceKind, srcNeedsBranch, identityBranch, sourceKey } from '@/utils/sources';
 import { isEmptyManifest } from '@/utils/manifest';
 import { URL_PARAMS } from '@/constants/urlParams';
 import type { Manifest } from '@/types';
@@ -134,9 +133,13 @@ export async function loadSource(payload: SourcePayload): Promise<void> {
   loadController?.abort(); // supersede any in-flight load
   const controller = new AbortController();
   loadController = controller;
+  // A local source has no branch axis — drop any branch (a stale deep-link or a
+  // legacy recent could carry one) so the fetch URL, overlay, committed source,
+  // and prefill all stay branch-less. The checked-out branch is display-only.
+  const branch = identityBranch(payload.src, payload.branch);
   const meta = {
     kind: srcKind(payload.src),
-    branch: payload.branch,
+    branch,
   };
   SCAN_PROGRESS.value = { ...meta, phase: null }; // show overlay immediately
   // Snapshot the applied manifest so a cancel that lands after a skeleton was
@@ -147,7 +150,7 @@ export async function loadSource(payload: SourcePayload): Promise<void> {
   try {
     const url = manifestUrlFor({
       src: payload.src,
-      branch: payload.branch,
+      branch,
       noCache: !!payload.skipCache,
       exclude: activeExcludePathsFor(payload.src),
     });
@@ -174,7 +177,7 @@ export async function loadSource(payload: SourcePayload): Promise<void> {
     // camera-reframe reaction keys off CURRENT_SOURCE captured at apply-START, so
     // the new key must be live for the FINAL apply (the one to frame on) and NOT
     // for the preceding skeleton apply (which must not reframe).
-    setCurrentSource(payload.src, payload.branch, manifest);
+    setCurrentSource(payload.src, branch, manifest);
     setManifest(manifest);
   } catch (err) {
     if (myGen !== loadGeneration) return; // superseded — its error isn't current
@@ -184,7 +187,7 @@ export async function loadSource(payload: SourcePayload): Promise<void> {
     }
     SOURCE_ERROR.value = {
       error: err instanceof Error ? err.message : String(err),
-      prefill: { src: payload.src, branch: payload.branch },
+      prefill: { src: payload.src, branch },
     };
   } finally {
     // Only the authoritative load tears down the overlay; a superseded one must

app/src/state/stores/excludes.ts

@@ -8,7 +8,8 @@
 import { computed, type ReadonlySignal } from '@preact/signals';
 import { persistedSignal } from '@/state/persist';
 import { PERSISTED_KEYS } from '@/constants/storage';
-import { CURRENT_SOURCE, sourceKey } from '@/state/stores/source';
+import { CURRENT_SOURCE } from '@/state/stores/source';
+import { sourceKey } from '@/utils/sources';
 
 /** repo key -> sorted, de-duped rel-paths. One localStorage slot for all repos.
  *  Whole-object persistence: keys are runtime repo hashes, not in the default,

app/src/state/stores/source.ts

@@ -1,6 +1,8 @@
 // state/stores/source.ts — Everything about *which source is loaded*: the
-// current source's stable key + display info, the per-(src,branch) hash used to
-// namespace per-source localStorage slots, and the recently-opened list.
+// current source's stable key + display info and the recently-opened list. The
+// pure source-identity helpers (sourceKey/sourceIdentity/sameSourceIdentity)
+// live in utils/sources; this module owns the signals and persistence built on
+// them.
 //
 // CURRENT_SOURCE is session-scoped (set on every successful source apply);
 // CURRENT_SOURCE_KEY + SOURCE_INFO derive from it (the latter also from
@@ -14,31 +16,17 @@ import { PERSISTED_KEYS } from '@/constants/storage';
 import { MAX_RECENT_SOURCES } from '@/constants/ui';
 import { URL_PARAMS } from '@/constants/urlParams';
 import { MANIFEST } from '@/state/stores/manifest';
-import { srcKind, SourceKind, resolveBranch } from '@/utils/sources';
+import {
+  srcKind,
+  SourceKind,
+  resolveBranch,
+  identityBranch,
+  sourceKey,
+  sameSourceIdentity,
+} from '@/utils/sources';
 import { isEmptyManifest } from '@/utils/manifest';
 import type { Manifest } from '@/types';
 
-// ── sourceKey: stable short hash of (src, branch) ────────────────────
-
-function djb2(s: string): string {
-  let h = 5381;
-  for (let i = 0; i < s.length; i++) {
-    h = ((h << 5) + h + s.charCodeAt(i)) | 0;
-  }
-  return (h >>> 0).toString(36); // unsigned, base-36 — ~6-7 chars
-}
-
-/**
- * Compute a short stable hash for a (src, branch) pair. Used to namespace
- * per-source state (selection, camera pose) in localStorage.
- *
- * The hash distinguishes (src, undefined) from (src, ""), but in practice
- * we treat empty-string branch as "no branch" — callers should pass undefined.
- */
-export function sourceKey(src: string, branch?: string): string {
-  return djb2(`${src}\0${branch ?? ''}`);
-}
-
 // ── Currently-loaded source ──────────────────────────────────────────
 
 /** The applied source ({src, branch}) or null when nothing is loaded
@@ -131,15 +119,13 @@ export function listRecents(): RecentSource[] {
 }
 
 /**
- * Push (or update) an entry. Dedupes by (src, branch ?? ''). The pushed
- * entry becomes the most-recent. List is capped at MAX_RECENT_SOURCES
- * entries (oldest dropped).
+ * Push (or update) an entry. Dedupes by source identity (src, plus branch for a
+ * remote — a local path is one row regardless of checkout). The pushed entry
+ * becomes the most-recent. List is capped at MAX_RECENT_SOURCES (oldest dropped).
  */
 export function pushRecent(entry: Omit<RecentSource, 'lastOpenedAt'>): void {
   const now = Date.now();
-  const filtered = RECENTS.value.filter(
-    (r) => !(r.src === entry.src && (r.branch ?? '') === (entry.branch ?? ''))
-  );
+  const filtered = RECENTS.value.filter((r) => !sameSourceIdentity(r, entry));
   filtered.unshift({ ...entry, lastOpenedAt: now });
   RECENTS.value = filtered.slice(0, MAX_RECENT_SOURCES);
 }
@@ -155,20 +141,23 @@ export function setCurrentSource(
   branch: string | undefined,
   manifest: Manifest
 ): void {
-  CURRENT_SOURCE.value = { src, branch };
+  // A local source carries no branch (identityBranch): its checkout is dynamic,
+  // so CURRENT_SOURCE, the URL, the cache key, and the recent all omit it. The
+  // checked-out branch is still shown in the header via SOURCE_INFO, which reads
+  // it from the manifest — display only, not identity.
+  const idBranch = identityBranch(src, branch);
+  CURRENT_SOURCE.value = { src, branch: idBranch };
   pushRecent({
     src,
     // The server bakes the canonical owner/repo name into tree.name (a local
     // worktree's src basename would be the folder name, not the repo); keep the
     // raw src only as a defensive fallback.
     label: manifest.tree?.name || src,
-    branch: resolveBranch(manifest, branch),
+    branch: identityBranch(src, resolveBranch(manifest, branch)),
   });
 }
 
-/** Drop the entry matching (src, branch). No-op if not present. */
+/** Drop the entry matching the given source identity. No-op if not present. */
 export function removeRecent(src: string, branch?: string): void {
-  RECENTS.value = RECENTS.value.filter(
-    (r) => !(r.src === src && (r.branch ?? '') === (branch ?? ''))
-  );
+  RECENTS.value = RECENTS.value.filter((r) => !sameSourceIdentity(r, { src, branch }));
 }

app/src/utils/sources.ts

@@ -38,6 +38,61 @@ export function resolveBranch(
   return requested ?? (looksReal ? mb : undefined);
 }
 
+/**
+ * The branch to commit for a source. A local source has no branch axis: it
+ * scans whatever is checked out on disk, so a stored branch would be a lie and
+ * must never namespace its cache, URL, or recents. It therefore commits
+ * `undefined`; a remote source keeps its branch. Applied once at the commit
+ * boundary (the source load + setCurrentSource) so everything downstream — the
+ * URL, the cache key, recents identity — can trust a local source is branch-
+ * less without re-checking the source kind on every read.
+ */
+export function identityBranch(src: string, branch?: string): string | undefined {
+  return srcKind(src) === SourceKind.Local ? undefined : branch;
+}
+
+// ── Source identity ──────────────────────────────────────────────────
+// A source's identity is (src + its identity branch). These derive a comparable
+// string, a boolean match, and a short hash from it — used for the localStorage
+// namespace, recents dedupe, and the active-row match. All pure: they trust the
+// branch to be normalized at the commit boundary (identityBranch), so a local
+// source is already branch-less by the time it reaches here.
+
+/**
+ * The canonical identity string for a source: its src joined with its branch.
+ * Two sources with the same identity string are "the same source". NUL-separated
+ * (can't appear in a path or URL) so src and branch can't collide across the
+ * boundary.
+ */
+export function sourceIdentity(src: string, branch?: string): string {
+  return `${src}\0${branch ?? ''}`;
+}
+
+/** Whether two source refs are the same source (same identity string). Local
+ *  refs are committed branch-less, so a checkout change never splits them. */
+export function sameSourceIdentity(
+  a: { src: string; branch?: string },
+  b: { src: string; branch?: string }
+): boolean {
+  return sourceIdentity(a.src, a.branch) === sourceIdentity(b.src, b.branch);
+}
+
+function djb2(s: string): string {
+  let h = 5381;
+  for (let i = 0; i < s.length; i++) {
+    h = ((h << 5) + h + s.charCodeAt(i)) | 0;
+  }
+  return (h >>> 0).toString(36); // unsigned, base-36 — ~6-7 chars
+}
+
+/**
+ * Compute a short stable hash for a source's identity. Used to namespace
+ * per-source state (selection, camera pose) in localStorage.
+ */
+export function sourceKey(src: string, branch?: string): string {
+  return djb2(sourceIdentity(src, branch));
+}
+
 /**
  * True when a source can't be loaded without first choosing a branch: a remote
  * URL with no branch specified. The picker resolves the repo's branches and

app/tests/components/RecentsList.test.tsx

@@ -61,6 +61,22 @@ describe('RecentsList', () => {
     expect(onOpen).toHaveBeenCalledWith({ src: 'https://github.com/o/alpha', branch: 'main' });
   });
 
+  it('renders a branch-less local recent with no @branch pill, matched active by path', async () => {
+    SERVER_CONFIG.value = { allowLocalRepos: true };
+    // A local recent is branch-less; CURRENT_SOURCE is too, so they match by src
+    // even though the loaded manifest reports a checkout branch (display only).
+    RECENTS.value = [{ src: '/Users/me/proj', label: 'proj', lastOpenedAt: 3 }];
+    CURRENT_SOURCE.value = { src: '/Users/me/proj' };
+    setManifest({ tree: { name: 'proj' }, repo: { branch: 'feat/x' } } as unknown as Manifest);
+    render(<RecentsList onOpen={() => {}} />, container);
+    await flush();
+
+    const rows = container.querySelectorAll('.recent-item');
+    expect(rows).toHaveLength(1);
+    expect(container.querySelector('.app-header-branch-pill')).toBeNull();
+    expect(container.querySelector('.recent-row--active')).toBeTruthy();
+  });
+
   it('remove is non-destructive: forgets the entry, does not touch the cache', async () => {
     const spy = vi.spyOn(manifestApi, 'clearManifestCache');
     render(<RecentsList onOpen={() => {}} />, container);

app/tests/state/stores/activeSource.test.ts

@@ -1,36 +1,17 @@
 import { describe, it, expect, afterEach } from 'vitest';
 import {
-  sourceKey,
   CURRENT_SOURCE_KEY,
   CURRENT_SOURCE,
   SOURCE_INFO,
   setCurrentSource,
   listRecents,
   RECENTS,
 } from '@/state/stores/source';
+import { sourceKey } from '@/utils/sources';
 import { setManifest } from '@/state/stores/manifest';
 import { EMPTY_MANIFEST } from '@/constants/manifest';
 import type { Manifest } from '@/types';
 
-describe('sourceKey', () => {
-  it('is deterministic for the same (src, branch)', () => {
-    expect(sourceKey('/foo', 'main')).toBe(sourceKey('/foo', 'main'));
-  });
-
-  it('distinguishes branches', () => {
-    expect(sourceKey('/foo', 'main')).not.toBe(sourceKey('/foo', 'develop'));
-  });
-
-  it('distinguishes (src, undefined) from (src, "main")', () => {
-    expect(sourceKey('/foo')).not.toBe(sourceKey('/foo', 'main'));
-  });
-
-  it('produces a short alphanumeric string', () => {
-    const k = sourceKey('/Users/example/repos/codecity');
-    expect(k).toMatch(/^[a-z0-9]{1,10}$/);
-  });
-});
-
 describe('CURRENT_SOURCE → CURRENT_SOURCE_KEY (derived)', () => {
   afterEach(() => {
     CURRENT_SOURCE.value = null;
@@ -121,12 +102,41 @@ describe('setCurrentSource', () => {
     expect(listRecents()[0].branch).toBe('dev');
   });
 
-  it('records a local source with its working-tree checkout branch', () => {
-    // A local worktree ignores any requested branch and reports its checkout.
+  it('records a local source with no branch (branch is not part of its identity)', () => {
+    // A local worktree scans whatever is checked out; storing that branch would
+    // be a lie (it changes on disk), so the recent and CURRENT_SOURCE omit it.
     setCurrentSource('/Users/me/worktrees/feat-x', undefined, {
       tree: { name: 'owner/codecity' },
       repo: { branch: 'feat/issue-77' },
     } as unknown as Manifest);
-    expect(listRecents()[0].branch).toBe('feat/issue-77');
+    expect(CURRENT_SOURCE.value).toEqual({ src: '/Users/me/worktrees/feat-x', branch: undefined });
+    expect(listRecents()[0].branch).toBeUndefined();
+  });
+
+  it('dedupes a local path across checkouts into one recent', () => {
+    // Opening the same local path at two different checkouts must not spawn a
+    // second row: both commits store branch: undefined, so they dedupe by src.
+    setCurrentSource('/proj', undefined, {
+      tree: { name: 'proj' },
+      repo: { branch: 'main' },
+    } as unknown as Manifest);
+    setCurrentSource('/proj', undefined, {
+      tree: { name: 'proj' },
+      repo: { branch: 'feat/x' },
+    } as unknown as Manifest);
+    expect(listRecents()).toHaveLength(1);
+    expect(listRecents()[0].branch).toBeUndefined();
+  });
+
+  it('drops the branch from CURRENT_SOURCE + the URL for a local source', () => {
+    // Even if a stale branch is passed in (old deep-link, recents onOpen), a
+    // local source never carries it: CURRENT_SOURCE and the page URL stay clean.
+    setCurrentSource('/Users/me/proj', 'stale-branch', {
+      tree: { name: 'proj' },
+      repo: { branch: 'main' },
+    } as unknown as Manifest);
+    expect(CURRENT_SOURCE.value).toEqual({ src: '/Users/me/proj', branch: undefined });
+    const u = new URL(window.location.href);
+    expect(u.searchParams.has('branch')).toBe(false);
   });
 });

app/tests/state/stores/excludes.test.ts

@@ -1,5 +1,6 @@
 import { describe, it, expect, beforeEach } from 'vitest';
-import { CURRENT_SOURCE, sourceKey } from '@/state/stores/source';
+import { CURRENT_SOURCE } from '@/state/stores/source';
+import { sourceKey } from '@/utils/sources';
 import {
   EXCLUDES,
   ACTIVE_EXCLUDES,