@neuralis/brain-core 0.3.1 → 0.4.0

package/app/filesystem/lib/sourceKindForm.ts

@@ -1,29 +1,24 @@
 /**
- * How a connector kind's ROOT field renders in the Add-Source form — derived
+ * How a connector kind's config fields render in the Add-Source form — derived
  * from the DECLARATION, never from the kind name and never from `isDocker`.
  *
- * Every other field in that form already renders from its declared
- * `x-neuralis.ui`; `root` was the one hand-written, kind-BLIND exception, which
- * is why the Host Machine kind used to show the `local` connector's Docker
- * volume picker, its `pnpm neuralis:mount add` callout and a `/mounts/...`
- * placeholder — while its own declaration already said `Host root path` /
- * `/home/you/projects` (warded-wren, closing the UI half of F-B5).
+ * The form is one page, in the order a person decides: the kind, then WHERE
+ * (a field the declaration marks `x-neuralis.ui.transport` — the `host` kind's
+ * `device`), then the ROOT folder (with Browse when the root declares
+ * `ui.browse`), then the plain fields, and the fields marked `ui.advanced`
+ * folded under "Advanced". `configFields` returns that order.
  *
- * `control` carries the distinction that matters:
- *   - `container-path` — the root lives in the CONTAINER filesystem, so the
- *     `/mounts` volume picker, the mount-CLI callout and Browse all apply.
- *   - `host-path` — the root lives on the operator's machine, reached through
- *     the host broker. None of that chrome applies, and Browse least of all:
- *     `GET /sources/browse` readdirs in the SERVER process, i.e. the wrong
- *     machine. A host root's authority is the operator-owned broker ceiling.
- *   - `path` (or absent) — the pre-existing form. Treated as container-plane,
- *     so an externally authored connector keeps working unchanged.
- *
- * Deliberately NOT keyed on `isHostPlaneKind`: that predicate is a NAME test
- * (`kind === 'host' || kind.startsWith('host-')`) whose own docstring says a
- * future `ssh`/`smb` connector joins the plane by being added to its body. A
- * negative test on that axis would hand the container chrome to every future
- * non-`local` kind — re-creating, in the UI, the kind-blindness this replaces.
+ * The root's meaning follows the transport, not a control name: until the
+ * transport field holds a value the root is a path in THIS server's filesystem
+ * (`container` — the `/mounts` suggestions and the mount-CLI callout apply in
+ * Docker); with a device chosen it is a path ON THAT DEVICE
+ * (`deviceLabel`, and `devicePlaceholders[<the device's platform>]` else
+ * `devicePlaceholder`), browsed through that device's broker and bounded by
+ * the folders its owner allowed. A root control is `container-path`
+ * or the pre-existing bare `path`, so an externally authored connector keeps
+ * working unchanged. Keyed on the DECLARATION and the form's own values, never
+ * on a kind name — a name test would hand one kind's chrome to every future
+ * kind it does not list.
  */
 export type SourceKindFormMeta = {
   kind: string;
@@ -37,6 +32,8 @@ export type RootFieldMeta = {
   container: boolean;
   label: string;
   placeholder: string;
+  /** The root declares `ui.browse`: the form offers the folder picker (on this server, or on the chosen device). */
+  browse: boolean;
 };
 
 type SchemaShape = { required: string[]; properties: Record<string, any> };
@@ -50,17 +47,203 @@ export function schemaShape(meta: SourceKindFormMeta | null | undefined): Schema
   };
 }
 
-const PATH_CONTROLS = new Set(['path', 'container-path', 'host-path']);
+const PATH_CONTROLS = new Set(['path', 'container-path']);
 
