@kabmo-labs/kabmo 0.7.0 → 0.8.0

package/src/server/routes/worktrees/list.ts

@@ -0,0 +1,124 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * GET /api/worktrees — the worktrees of one project, with the facts a row shows.
+ *
+ * Deliberately NOT on the realtime `git:` topic: that payload is republished on
+ * every tool call, and this read costs a `git status` per worktree. It is opened
+ * by hand (Settings → Projects → Worktrees, and the delete dialog), exactly the
+ * reasoning `git-repo-details.ts` records for keeping the repo modal off it.
+ *
+ * `sessions` counts chats whose cwd is inside a worktree, from the same topology
+ * the sidebar uses — so the number a row shows is the number of rows the user
+ * can see under it.
+ */
+
+import path from 'node:path';
+import { json } from '@/server/lib/remix-compat';
+import type { LoaderFunctionArgs } from '@/server/lib/remix-compat';
+import { getDataDir } from '@/server/lib/lifecycle/paths';
+import { resolveProjectRoot } from '@/server/lib/omp/core/worktree';
+import { listSessionFiles } from '@/server/lib/omp/session/files';
+import { scanSessionInfoCached } from '@/server/lib/omp/session/files';
+import { canonicalPath } from '@/server/lib/fs/canonical';
+import { worktreeIdentityFor, listWorktreeRows } from '@/server/lib/db/worktree-registry.server';
+import { dirtyCount, commitsAheadOf } from '@/server/lib/fs/worktree/remove';
+import { listWorktrees } from '@/server/lib/fs/worktree/list';
+import {
+  defaultWorktreeRoot,
+  resolveConfiguredWorktreeRoot,
+} from '@/server/lib/fs/worktree/location';
+import { readWorktreeSettings } from '@/server/lib/fs/worktree/settings.server';
+import { resolveProjectId } from '@/server/lib/fs/worktree/project-id';
+import { getDb } from '@/server/db.server';
+import { isMock } from '@/server/routes/worktrees/shared';
+import { mockRefusal, resolveWorktreeProject, worktreeFailureResponse } from '@/server/routes/worktrees/shared';
+import type { WorktreeInfo, WorktreeListPayload } from '@/shared/lib/workspace/worktree/types';
+
+export async function loader({ request }: LoaderFunctionArgs) {
+  if (isMock()) return mockRefusal();
+
+  const url = new URL(request.url);
+  const resolved = await resolveWorktreeProject(url.searchParams.get('root'), url.searchParams.get('folderId'));
+  if (resolved.error) return resolved.error;
+  const root = resolved.root as string;
+
+  try {
+    const db = await getDb();
+    const primaryRoot = await resolveProjectRoot(root);
+    const settings = await readWorktreeSettings();
+    const projectId = await resolveProjectId(primaryRoot, (candidate) => worktreeIdentityFor(db, candidate));
+    const base = resolveConfiguredWorktreeRoot(settings.directory, primaryRoot)
+      ?? defaultWorktreeRoot(getDataDir(), projectId);
+
+    const entries = await listWorktrees(primaryRoot);
+    const [rows, sessionCwds] = await Promise.all([
+      listWorktreeRows(db, primaryRoot),
+      // Every tree that can be counted, not just the repository: a worktree does
+      // NOT have to live inside it. Kabmo's own default puts one under the data
+      // directory (`<data>/worktrees/<projectId>/<name>`), so a `primaryRoot`
+      // prefix test counted ZERO sessions for every worktree at the default
+      // location — the number the delete dialog warns with.
+      sessionCwdsUnder([primaryRoot, ...entries.map((entry) => entry.path)]),
+    ]);
+    const rowByPath = new Map(rows.map((row) => [row.path, row]));
+
+    const worktrees: WorktreeInfo[] = [];
+    for (const entry of entries) {
+      const row = rowByPath.get(entry.path);
+      const dirty = entry.isPrimary ? 0 : await dirtyCount(entry.path).catch(() => 0);
+      const ahead = entry.isPrimary
+        ? 0
+        : (await commitsAheadOf(primaryRoot, row?.start_ref ?? '', entry.branch)) ?? 0;
+      worktrees.push({
+        path: entry.path,
+        branch: entry.branch,
+        head: entry.head,
+        detached: entry.detached,
+        missing: entry.missing,
+        isPrimary: entry.isPrimary,
+        dirty,
+        aheadOfStart: ahead,
+        startRef: row?.start_ref ?? '',
+        sessions: sessionCwds.filter((cwd) => cwd === entry.path || cwd.startsWith(`${entry.path}${path.sep}`)).length,
+      });
+    }
+
+    const payload: WorktreeListPayload = { worktrees, base, isRepo: true };
+    return json(payload);
+  } catch (error) {
+    // A failed listing is REPORTED, never substituted with an empty list: "no
+    // worktrees" and "git could not answer" are different answers, and only one
+    // of them means the user has nothing there.
+    return worktreeFailureResponse(error, 500);
+  }
+}
+
+/**
+ * Every session's recorded cwd, canonicalized, restricted to the trees that can
+ * be counted — the primary checkout and each worktree.
+ *
+ * Both sides are canonicalized, for the same reason `canonicalPath` exists: the
+ * recorded cwd is the spelling the agent was spawned with while a worktree path
+ * comes back realpath'd from git, and on macOS those differ for anything under
+ * `/var` (a symlink to `/private/var`) — a raw prefix test would then count zero
+ * for a worktree that is right there.
+ */
+async function sessionCwdsUnder(roots: string[]): Promise<string[]> {
+  const files = await listSessionFiles();
+  const infos = await Promise.all(files.map((file) => scanSessionInfoCached(file)));
+  const canonicalRoots = [...new Set(await Promise.all(roots.map((root) => canonicalPath(root))))];
+  const cwds: string[] = [];
+  const seen = new Set<string>();
+  for (const info of infos) {
+    if (!info?.cwd || seen.has(info.cwd)) continue;
+    seen.add(info.cwd);
+    const cwd = await canonicalPath(info.cwd);
+    if (!canonicalRoots.some((root) => cwd === root || cwd.startsWith(`${root}${path.sep}`))) continue;
+    cwds.push(cwd);
+  }
+  return cwds;
+}

