@kabmo-labs/kabmo 0.7.0 → 0.9.0

package/src/shared/lib/workspace/session-state/store.test.ts

@@ -6,63 +6,37 @@
 /**
  * Pins the session-state store's observer contract and cache lifecycle.
  *
- * The store is a module singleton with private Maps, so the tests drive it
- * only through its exports and tear every touched session down with
- * `forgetSession` (which clears the cache entry, its dirty flag and its
- * pending persist timer). What matters here: a write notifies exactly the
- * followers of that (session, slot), a blob arriving notifies every follower
- * of the session, a delete notifies, and the merge rules keep a local write
- * from being clobbered by a stored blob that predates it.
+ * The store is the single source of a session's UI state: every panel reads and
+ * writes through it, and it persists the whole blob through
+ * `GET/POST /api/sessions/:sessionId/state`. Two contracts matter enough to pin
+ * here rather than in a component test:
+ *
+ *  - **Notification routing.** A write notifies the slot's followers and the
+ *    session-wide ones, never another session's, and an unsubscribed listener
+ *    stops receiving while an in-flight pass still reaches it.
+ *  - **Cache lifecycle.** The cache is bounded (10 sessions) and TTL'd (10
+ *    minutes), and eviction never takes a session with unsaved writes.
+ *
+ * The blob-arrival half — the write-during-read race — is `store-load.test.ts`,
+ * and the wholesale-replacement bus is `replacement.test.ts`.
  */
 
-import { afterEach, describe, expect, setSystemTime, test } from 'bun:test';
+import { describe, expect, setSystemTime, test } from 'bun:test';
 
-import { notifySessionKey, subscribeSessionKey } from '@/shared/lib/workspace/session-state/listeners';
+import { notifySessionKey } from '@/shared/lib/workspace/session-state/listeners';
 import {
   clearSessionKey,
-  flushSession,
   forgetSession,
   getLastOpenedAt,
   getSessionValue,
   hydrateSession,
-  loadSession,
   migrateSessionState,
   recordSessionOpen,
   setSessionKey,
 } from '@/shared/lib/workspace/session-state/store';
+import { counter, follow, installStoreTeardown, use } from '@/shared/lib/workspace/session-state/harness.test-util';
 
