@kabmo-labs/kabmo 0.7.0 → 0.9.0

package/src/server/lib/fs/worktree/project-id.ts

@@ -0,0 +1,53 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Repository identity — the key a repository's worktrees live under.
+ *
+ * The derivation is OpenChamber's (`git rev-list --max-parents=0 --all`, sorted,
+ * first line: the root commit), and two clones of one repository share it.
+ *
+ * It is NOT stable on its own, which is why they cache it in
+ * `<primary>/.git/opencode`. Measured: adding a branch with unrelated history
+ * (`git checkout --orphan`) inserts a second root and MOVES the sorted-first
+ * value, so a repository that gained one would look for its worktrees in a
+ * different folder. Kabmo does not write into a user's `.git`, so the stored row
+ * is the cache and it always wins.
+ */
+
+import { runGit } from '@/server/lib/fs/git-run';
+
+/** `rev-list --max-parents=0 --all`, sorted, first. `null` for an unborn branch. */
+export async function deriveProjectId(primaryRoot: string): Promise<string | null> {
+  const listed = await runGit(['rev-list', '--max-parents=0', '--all'], {
+    cwd: primaryRoot,
+    maxBuffer: 1024 * 1024,
+  });
+  if (listed.exitCode !== 0) return null;
+  const roots = listed.stdout
+    .split('\n')
+    .map((line) => line.trim())
+    .filter(Boolean)
+    .sort((a, b) => a.localeCompare(b));
+  return roots[0] ?? null;
+}
+
+/**
+ * The identity to key this repository's worktrees under.
+ *
+ * A stored value beats the derivation — that is the whole point of keeping one.
+ * Only a repository with no record derives, which is the moment it has no
+ * worktree folder to protect.
+ */
+export async function resolveProjectId(
+  primaryRoot: string,
+  identityFor: (primaryRoot: string) => Promise<string | null>,
+): Promise<string> {
+  const stored = await identityFor(primaryRoot);
+  if (stored) return stored;
+  const derived = await deriveProjectId(primaryRoot);
+  if (!derived) throw new Error('This repository has no commits yet.');
+  return derived;
+}

package/src/server/lib/fs/worktree/remove.test.ts

