@neuralis/brain-core 0.2.0 → 0.2.1

package/app/filesystem/domain/types.ts

@@ -699,6 +699,18 @@ export interface PersistedFilesContext {
   activeFolderPath: string | null;
 }
 
+/**
+ * ONE Files window's reload-surviving view, keyed in the persisted record by the
+ * host's window id: the same allowlist as `PersistedFilesContext`, plus the
+ * user, project and bound agent it was written for — a projection whose identity
+ * does not match the LIVE one is ignored, never applied.
+ */
+export interface PersistedFilesWindow extends PersistedFilesContext {
+  userId: string;
+  projectId: string;
+  agentId: string;
+}
+
 // ---------------------------------------------------------------------------
 // API response shapes (re-declared locally so the package is self-contained)
 // ---------------------------------------------------------------------------

package/app/filesystem/hooks/README.md

@@ -1,10 +1,10 @@
 # brain-core/app/filesystem/hooks
 
-React hooks used by the Files widget: container-width detection, viewport diff loading and the filesystem SSE consumer.
+React hooks used by the Files widget: viewport diff loading and the filesystem SSE consumer. The container-width hook is a shared kernel client export.
 
 ## Responsibility
 
-- `useContainerWidth(ref, options)` — observe an element and report whether it is "wide" (≥ threshold), with hysteresis so the diff views' auto unified↔split flip does not strobe while the user drags the widget across the boundary. Consumers: `GitFileDiff`, `FileEditor`.
+- `GitFileDiff` and `FileEditor` import `useContainerWidth` from `@neuralis/package-system/client`. There is no package-local responsive hook.
 - `useFilesystemSSE(agentId, projectId)` — subscribe to the brain-core `filesystem` channel and dispatch the right store updates. Event types: `filesystem:created`/`updated`/`deleted`/`reverted` (per-file activity), `sync:completed` (source-scoped backstop — skipped when every change count, `filesMoved` and separate `chunksRemoved` included, says zero; a missing count is unknown and still re-lists, and a `purge` job never skips, because its removal count comes from a `deleteByFilter` and proves nothing), a `changeType:'badge'` git-state signal, and a `changeType:'structure'` + `external:true` EXTERNAL connector file change (brisk-kingfisher).
 
 - `useVisibleDiffCards(root)` — one viewport observer (cards within ~2 screens count as visible) and `CONTENT_LANES` (3) content lanes per Changes/history scroller, plus an LRU answer cache (200 entries / ~8 MB estimated) keyed by the caller — record or file, its `updatedAt`/mode and the source revision — so a card re-entering the viewport sends nothing and any change is a new key; `fresh` replaces an answer after a mutation. Pending previews defer to the observer; a git diff in the virtualized Changes list reads on mount (the virtualizer — overscan 4 — is that list's ONE mount bound) and paints its first frame from the synchronous `peek(key, family)` (the exact key, else the target's newest cached revision, shown as stale until its own answer lands — staging stays disabled meanwhile). The caller validates its current revision before queued work runs.
@@ -14,7 +14,7 @@ React hooks used by the Files widget: container-width detection, viewport diff l
 
 ## Public Surface
 
-- `useContainerWidth<T extends HTMLElement>(ref, options?: { wideThresholdPx?, hysteresisPx? }): boolean` — defaults 900 / 60.
+- Responsive hook contracts live in the kernel client export map; existing Files callers retain their width thresholds and hysteresis.
 - `useFilesystemSSE(agentId: string | undefined, projectId: string | null): void` — side-effecting hook; returns nothing.
 - `useDiscoverableSources(params): readonly DiscoverableSourceSuggestion[]` — empty until the first response lands, and empty again immediately on a context change.
   - **The "already fetched" latch is a REF, never state.** As state it is a dependency of the effect it guards: committing it re-runs the effect, the first instance's cleanup cancels the in-flight request, and the second returns at the guard and never re-fetches. Live symptom: the request 200s with real data, there is no console error and no banner, and the dock renders nothing — invisible to any presentational test. Pinned by `test/ui/useDiscoverableSources.test.tsx` (5 of its 8 cases fail on the old shape).
@@ -25,7 +25,7 @@ React hooks used by the Files widget: container-width detection, viewport diff l
 ## How it plugs into the package-system kernel
 
 - `useFilesystemSSE` subscribes through `WorkspaceHostPort.subscribeRealtime({ channel: 'filesystem', agentId, projectId, onEvent })` (via `getFilesystemHostImperative().subscribeFilesystemEvents`) — the shared, multiplexed `/api/events` hub owned by the host, NOT a per-widget `EventSource` (the SSE-consolidation invariant: never open a per-widget connection — see `docs/architect/realtime-transport.md`). The hub owns reconnect/backoff; the host route is gated by `drive.read`.
