@neuralis/brain-core 0.3.2 → 0.4.1

package/app/filesystem/api/projectPackages.ts

@@ -1,6 +1,8 @@
 /**
- * Client helpers for project-package operations exposed by the neuralis host
- * (NOT the brain-core package routes). Used by the filesystem panel Packages tab.
+ * Client reads for the Files → Packages panel: the packages an agent can use
+ * (the host's scoped snapshot) and the loader's diagnostics. The changes a
+ * package manager makes — trust, Build, the access feature — live in
+ * Admin → Packages.
  */
 
 import type {
@@ -27,15 +29,6 @@ export type ProjectPackageRow = {
   accessFeatureSource?: 'manifest' | 'override';
 };
 
-export type BuildResponse = {
-  ok: boolean;
-  slug: string;
-  wasmPath?: string;
-  logs: string[];
-  durationMs: number;
-  error?: string;
-};
-
 /**
  * W3F — diagnostics surfaced from the agent-core PackageLoader.
  * Each entry mirrors the loader's status with the captured init/manifest
@@ -59,8 +52,6 @@ export type PackagesDiagnosticsResponse = {
   summary: { total: number; loaded: number; partial: number; errors: number };
 };
 
-export type TrustValue = 'trusted' | 'untrusted' | null;
-
 async function parseJson<T>(res: Response): Promise<T> {
   const text = await res.text();
   try {
@@ -71,14 +62,17 @@ async function parseJson<T>(res: Response): Promise<T> {
 }
 
 /**
- * List installed packages for a project with their runtime status and
- * declarative contribution counts. Uses the host snapshot endpoint so the
- * panel reflects both first-party packages and project-installed packages.
+ * The packages an agent can use in this project — exactly what it gets: the
+ * host's scoped snapshot for this caller and THIS agent (`x-agent-id`, which
+ * the host verifies; an agent the caller cannot use resolves to none), so the
+ * agent's own packages show and another member's stay out. Native packages are
+ * left out (their trust is host-stamped, never a manifest claim): they belong
+ * to Admin → Packages. Each row carries its contribution counts.
  */
-export async function listProjectPackages(projectId: string): Promise<ProjectPackageRow[]> {
+export async function listProjectPackages(projectId: string, agentId?: string): Promise<ProjectPackageRow[]> {
   const res = await fetch('/api/packages/runtime', {
     method: 'GET',
-    headers: { 'x-project-id': projectId },
+    headers: { 'x-project-id': projectId, ...(agentId ? { 'x-agent-id': agentId } : {}) },
     credentials: 'same-origin',
   });
   if (!res.ok) throw new Error(`Failed to load packages snapshot: HTTP ${res.status}`);
@@ -102,6 +96,7 @@ export async function listProjectPackages(projectId: string): Promise<ProjectPac
   const commandsByPkg = groupCount(snapshot.commands, (c) => c.packageId);
 
   return snapshot.packages
+    .filter((pkg) => pkg.access?.trust !== 'native')
     .map<ProjectPackageRow>((pkg) => ({
       slug: pkg.id,
       packageId: pkg.id,
@@ -120,90 +115,6 @@ export async function listProjectPackages(projectId: string): Promise<ProjectPac
     }));
 }
 
-/**
- * Trigger a WASM build on the host. Returns once build + reload complete.
- * Use this against packages where the status is `partial` with reason
- * `build-missing`.
- */
-export async function buildPackage(projectId: string, slug: string): Promise<BuildResponse> {
-  const res = await fetch(
-    `/api/projects/${encodeURIComponent(projectId)}/packages/${encodeURIComponent(slug)}/build`,
-    { method: 'POST', credentials: 'same-origin' },
-  );
-  return parseJson<BuildResponse>(res);
-}
-
-/**
- * Flip a package's trust. `null` clears the project-level override (package
- * reverts to its manifest-declared trust, typically `untrusted`).
- */
-export async function setPackageTrust(
-  projectId: string,
-  slug: string,
-  trust: TrustValue,
-): Promise<{ ok: boolean; trust: TrustValue }> {
-  const res = await fetch(
-    `/api/projects/${encodeURIComponent(projectId)}/packages/${encodeURIComponent(slug)}/trust`,
-    {
-      method: 'PUT',
-      headers: { 'Content-Type': 'application/json' },
-      credentials: 'same-origin',
-      body: JSON.stringify({ trust }),
-    },
-  );
-  if (!res.ok) {
-    const body = await res.text();
-    throw new Error(`Failed to set trust (HTTP ${res.status}): ${body.slice(0, 200)}`);
-  }
-  return parseJson<{ ok: boolean; trust: TrustValue }>(res);
-}
-
-/**
- * R2b — set or clear the base-access feature OVERRIDE for a package. `null`/empty
- * clears it (the package reverts to its manifest `requires.accessFeature`, if
- * any). Owner/admin-effective; restrict-only (can only attach a requirement).
- */
-export async function setPackageAccessFeature(
-  projectId: string,
-  packageId: string,
-  featureId: string | null,
-): Promise<{ ok: boolean; featureId: string | null }> {
-  const res = await fetch(
-    `/api/projects/${encodeURIComponent(projectId)}/packages/${encodeURIComponent(packageId)}/access-feature`,
-    {
-      method: 'PUT',
-      headers: { 'Content-Type': 'application/json' },
-      credentials: 'same-origin',
-      body: JSON.stringify({ featureId }),
-    },
-  );
-  if (!res.ok) {
-    const body = await res.text();
-    throw new Error(`Failed to set access feature (HTTP ${res.status}): ${body.slice(0, 200)}`);
-  }
-  return parseJson<{ ok: boolean; featureId: string | null }>(res);
-}
-
-/**
- * R2b — fetch the project's grantable feature catalog (the SAME source the admin
- * Roles UI uses), so the access-feature governance control can offer a picker of
- * real features instead of free-text. The endpoint is project-scoped
- * (`requireAdmin` gates `canInvite`), reachable by the owner via `x-project-id`.
- * Returns a flat sorted id list; callers degrade to free-text on failure.
- */
-export async function getGrantableFeatureIds(projectId: string): Promise<string[]> {
-  const res = await fetch('/api/admin/feature-catalog', {
-    method: 'GET',
-    headers: { 'x-project-id': projectId },
-    credentials: 'same-origin',
-  });
-  if (!res.ok) throw new Error(`Failed to load feature catalog: HTTP ${res.status}`);
-  const body = await parseJson<{ groups?: Array<{ features?: string[] }> }>(res);
-  const ids = new Set<string>();
-  for (const g of body.groups ?? []) for (const id of g.features ?? []) ids.add(id);
-  return Array.from(ids).sort();
-}
-
 /**
  * W3F — fetch per-package diagnostics. Reads
  * `GET /api/packages/agent-core/packages/diagnostics`, served by

package/app/filesystem/domain/types.ts

@@ -1,4 +1,4 @@
-import type { SourceLiveReason } from '@neuralis/package-system/contracts';
+import type { ConnectorWatchState, DeviceNotReadyCode, SourceLiveReason } from '@neuralis/package-system/contracts';
 
 export type FileType = 'file' | 'folder';
 
@@ -77,6 +77,12 @@ export interface SourceInfo {
   live?: boolean;
   /** Why `live === false` — fixed enum, mapped to a display string in the UI. */
   live_reason?: SourceLiveReason;
+  /** With `live_reason: 'device_not_ready'`: the device broker's own readiness codes. */
+  live_not_ready?: DeviceNotReadyCode[];
+  /** The scope of the source config this row comes from; absent for a runtime-observed source with no config. */
+  config_scope?: 'project' | 'user' | 'agent';
+  /** How much of the source the live watch covers (`partial`/`off` show as a badge). */
+  watch?: ConnectorWatchState;
   /**
    * Contract-backed owning package id (the package that DECLARES this source in
    * its manifest `sources[]`). `null`/absent for user-added mounts — the Sources
@@ -343,6 +349,9 @@ export interface SourceConfigRecord {
    *  source that never authored its own. This is what the AGENT reads; the
    *  field above is only what is on disk. */
   description_effective?: string | null;
+  /** The folder the server opens for a `local` source on its own plane — natively the
+   *  pair's machine half, never the container spelling. Sent only with the paths. */
+  root_effective?: string;
   connection: {
     /** Open shape — any kind a package contributes via neuralis.connectors[]. */
     kind: string;
@@ -385,7 +394,7 @@ export interface SourceConfigRecord {
   updatedAt?: string;
   // Surfaced by the server-side sources route for UI badges.
   kind_label?: string;
-  kind_trust?: 'first-party' | 'trusted' | 'untrusted' | null;
+  kind_trust?: 'native' | 'trusted' | 'untrusted' | null;
   orphan?: boolean;
   orphan_hint?: string | null;
   observed?: boolean;
@@ -405,12 +414,17 @@ export interface SourceConfigRecord {
   live?: boolean;
   /** Why `live === false` — fixed enum, mapped to a display string in the UI. */
   live_reason?: SourceLiveReason;
+  /** With `live_reason: 'device_not_ready'`: the device broker's own readiness codes. */
+  live_not_ready?: DeviceNotReadyCode[];
+  /** How much of the source the live watch covers (`partial`/`off` show as a badge). */
+  watch?: ConnectorWatchState;
   /**
-   * R2b — local-kind source ALSO acts as a runtime package source (additive to the
-   * default `_packages/` drop-zone). Owner/admin-effective to set; honored for
-   * project AND user/agent scope (advertise isolation enforced downstream).
+   * R2b — the folders of this source that ALSO act as runtime package sources
+   * (additive to the default `_packages/` drop-zone), relative to the source root
+   * (`''` = the whole source). Owner/admin-effective to set; honored for project
+   * AND user/agent scope (advertise isolation enforced downstream).
    */
-  recognizesPackages?: boolean;
+  packageFolders?: string[];
   /**
    * Contract-backed owning package id (manifest `sources[]`); `null`/absent for
    * user-added mounts. The Sources panel groups rows by this (per-package),
@@ -462,8 +476,8 @@ export interface UpdateSourceConfigRequest {
    * the existing config, so disabling sync needs this explicit flag.
    */
   clearSync?: boolean;
-  /** R2b — toggle runtime package recognition (owner/admin-effective, local-only). */
-  recognizesPackages?: boolean;
+  /** R2b — the source's package folders (owner/admin-effective, folder kind only); `[]` clears them. */
+  packageFolders?: string[];
 }
 
 export interface CreateSourceRequest {
@@ -484,8 +498,8 @@ export interface CreateSourceRequest {
     /** Per-source override of the platform `brainMaxScanFiles` scan cap. */
     maxScanFiles?: number;
   };
-  /** R2b — create the (local-kind) source as a runtime package source (owner/admin). */
-  recognizesPackages?: boolean;
+  /** R2b — the new folder's package folders (owner/admin-effective). */
+  packageFolders?: string[];
 }
 
 /**
@@ -731,8 +745,14 @@ export type FSReadResponse = {
      * caller may not read it (uri-policy deny / disabled source). A batch read
      * reports per-file outcomes inside a 200, so the HTTP status cannot carry
      * this — and a refusal must NEVER be read as an absence.
+     * `'source_unavailable'` / `'device_refused'` = a device folder could not
+     * serve the read (`reason` says why); the file very likely still exists.
      */
     code?: string;
+    /** With `source_unavailable` the folder's live reason; with `device_refused` the device's code. */
+    reason?: string;
+    /** With `reason: 'device_not_ready'`: the device broker's own readiness codes. */
+    not_ready?: DeviceNotReadyCode[];
     pinned?: boolean;
     status?: string;
     category?: string;

package/app/filesystem/hooks/README.md

@@ -5,19 +5,19 @@ React hooks used by the Files widget: viewport diff loading and the filesystem S
 ## Responsibility
 
 - `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).
+- `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.
 
 - `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.
 - `useGitChangesInventory(...)` — the Git half of the Changes inventory: per-source repo discovery + status, re-read only when that source's change revision moved (or on a forced refresh), serial behind one tail and epoch-fenced; a source is marked read only once it COMPLETED.
 
-- `useDiscoverableSources({ agentId, projectId, enabled })` — the Discover dock's suggestion fetch (`GET /sources/discoverable`), lazily fired once the dock could actually render.
+- `useDiscoverableSources({ agentId, projectId, enabled })` — the Discover dock's suggestion fetch (`GET /sources/discoverable`), lazily fired once the dock could actually render. It reads and fills the window store's ONE copy (`loadDiscoverable`, keyed by the (agent, project) pair, an in-flight read reused), which the Sources panel reads too — opening Files asks once; the panel's Refresh re-reads (pinned: `test/ui/discoverableOneOwner.test.tsx`).
 
 ## Public Surface
 
 - 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).
+  - **The "already fetched" latch is never state of a hook.** (It now lives in the store's `loadDiscoverable`.) 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).
   - **Liveness is cleared on UNMOUNT ONLY**, never by dependency-change cleanup — otherwise a response is silently dropped when the user expands a branch mid-flight.
   - **A context change RE-ARMS the latch and clears the list.** The store can hydrate `agentId` and `projectId` out of step (a real run sent `projectId=main` under an `ecom` agent and took a correct cross-scope 403); without the re-arm that single racy render kills the dock for the whole page life.
   - Fail-soft: an error yields an empty list, no banner, and does NOT retry-loop.

package/app/filesystem/hooks/useDiscoverableSources.ts

@@ -36,11 +36,17 @@
  *    got a correct cross-scope 403. With the latch reset on change, the corrected
  *    pair simply re-fetches; without it, one racy first render killed the dock
  *    for the whole page life.
+ *
+ * Both now hold by construction: the latch and the answer live in the window
+ * store's `loadDiscoverable` (keyed by the pair, an in-flight read reused), the
+ * ONE owner the Sources panel reads too — so opening Files asks once.
  */
 
-import { useEffect, useRef, useState } from 'react';
-import { listDiscoverableSources, type DiscoverableSourceSuggestion } from '../api';
-import { useFilesystemStore } from '../store/filesystemStore';
+import { useEffect } from 'react';
+import type { DiscoverableSourceSuggestion } from '../api';
+import { discoverableKey, useFilesystemStore } from '../store/filesystemStore';
+
+const NONE: readonly DiscoverableSourceSuggestion[] = [];
 
 export function useDiscoverableSources(params: {
   agentId: string | undefined;
@@ -48,36 +54,19 @@ 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[]>([]);
-
-  // Cleared on UNMOUNT ONLY — never on a dependency change, so a response that
-  // lands while the caller is toggling `enabled` is still delivered.
-  const aliveRef = useRef(true);
-  useEffect(() => {
-    aliveRef.current = true;
-    return () => { aliveRef.current = false; };
-  }, []);
-
-  // The latch. A ref, not state: state would make it a dependency of the effect
-  // it guards. Declared BEFORE the fetch effect so the reset runs first.
-  const fetchedRef = useRef(false);
-  useEffect(() => {
-    fetchedRef.current = false;
-    setSuggestions([]);
-  }, [agentId, projectId]);
+  const loadDiscoverable = useFilesystemStore((s) => s.loadDiscoverable);
+  // The answer lives in the window STORE (its one owner, shared with the
+  // Sources panel), keyed by the pair: a reader on another pair sees nothing,
+  // and the store's held answer / in-flight read is the latch — never state of
+  // this hook, never a dependency of the effect below.
+  const key = agentId ? discoverableKey(agentId, projectId) : null;
+  const suggestions = useFilesystemStore((s) => (key && s.discoverable?.key === key ? s.discoverable.suggestions : NONE));
 
   useEffect(() => {
-    if (!agentId || !enabled || fetchedRef.current) return;
-    fetchedRef.current = true;
-    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, client]);
+    if (!agentId || !enabled) return;
+    void loadDiscoverable({ agentId, ...(projectId ? { projectId } : {}) });
+  }, [agentId, projectId, enabled, loadDiscoverable]);
 
   return suggestions;
 }

package/app/filesystem/hooks/useFilesystemSSE.ts

@@ -334,7 +334,7 @@ export function useFilesystemSSE(agentId: string | undefined, projectId: string
         return;
       }
 
-      // External connector file change (brisk-kingfisher) — a SOURCE-SCOPED signal
+      // External connector file change — a SOURCE-SCOPED signal
       // (no acting user, `external:true`) that a file changed OUTSIDE the platform
       // (a shell / host edit / external program). Like the badge branch this MUST be
       // an EARLY short-circuit BEFORE the `uri` guard + `upsertFileNodeFromEvent`:

package/app/filesystem/host/README.md

@@ -12,8 +12,10 @@ The host integration entry point — `installFilesystemHostComponents`, re-expor
 
 - `FilesystemPackageHost`, `FilesystemPackageHostProps` — `{ port: WorkspaceHostPort, children: ReactNode }`.
 - `useBuildFilesystemHostValue({ port })` — `FilesystemHostValue`. Includes the optional `usePackageIconBySlug()` hook (added 2026-05-07): fetches `/api/packages/agent-core/packages/overview` once per project and exposes `slug → lucide component` so the filetree can render package dock-icons on top-level `packages://<slug>/` and `data://<slug>/` folders. Empty map on miss → falls back to the plain Folder icon.
-- `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 `sources.mount`.
+- `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 the kernel `isOwnerOrAdminEffective` (`@neuralis/package-system/access`: `priority <= 2` or a `'*'` grant — the server gate's own predicate). Used to HIDE the owner-only package-folders field in Sources; 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. Consumers: the Explorer tree's **Discover dock**, gated on `sources.mount`, and the Packages panel's Admin link, gated on `packages.manage`.
+- `FilesystemHostValue.requestDeviceFolder` / `countDeviceFolderRequests` — optional; the folder picker's two device asks, agent-core's `POST`/`GET devices/:id/requests` through a `createPackageApi({slug:'agent-core'})` client built here (a component never fetches another package). The first records a folder on the caller's OWN device for its owner to allow there; the second counts that device's pending asks for this project (`null` = could not ask). Absent ⇒ the picker shows only the `neuralis device grant` line.
+- `FilesystemHostValue.openAdminPackages(agentId)` — optional; opens the Admin widget on its project-scope Packages tab in that agent's window (`port.openWidget`), where trust, Build and the access feature are changed. Absent ⇒ the Packages panel shows no link.
   - 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` 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`.
@@ -23,7 +25,7 @@ The host integration entry point — `installFilesystemHostComponents`, re-expor
 - `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.
 - `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.
+- 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 native 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
 

package/app/filesystem/host/buildFilesystemHostValue.ts

@@ -7,6 +7,7 @@
 
 import { useEffect, useMemo, useState } from 'react';
 import type { WorkspaceHostPort } from '@neuralis/package-system/contracts';
+import { createPackageApi } from '@neuralis/package-system/client';
 import type { FilesystemHostValue, PackageIconRecord } from '../FilesystemHost';
 import type { AgentInfo } from '../ports/types';
 import { resolveLucideIcon } from '../lib/iconResolver';
@@ -100,6 +101,24 @@ export function useBuildFilesystemHostValue({ port }: BuildFilesystemHostValueOp
       });
     },
     isDocker: port.isDocker,
+    openAdminPackages(agentId) {
+      port.openWidget({ agentId, type: 'admin', title: 'Admin', initialState: { scope: 'project', initialTab: 'packages' } });
+    },
+    // The folder picker's two device asks live on agent-core's devices route (the
+    // channel's owner); a component never fetches another package directly.
+    async requestDeviceFolder({ deviceId, path, list, projectId, agentId }) {
+      const api = createPackageApi({ slug: 'agent-core', getProjectId: () => projectId, getAgentId: () => agentId });
+      return api.post<{ recorded: boolean; reason?: string }>(`devices/${encodeURIComponent(deviceId)}/requests`, { path, list });
+    },
+    async countDeviceFolderRequests({ deviceId, projectId, agentId }) {
+      const api = createPackageApi({ slug: 'agent-core', getProjectId: () => projectId, getAgentId: () => agentId });
+      try {
+        const answer = await api.get<{ state?: string; requests?: unknown[] }>(`devices/${encodeURIComponent(deviceId)}/requests`);
+        return answer?.state === 'online' && Array.isArray(answer.requests) ? answer.requests.length : null;
+      } catch {
+        return null;
+      }
+    },
     /**
      * Fetches `/api/packages/agent-core/packages/overview` once per project
      * and exposes `slug → lucide icon component` so the filetree can render

package/app/filesystem/host/installFilesystemHostComponents.tsx

@@ -123,7 +123,7 @@ export function installFilesystemHostComponents(
 
   // Card components live in agent-core's chat card registry; brain-core
   // registers its `filesystem.change` card there at install time, as an OWNED
-  // first-party direct (React) card — `virtualized`, so it never raises the
+  // native direct (React) card — `virtualized`, so it never raises the
   // iframe/keep-alive overscan.
   // `estimateHeight` AND `composer` are MODULE-LEVEL references on purpose: the
   // registry compares them by identity to decide whether a re-registration is