@neuralis/brain-core 0.3.0 → 0.3.2

package/README.md

@@ -33,10 +33,11 @@ content-free existence probe a caller uses instead of reading a whole file to
 learn it is still there), `brain`
 (Qdrant-backed internal memory; reads go through `FilesystemService`, not the
 placeholder connector). Other packages contribute more kinds — `webtop` from
-`machine-core`, and `host` from `agent-core` (a read-WRITE view of the
-operator's machine through the host broker — 12 declared capabilities including
-`write`/`delete`/`move`/`mkdir`/`rmdir`; containment comes from the
-operator-owned broker ceiling, never from a missing capability. See the
+`machine-core`, and `host` from `agent-core` (a read-WRITE view of a paired
+device — the server or a person's own machine — through its broker over the device
+link; 13 declared capabilities including `write`/`delete`/`move`/`mkdir`/`rmdir`
+and `rawRead`; containment comes from the device owner's ceiling, never from a
+missing capability. See the
 host-plane rules below).
 
 A connector's **manifest id is not its kind**, and only the KIND addresses the
@@ -82,7 +83,7 @@ URI schemes you will see in production:
 | `data://` | `local` | builtin | Project data zone (`{neuralisHome}/projects/{pid}/data/`) |
 | `data.X://` | `local` | user | Additional `local` mount with a named slug |
 | `packages://` | `local` | builtin | Project's `_packages/` directory |
-| `app://` | `local` | builtin (privileged mount — `drive.mount.privileged`) | Platform app zone (`~/.neuralis/app/`); writes from agents are denied |
+| `app://` | `local` | builtin (privileged mount — `sources.privileged`) | Platform app zone (`~/.neuralis/app/`); writes from agents are denied |
 | `neuralis://` | `local` | user (`pnpm neuralis:mount add … --neuralis`) | The deployment's OWN `neuralis/` folder, live from the host. Surfaces as a `local`-kind source — there is **no** dedicated `neuralis` connector kind. The switch is `--neuralis`, not `--slug neuralis` (that is the ordinary data mount at `/mounts/neuralis`, without the two anonymous volumes that keep `_runtime/` and `node_modules/` from being shadowed). |
 | `neuralis-skills://` | `local` | user (same overlay, rooted at `<root>/skills`) | The narrower default: only the shipped operator skills. Preferred over `neuralis://` for giving an agent the operator-command vocabulary — the overlay root holds `.env`, and a source root is a READ boundary in a way a sync `include` is not. |
 | `machine://` | `webtop` | machine-core | Webtop sandbox; declared by `machine-core`, not brain-core. `machine` is the slug / `urlScheme` — the registry KIND is `webtop`, and only the kind addresses `GET /sources/kinds/:kind/schema`. |
@@ -483,18 +484,18 @@ in-source over-refresh is fine, never a leak), and cache invalidation is already
 
 **`git.canWrite` — the write-UI visibility gate.** `canWrite` is computed SERVER-side
 **per-caller** as the SAME two-plane gate the write routes enforce: the caller HAS the
