@kabmo-labs/kabmo 0.7.0 → 0.8.0

package/src/client/hooks/workspace/file-listing.ts

@@ -25,7 +25,7 @@
 
 import { useRef, useState } from 'preact/hooks';
 import type { FsNode } from '@/shared/types';
-import { rehydrateTree, setChildrenAt } from '@/shared/lib/fs/file-tree';
+import { placeEntry, rehydrateTree, setChildrenAt, takeEntry, rekeyCache } from '@/shared/lib/fs/file-tree';
 import { isRecord } from '@/shared/lib/util/guards';
 
 /**
@@ -86,6 +86,20 @@ export interface FileListing {
   loadChildren: (path: string) => Promise<void>;
   /** Adopt a realtime root snapshot, then re-read the open folders. */
   adoptRoot: (payload: unknown) => void;
+  /**
+   * Insert a row the panel just created, without a reload.
+   *
+   * A create answers with the entry's path, so the tree already knows the whole
+   * result; re-reading the root plus every open folder to learn it back would
+   * be one request per open folder for an answer the caller holds.
+   */
+  insertEntry: (entry: { path: string; kind: 'file' | 'folder' }) => void;
+  /**
+   * Move a row the panel just renamed, without a reload. Returns the folders
+   * whose path moved, so the caller can rekey its expansion set — a renamed
+   * folder's open branches are still open, under their new names.
+   */
+  moveEntry: (fromPath: string, toPath: string) => void;
   /** Forget the root listing and every cached child (a repo switch). */
   reset: () => void;
 }