-const originalWindow = Reflect.get(globalThis, 'window');
-/** The runner's own fetch, reached through `Bun` so a stub leaked onto the global cannot be mistaken for it. */
-const originalFetch = Bun.fetch;
-const touched: string[] = [];
-const unsubs: Array<() => void> = [];
-
-/** Register a session id so `afterEach` forgets it. */
-function use(id: string): string {
-  touched.push(id);
-  return id;
-}
-
-/** Subscribe and auto-unsubscribe at teardown. */
-function follow(sessionId: string | null, key: string | null, listener: () => void): () => void {
-  const unsubscribe = subscribeSessionKey(sessionId, key, listener);
-  unsubs.push(unsubscribe);
-  return unsubscribe;
-}
-
-/** Count how many times `notifySessionKey` reaches a listener. */
-function counter(): { calls: number; listener: () => void } {
-  const state = { calls: 0, listener: () => { state.calls += 1; } };
-  return state;
-}
-
-afterEach(() => {
-  for (const unsubscribe of unsubs.splice(0)) unsubscribe();
-  for (const id of touched.splice(0)) forgetSession(id);
-  Reflect.set(globalThis, 'window', originalWindow);
-  Reflect.set(globalThis, 'fetch', originalFetch);
-  setSystemTime();
-});
+installStoreTeardown();
 
 describe('session-state store: read/write', () => {
   test('a null session id is a no-op for reads and writes', () => {
@@ -211,102 +185,6 @@ describe('session-state store: notification routing', () => {
   });
 });
 
-describe('session-state store: blob arrival (loadSession)', () => {
-  function stubWindow(): void {
-    Reflect.set(globalThis, 'window', {});
-  }
-
-  function stubFetch(response: unknown): void {
-    Reflect.set(globalThis, 'fetch', async () => response);
-  }
-
-  test('a clean session adopts the stored blob and notifies', async () => {
-    const id = use('load-clean');
-    stubWindow();
-    stubFetch({ ok: true, json: async () => ({ state: { a: 1, b: 2 } }) });
-    const probe = counter();
-    follow(id, null, probe.listener);
-
-    await loadSession(id);
-    expect<number | undefined>(getSessionValue(id, 'a')).toBe(1);
-    expect<string | number | boolean | Record<string, unknown> | unknown[] | null | undefined>(getSessionValue(id, 'b')).toBe(2);
-    expect(probe.calls).toBe(1);
-  });
-
-  test('a dirty session keeps its local writes over the blob', async () => {
-    const id = use('load-dirty');
-    stubWindow();
-    setSessionKey(id, 'a', 99);
-    stubFetch({ ok: true, json: async () => ({ state: { a: 1, b: 2 } }) });
-
-    await loadSession(id);
-    expect<string | number | boolean | Record<string, unknown> | unknown[] | null | undefined>(getSessionValue(id, 'a')).toBe(99);
-    expect<string | number | boolean | Record<string, unknown> | unknown[] | null | undefined>(getSessionValue(id, 'b')).toBe(2);
-  });
-
-  test('a non-ok response leaves the cache untouched but still notifies', async () => {
-    const id = use('load-error');
-    stubWindow();
-    stubFetch({ ok: false, json: async () => ({}) });
-    const probe = counter();
-    follow(id, null, probe.listener);
-
-    await loadSession(id);
-    expect(getSessionValue(id, 'a')).toBeUndefined();
-    expect(probe.calls).toBe(1);
-  });
-
-  test('a rejected fetch is swallowed and notifies', async () => {
-    const id = use('load-throw');
-    stubWindow();
-    Reflect.set(globalThis, 'fetch', async () => {
-      throw new Error('offline');
-    });
-    const probe = counter();
-    follow(id, null, probe.listener);
-
-    // The store logs the failure; keep the expected warning out of the run log.
-    const warn = console.warn;
-    console.warn = () => {};
-    try {
-      await loadSession(id);
-    } finally {
-      console.warn = warn;
-    }
-    expect(getSessionValue(id, 'a')).toBeUndefined();
-    expect(probe.calls).toBe(1);
-  });
-
-  test('loadSession without a window returns early: no fetch, no notify', async () => {
-    const id = use('load-nowindow');
-    // Removed for the case and put back after it: another file's hook can have
-    // installed one while this file runs, and leaving it missing would break
-    // whichever case follows.
-    const hadWindow = Object.getOwnPropertyDescriptor(globalThis, 'window');
-    Reflect.deleteProperty(globalThis, 'window');
-    let fetched = false;
-    Reflect.set(globalThis, 'fetch', async () => {
-      fetched = true;
-      throw new Error('must not be called');
-    });
-    try {
-      const probe = counter();
-      follow(id, null, probe.listener);
-      await loadSession(id);
-      expect(fetched).toBe(false);
-      expect(probe.calls).toBe(0);
-    } finally {
-      if (hadWindow) Object.defineProperty(globalThis, 'window', hadWindow);
-      Reflect.set(globalThis, 'fetch', Bun.fetch);
-    }
-  });
-
-  test('flushSession is a resolved no-op without a window or id', async () => {
-    await expect(flushSession(null)).resolves.toBeUndefined();
-    await expect(flushSession(use('flush'))).resolves.toBeUndefined();
-  });
-});
-
 describe('session-state store: bounded cache', () => {
   test('the oldest clean session is evicted past the size cap', () => {
     const ids = Array.from({ length: 11 }, (_unused, index) => use(`lru-${index}`));

package/src/shared/lib/workspace/session-state/store.ts

@@ -66,91 +66,52 @@
  *                             from another conversation is never restored
  * - chat.draft                string
  * - chat.draftAttachments     attachment metadata array
+ *
+ * The module is three files, because one had passed the per-file ceiling: this
+ * one owns the PUBLIC API (read, write, load, migrate) and what a write means;
+ * `cache.ts` owns the storage (the maps, the LRU order, the idle TTL, the dirty
+ * flag); `merge.ts` owns the write counter and the "which copy wins when a blob
+ * lands" decision. The maps live only in `cache.ts`, so "is this session dirty"
+ * and "drop this session" cannot be answered from two places that disagree.
  */
 
 import { notifySessionKey, notifySessionReplaced } from '@/shared/lib/workspace/session-state/listeners';
+import {
+  clearDirty,
+  dropEntry,
+  dropPersistTimer,
+  entryForWrite,
+  evictIfNeeded,
+  isDirty,
+  lastAccess,
+  markDirty,
+  readEntry,
+  setPersistTimer,
+  stampAccess,
+  touchEntry,
+  writeEntry,
+} from '@/shared/lib/workspace/session-state/cache';
+import {
+  currentWriteSeq,
+  forgetWrites,
+  keysWrittenAfter,
+  mergeStoredBlob,
+  noteWrite,
+} from '@/shared/lib/workspace/session-state/merge';
 
 type SessionState = Record<string, unknown>;
 
-const cache = new Map<string, SessionState>();
-/** Epoch ms of the last user-driven access per session (get/set/hydrate). */
-const lastTouched = new Map<string, number>();
-const dirtySessions = new Map<string, boolean>();
-const persistTimers = new Map<string, ReturnType<typeof setTimeout>>();
-
 const PERSIST_DEBOUNCE_MS = 600;
 
-// Bounded LRU cache: cap the number of sessions kept in memory so the tab
-// doesn't grow unboundedly as the user visits more sessions.
-const MAX_CACHED_SESSIONS = 10;
-/** A session whose last user access is older than this is evicted regardless
- *  of the size cap, so stale per-session UI state (drafts, panel layouts)
- *  stops occupying memory 10 minutes after the user last opened it. */
-const SESSION_IDLE_TTL_MS = 10 * 60 * 1000;
-
-/**
- * Reorder a cache entry to the end of the Map's iteration order (the
- * most-recently-used position) via delete-then-set. Map.set on an existing
- * key updates the value but keeps its original position, so the explicit
- * delete is required for true LRU semantics.
- */
-function touchCacheEntry(sessionId: string): void {
-  const value = cache.get(sessionId);
-  if (value !== undefined) {
-    cache.delete(sessionId);
-    cache.set(sessionId, value);
-  }
-  lastTouched.set(sessionId, Date.now());
-}
-
-/**
- * Evict the oldest clean sessions until the cache is within bounds.
- *
- * Dirty-safety rule: a session with unsaved writes (`dirtySessions.get(id) ===
- * true`) must never be evicted, or the user's drafts and editor state would be
- * silently lost. If every candidate is dirty (or is the protected id currently
- * being written), stop evicting rather than lose data.
- *
- * Entries idle past SESSION_IDLE_TTL_MS are evicted first — even when the
- * cache is under the size cap — so long-unused sessions drop out on schedule.
- */
-function evictIfNeeded(protectedId: string | null): void {
-  const now = Date.now();
-  const evict = (id: string): void => {
-    cache.delete(id);
-    dirtySessions.delete(id);
-    lastTouched.delete(id);
-    const timer = persistTimers.get(id);
-    if (timer) {
-      clearTimeout(timer);
-      persistTimers.delete(id);
-    }
-  };
-  // TTL pass: safe to skip only while the timer still holds the unsaved state
-  // or the session is the one currently being written.
-  for (const [id, touched] of lastTouched) {
-    if (now - touched <= SESSION_IDLE_TTL_MS) continue;
-    if (id === protectedId) continue;
-    if (dirtySessions.get(id)) continue;
-    evict(id);
-  }
-  while (cache.size > MAX_CACHED_SESSIONS) {
-    let evicted = false;
-    for (const id of cache.keys()) {
-      if (id === protectedId) continue;
-      if (dirtySessions.get(id)) continue;
-      evict(id);
-      evicted = true;
-      break;
-    }
-    if (!evicted) break;
-  }
+/** Evict past the cap, dropping this session's write history with it. */
+function evictNow(protectedId: string | null): void {
+  evictIfNeeded(protectedId, forgetWrites);
 }
 
 export function getSessionValue<T>(sessionId: string | null, key: string): T | undefined {
   if (!sessionId) return undefined;
-  touchCacheEntry(sessionId);
-  return cache.get(sessionId)?.[key] as T | undefined;
+  touchEntry(sessionId);
+  return readEntry(sessionId)?.[key] as T | undefined;
 }
 
 /**
@@ -166,18 +127,20 @@ export function getSessionValue<T>(sessionId: string | null, key: string): T | u
  */
 export function getSessionState(sessionId: string | null): Readonly<Record<string, unknown>> | undefined {
   if (!sessionId) return undefined;
-  return cache.get(sessionId);
+  return readEntry(sessionId);
 }
 
 export function setSessionKey(sessionId: string | null, key: string, value: unknown): void {
   if (!sessionId) return;
-  const state = cache.get(sessionId) ?? {};
-  state[key] = value;
-  cache.set(sessionId, state);
-  touchCacheEntry(sessionId);
-  dirtySessions.set(sessionId, true);
+  // Mutated IN PLACE, never copied: `useSessionState` compares the store's entry
+  // against its own copy by IDENTITY to decide whether a fresher write exists,
+  // and a copy per write made every reader see a different object for one slot.
+  entryForWrite(sessionId)[key] = value;
+  touchEntry(sessionId);
+  markDirty(sessionId);
+  noteWrite(sessionId, key);
   schedulePersist(sessionId);
-  evictIfNeeded(sessionId);
+  evictNow(sessionId);
   notifySessionKey(sessionId, key);
 }
 
@@ -188,22 +151,25 @@ export function setSessionKey(sessionId: string | null, key: string, value: unkn
  */
 export function clearSessionKey(sessionId: string | null, key: string): void {
   if (!sessionId) return;
-  const state = cache.get(sessionId);
+  const state = readEntry(sessionId);
   if (!state || !(key in state)) return;
-  delete state[key];
-  touchCacheEntry(sessionId);
-  dirtySessions.set(sessionId, true);
+  delete (state as SessionState)[key];
+  touchEntry(sessionId);
+  markDirty(sessionId);
+  // A DELETE is a write: a blob that still carries the key must not bring it
+  // back (a retired key cleared on this side would return from the other tab's
+  // older snapshot).
+  noteWrite(sessionId, key);
   schedulePersist(sessionId);
   notifySessionKey(sessionId, key);
 }
 
 function schedulePersist(sessionId: string): void {
-  const existing = persistTimers.get(sessionId);
-  if (existing) clearTimeout(existing);
-  persistTimers.set(
+  dropPersistTimer(sessionId);
+  setPersistTimer(
     sessionId,
     setTimeout(() => {
-      persistTimers.delete(sessionId);
+      dropPersistTimer(sessionId);
       void persistSession(sessionId);
     }, PERSIST_DEBOUNCE_MS),
   );
@@ -211,9 +177,9 @@ function schedulePersist(sessionId: string): void {
 
 async function persistSession(sessionId: string): Promise<void> {
   if (typeof window === 'undefined' || !sessionId) return;
-  if (!dirtySessions.get(sessionId)) return;
-  dirtySessions.set(sessionId, false);
-  const state = cache.get(sessionId) ?? {};
+  if (!isDirty(sessionId)) return;
+  clearDirty(sessionId);
+  const state = readEntry(sessionId) ?? {};
   try {
     await fetch(`/api/sessions/${encodeURIComponent(sessionId)}/state`, {
       method: 'POST',
@@ -222,18 +188,14 @@ async function persistSession(sessionId: string): Promise<void> {
     });
   } catch (err) {
     console.warn('session-state persist failed:', err);
-    dirtySessions.set(sessionId, true);
+    markDirty(sessionId);
   }
 }
 
 /** Immediately persist any pending writes for a session (used on switch). */
 export function flushSession(sessionId: string | null): Promise<void> {
   if (!sessionId || typeof window === 'undefined') return Promise.resolve();
-  const timer = persistTimers.get(sessionId);
-  if (timer) {
-    clearTimeout(timer);
-    persistTimers.delete(sessionId);
-  }
+  dropPersistTimer(sessionId);
   return persistSession(sessionId);
 }
 
@@ -241,27 +203,34 @@ export function flushSession(sessionId: string | null): Promise<void> {
 export async function loadSession(sessionId: string): Promise<void> {
   if (!sessionId) return;
   if (typeof window === 'undefined') return;
+  /**
+   * The write counter as of the moment the read STARTED.
+   *
+   * Everything written after this is newer than the response, because the
+   * response describes the row as it was when the request arrived. Two
+   * mechanisms are needed and neither is sufficient alone: `dirtySessions`
+   * covers a write whose persist has not landed yet, while this covers one that
+   * already persisted — at which point the dirty flag is clear and a stale
+   * response would otherwise be adopted wholesale. Measured: a file opened
+   * during the first `/state` read came back with `layout.openedFiles` gone.
+   */
+  const startedAt = currentWriteSeq();
   try {
     const res = await fetch(`/api/sessions/${encodeURIComponent(sessionId)}/state`);
     if (res.ok) {
       const data = (await res.json()) as { state?: SessionState };
       const incoming = data.state && typeof data.state === 'object' ? data.state : {};
-      const existing = cache.get(sessionId) ?? {};
-      // Only keys written locally while the fetch was in flight win over the
-      // stored blob. Merging the WHOLE local cache over the blob (the old
-      // behavior) resurrected stale values on every tab: a second browser
-      // opening the session had cached the pre-write blob, and its stale
-      // copy clobbered another tab's fresh writes — queue items written in
-      // one tab never appeared in the other.
-      const dirty = dirtySessions.get(sessionId) === true;
-      const merged = dirty ? { ...incoming, ...existing } : incoming;
-      cache.set(sessionId, merged);
-      touchCacheEntry(sessionId);
+      const existing = readEntry(sessionId) ?? {};
+      writeEntry(
+        sessionId,
+        mergeStoredBlob(incoming, existing, keysWrittenAfter(sessionId, startedAt), isDirty(sessionId)),
+      );
+      touchEntry(sessionId);
     }
   } catch (err) {
     console.warn('session-state load failed:', err);
   }
-  evictIfNeeded(sessionId);
+  evictNow(sessionId);
   // The blob replaces every slot at once, so a follower that read the store
   // before it arrived (no pick yet) has to re-read — including a private copy
   // held by `useSessionState`, which does not follow per-slot writes.
@@ -272,9 +241,9 @@ export async function loadSession(sessionId: string): Promise<void> {
 /** Seed the cache synchronously (e.g. from SSR-provided data). */
 export function hydrateSession(sessionId: string | null, state: SessionState): void {
   if (!sessionId) return;
-  cache.set(sessionId, { ...(cache.get(sessionId) ?? {}), ...state });
-  touchCacheEntry(sessionId);
-  evictIfNeeded(sessionId);
+  writeEntry(sessionId, { ...(readEntry(sessionId) ?? {}), ...state });
+  touchEntry(sessionId);
+  evictNow(sessionId);
   notifySessionKey(sessionId);
   notifySessionReplaced(sessionId);
 }
@@ -285,12 +254,12 @@ export function hydrateSession(sessionId: string | null, state: SessionState): v
  * its last open is within SESSION_IDLE_TTL_MS.
  */
 export function recordSessionOpen(sessionId: string | null): void {
-  if (sessionId) lastTouched.set(sessionId, Date.now());
+  if (sessionId) stampAccess(sessionId);
 }
 
 /** Epoch ms of the user's last open of this session in this tab, if any. */
 export function getLastOpenedAt(sessionId: string): number | undefined {
-  return lastTouched.get(sessionId);
+  return lastAccess(sessionId);
 }
 
 /**
@@ -302,14 +271,8 @@ export function getLastOpenedAt(sessionId: string): number | undefined {
  * the delete and resurrect the state.
  */
 export function forgetSession(sessionId: string): void {
-  const timer = persistTimers.get(sessionId);
-  if (timer) {
-    clearTimeout(timer);
-    persistTimers.delete(sessionId);
-  }
-  cache.delete(sessionId);
-  dirtySessions.delete(sessionId);
-  lastTouched.delete(sessionId);
+  dropEntry(sessionId);
+  forgetWrites(sessionId);
   notifySessionKey(sessionId);
   notifySessionReplaced(sessionId);
 }
@@ -319,15 +282,14 @@ export function forgetSession(sessionId: string): void {
  * by a spawn, then discard the transient slot.
  */
 export function migrateSessionState(fromId: string, toId: string): void {
-  const from = cache.get(fromId);
-  if (from) cache.set(toId, { ...from, ...(cache.get(toId) ?? {}) });
-  touchCacheEntry(toId);
-  dirtySessions.set(toId, true);
+  const from = readEntry(fromId);
+  if (from) writeEntry(toId, { ...from, ...(readEntry(toId) ?? {}) });
+  touchEntry(toId);
+  markDirty(toId);
   schedulePersist(toId);
-  cache.delete(fromId);
-  dirtySessions.delete(fromId);
-  lastTouched.delete(fromId);
-  evictIfNeeded(toId);
+  dropEntry(fromId);
+  forgetWrites(fromId);
+  evictNow(toId);
   // The adopted slot gained the whole transient state; the transient one lost it.
   notifySessionKey(toId);
   notifySessionKey(fromId);

package/src/shared/lib/workspace/workspace-modules.test.ts

@@ -20,7 +20,7 @@
 
 import { afterAll, afterEach, describe, expect, test } from 'bun:test';
 
-import { activeProjectForSession, composerRootFor } from '@/shared/lib/workspace/active-project';
+import { activeProjectForSession, composerRootFor, effectiveRootFor } from '@/shared/lib/workspace/active-project';
 import { diffTabId, diffTabName, fileTabId } from '@/shared/lib/workspace/file-tab-id';
 import {
   DEFAULT_RIGHT_PANEL_FRACTION,
@@ -173,6 +173,54 @@ describe('active-project', () => {
     expect(composerRootFor(folders, 30, 1)).toBe('/work/gamma');
   });
 
+  /**
+   * The root the panels follow. A worktree session runs OUTSIDE its folder's
+   * project path, so pointing the panels at `project_path` showed the checkout
+   * the agent had left — measured: every panel kept reading the main tree while
+   * the run wrote to the worktree.
+   */
+  describe('effectiveRootFor', () => {
+    const withWorktree = (status: 'ready' | 'missing'): WorkspaceFolderData[] => [
+      {
+        id: 1,
+        name: 'alpha',
+        project_path: '/work/alpha',
+        isExpanded: true,
+        hasMore: false,
+        totalSessions: 2,
+        sessions: [
+          {
+            id: 'wt-session',
+            folder_id: 1,
+            title: 'in a worktree',
+            worktree: {
+              branch: 'wt/cosmic-dolphin',
+              path: '/data/worktrees/abc/cosmic-dolphin',
+              primaryRoot: '/work/alpha',
+              status,
+              detached: false,
+            },
+          },
+          { id: 'plain', folder_id: 1, title: 'in the checkout' },
+        ],
+      },
+    ];
+
+    test('a ready worktree wins over the folder project path', () => {
+      expect(effectiveRootFor(withWorktree('ready'), 'wt-session')).toBe('/data/worktrees/abc/cosmic-dolphin');
+    });
+
+    test('a MISSING worktree falls back to the project path — a directory that is gone is not a root', () => {
+      expect(effectiveRootFor(withWorktree('missing'), 'wt-session')).toBe('/work/alpha');
+    });
+
+    test('an ordinary session keeps the project path', () => {
+      expect(effectiveRootFor(withWorktree('ready'), 'plain')).toBe('/work/alpha');
+      expect(effectiveRootFor(folders, 30)).toBe('/work/gamma');
+      expect(effectiveRootFor(folders, 999)).toBeNull();
+    });
+  });
+
   test('composerRootFor falls back to the selected folder without a session match', () => {
     expect(composerRootFor(folders, null, 3)).toBe('/work/gamma');
     expect(composerRootFor(folders, 999, 3)).toBe('/work/gamma');