package/src/server/routes/worktrees/remove.ts

@@ -0,0 +1,102 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * DELETE /api/worktrees — remove one worktree.
+ *
+ * Order, and it is the point: stop the live children, archive and delete their
+ * sessions, THEN remove the directory. The reverse — which is what a plain
+ * `git worktree remove` alone does — leaves a child whose cwd no longer exists,
+ * and `resolveSpawnCwd` then quietly runs that session in the server's own
+ * directory: a chat the user deleted, alive somewhere else.
+ *
+ * The dirty refusal happens AFTER the sessions are stopped, so a refusal leaves a
+ * worktree the user can still see and retry rather than a half-deleted state.
+ */
+
+import { json } from '@/server/lib/remix-compat';
+import type { ActionFunctionArgs } from '@/server/lib/remix-compat';
+import { methodNotAllowed } from '@/server/lib/route-adapter';
+import { getDataDir } from '@/server/lib/lifecycle/paths';
+import { getDb } from '@/server/db.server';
+import { emitRealtimeSignal } from '@/server/lib/realtime/signals.server';
+import { pathHolds } from '@/server/lib/fs/canonical';
+import { removeWorktreeRow, worktreeRowFor } from '@/server/lib/db/worktree-registry.server';
+import { removeWorktree } from '@/server/lib/fs/worktree/remove';
+import { invalidateWorktreeTopology } from '@/server/lib/fs/worktree/topology';
+import { resolveProjectRoot } from '@/server/lib/omp/core/worktree';
+import { listRpcSessions } from '@/server/lib/omp/rpc/session-registry';
+import { removeSession } from '@/server/lib/omp/session/delete-flow.server';
+import { isMock, mockRefusal, resolveWorktreeProject, worktreeFailureResponse } from '@/server/routes/worktrees/shared';
+
+interface RemoveBody {
+  path?: unknown;
+  deleteBranch?: unknown;
+}
+
+/**
+ * Stop and delete every session whose cwd is inside `worktreePath`.
+ *
+ * A session this process does not manage has no child to stop — its transcript
+ * is removed the same way, and the owning instance learns on its next spawn
+ * (`resolveSpawnCwd` finds no directory and the row is already gone).
+ */
+async function stopSessionsIn(worktreePath: string): Promise<string[]> {
+  const handled: string[] = [];
+  for (const session of liveSessions()) {
+    if (!(await pathHolds(worktreePath, session.cwd))) continue;
+    // `removeSession` IS the single-delete sequence: pending-id refusal, id
+    // shape, the busy-child 409, `destroyAndWait`, then the purge. Repeating any
+    // of it here is how the batch path would drift from `DELETE /api/sessions/:id`.
+    const removal = await removeSession(session.id);
+    if (removal.ok) handled.push(session.id);
+  }
+  return handled;
+}
+
+/** Live wrappers, as the registry reports them. */
+function liveSessions(): { id: string; cwd: string }[] {
+  return listRpcSessions().map((session) => ({ id: session.sessionId, cwd: session.cwd }));
+}
+
+export async function action({ request }: ActionFunctionArgs) {
+  if (request.method !== 'DELETE') return methodNotAllowed({ request, params: {} });
+  if (isMock()) return mockRefusal();
+
+  const url = new URL(request.url);
+  const resolved = await resolveWorktreeProject(url.searchParams.get('root'), url.searchParams.get('folderId'));
+  if (resolved.error) return resolved.error;
+  const projectPath = resolved.root as string;
+
+  const body = (await request.json().catch(() => ({}))) as RemoveBody;
+  const worktreePath = typeof body.path === 'string' ? body.path.trim() : '';
+  if (!worktreePath) {
+    return json({ error: 'path is required', code: 'invalid_name', field: 'location' }, { status: 400 });
+  }
+
+  const db = await getDb();
+  try {
+    const primaryRoot = await resolveProjectRoot(projectPath);
+    const removed = await removeWorktree(
+      {
+        worktreePath,
+        projectPath,
+        deleteBranch: body.deleteBranch === true,
+        managedRoot: `${getDataDir()}/worktrees`,
+        stopSessions: stopSessionsIn,
+      },
+      {
+        rowFor: (candidate) => worktreeRowFor(db, candidate),
+        removeRow: (candidate) => removeWorktreeRow(db, candidate),
+      },
+    );
+    await invalidateWorktreeTopology(primaryRoot);
+    emitRealtimeSignal('sidebar-structure');
+    emitRealtimeSignal('workspace-dirty');
+    return json(removed);
+  } catch (error) {
+    return worktreeFailureResponse(error);
+  }
+}

