@kabmo-labs/kabmo 0.7.0 → 0.8.0

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 { 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 runGit(['rev-parse', '--is-inside-work-tree'], { cwd: input.projectPath });
+  if (insideWorkTree.exitCode !== 0 || insideWorkTree.stdout.trim() !== 'true') {
+    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;
+}

package/src/server/lib/omp/session/sidebar-data.canonical.test.ts

@@ -0,0 +1,155 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * A workspace folder finds its sessions through a CANONICAL path, not through
+ * the spelling the folder was registered under.
+ *
+ * `resolveRootsByCwd` runs every session's cwd through `resolveProjectRoot`,
+ * which realpaths it, so the bucket key is canonical. A folder row holds the
+ * spelling the user's path was registered with. On macOS those differ for
+ * anything under `/var` (a symlink to `/private/var`), which is where every
+ * temp directory lives — measured: a real-mode workspace in a temp directory
+ * listed ZERO sessions, and the worktree badge could never appear because the
+ * session was not even in the folder it belongs to.
+ *
+ * The symlink here is created by the test rather than borrowed from
+ * `os.tmpdir()`, because on Linux the two spellings are identical and a
+ * platform-shaped fixture would pass with the fix removed.
+ */
+
+import { afterAll, afterEach, beforeAll, beforeEach, describe, expect, test } from 'bun:test';
+import fs from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import { getDb } from '@/server/db.server';
+import { loadSidebarStructure } from '@/server/lib/omp/session/sidebar-data.server';
+import { invalidateOmpSidebarData } from '@/server/lib/omp/session/reader';
+import { clearSessionFileCaches } from '@/server/lib/omp/session/files';
+import { isolateDb, releaseDb } from '@/test-support/isolated-db';
+import { removeDir } from '@/test-support/remove-dir';
+
+const saved = {
+  agentDir: Bun.env.PI_CODING_AGENT_DIR,
+  xdg: Bun.env.XDG_DATA_HOME,
+  mock: Bun.env.MOCK,
+  sync: Bun.env.SYNC_WORKSPACE,
+};
+
+let root = '';
+let sessionsRoot = '';
+/** The directory a session actually ran in — what the scan resolves to. */
+let realProject = '';
+/** A symlink to it, which is how the folder is registered. */
+let linkedProject = '';
+
+beforeAll(async () => {
+  root = await fs.promises.mkdtemp(join(tmpdir(), 'omc-sidebar-canonical-'));
+  const agent = join(root, 'agent');
+  sessionsRoot = join(agent, 'sessions');
+  await fs.promises.mkdir(sessionsRoot, { recursive: true });
+
+  realProject = join(root, 'real-project');
+  await fs.promises.mkdir(realProject, { recursive: true });
+  linkedProject = join(root, 'linked-project');
+  await fs.promises.symlink(realProject, linkedProject, 'dir');
+
+  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;
+  Bun.env.MOCK = 'false';
+  Bun.env.SYNC_WORKSPACE = 'false';
+});
+
+afterAll(() => {
+  if (saved.agentDir === undefined) delete Bun.env.PI_CODING_AGENT_DIR;
+  else Bun.env.PI_CODING_AGENT_DIR = saved.agentDir;
+  if (saved.xdg === undefined) delete Bun.env.XDG_DATA_HOME;
+  else Bun.env.XDG_DATA_HOME = saved.xdg;
+  if (saved.mock === undefined) delete Bun.env.MOCK;
+  else Bun.env.MOCK = saved.mock;
+  if (saved.sync === undefined) delete Bun.env.SYNC_WORKSPACE;
+  else Bun.env.SYNC_WORKSPACE = saved.sync;
+  removeDir(root);
+});
+
+beforeEach(async () => {
+  await isolateDb();
+  // The sessions root is shared by the file, so each case starts from an empty
+  // one: a file left by a previous case would be listed by the next, which is
+  // what made the first run of this suite fail.
+  await fs.promises.rm(join(sessionsRoot, 'project'), { recursive: true, force: true });
+  invalidateOmpSidebarData();
+  clearSessionFileCaches();
+});
+
+afterEach(async () => {
+  await releaseDb();
+});
+
+/** One session file whose cwd is the CANONICAL spelling, as omp would record it. */
+async function writeSession(id: string, cwd: string): Promise<void> {
+  const dir = join(sessionsRoot, 'project');
+  await fs.promises.mkdir(dir, { recursive: true });
+  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: 'hello from the canonical bucket' },
+    }),
+  ];
+  await Bun.write(join(dir, `${id}.jsonl`), `${lines.join('\n')}\n`);
+}
+
+/** A workspace folder row bound to `projectPath`. */
+async function registerFolder(projectPath: string): Promise<number> {
+  const db = await getDb();
+  await db.run('INSERT INTO workspace_folders (name, project_path) VALUES (?, ?)', ['ws', projectPath]);
+  const row = await db.get<{ id: number }>('SELECT id FROM workspace_folders ORDER BY id DESC LIMIT 1');
+  return Number(row?.id);
+}
+
+describe('sidebar folders resolve sessions through a canonical path', () => {
+  test('a folder registered under a symlinked spelling lists the sessions that ran in its target', async () => {
+    // The session's cwd is the REAL directory; the folder names the symlink.
+    // Without the canonical bucket key this is an empty folder.
+    await writeSession('canonical-hit', realProject);
+    await registerFolder(linkedProject);
+
+    const payload = await loadSidebarStructure();
+    const folder = payload.folders.find((entry) => entry.project_path === linkedProject);
+
+    expect(folder).toBeDefined();
+    expect(folder?.sessions.map((session) => session.id)).toEqual(['canonical-hit']);
+  });
+
+  test('a folder registered under the real spelling keeps listing its sessions', async () => {
+    // The control: the fallback to the raw spelling must not be the only path
+    // that works, or the fix would trade one empty folder for another.
+    await writeSession('canonical-plain', realProject);
+    await registerFolder(realProject);
+
+    const payload = await loadSidebarStructure();
+    const folder = payload.folders.find((entry) => entry.project_path === realProject);
+
+    expect(folder?.sessions.map((session) => session.id)).toEqual(['canonical-plain']);
+  });
+
+  test('a session in an unrelated directory stays out of the folder', async () => {
+    const other = join(root, 'other-project');
+    await fs.promises.mkdir(other, { recursive: true });
+    await writeSession('canonical-elsewhere', other);
+    await registerFolder(linkedProject);
+
+    const payload = await loadSidebarStructure();
+    const folder = payload.folders.find((entry) => entry.project_path === linkedProject);
+
+    expect(folder?.sessions).toEqual([]);
+  });
+});