@@ -0,0 +1,242 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Removing a worktree, against real repositories.
+ *
+ * Three rules, each measured, each a way work is lost if it is wrong:
+ *
+ *  - **Sessions are stopped BEFORE the directory goes.** The omp child holds the
+ *    worktree as its cwd; a child in a deleted directory makes
+ *    `resolveSpawnCwd` quietly run that session in the server's own folder.
+ *  - **A dirty worktree refuses.** git exits 128 with "contains modified or
+ *    untracked files" and `--force` is never passed, so the refusal is
+ *    recoverable and the count is reported.
+ *  - **The branch is deleted with `-d` only.** Its refusal (an unmerged branch)
+ *    IS the safety net, so a branch with commits of its own survives and the
+ *    answer says so rather than pretending the delete worked.
+ */
+
+import { afterAll, describe, expect, test } from 'bun:test';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { canonicalPath } from '@/server/lib/fs/canonical';
+import { createWorktree } from '@/server/lib/fs/worktree/create';
+import type { CreateWorktreeDeps } from '@/server/lib/fs/worktree/create';
+import { listWorktrees } from '@/server/lib/fs/worktree/list';
+import { commitsAheadOf, dirtyCount, removeWorktree, type RemoveWorktreeDeps } from '@/server/lib/fs/worktree/remove';
+import { invalidateWorktreeTopology } from '@/server/lib/fs/worktree/topology';
+import { removeDir } from '@/test-support/remove-dir';
+
+const FIXTURE_ROOT = fs.mkdtempSync(path.join(os.tmpdir(), 'kabmo-worktree-remove-'));
+const DATA_DIR = path.join(FIXTURE_ROOT, 'data');
+const MANAGED_ROOT = path.join(DATA_DIR, 'worktrees');
+
+const GIT_ENV_FOR_TESTS = {
+  ...Bun.env,
+  GIT_EDITOR: 'true',
+  GIT_TERMINAL_PROMPT: '0',
+  GIT_AUTHOR_NAME: 'Test',
+  GIT_AUTHOR_EMAIL: 'test@example.invalid',
+  GIT_COMMITTER_NAME: 'Test',
+  GIT_COMMITTER_EMAIL: 'test@example.invalid',
+};
+
+function git(cwd: string, ...args: string[]): string {
+  return Bun.spawnSync({ cmd: ['git', ...args], cwd, env: GIT_ENV_FOR_TESTS }).stdout.toString();
+}
+
+function makeRepo(name: string): string {
+  const dir = path.join(FIXTURE_ROOT, name);
+  fs.mkdirSync(dir, { recursive: true });
+  git(dir, 'init', '-q', '-b', 'main', '.');
+  fs.writeFileSync(path.join(dir, 'readme.md'), 'hello\n');
+  git(dir, 'add', '-A');
+  git(dir, 'commit', '-q', '-m', 'base');
+  return dir;
+}
+
+/** The registry stub: the production one is two SQLite statements. */
+function registry(rows = new Map<string, { start_ref: string }>()): RemoveWorktreeDeps & {
+  rows: Map<string, { start_ref: string }>;
+} {
+  return {
+    rows,
+    rowFor: async (candidate) => rows.get(candidate),
+    removeRow: async (candidate) => {
+      rows.delete(candidate);
+    },
+  };
+}
+
+const createDeps = (rows = new Map<string, { startRef: string; projectId: string }>()): CreateWorktreeDeps => ({
+  identityFor: async () => null,
+  carryIgnored: false,
+  dataDir: DATA_DIR,
+  configuredDirectory: null,
+  record: async (row) => {
+    rows.set(await canonicalPath(row.path), { startRef: row.startRef, projectId: row.projectId });
+  },
+});
+
+afterAll(async () => {
+  await invalidateWorktreeTopology();
+  removeDir(FIXTURE_ROOT);
+});
+
+describe('removeWorktree', () => {
+  test('a dirty worktree refuses with the count and keeps everything', async () => {
+    const repo = makeRepo('remove-dirty');
+    const created = await createWorktree({ projectPath: repo, mode: 'new', branch: 'wt/dirty' }, createDeps());
+    fs.writeFileSync(path.join(created.path, 'readme.md'), 'changed\n');
+    fs.writeFileSync(path.join(created.path, 'untracked.txt'), 'new\n');
+
+    const failure = removeWorktree(
+      { projectPath: repo, worktreePath: created.path, managedRoot: MANAGED_ROOT },
+      registry(),
+    );
+    await failure.catch((error) => expect(error).toMatchObject({ code: 'dirty', count: 2 }));
+
+    expect(fs.existsSync(created.path)).toBe(true);
+    expect((await listWorktrees(repo)).some((entry) => entry.path === created.path)).toBe(true);
+    // The refusal names what it found, so the dialog can show it.
+    expect(await dirtyCount(created.path)).toBe(2);
+  });
+
+  test('a clean worktree goes, and a branch with commits of its own is kept', async () => {
+    const repo = makeRepo('remove-keep-branch');
+    const records = new Map<string, { startRef: string; projectId: string }>();
+    const created = await createWorktree(
+      { projectPath: repo, mode: 'new', branch: 'wt/keepme' },
+      createDeps(records),
+    );
+    fs.writeFileSync(path.join(created.path, 'work.txt'), 'done\n');
+    git(created.path, 'add', '-A');
+    git(created.path, 'commit', '-q', '-m', 'work');
+
+    const rows = new Map([[await canonicalPath(created.path), { start_ref: 'HEAD' }]]);
+    const deps = registry(rows);
+    // The dialog gates on this number: anything above zero must disable the
+    // branch checkbox, because `git branch -d` would refuse anyway.
+    expect(await commitsAheadOf(await canonicalPath(repo), 'HEAD', 'wt/keepme')).toBe(1);
+
+    const result = await removeWorktree(
+      { projectPath: repo, worktreePath: created.path, deleteBranch: true, managedRoot: MANAGED_ROOT },
+      deps,
+    );
+
+    expect(result.removed).toBe(true);
+    expect(result.branchDeleted).toBe(false);
+    expect(result.branchKept).toBe(true);
+    expect(fs.existsSync(created.path)).toBe(false);
+    expect(git(repo, 'branch', '--list', 'wt/keepme').trim()).toContain('wt/keepme');
+    expect(rows.size).toBe(0);
+  });
+
+  test('a branch with nothing of its own is deleted with -d', async () => {
+    const repo = makeRepo('remove-delete-branch');
+    const created = await createWorktree({ projectPath: repo, mode: 'new', branch: 'wt/disposable' }, createDeps());
+    const rows = new Map([[await canonicalPath(created.path), { start_ref: 'HEAD' }]]);
+
+    const result = await removeWorktree(
+      { projectPath: repo, worktreePath: created.path, deleteBranch: true, managedRoot: MANAGED_ROOT },
+      registry(rows),
+    );
+
+    expect(result.branchDeleted).toBe(true);
+    expect(git(repo, 'branch', '--list', 'wt/disposable').trim()).toBe('');
+    expect(rows.size).toBe(0);
+  });
+
+  test('the main checkout cannot be removed', async () => {
+    const repo = makeRepo('remove-primary');
+    const primary = (await listWorktrees(repo)).find((entry) => entry.isPrimary)?.path as string;
+    const failure = removeWorktree({ projectPath: repo, worktreePath: primary }, registry());
+    await failure.catch((error) => expect(error).toMatchObject({ code: 'primary_checkout' }));
+  });
+
+  test('a path that is not a worktree of this repository is refused', async () => {
+    const repo = makeRepo('remove-stranger');
+    const stranger = path.join(FIXTURE_ROOT, 'stranger');
+    fs.mkdirSync(stranger, { recursive: true });
+    const failure = removeWorktree({ projectPath: repo, worktreePath: stranger }, registry());
+    await failure.catch((error) => expect(error).toMatchObject({ code: 'not_a_worktree' }));
+  });
+
+  test('a worktree whose folder was deleted outside Kabmo still removes, and prunes', async () => {
+    const repo = makeRepo('remove-vanished');
+    const created = await createWorktree({ projectPath: repo, mode: 'new', branch: 'wt/vanish' }, createDeps());
+    fs.rmSync(created.path, { recursive: true, force: true });
+
+    // It is still listed — that is what keeps its sessions on screen.
+    expect((await listWorktrees(repo)).some((entry) => entry.path === created.path)).toBe(true);
+
+    const result = await removeWorktree(
+      { projectPath: repo, worktreePath: created.path, deleteBranch: true, managedRoot: MANAGED_ROOT },
+      registry(),
+    );
+    expect(result.removed).toBe(true);
+    expect((await listWorktrees(repo)).some((entry) => entry.path === created.path)).toBe(false);
+  });
+
+  test('children are stopped BEFORE the directory disappears', async () => {
+    const repo = makeRepo('remove-order');
+    const created = await createWorktree({ projectPath: repo, mode: 'new', branch: 'wt/order' }, createDeps());
+
+    // A child that simply waits: `await new Promise(() => {})` never settles, so
+    // the process stays alive without a timer a test would have to wait on.
+    const child = Bun.spawn({
+      cmd: ['bun', '-e', 'await new Promise(() => {});'],
+      cwd: created.path,
+      stdin: 'ignore',
+      stdout: 'ignore',
+      stderr: 'ignore',
+    });
+
+    const order: string[] = [];
+    const result = await removeWorktree(
+      {
+        projectPath: repo,
+        worktreePath: created.path,
+        managedRoot: MANAGED_ROOT,
+        stopSessions: async (worktreePath) => {
+          order.push(`stop:${path.basename(worktreePath)}`);
+          child.kill();
+          await child.exited;
+          return ['session-1'];
+        },
+      },
+      registry(),
+    );
+    order.push('removed');
+
+    expect(order).toEqual(['stop:order', 'removed']);
+    expect(result.archived).toEqual(['session-1']);
+    expect(fs.existsSync(created.path)).toBe(false);
+    // A SIGTERM'd process reports `signalCode`, not an exit code.
+    expect(child.signalCode).toBe('SIGTERM');
+  });
+
+  test('a refusal after the sessions are stopped leaves a worktree that can be retried', async () => {
+    const repo = makeRepo('remove-retry');
+    const created = await createWorktree({ projectPath: repo, mode: 'new', branch: 'wt/retry' }, createDeps());
+    fs.writeFileSync(path.join(created.path, 'dirty.txt'), 'x');
+
+    const failure = removeWorktree(
+      {
+        projectPath: repo,
+        worktreePath: created.path,
+        managedRoot: MANAGED_ROOT,
+        stopSessions: async () => ['session-1'],
+      },
+      registry(),
+    );
+    await failure.catch((error) => expect(error).toMatchObject({ code: 'dirty' }));
+
+    expect(fs.existsSync(created.path)).toBe(true);
+    expect((await listWorktrees(repo)).some((entry) => entry.path === created.path)).toBe(true);
+  });
+});