package/src/server/routes/worktrees/routes.test.ts

@@ -0,0 +1,309 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * The `/api/worktrees` routes, end to end over a real repository.
+ *
+ * What a unit test on the modules cannot show, and what these cases are for:
+ *
+ *  - the LIST payload carries every fact a row draws, from one read;
+ *  - a create answers with the worktree it made, and the next list shows it —
+ *    the topology cache invalidation is what makes "next list" true;
+ *  - a DELETE takes the path in its BODY (a path has separators) and answers the
+ *    branch verdict rather than a bare success;
+ *  - MOCK refuses, because a demo install has no repository to make one in.
+ */
+
+import { afterAll, afterEach, beforeAll, beforeEach, describe, expect, test } from 'bun:test';
+import { mkdirSync, mkdtempSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { getDb } from '@/server/db.server';
+import { loader as listLoader } from '@/server/routes/worktrees/list';
+import { action as createAction, validateAction } from '@/server/routes/worktrees/create';
+import { action as removeAction } from '@/server/routes/worktrees/remove';
+import { invalidateWorktreeTopology } from '@/server/lib/fs/worktree/topology';
+import { clearSessionFileCaches } from '@/server/lib/omp/session/files';
+import { isolateDb, releaseDb } from '@/test-support/isolated-db';
+import { removeDir } from '@/test-support/remove-dir';
+
+const GIT_ENV = {
+  ...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 }).stdout.toString();
+}
+
+let workRoot: string;
+let repo: string;
+/** Where the session files live, so a count can be observed without omp. */
+let sessionsRoot: string;
+const saved = {
+  MOCK: Bun.env.MOCK,
+  SYNC_WORKSPACE: Bun.env.SYNC_WORKSPACE,
+  agentDir: Bun.env.PI_CODING_AGENT_DIR,
+  xdg: Bun.env.XDG_DATA_HOME,
+  dataDir: Bun.env.KABMO_DATA_DIR,
+};
+
+/**
+ * Call a route module the way the adapter does — with `params`, which every
+ * Remix-shaped handler declares even when its path has no parameter.
+ */
+async function call(
+  handler: (args: { request: Request; params: Record<string, string> }) => unknown,
+  url: string,
+  init?: RequestInit,
+): Promise<{ status: number; body: Record<string, unknown> }> {
+  const response = (await handler({ request: new Request(url, init), params: {} })) as Response;
+  return { status: response.status, body: (await response.json()) as Record<string, unknown> };
+}
+
+/** Put an env var back, or unset it when the file started without one. */
+function restoreEnv(name: string, value: string | undefined): void {
+  if (value === undefined) delete Bun.env[name];
+  else Bun.env[name] = value;
+}
+
+/** One session file whose cwd is `cwd`, as the agent would record it. */
+function writeSession(id: string, cwd: string): void {
+  const lines = [
+    JSON.stringify({ type: 'session', id, cwd, timestamp: '2026-10-23T00:00:00.000Z' }),
+    JSON.stringify({
+      type: 'message',
+      id: `${id}-m1`,
+      parentId: null,
+      timestamp: '2026-10-23T00:00:01.000Z',
+      message: { role: 'user', content: 'where am I' },
+    }),
+  ];
+  writeFileSync(join(sessionsRoot, 'project', `${id}.jsonl`), `${lines.join('\n')}\n`);
+}
+
+/** The `worktrees` array of a list payload, narrowed once. */
+function worktreesOf(body: Record<string, unknown>): Array<Record<string, unknown>> {
+  const list = body.worktrees;
+  return Array.isArray(list) ? (list as Array<Record<string, unknown>>) : [];
+}
+
+const base = (): string => `http://localhost/api/worktrees?root=${encodeURIComponent(repo)}`;
+
+beforeAll(() => {
+  workRoot = mkdtempSync(join(tmpdir(), 'kabmo-worktree-routes-'));
+  repo = join(workRoot, 'repo');
+  mkdirSync(repo, { recursive: true });
+  writeFileSync(join(repo, '.gitignore'), 'node_modules\n');
+  mkdirSync(join(repo, 'node_modules', 'dep'), { recursive: true });
+  writeFileSync(join(repo, 'node_modules', 'dep', 'index.js'), 'module.exports = {};\n');
+  writeFileSync(join(repo, 'readme.md'), 'hello\n');
+  git(repo, 'init', '-q', '-b', 'main', '.');
+  git(repo, 'add', '-A');
+  git(repo, 'commit', '-q', '-m', 'base');
+
+  // A sessions root of this file's own: the worktree count reads it, and
+  // without the override it would scan the developer's real `~/.omp/agent`.
+  const agent = join(workRoot, 'agent');
+  sessionsRoot = join(agent, 'sessions');
+  mkdirSync(join(sessionsRoot, 'project'), { recursive: true });
+  Bun.env.PI_CODING_AGENT_DIR = agent;
+  // XDG would redirect the sessions dir to $XDG_DATA_HOME/omp when it exists.
+  delete Bun.env.XDG_DATA_HOME;
+  // A worktree's default location is `<data>/worktrees/<projectId>/<name>`, so
+  // without this the suite writes into the developer's own `~/.kabmo`.
+  Bun.env.KABMO_DATA_DIR = join(workRoot, 'data');
+});
+
+beforeEach(async () => {
+  await isolateDb();
+  Bun.env.MOCK = 'false';
+  Bun.env.SYNC_WORKSPACE = 'false';
+  const db = await getDb();
+  await db.run('INSERT INTO workspace_folders (name, project_path) VALUES (?, ?)', ['proj', repo]);
+});
+
+afterEach(async () => {
+  await invalidateWorktreeTopology();
+  // The session-file caches are keyed on `globalThis` and this file writes
+  // session files, so a case that leaves one behind would be counted by the next.
+  clearSessionFileCaches();
+  await releaseDb();
+});
+
+afterAll(() => {
+  removeDir(workRoot);
+  // Explicitly mapped: the record's keys are not the env names, and an
+  // `Object.entries` restore would silently leave `PI_CODING_AGENT_DIR` pointed
+  // at a directory this file just deleted.
+  restoreEnv('MOCK', saved.MOCK);
+  restoreEnv('SYNC_WORKSPACE', saved.SYNC_WORKSPACE);
+  restoreEnv('PI_CODING_AGENT_DIR', saved.agentDir);
+  restoreEnv('XDG_DATA_HOME', saved.xdg);
+  restoreEnv('KABMO_DATA_DIR', saved.dataDir);
+});
+
+describe('GET /api/worktrees', () => {
+  test('lists the checkout with the facts a row draws', async () => {
+    const { status, body } = await call(listLoader, base());
+    expect(status).toBe(200);
+    expect(body.isRepo).toBe(true);
+    expect(String(body.base)).toContain('worktrees');
+    const primary = worktreesOf(body)[0] as Record<string, unknown>;
+    expect(primary.isPrimary).toBe(true);
+    expect(primary.branch).toBe('main');
+    expect(String(primary.head).length).toBeGreaterThan(0);
+    expect(primary.dirty).toBe(0);
+  });
+
+  test('counts a session running in a worktree that lives OUTSIDE the repository', async () => {
+    const created = await call(createAction, base(), {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({ mode: 'new', branch: 'wt/route-counted' }),
+    });
+    const path = String((created.body.worktree as Record<string, unknown>).path);
+    // The default location is under the data directory, not inside the checkout
+    // — which is the case a `primaryRoot` prefix test counted zero for.
+    expect(path.startsWith(repo)).toBe(false);
+
+    writeSession('route-counted-session', path);
+
+    const listed = await call(listLoader, base());
+    const row = worktreesOf(listed.body).find((entry) => entry.path === path);
+    // The number the delete dialog warns with: a chat is running here.
+    expect(row?.sessions).toBe(1);
+  });
+
+  test('a folder with no project binding is refused, not answered for the app root', async () => {
+    const { status, body } = await call(listLoader, 'http://localhost/api/worktrees');
+    expect(status).toBe(400);
+    expect(body.code).toBe('not_a_repo');
+  });
+
+  test('MOCK refuses — a demo install has no repository to read', async () => {
+    Bun.env.MOCK = 'true';
+    const { status, body } = await call(listLoader, base());
+    expect(status).toBe(409);
+    expect(body.code).toBe('mock_mode');
+  });
+});
+
+describe('POST /api/worktrees', () => {
+  test('creates one, carries the ignored build folder, and the next list shows it', async () => {
+    const created = await call(createAction, base(), {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({ mode: 'new', branch: 'wt/route-created' }),
+    });
+
+    expect(created.status).toBe(200);
+    const worktree = created.body.worktree as Record<string, unknown>;
+    expect(worktree.branch).toBe('wt/route-created');
+    // The carry is the one capability git does not provide; without it the new
+    // checkout cannot run the project.
+    const carried = worktree.carried as { copied: string[] };
+    expect(carried.copied).toContain('node_modules');
+
+    const listed = await call(listLoader, base());
+    const row = worktreesOf(listed.body).find((entry) => entry.branch === 'wt/route-created');
+    expect(row).toBeDefined();
+    expect(row?.isPrimary).toBe(false);
+    expect(row?.startRef).toBe('HEAD');
+  });
+
+  test('a refusal answers its code and field, so the dialog can mark the input', async () => {
+    const refused = await call(createAction, base(), {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({ mode: 'existing', branch: 'main' }),
+    });
+    expect(refused.status).toBe(400);
+    expect(refused.body.code).toBe('branch_in_use');
+    expect(refused.body.field).toBe('branch');
+  });
+
+  test('validate answers the same refusal without creating anything', async () => {
+    const result = await call(validateAction, base(), {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({ mode: 'new', branch: 'has space' }),
+    });
+    expect(result.status).toBe(400);
+    expect(result.body.ok).toBe(false);
+    const failures = result.body.failures as Array<{ code: string }>;
+    expect(failures[0]?.code).toBe('invalid_name');
+
+    // Nothing was created: the fixture repository is shared by this file, so the
+    // assertion names the branch rather than a count (a count would also pin how
+    // many earlier tests happened to leave behind).
+    const listed = await call(listLoader, base());
+    expect(worktreesOf(listed.body).some((entry) => entry.branch === 'has-space')).toBe(false);
+    expect(worktreesOf(listed.body).some((entry) => entry.branch === 'has space')).toBe(false);
+  });
+});
+
+describe('DELETE /api/worktrees', () => {
+  test('removes the worktree and its branch, and the list no longer shows it', async () => {
+    const created = await call(createAction, base(), {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({ mode: 'new', branch: 'wt/route-remove' }),
+    });
+    const path = String((created.body.worktree as Record<string, unknown>).path);
+
+    const removed = await call(removeAction, base(), {
+      method: 'DELETE',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({ path, deleteBranch: true }),
+    });
+    expect(removed.status).toBe(200);
+    expect(removed.body.removed).toBe(true);
+    expect(removed.body.branchDeleted).toBe(true);
+
+    const listed = await call(listLoader, base());
+    expect(worktreesOf(listed.body).some((entry) => entry.path === path)).toBe(false);
+  });
+
+  test('a missing path is refused by name, not by a crash', async () => {
+    const refused = await call(removeAction, base(), {
+      method: 'DELETE',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({}),
+    });
+    expect(refused.status).toBe(400);
+    expect(refused.body.code).toBe('invalid_name');
+  });
+
+  test('a dirty worktree is refused with 409 and its count, so a caller can tell a retry from a bad request', async () => {
+    const created = await call(createAction, base(), {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({ mode: 'new', branch: 'wt/route-dirty' }),
+    });
+    const path = String((created.body.worktree as Record<string, unknown>).path);
+    writeFileSync(join(path, 'scratch.txt'), 'not committed\n');
+
+    const refused = await call(removeAction, base(), {
+      method: 'DELETE',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({ path, deleteBranch: true }),
+    });
+    // 409: the request is well-formed and the tree is the obstacle — the same
+    // distinction `mock_mode` draws. A 400 here reads as "fix your request".
+    expect(refused.status).toBe(409);
+    expect(refused.body.code).toBe('dirty');
+    expect(Number(refused.body.count)).toBeGreaterThan(0);
+
+    // A refusal is not a partial removal.
+    const listed = await call(listLoader, base());
+    expect(worktreesOf(listed.body).some((entry) => entry.path === path)).toBe(true);
+  });
+});