-`drive.write` FEATURE **and** the caller's RESOLVED uri-policy `write` on the source root
+`files.write` FEATURE **and** the caller's RESOLVED uri-policy `write` on the source root
 `<slug>://` is allowed (`resolveGitCanWrite`, deny-by-default). The panel shows the
 Stage/Unstage/Discard/Commit/branch-write affordances IFF `git.canWrite === true` — or, with
 a focused NESTED repo, IFF that repo's `/git/repos` row carries `canWrite: true` (the
 per-repo granularity above; the root row's flag is not consulted). This must NOT
 be derived from `SourceInfo.permissions.write` (the source's DEFAULT permission block) — that
 hid the owner's write UI on a `default write:false` source where the owner gains write via
-`byRole`/`byUser`, and would also show buttons to a `drive.read`-only role. The server route is
+`byRole`/`byUser`, and would also show buttons to a `files.read`-only role. The server route is
 the deny-by-default floor regardless of this UI gate.
 
-**The `git/*` routes** (`src/routes/git.ts`, file-level `feature='drive.read'`):
-- **GET (read, `drive.read`):** `status?source=<slug>` (whole-repo change-set + current
+**The `git/*` routes** (`src/routes/git.ts`, file-level `feature='files.read'`):
+- **GET (read, `files.read`):** `status?source=<slug>` (whole-repo change-set + current
   branch, plus `upstream`/`ahead`/`behind` when the branch tracks an upstream — all
   three absent otherwise), `branch?source=<slug>` (local branch list, for the switcher),
   `diff?source=<slug>&path=<repoRelPath>&(staged=<0|1> | commit=<sha> | base=<sha>&head=<sha>)`
@@ -526,7 +527,7 @@ the deny-by-default floor regardless of this UI gate.
   `repos?source=<slug>` (the in-source repo-picker listing `{rel, name, branch?,
   canWrite}`; names-only, source-root read gate + per-nested-name filter —
   see the multi-repo model above).
-- **POST (write, additionally `drive.write`-gated):** `stage` (`{paths[]}` whole-file `add`
+- **POST (write, additionally `files.write`-gated):** `stage` (`{paths[]}` whole-file `add`
   OR `{hunk}` `git apply --cached`), `unstage` (`{paths[]}` `reset -- <p>` OR `{hunk}`
   reverse-apply), `discard` (`{paths[]}` restore WT from index; typed `rescue?` returned),
   `commit` (`{message, amend?}`), `branch` (`{action:'create'|'delete', name, startPoint?,
@@ -582,7 +583,7 @@ would corrupt expanded diff context.
 
 **Write model — human consent + SERVER unconditional auto-snapshot.** The write POST
 routes are the HUMAN face of the git engine: the caller's authenticated session IS the consent
-(`drive.write` feature + uri-policy `write`), NOT the `PendingInteraction` agent-approval
+(`files.write` feature + uri-policy `write`), NOT the `PendingInteraction` agent-approval
 guard (that is the additive AGENT face, a later increment; both faces drive the same `GitRunner`
 mutating methods). Before ANY **destructive** op (`discard`, `branch` delete) the SERVER
 **UNCONDITIONALLY** `snapshot()`s a reflog-recoverable rescue point (a `refs/nrs-rescue/<label>`
@@ -592,7 +593,7 @@ directly). The op returns a TYPED, CONDITIONAL `rescue` carrier — `{kind:'stas
 dirty-tree discard, `{kind:'branch', ref, name}` on a resolved-tip branch delete (absent when
 there is nothing to recover) — which drives the **one-click UNDO**: `POST /git/restore
 {rescue}` re-snapshots first (a restore is itself a mutation) then `git stash apply` /
-`git branch <name> <ref>` (non-force → 409 on an existing name), same `drive.write` +
+`git branch <name> <ref>` (non-force → 409 on an existing name), same `files.write` +
 uri-policy `write` floor, no `PendingInteraction`. The panel's rescue banner grows an **Undo**
 button beside Dismiss. Every successful write publishes the IN-APP `changeType:'badge'`
 event with the actor's **REAL** `(userId, projectId, agentId)` via `publishInAppGitBadge` (the
@@ -695,7 +696,7 @@ Lifecycle exports (`src/lifecycle.ts`):
 
 - `init`, `start`, `onBootstrapComplete`, `drain`, `stop`, `api`, `onCredentialChanged`, `health`, `onPrincipalRevoked`, `provisionProject` (`usecases/provisionProject.ts` — a NEW project's declared `seed:'auto'` sources, written complete through the same create path as the boot repair; see Declared sources), `deprovisionProject` (`usecases/deprovisionProject.ts` — on a PERMANENT project delete, ALL of the project's vector points leave the shared index in ONE bounded `deleteByFilter({ must: [{ field: 'projectId', equals: id }] })` — chunks + folder-ancestor points covered by the same keyword-index filter. MUST-HAVE: a failed delete throws, and so does a degraded boot where Qdrant is configured but the in-memory index is wired (a delete there would leave every real point in Qdrant); the host then stops the purge before any file is removed. It runs BEFORE the fs tree is removed, so resolving the brain infra cannot re-materialize the project dir).
 - `init` state exposes `services["package-source-roots"]` for kernel registration; its `listPackageSourceRoots` delegate is the same function as the direct API method, and its `subscribePackageSourceRoots(listener)` calls `listener(projectId)` after every committed source-config write of the app root (`SourceConfigMutation.onChanged` — fired outside the write lock, a no-op write never fires, a throwing listener is logged and never reaches the writer), so the host re-derives that project's flagged package roots at once.
-- `BrainCoreApi` — `getProjectServices`, `getProjectInfra`, `getFilesystem`, `upsertSourceConfig`, `listShellSourceRoots(projectId)` (every shell-capable source with its persisted permissions; feeds agent-core's shell uri-policy gate and the terminal's host-tab resolver; NOT access-filtered — consumers evaluate the policy against the caller's own `SessionContext`. Rows carry an explicit **`plane`**: `container` sources contribute their `containerRoot`, resolved by the canonical `resolveLocalRoot`; **host-plane** sources contribute a raw `hostRoot` and an intentionally EMPTY `containerRoot` — no container path exists for them, and the empty value is load-bearing, because the consumer's container-plane filter drops rootless entries so a host source can never leak into a container-plane lookup even if `plane` were ignored. The plane is derived from the connector KIND, never from the slug string — an ordinary local source may legitimately be named `host-notes`. Kinds that host no shell at all (brain vectors, webtop) contribute nothing), and `listSourceRuntimeSummaries(projectId, { userId, agentId, role?, grantedFeatures? })` (the READ sibling of `listShellSourceRoots`, feeding agent-core's `<runtime_stack>` source rendering — **all** connector kinds, **access-filtered** (host-plane rows carry `containerDir: null` — their root is a path in the OPERATOR's filesystem with no container equivalent, and the local-shaped derivation would otherwise print a container path that does not exist, baked into every agent's cached system prompt) via `canAccessScope` → `filesystem.observeScoped`/deny-by-default, each row carrying connector, `os_uri`/`container_dir`, the caller-effective uri-policy, `description`, and the cached index snapshot; reads persisted source-config JSON ONLY — no live walk / no vector count — so it is safe to call once per stream. Agent-core renders the stable structure in the cached `<runtime_stack>` prefix and the volatile counts + on/off in `<workspace_live>`. Disabled sources are INCLUDED, marked `enabledEffective:false`). `listPackageSourceRoots(projectId)` (enumerate every project-associated source as a runtime package-source candidate `{ slug, uriRoot, containerRoot, scope, recognizesPackages, enabled, kind }`; identity-free like `listShellSourceRoots`, ALL candidates returned so the host applies the floor — project-scope + flagged + enabled + local; the host's `projectPackages` consumes it to scan + hot-reload flagged source dirs alongside `_packages/`). Filesystem events reach the `/brain-core/events` SSE route and the discovered `filesystem` channel of the host `/api/events` hub through ONE authorization adapter: it takes the real session, authorizes EACH requested agent deny-by-default (a foreign agent yields zero events, never an existence-confirming error), and filters events by user/project/types and the authorized agent or source.
+- `BrainCoreApi` — `getProjectServices`, `getProjectInfra`, `getFilesystem`, `upsertSourceConfig`, `listShellSourceRoots(projectId)` (every shell-capable source with its persisted permissions; feeds agent-core's shell uri-policy gate and the terminal's host-tab resolver; NOT access-filtered — consumers evaluate the policy against the caller's own `SessionContext`. Rows carry an explicit **`plane`**: `container` sources contribute their `containerRoot`, resolved by the canonical `resolveLocalRoot`; **host-plane** sources contribute a raw `hostRoot` and an intentionally EMPTY `containerRoot` — no container path exists for them, and the empty value is load-bearing, because the consumer's container-plane filter drops rootless entries so a host source can never leak into a container-plane lookup even if `plane` were ignored. The plane is derived from the connector KIND, never from the slug string — an ordinary local source may legitimately be named `host-notes`. Kinds that host no shell at all (brain vectors, webtop) contribute nothing), and `listSourceRuntimeSummaries(projectId, { userId, agentId, role?, grantedFeatures? })` (the READ sibling of `listShellSourceRoots`, feeding agent-core's `<runtime_stack>` source rendering — **all** connector kinds, **access-filtered** (host-plane rows carry `containerDir: null` — their root is a path in the OPERATOR's filesystem with no container equivalent, and the local-shaped derivation would otherwise print a container path that does not exist, baked into every agent's cached system prompt) via `canAccessScope` → `files.readOthers`/deny-by-default, each row carrying connector, `os_uri`/`container_dir`, the caller-effective uri-policy, `description`, and the cached index snapshot; reads persisted source-config JSON ONLY — no live walk / no vector count — so it is safe to call once per stream. Agent-core renders the stable structure in the cached `<runtime_stack>` prefix and the volatile counts + on/off in `<workspace_live>`. Disabled sources are INCLUDED, marked `enabledEffective:false`). `listPackageSourceRoots(projectId)` (enumerate every project-associated source as a runtime package-source candidate `{ slug, uriRoot, containerRoot, scope, recognizesPackages, enabled, kind }`; identity-free like `listShellSourceRoots`, ALL candidates returned so the host applies the floor — project-scope + flagged + enabled + local; the host's `projectPackages` consumes it to scan + hot-reload flagged source dirs alongside `_packages/`). Filesystem events reach the `/brain-core/events` SSE route and the discovered `filesystem` channel of the host `/api/events` hub through ONE authorization adapter: it takes the real session, authorizes EACH requested agent deny-by-default (a foreign agent yields zero events, never an existence-confirming error), and filters events by user/project/types and the authorized agent or source.
 
 **Cross-package writes go through `FilesystemService` itself, and its permission check is
 the ONLY gate on that path.** `getProjectServices(projectId).filesystem` hands back the live
@@ -708,7 +709,7 @@ filesystem. Two consequences for anyone mirroring the request types into another
 would be a cycle, so that mirror is pinned instead by a compile-time guard against brain-core's
 shipped `.d.ts`): the mirrored type must expose neither
 `review` nor `allowEmpty` — both are INTERNAL-only governance escapes deliberately absent from
-every tool schema and route body — and the caller must gate on its own feature (`drive.write`)
+every tool schema and route body — and the caller must gate on its own feature (`files.write`)
 before it gets here, because `#checkPermission` answers "may this URI be written", not "may
 this caller write at all".
 
@@ -881,8 +882,8 @@ survive in two places on purpose — stored transcripts still hold 1 800+ of the
 rows, so the `filesystem-change` card's manifest `match.tools` and agent-core's
 `REVERTIBLE_TOOLS` keep naming them so that history renders and rewinds.
 
-Each tool declares its feature gate on itself (`x-neuralis.requires.features`): `fs_read`/`fs_list` → `drive.read`, `fs_write` → `drive.write`,
-`fs_search` → `drive.search`. This is the ONE source for the tool gate — the
+Each tool declares its feature gate on itself (`x-neuralis.requires.features`): `fs_read`/`fs_list` → `files.read`, `fs_write` → `files.write`,
+`fs_search` → `files.search`. This is the ONE source for the tool gate — the
 former manifest `policies[] kind:'access'` block was removed; only the `fs_*`
 timeout `safety` policy remains. The HTTP routes below carry the SAME features
 independently (route-layer `requireFeature`), so both the agent-tool path and
@@ -890,14 +891,14 @@ the direct-HTTP path are gated.
 
 Routes (`src/routes/*.ts`, exported `pattern` + `feature`):
 
-- `read` (POST, `drive.read`), `list` (POST, `drive.read`), `search` (POST, `drive.search` — body key `search_mode`, the same vocabulary as the `fs_search` tool; an unknown value or the legacy `mode` key is a hard 400, never a silent semantic fallthrough).
-- `write` (POST, `drive.write` — the ONE write route, every `fs_write` verb key; a copy-only call is guarded as `read` on the source), `approve` (POST, `drive.write`), `upload` (POST, `drive.write`).
-- `raw` (GET, `drive.read`), `events` (GET SSE, `drive.read` — a single-agent caller of the `subscribeFilesystemEventsImpl` authorization adapter, which re-authorizes the agentId deny-by-default), `health/*` (GET/POST, `drive.read` — but the `gc` sub-path is **POST-only** and escalates in-handler to **`drive.write`**, and the GET `hot-uris` sub-path (the write monitor) takes the same `drive.write` tier and then filters per uri, both declared via `export const escalations`; see the Vector health section).
+- `read` (POST, `files.read`), `list` (POST, `files.read`), `search` (POST, `files.search` — body key `search_mode`, the same vocabulary as the `fs_search` tool; an unknown value or the legacy `mode` key is a hard 400, never a silent semantic fallthrough).
+- `write` (POST, `files.write` — the ONE write route, every `fs_write` verb key; a copy-only call is guarded as `read` on the source), `approve` (POST, `files.write`), `upload` (POST, `files.write`).
+- `raw` (GET, `files.read`), `events` (GET SSE, `files.read` — a single-agent caller of the `subscribeFilesystemEventsImpl` authorization adapter, which re-authorizes the agentId deny-by-default), `health/*` (GET/POST, `files.read` — but the `gc` sub-path is **POST-only** and escalates in-handler to **`files.write`**, and the GET `hot-uris` sub-path (the write monitor) takes the same `files.write` tier and then filters per uri, both declared via `export const escalations`; see the Vector health section).
 
-  **The `raw` byte lane never asks a browser to RENDER what a member wrote.** Response headers come from one owner, `buildRawResponseHeaders` (`domain/mime.ts`), and the route builds none of its own. `drive.write` is a member default on the seeded `data` source, so anything the lane renders on the app origin runs with the READER's session — an SVG carrying `<script>` was a stored-XSS primitive while the route echoed the file's own mime with `content-disposition: inline`. Three classes, and the split preserves every capability: safe previews (image except SVG, video, audio, PDF, text, JSON) stay `inline`; the ACTIVE-DOCUMENT class (SVG, HTML, XHTML, XML and every `+xml` subtype) is served with its TRUE type and `content-disposition: attachment`, so the file downloads normally and simply never becomes a live document; everything else downloads too, **keeping its real type** — the protection comes from the disposition, so a `.docx` or a `.wasm` is not flattened to `application/octet-stream` (only an absent or unparseable type is). A non-inline response always carries the header even without a filename, and filenames ride as a sanitized ASCII form plus the RFC 5987 `filename*` form so non-ASCII names survive. The store side is closed with it: `upload` no longer persists the caller-supplied part `Content-Type` verbatim (`normalizeStoredMimeType` — extension first, declared value only for unknown extensions, magic-byte check on the raster formats). Defense in depth, not a substitute for either: the host adds `Content-Security-Policy: sandbox` to every `/api/packages/*` response, which forces any navigated document on the lane into an opaque origin.
-- `git/*` (`src/routes/git.ts` — the Git Control panel surface): **GET** (`drive.read`) `status` (whole-repo change-set + branch + `upstream`/`ahead`/`behind` when tracking exists) + `branch` (local branch list) + `diff` (per-file unified diff — `?path=&staged=` WT↔Index vs Index↔HEAD, `?commit=<sha>` commit↔first-parent, or `?base=&head=` explicit sha pair; modes mutually exclusive, shas whitelisted, untracked rendered fully-added via `--no-index`, per-path uri-policy gate in every mode) + `log` (`?maxCount=&skip=&ref=` — ONE page of the commit DAG for the graph; page ≤ 1999, `skip` ≤ 100 000 (past the window ⇒ `hasMore:false`), exact `hasMore` probe replaced `truncated` here; each entry carries `subject` + the full `body` (both server-capped) for the hover card; plus `outgoing?: string[]` not-pushed shas, absent without an upstream) + `commit` (`?sha=` — the commit's file list, first-parent two-tree form, root commit = all-adds vs the empty tree; names-only ⇒ root-gated) + `outgoing` (server-resolved merge-base(`@{u}`,`HEAD`)↔`HEAD` aggregate file list + sha pair; NO caller refs; local refs only, fail-soft without an upstream) + `show` (`?path=&rev=<sha|index>` — blob content at a rev for the diff expanders; per-path uri-policy gate, blob-only + 2 MB/binary guards, typed `ok:false` refusals instead of truncation) + `log-stats` (per-commit `+/-` totals for one log page, totals only, never a path) + `repos` (the in-source repo picker — and the only route that tells a caller whether a git plane exists at all: `rel:""` is the source root, any other `rel` is a nested checkout a root-gated read will not see). **The four root-gated summary reads — `status`/`branch`/`log`/`log-stats` — fail SOFT to an empty `ok:true` on a non-repo, a containment refusal or any git error, which is byte-identical to a clean repository; `commit`/`outgoing`/`show` answer the typed `{ok:false,'unavailable'}` dialect instead.** **POST** (additionally `drive.write` + uri-policy `write`) `stage`/`unstage` (whole-file OR `{hunk}`) + `discard` + `commit` + `branch` (create/delete) + `checkout` — HUMAN consent (the session, NOT the agent-approval guard), SERVER unconditional auto-snapshot before a destructive op (returns `rescue`), and an in-app badge with the actor's REAL identity on success. All per-source (`?source=` GET / body `source` POST), deny-by-default (non-accessible → 404), repo-relative paths only + host-path-scrubbed errors, size-capped (diff 2 MB — the human-panel memory bound; the 20 KB `boundToolResult` floor stays the model-facing invariant for the planned hosted git tools).
-- `policies/uri` (GET read = `drive.read`; POST patch escalates in-handler to **`drive.policy`** — a feature replacing the former owner/admin role-name check; not granted below the admin tier — owner via `'*'`, admin via its enumerated default grants — and grantable per-role; declared via `export const escalations`). The brain-local `hasRouteFeature` is now a thin wrapper over the shared `hasFeature` (one-predicate invariant). In-handler escalation features (`drive.mount`, `drive.mount.privileged`, `drive.sync`, `filesystem.observeScoped`/`modifyScoped`, `drive.policy`) gate path/scope-dependent operations on top of the route's declared baseline — the same two-tier pattern machine-core uses; they are LIVE, not dead. **`drive.mount.privileged`** (not granted below the admin tier — owner via `'*'`, admin via its enumerated default grants — and grantable per-role) gates SEEing in `discoverable`, ADDing (create), EDITING (PATCH — permission widening on an already-attached protected-rooted source), and — since warded-wren — BROWSING (`sources/browse`) a source rooted in a high-blast-radius zone (the app zone, the Neuralis tree, or the whole host `/`); the add/edit arm is kind-agnostic on the container plane (any non-host-plane kind whose config carries a string `root`); enforced by canonical path containment in `sources.ts` (browse matches IS-or-UNDER only and omits protected children from the listing, and it requires the feature for the filesystem ROOT and for ANY path while the runtime stack is unavailable — an empty protected-root table must never read as *unrestricted*) — see `src/routes/README.md`. **`drive.mount.host`** (not granted below the admin tier — owner via `'*'`, admin via its enumerated default grants — and grantable per-role) gates the **host plane** — any source whose connector kind resolves OUTSIDE the container (`host`, `host-*`). It is required **together with** `drive.mount.privileged`, and both are checked independently: on the host plane **every root is privileged by construction**, so `/home/me/notes` is gated exactly like `/` — there is deliberately no root-sensitivity, because a sub-directory carve-out would re-open the escalation through a subdirectory. The check runs BEFORE the container-plane protected-root logic and needs no runtime-stack information, so it holds even when the stack is unavailable (fail closed). **Editing** a host-plane source requires the same pair as attaching one: `PATCH` cannot change `connection`, but it CAN widen `read` → `write`, so a plain-`drive.mount` manager must not be able to escalate an existing host source in place. Beyond these features, the operator-owned host-broker ceiling clamps what a granted caller can actually reach (see the agent-core README's host-access section) — the ceiling is the floor; the features are the audit trail. **`packages.author`** gates the package-authoring *affordances* — the Packages-panel scaffold launcher and the install/build actions — granted to `admin` and `manager` via `defaultRoleGrants` (owner passes on the wildcard). It does NOT gate the authoring SKILL: `skills/create-package` is ungated on purpose, so a caller who cannot yet write or install can still read the contract and learn exactly which capability they are missing instead of failing blind. The downstream gates are unchanged — scaffolding into `packages://` still needs `drive.write`, and install/build still need `packages.author`.
-- `sources/*` (CRUD + `sync` (202 + queue job snapshot) + `cancel` (per-source `{source}` or all-visible; drive.sync) + `reindex` (202) + `reset` + `sync-status` (GET job snapshots, drive.sync) + `browse` (**`drive.mount`**; the filesystem root and any protected host zone additionally need `drive.mount.privileged`) + `preflight` (POST-only create validation/authorization, no write) + `kinds` + `kinds/:kind/schema` + `enabled` (light toggle, `'auto'` machine-only) + `discoverable` (**`drive.mount`** — well-known unattached source roots from the runtime stack, e.g. the "Neuralis Tree" `neuralis://` mount when `pnpm neuralis:mount add … --neuralis` is configured), mixed `drive.*`). A suggestion may pre-fill **`suggestedSync`** (`include` + `trigger`, both riding the contract — the add form no longer hard-codes `'manual'`) and **`suggestedPolicies`** (uri-policy path rules, `$source`-tokenised so they survive a slug rename). The two are not interchangeable: `include` narrows what is **indexed**, `suggestedPolicies` narrows what can be **read**. The `--neuralis` overlay therefore offers TWO proposals, narrowest first — `neuralis-skills://` rooted at `<root>/skills` (root = boundary, `existsSync`-guarded so a `skills`-less overlay advertises nothing) and `neuralis://` over the whole folder, which pre-fills `include: ['skills/**']` plus a `.env*` read-deny because that root holds `.env`. `POST sources/sync` classifies its two pre-flight refusals rather than redacting them: **404** (plain shape) when the slug does not resolve for the caller, **400** when it resolves but carries no `sync` block. **PATCH replaces `permissions` wholesale — it never merges.** A body carrying only `permissions.default` answers 200 and drops every `paths[]` rule the source held; only `floor:true` rules are protected (409), so a 200 is not evidence the rest survived. Every caller — skill, UI, test — must round-trip the source's current `permissions` object. **A connector-declared floor self-heals on ANY scheme; the manifest-baseline union self-heals on `data`/`packages` only; nothing else self-heals at all.** The two halves run on different gates. `reconcileImmutablePolicyFloors` runs on EVERY boot, past the version stamp, for every source whose connector declares `floor:true` rows — so a machine/webtop source restores its floors too, and a floor row added by a later package version reaches EXISTING configs without a version bump. The version-gated half is the baseline UNION, and a PATCH no longer re-arms it: `updateSourceConfig` rebuilds the record from an explicit FIELD ALLOWLIST (every sibling writer spreads `existing`), and `baselineRepairVersion` was missing from that list, so any PATCH — a no-op included — silently un-stamped the config and the next boot's `repairSourceBaselines` re-unioned the manifest baselines. Since `mergeBaselines`'s `paths` semantics are UNION, that RESURRECTED a non-floor rule a `removeRule` had deliberately taken out. The allowlist now preserves the stamp. On every other scheme there is no baseline union to re-run. Hand-added rules never come back on any scheme.
+  **The `raw` byte lane never asks a browser to RENDER what a member wrote.** Response headers come from one owner, `buildRawResponseHeaders` (`domain/mime.ts`), and the route builds none of its own. `files.write` is a member default on the seeded `data` source, so anything the lane renders on the app origin runs with the READER's session — an SVG carrying `<script>` was a stored-XSS primitive while the route echoed the file's own mime with `content-disposition: inline`. Three classes, and the split preserves every capability: safe previews (image except SVG, video, audio, PDF, text, JSON) stay `inline`; the ACTIVE-DOCUMENT class (SVG, HTML, XHTML, XML and every `+xml` subtype) is served with its TRUE type and `content-disposition: attachment`, so the file downloads normally and simply never becomes a live document; everything else downloads too, **keeping its real type** — the protection comes from the disposition, so a `.docx` or a `.wasm` is not flattened to `application/octet-stream` (only an absent or unparseable type is). A non-inline response always carries the header even without a filename, and filenames ride as a sanitized ASCII form plus the RFC 5987 `filename*` form so non-ASCII names survive. The store side is closed with it: `upload` no longer persists the caller-supplied part `Content-Type` verbatim (`normalizeStoredMimeType` — extension first, declared value only for unknown extensions, magic-byte check on the raster formats). Defense in depth, not a substitute for either: the host adds `Content-Security-Policy: sandbox` to every `/api/packages/*` response, which forces any navigated document on the lane into an opaque origin.
+- `git/*` (`src/routes/git.ts` — the Git Control panel surface): **GET** (`files.read`) `status` (whole-repo change-set + branch + `upstream`/`ahead`/`behind` when tracking exists) + `branch` (local branch list) + `diff` (per-file unified diff — `?path=&staged=` WT↔Index vs Index↔HEAD, `?commit=<sha>` commit↔first-parent, or `?base=&head=` explicit sha pair; modes mutually exclusive, shas whitelisted, untracked rendered fully-added via `--no-index`, per-path uri-policy gate in every mode) + `log` (`?maxCount=&skip=&ref=` — ONE page of the commit DAG for the graph; page ≤ 1999, `skip` ≤ 100 000 (past the window ⇒ `hasMore:false`), exact `hasMore` probe replaced `truncated` here; each entry carries `subject` + the full `body` (both server-capped) for the hover card; plus `outgoing?: string[]` not-pushed shas, absent without an upstream) + `commit` (`?sha=` — the commit's file list, first-parent two-tree form, root commit = all-adds vs the empty tree; names-only ⇒ root-gated) + `outgoing` (server-resolved merge-base(`@{u}`,`HEAD`)↔`HEAD` aggregate file list + sha pair; NO caller refs; local refs only, fail-soft without an upstream) + `show` (`?path=&rev=<sha|index>` — blob content at a rev for the diff expanders; per-path uri-policy gate, blob-only + 2 MB/binary guards, typed `ok:false` refusals instead of truncation) + `log-stats` (per-commit `+/-` totals for one log page, totals only, never a path) + `repos` (the in-source repo picker — and the only route that tells a caller whether a git plane exists at all: `rel:""` is the source root, any other `rel` is a nested checkout a root-gated read will not see). **The four root-gated summary reads — `status`/`branch`/`log`/`log-stats` — fail SOFT to an empty `ok:true` on a non-repo, a containment refusal or any git error, which is byte-identical to a clean repository; `commit`/`outgoing`/`show` answer the typed `{ok:false,'unavailable'}` dialect instead.** **POST** (additionally `files.write` + uri-policy `write`) `stage`/`unstage` (whole-file OR `{hunk}`) + `discard` + `commit` + `branch` (create/delete) + `checkout` — HUMAN consent (the session, NOT the agent-approval guard), SERVER unconditional auto-snapshot before a destructive op (returns `rescue`), and an in-app badge with the actor's REAL identity on success. All per-source (`?source=` GET / body `source` POST), deny-by-default (non-accessible → 404), repo-relative paths only + host-path-scrubbed errors, size-capped (diff 2 MB — the human-panel memory bound; the 20 KB `boundToolResult` floor stays the model-facing invariant for the planned hosted git tools).
+- `policies/uri` (GET read = `files.read`; POST patch escalates in-handler to **`sources.policy`** — a feature replacing the former owner/admin role-name check; not granted below the admin tier — owner via `'*'`, admin via its enumerated default grants — and grantable per-role; declared via `export const escalations`). The brain-local `hasRouteFeature` is now a thin wrapper over the shared `hasFeature` (one-predicate invariant). In-handler escalation features (`sources.mount`, `sources.privileged`, `sources.sync`, `files.readOthers`/`files.writeOthers`, `sources.policy`) gate path/scope-dependent operations on top of the route's declared baseline — the same two-tier pattern machine-core uses; they are LIVE, not dead. **`sources.privileged`** (not granted below the admin tier — owner via `'*'`, admin via its enumerated default grants — and grantable per-role) gates SEEing in `discoverable`, ADDing (create), EDITING (PATCH — permission widening on an already-attached protected-rooted source), and — since warded-wren — BROWSING (`sources/browse`) a source rooted in a high-blast-radius zone (the app zone, the Neuralis tree, or the whole host `/`); the add/edit arm is kind-agnostic on the container plane (any non-host-plane kind whose config carries a string `root`); enforced by canonical path containment in `sources.ts` (browse matches IS-or-UNDER only and omits protected children from the listing, and it requires the feature for the filesystem ROOT and for ANY path while the runtime stack is unavailable — an empty protected-root table must never read as *unrestricted*) — see `src/routes/README.md`. A source on the **host plane** — any connector kind that resolves OUTSIDE the container (`host`, `host-*`), i.e. a paired device — is attached or edited only by **that device's owner holding `device.own`**, answered by agent-core's device gate; no role feature opens it for anyone else, at any root, and the check runs BEFORE the container-plane protected-root logic with no runtime-stack precondition (fail closed). **Editing** one needs the same: `PATCH` cannot change `connection`, but it CAN widen `read` → `write`, so a plain-`sources.mount` manager must not be able to escalate an existing host source in place. Beyond that, the device's own allowlist (`neuralis device grant`) bounds what the owner's source can actually reach (see the agent-core README's host-access section). **`packages.author`** gates the package-authoring *affordances* — the Packages-panel scaffold launcher and the install/build actions — granted to `admin` and `manager` via `defaultRoleGrants` (owner passes on the wildcard). It does NOT gate the authoring SKILL: `skills/create-package` is ungated on purpose, so a caller who cannot yet write or install can still read the contract and learn exactly which capability they are missing instead of failing blind. The downstream gates are unchanged — scaffolding into `packages://` still needs `files.write`, and install/build still need `packages.author`.
+- `sources/*` (CRUD + `sync` (202 + queue job snapshot) + `cancel` (per-source `{source}` or all-visible; sources.sync) + `reindex` (202) + `reset` + `sync-status` (GET job snapshots, sources.sync) + `browse` (**`sources.mount`**; the filesystem root and any protected host zone additionally need `sources.privileged`) + `preflight` (POST-only create validation/authorization, no write) + `kinds` + `kinds/:kind/schema` + `enabled` (light toggle, `'auto'` machine-only) + `discoverable` (**`sources.mount`** — well-known unattached source roots from the runtime stack, e.g. the "Neuralis Tree" `neuralis://` mount when `pnpm neuralis:mount add … --neuralis` is configured), mixed `drive.*`). A suggestion may pre-fill **`suggestedSync`** (`include` + `trigger`, both riding the contract — the add form no longer hard-codes `'manual'`) and **`suggestedPolicies`** (uri-policy path rules, `$source`-tokenised so they survive a slug rename). The two are not interchangeable: `include` narrows what is **indexed**, `suggestedPolicies` narrows what can be **read**. The `--neuralis` overlay therefore offers TWO proposals, narrowest first — `neuralis-skills://` rooted at `<root>/skills` (root = boundary, `existsSync`-guarded so a `skills`-less overlay advertises nothing) and `neuralis://` over the whole folder, which pre-fills `include: ['skills/**']` plus a `.env*` read-deny because that root holds `.env`. `POST sources/sync` classifies its two pre-flight refusals rather than redacting them: **404** (plain shape) when the slug does not resolve for the caller, **400** when it resolves but carries no `sync` block. **PATCH replaces `permissions` wholesale — it never merges.** A body carrying only `permissions.default` answers 200 and drops every `paths[]` rule the source held; only `floor:true` rules are protected (409), so a 200 is not evidence the rest survived. Every caller — skill, UI, test — must round-trip the source's current `permissions` object. **A connector-declared floor self-heals on ANY scheme; the manifest-baseline union self-heals on `data`/`packages` only; nothing else self-heals at all.** The two halves run on different gates. `reconcileImmutablePolicyFloors` runs on EVERY boot, past the version stamp, for every source whose connector declares `floor:true` rows — so a machine/webtop source restores its floors too, and a floor row added by a later package version reaches EXISTING configs without a version bump. The version-gated half is the baseline UNION, and a PATCH no longer re-arms it: `updateSourceConfig` rebuilds the record from an explicit FIELD ALLOWLIST (every sibling writer spreads `existing`), and `baselineRepairVersion` was missing from that list, so any PATCH — a no-op included — silently un-stamped the config and the next boot's `repairSourceBaselines` re-unioned the manifest baselines. Since `mergeBaselines`'s `paths` semantics are UNION, that RESURRECTED a non-floor rule a `removeRule` had deliberately taken out. The allowlist now preserves the stamp. On every other scheme there is no baseline union to re-run. Hand-added rules never come back on any scheme.
 
 **A non-project-scoped source never keeps the `default` you send — and the two non-project kinds seed DIFFERENTLY.** `applyScopeSeedPermissions` forces `default: {read:false,write:false,exec:false}` and `byRole: {owner:{read:true}, admin:{read:true}}` for BOTH `user` and `agent` scope, but the principal grant branches on the kind:
 
@@ -964,9 +965,9 @@ embed call, because no embed call uses an LLM key.
 
 The per-category contribution folders are the agent-facing knowledge surface for brain-core:
 
-- `rules/brain-rules.md` and `docs/drive-overview.md` explain URI identity, connector-first read/list behavior, search freshness, the **fs write policy** (modify-don't-recreate, read-before-modify, `revert` as 1-level undo — moved here from agent-core's `tool-use` so the filesystem owner owns writes), source scope, feature gates, recovery, and vector health.
+- `rules/brain-rules.md` (always on) and `instructions/brain-model.md` (on demand) explain URI identity, connector-first read/list behavior, search freshness, the **fs write policy** (modify-don't-recreate, read-before-modify, `revert` as 1-level undo — moved here from agent-core's `tool-use` so the filesystem owner owns writes), source scope and the independent gates; each `fs_*` tool description carries its own mechanics. brain-core ships no `docs/` and no MCP `resources[]`.
 - brain-core ships **nine** skill bundles under `skills/`. `skills/brain-start`, `sync`, and `organize` are operational workflows for using the filesystem safely; `manage-files` (bulk/route-level file ops when the `fs_*` tools are insufficient or an approval flow is involved), `manage-sources` (source survey + index-health diagnostics alongside its CRUD/sync lifecycle), `manage-uri-policy` (inspect/patch per-source read/write/exec path policy) and `git` (drive a git-backed source through the governed `/git/*` routes) each wrap a slice of the HTTP surface — see the LLM-callable skills table below.
-- `skills/connect-business-data` is the governance-first orchestration layer for organisation-wide and single-user external data. It establishes ownership, approved location, audience/scope, sensitivity/retention, credential scope, copy permission and provenance before routing to a configured source, connector or reusable package. Corpus content remains source-backed; identity and memory never become a shadow dataset, while skills/tools/workflows operate on governed source URIs. Gated `drive.read` (authoring still needs its own write/install capability).
+- `skills/connect-business-data` is the governance-first orchestration layer for organisation-wide and single-user external data. It establishes ownership, approved location, audience/scope, sensitivity/retention, credential scope, copy permission and provenance before routing to a configured source, connector or reusable package. Corpus content remains source-backed; identity and memory never become a shadow dataset, while skills/tools/workflows operate on governed source URIs. Gated `files.read` (authoring still needs its own write/install capability).
 - `skills/create-package` is the SINGLE package-authoring skill — a router `SKILL.md` over `references/` (context files, manifest + discovery, tool schemas, runtime + build, app surfaces, connectors + uriPolicies, config + credentials, team + workflows, test + ship) plus two `scripts/` (a static pre-flight and a runtime load check). ONE dispatch surface, so an agent that finds the skill at all reaches the right chapter. It is **ungated** — every caller can read the contract and learn which capability they are missing; the write / install / build capabilities still gate the actual work.
 - brain-core ships **no** `agents/`. Its four package-authoring subagents (`planner-agent`, `reviewer-agent`, `scaffolder-agent`, `brain-search-agent`) were retired: they duplicated the platform operating floor they were already injected with, and their `allowed-tools` allowlists hid every non-`fs_*` tool from them — no `execute`, no web, no MCP, no package tool. Three of the four were additionally gated on `packages.author`, which member and viewer do not hold. The universal roles now live in agent-core (`agents/*.md`: explore, research, planner, execute, validate, operate, general) and the package contract these encoded is in `skills/create-package`, which any of those roles can activate.
 
@@ -988,9 +989,9 @@ There is intentionally no README inside the contribution folders; this section i
 ## Security & scope
 
 - Every route helper (`src/routes/helpers.ts`) extracts `(userId, projectId, agentId, role, grantedFeatures, agentAccess, agentOwnership)` from the canonical `req.session` (`SessionContext`) and rejects sentinel identities. `projectId`/`userId` come straight from the session; `agentId` resolves `body ?? query ?? req.session.agentId`, so a session-ticket caller (skill-script curl) inherits the stream's agent without passing `AGENT_ID` — `ensureAccess` only 400s when no agent is present anywhere. A body/query `projectId` that disagrees with the session is rejected (403). `getServices(state, projectId)` resolves project-scoped infra; sentinel `__system__` ids never reach a real Qdrant collection.
-- Source scope evaluation uses `canAccessScope` from `@neuralis/package-system/contracts`. Project-scoped sources are visible to every project member; user-scoped sources require ownership or the `filesystem.observeScoped` / `filesystem.modifyScoped` feature. The grant alone decides — `canAccessScope` carries no role-name conjunct, so a custom role explicitly granted the feature observes exactly what a wildcard holder does. Default grants: `filesystem.observeScoped` AND `filesystem.modifyScoped` are both enumerated for `admin`; `owner` reaches them through the `'*'` wildcard; `manager`/`member`/`viewer` hold neither and reach a foreign scope only through an explicit grant. Since `canAccessScope` lost its role-name conjunct, these grants are what carry the decision — they are not inert. `allowedScopes` declared on a connector kind rejects mismatched scope at create time. Every route-level source-config read (`BridgeService.getSourceConfig` / `listSourceConfigs`) MUST pass the caller's access context (`toScopeAccessCtx(ctx)` from `routes/helpers.ts`) — omitting it downgrades the caller to a feature-less `member` and hides user/agent-scoped sources from their own owner (the "Source not found on edit" regression). The `FilesystemService` accessible-sources cache is keyed on the full access context (user, project, agent, role, grantedFeatures), never on `userId:projectId` alone — a narrower key lets one agent's set poison another agent's view for the TTL window.
+- Source scope evaluation uses `canAccessScope` from `@neuralis/package-system/contracts`. Project-scoped sources are visible to every project member; user-scoped sources require ownership or the `files.readOthers` / `files.writeOthers` feature. The grant alone decides — `canAccessScope` carries no role-name conjunct, so a custom role explicitly granted the feature observes exactly what a wildcard holder does. Default grants: `files.readOthers` AND `files.writeOthers` are both enumerated for `admin`; `owner` reaches them through the `'*'` wildcard; `manager`/`member`/`viewer` hold neither and reach a foreign scope only through an explicit grant. Since `canAccessScope` lost its role-name conjunct, these grants are what carry the decision — they are not inert. `allowedScopes` declared on a connector kind rejects mismatched scope at create time. Every route-level source-config read (`BridgeService.getSourceConfig` / `listSourceConfigs`) MUST pass the caller's access context (`toScopeAccessCtx(ctx)` from `routes/helpers.ts`) — omitting it downgrades the caller to a feature-less `member` and hides user/agent-scoped sources from their own owner (the "Source not found on edit" regression). The `FilesystemService` accessible-sources cache is keyed on the full access context (user, project, agent, role, grantedFeatures), never on `userId:projectId` alone — a narrower key lets one agent's set poison another agent's view for the TTL window.
 - A delete asks through the GUARD, not through a hand-written gate: `fs_write` declares `x-neuralis.askOnKeys: ["delete"]`, so the presence of that root key makes `balanced` open the approval while an edit stays quiet, and `auto` runs neither. Approval replays the original `toolUseId` and runs the mutation; denial leaves connector and index state untouched. The old tool-side consent (`maybeRequestDeleteApproval`) is gone — a second approval gate outside `evaluateGuard` is exactly what `auto` could not short-circuit.
-- **Pending-resolution security floor (2026-07-17).** Every pending-change verb (list / approve / revert / discard) resolves its vector target with an exact tenant-scoped `(projectId, id)` lookup — never a collection-global `retrieve(id)` — so a same-id point in another project is invisible: the previously tenant-blind lookups are hardened and the bounded uri-echo disclosure (a foreign tenant's point donating its uri to a discard/revert response) is closed. Chunk deletes/relocations are project-scoped the same way. The canonical check order on every mutating verb: session identity → `drive.write` (in-handler, before any lookup) → projectId tenant boundary → per-record owner (`canAccessScope` + `recordOwnerScope`) → source scope + uri-policy on the RESOLVED uri(s) (including a move destination and a move-revert's baseline uri; id-only modifies are gated too) → only then side effects. Cross-user resolution widens ONLY for a `filesystem.modifyScoped` HOLDER — the grant decides, not the role name (`canAccessScope` carries no role-name conjunct) — and preserves the record author's provenance; approving a delete tombstone deletes the point + chunks instead of resurrecting an active ghost. The owner floor also precedes the idempotent already-terminal early-return on discard/dismiss — a foreign caller probing a terminal record id gets `FORBIDDEN` (403) with no uri echo; terminal state is no oracle. The route maps every single-record resolution verb (revert / discard / dismiss) through ONE status mapping: `FORBIDDEN` → 403, `NOT_FOUND` → 404, retryable → 503, else 409.
+- **Pending-resolution security floor (2026-07-17).** Every pending-change verb (list / approve / revert / discard) resolves its vector target with an exact tenant-scoped `(projectId, id)` lookup — never a collection-global `retrieve(id)` — so a same-id point in another project is invisible: the previously tenant-blind lookups are hardened and the bounded uri-echo disclosure (a foreign tenant's point donating its uri to a discard/revert response) is closed. Chunk deletes/relocations are project-scoped the same way. The canonical check order on every mutating verb: session identity → `files.write` (in-handler, before any lookup) → projectId tenant boundary → per-record owner (`canAccessScope` + `recordOwnerScope`) → source scope + uri-policy on the RESOLVED uri(s) (including a move destination and a move-revert's baseline uri; id-only modifies are gated too) → only then side effects. Cross-user resolution widens ONLY for a `files.writeOthers` HOLDER — the grant decides, not the role name (`canAccessScope` carries no role-name conjunct) — and preserves the record author's provenance; approving a delete tombstone deletes the point + chunks instead of resurrecting an active ghost. The owner floor also precedes the idempotent already-terminal early-return on discard/dismiss — a foreign caller probing a terminal record id gets `FORBIDDEN` (403) with no uri echo; terminal state is no oracle. The route maps every single-record resolution verb (revert / discard / dismiss) through ONE status mapping: `FORBIDDEN` → 403, `NOT_FOUND` → 404, retryable → 503, else 409.
 - `LocalDiskConnector` blocks symlink traversal, `..` escape, and explicit access to the platform app zone (`~/.neuralis/app`) or credential files.
 - The brain source is per-agent inside the same project — `searchFiles` isolates brain rows by `agentId` unless `include_siblings` is set: an explicit `brain://` scope gets the vector pre-filter, an UNSCOPED (no `folder_uri`) search drops foreign brain rows per-node via `isVisibleSearchNode` while non-brain rows stay project-shared (the old global pre-filter starved cross-source search); cross-agent observation requires the corresponding feature.
 
@@ -1026,11 +1027,11 @@ fixes a wrong guess. Before this it fell into the catch-all 500, where the
 dispatcher redacts the message away.
 
 A source the caller cannot SEE — another user's or agent's, without
-`filesystem.observeScoped` — answers exactly like an absent one, on every plane:
+`files.readOthers` — answers exactly like an absent one, on every plane:
 the same 404 body (its slug never in `availableSources`; a disabled hidden source
 never answers `source_disabled`, which named its owner), the same 403 at the uri
 guard. (Creating a source under a taken slug is still refused — the per-project
-slug namespace needs that, and only a `drive.mount` holder reaches it.) A source the caller CAN see keeps its real
+slug namespace needs that, and only a `sources.mount` holder reaches it.) A source the caller CAN see keeps its real
 answers: `403 uri_policy_denied` for a denied path, `409 source_disabled` when it
 is off — never the 404 and its suggestion list.
 
@@ -1122,7 +1123,7 @@ Review uses a fresh `POST /pending` `{action:"preview",id}` receipt, separating
 
 ### Source delete + vector purge
 
-`POST /sources/purge` cleans cached index data without deleting the source or connector files. Body: `{source,selector:{kind:"source"}|{kind:"file"|"folder",uri},mode:"estimate"|"apply",obsoleteOnly?:boolean}`. Canonical selectors stay within the source; both drive.mount and drive.sync plus source-management and per-path READ gates apply. `obsoleteOnly:true` removes only current pattern/media exclusions; false/omitted explicitly clears selected eligible cached data too, while retaining recovery payloads. Estimate returns counts without provider work; confirm before apply. Unknown records remain unresolved. The projected inventory reuses caller READ configuration until its revision changes; selected points recheck fresh READ and source-management authority before hydration or mutation.
+`POST /sources/purge` cleans cached index data without deleting the source or connector files. Body: `{source,selector:{kind:"source"}|{kind:"file"|"folder",uri},mode:"estimate"|"apply",obsoleteOnly?:boolean}`. Canonical selectors stay within the source; both sources.mount and sources.sync plus source-management and per-path READ gates apply. `obsoleteOnly:true` removes only current pattern/media exclusions; false/omitted explicitly clears selected eligible cached data too, while retaining recovery payloads. Estimate returns counts without provider work; confirm before apply. Unknown records remain unresolved. The projected inventory reuses caller READ configuration until its revision changes; selected points recheck fresh READ and source-management authority before hydration or mutation.
 
 `DELETE /sources/:slug` always removes the source-config JSON and the
 in-memory connector binding. **The host folder is never touched** — the
@@ -1172,16 +1173,16 @@ collection walk:
   that walks every point: orphan-chunk + duplicate-document detection.
 
 The GC actions — **`POST /health/gc` only, and gated one tier above the rest of
-the route.** The module feature is `drive.read`, which every role holds down to
+the route.** The module feature is `files.read`, which every role holds down to
 `viewer`, and that is right for the two read arms above; `gc` and
 `repair-orphans` are mutations whose `dryRun` defaults to **false**, so the
-sub-path escalates in-handler to **`drive.write`** and answers a caller without
-it `403 Missing feature: drive.write (vector health repair)`. `deduplicate` is
+sub-path escalates in-handler to **`files.write`** and answers a caller without
+it `403 Missing feature: files.write (vector health repair)`. `deduplicate` is
 read-only but rides the same gate — its rows enumerate other agents' `data://`
 paths. `GET /health/gc` answers **405**, so a link or a prefetch can never start
 a deletion; it declares `Allow: POST` (the host catch-all forwards route headers
 only on content-type-bearing responses, so it is not on the wire yet). The arm is
-fenced, not removed: a `drive.write` holder (manager tier and up) runs every
+fenced, not removed: a `files.write` holder (manager tier and up) runs every
 action exactly as before, and the Vector Health panel already posts.
 `action:"repair-pending"` (dry-run supported in the panel) works on the CALLER's own
 visible pending records, never the project scope: it counts orphaned and
@@ -1247,7 +1248,7 @@ and `points` (everything written, chunks included). It is bounded to
 `vectorWriteMonitorMaxUris` uris per project (least recently written dropped
 first). A uri reaching `vectorWriteHotUriThreshold` writes in the hour logs ONE
 server-side `vector.write.hot-uri` warn per hour. `GET /health/hot-uris` lists the
-top `vectorWriteHotUriTopN` for the caller: it takes the same `drive.write` tier as
+top `vectorWriteHotUriTopN` for the caller: it takes the same `files.write` tier as
 `gc` (the list names files across the project's users and agents) and is then
 filtered per uri exactly like a file listing — the caller's source scope, the
 uri's READ policy, and agent isolation for `brain://` — before it is ranked and
@@ -1511,7 +1512,7 @@ The package declares the optional singleton `package-source-roots` service, dele
 - `commitWrite` (`usecases/write/commit.ts`) orders the slow phases so a write pays the least it can, and **every step of that order is an invariant** — the full rule, with its degrade matrix, lives in `src/usecases/README.md` and is stated there alone.
 - `OllamaEmbedder` now sends `keep_alive: '10m'` on every `/api/embed` request (configurable via `OllamaEmbedderConfig.keepAlive`; pass `0` to defer to the upstream default). Mirrors the LLM-stream keep-alive contract — keeps the embedding model resident on the GPU between fs_* calls and avoids the 1–2 s cold-start when the model gets paged out.
 - Host integration: the runtime UI module `app/host.tsx` (`neuralis.app.module`, built by `pnpm build:ui`) exports `installFilesystemHostComponents`, which registers the Files widget, the `filesystem.change` card and the `workspace.provider:@neuralis/brain-core` fill (`<FilesystemPackageHost port>` around the workspace tree). That install entry also mounts `<WorkspaceHostPortProvider port={port}>` once around the widget so the additive `SkillLauncher` launchers throughout the filesystem UI resolve the port from context — without it they render `null` silently, which the host's `hostPortProviderMount.test.ts` now fails on.
-- Filesystem-UI `SkillLauncher` launchers (additive composer-prefill affordances; visibility DERIVED from the host's per-caller skill catalog, never a hand-typed feature list): `Toolbar` → `sync` + `manage-files`; `SourcesPanel` header → `manage-sources`, per-source Permissions header → `manage-uri-policy` (URI / path-permission edit; `drive.policy`); `FileTree` empty-state → `manage-files`; `GitControlPanel` header → `git`; `PendingChangesPanel` → `manage-files`; `VectorHealthPanel` → `manage-sources`; `PackagesPanel` header → `create-package` (the one launcher that narrows further with `alsoRequires={["packages.author"]}` even though the skill is ungated — the button scaffolds into `packages://`, which the default `member` role cannot write). Full per-placement coverage note lives in `app/filesystem/ui/README.md`.
+- Filesystem-UI `SkillLauncher` launchers (additive composer-prefill affordances; visibility DERIVED from the host's per-caller skill catalog, never a hand-typed feature list): `Toolbar` → `sync` + `manage-files`; `SourcesPanel` header → `manage-sources`, per-source Permissions header → `manage-uri-policy` (URI / path-permission edit; `sources.policy`); `FileTree` empty-state → `manage-files`; `GitControlPanel` header → `git`; `PendingChangesPanel` → `manage-files`; `VectorHealthPanel` → `manage-sources`; `PackagesPanel` header → `create-package` (the one launcher that narrows further with `alsoRequires={["packages.author"]}` even though the skill is ungated — the button scaffolds into `packages://`, which the default `member` role cannot write). Full per-placement coverage note lives in `app/filesystem/ui/README.md`.
 
 ## LLM-callable skills
 
@@ -1522,9 +1523,9 @@ the `execute action="skill"` + `execute action="shell"` pipeline:
 
 | Bundle | Surface | Scripts |
 |---|---|---|
-| `manage-sources` | `/sources/*` CRUD + sync / sync-status / cancel / reset / reindex / enabled lifecycle, scoped index purge, kind catalog, browse + discoverable roots (both `drive.mount`, not the skill's `drive.read` floor) | 17 |
-| `manage-files` | `/list`, `/search`, `/read`, `/raw`, `/create`, `/modify`, `/mkdir`, `/copy`, `/upload`, `/approve`, `/pending` (bulk; `fs_*` tools remain primary for one-offs). `/create` and `/upload` both use the write engine and `drive.write`; agent-origin uploads are journaled as pending review, while interactive human uploads land committed | 11 |
-| `manage-uri-policy` | `/policies/uri/*` — read manifests baselines, read effective merged policy, patch path rules. Reads are the route's `drive.read` module feature (every built-in role holds it); the patch escalates in-handler to `drive.policy` — a feature check, not a role-name check. Immutable `floor:true` rules (trusted-manifest-only) can't be created or removed here — the route answers `409 immutable_policy_floor`. | 3 |
+| `manage-sources` | `/sources/*` CRUD + sync / sync-status / cancel / reset / reindex / enabled lifecycle, scoped index purge, kind catalog, browse + discoverable roots (both `sources.mount`, not the skill's `files.read` floor) | 17 |
+| `manage-files` | `/list`, `/search`, `/read`, `/raw`, `/create`, `/modify`, `/mkdir`, `/copy`, `/upload`, `/approve`, `/pending` (bulk; `fs_*` tools remain primary for one-offs). `/create` and `/upload` both use the write engine and `files.write`; agent-origin uploads are journaled as pending review, while interactive human uploads land committed | 11 |
+| `manage-uri-policy` | `/policies/uri/*` — read manifests baselines, read effective merged policy, patch path rules. Reads are the route's `files.read` module feature (every built-in role holds it); the patch escalates in-handler to `sources.policy` — a feature check, not a role-name check. Immutable `floor:true` rules (trusted-manifest-only) can't be created or removed here — the route answers `409 immutable_policy_floor`. | 3 |
 | `git` | `/git/*` — the same routes the Git Control panel drives. Reads: status / branch / diff / log / log-stats / commit / outgoing / show / repos. Writes: stage / unstage / discard, commit, branch / checkout, `restore`, and fetch / pull / push (uri-policy `exec` + connected remote). its routes taught as `neuralis request <METHOD> @neuralis/brain-core/git/<route>` lines; also documents the raw-shell and external-GitHub-MCP git planes (a routes-based skill, NOT a `git_*` MCP bundle). **The helper takes its HTTP VERB as a positional argument, so the mutating half of the skill is invisible to anything that classifies an example by the SCRIPT FILE** — 10 of the 19 routes are POST writes, and the skill's write examples are marked `NOT DISPOSABLE` (git routes only act on an already-attached source; there is no throwaway repo) with point-of-use consequences for commit / checkout / pull / push | 1 |
 
 `manage-uri-policy` migrated here from `@neuralis/agent-core` on
@@ -1538,7 +1539,7 @@ env vars and examples.
 `workflows/sources-digest.json` — a working-day digest of what changed across
 the synced sources (fs_search/fs_list since the last run, hygiene flags for
 stale/contradicting docs, per-source summary into the workflow's state
-`reports/`). Feature-gated by `drive.search` (hidden from default viewers — a
+`reports/`). Feature-gated by `files.search` (hidden from default viewers — a
 deliberate gate-visibility decision: the runs need search). Cron default
 `0 8 * * 1-5` hardcoded UTC (template crons never depend on install-time
 locale); draft-first install like every template. `workflows` is in the

package/app/README.md

@@ -23,9 +23,9 @@ React surface contributed by `@neuralis/brain-core`: the Files widget, the `file
 
 ## Security & scope
 
-- Every API call flows through `PackageApiProvider`, which the host scopes by `(projectId, agentId, userId)` from the workspace session. The brain-core route layer enforces feature grants — `drive.read`, `drive.write`, `drive.search`, `drive.sync`, `drive.mount` (plus the in-handler escalations `drive.mount.privileged` / `drive.mount.host` for privileged and host-plane roots, and `drive.policy` for the URI-policy patch), together with `filesystem.observeScoped` / `filesystem.modifyScoped` for cross-scope access — and source-scope access. The UI is not authoritative.
-- File marks and SSE event subscriptions are per-agent. Cross-agent visibility in the tree requires the same feature grants the route layer enforces (`filesystem.observeScoped`).
-- The `filesystem.change` card reads tool input from agent-core's chat store; it never re-issues writes. Approval flows go through the `approve` route, gated by `drive.write`.
+- Every API call flows through `PackageApiProvider`, which the host scopes by `(projectId, agentId, userId)` from the workspace session. The brain-core route layer enforces feature grants — `files.read`, `files.write`, `files.search`, `sources.sync`, `sources.mount` (plus the in-handler escalation `sources.privileged` for privileged roots — a source on a paired device is attached only by its owner under `device.own` — and `sources.policy` for the URI-policy patch), together with `files.readOthers` / `files.writeOthers` for cross-scope access — and source-scope access. The UI is not authoritative.
+- File marks and SSE event subscriptions are per-agent. Cross-agent visibility in the tree requires the same feature grants the route layer enforces (`files.readOthers`).
+- The `filesystem.change` card reads tool input from agent-core's chat store; it never re-issues writes. Approval flows go through the `approve` route, gated by `files.write`.
 
 ## Gotchas
 

package/app/filesystem/FilesystemHost.tsx

@@ -31,6 +31,13 @@ export interface FilesystemHostValue {
     onEvent: (event: unknown) => void,
     onConnChange?: () => void,
   ): () => void;
+  /**
+   * Subscribe to paired-device state TRANSITIONS (`devices` channel of the same
+   * hub): the frame is `{deviceId, status}` only — the subscriber re-reads its
+   * own lists (source summaries, a device `select`). The hub decides who hears
+   * which device. Optional: a host without it gives no live device updates.
+   */
+  subscribeDeviceEvents?(projectId: string, onEvent: (event: unknown) => void): () => void;
   isDocker?: boolean;
   /**
    * Optional: the signed-in user's identity, used by the Sources "Add Source"

package/app/filesystem/README.md

@@ -34,7 +34,7 @@ Files widget package — the React surface mounted by the host as the brain-core
 
 ## Pending Changes tab
 
-`ui/PendingChangesPanel.tsx` is the **Pending Changes** view in the Files widget — a journal of revertible filesystem changes that an agent has made (the durable backend is `src/store/PendingChangeStore.ts`; the route is `pending`, see `src/routes/README.md`). It offers two genuinely distinct views: a **compact list** (filename + full folder path, no content fetch) and **diff cards** (the default — opened inline, each card loads its hunks lazily from ONE fresh `preview` (baseline + current state, the record's own fingerprint) through `hooks/useVisibleDiffCards.ts`; on a source-revision change or a virtualizer remount the card keeps its last preview on screen while the fresh one loads, and the index badge shows only for the current key's answer; `+N/−M` counts are computed from the loaded hunks when the record carries none). Records are ordered **oldest-first** so the review walks first→last. A focused-card cursor (◄/► header buttons, plus `↑`/`↓`/`←`/`→`, `a`=approve, `r`=revert, `x`=dismiss when the panel is focused) an **Approve N** (two-step confirm; only records that need no acknowledgement) button and an **M need confirmation** button make a full sweep fast — the latter opens `PendingReviewDialog`, grouped by reason, 100 records per batch; a finished batch disables its group buttons and offers **Next batch (K left)**; approving advances to the next change. Each live (non-orphaned) row also carries a neutral-tone **Dismiss** (x) button — "accept-and-stop-reviewing": the change is kept exactly as it is (a present file stays on disk + indexed, an agent's delete stays deleted) and only the review entry resolves, with no connector write (the `pending` route's `dismiss` action; see `src/routes/README.md`). Clicking a filename opens the file in the tree (never replacing the panel). A filter bar narrows by source / agent / conversation, and the conversation chip is **clearable** (the `×` resets `pendingPanelFilter`). The panel is registered as `WorkspacePanelId += 'pending'` in the store, a Toolbar button, and a `FileEditor` tab + render branch — `FileEditor`'s `showFilePane` **excludes** the pending tab so the file header / amber pending banner / file-content layer never overlay the panel (they share one flex container). The tab is gated by `drive.read` (visible to every drive user), while the *content* is filtered per record server-side (owner isolation + uri-policy on the `pending` route). The chat composer's "Open in Files" button (agent-core Changes&Actions) opens this tab scoped to a conversation; this is navigation only and is distinct from the chat approve/deny `PendingInteraction` card. A notification row opens the widget through the same one-shot `applyNav`: `open-pending` (the pending summary), `open-sources` (a source's sync/embedding outcome) and `open-vector-health` (an operator's collection action) — navigation only, every gate re-applied by the panel's own reads.
+`ui/PendingChangesPanel.tsx` is the **Pending Changes** view in the Files widget — a journal of revertible filesystem changes that an agent has made (the durable backend is `src/store/PendingChangeStore.ts`; the route is `pending`, see `src/routes/README.md`). It offers two genuinely distinct views: a **compact list** (filename + full folder path, no content fetch) and **diff cards** (the default — opened inline, each card loads its hunks lazily from ONE fresh `preview` (baseline + current state, the record's own fingerprint) through `hooks/useVisibleDiffCards.ts`; on a source-revision change or a virtualizer remount the card keeps its last preview on screen while the fresh one loads, and the index badge shows only for the current key's answer; `+N/−M` counts are computed from the loaded hunks when the record carries none). Records are ordered **oldest-first** so the review walks first→last. A focused-card cursor (◄/► header buttons, plus `↑`/`↓`/`←`/`→`, `a`=approve, `r`=revert, `x`=dismiss when the panel is focused) an **Approve N** (two-step confirm; only records that need no acknowledgement) button and an **M need confirmation** button make a full sweep fast — the latter opens `PendingReviewDialog`, grouped by reason, 100 records per batch; a finished batch disables its group buttons and offers **Next batch (K left)**; approving advances to the next change. Each live (non-orphaned) row also carries a neutral-tone **Dismiss** (x) button — "accept-and-stop-reviewing": the change is kept exactly as it is (a present file stays on disk + indexed, an agent's delete stays deleted) and only the review entry resolves, with no connector write (the `pending` route's `dismiss` action; see `src/routes/README.md`). Clicking a filename opens the file in the tree (never replacing the panel). A filter bar narrows by source / agent / conversation, and the conversation chip is **clearable** (the `×` resets `pendingPanelFilter`). The panel is registered as `WorkspacePanelId += 'pending'` in the store, a Toolbar button, and a `FileEditor` tab + render branch — `FileEditor`'s `showFilePane` **excludes** the pending tab so the file header / amber pending banner / file-content layer never overlay the panel (they share one flex container). The tab is gated by `files.read` (visible to every drive user), while the *content* is filtered per record server-side (owner isolation + uri-policy on the `pending` route). The chat composer's "Open in Files" button (agent-core Changes&Actions) opens this tab scoped to a conversation; this is navigation only and is distinct from the chat approve/deny `PendingInteraction` card. A notification row opens the widget through the same one-shot `applyNav`: `open-pending` (the pending summary), `open-sources` (a source's sync/embedding outcome) and `open-vector-health` (an operator's collection action) — navigation only, every gate re-applied by the panel's own reads.
 
 ## Open-to-file tree hydration
 

package/app/filesystem/api/index.ts

@@ -552,7 +552,7 @@ export async function getGitShow(params: {
 
 // ---------------------------------------------------------------------------
 // Git Control WRITE fetchers (G2.3 / spellbound-heron) — the HUMAN face of the
-// git engine. All POST; the server additionally gates `drive.write` + a
+// git engine. All POST; the server additionally gates `files.write` + a
 // uri-policy `write` capability (uniform 403 on missing feature, 404 on scope,
 // 403 `uri_policy_denied` on path deny), unconditionally auto-snapshots before a
 // destructive op (Q6), and publishes the in-app badge with the actor's REAL
@@ -732,7 +732,7 @@ export async function deleteGitBranch(params: {
  * One-click UNDO of a destructive op (G2.5) — POST the typed `rescue` a prior
  * `discardPaths` / `deleteGitBranch` returned. The server re-snapshots first
  * (a restore is itself a mutation), then `git stash apply` (discard) or
- * `git branch <name> <ref>` (branch). `drive.write` + uri-policy `write`.
+ * `git branch <name> <ref>` (branch). `files.write` + uri-policy `write`.
  */
 export async function restoreGit(params: {
   agentId: string;
@@ -771,7 +771,7 @@ export async function checkoutGitBranch(params: {
 }
 
 /**
- * Remote git ops (G4 keyring-kestrel Slice 2) — `drive.write` + uri-policy
+ * Remote git ops (G4 keyring-kestrel Slice 2) — `files.write` + uri-policy
  * `exec`. The server derives the remote host, reads the caller's OWN connected
  * binding, resolves their OWN push token, and runs the op with a host-matched
  * credential helper (HTTPS-only, no force-push). `fetch`/`pull` echo the fresh
@@ -1259,7 +1259,7 @@ export async function getSourcesHealth(params: {
  * `agentId` is REQUIRED (warded-wren): the route runs `ensureAccess` like every
  * sibling handler, and that refuses a call with no agent in context. Every other
  * source call on this client already sends it; browse was the one that did not.
- * The route gate itself is `drive.mount` — `drive.mount.privileged` for the
+ * The route gate itself is `sources.mount` — `sources.privileged` for the
  * filesystem root and the protected host zones — so a caller who cannot attach
  * a source gets a 403 here too.
  */

package/app/filesystem/hooks/README.md

@@ -24,7 +24,7 @@ React hooks used by the Files widget: viewport diff loading and the filesystem S
 
 ## 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`.
+- `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 `files.read`.
 - 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.

package/app/filesystem/hooks/useFilesystemSSE.ts

@@ -1,6 +1,7 @@
 import { useEffect, useCallback, useRef } from 'react';
+import { createDebouncedRefetch } from '@neuralis/package-system/client';
 import { useFilesystemStore, useFilesystemStoreApi } from '../store/filesystemStore';
-import { getFilesystemHostImperative } from '../FilesystemHost';
+import { getFilesystemHostImperative, type FilesystemHostValue } from '../FilesystemHost';
 import { uriAncestors, sourceFromUri, folderUri } from '../store/helpers';
 
 /**
@@ -515,6 +516,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();
+        // …and `devices` frames: a device select re-reads too.
+        storeApi.setState((s) => ({ deviceRevision: s.deviceRevision + 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>();
@@ -575,4 +578,41 @@ export function useFilesystemSSE(agentId: string | undefined, projectId: string
     }, () => { if (live) handleConnChangeRef.current(); });
     return () => { live = false; unsubscribe(); };
   }, [agentId, projectId, storeApi]);
+
+  // Paired-device state is LIVE here too: a host source's liveness and the
+  // source form's device list follow a `devices` frame. ONE subscription per
+  // Files window; a burst is ONE summaries re-read + ONE revision bump. A hub
+  // reconnect is already covered above (the summaries re-read + the bump).
+  useEffect(() => {
+    if (!agentId || !projectId) return;
+    const host = getFilesystemHostImperative();
+    if (!host) return;
+    return subscribeDeviceRefresh(host, projectId, () => {
+      void loadSourceSummaries({ agentId, projectId }).catch(() => undefined);
+      storeApi.setState((s) => ({ deviceRevision: s.deviceRevision + 1 }));
+    });
+  }, [agentId, projectId, storeApi, loadSourceSummaries]);
+}
+
+/**
+ * `onBurst` once per burst of `devices` frames (trailing `debounceMs`). The
+ * frame is `{deviceId, status}`; anything without a device id is ignored. A
+ * host without the method gives no live device updates.
+ */
+export function subscribeDeviceRefresh(
+  host: Pick<FilesystemHostValue, 'subscribeDeviceEvents'>,
+  projectId: string,
+  onBurst: () => void,
+  debounceMs = 400,
+): () => void {
+  if (!host.subscribeDeviceEvents) return () => {};
+  const debounced = createDebouncedRefetch(onBurst, debounceMs);
+  const unsubscribe = host.subscribeDeviceEvents(projectId, (payload) => {
+    if (typeof (payload as { deviceId?: unknown } | null)?.deviceId !== 'string') return;
+    debounced.trigger();
+  });
+  return () => {
+    debounced.cancel();
+    unsubscribe();
+  };
 }

package/app/filesystem/host/README.md

@@ -13,7 +13,7 @@ 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 `drive.mount`.
+- `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`.
   - 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`.
@@ -29,7 +29,7 @@ The host integration entry point — `installFilesystemHostComponents`, re-expor
 
 - 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.
+- File marks and event subscriptions are agent-scoped; cross-agent observation requires the corresponding `files.readOthers` / `files.writeOthers` features which the route layer enforces.
 
 ## Gotchas
 

package/app/filesystem/host/buildFilesystemHostValue.ts

@@ -33,7 +33,7 @@ export function useBuildFilesystemHostValue({ port }: BuildFilesystemHostValueOp
     [userRole, userPriority],
   );
   // counted-cormorant — the caller's GRANTS, for hide-only affordance gates (the
-  // Discover dock's `drive.mount` check). Deliberately separate from
+  // Discover dock's `sources.mount` check). Deliberately separate from
   // `currentRole`: the role NAME decides nothing, the grant does. Joined into a
   // stable string so the memo below doesn't churn on a fresh array each render.
   // Named `active*`: `usePackageIconBySlug` below declares its OWN `projectId`
@@ -42,7 +42,7 @@ export function useBuildFilesystemHostValue({ port }: BuildFilesystemHostValueOp
   const activeUserId = port.useUserId();
   // `getGrantedFeatures` returns a FRESH array on every call, so memoise on a
   // joined key rather than on array identity. Feature ids are dotted lowercase
-  // (`drive.mount`) and can never contain a comma, so the round-trip is exact.
+  // (`sources.mount`) and can never contain a comma, so the round-trip is exact.
   const grantedKey = port.getGrantedFeatures(activeProjectId, activeUserId).join(',');
   const grantedFeatures = useMemo<readonly string[]>(
     () => grantedKey.split(',').filter(Boolean),
@@ -92,6 +92,13 @@ export function useBuildFilesystemHostValue({ port }: BuildFilesystemHostValueOp
         ...(onConnChange ? { onConnChange } : {}),
       });
     },
+    subscribeDeviceEvents(projectId, onEvent) {
+      return port.subscribeRealtime({
+        channel: 'devices',
+        projectId,
+        onEvent: (_name, payload) => onEvent(payload),
+      });
+    },
     isDocker: port.isDocker,
     /**
      * Fetches `/api/packages/agent-core/packages/overview` once per project