package/src/server/lib/fs/worktree/remove.ts

@@ -0,0 +1,152 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Remove a worktree, in an order that is the REVERSE of OpenChamber's and
+ * deliberately so: the omp child holds the worktree as its cwd, so the sessions
+ * are stopped and deleted FIRST and only then does the directory go away.
+ *
+ * A child still holding a deleted cwd is the case `resolveSpawnCwd` papers over
+ * by silently running the session in the server's own directory — a session the
+ * user asked to delete, alive somewhere else.
+ *
+ * Nothing here passes `--force`. A dirty worktree refuses (measured: git exits
+ * 128 with "contains modified or untracked files") and the caller reports the
+ * count instead of destroying work, so the refusal is recoverable.
+ */
+
+import { existsSync, rmSync } from 'fs';
+import path from 'path';
+import { canonicalPath, pathHolds } from '@/server/lib/fs/canonical';
+import { runGit } from '@/server/lib/fs/git-run';
+import { resolveProjectRoot } from '@/server/lib/omp/core/worktree';
+import { WorktreeError } from '@/server/lib/fs/worktree/errors';
+import { isWorkTree, listWorktrees } from '@/server/lib/fs/worktree/list';
+
+/** Changed + untracked count in `directory`; 0 when git cannot answer. */
+export async function dirtyCount(directory: string): Promise<number> {
+  const result = await runGit(['status', '--porcelain'], { cwd: directory, maxBuffer: 4 * 1024 * 1024 });
+  if (result.exitCode !== 0) return 0;
+  return result.stdout.split('\n').filter((line) => line.trim()).length;
+}
+
+/** Commits on `branch` that are not on `startRef`; null when it cannot be told. */
+export async function commitsAheadOf(
+  repo: string,
+  startRef: string,
+  branch: string,
+): Promise<number | null> {
+  if (!startRef || !branch) return null;
+  const result = await runGit(['rev-list', '--count', `${startRef}..${branch}`], { cwd: repo });
+  if (result.exitCode !== 0) return null;
+  const value = Number.parseInt(result.stdout.trim(), 10);
+  return Number.isFinite(value) ? value : null;
+}
+
+export interface RemoveWorktreeInput {
+  /** Absolute worktree path as the caller holds it (any spelling). */
+  worktreePath: string;
+  /** Any directory inside the repository — used for the git commands. */
+  projectPath: string;
+  /** Delete the branch too, attempted with `git branch -d` only. */
+  deleteBranch?: boolean;
+  /**
+   * `<data dir>/worktrees` — a root Kabmo owns outright, where a leftover
+   * directory may be cleaned even after git stopped tracking it. A CONFIGURED
+   * root is not this: there, only a path git still lists is ever touched.
+   */
+  managedRoot?: string | null;
+  /**
+   * Destroy the live children whose cwd is inside, and delete or archive their
+   * sessions. Runs BEFORE anything is removed; returns the ids it handled.
+   */
+  stopSessions?: (worktreePath: string) => Promise<string[]>;
+}
+
+export interface RemoveWorktreeDeps {
+  rowFor: (worktreePath: string) => Promise<{ start_ref: string } | undefined>;
+  removeRow: (worktreePath: string) => Promise<void>;
+}
+
+export interface RemovedWorktree {
+  removed: true;
+  archived: string[];
+  branchDeleted: boolean;
+  /** True when the user asked for the branch and git refused to lose it. */
+  branchKept: boolean;
+}
+
+export async function removeWorktree(
+  input: RemoveWorktreeInput,
+  deps: RemoveWorktreeDeps,
+): Promise<RemovedWorktree> {
+  const requested = path.resolve(input.worktreePath);
+  const insideManagedRoot = input.managedRoot ? await pathHolds(input.managedRoot, requested) : false;
+
+  const insideWorkTree = await isWorkTree(input.projectPath);
+  if (!insideWorkTree) {
+    throw new WorktreeError('not_a_repo', 'This folder is not a Git repository.');
+  }
+
+  const primaryRoot = await resolveProjectRoot(input.projectPath);
+  const entries = await listWorktrees(primaryRoot);
+  const target = await canonicalPath(requested);
+  const entry = entries.find((candidate) => candidate.path === target);
+
+  if (!entry) {
+    // Not registered: only a directory inside a root we own may be cleaned, and
+    // only because git already let it go.
+    if (!insideManagedRoot) {
+      throw new WorktreeError('not_a_worktree', `${requested} is not a worktree of this repository.`);
+    }
+    await runGit(['worktree', 'prune'], { cwd: primaryRoot });
+    if (existsSync(requested)) rmSync(requested, { recursive: true, force: true });
+    await deps.removeRow(target);
+    return { removed: true, archived: [], branchDeleted: false, branchKept: false };
+  }
+
+  if (entry.isPrimary) {
+    throw new WorktreeError('primary_checkout', 'The main checkout cannot be removed.');
+  }
+
+  const archived = input.stopSessions ? await input.stopSessions(entry.path) : [];
+
+  const dirty = await dirtyCount(entry.path);
+  if (dirty > 0) {
+    throw new WorktreeError(
+      'dirty',
+      `${dirty} uncommitted file${dirty === 1 ? '' : 's'} here would be lost.`,
+      { count: dirty },
+    );
+  }
+
+  const removed = await runGit(['worktree', 'remove', entry.path], { cwd: primaryRoot });
+  if (removed.exitCode !== 0) {
+    throw new WorktreeError(
+      'remove_failed',
+      removed.stderr.trim() || removed.stdout.trim() || `git exited ${removed.exitCode}`,
+    );
+  }
+  await runGit(['worktree', 'prune'], { cwd: primaryRoot });
+
+  // The branch: `-d` only. Its refusal IS the safety net, so a branch with
+  // commits of its own survives and the answer says so.
+  let branchDeleted = false;
+  let branchKept = false;
+  if (input.deleteBranch && entry.branch) {
+    const row = await deps.rowFor(entry.path);
+    const ahead = await commitsAheadOf(primaryRoot, row?.start_ref ?? '', entry.branch);
+    if (ahead !== null && ahead > 0) {
+      branchKept = true;
+    } else {
+      const deleted = await runGit(['branch', '-d', entry.branch], { cwd: primaryRoot });
+      branchDeleted = deleted.exitCode === 0;
+      branchKept = !branchDeleted;
+    }
+  }
+
+  await deps.removeRow(entry.path);
+  return { removed: true, archived, branchDeleted, branchKept };
+}