@@ -117,6 +131,8 @@ export function useFileListing({
   const scopeRef = useRef(scope);
   scopeRef.current = scope;
   const listedScopeRef = useRef('');
+  /** The absolute base dir the current listing was read for — what `commit` stamps. */
+  const listedRootRef = useRef('');
   const expandedPathsRef = useRef(expandedPaths);
   expandedPathsRef.current = expandedPaths;
 
@@ -132,6 +148,7 @@ export function useFileListing({
   /** Render the tree from the current root listing plus the children cache. */
   const commit = (requested: string, root: string) => {
     listedScopeRef.current = requested;
+    listedRootRef.current = root;
     setState({
       scope: requested,
       files: rehydrateTree(rootFilesRef.current, childrenCacheRef.current),
@@ -223,9 +240,45 @@ export function useFileListing({
     childrenCacheRef.current = {};
     rootFilesRef.current = [];
     listedScopeRef.current = '';
+    listedRootRef.current = '';
     setState({ scope: '', files: [], root: '' });
   };
 
+  /**
+   * The tree edits below patch the same two sources a read fills — the root
+   * list and the children cache — and then commit, so `rehydrateTree` remains
+   * the only thing that builds what is rendered. Editing the rendered tree
+   * directly would be undone by the next commit, which rebuilds from these.
+   */
+  const insertEntry = (entry: { path: string; kind: 'file' | 'folder' }): void => {
+    const requested = scopeRef.current;
+    if (listedScopeRef.current !== requested) return;
+    const node: FsNode = {
+      name: entry.path.slice(entry.path.lastIndexOf('/') + 1),
+      path: entry.path,
+      type: entry.kind,
+      ignored: false,
+    };
+    const placed = placeEntry(rootFilesRef.current, childrenCacheRef.current, node);
+    if (placed.nodes === rootFilesRef.current) return;
+    rootFilesRef.current = placed.nodes;
+    childrenCacheRef.current = placed.cache;
+    commit(requested, listedRootRef.current);
+  };
+
+  const moveEntry = (fromPath: string, toPath: string): void => {
+    const requested = scopeRef.current;
+    if (listedScopeRef.current !== requested) return;
+    const taken = takeEntry(rootFilesRef.current, childrenCacheRef.current, fromPath);
+    if (!taken.entry) return;
+    childrenCacheRef.current = rekeyCache(taken.cache, fromPath, toPath);
+    const moved: FsNode = { ...taken.entry, path: toPath, name: toPath.slice(toPath.lastIndexOf('/') + 1) };
+    const placed = placeEntry(taken.nodes, childrenCacheRef.current, moved);
+    rootFilesRef.current = placed.nodes;
+    childrenCacheRef.current = placed.cache;
+    commit(requested, listedRootRef.current);
+  };
+
   // A listing read for another scope is not this one's to render: the panel
   // shows an empty tree until the current scope's read lands.
   const current = state.scope === scope;
@@ -237,6 +290,8 @@ export function useFileListing({
     reload,
     loadChildren,
     adoptRoot,
+    insertEntry,
+    moveEntry,
     reset,
   };
 }

package/src/client/hooks/workspace/file-tree-actions.ts

@@ -22,7 +22,7 @@ import type { FormEvent, RefObject } from 'preact/compat';
 import { useFetcher } from '@/client/lib/router/fetcher';
 import { toAbsolutePath } from '@/shared/lib/fs/paths';
 import { copyToClipboard } from '@/client/hooks/ui/clipboard';
-import { useFileCreate } from '@/client/hooks/workspace/file-create';
+import { useFileCreate, type CreatedEntry } from '@/client/hooks/workspace/file-create';
 import type { FileClipboard } from '@/client/hooks/workspace/file-clipboard';
 import type { FsActionResponse } from '@/shared/types';
 
@@ -40,7 +40,17 @@ export interface FileActionDeps {
   /** Which diff to open, when the row is a changed file. */
   diff?: { staged?: boolean; status?: string };
   onOpenFile?: (file: { path: string; name: string; root?: string; repo?: string }) => void;
+  /** Re-read the tree — a DELETE has no local answer, so it re-reads. */
   onActionComplete: () => void;
+  /**
+   * A row the panel just created, placed locally.
+   *
+   * A create answers with the whole result, so the tree inserts it rather than
+   * re-reading the root plus every open folder to learn it back.
+   */
+  onCreated?: (entry: CreatedEntry) => void;
+  /** A row the panel just renamed, moved locally — same reason as `onCreated`. */
+  onRenamed?: (fromPath: string, toPath: string) => void;
   /** The panel's clipboard: Cut/Copy fill it, Paste reads it. */
   clipboard: FileClipboard;
   /** Whether this row is a folder — what Cut/Copy/Paste need to name their target. */
@@ -56,12 +66,16 @@ export interface FileActions {
   showDeleteModal: boolean;
   showHistoryModal: boolean;
   showCreateModal: boolean;
+  /** Whether the open create dialog makes a folder. */
+  createKind: 'file' | 'folder';
   /** The server's refusal for the create request, rendered inside its dialog. */
   createError: string | null;
   createName: string;
   setCreateName: (value: string) => void;
   renameValue: string;
   setRenameValue: (value: string) => void;
+  /** The server's refusal for the rename request, rendered inside its dialog. */
+  renameError: string | null;
   /** True while a request is in flight; every dialog's buttons read it. */
   busy: boolean;
   /** Label of the row's Paste action, or null when a paste cannot land here. */
@@ -79,7 +93,7 @@ export interface FileActions {
   closeHistory: () => void;
 }
 
-export function useFileActions({ file, diff, onOpenFile, onActionComplete, clipboard, isFolder }: FileActionDeps): FileActions {
+export function useFileActions({ file, diff, onOpenFile, onActionComplete, onCreated, onRenamed, clipboard, isFolder }: FileActionDeps): FileActions {
   const actionFetcher = useFetcher<FsActionResponse>();
   const [contextMenu, setContextMenu] = useState<{ x: number; y: number } | null>(null);
   const contextMenuRef = useRef<HTMLDivElement>(null);
@@ -87,6 +101,7 @@ export function useFileActions({ file, diff, onOpenFile, onActionComplete, clipb
   const [showDeleteModal, setShowDeleteModal] = useState(false);
   const [showHistoryModal, setShowHistoryModal] = useState(false);
   const [renameValue, setRenameValue] = useState(file.path);
+  const [renameError, setRenameError] = useState<string | null>(null);
 
   const repo = file.repo;
   const rootPath = file.rootPath;
@@ -98,7 +113,10 @@ export function useFileActions({ file, diff, onOpenFile, onActionComplete, clipb
     folderPath: file.path,
     rootPath,
     repo,
-    onCreated: onActionComplete,
+    // The tree places the entry itself and does NOT reload: the response names
+    // the whole result, and re-reading the root plus every open folder to learn
+    // it back is the reload this path exists to avoid.
+    onCreated: (entry) => (onCreated ? onCreated(entry) : onActionComplete()),
     onOpenCreated: (created) => onOpenFile?.({ ...created, root: rootPath, repo: repo || '.' }),
   });
 
@@ -124,7 +142,15 @@ export function useFileActions({ file, diff, onOpenFile, onActionComplete, clipb
     if (data.success && !data.type) {
       setShowRenameModal(false);
       setShowDeleteModal(false);
-      onActionComplete();
+      setRenameError(null);
+      // A rename response names both ends, so the tree moves the row locally
+      // instead of re-reading every open folder to discover the move.
+      if (data.previousPath && data.path && onRenamed) onRenamed(data.previousPath, data.path);
+      else onActionComplete();
+    } else if (!data.success && data.error && showRenameModal) {
+      // A refusal keeps the dialog open with the server's own words beside the
+      // field: "already exists" is a message about what to type next.
+      setRenameError(data.error);
     }
     // eslint-disable-next-line react-hooks/exhaustive-deps
   }, [actionFetcher.state, actionFetcher.data]);
@@ -155,6 +181,7 @@ export function useFileActions({ file, diff, onOpenFile, onActionComplete, clipb
 
   const handleAction = (actionType: string) => {
     setContextMenu(null);
+    setRenameError(null);
     if (actionType === 'view') {
       openFile();
     } else if (actionType === 'diff') {
@@ -186,7 +213,9 @@ export function useFileActions({ file, diff, onOpenFile, onActionComplete, clipb
       setRenameValue(file.path);
       setShowRenameModal(true);
     } else if (actionType === 'new_file') {
-      create.openDialog();
+      create.openDialog('file');
+    } else if (actionType === 'new_folder') {
+      create.openDialog('folder');
     } else if (actionType === 'delete') {
       setShowDeleteModal(true);
     } else if (actionType === 'cut') {
@@ -202,6 +231,7 @@ export function useFileActions({ file, diff, onOpenFile, onActionComplete, clipb
 
   const submitRename = (e: FormEvent) => {
     e.preventDefault();
+    setRenameError(null);
     const fd = new FormData();
     fd.append('actionType', 'rename');
     fd.append('path', file.path);
@@ -225,11 +255,13 @@ export function useFileActions({ file, diff, onOpenFile, onActionComplete, clipb
     showDeleteModal,
     showHistoryModal,
     showCreateModal: create.open,
+    createKind: create.kind,
     createError: create.error,
     createName: create.name,
     setCreateName: create.setName,
     renameValue,
     setRenameValue,
+    renameError,
     busy: actionFetcher.state !== 'idle' || create.busy || clipboard.busy,
     pasteLabel,
     fetcherState: actionFetcher.state,

package/src/client/hooks/workspace/worktree/index.ts

@@ -0,0 +1,150 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Client state for the worktree surfaces: the list, creation and removal.
+ *
+ * One module for all three because they share the same two facts — the project
+ * the request is scoped to and the failure shape the server answers with — and
+ * splitting them would put the fetch envelope in three places.
+ *
+ * Nothing here invents a path: the server resolves the destination from the
+ * dialog's NAME and reports back what it used, so the client cannot name a
+ * directory outside the project.
+ */
+
+import { useCallback, useEffect, useState } from 'preact/hooks';
+import type { WorktreeFailure, WorktreeInfo, WorktreeListPayload, WorktreeValidation } from '@/shared/lib/workspace/worktree/types';
+
+export interface WorktreeRequestScope {
+  /** The project's `project_path`, sent as `?root=`. */
+  root: string | null;
+  /** Sent as `?folderId=` so an unbound-but-valid folder still resolves. */
+  folderId?: number | string | null;
+}
+
+function queryFor(scope: WorktreeRequestScope): string {
+  const params = new URLSearchParams();
+  if (scope.root) params.set('root', scope.root);
+  if (scope.folderId !== null && scope.folderId !== undefined) params.set('folderId', String(scope.folderId));
+  const query = params.toString();
+  return query ? `?${query}` : '';
+}
+
+/** A refusal the UI reports verbatim; `field` marks the input that caused it. */
+export class WorktreeRequestError extends Error {
+  readonly failure: WorktreeFailure;
+
+  constructor(failure: WorktreeFailure) {
+    super(failure.message);
+    this.name = 'WorktreeRequestError';
+    this.failure = failure;
+  }
+}
+
+async function readFailure(response: Response): Promise<never> {
+  const body = (await response.json().catch(() => null)) as (WorktreeFailure & { error?: string }) | null;
+  throw new WorktreeRequestError({
+    code: body?.code ?? 'create_failed',
+    message: body?.message ?? body?.error ?? `HTTP ${response.status}`,
+    ...(body?.field ? { field: body.field } : {}),
+    ...(body?.count !== undefined ? { count: body.count } : {}),
+  });
+}
+
+/** The project's worktrees, with the facts each row shows. */
+export function useWorktrees(scope: WorktreeRequestScope, enabled: boolean) {
+  const [payload, setPayload] = useState<WorktreeListPayload | null>(null);
+  const [loading, setLoading] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+
+  const refresh = useCallback(async () => {
+    if (!enabled) return;
+    setLoading(true);
+    try {
+      const response = await fetch(`/api/worktrees${queryFor(scope)}`);
+      if (!response.ok) await readFailure(response);
+      setPayload((await response.json()) as WorktreeListPayload);
+      setError(null);
+    } catch (cause) {
+      // Kept apart from the payload: an empty list and a failed read are
+      // different answers, and only one of them means nothing is there.
+      setError(cause instanceof Error ? cause.message : String(cause));
+    } finally {
+      setLoading(false);
+    }
+  }, [enabled, scope.root, scope.folderId]);
+
+  useEffect(() => {
+    void refresh();
+  }, [refresh]);
+
+  return {
+    payload,
+    worktrees: payload?.worktrees ?? ([] as WorktreeInfo[]),
+    /** The resolved parent directory a create would use. */
+    base: payload?.base ?? '',
+    loading,
+    error,
+    refresh,
+  };
+}
+
+export interface CreateWorktreeRequest {
+  mode: 'new' | 'existing';
+  branch?: string;
+  worktreeName?: string;
+  startRef?: string;
+}
+
+/** The plan a create would use, without creating anything. */
+export async function validateWorktree(
+  scope: WorktreeRequestScope,
+  request: CreateWorktreeRequest,
+): Promise<WorktreeValidation> {
+  const response = await fetch(`/api/worktrees/validate${queryFor(scope)}`, {
+    method: 'POST',
+    headers: { 'content-type': 'application/json' },
+    body: JSON.stringify(request),
+  });
+  const body = (await response.json().catch(() => null)) as WorktreeValidation | null;
+  if (!body) return { ok: false, failures: [{ code: 'create_failed', message: `HTTP ${response.status}` }] };
+  return body;
+}
+
+export async function createWorktree(
+  scope: WorktreeRequestScope,
+  request: CreateWorktreeRequest,
+): Promise<WorktreeInfo> {
+  const response = await fetch(`/api/worktrees${queryFor(scope)}`, {
+    method: 'POST',
+    headers: { 'content-type': 'application/json' },
+    body: JSON.stringify(request),
+  });
+  if (!response.ok) await readFailure(response);
+  const body = (await response.json()) as { worktree: WorktreeInfo };
+  return body.worktree;
+}
+
+export interface RemoveWorktreeResult {
+  removed: true;
+  archived: string[];
+  branchDeleted: boolean;
+  branchKept: boolean;
+}
+
+export async function removeWorktree(
+  scope: WorktreeRequestScope,
+  worktreePath: string,
+  options: { deleteBranch?: boolean } = {},
+): Promise<RemoveWorktreeResult> {
+  const response = await fetch(`/api/worktrees${queryFor(scope)}`, {
+    method: 'DELETE',
+    headers: { 'content-type': 'application/json' },
+    body: JSON.stringify({ path: worktreePath, deleteBranch: options.deleteBranch === true }),
+  });
+  if (!response.ok) await readFailure(response);
+  return (await response.json()) as RemoveWorktreeResult;
+}

package/src/client/tailwind.css

@@ -245,6 +245,25 @@
   }
 }
 
+/* The Files panel's tree, on a finger.
+ *
+ * Every row is `select-none`, but a long press on iOS/Android still raises the
+ * native callout and a selection of the CONTAINER's text — measured on a phone:
+ * holding a file row highlighted the whole panel instead of opening its menu.
+ * `user-select` alone does not stop it; `-webkit-touch-callout` is what removes
+ * the callout menu, and `user-select: none` on the scroller (not only the rows)
+ * is what keeps a press that drifts between two rows from selecting the text of
+ * both. Rows themselves stay `select-none` and no row carries `select-text`:
+ * a path is copied through the context menu's Copy Path, never by dragging over
+ * it, and a selectable row makes every press a candidate for a selection.
+ */
+.file-tree-touch,
+.file-tree-touch * {
+  -webkit-touch-callout: none;
+  -webkit-user-select: none;
+  user-select: none;
+}
+
 /* Horizontally scrollable strips (mobile tab bars) that pan without a visible
  * scrollbar track eating vertical space. */
 .no-scrollbar {

package/src/server/index.ts

@@ -268,7 +268,9 @@ startWaitingRuntime();
  *
  * A Kabmo update replaces the store and leaves the install — it is a
  * copied directory of ordinary files — so this is the only thing that notices.
- * It is version-gated and skips git clones, so a plugin the user installed from
+ * An install Kabmo wrote is compared by CONTENT, so a shipped fix applies even
+ * when its version did not move; a directory of unknown provenance keeps the
+ * version gate, and git clones are skipped, so a plugin the user installed from
  * a URL is never overwritten by a store entry that happens to share its id.
  *
  * BEFORE the server halves load, and that order is the whole point: a plugin's
@@ -283,7 +285,10 @@ startWaitingRuntime();
 try {
   const synced = await syncBundledPlugins();
   for (const item of synced.updated) {
-    console.log(`[kabmo] plugins:        synced ${item.pluginId} ${item.from} → ${item.to}`);
+    // A content-only sync has no version to show, and printing `1.0.0 → 1.0.0`
+    // would read as a no-op when a shipped fix actually landed.
+    const span = item.contentOnly ? `${item.to} (content changed, version unchanged)` : `${item.from} → ${item.to}`;
+    console.log(`[kabmo] plugins:        synced ${item.pluginId} ${span}`);
     if (item.warning) console.error(`[plugins] ${item.pluginId}: rebuild after sync failed — ${item.warning}`);
   }
   for (const failure of synced.failed) console.error(`[plugins] ${failure.pluginId}: bundled sync failed — ${failure.error}`);

package/src/server/lib/bundler/titlebar-css.test.ts

@@ -50,11 +50,21 @@ describe('window-drag contract', () => {
   /**
    * The shell's hit test starts at the element under the pointer and walks up.
    * A header without the attribute is a header that cannot move the window.
+   *
+   * EVERY header that can be the window's top strip is listed, not just the
+   * desktop pair. A desktop shell window may be narrower than `App`'s 768px
+   * layout breakpoint (all three shells allow 720px), so the phone layout's
+   * headers are title bars too — and the mobile ones were missing the attribute
+   * entirely, which on macOS left a narrowed window with no draggable strip in
+   * its main screen and no way to move it.
    */
-  test('both title-bar headers carry data-drag-region', () => {
+  test('every title-bar header carries data-drag-region', () => {
     for (const path of [
       'src/client/components/layout/desktop-layout/TopNavbar.tsx',
       'src/client/components/layout/session-sidebar/Header.tsx',
+      'src/client/components/mobile/mobile-main-view/Header.tsx',
+      'src/client/components/mobile/mobile-session-sidebar/Header.tsx',
+      'src/client/components/mobile/RightSidebar.tsx',
     ]) {
       const file = source(path);
       expect(file).toContain('dragRegionProps()');
@@ -63,6 +73,37 @@ describe('window-drag contract', () => {
     expect(source('src/client/lib/desktop/titlebar.ts')).toContain("'data-drag-region'");
   });
 
+  /**
+   * The phone headers reserve the shell's own inset, not only the PWA's.
+   *
+   * `titlebarPaddingLeft` reads `env(titlebar-area-x)`, which a native WKWebView
+   * never defines — so the shell's 76px of traffic lights has to come from
+   * `titlebarInsetLeft`, the helper the desktop headers already use. Without it
+   * the phone header's hamburger and wordmark sat UNDER the traffic lights.
+   */
+  test('the phone headers use the shell inset', () => {
+    for (const path of [
+      'src/client/components/mobile/mobile-main-view/Header.tsx',
+      'src/client/components/mobile/mobile-session-sidebar/Header.tsx',
+      'src/client/components/mobile/RightSidebar.tsx',
+    ]) {
+      expect(source(path)).toContain('titlebarInsetLeft(');
+    }
+  });
+
+  /**
+   * A header marked as a drag region makes its controls drag handles unless
+   * they say otherwise — `app-region` INHERITS (WebView2's spec, enforced by
+   * Chromium 152), and a drag handle swallows the click.
+   */
+  test('a drag-region header marks its controls no-drag', () => {
+    const pairs: Array<[string, string]> = [
+      ['src/client/components/mobile/RightSidebar.tsx', 'titlebar-no-drag'],
+      ['src/client/components/common/header-controls/index.tsx', 'titlebar-no-drag'],
+    ];
+    for (const [path, marker] of pairs) expect(source(path)).toContain(marker);
+  });
+
   /** The PWA keeps its drag region: the property has to reach the browser. */
   test('the webkit property survives the bundle', async () => {
     const out = await build(`

package/src/server/lib/db/schema.ts

@@ -18,6 +18,7 @@ import { ensureScheduleSchema } from '@/server/lib/schedule/schema.server';
 import { ensureWaitingSchema } from '@/server/lib/waiting/schema.server';
 import { ensurePluginSchema } from '@/server/lib/plugins/schema.server';
 import { ensureModelRolePresetSchema } from '@/server/lib/model-roles/schema.server';
+import { ensureWorktreeSchema } from '@/server/lib/db/worktree-registry.server';
 import { migrateWorkspaceFolderColumns } from '@/shared/lib/workspace/schema-migrations';
 import { migrateSessionStreamStateColumns } from '@/shared/lib/omp/session/schema-migrations';
 
@@ -112,6 +113,9 @@ export async function initSchema(db: DbClient): Promise<void> {
   await ensurePluginSchema(db);
   // Named model-role presets (the role editor's preset picker).
   await ensureModelRolePresetSchema(db);
+  // Worktree registry: the ref each worktree branched from, and the identity
+  // cache that keys its folder.
+  await ensureWorktreeSchema(db);
 
   await db.exec(`
     CREATE TABLE IF NOT EXISTS files (

package/src/server/lib/db/worktree-registry.server.ts

@@ -0,0 +1,91 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * The `worktrees` table: one row per worktree Kabmo created.
+ *
+ * Everything a worktree row shows is read from git — except two things this
+ * table is the only home for:
+ *
+ *  - **`start_ref`**, the ref the branch was created from. `aheadOfStart` gates
+ *    the delete dialog's branch checkbox, and git cannot answer it later: the
+ *    branch has moved on, and for an existing-branch worktree there was no start
+ *    ref at all.
+ *  - **`project_id`**, the repository's identity, which is what the default
+ *    root is keyed by. It is a CACHE, not a derivation result: the derivation
+ *    moves when a repository gains an unrelated root commit (see
+ *    `worktree/project-id.ts`), so a stored value always wins.
+ */
+
+import type { DbClient } from '@/server/lib/db/client';
+
+const WORKTREE_SCHEMA_SQL = `
+  CREATE TABLE IF NOT EXISTS worktrees (
+    path TEXT PRIMARY KEY,
+    primary_root TEXT NOT NULL,
+    project_id TEXT NOT NULL,
+    branch TEXT NOT NULL,
+    start_ref TEXT NOT NULL DEFAULT '',
+    created_at TEXT NOT NULL
+  );
+  CREATE INDEX IF NOT EXISTS idx_worktrees_primary ON worktrees (primary_root);
+`;
+
+export interface WorktreeRow {
+  path: string;
+  primary_root: string;
+  project_id: string;
+  branch: string;
+  start_ref: string;
+  created_at: string;
+}
+
+/** Idempotent: the worktree registry, created on every database open. */
+export async function ensureWorktreeSchema(db: DbClient): Promise<void> {
+  await db.exec(WORKTREE_SCHEMA_SQL);
+}
+
+/**
+ * The identity cache: the project id already recorded for this repository.
+ * `LIMIT 1` because every row of one repository carries the same value.
+ */
+export async function worktreeIdentityFor(db: DbClient, primaryRoot: string): Promise<string | null> {
+  try {
+    const row = await db.get<{ project_id: string }>(
+      'SELECT project_id FROM worktrees WHERE primary_root = ? LIMIT 1',
+      [primaryRoot],
+    );
+    return typeof row?.project_id === 'string' && row.project_id ? row.project_id : null;
+  } catch {
+    // A database that cannot answer is not a reason to refuse the operation:
+    // the derivation still gives a usable key.
+    return null;
+  }
+}
+
+export async function worktreeRowFor(db: DbClient, worktreePath: string): Promise<WorktreeRow | undefined> {
+  return db.get<WorktreeRow>('SELECT * FROM worktrees WHERE path = ?', [worktreePath]);
+}
+
+export async function listWorktreeRows(db: DbClient, primaryRoot: string): Promise<WorktreeRow[]> {
+  return db.all<WorktreeRow>('SELECT * FROM worktrees WHERE primary_root = ?', [primaryRoot]);
+}
+
+export async function putWorktreeRow(db: DbClient, row: WorktreeRow): Promise<void> {
+  await db.run(
+    `INSERT INTO worktrees (path, primary_root, project_id, branch, start_ref, created_at)
+     VALUES (?, ?, ?, ?, ?, ?)
+     ON CONFLICT(path) DO UPDATE SET
+       primary_root = excluded.primary_root,
+       project_id = excluded.project_id,
+       branch = excluded.branch,
+       start_ref = excluded.start_ref`,
+    [row.path, row.primary_root, row.project_id, row.branch, row.start_ref, row.created_at],
+  );
+}
+
+export async function removeWorktreeRow(db: DbClient, worktreePath: string): Promise<void> {
+  await db.run('DELETE FROM worktrees WHERE path = ?', [worktreePath]);
+}

package/src/server/lib/fs/canonical.ts

@@ -0,0 +1,52 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Canonical paths and containment for filesystem work.
+ *
+ * Two traps this exists to close, both measured:
+ *
+ *  - **A spelling difference is not a difference.** On macOS git prints
+ *    `/private/tmp/...` for a directory the caller typed as `/tmp/...`, and
+ *    `path.resolve` alone does not reconcile them. A worktree compared against
+ *    its own entry answered "not inside", so the session badge silently never
+ *    appeared.
+ *  - **A missing path cannot be `realpath`'d at all** — and that is exactly the
+ *    `missing` worktree, whose directory was removed outside Kabmo. Resolving
+ *    the nearest existing ANCESTOR and re-appending the tail is what lets such a
+ *    worktree still be matched against the entry git keeps listing.
+ *
+ * Everything that compares two paths goes through here; `isWithinRoot` in
+ * `lib/fs/root.ts` stays the raw prefix test it always was.
+ */
+
+import path from 'path';
+import { realpath } from 'fs/promises';
+
+/** Absolute, symlink-resolved, no trailing separator. */
+export async function canonicalPath(target: string): Promise<string> {
+  const absolute = path.resolve(target).replace(/\/+$/, '');
+  const pending: string[] = [];
+  let cursor = absolute;
+  while (true) {
+    try {
+      const resolved = (await realpath(cursor)).replace(/\/+$/, '');
+      return pending.length > 0 ? [resolved, ...pending].join(path.sep) : resolved;
+    } catch {
+      const parent = path.dirname(cursor);
+      // The whole ancestor chain is gone (or this is the filesystem root): the
+      // `..`-folded path is the best answer that exists.
+      if (parent === cursor) return absolute;
+      pending.unshift(path.basename(cursor));
+      cursor = parent;
+    }
+  }
+}
+
+/** True when `target` is `root` itself or lies inside it. Both are canonicalized. */
+export async function pathHolds(root: string, target: string): Promise<boolean> {
+  const [canonicalRoot, canonicalTarget] = await Promise.all([canonicalPath(root), canonicalPath(target)]);
+  return canonicalTarget === canonicalRoot || canonicalTarget.startsWith(`${canonicalRoot}${path.sep}`);
+}