@kabmo-labs/kabmo 0.7.0 → 0.9.0

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

@@ -0,0 +1,162 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * The `sidebar:activity` resolver, against a real sessions directory.
+ *
+ * The rules under test are the ones that keep this payload small enough to be
+ * republished per tool call:
+ *
+ *   - it carries ONLY sessions with a run in flight — every other row keeps the
+ *     stamp the structure gave it, which is why the structure does not have to
+ *     be re-scanned;
+ *   - a live run with no transcript yet contributes nothing (a fresh spawn:
+ *     omp writes the file only when the first assistant message settles);
+ *   - the stamp it reports is the newest ENTRY's timestamp, the same quantity
+ *     the structure ships as `updated_at`, so the client can compare them;
+ *   - the subagent flag is reported alongside, because a subagent's transcript
+ *     appears mid-run and lights the parent row's roster chevron.
+ *
+ * Driven through `localRuns()` rather than a stubbed registry: that set is the
+ * real "a run is in flight" source (the mock SSE stream uses it too), so the
+ * test exercises the same read `loadSidebarStatus` does.
+ */
+
+import { afterAll, afterEach, describe, expect, test } from 'bun:test';
+import fs from 'fs';
+import * as path from 'path';
+
+import { loadSidebarActivity } from '@/server/lib/omp/session/sidebar-activity.server';
+import { localRuns } from '@/server/lib/omp/session/local-runs.server';
+import { clearSessionFileCaches } from '@/server/lib/omp/session/files';
+import { SESSION_TITLE_SLOT_BYTES } from '@/server/lib/omp/session/files';
+
+const tempDirs: string[] = [];
+const previousAgentDir = process.env.PI_CODING_AGENT_DIR;
+
+/**
+ * Point the agent dir at a scratch tree, because `findSessionFileById` resolves
+ * through the real sessions root. `PI_CODING_AGENT_DIR` is read per call, so no
+ * module reload is needed — but the file caches are process-wide and keyed by
+ * path, so they are cleared before and after.
+ */
+function useAgentDir(): string {
+  const dir = fs.mkdtempSync(path.join(fs.realpathSync('/tmp'), 'kabmo-activity-'));
+  tempDirs.push(dir);
+  process.env.PI_CODING_AGENT_DIR = dir;
+  clearSessionFileCaches();
+  return dir;
+}
+
+/** A title slot line, exactly as omp writes it, so the scan reads a real file. */
+function titleSlot(title: string): string {
+  const raw = JSON.stringify({ type: 'title', title });
+  return raw + ' '.repeat(Math.max(0, SESSION_TITLE_SLOT_BYTES - 1 - raw.length));
+}
+
+interface SessionFixture {
+  id: string;
+  entries?: Array<{ type: string; timestamp?: string }>;
+  subagents?: string[];
+}
+
+/**
+ * Write one session file under `<agentDir>/sessions/<project>/`.
+ *
+ * The entries are minimal but carry the field the scan dates the file by (the
+ * newest entry's own `timestamp`), which is the whole quantity under test.
+ */
+function writeSession(agentDir: string, fixture: SessionFixture): string {
+  const projectDir = path.join(agentDir, 'sessions', '-tmp-project');
+  fs.mkdirSync(projectDir, { recursive: true });
+  const file = path.join(projectDir, `2026-10-24T00-00-00-000Z_${fixture.id}.jsonl`);
+  const lines = [
+    titleSlot(`Session ${fixture.id}`),
+    JSON.stringify({ type: 'session', id: fixture.id, cwd: '/tmp/project', timestamp: '2026-10-24T00:00:00.000Z' }),
+    ...(fixture.entries ?? []).map((entry) => JSON.stringify(entry)),
+  ];
+  fs.writeFileSync(file, `${lines.join('\n')}\n`);
+
+  if (fixture.subagents?.length) {
+    // A sibling directory named after the session file, holding one .jsonl per
+    // subagent — the shape `sessionHasSubagents` reads.
+    const sibling = file.replace(/\.jsonl$/, '');
+    fs.mkdirSync(sibling, { recursive: true });
+    for (const id of fixture.subagents) {
+      fs.writeFileSync(path.join(sibling, `${id}.jsonl`), `${JSON.stringify({ type: 'message' })}\n`);
+    }
+  }
+  clearSessionFileCaches();
+  return file;
+}
+
+afterEach(() => {
+  localRuns().clear();
+  clearSessionFileCaches();
+});
+
+afterAll(() => {
+  if (previousAgentDir === undefined) delete process.env.PI_CODING_AGENT_DIR;
+  else process.env.PI_CODING_AGENT_DIR = previousAgentDir;
+  for (const dir of tempDirs) fs.rmSync(dir, { recursive: true, force: true });
+});
+
+describe('loadSidebarActivity', () => {
+  test('carries nothing when no run is in flight', async () => {
+    const agentDir = useAgentDir();
+    writeSession(agentDir, { id: 'idle', entries: [{ type: 'message', timestamp: '2026-10-24T01:00:00.000Z' }] });
+    expect(await loadSidebarActivity()).toEqual({});
+  });
+
+  test('reports the newest entry timestamp of a session with a live run', async () => {
+    const agentDir = useAgentDir();
+    writeSession(agentDir, {
+      id: 'live',
+      entries: [
+        { type: 'message', timestamp: '2026-10-24T01:00:00.000Z' },
+        { type: 'message', timestamp: '2026-10-24T01:05:00.000Z' },
+      ],
+    });
+    localRuns().add('live');
+
+    const activity = await loadSidebarActivity();
+    expect(Object.keys(activity)).toEqual(['live']);
+    expect(activity.live?.updatedAt).toBe('2026-10-24T01:05:00.000Z');
+  });
+
+  test('never reports a session without a run, however recent its transcript', async () => {
+    const agentDir = useAgentDir();
+    writeSession(agentDir, { id: 'other', entries: [{ type: 'message', timestamp: '2026-10-24T01:00:00.000Z' }] });
+    writeSession(agentDir, { id: 'live', entries: [{ type: 'message', timestamp: '2026-10-24T01:00:00.000Z' }] });
+    localRuns().add('live');
+
+    expect(Object.keys(await loadSidebarActivity())).toEqual(['live']);
+  });
+
+  test('omits a live run whose transcript does not exist yet', async () => {
+    // A fresh spawn: omp writes the session file only when the first assistant
+    // message settles, so there is no stamp to report. Its row is the client's
+    // pending row until the scan finds the file.
+    useAgentDir();
+    localRuns().add('not-written-yet');
+    expect(await loadSidebarActivity()).toEqual({});
+  });
+
+  test('reports the subagent flag, which moves mid-run', async () => {
+    const agentDir = useAgentDir();
+    writeSession(agentDir, {
+      id: 'with-sub',
+      entries: [{ type: 'message', timestamp: '2026-10-24T01:00:00.000Z' }],
+      subagents: ['Sleeper'],
+    });
+    writeSession(agentDir, { id: 'plain', entries: [{ type: 'message', timestamp: '2026-10-24T01:00:00.000Z' }] });
+    localRuns().add('with-sub');
+    localRuns().add('plain');
+
+    const activity = await loadSidebarActivity();
+    expect(activity['with-sub']?.hasSubagents).toBe(true);
+    expect(activity.plain?.hasSubagents).toBe(false);
+  });
+});

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