package/src/server/lib/fs/worktree/settings.server.ts

@@ -0,0 +1,56 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * The two worktree settings, read on the SERVER.
+ *
+ * They live in the `kabmo_settings` blob the settings UI writes, and a create
+ * has to honour them without a round trip through the page — a scheduled task or
+ * a plugin can create a worktree with no tab open.
+ *
+ * Absent means the default, never "off": a database written before this feature
+ * has no keys at all, and the feature must behave as documented on it.
+ */
+
+import { getDb } from '@/server/db.server';
+import { readSettingsBlob, SETTINGS_BLOB_KEY } from '@/shared/lib/settings/keys';
+import {
+  WORKTREE_CARRY_SETTING,
+  WORKTREE_DIRECTORY_SETTING,
+} from '@/shared/lib/fs/worktree/settings-keys';
+
+export interface WorktreeSettings {
+  /** The configured parent directory, un-resolved; `null` when unset. */
+  directory: string | null;
+  carryIgnored: boolean;
+}
+
+export async function readWorktreeSettings(): Promise<WorktreeSettings> {
+  const fallback: WorktreeSettings = { directory: null, carryIgnored: true };
+  try {
+    const db = await getDb();
+    const row = await db.get<{ value: string }>('SELECT value FROM app_settings WHERE key = ?', [SETTINGS_BLOB_KEY]);
+    if (!row?.value) return fallback;
+    let parsed: unknown;
+    try {
+      parsed = JSON.parse(row.value);
+    } catch {
+      return fallback;
+    }
+    const blob = readSettingsBlob({ [SETTINGS_BLOB_KEY]: parsed });
+    const directory = typeof blob[WORKTREE_DIRECTORY_SETTING] === 'string'
+      ? (blob[WORKTREE_DIRECTORY_SETTING] as string)
+      : null;
+    const carry = blob[WORKTREE_CARRY_SETTING];
+    return {
+      directory: directory?.trim() ? directory.trim() : null,
+      // Only an explicit `false` turns the carry off; anything else is the
+      // documented default of on.
+      carryIgnored: carry !== false,
+    };
+  } catch {
+    return fallback;
+  }
+}