-- Handlers dispatch into `useFilesystemStore` actions per event: `upsertFileNodeFromEvent` (per-file), `reconcileSourceFolders` (`sync:completed` and the `external:true` branch — both EARLY short-circuits BEFORE the `uri` guard, because the payload `uri` is the bare `<source>://` and would otherwise fabricate a phantom root node), `reconcileFolders` (a `changeType:'structure'` create/update/delete/revert — the affected PARENTS, never a global refresh), `ensureFolderLoaded({force})` + `refresh` (badge → `FileNode.git` subtree re-list + `SourceInfo.git` summaries), and `setSourceDirty` for a source that is not hydrated. An external change and a changing `sync:completed` share ONE per-source reconcile schedule: a trailing debounce (`RECONCILE_QUIET_MS` = 2 s — every event restarts it) bounded by a max-wait (`RECONCILE_MAX_WAIT_MS` = 6 s from the window's first event), so one agent turn's burst costs one or two passes of the visible folders instead of one per event, and a continuous burst still converges. The quiet window is sized on a measured turn, whose events arrive up to ~1.8 s apart. Pending passes are dropped on unmount and on an agent/project change. The badge branch keeps its own 250 ms timers (it does different work; a shared key would let one cancel the other). Badge/status and reconnect callbacks publish source revisions for Changes; timers are cancelled on context changes, and an epoch check prevents an old reconnect response from publishing into the new context.
+- Handlers dispatch into the actions of the window's OWN store (`useFilesystemStore` / `useFilesystemStoreApi`) per event; a frame the hub delivers after the scope changed (agent, project or store) is dropped, never applied to the next scope: `upsertFileNodeFromEvent` (per-file), `reconcileSourceFolders` (`sync:completed` and the `external:true` branch — both EARLY short-circuits BEFORE the `uri` guard, because the payload `uri` is the bare `<source>://` and would otherwise fabricate a phantom root node), `reconcileFolders` (a `changeType:'structure'` create/update/delete/revert — the affected PARENTS, never a global refresh), `ensureFolderLoaded({force})` + `refresh` (badge → `FileNode.git` subtree re-list + `SourceInfo.git` summaries), and `setSourceDirty` for a source that is not hydrated. An external change and a changing `sync:completed` share ONE per-source reconcile schedule: a trailing debounce (`RECONCILE_QUIET_MS` = 2 s — every event restarts it) bounded by a max-wait (`RECONCILE_MAX_WAIT_MS` = 6 s from the window's first event), so one agent turn's burst costs one or two passes of the visible folders instead of one per event, and a continuous burst still converges. The quiet window is sized on a measured turn, whose events arrive up to ~1.8 s apart. Pending passes are dropped on unmount and on an agent/project change. The badge branch keeps its own 250 ms timers (it does different work; a shared key would let one cancel the other). Badge/status and reconnect callbacks publish source revisions for Changes; timers are cancelled on context changes, and an epoch check prevents an old reconnect response from publishing into the new context.
 - **The Changes badge re-count.** `pending:changed` (content-free, project-wide, derived server-side) never reaches the file handlers: it — plus a window focus / tab return and a successful reconnect probe — feeds ONE trailing schedule (`PENDING_COUNT_QUIET_MS` 1 000 ms, `PENDING_COUNT_MAX_WAIT_MS` 5 000 ms) that calls `refreshPendingCount`; a hidden tab skips the call, the mount counts once, a context change drops the timer. No poll, no timer while idle.
 - **Reconnect recovery.** The filesystem channel is strictly live fan-out — the package route has no `Last-Event-ID`, no backfill and no cursor, and the host hub replays a snapshot only for `presence`. Everything emitted while the connection was down is lost. The hook therefore subscribes with `onConnChange` and, on a settled liveness flip, PROBES with the cheap summaries call and then re-converges every hydrated source. The hub's flip carries no direction, which is why the probe exists instead of a guess. This is what makes the toolbar Refresh a rare, deliberate action rather than routine repair.
 
@@ -35,7 +35,7 @@ React hooks used by the Files widget: container-width detection, viewport diff l
 
 ## Gotchas
 
-- `useContainerWidth` re-measures on `ResizeObserver` ticks. Avoid CSS that changes layout in response to the returned value without hysteresis — the default `hysteresisPx: 60` is what prevents oscillation. It reads `clientWidth` ONLY: a `scrollWidth` comparison inside the observer callback forces a layout flush per tick. Its `scrollWidth`-comparing sibling `useElementFits` was DELETED (2026-08) after a repo-wide grep found no consumer in `packages/*` — do not resurrect it without one.
+- The shared width hook observes `clientWidth`. Preserve hysteresis when CSS changes layout in response to its result; do not recreate the deleted `useElementFits` hook without a consumer.
 - `useFilesystemSSE` handlers must be defensive — a throw would break the shared hub subscription for every channel, not just this widget.
 - The `external:true` branch reconciles the source's VISIBLE folders (adds new files; strikes through / prunes removed ones). It must stay an EARLY `return` short-circuit before `upsertFileNodeFromEvent` (the `<source>://` uri is truthy → a phantom node otherwise), exactly like the badge branch.
 - **Anything guarded by `!uri` below the `if (!uri) return` is DEAD.** Three structural branches sat there and could never run; the intent (re-converge after a move/delete) is delivered now by the `changeType === 'structure'` parent reconcile. Do not reintroduce a `!uri` condition below that guard.

package/app/filesystem/hooks/useDiscoverableSources.ts

@@ -40,6 +40,7 @@
 
 import { useEffect, useRef, useState } from 'react';
 import { listDiscoverableSources, type DiscoverableSourceSuggestion } from '../api';
+import { useFilesystemStore } from '../store/filesystemStore';
 
 export function useDiscoverableSources(params: {
   agentId: string | undefined;
@@ -47,6 +48,7 @@ export function useDiscoverableSources(params: {
   /** Only fetch once the caller could actually use the result. */
   enabled: boolean;
 }): readonly DiscoverableSourceSuggestion[] {
+  const client = useFilesystemStore((s) => s.client);
   const { agentId, projectId, enabled } = params;
   const [suggestions, setSuggestions] = useState<readonly DiscoverableSourceSuggestion[]>([]);
 
@@ -69,13 +71,13 @@ export function useDiscoverableSources(params: {
   useEffect(() => {
     if (!agentId || !enabled || fetchedRef.current) return;
     fetchedRef.current = true;
-    listDiscoverableSources({ agentId, ...(projectId ? { projectId } : {}) })
+    listDiscoverableSources({ agentId, ...(projectId ? { projectId } : {}) }, client)
       .then((res) => { if (aliveRef.current) setSuggestions(res.suggestions ?? []); })
       // Fail-soft: no dock, no banner. It is an affordance, not a result. The
       // latch stays set, so a transient failure does not retry-loop; a context
       // change (the effect above) is what re-arms it.
       .catch(() => { if (aliveRef.current) setSuggestions([]); });
-  }, [agentId, projectId, enabled]);
+  }, [agentId, projectId, enabled, client]);
 
   return suggestions;
 }

package/app/filesystem/hooks/useFilesystemSSE.ts

@@ -1,5 +1,5 @@
 import { useEffect, useCallback, useRef } from 'react';
-import { useFilesystemStore } from '../store/filesystemStore';
+import { useFilesystemStore, useFilesystemStoreApi } from '../store/filesystemStore';
 import { getFilesystemHostImperative } from '../FilesystemHost';
 import { uriAncestors, sourceFromUri, folderUri } from '../store/helpers';
 
@@ -96,6 +96,9 @@ export function syncChangedNothing(payload: Record<string, unknown>): boolean {
  * hook just filters the channel to its own agent + the known event types.
  */
 export function useFilesystemSSE(agentId: string | undefined, projectId: string | null) {
+  // THIS window's store: every handler below reads and writes it, never another
+  // window's — a new store (another identity) is a new subscription.
+  const storeApi = useFilesystemStoreApi();
   const refreshTree = useFilesystemStore((s) => s.refreshTree);
   const loadSourceSummaries = useFilesystemStore((s) => s.refresh);
   const ensureFolderLoaded = useFilesystemStore((s) => s.ensureFolderLoaded);
@@ -135,7 +138,7 @@ export function useFilesystemSSE(agentId: string | undefined, projectId: string
       for (const t of status.values()) clearTimeout(t);
       status.clear();
     };
-  }, [agentId, projectId]);
+  }, [agentId, projectId, storeApi]);
   useEffect(() => {
     const reconcile = reconcileTimersRef.current;
     return () => {
@@ -143,7 +146,7 @@ export function useFilesystemSSE(agentId: string | undefined, projectId: string
       for (const entry of reconcile.values()) clearTimeout(entry.timer);
       reconcile.clear();
     };
-  }, [agentId, projectId]);
+  }, [agentId, projectId, storeApi]);
 
   // ONE pending re-count schedule per context (see `PENDING_COUNT_QUIET_MS`).
   const countTimerRef = useRef<{ timer: ReturnType<typeof setTimeout>; deadline: number } | null>(null);