@@ -0,0 +1,70 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * The `sidebar:activity` resolver: the two row fields a RUNNING session can
+ * still move between turn boundaries.
+ *
+ * Split out of `sidebar-data.server.ts` (which owns the structure and the
+ * status) because it answers a different question at a different cadence: the
+ * structure is re-scanned at turn boundaries, while this is resolved on every
+ * tool call — and its whole reason to exist is that the structure must NOT be.
+ *
+ * A run appends to its transcript on every tool call, so its row's age and its
+ * `LATEST_SESSION` position move mid-run. Republishing the structure for that
+ * cost 216 KB over 731 sessions per tool call (measured on the author's
+ * install, against 87 bytes for one live entry here), which is what made a
+ * phone's stream feel slow. Only a RUNNING session can move between boundaries,
+ * so only those are carried.
+ *
+ * A live run with no session FILE yet (a fresh spawn: omp writes it only when
+ * the first assistant message settles) contributes nothing — there is no stamp
+ * to report, and its sidebar row is the client's pending row until the scan
+ * finds the file.
+ */
+
+import { isMockMode } from '@/server/mock.server';
+import { getLiveRunSessionIds } from '@/server/lib/omp/rpc/session-registry';
+import { findSessionFileById } from '@/server/lib/omp/session/locator';
+import { scanSessionInfoCached } from '@/server/lib/omp/session/files';
+import { sessionHasSubagents } from '@/server/lib/omp/session/subagent-presence';
+import type { SidebarActivityPayload } from '@/shared/types/realtime';
+
+export async function loadSidebarActivity(): Promise<SidebarActivityPayload> {
+  const activity: SidebarActivityPayload = {};
+  // MOCK answers nothing, and that is not a shortcut: the simulated stream is
+  // an SSE route, not an omp child, so no `tool_execution_end` frame ever fires
+  // there and there is no between-boundary movement to report. Its rows also
+  // read `created_at` (the mock `sessions` table has no `updated_at`), so a
+  // `chat_sessions` stamp would be a different quantity under the same name —
+  // the one thing this payload must never be.
+  if (isMockMode()) return activity;
+
+  const live = getLiveRunSessionIds();
+  if (live.size === 0) return activity;
+  const entries = await Promise.all(
+    [...live].map(async (sessionId) => {
+      const filePath = await findSessionFileById(sessionId);
+      if (!filePath) return null;
+      const info = await scanSessionInfoCached(filePath);
+      if (!info) return null;
+      // `modified` is the newest entry's own timestamp, which is what the
+      // structure ships as `updated_at` — the same quantity, so the client can
+      // compare the two as ISO strings.
+      const updatedAt = info.modified.toISOString();
+      // The chevron's flag moves mid-run too: a subagent writes its own
+      // transcript beside the parent, and the row it lights is the parent's.
+      // Cost is a stat plus (on a change) one readdir, and the presence module
+      // memoizes on `(last entry, sibling mtime)` — measured 4-8 ms on a cache
+      // miss, 0 on a hit.
+      const hasSubagents = await sessionHasSubagents(filePath, updatedAt);
+      return [sessionId, { updatedAt, hasSubagents }] as const;
+    }),
+  );
+  for (const entry of entries) {
+    if (entry) activity[entry[0]] = entry[1];
+  }
+  return activity;
+}

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/omp/session/telemetry/compute.ts