package/src/server/lib/fs/worktree/topology.ts

@@ -0,0 +1,142 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Worktree topology of one repository, and the session → worktree lookup built
+ * on it.
+ *
+ * A session's badge is derived from its own cwd, never from a stored
+ * association: the cwd is the truth and it survives a branch rename.
+ *
+ * The topology is cached per primary root for a short TTL, because the sidebar
+ * scan runs on every publish while `git worktree list` costs a spawn per
+ * repository. `invalidateWorktreeTopology()` is called by the create and remove
+ * paths, and by the `workspace-dirty` signal, so a worktree made a second ago
+ * appears without waiting the TTL out.
+ */
+
+import { canonicalPath, pathHolds } from '@/server/lib/fs/canonical';
+import { listWorktrees, type WorktreeEntry } from '@/server/lib/fs/worktree/list';
+import type { SessionWorktreeInfo } from '@/shared/lib/workspace/worktree/types';
+
+const TOPOLOGY_TTL_MS = 10_000;
+
+declare global {
+  // eslint-disable-next-line no-var
+  var __kabmoWorktreeTopology:
+    | Map<string, { entries: WorktreeEntry[]; expiresAt: number; inFlight?: Promise<WorktreeEntry[]> }>
+    | undefined;
+}
+
+function topologyCache(): Map<string, { entries: WorktreeEntry[]; expiresAt: number; inFlight?: Promise<WorktreeEntry[]> }> {
+  globalThis.__kabmoWorktreeTopology ??= new Map();
+  return globalThis.__kabmoWorktreeTopology;
+}
+
+/** Drop the cache for one repository, or all of them. */
+export async function invalidateWorktreeTopology(primaryRoot?: string): Promise<void> {
+  const cache = topologyCache();
+  if (!primaryRoot) {
+    cache.clear();
+    return;
+  }
+  cache.delete(await canonicalPath(primaryRoot));
+}
+
+/**
+ * Every worktree of `primaryRoot`, cached for a few seconds. A failure is NOT
+ * cached: an unreadable repository must not look like one with no worktrees for
+ * the next ten minutes.
+ */
+export async function readProjectWorktrees(primaryRoot: string): Promise<WorktreeEntry[]> {
+  const cache = topologyCache();
+  // Keyed by the CANONICAL root: a caller holding `/tmp/x` and one holding
+  // `/private/tmp/x` are asking about one repository, and two entries would let
+  // an invalidation miss the entry a later read created (measured: the
+  // invalidation dropped nothing and the new worktree stayed invisible).
+  const key = await canonicalPath(primaryRoot);
+  const hit = cache.get(key);
+  if (hit && hit.expiresAt > Date.now()) return hit.entries;
+  if (hit?.inFlight) return hit.inFlight;
+
+  const inFlight = listWorktrees(key)
+    .then((entries) => {
+      cache.set(key, { entries, expiresAt: Date.now() + TOPOLOGY_TTL_MS });
+      return entries;
+    })
+    .catch((error: unknown) => {
+      cache.delete(key);
+      throw error;
+    });
+
+  cache.set(key, { entries: hit?.entries ?? [], expiresAt: 0, inFlight });
+  return inFlight;
+}
+
+/**
+ * The worktree holding `cwd`, or null when the session runs in the checkout
+ * itself — a chat in the main repository is not a "worktree session", and a
+ * badge on every row would be noise — or in none.
+ *
+ * Longest path wins, so a worktree nested inside another resolves to the inner
+ * checkout: the directory the agent actually writes to.
+ */
+export async function worktreeForCwd(
+  entries: WorktreeEntry[],
+  cwd: string,
+  primaryRoot: string,
+): Promise<SessionWorktreeInfo | null> {
+  let best: WorktreeEntry | null = null;
+  let bestLength = -1;
+
+  for (const entry of entries) {
+    if (!entry.path || entry.isPrimary) continue;
+    if (!(await pathHolds(entry.path, cwd))) continue;
+    const length = (await canonicalPath(entry.path)).length;
+    if (length <= bestLength) continue;
+    best = entry;
+    bestLength = length;
+  }
+
+  if (!best) return null;
+  return {
+    branch: best.branch,
+    path: await canonicalPath(best.path),
+    primaryRoot,
+    status: best.missing ? 'missing' : 'ready',
+    detached: best.detached,
+  };
+}
+
+/**
+ * One lookup per session of one repository, sharing a single topology read.
+ * Sessions whose cwd is outside every worktree are absent from the map — the
+ * caller treats "absent" as "an ordinary session", which is the common case.
+ */
+export async function sessionWorktreeMap(
+  primaryRoot: string,
+  sessions: readonly { id: string; cwd: string }[],
+): Promise<Map<string, SessionWorktreeInfo>> {
+  const result = new Map<string, SessionWorktreeInfo>();
+  if (sessions.length === 0) return result;
+
+  let entries: WorktreeEntry[];
+  try {
+    entries = await readProjectWorktrees(primaryRoot);
+  } catch {
+    // A repository git cannot read has no badges to draw; it must not fail the
+    // sidebar, which lists sessions from files rather than from git.
+    return result;
+  }
+  if (entries.length <= 1) return result;
+
+  const resolved = await Promise.all(
+    sessions.map(async (session) => ({ id: session.id, info: await worktreeForCwd(entries, session.cwd, primaryRoot) })),
+  );
+  for (const { id, info } of resolved) {
+    if (info) result.set(id, info);
+  }
+  return result;
+}