@@ -198,7 +201,7 @@ export function useFilesystemSSE(agentId: string | undefined, projectId: string
       // `gitStatusSeq` guard drops any out-of-order response.
       const scheduleGitStatusRefresh = (source: string): void => {
         if (!agentId || !source) return;
-        const active = useFilesystemStore.getState().activeSource;
+        const active = storeApi.getState().activeSource;
         const focused =
           typeof active === 'string' && active
             ? active.includes('://')
@@ -212,7 +215,7 @@ export function useFilesystemSSE(agentId: string | undefined, projectId: string
           source,
           setTimeout(() => {
             timers.delete(source);
-            useFilesystemStore.setState(s => ({ sourceChangeRevision: { ...s.sourceChangeRevision, [source]: (s.sourceChangeRevision[source] ?? 0) + 1 } }));
+            storeApi.setState(s => ({ sourceChangeRevision: { ...s.sourceChangeRevision, [source]: (s.sourceChangeRevision[source] ?? 0) + 1 } }));
             if (focused === source) void loadGitStatus({ agentId, projectId, source });
           }, BADGE_REFRESH_DEBOUNCE_MS),
         );
@@ -254,7 +257,7 @@ export function useFilesystemSSE(agentId: string | undefined, projectId: string
           // folder of the source and applies the absence semantics. On a source that
           // is not hydrated yet it is a no-op by design; mark it dirty instead so the
           // header can tell the user a refresh is worth it.
-          if (useFilesystemStore.getState().loadedFolders?.[`${source}://`]) {
+          if (storeApi.getState().loadedFolders?.[`${source}://`]) {
             scheduleSourceReconcile(source);
           } else {
             setSourceDirty(source, true);
@@ -287,9 +290,9 @@ export function useFilesystemSSE(agentId: string | undefined, projectId: string
       // (recursive:false re-list) — acceptable v1.
       if (payload.changeType === 'badge') {
         if (!agentId) return;
-        // A background Files widget bound to a DIFFERENT agent than the active tree
-        // must not thrash the shared store's context on a source-scoped badge.
-        const storeAgent = useFilesystemStore.getState().activeAgentId;
+        // A store whose context is not this hook's agent (mid-switch) must not have
+        // its context thrashed by a source-scoped badge.
+        const storeAgent = storeApi.getState().activeAgentId;
         if (storeAgent && storeAgent !== agentId) return;
         const source =
           typeof payload.source === 'string' && payload.source
@@ -303,14 +306,14 @@ export function useFilesystemSSE(agentId: string | undefined, projectId: string
           source,
           setTimeout(() => {
             timers.delete(source);
-            useFilesystemStore.setState(s => ({ sourceChangeRevision: { ...s.sourceChangeRevision, [source]: (s.sourceChangeRevision[source] ?? 0) + 1 } }));
+            storeApi.setState(s => ({ sourceChangeRevision: { ...s.sourceChangeRevision, [source]: (s.sourceChangeRevision[source] ?? 0) + 1 } }));
             // FileNode.git for the source subtree (matches the sync:completed precedent).
             void ensureFolderLoaded({ agentId, projectId, uri: `${source}://`, force: true });
             // SourceInfo.git (repo-switcher, tree source header, panel branch hint).
             // Summaries ONLY — a git badge must never trigger a per-source walk.
             void loadSourceSummaries({ agentId, projectId });
             // Git Control panel change-set + branch, only when this is the focused repo.
-            const active = useFilesystemStore.getState().activeSource;
+            const active = storeApi.getState().activeSource;
             const focused =
               typeof active === 'string' && active
                 ? active.includes('://')
@@ -341,9 +344,9 @@ export function useFilesystemSSE(agentId: string | undefined, projectId: string
       // shared per-source reconcile schedule, never the badge's timers.
       if (payload.external === true) {
         if (!agentId) return;
-        // A background Files widget bound to a DIFFERENT agent than the active tree
-        // must not thrash the shared store's context on a source-scoped event.
-        const storeAgent = useFilesystemStore.getState().activeAgentId;
+        // A store whose context is not this hook's agent (mid-switch) must not have
+        // its context thrashed by a source-scoped event.
+        const storeAgent = storeApi.getState().activeAgentId;
         if (storeAgent && storeAgent !== agentId) return;
         const source =
           typeof payload.source === 'string' && payload.source
@@ -356,7 +359,7 @@ export function useFilesystemSSE(agentId: string | undefined, projectId: string
         // A source that has never been hydrated has nothing to reconcile against —
         // an eager content list here would defeat lazy hydration. Flag it instead:
         // the header shows the "stale" hint and the next expand/refresh converges it.
-        if (!useFilesystemStore.getState().loadedFolders?.[`${source}://`]) {
+        if (!storeApi.getState().loadedFolders?.[`${source}://`]) {
           setSourceDirty(source, true);
           return;
         }
@@ -460,6 +463,7 @@ export function useFilesystemSSE(agentId: string | undefined, projectId: string
     [
       agentId,
       projectId,
+      storeApi,
       refreshTree,
       loadSourceSummaries,
       ensureFolderLoaded,
@@ -511,8 +515,8 @@ export function useFilesystemSSE(agentId: string | undefined, projectId: string
         if (epoch !== contextEpoch.current) return;
         // A gap may have hidden pending:changed frames — re-count once.
         scheduleCountRef.current();
-        const state = useFilesystemStore.getState();
-        useFilesystemStore.setState(s => ({ sourceChangeRevision: Object.fromEntries(s.sources.map(source => [sourceFromUri(source.uri_root), (s.sourceChangeRevision[sourceFromUri(source.uri_root)] ?? 0) + 1])) }));
+        const state = storeApi.getState();
+        storeApi.setState(s => ({ sourceChangeRevision: Object.fromEntries(s.sources.map(source => [sourceFromUri(source.uri_root), (s.sourceChangeRevision[sourceFromUri(source.uri_root)] ?? 0) + 1])) }));
         const sources = new Set<string>();
         for (const [key, loaded] of Object.entries(state.loadedFolders || {})) {
           if (!loaded) continue;
@@ -526,7 +530,7 @@ export function useFilesystemSSE(agentId: string | undefined, projectId: string
         );
       })();
     }, RECONNECT_RECONCILE_DEBOUNCE_MS);
-  }, [agentId, projectId, loadSourceSummaries, reconcileSourceFolders]);
+  }, [agentId, projectId, storeApi, loadSourceSummaries, reconcileSourceFolders]);
 
   const handleConnChangeRef = useRef(handleConnChange);
   handleConnChangeRef.current = handleConnChange;
@@ -536,14 +540,17 @@ export function useFilesystemSSE(agentId: string | undefined, projectId: string
     return () => {
       if (timer.current) clearTimeout(timer.current);
     };
-  }, [agentId, projectId]);
+  }, [agentId, projectId, storeApi]);
 
   useEffect(() => {
     if (!agentId || !projectId) return;
     const host = getFilesystemHostImperative();
     if (!host?.subscribeFilesystemEvents) return;
-
-    return host.subscribeFilesystemEvents(agentId, projectId, (raw) => {
+    // Inert once this scope is gone (agent/project/store change, unmount): a frame
+    // the hub delivers after the unsubscribe must not reach the next scope's store.
+    let live = true;
+    const unsubscribe = host.subscribeFilesystemEvents(agentId, projectId, (raw) => {
+      if (!live) return;
       // The hub carries the whole authorized agent set; keep only THIS agent's
       // known event types (server already scoped by user/project).
       const event = raw as FilesystemEvent | null;
@@ -565,6 +572,7 @@ export function useFilesystemSSE(agentId: string | undefined, projectId: string
       const isExternal = (event.payload as { external?: boolean }).external === true;
       if (!isBadge && !isExternal && event.agentId !== agentId) return;
       handleEventRef.current(event);
-    }, () => handleConnChangeRef.current());
-  }, [agentId, projectId]);
+    }, () => { if (live) handleConnChangeRef.current(); });
+    return () => { live = false; unsubscribe(); };
+  }, [agentId, projectId, storeApi]);
 }

package/app/filesystem/hooks/useGitChangesInventory.ts

@@ -4,6 +4,7 @@ import { useCallback, useEffect, useRef, useState } from 'react';
 import { getGitRepos, getGitStatus } from '../api';
 import type { SourceInfo } from '../domain/types';
 import type { GitGroup } from '../ui/pendingChangesModel';
+import { useFilesystemStore } from '../store/filesystemStore';
 
 /**
  * The Git half of the Changes inventory: every accessible checkout's status, one
@@ -15,6 +16,7 @@ import type { GitGroup } from '../ui/pendingChangesModel';
 export function useGitChangesInventory(params: {
   agentId: string; projectId: string | null; sources: SourceInfo[]; revisions: Record<string, number>; resetKey: string;
 }): { groups: GitGroup[]; loading: boolean; refresh: (force: boolean) => Promise<void> } {
+  const client = useFilesystemStore((s) => s.client);
   const { agentId, projectId, sources, revisions, resetKey } = params;
   const [groups, setGroups] = useState<GitGroup[]>([]);
   const [loading, setLoading] = useState(false);
@@ -42,7 +44,7 @@ export function useGitChangesInventory(params: {
           const revision = revisions[slug] ?? 0;
           if (!all && seen.current[slug] === revision) continue;
           try {
-            const repos = await getGitRepos({ agentId, ...scope, source: slug });
+            const repos = await getGitRepos({ agentId, ...scope, source: slug }, client);
             if (mine !== seq.current) return;
             for (let index = next.length - 1; index >= 0; index--) {
               if (next[index].source === slug && !repos.repos.some(repo => repo.rel === next[index].repo.rel)) next.splice(index, 1);
@@ -50,7 +52,7 @@ export function useGitChangesInventory(params: {
             for (const repo of repos.repos) {
               const group: GitGroup = { source: slug, repo };
               try {
-                const result = await getGitStatus({ agentId, ...scope, source: slug, repo: repo.rel });
+                const result = await getGitStatus({ agentId, ...scope, source: slug, repo: repo.rel }, client);
                 if (mine !== seq.current) return;
                 if (result.ok === false) group.error = 'Git status unavailable'; else group.status = result.status;
               } catch (error) { group.error = error instanceof Error ? error.message : 'Git status failed'; }

package/app/filesystem/host/README.md

@@ -15,18 +15,19 @@ The host integration entry point — `installFilesystemHostComponents`, re-expor
 - `FilesystemHostValue.currentRole` — `{ role?, priority? }` for the caller in the active project, derived from `WorkspaceHostPort.useCurrentUser()` (which now returns role + ordinal priority alongside name/email). Owner/admin-effective is `priority <= 2`. Used to HIDE owner-only Sources/Packages controls (the `recognizesPackages` toggle, the package access-feature override); UX-only — the server route stays the enforcement floor, so an absent signal hides the control (deny-by-default).
 - `FilesystemHostValue.grantedFeatures` — `readonly string[]`, the caller's granted feature ids in the active project, read from `WorkspaceHostPort.getGrantedFeatures(projectId, userId)`. **Evaluate it ONLY through `hasFeature` / `meetsRequires` from `@neuralis/package-system/access`** — never a hand-rolled `includes` (it would miss the `'*'` wildcard), and never `currentRole`: the role NAME is not an authority source, not even for a hide-only gate. It is `readonly` so no UI file can mutate the caller's grants; the kernel predicates take a mutable array, so copy at the call site rather than widening the contract. UX-only exactly like `currentRole` — it hides an affordance the caller could not use (the S2 "hidden means absent" discipline: hidden entirely, never a greyed-out or locked row), and the route re-checks every call regardless. Absent/empty ⇒ hide, deny-by-default. First consumer: the Explorer tree's **Discover dock**, gated on `drive.mount`.
   - The port returns a FRESH array on every call, so `buildFilesystemHostValue` memoises on a joined key rather than array identity — a raw pass-through would invalidate the whole host-value memo on every render.
-- `installFilesystemHostComponents({ registry: PackageHostRegistry, port: WorkspaceHostPort })` — side-effecting; registers widget + card + the provider fill (one component per install, closed over the port; it ignores the slot's `snapshot`/`assetScope` props), and subscribes ONCE to the host's optional `port.onClientStateReset` so the dock broom (widget / agent / project level) reaches the Files store (`resetClientState`). A host without the method simply never resets the store.
+- `installFilesystemHostComponents({ registry: PackageHostRegistry, port: WorkspaceHostPort })` — side-effecting; registers widget + card + the provider fill (one component per install, closed over the port; it ignores the slot's `snapshot`/`assetScope` props), and subscribes ONCE to the host's optional `port.onClientStateReset` with `resetFilesClientState`, so the dock broom (instance / widget / agent / project level) reaches every mounted Files window it scopes and the one persisted record. A host without the method simply never resets.
 - `InstallFilesystemHostComponentsOptions`.
 
 ## How it plugs into the package-system kernel
 
 - `WorkspaceHostPort` (from `@neuralis/package-system/contracts`) is the single point of contact between the host and brain-core's UI. The host has exactly one implementation; brain-core consumes the port without knowing which host runs it.
 - `installFilesystemHostComponents` registers the widget under `componentImport: '@neuralis/brain-core/app/filesystem'` — the same string the package manifest declares for `app.surfaces[].component.import`. The host renderer resolves widgets by that import string at render time.
-- The widget is wrapped in `<PackageApiProvider slug="brain-core" projectId agentId userId>` from `@neuralis/package-system/client` so every internal API call resolves through the kernel session.
+- `FilesystemWidgetHost` is the window seam: it receives the window's `widgetId` and BOUND `agentId`, creates the window's own store (`useFilesWindowStore` — none, and nothing painted, until the live user and project are known) and mounts it under `FilesystemStoreProvider`, keyed on that identity so a different user or project remounts the whole Files tree instead of re-using callbacks of the previous one. The store's request `client` (`createPackageApi` over the window's project and bound agent) is what every API call passes; the surrounding `<PackageApiProvider slug="brain-core" projectId agentId userId>` keeps serving the kernel's own React consumers.
 - The card registration uses `registerCardComponent('filesystem.change', FilesystemChangeCard, { owner: { kind: 'package-direct', packageId: '@neuralis/brain-core' }, renderer: 'direct', mountPolicy: 'virtualized', estimateHeight: estimateFilesystemChangeCardHeight })` from `@neuralis/agent-core/app/chat` — the agent-core chat surface owns the card registry; brain-core contributes an OWNED first-party direct (React) card. The `virtualized` mount policy keeps it out of the iframe/keep-alive overscan bump. The registry rejects any OTHER owner touching `filesystem.change` (`OWNER_MISMATCH`) and never lets a package overwrite a builtin. `estimateHeight` is the card's own row-height model (see `app/cards/README.md`); it MUST stay a module-level reference — the registry compares estimator identity when deciding whether a re-registration is idempotent, so an inline arrow here would churn the registry (fingerprint bump + retained-View eviction) on every call.
 
 ## Security & scope
 
+- One window store per mounted Files window, hidden and minimized windows included (they stay mounted); a window id addresses a reset and keys a persisted view, never an authority.
 - The widget never sees raw host internals. `WorkspaceHostPort` exposes only the active session ids, the agent map, file marks, the SSE URL builder, granted features (read-only), the docker flag, and the client-state reset subscription (a scope, never a package name — the host stays generic).
 - File marks and event subscriptions are agent-scoped; cross-agent observation requires the corresponding `filesystem.observeScoped` / `filesystem.modifyScoped` features which the route layer enforces.
 

package/app/filesystem/host/installFilesystemHostComponents.tsx

@@ -9,7 +9,7 @@
 
 'use client';
 
-import React, { Suspense, type ReactNode } from 'react';
+import React, { Suspense, useEffect, type ReactNode } from 'react';
 import type { WorkspaceHostPort } from '@neuralis/package-system/contracts';
 import {
   PackageApiProvider,
@@ -18,7 +18,7 @@ import {
 } from '@neuralis/package-system/client';
 import { registerCardComponent } from '@neuralis/agent-core/app/chat';
 import { FilesystemWidget } from '../ui';
-import { useFilesystemStore } from '../store/filesystemStore';
+import { FilesystemStoreProvider, resetFilesClientState, setFilesLiveUser, useFilesWindowStore } from '../store/filesystemStore';
 import { FilesystemChangeCard } from '../../cards/FilesystemChangeCard';
 import { estimateFilesystemChangeCardHeight } from '../../cards/FilesystemCardShell';
 import { FILESYSTEM_CARD_MATCH_TOOLS, FILESYSTEM_COMPOSER_CONTRACT } from '../../cards/diffUtils';
@@ -48,10 +48,12 @@ type FilesystemWidgetProps = {
 };
 
 /**
- * The dock broom's reach into the Files store is wired ONCE per module, at
+ * The dock broom's reach into the Files stores is wired ONCE per module, at
  * install time, to the FIRST port that carries `onClientStateReset` — the only
- * place the port is consumed outside `buildFilesystemHostValue`. A host without
- * the optional method simply never resets this store (fail-safe: the package
+ * place the port is consumed outside `buildFilesystemHostValue` and the window
+ * host. ONE subscription for every window: `resetFilesClientState` fans the scope
+ * out to the mounted windows it reaches and to the one persisted record. A host
+ * without the optional method simply never resets (fail-safe: the package
  * assumes nothing); a second install with a different port is not re-wired
  * (there is one host port per process).
  */
@@ -64,15 +66,17 @@ export function installFilesystemHostComponents(
 
   if (!resetSubscribed && port.onClientStateReset) {
     resetSubscribed = true;
-    port.onClientStateReset((scope) => {
-      useFilesystemStore.getState().resetClientState(scope);
-    });
+    port.onClientStateReset(resetFilesClientState);
   }
 
   // The provider fill: ONE component per install (its identity is the host's
   // memo key). The slot's `snapshot`/`assetScope` props are not read — the
   // Files host value comes from the port alone.
   function FilesystemWorkspaceProvider({ children }: { children?: ReactNode }) {
+    // Whose persisted Files records a broom prunes — the signed-in user, also
+    // when no Files window is open.
+    const userId = port.useUserId();
+    useEffect(() => { setFilesLiveUser(userId); }, [userId]);
     return <FilesystemPackageHost port={port}>{children}</FilesystemPackageHost>;
   }
 
@@ -82,13 +86,22 @@ export function installFilesystemHostComponents(
     Component: FilesystemWorkspaceProvider,
   });
 
+  // ONE store per window — the insertion seam. `agentId` is the window's BOUND
+  // agent and `widgetId` its id; a different user or project is a new store, and
+  // nothing renders before both are known. The key remounts the Files tree with a
+  // new store, so no component keeps a callback, client or local list of the
+  // previous identity.
   function FilesystemWidgetHost({ agentId, widgetId, state }: FilesystemWidgetProps) {
     const projectId = port.useProjectId();
     const userId = port.useUserId();
+    const store = useFilesWindowStore(widgetId, userId, projectId, agentId);
+    if (!store) return LOADING;
     return (
       <WorkspaceHostPortProvider port={port}>
         <PackageApiProvider slug="brain-core" projectId={projectId} agentId={agentId} userId={userId}>
-          <FilesystemWidget agentId={agentId} projectId={projectId} userId={userId} widgetId={widgetId} state={state} />
+          <FilesystemStoreProvider key={`${widgetId}\u0000${userId}\u0000${projectId}\u0000${agentId}`} store={store}>
+            <FilesystemWidget agentId={agentId} projectId={projectId} userId={userId} widgetId={widgetId} state={state} />
+          </FilesystemStoreProvider>
         </PackageApiProvider>
       </WorkspaceHostPortProvider>
     );

package/app/filesystem/store/README.md

@@ -1,6 +1,6 @@
 # brain-core/app/filesystem/store
 
-Zustand store powering the Files widget: file dictionary, expanded folders, sources registry, search state, list / search slices.
+Zustand stores powering the Files windows — ONE live store per window (file dictionary, expanded folders, sources registry, search and git state, list / search / git slices) and ONE persistence owner for all of them.
 
 ## Responsibility
 
@@ -28,12 +28,15 @@ Two guards make this safe against the races a plain re-list would lose:
 
 ## Public Surface
 
-- `useFilesystemStore` — Zustand hook exposing `FileSystemState` plus `ListSliceActions` and `SearchSliceActions`.
+- `createFilesystemStore(init)` — one Files store (a vanilla Zustand store exposing `FileSystemState` plus the list / search / git slice actions). Every asynchronous fence and dedup map is created with it (`resetEpoch`, the pending-count and search / git sequences, the rehydrate set, the folder-load and root-listing dedup maps, the reconcile jobs, the per-folder generations), so two windows — of two agents or of the same one — never fence, supersede or dedup each other. It persists nothing itself and carries its window's identity: `windowId` and `client`, the request client built over the window's project and BOUND agent that every API call of the store passes.
+- `createFilesWindowStore(identity)` / `mountFilesWindow(store, identity)` / `useFilesWindowStore(...)` — a window's store for its LIVE `(windowId, userId, projectId, agentId)`, registered while mounted. `useFilesWindowStore` returns `null` until the user and project are known (nothing persisted is read and nothing paints before), and a different user or project is a different store.
+- `FilesystemStoreProvider` / `useFilesystemStore(selector)` / `useFilesystemStoreApi()` — the window's store through React context. The hook keeps its name and reads THIS window's store; outside a `FilesystemStoreProvider` it throws (there is no module store to fall back to). Imperative readers (event handlers, the SSE hook) take the store from `useFilesystemStoreApi()`.
+- `filesPersistence` — the ONE writer of `neuralis.filesystem.tabs` (v2, see the context space below), and `resetFilesClientState(scope)`, the broom's ONE entry.
 - `helpers.ts` — URI helpers (`fileKey`, `fileKeyFromNode`, `folderUri`, `sourceFromUri`, `sourceRootUri`, `extractFilename`, `uriAncestors`, `parseFilePrev`, `extractFileContent`, `extractReadFilesPayload`, `ensureFolderChainForUri`, `hasCompletedRead` — a tab's read is done when it left a string baseline or an error; FileNode presence says nothing — and `contextKey(userId, projectId, agentId)`, the ONE key of the context space).
 - `searchSlice.ts` — `SearchSliceState`, `SearchSliceActions`, `SearchSliceHit`.
 - `listSlice.ts` — `ListSliceActions` (`loadList`, `refresh` — both source-summary loaders) + `contextResetPatch()`, the ONE per-context wipe (everything except the preference fields, the active pair and the in-flight `uploading` flag) shared by `loadList`'s agent/project switch and `resetClientState`.
 - `FILES_LRU_HARD_CAP` — the cold-row cap (exported for the eviction tests, which seed `cap + n` rows instead of a hardcoded count).
-- **The context space — `activeUserId` + `contextStateByKey`** (owner rule 2026-09-04: isolation between agents is not loss). The store is scoped the way the platform is: by `(user, project, agent)`. The ACTIVE context lives in the flat fields; every context the store has left sits in `contextStateByKey` under `contextKey(userId, projectId, agentId)` as its FULL per-context slice — exactly the keys of `contextResetPatch()` (`captureContextSlice`): tree nodes, expanded/loaded folders, tabs, content caches, search, git panel, sources, panels. `loadList` on a switch fences, stashes the outgoing slice, and restores the incoming one (or the reset defaults for a context never visited), then re-reads the restored active tab (`rehydrateActiveTab`) and reconciles the restored context's loaded sources — its realtime events were dropped while it was inactive, so a switch-back IS a gap. The widget passes `userId` (from `port.useUserId()`) only on its mount `loadList`; a store with no user ADOPTS the first real one in place, a different user is a switch. Persisted as `contexts` projections (`PersistedFilesContext`: the tab shape, `expandedFolders` as an array, `sidebarView`, `activeWorkspaceTab`, `workspacePanels`, `activeFolderPath`) — nodes and caches stay in memory and re-fetch; the active context's projection is taken off the flat fields on every write, `merge` puts it back into them on rehydrate, and a v1 payload's flat tab trio is lifted into the active context by `migrate`. The dock broom is the ONE writer that drops a stashed context, its own scope only (widget/agent: this context; project: every context of this user's project). It mirrors the host's per-context runtime map; the routes remain the enforcement floor — this is the client's mirror, never an access decision.
+- **The context space — `activeUserId` + `contextStateByKey`** (owner rule 2026-09-04: isolation between agents is not loss). The store is scoped the way the platform is: by `(user, project, agent)`. The ACTIVE context lives in the flat fields; every context the store has left sits in `contextStateByKey` under `contextKey(userId, projectId, agentId)` as its FULL per-context slice — exactly the keys of `contextResetPatch()` (`captureContextSlice`): tree nodes, expanded/loaded folders, tabs, content caches, search, git panel, sources, panels. `loadList` on a switch fences, stashes the outgoing slice, and restores the incoming one (or the reset defaults for a context never visited), then re-reads the restored active tab (`rehydrateActiveTab`) and reconciles the restored context's loaded sources — its realtime events were dropped while it was inactive, so a switch-back IS a gap. The widget passes `userId` (from `port.useUserId()`) only on its mount `loadList`; a store with no user ADOPTS the first real one in place, a different user is a switch. **Persistence has ONE owner** (`filesPersistence`) — window stores persist nothing, so two windows writing one key can never overwrite each other. The v2 record keeps its prefs, its active triple and the per-agent `contexts` projections (`PersistedFilesContext`: the tab shape, `expandedFolders` as an array, `sidebarView`, `activeWorkspaceTab`, `workspacePanels`, `activeFolderPath`) exactly as an older build wrote them, plus an OPTIONAL `windows` map: one `PersistedFilesWindow` per window id — the same allowlist plus the user, project and bound agent it was written for. Nodes and caches stay in memory and re-fetch. A window's store starts from its OWN projection when the record holds one for the LIVE identity (one written for another user, project or agent is ignored); a window with none starts from the defaults — the per-agent `contexts` entries are never read into a window (no translation from an agent key to a window id; an upgrade resets the open tabs once). While mounted, the window feeds its projection to the owner: per store update eight reference compares, and only a projection that changed is serialized and written (the whole allowlisted record, once). A record without `windows` is read without one and is not rewritten until a window really changes; a v1 payload's flat tab trio is lifted into the active context by `migrate` (pre-existing, not extended). Hiding a window or switching a Group keeps its projection; unmounting drops its subscription and fences its in-flight readers, never its projection. The dock broom is the ONE writer that drops persisted state, its own scope only (see below). It mirrors the host's per-context runtime map; the routes remain the enforcement floor — this is the client's mirror, never an access decision.
 - `rehydrateActiveTab` — fetches the active tab's content when no read has completed for it (`hasCompletedRead`), against the store's OWN active pair; run by `loadList` on a same-context mount (page reload) and after a switch-back restore, and by `setActiveFile` (a tab click). It replaced a `FilesystemWidget` effect that decided from its render closure (the previous agent's tab re-opened under the new one after a switch) and from FileNode presence (a listed-but-unread tab rendered "Empty file"). A per-uri in-flight set stops a double activation from issuing two reads; the fence clears it (the same uri under another context is another file).
 - `saveFileInPlace` / `markFileDeleted` — the editor's in-place mutation tails beside `moveFileToFolder`: move when the target uri differs, update content when it differs, then a targeted `reconcileFolders` of BOTH parents (the old folder loses the departed row — the upsert-only `refresh` never could) and a forced re-read; delete, then reconcile the parent (the tombstone comes from the reconcile). A rejected `/modify` is HTTP 200 — `ok !== true` throws the server's message and runs no tail.
 - `snapshotError` / `clearSnapshotError` — the ROOT-listing failure (`loadList`'s catch: the service, not one source — a source's own failure is `hydrationState[uri]`); rendered by the tree with Retry, cleared by the next successful listing, the reset patch or the dismiss.
@@ -41,9 +44,9 @@ Two guards make this safe against the races a plain re-list would lose:
 
 ## How it plugs into the package-system kernel
 
-- The store calls `api/index.ts` clients which go through `tryGetPackageApiImperativeAsync('brain-core')` — every API call is session-scoped by the kernel.
+- The store calls the `api/index.ts` functions with its own `client` (`createPackageApi` over the window's project and bound agent) — the X-Project-Id / X-Agent-Id headers are fixed before any await and never come from another mounted window; the routes resolve the real session from them.
 - SSE events arrive via `useFilesystemSSE` (in `hooks/`) and dispatch into store actions; the event payload follows the `FilesystemEventPayload` shape from `src/domain/events.ts`.
-- **The dock broom reaches this store through the kernel port**: `installFilesystemHostComponents` subscribes `port.onClientStateReset` once at install time and forwards every scope to `resetClientState(scope)`. The action matches the scope against the ACTIVE `(activeProjectId, activeAgentId)` pair (widget level: only the `filesystem` widget type; anything else is a no-op), applies `contextResetPatch()` (which includes an empty `tabMeta`) — so the persisted allowlist (`openFiles`/`activeFile`/`tabMeta`) is written EMPTY and a persisted tab cannot re-run the read/list race on the next mount — and fences everything in flight through the ONE `fenceInFlightWriters` action — a module-level `resetEpoch` that the `openFile` read, a reconcile pass's `set()`, `createNode`'s optimistic folder and the editor tails `saveFileInPlace` / `markFileDeleted` capture before their `await` and check after, plus a generation bump on every folder ever listed and a clear of the folder-load dedup map and the rehydrate set. **`loadList`'s agent/project/user switch runs the SAME fence before it swaps the context** — until 2026-09-04 only the broom fenced, so a read a tab click had started under the previous agent could land its file, and `activeFile`, under the new one. Preferences survive (`previewEditorsEnabled`, `diffViewMode`, `sidebarWidth`, `sidebarOpen`, `gitViewMode`, `searchMode`) and so does the active pair. Never a server call; `reconcileJobs` is deliberately not cleared (a running job's `finally` would delete the next job's entry and two passes would run at once — the epoch makes the running job inert instead).
+- **The dock broom reaches these stores through the kernel port**: `installFilesystemHostComponents` subscribes `port.onClientStateReset` ONCE at install time with `resetFilesClientState(scope)`, which calls `resetClientState(scope)` on every mounted window the scope reaches and then prunes the persisted record: `instance` (one window cleaned) drops that window's projection; `widget` (one window destroyed) drops it and the legacy context of its `(user, project, agent)`; `agent` / `project` drop the legacy contexts and the window projections of their scope — the signed-in user's only, never another project's or a sibling window's. The store action matches the scope against its ACTIVE `(activeProjectId, activeAgentId)` pair (`instance` / `widget`: also the `filesystem` widget type AND its own `windowId`; anything else is a no-op), applies `contextResetPatch()` (which includes an empty `tabMeta`) — so the persisted allowlist (`openFiles`/`activeFile`/`tabMeta`) is written EMPTY and a persisted tab cannot re-run the read/list race on the next mount — and fences everything in flight through the ONE `fenceInFlightWriters` action — the store's own `resetEpoch` that the `openFile` read, a reconcile pass's `set()`, `createNode`'s optimistic folder and the editor tails `saveFileInPlace` / `markFileDeleted` capture before their `await` and check after, plus a generation bump on every folder ever listed and a clear of the folder-load dedup map and the rehydrate set. **`loadList`'s agent/project/user switch runs the SAME fence before it swaps the context** — until 2026-09-04 only the broom fenced, so a read a tab click had started under the previous agent could land its file, and `activeFile`, under the new one. Preferences survive (`previewEditorsEnabled`, `diffViewMode`, `sidebarWidth`, `sidebarOpen`, `gitViewMode`, `searchMode`) and so does the active pair. Never a server call; `reconcileJobs` is deliberately not cleared (a running job's `finally` would delete the next job's entry and two passes would run at once — the epoch makes the running job inert instead).
 
 ## Security & scope
 
@@ -53,9 +56,9 @@ Two guards make this safe against the races a plain re-list would lose:
 
 ## Gotchas
 
-- `searchSliceSeq` and `filenameSearchSeq` are module-level monotonic counters used to discard stale search responses. Removing them re-introduces the classic "old query results overwrite new ones" race.
+- The search and git slices keep monotonic per-store sequences (`searchSeq`, `gitStatusSeq`, `gitBranchSeq`) that discard stale responses. Removing them re-introduces the classic "old query results overwrite new ones" race; sharing them across stores would let one window's request supersede another's.
 - `fileKey` returns the URI as the canonical key. URIs MUST be canonicalised (`canonicalUri` in `src/usecases/list.ts`) before lookup — three-slash URIs (`brain:///foo`) collapse to two-slash form.
-- `loadList` uses an in-flight map keyed by `(agentId, projectId, withCounts)` to deduplicate concurrent calls. Calling `refresh` while a load is pending no-ops the second call.
+- `loadList` uses a per-store in-flight map keyed by `(agentId, projectId, withCounts)` to deduplicate concurrent calls. Calling `refresh` while a load is pending no-ops the second call.
 - **`/modify` answers HTTP 200 for a REJECTED operation** — the outcome is in `ok`, not the status code. Every mutation action branches on `ok === false` before applying an optimistic state, and reports through `organizeError` (a dismissible banner above the tree). `warning: 'moved_with_source_retained'` is a *partial success*: the copy landed, the source delete did not, and BOTH copies exist on purpose.
 - A **folder** move or delete is decomposed server-side into a recursive copy + a delete of the old subtree. The reconcile only inspects DIRECT children, so the store prunes by URI PREFIX for those two cases — a parent-only reconcile would leave the old subtree's interior behind forever.
 - **`removeFilePath` purges a URI from EVERY surface** — node, `openFiles`, `activeFile`, `tabMeta` and the content/baseline/error/prev side maps — and it must not require the node to exist. `tabMeta`/`openFiles` are PERSISTED, so a tab pointing at a deleted file outlives the node; gating the purge on `files[uri]` made it a no-op in exactly that case, and the tab could never close itself.
@@ -69,4 +72,5 @@ Two guards make this safe against the races a plain re-list would lose:
 - `test/store/reconcileSourceFolders.test.ts` — the external-event reconcile path.
 - `test/store/visibleReconcile.test.ts` — visible-only wide passes, collapse → stale → one narrow authoritative listing on re-open, and the bound.
 - `test/store/syncCompletedRelist.test.tsx` — the real SSE hook + store: a zero-count `sync:completed` lists nothing, and one event burst's list-request count.
+- `test/store/filesWindows.test.ts` — independent windows on the one owner: two same-agent windows keep distinct tabs and send their own client, interleaved writes survive a reload, an old record is read as it is and not rewritten until a real change, no content is persisted, a reset reaches exactly its scope, and a late answer never lands in the next identity's store.
 - `test/ui/` covers the rest of the store actions: list merge with the source registry, SSE event reduction, search slice debouncing, and the eviction cap.