@@ -10,6 +10,15 @@ import { scanSessionEntries } from '@/server/lib/omp/session/telemetry/scan';
  * Compute real `SessionContextTelemetry` for a session file (all-zero on
  * unreadable/empty). `rawLimit` caps materialized raw items (0 = none): the
  * panel reads full pages from `computeRawMessagesPage` in ./telemetry-raw.ts.
+ *
+ * The default is 0 — no raw items — and that is load-bearing rather than
+ * tidy: this value is published as the `session:<id>:telemetry` topic, which
+ * the navbar ring subscribes to for EVERY open session and the server
+ * republishes on every tool call. Measured on a 111-message transcript, the
+ * full `rawMessages` list (each item carrying its whole entry as
+ * `rawPayload`) was **690 KB of a 691 KB snapshot** — 99.9% of every push,
+ * per tool call, per tab. Nothing reads it: the panel pages raw items from
+ * `/api/telemetry/raw-messages`, and `/api/telemetry/context` strips them.
  */
 export async function computeRealSessionTelemetry(
   filePath: string,
@@ -106,7 +115,10 @@ export async function computeRealSessionTelemetry(
 
     if (role === 'user' || role === 'assistant') {
       messagesCount++;
-      if (rawLimit === 0 || rawMessages.length < rawLimit) {
+      // `rawLimit` is a CAP, so 0 means "none" — the guard must not read 0 as
+      // "unlimited", which is what it did and what put the whole transcript on
+      // the telemetry topic (see the doc above).
+      if (rawLimit > 0 && rawMessages.length < rawLimit) {
         const isAssistant = role === 'assistant';
         const snippet = text.slice(0, 70);
         rawMessages.push({

package/src/server/lib/omp/session/telemetry.test.ts

@@ -152,3 +152,36 @@ describe('computeRealSessionTelemetry context anchor', () => {
     expect(telemetry.contextUsed).toBe(2200);
   });
 });
+
+describe('computeRealSessionTelemetry raw items', () => {
+  // The default is the TELEMETRY TOPIC's payload, which the navbar ring keeps
+  // subscribed for every open session and the server republishes on every tool
+  // call. A raw item carries its whole entry as `rawPayload`, so reading 0 as
+  // "unlimited" put the entire transcript on that topic — measured 690 KB of a
+  // 691 KB snapshot on a 111-message session.
+  test('materializes no raw items by default', async () => {
+    const file = await writeSession([
+      header,
+      userMessage('u1', 'first turn'),
+      assistantMessage('a1', { usage: { input: 10, output: 5 } }),
+      userMessage('u2', 'second turn'),
+      assistantMessage('a2', { usage: { input: 20, output: 5 } }),
+    ]);
+    const telemetry = await computeRealSessionTelemetry(file, 'ses_telemetry');
+    expect(telemetry.messagesCount).toBe(4);
+    expect(telemetry.rawMessages).toEqual([]);
+  });
+
+  test('caps raw items at a positive limit', async () => {
+    const file = await writeSession([
+      header,
+      userMessage('u1', 'first turn'),
+      assistantMessage('a1', { usage: { input: 10, output: 5 } }),
+      userMessage('u2', 'second turn'),
+      assistantMessage('a2', { usage: { input: 20, output: 5 } }),
+    ]);
+    const telemetry = await computeRealSessionTelemetry(file, 'ses_telemetry', undefined, 2);
+    expect(telemetry.rawMessages).toHaveLength(2);
+    expect(telemetry.rawMessages[0]?.id).toBe('u1');
+  });
+});

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;
+}

package/src/server/lib/panels/sync.fixture.test-util.ts

@@ -0,0 +1,92 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * The two-directory fixture the bundled-sync suites run against: a WORKING
+ * marketplace (what is installed) and a STORE (what the package ships).
+ *
+ * Split out because the two suites that pin the sync would otherwise each carry
+ * a copy of the same setup, and the paths are the whole contract — a copy that
+ * forgot `KABMO_BUNDLED_MARKETPLACE_DIR` would silently compare the real
+ * package's store against a temp install and pass for the wrong reason.
+ *
+ * `isolateDb` is part of the setup, not a separate step: the baselines and the
+ * refusal records live in `app_settings`, and a suite that skipped it would read
+ * (and write) the developer's own database.
+ */
+
+import fs from 'node:fs';
+import { mkdtempSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import { invalidatePanelScan } from '@/server/lib/panels/registry.server';
+import { hashTrackedFiles } from '@/server/lib/panels/local-edits.server';
+import { writeBaseline } from '@/server/lib/panels/baseline.server';
+import { isolateDb, releaseDb } from '@/test-support/isolated-db';
+
+export interface SyncFixture {
+  /** The working marketplace root (installs live here). */
+  root: string;
+  /** The bundled store root (the package's copy). */
+  store: string;
+  /** A scratch directory for git repositories. */
+  work: string;
+}
+
+export const FIXTURE_MANIFEST = { id: 'demo', name: 'Demo', version: '1.0.0', app: 'dist/app.js' };
+
+/** Write a plugin directory: manifest, bundle, and any extra files. */
+export function writePlugin(dir: string, manifest: unknown, files: Record<string, string> = {}): void {
+  fs.mkdirSync(join(dir, 'dist'), { recursive: true });
+  fs.writeFileSync(join(dir, 'kabmo.json'), JSON.stringify(manifest));
+  fs.writeFileSync(join(dir, 'dist', 'app.js'), 'export default {};');
+  for (const [name, content] of Object.entries(files)) {
+    const target = join(dir, name);
+    fs.mkdirSync(join(target, '..'), { recursive: true });
+    fs.writeFileSync(target, content);
+  }
+}
+
+/** Create the fixture and point the process at it. Call from `beforeEach`. */
+export async function setupSyncFixture(): Promise<SyncFixture> {
+  const fixture: SyncFixture = {
+    root: mkdtempSync(join(tmpdir(), 'omp-sync-work-')),
+    store: mkdtempSync(join(tmpdir(), 'omp-sync-store-')),
+    work: mkdtempSync(join(tmpdir(), 'omp-sync-repos-')),
+  };
+  process.env.KABMO_MARKETPLACE_DIR = fixture.root;
+  process.env.KABMO_BUNDLED_MARKETPLACE_DIR = fixture.store;
+  await isolateDb();
+  invalidatePanelScan();
+  return fixture;
+}
+
+/** Tear the fixture down. Call from `afterEach`. */
+export async function teardownSyncFixture(fixture: SyncFixture): Promise<void> {
+  delete process.env.KABMO_MARKETPLACE_DIR;
+  delete process.env.KABMO_BUNDLED_MARKETPLACE_DIR;
+  await releaseDb();
+  invalidatePanelScan();
+  for (const dir of [fixture.root, fixture.store, fixture.work]) {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+}
+
+/**
+ * Install a bundled plugin the way the install path does: the store's copy is
+ * written into the working marketplace, and the baseline is taken from what
+ * landed. `files` therefore go into the STORE, or the install would carry a file
+ * the store never had — a state an install cannot produce.
+ */
+export async function installBundled(
+  fixture: SyncFixture,
+  version: string,
+  files: Record<string, string> = {},
+): Promise<void> {
+  writePlugin(join(fixture.store, 'plugins', 'demo'), { ...FIXTURE_MANIFEST, version }, files);
+  writePlugin(join(fixture.root, 'plugins', 'demo'), { ...FIXTURE_MANIFEST, version }, files);
+  await writeBaseline('demo', await hashTrackedFiles(join(fixture.root, 'plugins', 'demo')));
+}