@neuralis/brain-core 0.2.0 → 0.3.0

package/app/filesystem/store/filesystemStore.ts

@@ -1,7 +1,10 @@
-import { create } from 'zustand';
+import { createContext, createElement, useContext, useLayoutEffect, useMemo, type ReactNode } from 'react';
+import { useStore } from 'zustand';
 import { persist, createJSONStorage } from 'zustand/middleware';
+import { createStore, type StoreApi as ZustandStoreApi } from 'zustand/vanilla';
 import type { ClientStateResetScope } from '@neuralis/package-system/contracts';
-import type { EditorTabMeta, FileNode, FileSystemState, FSWriteResponse, PersistedFilesContext, SidebarView, WorkspacePanelId } from '../domain/types';
+import { createPackageApi, type PackageApi } from '@neuralis/package-system/client';
+import type { EditorTabMeta, FileNode, FileSystemState, FSWriteResponse, PersistedFilesContext, PersistedFilesWindow, SidebarView, WorkspacePanelId } from '../domain/types';
 export type { SidebarView, WorkspacePanelId } from '../domain/types';
 import { countPendingChanges, readFiles, uploadFile, writeFile, writeRefusalMessage } from '../api';
 import {
@@ -42,44 +45,6 @@ import { gitSliceInitial, createGitSlice, type GitSliceState, type GitSliceActio
  */
 export const FILES_LRU_HARD_CAP = 50_000;
 
-/**
- * Bumped by `fenceInFlightWriters` — the ONE fence BOTH reset paths run before
- * their wipe: `resetClientState` (the dock broom) and `loadList`'s agent/project
- * switch. Every async writer that materialises a node or content AFTER an await
- * (the `openFile` read, a reconcile pass's `set`, the optimistic folder in
- * `createNode`, the editor tails `saveFileInPlace` / `markFileDeleted`) captures
- * it BEFORE the await and writes only when it still matches — a read, listing
- * or mutation answer that resolves after the reset must not put a tab, its
- * folder chain, its content or its parent's dirty flag into a store that now
- * belongs to another context. Module-level like the generation map: the reset
- * is a store-wide event. Until 2026-09-04 only the broom fenced; the switch
- * wiped without fencing, so a read a tab click had started under the previous
- * agent could land its file — and `activeFile` — under the new one.
- *
- * Writers that need NO epoch (documented, not oversight): `moveFileToFolder` /
- * `renameNode` / `pasteNodes` / `deleteNodes` / `upload*` are no-ops on an empty
- * store (`replaceFilePath`, `prunePrefix`, `patchFileNode`, the `openFiles.map`
- * all find nothing) or set a hint flag; a late `loadList` answer writes
- * `brain://` + `sources`, which the remounted widget re-requests anyway; late
- * `runSearch` / `loadGitStatus` / `loadGitBranches` answers are overwritten on
- * the next use; `ensureFolderLoaded`'s superseded and catch branches write
- * `hydrationState[uri]` only (`'idle'` / `'error'` for a folder row that is gone);
- * the SSE handlers are synchronous and die with the widget; `applyNav` /
- * `autoExpandToFile` write synchronously before any await.
- */
-let resetEpoch = 0;
-/** The newest `refreshPendingCount` call — an older answer never overwrites a newer one. */
-let pendingCountSeq = 0;
-/**
- * Tabs whose rehydrate read is in flight — a second activation must not issue a
- * second read. Keyed by uri, so the fence CLEARS it: the same uri under another
- * context is another file, and a stale key would suppress the new context's read
- * for good (the old answer is fenced out, the baseline never arrives).
- */
-const rehydrateInFlight = new Set<string>();
-
-const liveFolderLoadInFlight = new Map<string, Promise<void>>();
-
 /**
  * Per-source reconcile job. The guard used to DROP a request that arrived while a
  * reconcile was running, which made every mutation tail unsafe: the drop silently
@@ -89,29 +54,78 @@ const liveFolderLoadInFlight = new Map<string, Promise<void>>();
  * and the caller awaits the whole chain.
  */
 type ReconcileJob = { rerun: boolean; wide: boolean; extra: Set<string>; promise: Promise<void> };
-const reconcileJobs = new Map<string, ReconcileJob>();
 
 /** Bound on coalesced reruns so a hot event stream can't spin the loop forever. */
 const MAX_RECONCILE_PASSES = 3;
 
 /**
- * Monotonic list-generation token PER FOLDER (not per source). Two listings of the
- * SAME folder can be in flight at once — `reconcileSourceFolders` lists its targets
- * concurrently and `ensureFolderLoaded` can overlap it — so a slow response must not
- * overwrite a newer one. Every list issue bumps its folder's counter; a response
- * whose token is no longer current is discarded. A per-SOURCE token would not catch
- * this: both listings share the source.
+ * The asynchronous fences of ONE Files store — one set per window, created with
+ * it (`createFilesystemStore`). Two windows never share a fence: a reset or a
+ * context switch is that window's event, so it fences only that window's
+ * in-flight work, and a sibling window's listing can never supersede this one's.
+ *
+ * - `resetEpoch` — bumped by `fenceInFlightWriters`, the ONE fence BOTH reset
+ *   paths run before their wipe: `resetClientState` (the dock broom) and
+ *   `loadList`'s context switch. Every async writer that materialises a node or
+ *   content AFTER an await (the `openFile` read, a reconcile pass's `set`, the
+ *   optimistic folder in `createNode`, the editor tails `saveFileInPlace` /
+ *   `markFileDeleted`) captures it BEFORE the await and writes only when it still
+ *   matches — a read, listing or mutation answer that resolves after the reset
+ *   must not put a tab, its folder chain, its content or its parent's dirty flag
+ *   into a store that now belongs to another context. Writers that need NO epoch
+ *   (documented, not oversight): `moveFileToFolder` / `renameNode` / `pasteNodes`
+ *   / `deleteNodes` / `upload*` are no-ops on an empty store (`replaceFilePath`,
+ *   `prunePrefix`, `patchFileNode`, the `openFiles.map` all find nothing) or set
+ *   a hint flag; a late `loadList` answer writes `brain://` + `sources`, which the
+ *   remounted widget re-requests anyway; late `runSearch` / `loadGitStatus` /
+ *   `loadGitBranches` answers are overwritten on the next use;
+ *   `ensureFolderLoaded`'s superseded and catch branches write
+ *   `hydrationState[uri]` only; the SSE handlers are synchronous and die with the
+ *   widget; `applyNav` / `autoExpandToFile` write synchronously before any await.
+ * - `pendingCountSeq` — the newest `refreshPendingCount` call; an older answer
+ *   never overwrites a newer one.
+ * - `rehydrateInFlight` — tabs whose rehydrate read is in flight, so a second
+ *   activation issues no second read. Keyed by uri, so the fence CLEARS it: the
+ *   same uri under another context is another file, and a stale key would
+ *   suppress the new context's read for good.
+ * - `liveFolderLoadInFlight` — the folder-listing dedup map.
+ * - `reconcileJobs` — the per-source coalescer (`ReconcileJob`).
+ * - `folderGeneration` — a monotonic list-generation token PER FOLDER (not per
+ *   source). Two listings of the SAME folder can be in flight at once —
+ *   `reconcileSourceFolders` lists its targets concurrently and
+ *   `ensureFolderLoaded` can overlap it — so a slow response must not overwrite a
+ *   newer one. Every list issue bumps its folder's counter; a response whose
+ *   token is no longer current is discarded. A per-SOURCE token would not catch
+ *   this: both listings share the source.
  */
-const folderGeneration = new Map<string, number>();
+type StoreFences = {
+  resetEpoch: number;
+  pendingCountSeq: number;
+  rehydrateInFlight: Set<string>;
+  liveFolderLoadInFlight: Map<string, Promise<void>>;
+  reconcileJobs: Map<string, ReconcileJob>;
+  folderGeneration: Map<string, number>;
+};
 
-function nextFolderGeneration(folderKey: string): number {
-  const gen = (folderGeneration.get(folderKey) ?? 0) + 1;
-  folderGeneration.set(folderKey, gen);
+function createStoreFences(): StoreFences {
+  return {
+    resetEpoch: 0,
+    pendingCountSeq: 0,
+    rehydrateInFlight: new Set<string>(),
+    liveFolderLoadInFlight: new Map<string, Promise<void>>(),
+    reconcileJobs: new Map<string, ReconcileJob>(),
+    folderGeneration: new Map<string, number>(),
+  };
+}
+
+function nextFolderGeneration(fences: StoreFences, folderKey: string): number {
+  const gen = (fences.folderGeneration.get(folderKey) ?? 0) + 1;
+  fences.folderGeneration.set(folderKey, gen);
   return gen;
 }
 
-function isCurrentFolderGeneration(folderKey: string, gen: number): boolean {
-  return folderGeneration.get(folderKey) === gen;
+function isCurrentFolderGeneration(fences: StoreFences, folderKey: string, gen: number): boolean {
+  return fences.folderGeneration.get(folderKey) === gen;
 }
 
 /** `pendingReviewPaths` transitions the shared mapper observed, applied by the caller. */
@@ -280,8 +294,8 @@ function withPendingDelta(
   return out;
 }
 
-/** Minimal store handle the module-level reconcile engine needs. */
-type StoreApi = { get: () => any; set: (fn: (s: any) => any) => void };
+/** The store handle the module-level reconcile engine needs: state, its window's fences and request client. */
+type StoreApi = { get: () => any; set: (fn: (s: any) => any) => void; fences: StoreFences; client: PackageApi };
 
 /**
  * How many folder listings one reconcile pass has in flight. Each costs a server
@@ -399,7 +413,7 @@ async function runReconcilePass(
   // Captured at pass START: the per-folder generation guard sits in the worker,
   // so a listing set that landed BEFORE a broom would still be written by the
   // `set()` below unless the pass itself is fenced.
-  const epoch = resetEpoch;
+  const epoch = api.fences.resetEpoch;
   const state0 = api.get();
   const lf = state0.loadedFolders || {};
   const targetSet = new Set<string>();
@@ -442,12 +456,12 @@ async function runReconcilePass(
   // walk plus an index pass. A tree-wide Refresh across several sources multiplies
   // that again.
   const listed = await mapWithLimit(targets, RECONCILE_LIST_CONCURRENCY, async (folderKey) => {
-    const gen = nextFolderGeneration(folderKey);
+    const gen = nextFolderGeneration(api.fences, folderKey);
     const issuedAt = Date.now();
     try {
-      const res = await resolveList(agentId, projectId ?? undefined, { uri: folderKey, recursive: false });
+      const res = await resolveList(agentId, projectId ?? undefined, { uri: folderKey, recursive: false }, api.client);
       // A newer listing of the SAME folder superseded this one → drop it whole.
-      if (!isCurrentFolderGeneration(folderKey, gen)) return { folderKey, res: null, issuedAt, ok: false as const };
+      if (!isCurrentFolderGeneration(api.fences, folderKey, gen)) return { folderKey, res: null, issuedAt, ok: false as const };
       return { folderKey, res, issuedAt, ok: true as const };
     } catch {
       return { folderKey, res: null, issuedAt, ok: false as const };
@@ -455,7 +469,7 @@ async function runReconcilePass(
   });
 
   api.set((state: any) => {
-    if (epoch !== resetEpoch) return state; // the broom emptied the store mid-pass → inert
+    if (epoch !== api.fences.resetEpoch) return state; // the broom emptied the store mid-pass → inert
     const next = { ...state.files };
     const ts = Date.now();
     const pendingDelta: ListedPendingDelta = { add: new Set(), remove: new Set() };
@@ -612,7 +626,7 @@ async function runSourceReconcile(
   const { agentId, projectId, source, targets } = params;
   const wide = params.wide !== false;
   if (!agentId || !source) return;
-  const existing = reconcileJobs.get(source);
+  const existing = api.fences.reconcileJobs.get(source);
   if (existing) {
     existing.rerun = true;
     if (wide) existing.wide = true;
@@ -621,7 +635,7 @@ async function runSourceReconcile(
     return;
   }
   const job: ReconcileJob = { rerun: false, wide, extra: new Set(targets ?? []), promise: Promise.resolve() };
-  reconcileJobs.set(source, job);
+  api.fences.reconcileJobs.set(source, job);
   job.promise = (async () => {
     try {
       for (let pass = 0; pass < MAX_RECONCILE_PASSES; pass++) {
@@ -634,7 +648,7 @@ async function runSourceReconcile(
         if (!job.rerun) break;
       }
     } finally {
-      reconcileJobs.delete(source);
+      api.fences.reconcileJobs.delete(source);
     }
   })();
   await job.promise;
@@ -837,9 +851,11 @@ interface FilesystemStore extends FileSystemState, SearchSliceActions, ListSlice
   refreshTree: (params: { agentId: string; projectId: string | null }) => Promise<void>;
   /**
    * The dock broom's reach into this store (host → kernel port
-   * `onClientStateReset` → here). Matches the scope against the ACTIVE
-   * `(activeProjectId, activeAgentId)` pair (widget level: only the
-   * `filesystem` widget type); a non-matching scope is a no-op. A match applies
+   * `onClientStateReset` → `resetFilesClientState` → here). Matches the scope
+   * against the ACTIVE `(activeProjectId, activeAgentId)` pair; the `instance`
+   * and `widget` levels also need the `filesystem` widget type AND this store's
+   * own `windowId` — one window's clean or close never empties a sibling
+   * window, of the same agent included. A non-matching scope is a no-op. A match applies
    * the ONE `contextResetPatch` (the same wipe an agent/project switch does),
    * clears the persisted tab strip (`tabMeta` included — the allowlist is written
    * EMPTY, so a persisted `activeFile` cannot re-run the read/list race on the
@@ -856,6 +872,18 @@ interface FilesystemStore extends FileSystemState, SearchSliceActions, ListSlice
    * through `get()` — never a second copy.
    */
   fenceInFlightWriters: () => void;
+  /**
+   * The host's id of the Files window this store belongs to (`null` for a store
+   * no window owns). Identity like `activeAgentId`: no reset touches it, and it
+   * is never an authority source — it only addresses an `instance`/`widget` reset.
+   */
+  windowId: string | null;
+  /**
+   * The request client every API call of this store goes through — created with
+   * the store over the window's project and BOUND agent, so a request's headers
+   * never come from another mounted window (`api/index.ts`).
+   */
+  client: PackageApi;
   /** Dismiss the structural-operation banner (`organizeError`). */
   clearOrganizeError: () => void;
   /**
@@ -950,6 +978,7 @@ interface FilesystemStore extends FileSystemState, SearchSliceActions, ListSlice
   pendingReviewPaths: Set<string>;
   /** The caller's visible pending-review count (server `count_only`), shown on the Changes button. */
   pendingCount: number;
+  pendingCountState: 'exact' | 'partial' | 'stale';
   /** Re-read `pendingCount`; a newer call or another active context drops the answer. */
   refreshPendingCount: (params: { agentId: string; projectId: string | null }) => Promise<void>;
 
@@ -1078,7 +1107,11 @@ function readStoredSidebarWidth(): number {
   }
 }
 
-/** The localStorage payload (v2): prefs, the active triple, the context projections. */
+/**
+ * The localStorage payload (v2): prefs, the active triple, the per-agent context
+ * projections, and — OPTIONAL, absent until a window writes one — the per-window
+ * projections keyed by the host's window id (`PersistedFilesWindow`).
+ */
 type PersistedFilesShape = {
   previewEditorsEnabled: boolean;
   diffViewMode: DiffViewMode;
@@ -1086,9 +1119,39 @@ type PersistedFilesShape = {
   activeAgentId: string | null;
   activeProjectId: string | null;
   contexts: Record<string, PersistedFilesContext>;
+  windows?: Record<string, PersistedFilesWindow>;
 };
 
-export const useFilesystemStore = create<FilesystemStore>()(persist((set, get) => ({
+/** What a new store starts from: its window, its request client, the preferences and the seeded view. */
+export type FilesystemStoreInit = {
+  /** The request client every API call of this store goes through (see `FilesystemStore.client`). */
+  client: PackageApi;
+  windowId?: string | null;
+  userId?: string | null;
+  projectId?: string | null;
+  agentId?: string | null;
+  previewEditorsEnabled?: boolean;
+  diffViewMode?: DiffViewMode;
+  /** The window's persisted view — its own projection (a new window has none and starts from the defaults). */
+  projection?: Partial<PersistedFilesContext>;
+};
+
+export type FilesystemStoreApi = ZustandStoreApi<FilesystemStore>;
+
+/**
+ * ONE Files store per window: a live view that persists nothing itself — the
+ * ONE writer of `neuralis.filesystem.tabs` is `filesPersistence` below, which a
+ * mounted window feeds through `mountFilesWindow`. Every asynchronous fence and
+ * dedup map is created with the store (`StoreFences`, the list/search/git slice
+ * closures), so two windows — of two agents, or of the same agent — never fence,
+ * supersede or dedup each other.
+ */
+export function createFilesystemStore(init: FilesystemStoreInit): FilesystemStoreApi {
+  const fences = createStoreFences();
+  const client = init.client;
+  return createStore<FilesystemStore>()((set, get) => ({
+  windowId: init.windowId ?? null,
+  client,
   files: {},
   folderBadges: {},
   fileContentByPath: {},
@@ -1098,17 +1161,17 @@ export const useFilesystemStore = create<FilesystemStore>()(persist((set, get) =
   openFiles: [],
   activeFile: null,
   tabMeta: {},
-  activeUserId: null,
+  activeUserId: init.userId ?? null,
   contextStateByKey: {},
-  previewEditorsEnabled: false,
+  previewEditorsEnabled: init.previewEditorsEnabled ?? false,
   // Nothing is pre-expanded — under lazy hydration an expanded entry is a FETCH,
   // and every source branch (including `brain://`) starts collapsed.
   expandedFolders: new Set<string>(),
   sidebarOpen: true,
   sidebarWidth: readStoredSidebarWidth(),
   sidebarView: 'tree',
-  activeAgentId: null,
-  activeProjectId: null,
+  activeAgentId: init.agentId ?? null,
+  activeProjectId: init.projectId ?? null,
   sources: [],
   sourcesLoading: true,
   activeSource: null,
@@ -1119,7 +1182,7 @@ export const useFilesystemStore = create<FilesystemStore>()(persist((set, get) =
   activeWorkspaceTab: 'file',
   pendingSourceSuggestion: null,
   vectorHealthOpen: false,
-  diffViewMode: 'auto',
+  diffViewMode: init.diffViewMode ?? 'auto',
   pendingPanelFilter: {},
   // Nothing is hydrated at boot. `brain://` is EXPANDED by default (below) and the
   // tree's hydration effect lists it — marking it "loaded" here would suppress that
@@ -1132,6 +1195,7 @@ export const useFilesystemStore = create<FilesystemStore>()(persist((set, get) =
   snapshotError: undefined,
   pendingReviewPaths: new Set<string>(),
   pendingCount: 0,
+  pendingCountState: 'stale',
 
   ...searchSliceInitial,
   ...createSearchSlice(set as any, get),
@@ -1269,28 +1333,28 @@ export const useFilesystemStore = create<FilesystemStore>()(persist((set, get) =
       // Enumerated once, then hidden — no reconcile listed it off screen, so its rows
       // may be stale. ONE authoritative listing of exactly this folder (absence
       // applies), never a re-list of the whole visible tree.
-      await runSourceReconcile({ get, set }, { agentId, projectId, source: sourceFromUri(uri), targets: [uri], wide: false });
+      await runSourceReconcile({ get, set, fences, client }, { agentId, projectId, source: sourceFromUri(uri), targets: [uri], wide: false });
       return;
     }
 
-    const existing = liveFolderLoadInFlight.get(uri);
+    const existing = fences.liveFolderLoadInFlight.get(uri);
     if (existing) { await existing; return; }
 
     set((state: any) => ({ hydrationState: { ...(state.hydrationState || {}), [uri]: 'loading' as const } }));
 
     const task = (async () => {
-      const gen = nextFolderGeneration(uri);
+      const gen = nextFolderGeneration(fences, uri);
       const issuedAt = Date.now();
       try {
         // recursive:false → single `readdir` on the connector, ~50ms even on
         // million-file subtrees. Replaces the previous full-tree snapshot call.
-        const res = await resolveList(agentId, projectId ?? undefined, { uri, recursive: false });
+        const res = await resolveList(agentId, projectId ?? undefined, { uri, recursive: false }, client);
         // Superseded by a newer listing of the same folder (a concurrent reconcile
         // or a second expand) → drop this response instead of overwriting. Restore
         // the fetch state on the way out: returning bare left `loading` pinned
         // forever, and the refresh control is `disabled={loading}` — the one control
         // that could recover would have been disabled by the state it must clear.
-        if (!isCurrentFolderGeneration(uri, gen)) {
+        if (!isCurrentFolderGeneration(fences, uri, gen)) {
           set((state: any) => ({
             hydrationState: {
               ...(state.hydrationState || {}),
@@ -1327,8 +1391,8 @@ export const useFilesystemStore = create<FilesystemStore>()(persist((set, get) =
       }
     })();
 
-    liveFolderLoadInFlight.set(uri, task);
-    try { await task; } finally { liveFolderLoadInFlight.delete(uri); }
+    fences.liveFolderLoadInFlight.set(uri, task);
+    try { await task; } finally { fences.liveFolderLoadInFlight.delete(uri); }
   },
 
   clearOrganizeError: () => set(() => ({ organizeError: null })),
@@ -1345,31 +1409,32 @@ export const useFilesystemStore = create<FilesystemStore>()(persist((set, get) =
     }),
 
   async reconcileSourceFolders({ agentId, projectId, source }) {
-    await runSourceReconcile({ get, set }, { agentId, projectId, source });
+    await runSourceReconcile({ get, set, fences, client }, { agentId, projectId, source });
   },
 
   fenceInFlightWriters() {
-    resetEpoch += 1;
-    for (const key of Array.from(folderGeneration.keys())) nextFolderGeneration(key);
+    fences.resetEpoch += 1;
+    for (const key of Array.from(fences.folderGeneration.keys())) nextFolderGeneration(fences, key);
     // The dedup maps only; the in-flight tasks' own `finally` deletes a missing
     // key as a no-op. `reconcileJobs` is deliberately NOT cleared: a running job's
     // `finally` would then delete the NEXT job's entry and two passes would run
     // concurrently — the job runs to completion and the epoch makes it inert.
-    liveFolderLoadInFlight.clear();
-    rehydrateInFlight.clear();
+    fences.liveFolderLoadInFlight.clear();
+    fences.rehydrateInFlight.clear();
   },
 
   resetClientState(scope) {
     const s = get();
     if (!s.activeProjectId || scope.projectId !== s.activeProjectId) return;
     if (scope.level !== 'project' && scope.agentId !== s.activeAgentId) return;
-    if (scope.level === 'widget' && scope.widgetType !== FILESYSTEM_WIDGET_TYPE) return;
+    if ((scope.level === 'widget' || scope.level === 'instance')
+      && (scope.widgetType !== FILESYSTEM_WIDGET_TYPE || scope.instanceId !== s.windowId)) return;
     // Fence FIRST, then wipe: a read/listing/reconcile that resolves after this
     // point finds a stale epoch (or a stale folder generation) and writes nothing.
     get().fenceInFlightWriters();
     // The broom is the ONE writer that drops a stashed context — its own scope
-    // only: the widget/agent levels drop this context, the project level every
-    // context of the project (this user's). Other projects are not its business.
+    // only: the instance/widget/agent levels drop this context, the project level
+    // every context of the project (this user's). Other projects are not its business.
     const prefix = `${s.activeUserId ?? ''}::${s.activeProjectId}::`;
     const own = contextKey(s.activeUserId, s.activeProjectId, s.activeAgentId ?? '');
     const kept: Record<string, Record<string, unknown>> = {};
@@ -1408,7 +1473,7 @@ export const useFilesystemStore = create<FilesystemStore>()(persist((set, get) =
     if (bySource.size === 0) return;
     await Promise.all(
       Array.from(bySource.entries()).map(([source, targets]) =>
-        runSourceReconcile({ get, set }, { agentId, projectId, source, targets }),
+        runSourceReconcile({ get, set, fences, client }, { agentId, projectId, source, targets }),
       ),
     );
   },
@@ -1430,7 +1495,7 @@ export const useFilesystemStore = create<FilesystemStore>()(persist((set, get) =
       if (source) sources.add(source);
     }
     await Promise.all(
-      Array.from(sources).map((source) => runSourceReconcile({ get, set }, { agentId, projectId, source })),
+      Array.from(sources).map((source) => runSourceReconcile({ get, set, fences, client }, { agentId, projectId, source })),
     );
   },
 
@@ -1445,8 +1510,8 @@ export const useFilesystemStore = create<FilesystemStore>()(persist((set, get) =
     const agentId = s.activeAgentId;
     if (!uri || !agentId) return;
     if (hasCompletedRead(s, uri)) return;
-    if (rehydrateInFlight.has(uri)) return;
-    rehydrateInFlight.add(uri);
+    if (fences.rehydrateInFlight.has(uri)) return;
+    fences.rehydrateInFlight.add(uri);
     try {
       // A tab from another agent's source reads through that agent, as the tree
       // open did — never through a SENTINEL (`__system__` is the writer the
@@ -1459,7 +1524,7 @@ export const useFilesystemStore = create<FilesystemStore>()(persist((set, get) =
       // rehydrate is not a user open.
       await s.openFile({ agentId, projectId: s.activeProjectId, uri, readAgentId, revealPane: false });
     } finally {
-      rehydrateInFlight.delete(uri);
+      fences.rehydrateInFlight.delete(uri);
     }
   },
 
@@ -1679,8 +1744,8 @@ export const useFilesystemStore = create<FilesystemStore>()(persist((set, get) =
     // The server-side work completes whatever happens to the store; every store
     // write after an await is fenced — a context reset mid-save must not re-key,
     // fill, dirty-flag or re-open anything under the new context.
-    const epoch = resetEpoch;
-    const fenced = () => epoch !== resetEpoch;
+    const epoch = fences.resetEpoch;
+    const fenced = () => epoch !== fences.resetEpoch;
 
     let effectiveUri = fromUri;
     if (moved) {
@@ -1690,7 +1755,7 @@ export const useFilesystemStore = create<FilesystemStore>()(persist((set, get) =
         id: node.id,
         uri: fromUri,
         move: targetUri,
-      });
+      }, client);
       if (!res || res.ok !== true) throw new Error(writeRefusalMessage(res, 'Move failed'));
       effectiveUri = targetUri;
       if (fenced()) return { uri: effectiveUri, moved, contentChanged: false };
@@ -1704,7 +1769,7 @@ export const useFilesystemStore = create<FilesystemStore>()(persist((set, get) =
         id: node.id,
         uri: effectiveUri,
         overwrite: { content },
-      });
+      }, client);
       if (!res || res.ok !== true) throw new Error(writeRefusalMessage(res, 'Save failed'));
       if (fenced()) return { uri: effectiveUri, moved, contentChanged };
       // After a move the node lives under its NEW uri (`replaceFilePath` re-keys
@@ -1726,32 +1791,38 @@ export const useFilesystemStore = create<FilesystemStore>()(persist((set, get) =
 
   async refreshPendingCount({ agentId, projectId }) {
     if (!agentId) return;
-    const mine = ++pendingCountSeq;
+    const mine = ++fences.pendingCountSeq;
     // A failed count keeps the last known number — the next event, focus or reconnect re-asks.
-    let count: number;
-    try { count = await countPendingChanges({ agentId, ...(projectId ? { projectId } : {}) }); } catch { return; }
+    let count: Awaited<ReturnType<typeof countPendingChanges>>;
+    try { count = await countPendingChanges({ agentId, ...(projectId ? { projectId } : {}) }, client); } catch {
+      if (mine === fences.pendingCountSeq && get().activeAgentId === agentId && get().activeProjectId === projectId) set({ pendingCountState: 'stale' });
+      return;
+    }
     // No reset-epoch fence: the count is the context's own server answer, so one
     // that resolves after a reset of the SAME context is still right; the context
     // check below is what keeps another context's number out.
-    if (mine !== pendingCountSeq) return;
+    if (mine !== fences.pendingCountSeq) return;
     const s = get();
     if (s.activeAgentId !== agentId || s.activeProjectId !== projectId) return;
-    set(() => ({ pendingCount: count }));
+    if (count.unavailable?.includes('journal') && count.unavailable.includes('vector')) {
+      set({ pendingCountState: 'stale' }); return;
+    }
+    set(() => ({ pendingCount: count.count, pendingCountState: count.exact ? 'exact' : 'partial' }));
   },
 
   async markFileDeleted({ agentId, projectId, node }) {
-    const epoch = resetEpoch;
+    const epoch = fences.resetEpoch;
     const res = await writeFile({
       agentId,
       ...(projectId ? { projectId } : {}),
       id: node.id,
       uri: node.uri,
       delete: true,
-    });
+    }, client);
     if (!res || res.ok !== true) throw new Error(writeRefusalMessage(res, 'Delete failed'));
     // The reconcile flags an unloaded source dirty — not a no-op on a store the
     // reset just handed to another context.
-    if (epoch !== resetEpoch) return;
+    if (epoch !== fences.resetEpoch) return;
     await get().reconcileFolders({ agentId, projectId, folders: [folderUri(node.uri)] });
   },
 
@@ -1772,7 +1843,7 @@ export const useFilesystemStore = create<FilesystemStore>()(persist((set, get) =
         id,
         uri: fromUri,
         move: destinationUri,
-      });
+      }, client);
     } catch (e) {
       console.error('[Filesystem] move failed', fromUri, e);
       set(() => ({ organizeError: 'Move failed' }));
@@ -1801,7 +1872,7 @@ export const useFilesystemStore = create<FilesystemStore>()(persist((set, get) =
       // of the old subtree would stay in the store forever. Prune by prefix (the
       // pattern `renameNode` already proved) and force-relist the destination.
       if (!retained) {
-        prunePrefix({ get, set }, fromUri);
+        prunePrefix({ get, set, fences, client }, fromUri);
       }
       await get().ensureFolderLoaded({ agentId, projectId, uri: toFolderUri, force: true });
     } else {
@@ -1842,7 +1913,7 @@ export const useFilesystemStore = create<FilesystemStore>()(persist((set, get) =
         id,
         uri,
         move: isFolder ? destinationUri : trimmed,
-      });
+      }, client);
     } catch (e) {
       console.error('[Filesystem] rename failed', uri, e);
       set(() => ({ organizeError: 'Rename failed' }));
@@ -1861,7 +1932,7 @@ export const useFilesystemStore = create<FilesystemStore>()(persist((set, get) =
       // tombstoned the old one. Prune the stale old subtree from the store and
       // force-relist the parent so the renamed folder surfaces immediately (the
       // non-recursive `refresh` alone would not re-list a nested folder's parent).
-      prunePrefix({ get, set }, uri);
+      prunePrefix({ get, set, fences, client }, uri);
       await get().ensureFolderLoaded({ agentId, projectId, uri: parent, force: true });
     } else {
       get().replaceFilePath(uri, destinationUri);
@@ -1873,11 +1944,11 @@ export const useFilesystemStore = create<FilesystemStore>()(persist((set, get) =
     const trimmed = (name ?? '').trim();
     if (!agentId || !parentUri || !trimmed) return;
     const targetUri = parentUri.endsWith('://') ? `${parentUri}${trimmed}` : `${parentUri}/${trimmed}`;
-    const epoch = resetEpoch;
+    const epoch = fences.resetEpoch;
     try {
       if (kind === 'folder') {
-        const res = await writeFile({ agentId, ...(projectId ? { projectId } : {}), uri: targetUri, mkdir: true });
-        if (res?.ok && epoch === resetEpoch) {
+        const res = await writeFile({ agentId, ...(projectId ? { projectId } : {}), uri: targetUri, mkdir: true }, client);
+        if (res?.ok && epoch === fences.resetEpoch) {
           // Optimistic folder node — an EMPTY folder has no vector node, so only a
           // connector-live re-list surfaces it; seed it now so it appears instantly.
           set((state) => {
@@ -1908,7 +1979,7 @@ export const useFilesystemStore = create<FilesystemStore>()(persist((set, get) =
           file: new File([''], trimmed),
           uri: parentUri,
           tags: [],
-        });
+        }, client);
       }
     } catch (e) {
       console.error('[Filesystem] create failed', kind, targetUri, e);
@@ -1931,11 +2002,11 @@ export const useFilesystemStore = create<FilesystemStore>()(persist((set, get) =
       touched.add(folderUri(src));
       try {
         if (op === 'copy') {
-          const res = await writeFile({ agentId, ...(projectId ? { projectId } : {}), uri: src, copy: dest });
+          const res = await writeFile({ agentId, ...(projectId ? { projectId } : {}), uri: src, copy: dest }, client);
           if (res && res.ok === false) rejected.push(base);
         } else {
           // 200-with-`ok:false` is a REJECTED move — collect it, never treat it as done.
-          const res = await writeFile({ agentId, ...(projectId ? { projectId } : {}), uri: src, move: dest });
+          const res = await writeFile({ agentId, ...(projectId ? { projectId } : {}), uri: src, move: dest }, client);
           if (res && res.ok === false) rejected.push(base);
           else if (res?.warning === 'moved_with_source_retained') rejected.push(`${base} (original retained)`);
           else if (get().files[src]?.type === 'folder') {
@@ -1944,7 +2015,7 @@ export const useFilesystemStore = create<FilesystemStore>()(persist((set, get) =
             // inspects direct children — so the old prefix has to go here or its
             // interior lingers. Cut/paste reaches this path too, and only the drag
             // path used to handle it.
-            prunePrefix({ get, set }, src);
+            prunePrefix({ get, set, fences, client }, src);
           }
         }
       } catch (e) {
@@ -1974,7 +2045,7 @@ export const useFilesystemStore = create<FilesystemStore>()(persist((set, get) =
           id: t.id,
           uri: t.uri,
           delete: true,
-        });
+        }, client);
         if (res && res.ok === false) {
           // 200-with-`ok:false`. A FOLDER delete can still have removed N files
           // before failing — `affected`/`failed` carry that partial outcome, and
@@ -1990,7 +2061,7 @@ export const useFilesystemStore = create<FilesystemStore>()(persist((set, get) =
         if (isFolder) {
           // A folder delete removes the whole subtree server-side; prune by prefix so
           // the interior cannot linger (the reconcile only inspects direct children).
-          prunePrefix({ get, set }, t.uri);
+          prunePrefix({ get, set, fences, client }, t.uri);
         } else {
           // Optimistic: strike the node (revertible tombstone). The targeted
           // reconcile below converges to server truth — a tracked node KEEPS the
@@ -2074,16 +2145,16 @@ export const useFilesystemStore = create<FilesystemStore>()(persist((set, get) =
       (typeof st.fileContentByPath[uri] === 'string' && (st.fileContentByPath[uri]?.length || 0) > 0);
     if (!force && hasContent) return;
 
-    const epoch = resetEpoch;
+    const epoch = fences.resetEpoch;
     try {
       const res = await readFiles({
         agentId: readAgentId || agentId,
         ...(projectId ? { projectId } : {}),
         files: [uri],
-      });
+      }, client);
       // The broom ran while the read was in flight: the tab is gone, the store is
       // empty, and this answer must not put either back.
-      if (epoch !== resetEpoch) return;
+      if (epoch !== fences.resetEpoch) return;
       const files = extractReadFilesPayload(res);
       if (files.length > 0) {
         const f = files[0];
@@ -2193,7 +2264,7 @@ export const useFilesystemStore = create<FilesystemStore>()(persist((set, get) =
     } catch (e) {
       const message = e instanceof Error ? e.message : 'Read failed';
       console.error('[Filesystem] read failed', e);
-      if (epoch !== resetEpoch) return;
+      if (epoch !== fences.resetEpoch) return;
       set((state) => ({
         files: {
           ...state.files,
@@ -2253,7 +2324,7 @@ export const useFilesystemStore = create<FilesystemStore>()(persist((set, get) =
     const targetUri = uri || 'brain://docs';
     set(() => ({ uploading: true }));
     try {
-      await uploadFile({ agentId, ...(projectId ? { projectId } : {}), file, uri: targetUri, tags: ['upload'] });
+      await uploadFile({ agentId, ...(projectId ? { projectId } : {}), file, uri: targetUri, tags: ['upload'] }, client);
       await get().reconcileFolders({ agentId, projectId, folders: [targetUri] });
     } finally {
       set(() => ({ uploading: false }));
@@ -2268,25 +2339,43 @@ export const useFilesystemStore = create<FilesystemStore>()(persist((set, get) =
     set(() => ({ uploading: true }));
     try {
       for (const file of list) {
-        await uploadFile({ agentId, ...(projectId ? { projectId } : {}), file, uri: targetUri, tags: ['upload'] });
+        await uploadFile({ agentId, ...(projectId ? { projectId } : {}), file, uri: targetUri, tags: ['upload'] }, client);
       }
       await get().reconcileFolders({ agentId, projectId, folders: [targetUri] });
     } finally {
       set(() => ({ uploading: false }));
     }
   },
+  // The window's persisted view, lifted into the flat fields — after every
+  // default above, so a seeded tab strip is what the first render shows.
+  ...(init.projection ? sliceFromPersisted(init.projection) : {}),
+}));
+}
+
+/**
+ * The ONE writer of `neuralis.filesystem.tabs` (v2). Window stores persist
+ * nothing; a mounted window feeds its projection here (`mountFilesWindow`), so
+ * two windows writing the same key can never overwrite each other's view — the
+ * whole record is written from this one in-memory owner.
+ *
+ * What it holds: the preferences, the legacy per-agent `contexts` (the record an
+ * older build wrote — never read into a window, pruned by the broom, otherwise
+ * left as it is: never rewritten, re-keyed or converted), and the optional
+ * `windows` map — one `PersistedFilesWindow` per window, carrying the
+ * user/project/agent it was written for. A record without `windows` reads
+ * without one and is not written back until a window really changes.
+ */
+export const filesPersistence = createStore<PersistedFilesShape>()(persist((): PersistedFilesShape => ({
+  previewEditorsEnabled: false,
+  diffViewMode: 'auto',
+  activeUserId: null,
+  activeAgentId: null,
+  activeProjectId: null,
+  contexts: {},
 }), {
-  // Persist the prefs, the active triple and the CONTEXT SPACE as projections
-  // (`PersistedFilesContext` per context — tab shape, expanded folders as an
-  // array, sidebar view, panels, last-touched folder): the active context's
-  // projection is taken off the flat fields on every write, the others off
-  // `contextStateByKey`. NEVER the `files`/content dicts or a `Set` as such —
-  // `pendingReviewPaths` is derived from `files` and stays in memory.
-  // `sidebarWidth` keeps its own hand-persist. On rehydrate (`merge`) the active
-  // context's projection lands in the flat fields so `loadList`'s same-context
-  // guard keeps them on a page refresh, and every other context waits in the
-  // space for its switch-back. v2 (2026-09-04): the flat tab trio became the
-  // context space; `migrate` lifts a v1 payload's trio into the active context.
+  // v2 (2026-09-04): the flat tab trio became the context space; `migrate` lifts
+  // a v1 payload's trio into the active context. The optional `windows` map is
+  // additive — no version bump, an absent map stays absent.
   name: 'neuralis.filesystem.tabs',
   version: 2,
   migrate: (persistedState, version) => {
@@ -2322,44 +2411,236 @@ export const useFilesystemStore = create<FilesystemStore>()(persist((set, get) =
   merge: (persistedState, currentState) => {
     const p = persistedState as Partial<PersistedFilesShape> | undefined;
     if (!p) return currentState;
-    const contexts = p.contexts ?? {};
-    const activeKey = p.activeAgentId ? contextKey(p.activeUserId ?? null, p.activeProjectId ?? null, p.activeAgentId) : null;
-    const space: Record<string, Record<string, unknown>> = {};
-    for (const [key, projection] of Object.entries(contexts)) {
-      if (key !== activeKey) space[key] = sliceFromPersisted(projection);
-    }
-    const active = activeKey && contexts[activeKey] ? sliceFromPersisted(contexts[activeKey]) : {};
     return {
-      ...currentState,
       previewEditorsEnabled: p.previewEditorsEnabled ?? currentState.previewEditorsEnabled,
       diffViewMode: p.diffViewMode ?? currentState.diffViewMode,
       activeUserId: p.activeUserId ?? null,
       activeAgentId: p.activeAgentId ?? null,
       activeProjectId: p.activeProjectId ?? null,
-      ...active,
-      contextStateByKey: space,
-    } as FilesystemStore;
+      contexts: p.contexts ?? {},
+      ...(p.windows ? { windows: p.windows } : {}),
+    };
   },
   storage: createJSONStorage(() =>
     typeof window !== 'undefined' && window.localStorage
       ? window.localStorage
       : { getItem: () => null, setItem: () => undefined, removeItem: () => undefined },
   ),
-  partialize: (state): PersistedFilesShape => {
-    const contexts: Record<string, PersistedFilesContext> = {};
-    for (const [key, slice] of Object.entries(state.contextStateByKey)) contexts[key] = persistedContext(slice);
-    if (state.activeAgentId) {
-      contexts[contextKey(state.activeUserId, state.activeProjectId, state.activeAgentId)] = persistedContext(
-        state as unknown as Record<string, unknown>,
-      );
-    }
-    return {
-      previewEditorsEnabled: state.previewEditorsEnabled,
-      diffViewMode: state.diffViewMode,
-      activeUserId: state.activeUserId,
-      activeAgentId: state.activeAgentId,
-      activeProjectId: state.activeProjectId,
-      contexts,
-    };
-  },
+  // NEVER the `files`/content dicts or a `Set` as such — every projection is a
+  // `persistedContext` allowlist (Sets as arrays). `sidebarWidth` keeps its own
+  // hand-persist.
+  partialize: (state): PersistedFilesShape => ({
+    previewEditorsEnabled: state.previewEditorsEnabled,
+    diffViewMode: state.diffViewMode,
+    activeUserId: state.activeUserId,
+    activeAgentId: state.activeAgentId,
+    activeProjectId: state.activeProjectId,
+    contexts: state.contexts,
+    ...(state.windows ? { windows: state.windows } : {}),
+  }),
 }));
+
+/** The live identity of one Files window: the host's window id, the signed-in user, the project and the BOUND agent. */
+export type FilesWindowIdentity = { windowId: string; userId: string; projectId: string; agentId: string };
+
+function sameWindowIdentity(entry: PersistedFilesWindow, id: FilesWindowIdentity): boolean {
+  return entry.userId === id.userId && entry.projectId === id.projectId && entry.agentId === id.agentId;
+}
+
+/** A window projection without its identity fields — the shape `sliceFromPersisted` reads. */
+function viewOf(entry: PersistedFilesWindow): PersistedFilesContext {
+  const { userId: _u, projectId: _p, agentId: _a, ...view } = entry;
+  return view;
+}
+
+/**
+ * A new window store. Its view comes from the window's OWN projection when the
+ * record holds one written for this LIVE identity; a projection written for
+ * another user, project or agent is ignored, and a window with no projection
+ * of its own starts from the defaults. The older per-agent `contexts` entries
+ * are never read into a window (no ID translation from an agent key to a
+ * window id): an upgrade resets the open tabs once.
+ */
+export function createFilesWindowStore(id: FilesWindowIdentity): FilesystemStoreApi {
+  const record = filesPersistence.getState();
+  const own = record.windows?.[id.windowId];
+  const projection = own && sameWindowIdentity(own, id) ? viewOf(own) : undefined;
+  return createFilesystemStore({
+    client: createPackageApi({ slug: 'brain-core', getProjectId: () => id.projectId, getAgentId: () => id.agentId }),
+    windowId: id.windowId,
+    userId: id.userId,
+    projectId: id.projectId,
+    agentId: id.agentId,
+    previewEditorsEnabled: record.previewEditorsEnabled,
+    diffViewMode: record.diffViewMode,
+    ...(projection ? { projection } : {}),
+  });
+}
+
+/** The fields `persistedContext` reads — a store update that changed none of them changed no projection. */
+const PROJECTION_INPUTS = [
+  'openFiles', 'activeFile', 'tabMeta', 'expandedFolders',
+  'sidebarView', 'activeWorkspaceTab', 'workspacePanels', 'activeFolderPath',
+] as const;
+
+/**
+ * Feed ONE window's view into the persistence owner while it is mounted. Per
+ * store update: O(1) — eight reference compares; only an update that touched a
+ * projection input serializes the projection, and only a projection that
+ * differs from the last one written reaches the owner (which serializes the
+ * whole allowlisted record once). Returns the unsubscribe.
+ */
+function bindWindowPersistence(store: FilesystemStoreApi, id: FilesWindowIdentity): () => void {
+  let last = JSON.stringify(persistedContext(store.getState() as unknown as Record<string, unknown>));
+  return store.subscribe((state, prev) => {
+    if (state.previewEditorsEnabled !== prev.previewEditorsEnabled || state.diffViewMode !== prev.diffViewMode) {
+      const owner = filesPersistence.getState();
+      if (owner.previewEditorsEnabled !== state.previewEditorsEnabled || owner.diffViewMode !== state.diffViewMode) {
+        filesPersistence.setState({ previewEditorsEnabled: state.previewEditorsEnabled, diffViewMode: state.diffViewMode });
+      }
+    }
+    if (!PROJECTION_INPUTS.some((key) => state[key] !== prev[key])) return;
+    // The view belongs to the window's own identity; a store that left it writes nothing.
+    if (state.activeUserId !== id.userId || state.activeProjectId !== id.projectId || state.activeAgentId !== id.agentId) return;
+    const view = persistedContext(state as unknown as Record<string, unknown>);
+    const json = JSON.stringify(view);
+    if (json === last) return;
+    last = json;
+    filesPersistence.setState((owner) => ({
+      windows: {
+        ...(owner.windows ?? {}),
+        [id.windowId]: { userId: id.userId, projectId: id.projectId, agentId: id.agentId, ...view },
+      },
+    }));
+  });
+}
+
+type LiveFilesWindow = { identity: FilesWindowIdentity; store: FilesystemStoreApi };
+
+/** Every mounted Files window — hidden and minimized ones included (they stay mounted). */
+const liveFilesWindows = new Set<LiveFilesWindow>();
+
+/** The signed-in user, from the workspace provider — which user's records a broom prunes. */
+let liveFilesUserId: string | null = null;
+
+export function setFilesLiveUser(userId: string | null): void {
+  liveFilesUserId = userId;
+}
+
+/**
+ * Register a window store while it is mounted: the reset fan-out reaches it and
+ * its view feeds the persistence owner. The disposer drops the subscription and
+ * fences the store's in-flight readers — the persisted view stays (closing or
+ * hiding a window is not a reset).
+ */
+export function mountFilesWindow(store: FilesystemStoreApi, identity: FilesWindowIdentity): () => void {
+  const entry: LiveFilesWindow = { identity, store };
+  liveFilesWindows.add(entry);
+  const unbind = bindWindowPersistence(store, identity);
+  return () => {
+    unbind();
+    liveFilesWindows.delete(entry);
+    store.getState().fenceInFlightWriters();
+  };
+}
+
+function scopeReachesWindow(scope: ClientStateResetScope, id: FilesWindowIdentity): boolean {
+  if (scope.projectId !== id.projectId) return false;
+  if (scope.level === 'project') return true;
+  if (scope.agentId !== id.agentId) return false;
+  return scope.level === 'agent' || scope.instanceId === id.windowId;
+}
+
+/**
+ * The persisted half of a broom, applied to the ONE record: `instance` drops that
+ * window's projection; `widget` drops it AND the legacy (user, project, agent)
+ * context — the type-clean meaning that level always had; `agent` / `project`
+ * drop the legacy contexts and the window projections of their scope. Only the
+ * signed-in user's records; another user's, project's or agent's stay.
+ */
+function resetPersistedFiles(scope: ClientStateResetScope, userId: string | null): void {
+  if ((scope.level === 'instance' || scope.level === 'widget') && scope.widgetType !== FILESYSTEM_WIDGET_TYPE) return;
+  const record = filesPersistence.getState();
+  const dropWindow = (windowId: string, entry: PersistedFilesWindow): boolean => {
+    if (entry.projectId !== scope.projectId) return false;
+    if (scope.level === 'instance' || scope.level === 'widget') return windowId === scope.instanceId && entry.agentId === scope.agentId;
+    if (userId === null || entry.userId !== userId) return false;
+    return scope.level === 'project' || entry.agentId === scope.agentId;
+  };
+  const dropContext = (key: string): boolean => {
+    if (scope.level === 'instance') return false;
+    if (scope.level === 'project') return key.startsWith(`${userId ?? ''}::${scope.projectId}::`);
+    return key === contextKey(userId, scope.projectId, scope.agentId);
+  };
+  let windows = record.windows;
+  for (const [windowId, entry] of Object.entries(record.windows ?? {})) {
+    if (!dropWindow(windowId, entry)) continue;
+    if (windows === record.windows) windows = { ...record.windows };
+    delete windows![windowId];
+  }
+  let contexts = record.contexts;
+  for (const key of Object.keys(record.contexts)) {
+    if (!dropContext(key)) continue;
+    if (contexts === record.contexts) contexts = { ...record.contexts };
+    delete contexts[key];
+  }
+  if (windows === record.windows && contexts === record.contexts) return;
+  filesPersistence.setState({ contexts, ...(windows ? { windows } : {}) });
+}
+
+/**
+ * The ONE handler behind the install-level `port.onClientStateReset`
+ * subscription: the matching live window stores first (each wipe re-feeds its
+ * own, now empty, view), then the persisted record — so an `instance` / `widget`
+ * reset leaves that window's projection absent and a sibling's untouched.
+ * O(mounted Files windows) per broom event.
+ */
+export function resetFilesClientState(scope: ClientStateResetScope): void {
+  for (const live of liveFilesWindows) {
+    if (scopeReachesWindow(scope, live.identity)) live.store.getState().resetClientState(scope);
+  }
+  resetPersistedFiles(scope, liveFilesUserId);
+}
+
+/**
+ * The store of the Files window being rendered: created once per LIVE identity
+ * (window, user, project, bound agent) — a different user or project is a
+ * different store, never a re-used one — and mounted for the window's lifetime.
+ * `null` until the identity is known: nothing persisted is read, and nothing
+ * paints, before the live user and project are.
+ */
+export function useFilesWindowStore(
+  windowId: string | null | undefined,
+  userId: string | null | undefined,
+  projectId: string | null | undefined,
+  agentId: string | null | undefined,
+): FilesystemStoreApi | null {
+  const live = useMemo(() => {
+    if (!windowId || !userId || !projectId || !agentId) return null;
+    const identity: FilesWindowIdentity = { windowId, userId, projectId, agentId };
+    return { identity, store: createFilesWindowStore(identity) };
+  }, [windowId, userId, projectId, agentId]);
+  // Layout phase: registered (and its persistence bound) before any child's
+  // passive effect issues the first request; disposed before the next paint.
+  useLayoutEffect(() => (live ? mountFilesWindow(live.store, live.identity) : undefined), [live]);
+  return live?.store ?? null;
+}
+
+const FilesystemStoreContext = createContext<FilesystemStoreApi | null>(null);
+
+/** Puts a window's store under its Files tree; every `useFilesystemStore` below reads THIS window's store. */
+export function FilesystemStoreProvider({ store, children }: { store: FilesystemStoreApi; children?: ReactNode }) {
+  return createElement(FilesystemStoreContext.Provider, { value: store }, children);
+}
+
+/** The window's store itself, for imperative reads/writes outside a selector (event handlers, the SSE hook). */
+export function useFilesystemStoreApi(): FilesystemStoreApi {
+  const store = useContext(FilesystemStoreContext);
+  if (!store) throw new Error('useFilesystemStore must be used inside a Files window (FilesystemStoreProvider)');
+  return store;
+}
+
+/** Select from the store of the Files window this component renders in. */
+export function useFilesystemStore<T>(selector: (state: FilesystemStore) => T): T {
+  return useStore(useFilesystemStoreApi(), selector);
+}