package/src/server/routes/worktrees/shared.ts

@@ -0,0 +1,90 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * The worktree routes' shared plumbing: resolve the project, refuse in MOCK, and
+ * turn a `WorktreeError` into the JSON envelope the client already understands.
+ *
+ * Root resolution goes through `resolveRoot`, the security boundary every fs
+ * route uses — a client-supplied `root` is only honoured when it is the app
+ * root, a registered `project_path`, or (this feature) a worktree of one.
+ */
+
+import { json } from '@/server/lib/remix-compat';
+import { isMockMode } from '@/server/mock.server';
+import { getDb } from '@/server/db.server';
+import { resolveRoot } from '@/server/lib/fs/root';
+import { asWorktreeFailure } from '@/server/lib/fs/worktree/errors';
+import type { WorktreeFailure } from '@/shared/lib/workspace/worktree/types';
+
+/** A registered workspace's `project_path`, or null when the folder is unbound. */
+export async function projectPathForFolder(folderId: number | string | null): Promise<string | null> {
+  if (folderId === null || folderId === '') return null;
+  try {
+    const db = await getDb();
+    const row = await db.get<{ project_path: string | null }>(
+      'SELECT project_path FROM workspace_folders WHERE id = ?',
+      [Number(folderId)],
+    );
+    return row?.project_path ?? null;
+  } catch {
+    return null;
+  }
+}
+
+/** The project a request names: its own `root`, else the folder's binding. */
+export async function resolveWorktreeProject(
+  rawRoot: string | null | undefined,
+  folderId: string | null,
+): Promise<{ root: string | null; error?: Response }> {
+  const fromFolder = await projectPathForFolder(folderId);
+  const root = await resolveRoot(rawRoot || fromFolder, '');
+  if (!root) {
+    return {
+      root: null,
+      error: json(
+        {
+          error: 'Pick a workspace bound to a Git repository first.',
+          code: 'not_a_repo',
+        },
+        { status: 400 },
+      ),
+    };
+  }
+  return { root };
+}
+
+/**
+ * A worktree mutation in demo mode is refused rather than simulated: MOCK has no
+ * repository on disk, so a "successful" create would promise a folder that does
+ * not exist.
+ */
+export function mockRefusal(): Response {
+  return json(
+    { error: 'Worktrees need a real Git repository; Kabmo is running in demo mode.', code: 'mock_mode' },
+    { status: 409 },
+  );
+}
+
+/**
+ * A refusal's HTTP status, from what the refusal MEANS.
+ *
+ * `dirty` is a conflict with the tree's current state rather than a malformed
+ * request — the same distinction `session_not_running` and `mock_mode` draw with
+ * 409 — and a caller that retries after committing needs to tell the two apart
+ * without parsing the message.
+ */
+const REFUSAL_STATUS: Partial<Record<WorktreeFailure['code'], number>> = {
+  dirty: 409,
+};
+
+export function worktreeFailureResponse(error: unknown, status = 400): Response {
+  const failure = asWorktreeFailure(error);
+  return json({ error: failure.message, ...failure }, { status: REFUSAL_STATUS[failure.code] ?? status });
+}
+
+export function isMock(): boolean {
+  return isMockMode();
+}