-export function rootFieldMeta(meta: SourceKindFormMeta | null | undefined): RootFieldMeta {
+/**
+ * `platform` is the chosen device's claimed platform (its WHERE option's
+ * `platform`): the placeholder takes the declared `devicePlaceholders` entry
+ * for it, else the `devicePlaceholder` default — so a Windows device hints
+ * `C:\…`, never another machine's path style.
+ */
+export function rootFieldMeta(
+  meta: SourceKindFormMeta | null | undefined,
+  values: Readonly<Record<string, unknown>> = {},
+  platform?: string,
+): RootFieldMeta {
   const schema = schemaShape(meta);
   const root = schema.properties.root;
   const ui = root?.['x-neuralis']?.ui;
   const control = typeof ui?.control === 'string' ? (ui.control as string) : undefined;
+  const onDevice = transportChosen(meta, values);
+  const pick = (deviceKey: string, key: string, fallback: string): string =>
+    onDevice && typeof ui?.[deviceKey] === 'string' ? ui[deviceKey] : typeof ui?.[key] === 'string' ? ui[key] : fallback;
+  const perPlatform = onDevice && platform ? ui?.devicePlaceholders?.[platform] : undefined;
   return {
     needed: Boolean(root && (schema.required.includes('root') || (control && PATH_CONTROLS.has(control)))),
-    container: control !== 'host-path',
-    label: typeof ui?.label === 'string' ? ui.label : 'Path',
-    placeholder: typeof ui?.placeholder === 'string' ? ui.placeholder : '',
+    container: !onDevice,
+    label: pick('deviceLabel', 'label', 'Path'),
+    placeholder: typeof perPlatform === 'string' ? perPlatform : pick('devicePlaceholder', 'placeholder', ''),
+    browse: ui?.browse === true,
   };
 }
+
+/** One non-root config field, with the hints the form reads off its `x-neuralis.ui`. */
+export type ConfigField = { key: string; prop: unknown; label: string; help?: string; placeholder?: string };
+
+/**
+ * The non-root config fields in the order the form renders them: `transport`
+ * (WHERE — before the root, because it decides what the root means), `fields`,
+ * and `advanced` (`ui.advanced`, folded). A field the schema's exclusion hides
+ * for the current values (`hiddenByExclusion`) is not offered at all.
+ */
+export function configFields(
+  meta: SourceKindFormMeta | null | undefined,
+  values: Readonly<Record<string, unknown>>,
+): { transport: ConfigField[]; fields: ConfigField[]; advanced: ConfigField[] } {
+  const out = { transport: [] as ConfigField[], fields: [] as ConfigField[], advanced: [] as ConfigField[] };
+  for (const [key, prop] of Object.entries(schemaShape(meta).properties)) {
+    if (key === 'root' || hiddenByExclusion(meta, values, key)) continue;
+    const ui = prop?.['x-neuralis']?.ui ?? {};
+    const field: ConfigField = {
+      key,
+      prop,
+      label: typeof ui.label === 'string' ? ui.label : key,
+      ...(typeof ui.help === 'string' ? { help: ui.help } : {}),
+      ...(typeof ui.placeholder === 'string' ? { placeholder: ui.placeholder } : {}),
+    };
+    (ui.transport === true ? out.transport : ui.advanced === true ? out.advanced : out.fields).push(field);
+  }
+  return out;
+}
+
+/** The kind's one-line card text (`configSchema["x-neuralis"].ui.summary`); the long `description` is the agent's. */
+export function kindSummary(meta: SourceKindFormMeta | null | undefined): string | null {
+  const summary = (meta as any)?.configSchema?.['x-neuralis']?.ui?.summary;
+  return typeof summary === 'string' && summary ? summary : null;
+}
+
+/**
+ * Has the form chosen a TRANSPORT — a value in a field the declaration marks
+ * `x-neuralis.ui.transport` (the `host` kind's `device`)? Then the root is a
+ * path on that device, not in this server's filesystem.
+ */
+export function transportChosen(meta: SourceKindFormMeta | null | undefined, values: Readonly<Record<string, unknown>>): boolean {
+  const { properties } = schemaShape(meta);
+  return Object.entries(properties).some(([key, prop]) =>
+    prop?.['x-neuralis']?.ui?.transport === true && typeof values[key] === 'string' && values[key] !== '');
+}
+
+/**
+ * Is this field hidden because a field it is mutually exclusive with (the
+ * schema's `not: { required: [...] }`) already holds a value? The kind's
+ * validator refuses the pair, so the form never offers it.
+ */
+export function hiddenByExclusion(meta: SourceKindFormMeta | null | undefined, values: Readonly<Record<string, unknown>>, key: string): boolean {
+  const exclusive = (meta as any)?.configSchema?.not?.required;
+  if (!Array.isArray(exclusive) || !exclusive.includes(key)) return false;
+  return exclusive.some((other: unknown) => other !== key && typeof other === 'string'
+    && values[other] !== undefined && values[other] !== '');
+}
+
+/**
+ * How a NON-root config field renders. A CLOSED set: `text` (the default — a
+ * plain input, `number` for a numeric type) and `select`, whose options a
+ * route in the DECLARING package answers (`x-neuralis.ui.optionsRoute`).
+ *
+ * The list a `select` shows is UX only: the declaring package re-checks the
+ * picked value when the source is created (a host source's `device` is
+ * re-checked by the device's owner rule), so the form never decides who may
+ * attach what. An `optionsRoute` the form refuses (absolute, a scheme, a `..`
+ * segment, an escape) renders the field as `text` and names the refusal —
+ * never a request to somewhere the declaration did not mean.
+ */
+export type FieldControl =
+  | { control: 'text'; numeric: boolean; refused?: string }
+  | { control: 'select'; numeric: boolean; options: OptionsRoute; emptyLabel?: string };
+
+/** A validated options route: one package-relative path + its query. */
+export type OptionsRoute = { slug: string; path: string; params: Record<string, string> };
+
+const ROUTE_PATH = /^[A-Za-z0-9][A-Za-z0-9._~-]*(?:\/[A-Za-z0-9._~-]+)*$/;
+const ROUTE_QUERY_PART = /^[A-Za-z0-9._~-]+$/;
+
+/**
+ * The `/api/packages/<slug>` segment of a registry id: the native scope is
+ * dropped (`@neuralis/agent-core` → `agent-core`, the same rule the route
+ * gateway resolves), any other id travels as ONE encoded segment.
+ */
+export function packageRouteSlug(packageId: string): string {
+  return encodeURIComponent(packageId.replace(/^@neuralis\//, ''));
+}
+
+/**
+ * Parse a declared `optionsRoute` against the package that declares the field.
+ * Relative only, plain path segments (no `.`/`..`, no `%`, no `\`), an optional
+ * `key=value&…` query of the same characters, ≤ 200 characters.
+ */
+export function parseOptionsRoute(raw: unknown, packageId: string): OptionsRoute | { refused: string } {
+  if (typeof raw !== 'string' || raw.length === 0 || raw.length > 200) {
+    return { refused: 'optionsRoute must be a non-empty string of at most 200 characters' };
+  }
+  if (!packageId) return { refused: 'optionsRoute has no declaring package' };
+  const [path, query, extra] = raw.split('?');
+  if (extra !== undefined || !ROUTE_PATH.test(path ?? '')) {
+    return { refused: 'optionsRoute must be a relative route inside the declaring package' };
+  }
+  if ((path ?? '').split('/').some((segment) => segment === '.' || segment === '..')) {
+    return { refused: 'optionsRoute must be a relative route inside the declaring package' };
+  }
+  const params: Record<string, string> = {};
+  if (query !== undefined) {
+    for (const pair of query.split('&')) {
+      const [key, value, more] = pair.split('=');
+      if (more !== undefined || !key || !ROUTE_QUERY_PART.test(key) || (value !== undefined && value !== '' && !ROUTE_QUERY_PART.test(value))) {
+        return { refused: 'optionsRoute query must be plain key=value pairs' };
+      }
+      params[key] = value ?? '';
+    }
+  }
+  return { slug: packageRouteSlug(packageId), path: path as string, params };
+}
+
+/**
+ * An OPTIONAL select (`ui.optional`) offers its `emptyLabel` as a real choice —
+ * the empty value (for the `host` kind's `device`: "This server"); a required
+ * one only lists the route's rows.
+ */
+export function fieldControl(prop: unknown, packageId: string): FieldControl {
+  const p = (prop ?? {}) as { type?: unknown; 'x-neuralis'?: { ui?: { control?: unknown; optionsRoute?: unknown; optional?: unknown; emptyLabel?: unknown } } };
+  const numeric = p.type === 'number' || p.type === 'integer';
+  const ui = p['x-neuralis']?.ui;
+  if (ui?.control !== 'select') return { control: 'text', numeric };
+  const route = parseOptionsRoute(ui.optionsRoute, packageId);
+  if ('refused' in route) return { control: 'text', numeric, refused: route.refused };
+  const emptyLabel = ui.optional === true ? (typeof ui.emptyLabel === 'string' && ui.emptyLabel ? ui.emptyLabel : 'None') : undefined;
+  return { control: 'select', numeric, options: route, ...(emptyLabel ? { emptyLabel } : {}) };
+}
+
+/** One row of a `select`: the stored value, its label, whether it reads dimmed, and a device row's claimed `platform`. */
+export type SelectOption = { value: string; label: string; dimmed: boolean; platform?: string };
+
+/** The OS word a device row's `platform` reads as; any other token prints as it came. */
+const PLATFORM_WORDS: Readonly<Record<string, string>> = { win32: 'Windows', darwin: 'macOS', linux: 'Linux' };
+
+/**
+ * The options an `optionsRoute` answered. The answer is a JSON object whose
+ * FIRST array-valued property lists the rows; a row is `{id, name?, platform?,
+ * status?, confinement?}` (the shape of a device list). The label is
+ * `name · OS · status · confinement`; a `revoked` row is not offered at all; any
+ * status other than `online` reads dimmed but stays selectable — attaching a
+ * source to an offline device is allowed, it simply answers once the device is
+ * back. Rows without a string `id` are dropped.
+ */
+export function selectOptionsFrom(answer: unknown): SelectOption[] {
+  if (!answer || typeof answer !== 'object') return [];
+  const rows = Object.values(answer as Record<string, unknown>).find(Array.isArray) as unknown[] | undefined;
+  if (!rows) return [];
+  const out: SelectOption[] = [];
+  for (const row of rows) {
+    if (!row || typeof row !== 'object') continue;
+    const r = row as { id?: unknown; name?: unknown; platform?: unknown; status?: unknown; confinement?: unknown };
+    if (typeof r.id !== 'string' || r.id.length === 0) continue;
+    const status = typeof r.status === 'string' ? r.status : undefined;
+    if (status === 'revoked') continue;
+    const platform = typeof r.platform === 'string' && r.platform ? r.platform : undefined;
+    const parts = [typeof r.name === 'string' && r.name ? r.name : r.id];
+    if (platform) parts.push(PLATFORM_WORDS[platform] ?? platform);
+    if (status) parts.push(status.replace(/_/g, ' '));
+    if (typeof r.confinement === 'string') parts.push(r.confinement);
+    out.push({ value: r.id, label: parts.join(' · '), dimmed: status !== undefined && status !== 'online', ...(platform ? { platform } : {}) });
+  }
+  return out;
+}

package/app/filesystem/lib/treeVisualState.tsx

@@ -326,27 +326,121 @@ export function getSourceVisualTone(info: SourceInfo): {
 // gone. Returned as a plain string for the parent button's `title` tooltip.
 /** Display strings for the `SourceLiveReason` enum (the wire value is an enum to
  *  keep it parseable / leak-free — the human text is mapped here, in the UI). */
+/** How a device's owner updates the CLI that serves it: the desktop app carries it, an npm install updates by npm (`neuralis update` is the SERVER's verb, never a device's). */
+const DEVICE_UPDATE_STEPS = 'update the Neuralis desktop app on that computer, or run npm i -g @neuralis/cli@latest there, then neuralis device install';
+
 const LIVE_REASON_LABEL: Record<string, string> = {
   runtime_offline: 'Machine offline — container not running',
   fs_unreachable: 'Filesystem unreachable — mount missing',
   fs_permission: 'Filesystem unreadable — permission denied',
   store_unreachable: 'Store offline — backing service unreachable',
+  broker_outdated: `Device needs an update — ${DEVICE_UPDATE_STEPS}`,
+  devices_disabled: 'Devices are turned off on this server — an admin turns them on in Admin → Config',
+  device_not_ready: 'Device not ready — neuralis device status on that computer says why',
+};
+
+/** A `host` folder is offline only through its device's link (an in-process folder answers `fs_*`). */
+const DEVICE_OFFLINE_LABEL = 'Device offline — it is not connected to this server';
+
+/** What a device's owner fixes there, per broker readiness code (`DeviceNotReadyCode`). */
+const DEVICE_NOT_READY_LABEL: Record<string, string> = {
+  ceiling_missing_or_empty: 'no folder is allowed on it yet (neuralis device grant on that computer)',
+  sandbox_helper_missing: 'its sandbox helper is not usable (neuralis device install on that computer)',
+  socket_isolation_failed: 'its sandbox cannot keep commands away from the computer\'s own control sockets (neuralis device status on that computer says how to fix it)',
+  secret_file_missing_or_too_short: 'its pairing secret is missing (pair it again)',
+  scratch_root_missing: 'its scratch folder is missing (neuralis device install on that computer)',
 };
 
 /** Map a `SourceLiveReason` (or undefined) to its display string. Shared by the
- *  file tree tooltip and the Sources panel so both render the same text. */
-export function sourceLiveReasonLabel(reason?: string | null): string {
+ *  file tree tooltip, the Sources panel and the read/preview failures so all
+ *  render the same text: `kind` words an offline `host` folder as its device,
+ *  `notReady` names a not-ready device's own codes. */
+export function sourceLiveReasonLabel(reason?: string | null, opts: { kind?: string | null; notReady?: readonly unknown[] | null } = {}): string {
+  if (reason === 'runtime_offline' && opts.kind === 'host') return DEVICE_OFFLINE_LABEL;
+  if (reason === 'device_not_ready') {
+    const known = (opts.notReady ?? []).flatMap((code) => (typeof code === 'string' && DEVICE_NOT_READY_LABEL[code] ? [DEVICE_NOT_READY_LABEL[code]] : []));
+    if (known.length > 0) return `Device not ready — ${known.join('; ')}`;
+  }
   return (reason ? LIVE_REASON_LABEL[reason] : undefined)
     ?? 'Disconnected — connector cannot reach its backing filesystem';
 }
 
+/**
+ * The source row's live-watch badge: `null` while the watch covers the whole
+ * source (or none is meant for it), else the label and the tooltip that says
+ * what is and is not live right now.
+ */
+export function sourceWatchBadge(
+  watch: string | null | undefined,
+  liveReason?: string | null,
+): { label: string; title: string; tone: 'pending' | 'warn' } | null {
+  if (watch === 'starting') {
+    return {
+      label: 'Live: starting',
+      title: 'Live changes are starting: the watcher is still walking this source\'s folders. Until it is ready, a change can arrive only with the next reconcile or Sync now.',
+      tone: 'pending',
+    };
+  }
+  if (watch === 'partial') {
+    return {
+      label: 'Live: partial',
+      title: 'Live changes cover part of this source: it has more folders than the watcher budget (brainWatchMaxFolders) or this computer\'s watch limit allows. Changes in the folders past it, new folders there included, are picked up by the next full reconcile (every 24 h by default) or by Sync now.',
+      tone: 'warn',
+    };
+  }
+  if (watch === 'off') {
+    return {
+      label: 'Live: off',
+      title: liveReason === 'broker_outdated'
+        ? `No live changes for this source: its device runs a CLI too old to watch — ${DEVICE_UPDATE_STEPS}. Changes arrive with the regular sync.`
+        : `No live changes for this source: its watch is not running (a device may be offline, or run a CLI too old to watch — ${DEVICE_UPDATE_STEPS}). Changes arrive with the regular sync.`,
+      tone: 'warn',
+    };
+  }
+  return null;
+}
+
+/** A device refusal code its owner can act on, in words — the file read, the preview and the source row say it alike. */
+const DEVICE_REFUSAL_LABEL: Record<string, string> = {
+  host_fs_denied: 'Not allowed on that device yet — ask there (tray → Allow a folder…, or neuralis device grant); it serves once allowed',
+};
+
+/** A device's refusal of one file, by its fixed code; `undefined` for anything that is not a code. */
+export function deviceRefusalLabel(reason: unknown): string | undefined {
+  if (typeof reason !== 'string' || !/^[a-z][a-z0-9_]{0,63}$/.test(reason)) return undefined;
+  return DEVICE_REFUSAL_LABEL[reason] ?? `The device refused this file (${reason})`;
+}
+
+/** The fixed codes a refused sync persists as `lastSyncResult.error` (a device's refusal codes too, by the map above). */
+const SYNC_REFUSAL_LABEL: Record<string, string> = {
+  root_unreachable: 'Sync stopped — the source folder cannot be reached (unmounted, renamed or offline). Nothing was removed from the index.',
+  root_empty: 'Sync stopped — the source folder is empty, but the index still holds its files. Nothing was removed. Choose Sync anyway if the folder really is empty.',
+};
+
+/** A sync error for display: the label of a fixed refusal code, any other text unchanged. */
+export function syncErrorLabel(error: string): string {
+  return SYNC_REFUSAL_LABEL[error] ?? DEVICE_REFUSAL_LABEL[error] ?? error;
+}
+
+/**
+ * Why a source that lists nothing is UNAVAILABLE rather than empty: its live
+ * state, else the code its walk, count or last sync stopped on (`last_error` —
+ * a failed walk or count never sets `sync_status`); `undefined` = truly empty.
+ */
+export function sourceUnavailableLabel(info: SourceInfo): string | undefined {
+  if (info.live === false) return sourceLiveReasonLabel(info.live_reason, { kind: info.source_kind, notReady: info.live_not_ready });
+  return info.last_error ? syncErrorLabel(info.last_error) : undefined;
+}
+
 export function resolveSourceToneTitle(info: SourceInfo): string | null {
   if (info.enabled === false) return 'Source disabled';
   if (info.enabled === 'auto' && info.enabled_effective === false) return 'Source auto — currently stopped';
-  if (info.live === false) return sourceLiveReasonLabel(info.live_reason);
-  if (info.sync_status === 'error') return info.last_error ?? 'Sync error';
+  if (info.live === false) return sourceLiveReasonLabel(info.live_reason, { kind: info.source_kind, notReady: info.live_not_ready });
+  if (info.sync_status === 'error') return info.last_error ? syncErrorLabel(info.last_error) : 'Sync error';
   if (info.sync_status === 'paused') return 'Sync paused';
   if (info.sync_status === 'active') return 'Sync active';
+  // A failed walk or count leaves `sync_status` alone: neutral tone, the code as the title.
+  if (info.last_error) return syncErrorLabel(info.last_error);
   return null;
 }
 

package/app/filesystem/store/README.md

@@ -65,6 +65,7 @@ Two guards make this safe against the races a plain re-list would lose:
 - **`pendingSourceSuggestion` is a HANDOFF, not state.** The tree's Discover dock cannot call into `SourcesPanel` — the panel is a conditional mount and does not exist at click time — so the pick travels through the store and the panel consumes it on mount, clearing it in the same tick. It is deliberately OUT of the persist allowlist (a reload that re-opened a prefilled Add-Source form by itself is the ghost class this store already fought) and `loadList`'s context reset clears it beside `workspacePanels`, so a pick can never strand across an agent/project switch and prefill a root the new context does not have.
 - `loadedFolders[uri]` means "this folder HAS been enumerated". Only a successful listing sets it. Marking a source loaded that was never listed (the old `loadList` did this for every source, connector-failed ones included) lets a later absence pass prune everything under it. `false` is a third state, STALE: enumerated once, then taken off screen by a collapse. Every truthiness reader treats it as not loaded; `ensureFolderLoaded` on a stale folder runs ONE narrow authoritative pass over exactly that folder (`runSourceReconcile({ wide: false })`, absence applies) instead of an upsert-only listing, and that pass marks it `true` again; a stale folder put back on screen another way (`autoExpandToFile`, a nav link) is re-listed by the next wide pass. A narrow re-open pass whose listing FAILS leaves the folder stale, with only the source header's "may be out of date" hint; the next collapse and re-open retries it.
 - **Collapse and the bound.** `toggleFolder` collapsing a folder drops every expanded descendant from `expandedFolders` and marks every enumerated folder at or under it stale — so no reconcile keeps listing what nobody can see. The expanded set is capped at `EXPANDED_FOLDERS_CAP` (`listSlice.ts`); `expandPatch` moves each newly expanded folder to most-recent and `boundExpandedFolders` drops the oldest LEAF (never an ancestor of a kept folder, never a source root), marking it stale like a collapse. `autoExpandToFile` is the writer that needs it: it adds a folder chain for every pending write an agent makes. The persisted projection and a rehydrated legacy payload are bounded the same way.
+- **Per-source refresh:** It works on a collapsed source too — an explicit click is a user intent, unlike the automatic event-driven loads, which never list a collapsed source — and it opens the branch so the result is visible.
 
 ## Tests
 

package/app/filesystem/store/filesystemStore.ts

@@ -4,7 +4,7 @@ import { persist, createJSONStorage } from 'zustand/middleware';
 import { createStore, type StoreApi as ZustandStoreApi } from 'zustand/vanilla';
 import type { ClientStateResetScope } from '@neuralis/package-system/contracts';
 import { createPackageApi, type PackageApi } from '@neuralis/package-system/client';
-import type { EditorTabMeta, FileNode, FileSystemState, FSWriteResponse, PersistedFilesContext, PersistedFilesWindow, SidebarView, WorkspacePanelId } from '../domain/types';
+import type { EditorTabMeta, FileNode, FileSystemState, FSWriteResponse, PersistedFilesContext, PersistedFilesWindow, SidebarView, SourceInfo, WorkspacePanelId } from '../domain/types';
 export type { SidebarView, WorkspacePanelId } from '../domain/types';
 import { countPendingChanges, readFiles, uploadFile, writeFile, writeRefusalMessage } from '../api';
 import {
@@ -21,8 +21,9 @@ import {
   sourceRootUri,
   uriAncestors,
   parseFilePrev,
+  readFailureMessage,
 } from './helpers';
-import { resolveList, type DiscoverableSourceSuggestion } from '../api';
+import { listDiscoverableSources, resolveList, type DiscoverableSourceSuggestion } from '../api';
 import { searchSliceInitial, createSearchSlice, type SearchSliceActions } from './searchSlice';
 import { boundExpandedFolders, contextResetPatch, createListSlice, persistedContext, sliceFromPersisted, type ListSliceActions } from './listSlice';
 import { gitSliceInitial, createGitSlice, type GitSliceState, type GitSliceActions } from './gitSlice';
@@ -185,6 +186,38 @@ function repairParentUri(next: Record<string, any>, rawUri: string, prev: any):
   return fixed;
 }
 
+/**
+ * A folder listing carries its source's CURRENT state. The tree's empty row and
+ * header read `state.sources`, which otherwise only the sources-only listing
+ * writes — so a Refresh that found the device gone would show "No files" until
+ * the next background pass. Only the live/sync fields move; counts and every
+ * other field stay with the listing that asked for them.
+ */
+export function mergeListedSourceState(current: SourceInfo[], res: { sources?: unknown }): SourceInfo[] {
+  const listed = Array.isArray(res.sources) ? (res.sources as SourceInfo[]) : [];
+  if (listed.length === 0 || current.length === 0) return current;
+  let out = current;
+  for (const fresh of listed) {
+    const i = current.findIndex((s) => s.uri_root === fresh.uri_root);
+    if (i < 0) continue;
+    const old = current[i];
+    const patch: SourceInfo = {
+      ...old,
+      live: fresh.live,
+      live_reason: fresh.live_reason,
+      live_not_ready: fresh.live_not_ready,
+      sync_status: fresh.sync_status,
+      last_error: fresh.last_error,
+    };
+    if (patch.live === old.live && patch.live_reason === old.live_reason
+      && patch.live_not_ready === old.live_not_ready && patch.sync_status === old.sync_status
+      && patch.last_error === old.last_error) continue;
+    if (out === current) out = current.slice();
+    out[i] = patch;
+  }
+  return out;
+}
+
 function applyListedNodes(
   next: Record<string, any>,
   res: { folders?: unknown[]; files?: unknown[] },
@@ -476,6 +509,10 @@ async function runReconcilePass(
     const pruned: string[] = [];
     let anyAuthoritative = false;
     let incomplete = false;
+    const listedSources = (st: any): SourceInfo[] => listed.reduce(
+      (acc: SourceInfo[], entry) => (entry.ok && entry.res ? mergeListedSourceState(acc, entry.res) : acc),
+      st.sources ?? [],
+    );
 
     for (const entry of listed) {
       if (!entry.ok || !entry.res) { incomplete = true; continue; }
@@ -504,7 +541,7 @@ async function runReconcilePass(
     if (!anyAuthoritative) {
       // Every listing failed or was truncated → upsert-only, no absence pass.
       return withPendingDelta(
-        { files: evictColdSubtrees(next, state.expandedFolders, state.openFiles), dirtySources, loadedFolders },
+        { files: evictColdSubtrees(next, state.expandedFolders, state.openFiles), dirtySources, loadedFolders, sources: listedSources(state) },
         state.pendingReviewPaths,
         pendingDelta,
       );
@@ -605,6 +642,7 @@ async function runReconcilePass(
       out.fileContentByPath = cbp; out.fileBaseContentByPath = bbp;
       out.fileErrorByPath = ebp; out.filePrevByPath = pbp;
     }
+    out.sources = listedSources(state);
     return withPendingDelta(out, state.pendingReviewPaths, pendingDelta);
   });
 }
@@ -810,7 +848,7 @@ interface FilesystemStore extends FileSystemState, SearchSliceActions, ListSlice
     force?: boolean;
   }) => Promise<void>;
   /**
-   * brisk-kingfisher — reconcile the open (expanded) folders of ONE source against
+   * Reconcile the open (expanded) folders of ONE source against
    * the connector's CURRENT truth, in response to an EXTERNAL file change SSE event.
    * Re-lists each expanded+loaded folder under the source and, per direct child
    * absent from the fresh (non-truncated) listing: prunes an `unindexed` external-
@@ -900,6 +938,13 @@ interface FilesystemStore extends FileSystemState, SearchSliceActions, ListSlice
   activeFolderPath: string | null;
 
   uploading: boolean;
+  /**
+   * Bumped once per burst of `devices` frames (and on a hub reconnect): a
+   * paired device changed state. Consumers holding their own device fetch —
+   * the source form's device `select` — re-read on it. Not per context and
+   * never persisted.
+   */
+  deviceRevision: number;
   workspacePanels: Record<WorkspacePanelId, boolean>;
   // `'git-diff'` (G2.2) and `'git-commit'` (G2.4/C2 — the multi-file stacked
   // commit/outgoing view) are VIEWS, not toggleable panels — they live outside
@@ -925,6 +970,22 @@ interface FilesystemStore extends FileSystemState, SearchSliceActions, ListSlice
    */
   pendingSourceSuggestion: DiscoverableSourceSuggestion | null;
   setPendingSourceSuggestion: (suggestion: DiscoverableSourceSuggestion | null) => void;
+  /**
+   * The attachable-but-unattached source suggestions (`GET sources/discoverable`)
+   * for ONE (agent, project) pair — the ONE owner both consumers read: the
+   * tree's Discover dock (`useDiscoverableSources`) and the Sources panel (its
+   * list + the folder picker's Suggested row). `key` names the pair the answer
+   * belongs to; a reader on another pair sees nothing. Not persisted.
+   */
+  discoverable: { key: string; suggestions: readonly DiscoverableSourceSuggestion[] } | null;
+  /**
+   * Fetch the suggestions for a pair: an answer already held for it (or one in
+   * flight) is reused, so opening Files costs ONE request whoever asks first;
+   * `fresh` re-reads (the panel's Refresh, after a mutation). Fail-soft: a
+   * failure holds an empty list for the pair (no retry loop) until the next
+   * fresh read or a context change.
+   */
+  loadDiscoverable: (ctx: { agentId: string; projectId?: string }, opts?: { fresh?: boolean }) => Promise<readonly DiscoverableSourceSuggestion[]>;
   /**
    * Is the Sources panel's Vector Health section open? In the STORE so a
    * notification's `open-vector-health` nav can open it while the panel is not
@@ -1088,9 +1149,11 @@ const FILESYSTEM_WIDGET_TYPE = 'filesystem';
 /**
  * File-tree sidebar is a **fixed pixel** column (mirrors the admin widget):
  * its width is independent of the outer widget size, so resizing the widget in
- * the workspace never reflows the tree. The width is user-draggable and survives
- * reloads via localStorage. The drag handle clamps the upper bound to the live
- * container width so the tree can fully cover the file editor.
+ * the workspace never reflows the tree until the widget edge reaches it — then
+ * the rendered width is capped to the container and grows back to this stored
+ * width on widening. The width is user-draggable and survives reloads via
+ * localStorage. The drag handle clamps the upper bound to the live container
+ * width so the tree can fully cover the file editor.
  */
 export const FILESYSTEM_SIDEBAR_MIN_WIDTH = 120;
 const SIDEBAR_WIDTH_DEFAULT = 240;
@@ -1138,6 +1201,11 @@ export type FilesystemStoreInit = {
 
 export type FilesystemStoreApi = ZustandStoreApi<FilesystemStore>;
 
+/** The (agent, project) pair a discoverable answer belongs to. */
+export function discoverableKey(agentId: string, projectId: string | undefined): string {
+  return `${agentId}\n${projectId ?? ''}`;
+}
+
 /**
  * ONE Files store per window: a live view that persists nothing itself — the
  * ONE writer of `neuralis.filesystem.tabs` is `filesPersistence` below, which a
@@ -1149,6 +1217,8 @@ export type FilesystemStoreApi = ZustandStoreApi<FilesystemStore>;
 export function createFilesystemStore(init: FilesystemStoreInit): FilesystemStoreApi {
   const fences = createStoreFences();
   const client = init.client;
+  // The one discoverable read in flight for this window (`loadDiscoverable`).
+  let discoverableInFlight: { key: string; promise: Promise<readonly DiscoverableSourceSuggestion[]> } | null = null;
   return createStore<FilesystemStore>()((set, get) => ({
   windowId: init.windowId ?? null,
   client,
@@ -1178,9 +1248,11 @@ export function createFilesystemStore(init: FilesystemStoreInit): FilesystemStor
   activeRepoRel: '',
   activeFolderPath: 'brain://docs',
   uploading: false,
+  deviceRevision: 0,
   workspacePanels: { upload: false, sources: false, packages: false, pending: false },
   activeWorkspaceTab: 'file',
   pendingSourceSuggestion: null,
+  discoverable: null,
   vectorHealthOpen: false,
   diffViewMode: init.diffViewMode ?? 'auto',
   pendingPanelFilter: {},
@@ -1253,6 +1325,24 @@ export function createFilesystemStore(init: FilesystemStoreInit): FilesystemStor
       return { workspacePanels: nextPanels, activeWorkspaceTab };
     }),
   setPendingSourceSuggestion: (suggestion) => set(() => ({ pendingSourceSuggestion: suggestion })),
+  loadDiscoverable: (ctx, opts) => {
+    const key = discoverableKey(ctx.agentId, ctx.projectId);
+    const held = get().discoverable;
+    if (!opts?.fresh && held?.key === key) return Promise.resolve(held.suggestions);
+    if (!opts?.fresh && discoverableInFlight?.key === key) return discoverableInFlight.promise;
+    const promise = listDiscoverableSources({ agentId: ctx.agentId, ...(ctx.projectId ? { projectId: ctx.projectId } : {}) }, client)
+      .then((res) => res.suggestions ?? [], () => [] as DiscoverableSourceSuggestion[])
+      .then((suggestions) => {
+        // Only the newest read for a pair writes it; a superseded one answers its caller alone.
+        if (discoverableInFlight?.promise === promise) {
+          discoverableInFlight = null;
+          set(() => ({ discoverable: { key, suggestions } }));
+        }
+        return suggestions as readonly DiscoverableSourceSuggestion[];
+      });
+    discoverableInFlight = { key, promise };
+    return promise;
+  },
   setVectorHealthOpen: (open) => set(() => ({ vectorHealthOpen: open })),
   setActiveWorkspaceTab: (tab) => set(() => ({ activeWorkspaceTab: tab })),
   setDiffViewMode: (mode) => set(() => ({ diffViewMode: mode })),
@@ -1378,6 +1468,7 @@ export function createFilesystemStore(init: FilesystemStoreInit): FilesystemStor
               // to list must not have its (never-listed) children pruned.
               loadedFolders: { ...(state.loadedFolders || {}), [uri]: true },
               hydrationState: { ...(state.hydrationState || {}), [uri]: 'ready' as const },
+              sources: mergeListedSourceState(state.sources ?? [], res),
             },
             state.pendingReviewPaths,
             pendingDelta,
@@ -2159,7 +2250,7 @@ export function createFilesystemStore(init: FilesystemStoreInit): FilesystemStor
       if (files.length > 0) {
         const f = files[0];
         const content = extractFileContent(f);
-        const error = typeof f.error === 'string' ? f.error : undefined;
+        const error = readFailureMessage(f);
         // The file is GONE, not merely unreadable. This matters because the open-tab
         // shape is PERSISTED: a tab pointing at a deleted file re-materialises its
         // node (and its whole folder chain) on every page load, producing a tree row

package/app/filesystem/store/gitSlice.ts

@@ -198,6 +198,11 @@ export function createGitSlice(
           ...(repoRel ? { repo: repoRel } : {}),
         }, get().client);
         if (mySeq !== gitStatusSeq) return;
+        if (res?.ok === false) {
+          // A checkout git could not read is never shown as "No changes".
+          set(() => ({ gitStatus: null, gitTotals: null, gitLoading: false, gitError: res.error }));
+          return;
+        }
         // `totals` rides the SAME response as the rows it sums (the server
         // computes it after its read filter and cap), so the header can never
         // show a number the list below contradicts.