package/src/server/lib/omp/session/sidebar-data.server.ts

@@ -26,6 +26,9 @@ import { loadStreamStates, type SessionRunModel } from '@/shared/lib/omp/session
 import { healStaleStreamStatuses } from '@/shared/lib/omp/session/stream-heal.server';
 import { getAwaitingInputSessionIds, getLiveRunSessionIds, listRpcSessions } from '@/server/lib/omp/rpc/session-registry';
 import type { SessionItemData, SessionSortOption, WorkspaceFolderData } from '@/shared/types';
+import { sessionWorktreeMap } from '@/server/lib/fs/worktree/topology';
+import { canonicalPath } from '@/server/lib/fs/canonical';
+import type { SessionWorktreeInfo } from '@/shared/lib/workspace/worktree/types';
 import type { OmpSession } from '@/shared/types/omp/session';
 
 /** What `GET /api/sessions/list` returns and sidebars consume. */
@@ -236,11 +239,30 @@ async function buildRealFolders(folderRows: FolderRow[], archivedIds: Set<string
 
   return Promise.all(folderRows.map(async (folder) => {
     const root = folder.project_path ?? '';
-    const rootSessions: OmpSession[] = root ? sessionsByRoot.get(root) ?? [] : [];
+    // The bucket key is CANONICAL: `resolveRootsByCwd` resolves each session's
+    // cwd through `resolveProjectRoot`, which realpaths it, while a folder row
+    // holds the spelling the user's path was registered under. On macOS those
+    // differ for anything under `/var` (a symlink to `/private/var`), so a
+    // project in a temp directory or under a symlinked home listed ZERO sessions
+    // — measured: every real-mode session was missing from the sidebar, and the
+    // worktree badge could never appear because the session was not even in the
+    // folder it belongs to.
+    const rootKey = root ? await canonicalPath(root) : '';
+    const rootSessions: OmpSession[] = root
+      ? (sessionsByRoot.get(rootKey) ?? sessionsByRoot.get(root) ?? [])
+      : [];
+    // One topology read per repository, however many sessions it has. A chat in
+    // the checkout itself is absent from this map, which is exactly what the row
+    // draws (an ordinary row with no badge).
+    const worktrees = await sessionWorktreeMap(
+      root,
+      rootSessions.map((session) => ({ id: session.id, cwd: session.cwd })),
+    );
     const folderSessions = await Promise.all(rootSessions.map(async (session: OmpSession) => {
       const hasSub = session.path
         ? await sessionHasSubagents(session.path, session.modified)
         : false;
+      const worktree: SessionWorktreeInfo | undefined = worktrees.get(session.id);
       return {
         id: session.id,
         folder_id: folder.id,
@@ -250,6 +272,11 @@ async function buildRealFolders(folderRows: FolderRow[], archivedIds: Set<string
         is_active: 0,
         is_archived: archivedIds.has(String(session.id)) ? 1 : 0,
         hasSubagents: hasSub,
+        // The session's own working directory, and the worktree it resolves to
+        // when that cwd is a linked checkout. Both travel so no client and no
+        // plugin has to ask git.
+        cwd: session.cwd,
+        ...(worktree ? { worktree } : {}),
       };
     }));
     return {

package/src/server/lib/panels/local-edits.server.ts

@@ -124,3 +124,36 @@ export function changedPaths(baseline: TrackedFileHashes, current: TrackedFileHa
   }
   return [...changed].sort();
 }
+
+/**
+ * Whether a recorded baseline still describes this install.
+ *
+ * A baseline can only be evidence about the user while it agrees with what is on
+ * disk, and the test is exact and one-directional:
+ *
+ * > wherever the install and the store AGREE, the baseline must agree too.
+ *
+ * Kabmo is the only thing that writes store content into an install, and it
+ * re-takes the baseline when it does — so a path where the install already
+ * equals the store while the baseline says otherwise proves the baseline
+ * describes a copy this install never had. That is not hypothetical: the product
+ * rename rewrote every bundled file while an older baseline was still recorded,
+ * and reading that baseline as "the user edited 24 files" made the update refuse
+ * forever, with remove-and-reinstall as the only way out (measured).
+ *
+ * The converse is deliberately NOT required, so a genuine edit stays detectable:
+ * a user edit makes the install differ from the store, so those paths are
+ * skipped here and the remaining ones still vouch for the baseline. The edit is
+ * then reported by `changedPaths` rather than overwritten.
+ */
+export function baselineDescribesInstall(
+  baseline: TrackedFileHashes,
+  install: TrackedFileHashes,
+  store: TrackedFileHashes,
+): boolean {
+  for (const [path, hash] of Object.entries(install)) {
+    if (hash !== store[path]) continue;
+    if (baseline[path] !== hash) return false;
+  }
+  return true;
+}