@neuralis/brain-core 0.3.1 → 0.4.0

package/app/README.md

@@ -1,6 +1,6 @@
 # Brain UI
 
-React surface contributed by `@neuralis/brain-core`: the Files widget, the `filesystem.change` card, and the host integration entry points the workspace uses to mount them.
+React surface contributed by `@neuralis/brain-core`: the Files widget, the `filesystem.change` card, and the host integration entry points the workspace uses to mount them. The Filesystem dock declares `app/shared/filesystem.png`, retaining Folder as its glyph fallback.
 
 ## Responsibility
 
@@ -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/cards/FilesystemCardShell.tsx

@@ -13,7 +13,7 @@
 import React, { memo, useCallback, useMemo } from 'react';
 import { FileText } from 'lucide-react';
 import { CardShell, ToolStatusIcon } from '@neuralis/agent-core/app/chat';
-import { computeLineCounts, isContentAction, parseToolInput } from './diffUtils';
+import { computeLineCounts, computeStreamingHunks, extractContentString, isContentAction, parseToolInput, streamingWriteVerb } from './diffUtils';
 
 /**
  * The chrome this card actually renders: its OWN `renderHeader` (a single `px-3 py-1` row
@@ -77,8 +77,11 @@ function cacheEntryFor(tool: object, status: unknown): FsHeightCacheEntry {
  * `FilesystemChangeCard` (the estimate has to agree with the renderer or it is
  * guessing):
  *
- * - pending             → the "Running…" mount state (32). Streamed content growing
- *                         toward the 90 cap is an in-place, bottom-pinned resize.
+ * - pending content     → the 90 CEILING: a content write renders its diff rows
+ *                         while the arguments stream, growing toward the 90 cap
+ *                         every delta, so the reserve is the cap from the first
+ *                         delta that names the verb (over-reserve, the cheap side).
+ * - pending, otherwise  → the "Running…" mount state / one-line preview (32).
  * - non-content op      → `NonContentOpView`, one text row (32).
  * - content MODIFY      → the 90 CEILING, deliberately (H2 pre-reserve): the real
  *                         baseline→current LCS diff arrives from an async fetch and
@@ -101,7 +104,14 @@ function filesystemCompactBodyHeight(
 
   let body: number;
   if (isPending) {
-    body = COMPACT_FALLBACK_ROW_PX;
+    if (!isPendingContentWrite(tool.input)) {
+      // Not cached while the input still streams: the verb can arrive on a later
+      // delta under the same status, and a cached 32 would then under-reserve.
+      if (typeof tool.input === 'string') return COMPACT_FALLBACK_ROW_PX;
+      body = COMPACT_FALLBACK_ROW_PX;
+    } else {
+      body = FILESYSTEM_CARD_COMPACT_BODY_PX;
+    }
   } else {
     const input = parseToolInput(tool.input);
     const action = input && typeof input.action === 'string' ? input.action : undefined;
@@ -127,14 +137,42 @@ function filesystemCompactBodyHeight(
   return body;
 }
 
+/**
+ * The pending card renders a diff (see `FilesystemChangeCard` `pendingHunks`): a
+ * streaming string whose `fs_write` content verb has opened, or a settled input
+ * that is a content action or a create.
+ */
+function isPendingContentWrite(raw: unknown): boolean {
+  if (streamingWriteVerb(raw)) return true;
+  const input = parseToolInput(raw);
+  if (!input) return false;
+  const action = typeof input.action === 'string' ? input.action : undefined;
+  return action ? isContentAction(action) : extractContentString(input) !== null;
+}
+
+/** The expanded card's row cap — `FilesystemChangeCard`'s `EXPANDED_MAX_DIFF_LINES`. */
+const EXPANDED_MAX_DIFF_LINES = 200;
+
 /**
  * EXPANDED body — the cap is gone and the body is the whole diff. This branch is not an
  * optimization — it is the single largest measured defect in the model. Live-measured
  * 2026-08-02: this card estimated **114px** while rendering **1479px** expanded, a
  * **−1353px** under-reserve, which paints the following row directly on top of it. Line
  * counts come from the SAME `computeLineCounts` the header badge uses.
+ *
+ * A STREAMING content write (the input is still the delta string) renders the TAIL of
+ * the rows `computeStreamingHunks` builds, up to the 200-row cap plus the "lines skipped"
+ * row — so it is estimated from the same rows, input-only and exact (no context
+ * allowance), and NEVER cached: the next delta grows it under the same status.
  */
 function filesystemExpandedBodyHeight(tool: { input?: unknown }, status: unknown): number {
+  const streaming = typeof tool.input === 'string' ? computeStreamingHunks(tool.input) : null;
+  if (streaming) {
+    let rows = 0;
+    for (const hunk of streaming) rows += hunk.lines.length;
+    const shown = rows > EXPANDED_MAX_DIFF_LINES ? EXPANDED_MAX_DIFF_LINES + 1 : rows;
+    return Math.max(FILESYSTEM_CARD_COMPACT_BODY_PX, DIFF_BODY_PADDING_PX + shown * DIFF_LINE_PX);
+  }
   const entry = cacheEntryFor(tool as object, status);
   if (entry.expanded !== undefined) return entry.expanded;
 

package/app/cards/FilesystemChangeCard.tsx

@@ -20,7 +20,7 @@
 
 import React, { memo, useCallback, useEffect, useMemo, useState } from 'react';
 import type { CardProps } from '@neuralis/agent-core/app/chat';
-import { previewInput, extractPathsFromToolCall } from '@neuralis/agent-core/app/chat';
+import { previewInput, extractPathsFromToolCall, extractStreamingField } from '@neuralis/agent-core/app/chat';
 import { useChatHost, useHasRowIdentity, useRowDisclosureValue } from '@neuralis/agent-core/app/chat';
 import { useWorkspaceChatStore } from '@neuralis/agent-core/app/chat/store';
 import { readFiles } from '../filesystem/api';
@@ -36,12 +36,14 @@ import {
   computeTextInsertDiff,
   computeLineCounts,
   computeLcsDiff,
+  computeStreamingHunks,
   countHunks,
   detectLanguage,
   isContentAction,
   extractContentString,
   extractResultVersionDiff,
   parseToolInput,
+  tailDiffHunks,
 } from './diffUtils';
 import type { DiffHunk } from './diffUtils';
 
@@ -91,9 +93,15 @@ export const FilesystemChangeCard = memo(function FilesystemChangeCard({ tool, s
   const maxDiffLines = isCollapsedRow ? COMPACT_MAX_DIFF_LINES : EXPANDED_MAX_DIFF_LINES;
 
   const input = useMemo(() => parseToolInput(tool.input), [tool.input]);
+  // While the arguments stream, `tool.input` is the partial STRING: the uri is
+  // read out of it (head-windowed, trailing-partial) so the header names the file
+  // before the call settles.
   const uri = useMemo(() => {
     const paths = extractPathsFromToolCall(tool);
-    return paths[0] || (input ? (strField(input, 'uri') || strField(input, 'path')) : undefined);
+    return paths[0]
+      || (input ? (strField(input, 'uri') || strField(input, 'path')) : undefined)
+      || extractStreamingField(tool.input, 'uri')
+      || extractStreamingField(tool.input, 'path');
   }, [tool, input]);
 
   const normalizedStatus = String(status || '').toLowerCase();
@@ -129,7 +137,7 @@ export const FilesystemChangeCard = memo(function FilesystemChangeCard({ tool, s
 
   const hunks = useMemo((): DiffHunk[] => {
     if (!input) return [];
-    if (isPending) return []; // During streaming, we show raw content instead
+    if (isPending) return []; // the pending branch renders `pendingHunks`
     return computeHunks(action, input);
   }, [action, input, isPending]);
 
@@ -139,14 +147,25 @@ export const FilesystemChangeCard = memo(function FilesystemChangeCard({ tool, s
     host.openFilesystemWidget?.(agentId, clickedUri);
   }, [conversationAgentId, host]);
 
-  // Streaming preview — the shared `previewInput` (agent-core's streaming-helper
-  // carrier): a pending-scoped 32 000-char head window over `extractToolDetails`,
-  // O(window) per delta with a byte-identical preview. The input itself is never
-  // truncated (the completed object renders in full above).
+  // Streaming diff — while the call runs, a CONTENT write renders its red/green
+  // rows from the input as it arrives: a settled input through the same builders
+  // as the completed card, a partial string through `computeStreamingHunks`
+  // (head-windowed carrier reads, O(window) per delta, never the LCS). The rows
+  // follow the text being written (`tailDiffHunks`). The input itself is never
+  // truncated. `null` = no content verb (yet): the plain `previewInput` preview.
+  const pendingHunks = useMemo((): DiffHunk[] | null => {
+    if (!isPending) return null;
+    if (input) return !action || isContentAction(action) ? computeHunks(action, input) : null;
+    return computeStreamingHunks(tool.input);
+  }, [isPending, input, action, tool.input]);
   const streamContent = useMemo(() => {
-    if (!isPending) return undefined;
+    if (!isPending || pendingHunks) return undefined;
     return previewInput(tool.input, true);
-  }, [isPending, tool.input]);
+  }, [isPending, pendingHunks, tool.input]);
+  const pendingView = useMemo(
+    () => (pendingHunks && pendingHunks.length > 0 ? tailDiffHunks(pendingHunks, maxDiffLines) : null),
+    [pendingHunks, maxDiffLines],
+  );
 
   // --- Real baseline→current diff for completed MODIFY (not create) ---
   // The tool result carries only `version.diff` COUNTS, not the old content, so
@@ -227,7 +246,7 @@ export const FilesystemChangeCard = memo(function FilesystemChangeCard({ tool, s
   const displayHunks = realHunks ?? hunks;
   const displayCounts = realHunks ? countHunks(realHunks) : lineCounts;
 
-  // --- Streaming state: show raw content with green tint ---
+  // --- Streaming state: the input-only diff, or the plain preview ---
   if (isPending) {
     return (
       <FilesystemCardShell
@@ -239,7 +258,11 @@ export const FilesystemChangeCard = memo(function FilesystemChangeCard({ tool, s
         isInterrupted={false}
         onUriClick={uri ? handleOpenUri : undefined}
       >
-        <StreamingContent content={streamContent} />
+        {pendingView ? (
+          <DiffView hunks={pendingView} language={language} maxLines={maxDiffLines} />
+        ) : (
+          <StreamingContent content={streamContent} />
+        )}
       </FilesystemCardShell>
     );
   }

package/app/cards/README.md

@@ -10,15 +10,16 @@ Filesystem agent-card: an IDE-style diff view rendered for `fs_write` tool calls
 
 ## Public Surface
 
-- `FilesystemChangeCard` — `(props: CardProps) => JSX.Element`. Memoised; reads its streaming preview via `previewInput` and paths via `extractPathsFromToolCall`, both from `@neuralis/agent-core/app/chat`.
-  - **Never re-scan the whole growing input on every `tool_use_delta`.** While the tool is streaming, `tool.input` is a raw accumulating JSON STRING, and both readers ran over ALL of it per delta — O(n²) across a large `fs_create`, and one of the per-commit costs behind the React #185 `rate × saturation` class (see agent-core `app/chat/ui/timeline/README.md`). Two O(1)/O(window) guards, neither of which truncates the input — both now backed by agent-core's shared streaming-helper carrier (`domain/toolPresentation.ts`, streaming parity): `parseToolInput` (in `diffUtils.ts` — the fs-specific NAME, DELEGATING to the shared `parseSettledObject`, the ONE `}`-tail-gate implementation; still the one owner shared with the height model so estimate and render discriminate variants from the SAME parse) skips the guaranteed-to-throw parse of partial JSON while a completed object still parses in full, and `streamContent` is the shared `previewInput(tool.input, true)` (the pending-scoped 32 000-char `LIVE_PARSE_WINDOW` head window over `extractToolDetails`, which caps its own output at 20 000 chars — the preview is byte-identical; the former private copy of this window here is gone). Do not remove either guard, do not re-inline a private copy, and do not "extend" them into truncating the stored input.
+- `FilesystemChangeCard` — `(props: CardProps) => JSX.Element`. Memoised; reads paths via `extractPathsFromToolCall` and, while the call streams, its uri via `extractStreamingField` and its rows via `computeStreamingHunks` (below), all through `@neuralis/agent-core/app/chat`.
+  - **The pending card renders the diff while the arguments stream.** A content `fs_write` (`edit` / `insert` / `lines` / `overwrite` / `create`) shows the uri in its header and red/green rows from the partial input: the closed `edit[]` elements (`extractSettledArrayItems` + `extractJsonStringField`) plus the still-open tail element (`extractStreamingArrayTail` + `extractStreamingField`), or the verb's one text field. The rows are the input-only line split — `computeLcsDiff` never runs while pending — cut to the LAST `maxDiffLines` rows (`tailDiffHunks`, the dropped head counted) so the card follows the text being written; the `+N/−M` badge stays off until the call settles. A structural verb (move / copy / …) and a call whose verb has not arrived keep the one-line `previewInput` preview. No animation, no remount: the row is the same card, re-rendered per delta.
+  - **Never re-scan the whole growing input on every `tool_use_delta`.** While the tool is streaming, `tool.input` is a raw accumulating JSON STRING, and both readers ran over ALL of it per delta — O(n²) across a large `fs_create`, and one of the per-commit costs behind the React #185 `rate × saturation` class (see agent-core `app/chat/ui/timeline/README.md`). Every pending read is an O(1)/O(window) guard and none truncates the input — both now backed by agent-core's shared streaming-helper carrier (`domain/toolPresentation.ts`, streaming parity): `parseToolInput` (in `diffUtils.ts` — the fs-specific NAME, DELEGATING to the shared `parseSettledObject`, the ONE `}`-tail-gate implementation; still the one owner shared with the height model so estimate and render discriminate variants from the SAME parse) skips the guaranteed-to-throw parse of partial JSON while a completed object still parses in full, the streaming rows read only the 32 000-char `LIVE_PARSE_WINDOW` head (a longer call stops at the window; nothing past it is parsed), and `streamContent` is the shared `previewInput(tool.input, true)` (the same head window over `extractToolDetails`, which caps its own output at 20 000 chars — the preview is byte-identical; the former private copy of this window here is gone). Do not remove a guard, do not re-inline a private copy, and do not "extend" them into truncating the stored input.
   - **The compact diff mount is CLAMPED to 8 rows** (`COMPACT_MAX_DIFF_LINES`): the compact body clips at 90px, so at most ~6 rows are ever visible, and mounting the full 200-row `DiffLineRow` set into a clipped body was pure per-mount cost on the scroll path (H6, residual-slide audit 2026-08-07). The collapsed state is read via agent-core's READ-ONLY `useRowDisclosureValue('card')` + `useHasRowIdentity()` (never a second `useRowDisclosure` — that would fight the owning `CardShell` mirror); outside the virtualized timeline (transcript overlays, the Pending tab) there is no row identity and the full 200-line render stands. The clamp never changes the clipped visible height (8 × 18px ≥ 90px cap).
 - `FilesystemCardShell` — filesystem-specific header atop the unified `CardShell`. Two status inputs that must never be conflated: `isPending` is the tool CALL running (the ONLY spinner source) and `reviewPending` is the RESULT having landed `pending_review` — a governance state frozen in the result snapshot, rendered as the settled check's accessible name (`pending review`, `ToolStatusIcon statusLabel`) on every op alike. `CardShell` receives `committed` for such a result: a `pending_*` word there would re-arm its stream-follow pin and, through `resolveCardTone`'s substring match, the spinner.
-- `estimateFilesystemChangeCardHeight` (exported from `FilesystemCardShell.tsx`) — the card's OWN row-height model, handed to agent-core's card registry at install time. agent-core's timeline asks the registry for it before a row has been measured; a card with no model falls back to a generic constant. It is declared next to the chrome it describes because it drifted badly when it lived in the timeline: the host-side table once claimed 240 against a real ~117 — a live-measured `first-measure` delta of **−181px**, the worst of any builtin. The **COMPACT branch is variant-aware** (H1, residual-slide audit 2026-08-07): the body is content-height clipped at `maxHeight: 90`, NOT a constant, so the model is `27 + min(90, bodyContent)` where `bodyContent` mirrors the render dispatch — `18 × diffLines` for a CREATE's input-derived rows, `32` for the one-line fallbacks (pending "Running…", "Done"/"Operation failed", non-content ops), and the **90 CEILING for a completed content MODIFY deliberately** (H2 pre-reserve: the real LCS diff arrives from an async fetch and adds context rows the input-derived count cannot see — ceiling bias accepted so the arrival does not resize the row in view). The previous constant-117 model over-reserved every short-bodied variant by +18…+72. The **EXPANDED branch** models the diff body from `computeLineCounts` (the same helper the header badge uses) with a deliberate upward margin, and is not optional: returning the compact height for a row the disclosure store says is expanded measured **−1353px** live (114 estimated against 1479 rendered), and an under-reserve does not leave a gap — it paints the next row on top of this one. The memo is keyed by the tool object **with the status it computed at** — the tool mutates by reference across pending→settle, so a reference-only memo served the pending height after settle (the H3 class). Keep both branches in step with `renderHeader` / `compactHeight` / `DiffLineRow`'s `h-[18px]`, and keep the export a module-level reference (the registry compares estimator identity). Contract: agent-core `app/chat/cards/README.md` → "Card height model".
+- `estimateFilesystemChangeCardHeight` (exported from `FilesystemCardShell.tsx`) — the card's OWN row-height model, handed to agent-core's card registry at install time. agent-core's timeline asks the registry for it before a row has been measured; a card with no model falls back to a generic constant. It is declared next to the chrome it describes because it drifted badly when it lived in the timeline: the host-side table once claimed 240 against a real ~117 — a live-measured `first-measure` delta of **−181px**, the worst of any builtin. The **COMPACT branch is variant-aware** (H1, residual-slide audit 2026-08-07): the body is content-height clipped at `maxHeight: 90`, NOT a constant, so the model is `27 + min(90, bodyContent)` where `bodyContent` mirrors the render dispatch — `18 × diffLines` for a CREATE's input-derived rows, `32` for the one-line fallbacks (a pending call with no content verb yet, "Done"/"Operation failed", non-content ops), the **90 CEILING for a PENDING content write** (its rows grow toward the cap every delta; decided from the same `streamingWriteVerb` / `parseToolInput` the render reads, and a still-undecided streaming estimate is never memoized), and the **90 CEILING for a completed content MODIFY deliberately** (H2 pre-reserve: the real LCS diff arrives from an async fetch and adds context rows the input-derived count cannot see — ceiling bias accepted so the arrival does not resize the row in view). The previous constant-117 model over-reserved every short-bodied variant by +18…+72. The **EXPANDED branch** models the diff body from `computeLineCounts` (the same helper the header badge uses) with a deliberate upward margin, and is not optional: returning the compact height for a row the disclosure store says is expanded measured **−1353px** live (114 estimated against 1479 rendered), and an under-reserve does not leave a gap — it paints the next row on top of this one. The memo is keyed by the tool object **with the status it computed at** — the tool mutates by reference across pending→settle, so a reference-only memo served the pending height after settle (the H3 class). Keep both branches in step with `renderHeader` / `compactHeight` / `DiffLineRow`'s `h-[18px]`, and keep the export a module-level reference (the registry compares estimator identity). Contract: agent-core `app/chat/cards/README.md` → "Card height model".
 - `DiffView` — green/red line renderer with single-column line numbers, truncation and skipped-context markers.
 - `NonContentOpView` — summary renderer for `set_fields`, `move`, `delete`, `revert`.
 - `diffLine.tsx` — the **shared single-column diff-line primitive**: `DiffLineRow({ lineNo?, type, content })` + the `DIFF_LINE_BG` palette (`add` emerald / `remove` red / `context` colourless). ONE owning file for the green/red/colourless look + the line-number gutter. Its only consumer today is this card's `DiffView` — the Files-widget review diff moved to `@codemirror/merge` (`ReviewDiffView`) and the old hand-rolled `app/filesystem/ui/DiffView.tsx` was deleted. Keep it a standalone primitive: it is still the shared shape any future single-column diff renderer should reuse. No `+`/`-` prefix char — the row background conveys add/remove. `DiffView` owns one shared content-width wrapper; every row fills it so shorter coloured lines also cover the horizontal scroll extent. **Gutter is git / VS Code unified-diff style:** every row numbered — REMOVE rows show their OLD (pre-edit) file line number, ADD + CONTEXT show the NEW one (so the column intentionally jumps back at a block replacement: old positions then new).
-- Diff utilities (`diffUtils.ts`): input-derived hunk builders (`computeCreateDiff`, `computeReplaceTextDiff`, `computeMultiEditDiff`, `computeUpdateDiff`, `computeTextInsertDiff`, `computeLineCounts`) AND the real baseline→current LCS (`computeLcsDiff` + `countHunks`) shared with Changes. Callers must bound the O(n·m) matrix before invoking `computeLcsDiff`; pending previews use `pendingDiffWithinBudget`, because a byte cap alone does not bound newline-dense text. Plus `detectLanguage`, `isContentAction`, `extractContentString`, and `parseToolInput` (the streaming-tolerant `}`-tail-checked input parse — the fs-specific name for agent-core's shared `parseSettledObject`; ONE owner within brain-core for the card AND the height model) — which now also runs `normalizeCardInput`, the ONE place two write vocabularies are reconciled. `fs_write` carries its intent in KEYS (`edit`, `insert`, `lines`, `overwrite`, `create`, `fields`, `move`, `copy`, `mkdir`, `revert`, `delete`); the old pair carried it in `action` plus a flat field per shape. A verb-key input is PROJECTED onto the shape the views already read (`edit[].old_string/new_string` → the `replace_text` `edits[]` pair, so the red/green hunk appears before the tool result lands and a pending approval renders the PROPOSITION), and a row written by `fs_create`/`fs_modify` passes through untouched — which is what keeps the stored history rendering. A composed call previews the most informative verb (`edit` before `lines`, `insert`, `overwrite`, `create`). Pinned by `test/ui/verbKeyCardInput.test.ts`. Types: `DiffHunk`, `DiffLine`, `DiffLineType`.
+- Diff utilities (`diffUtils.ts`): input-derived hunk builders (`computeCreateDiff`, `computeReplaceTextDiff`, `computeMultiEditDiff`, `computeUpdateDiff`, `computeTextInsertDiff`, `computeLineCounts`) AND the real baseline→current LCS (`computeLcsDiff` + `countHunks`) shared with Changes. Callers must bound the O(n·m) matrix before invoking `computeLcsDiff`; pending previews use `pendingDiffWithinBudget`, because a byte cap alone does not bound newline-dense text. Plus `detectLanguage`, `isContentAction`, `extractContentString`, and `parseToolInput` (the streaming-tolerant `}`-tail-checked input parse — the fs-specific name for agent-core's shared `parseSettledObject`; ONE owner within brain-core for the card AND the height model) — which now also runs `normalizeCardInput`, the ONE place two write vocabularies are reconciled. `fs_write` carries its intent in KEYS (`edit`, `insert`, `lines`, `overwrite`, `create`, `fields`, `move`, `copy`, `mkdir`, `revert`, `delete`); the old pair carried it in `action` plus a flat field per shape. A verb-key input is PROJECTED onto the shape the views already read (`edit[].old_string/new_string` → the `replace_text` `edits[]` pair, so the red/green hunk appears before the tool result lands and a pending approval renders the PROPOSITION), and a row written by `fs_create`/`fs_modify` passes through untouched — which is what keeps the stored history rendering. A composed call previews the most informative verb (`edit` before `lines`, `insert`, `overwrite`, `create`). Pinned by `test/ui/verbKeyCardInput.test.ts`. The STREAMING twin of that projection is `streamingWriteVerb` (the first `fs_write` content-verb key whose value has opened in the partial string's head window — the card's pending branch AND the height model decide from it) + `computeStreamingHunks` (the input-only builders over the carrier reads, `null` when no content verb has arrived) + `tailDiffHunks`. Types: `DiffHunk`, `DiffLine`, `DiffLineType`, `StreamingWriteVerb`.
 - Composer-aggregation ownership (`diffUtils.ts`, the composer-contract inversion): `extractResultVersionDiff` (the ONE `structuredContent.version.diff` reader — the card's `+N/−M` header badge AND the composer extractor share it; moved here from both its former private copy in `FilesystemChangeCard` and agent-core's deleted `extractResultDiff`), `extractFilesystemComposerChanges` (paths via agent-core's shared `extractPathsFromToolCall` + the former `deriveOpenPath` input-uri fallback for `ok:false` results; diff on the first entry), and `FILESYSTEM_COMPOSER_CONTRACT` (`{ tab: 'changes', changes }`, module-level stable) — registered in `installFilesystemHostComponents.tsx` so agent-core's Changes tab + post-stream summary learn about fs changes from the card REGISTRY, never from literals. Pinned by `test/ui/composerContract.test.ts` (parity: success uri+diff, diff-less results, `ok:false` input fallback, files[] multi-path, empty, and the reducer's string-input forms — a COMPLETE JSON string parses via the settled-object gate, a PARTIAL in-flight string yields nothing and is covered by agent-core's aggregate `openPath || label` fallback row).
 
 ## How it plugs into the package-system kernel
@@ -44,4 +45,4 @@ Filesystem agent-card: an IDE-style diff view rendered for `fs_write` tool calls
 
 ## Tests
 
-`test/ui/filesystemCardHeight.test.ts` pins the card's height model; `test/ui/filesystemCardPendingReview.test.tsx` renders the card (jsdom, a cast `ChatHostProvider` stub) and pins the `pending_review`-is-a-name floor with an in-flight control; `test/ui/composerContract.test.ts` pins the composer extractor. The chat registry and the settled-row animation guard live in agent-core (`app/chat/ui/timeline/__tests__/settledRowsNoInfiniteAnimation.test.tsx`). Diff utilities have inline unit coverage.
+`test/ui/filesystemCardHeight.test.ts` pins the card's height model; `test/ui/filesystemCardStreaming.test.tsx` renders a streaming `fs_write` edit at three cut points (uri + red/green rows), a >32K create stopping at the parse window, the pending estimate against the rendered rows and a structural-verb control; `test/ui/filesystemCardPendingReview.test.tsx` renders the card (jsdom, a cast `ChatHostProvider` stub) and pins the `pending_review`-is-a-name floor with an in-flight control; `test/ui/composerContract.test.ts` pins the composer extractor. The chat registry and the settled-row animation guard live in agent-core (`app/chat/ui/timeline/__tests__/settledRowsNoInfiniteAnimation.test.tsx`). Diff utilities have inline unit coverage.

package/app/cards/diffUtils.ts

@@ -16,7 +16,15 @@
  *    Changes tab AND the chat card's completed-MODIFY branch, mirroring the file editor.
  */
 
-import { extractPathsFromToolCall, parseSettledObject } from '@neuralis/agent-core/app/chat';
+import {
+  extractJsonStringField,
+  extractPathsFromToolCall,
+  extractSettledArrayItems,
+  extractStreamingArrayTail,
+  extractStreamingField,
+  LIVE_PARSE_WINDOW,
+  parseSettledObject,
+} from '@neuralis/agent-core/app/chat';
 import { splitDiffLines } from '@neuralis/brain-core/domain/pending-change';
 import type {
   CardComposerContract,
@@ -185,6 +193,96 @@ export function parseToolInput(raw: unknown): Record<string, unknown> | null {
   return normalizeCardInput(parseSettledObject(raw));
 }
 
+// ---------------------------------------------------------------------------
+// The STREAMING preview — `fs_write` while its arguments still arrive
+// ---------------------------------------------------------------------------
+
+/** The `fs_write` content verbs a streaming card can preview, in schema order. */
+export type StreamingWriteVerb = 'edit' | 'insert' | 'lines' | 'overwrite' | 'create';
+
+const STREAMING_VERB_RE = /"(edit|insert|lines|overwrite|create)"\s*:\s*[[{]/;
+
+/**
+ * The content verb of an `fs_write` call whose input is still the accumulating
+ * `tool_use_delta` STRING — the first verb KEY whose value has opened, read from
+ * the head window. A key inside a string value cannot match (its quotes arrive
+ * escaped). `undefined` until one arrives, for a structural verb, and for any
+ * non-string input (a settled input is read through `parseToolInput`).
+ *
+ * ONE owner: the card's pending branch and the height model both decide from it.
+ */
+export function streamingWriteVerb(input: unknown): StreamingWriteVerb | undefined {
+  if (typeof input !== 'string') return undefined;
+  const head = input.length > LIVE_PARSE_WINDOW ? input.slice(0, LIVE_PARSE_WINDOW) : input;
+  return STREAMING_VERB_RE.exec(head)?.[1] as StreamingWriteVerb | undefined;
+}
+
+/**
+ * Line-split hunks for a STREAMING `fs_write` content verb, or `null` when no
+ * content verb has arrived (the caller keeps its plain preview). Edit pairs come
+ * from the closed `edit[]` elements plus the still-open tail element; the other
+ * verbs stream their one text field. Every read is head-windowed
+ * (`LIVE_PARSE_WINDOW`), never a `JSON.parse`, and the hunks use the input-only
+ * builders — never `computeLcsDiff`, whose O(n·m) matrix has no place per delta.
+ */
+export function computeStreamingHunks(input: unknown): DiffHunk[] | null {
+  const verb = streamingWriteVerb(input);
+  if (!verb) return null;
+  if (verb === 'edit') {
+    const edits: Array<{ find: string; replace: string }> = [];
+    for (const item of extractSettledArrayItems(input, 'edit')) {
+      edits.push({
+        find: extractJsonStringField(item, 'old_string') ?? '',
+        replace: extractJsonStringField(item, 'new_string') ?? '',
+      });
+    }
+    const tail = extractStreamingArrayTail(input, 'edit');
+    if (tail) {
+      edits.push({ find: readStreamingString(tail, 'old_string'), replace: readStreamingString(tail, 'new_string') });
+    }
+    return computeMultiEditDiff(edits);
+  }
+  if (verb === 'insert') return computeTextInsertDiff(readStreamingString(input, 'insert_text'));
+  if (verb === 'lines') return computeUpdateDiff(readStreamingString(input, 'content'));
+  return computeCreateDiff(readStreamingString(input, 'content'));
+}
+
+/**
+ * `extractStreamingField`, tolerant of a delta that ended inside an escape: an odd
+ * trailing backslash has no complete capture, so the value would vanish for one
+ * delta and the rows would flicker. The half escape is left for the next delta.
+ */
+function readStreamingString(text: unknown, field: string): string {
+  const value = extractStreamingField(text, field);
+  if (value !== undefined || typeof text !== 'string' || !text.endsWith('\\')) return value ?? '';
+  return extractStreamingField(text.slice(0, -1), field) ?? '';
+}
+
+/**
+ * The LAST `maxLines` rows of `hunks` — a streaming card follows the text being
+ * written, so the cut drops the HEAD and says how many rows it dropped (DiffView's
+ * own `maxLines` cut drops the tail, right for a settled card).
+ */
+export function tailDiffHunks(hunks: DiffHunk[], maxLines: number): DiffHunk[] {
+  let total = 0;
+  for (const h of hunks) total += h.lines.length;
+  if (total <= maxLines) return hunks;
+  const kept: DiffHunk[] = [];
+  let budget = maxLines;
+  for (let i = hunks.length - 1; i >= 0 && budget > 0; i--) {
+    const h = hunks[i];
+    if (h.lines.length <= budget) {
+      kept.unshift(h);
+      budget -= h.lines.length;
+    } else {
+      kept.unshift({ skippedBefore: 0, lines: h.lines.slice(h.lines.length - budget) });
+      budget = 0;
+    }
+  }
+  kept[0] = { ...kept[0], skippedBefore: total - maxLines };
+  return kept;
+}
+
 // ---------------------------------------------------------------------------
 // Real baseline → current diff (LCS) — shared by the Changes tab + the chat card
 // ---------------------------------------------------------------------------

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"
@@ -40,8 +47,8 @@ export interface FilesystemHostValue {
   currentUser?: { name?: string; email?: string };
   /**
    * R2b — the signed-in user's role + ordinal priority within the active
-   * project. Used to HIDE owner/admin-only controls (the `recognizesPackages`
-   * source toggle, the package access-feature override) for non-owner callers.
+   * project. Used to HIDE owner/admin-only controls (the package-folders field,
+   * the package access-feature override) for non-owner callers.
    * UX-only: the server route is always the enforcement floor. Omitted ⇒ the
    * controls hide (deny-by-default). Owner/admin-effective = priority ≤ 2.
    */
@@ -59,6 +66,21 @@ export interface FilesystemHostValue {
    * greyed-out or locked row). Omitted / empty ⇒ hide, deny-by-default.
    */
   grantedFeatures?: readonly string[];
+  /**
+   * Open Admin → Packages (project scope) for this agent's window — where a
+   * package manager changes a package's trust, builds it or gates it with a
+   * feature. Optional: a host without it shows no link.
+   */
+  openAdminPackages?(agentId: string): void;
+  /**
+   * The folder picker's device asks, both agent-core routes: record a folder on
+   * the caller's OWN device for its owner to allow there (`POST
+   * devices/:id/requests`), and how many asks that device holds for this
+   * project (`GET devices/:id/requests`; `null` = could not ask). The grant
+   * stays on the machine. Optional: a host without them shows the CLI line only.
+   */
+  requestDeviceFolder?(input: { deviceId: string; path: string; list: 'read' | 'write'; projectId: string; agentId: string }): Promise<{ recorded: boolean; reason?: string }>;
+  countDeviceFolderRequests?(input: { deviceId: string; projectId: string; agentId: string }): Promise<number | null>;
   /**
    * Optional: resolve a package's dock-icon by slug. Used by the filetree
    * to show the package icon on `packages://<slug>/` and `data://<slug>/`

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/README.md

@@ -6,7 +6,7 @@ Typed client for brain-core package routes plus a small set of host-side helpers
 
 - Wrap a kernel `PackageApi` into typed functions that mirror every brain-core route; each takes that client as its LAST argument.
 - Build raw-file URLs (`getRawFileUrl`) for the `<img>` / `<video>` preview elements. **Not for an iframe or any other document embed** — the byte lane serves the executable document class (SVG, HTML, XML) as `content-disposition: attachment`, so a document embed against it renders nothing, and making it render again would re-open a stored-XSS path. There is exactly one call site today (`FileEditor`).
-- Provide the host-side helpers (`projectPackages.ts`) used by the Packages tab — these talk to the host's `/api/packages/runtime` and `/api/projects/:id/packages/:slug/{build,trust}` routes, NOT to brain-core.
+- Provide the host-side reads (`projectPackages.ts`) used by the Packages tab — the host's scoped snapshot `/api/packages/runtime` (with the window's `x-agent-id`) and agent-core's diagnostics, NOT brain-core.
 
 ## Public Surface
 
@@ -14,13 +14,13 @@ Typed client for brain-core package routes plus a small set of host-side helpers
 - Pending changes (`index.ts`): `listPendingChanges` (with `include_orphans` it returns `orphanIds` beside the rows, from the server's SAME listing pass — the panel needs both on every mount, and two calls ran the whole dual-source listing twice), `previewPendingChange` (authoritative current/baseline states and fingerprint), `revertPendingChange`, `scanOrphanedPending` (the complete scanned page in `changes`, its orphan subset in `orphans`, and the same continuation), `discardPendingChange`, `dismissPendingChange`, `discardOrphanedPending`. Pending-backed approve/dismiss/revert carry the fresh `expectedFingerprint` and any required acknowledgement; a stale intent returns409. Types: `PendingChangeRecord`, `PendingChangesQuery`, `PendingPreview`, `PendingReviewIntent`. Pending clients preserve the page envelope and URI/cursor filters; count returns `{count, exact, complete, partial}` and safe unavailable branches; the store preserves its previous count when both branches fail.
 - Git (`index.ts`) — the `/git/*` client behind the Git Control panel. Reads: `getGitRepos`, `getGitStatus`, `getGitBranches`, `getGitDiff`, `getGitLog`, `getGitLogStats`, `getGitCommitFiles`, `getGitOutgoing`, `getGitShow`. Writes: `stagePaths`, `unstagePaths`, `stageHunk`, `unstageHunk`, `discardPaths`, `commitGit`, `createGitBranch`, `deleteGitBranch`, `restoreGit`, `checkoutGitBranch`. Remote (uri-policy `exec`): `fetchGit`, `pullGit`, `pushGit`. Type: `GitRescue` — the typed carrier a destructive op returns and `restoreGit` echoes back.
 - Sources (`index.ts`): `listSourceConfigs`, `updateSourceConfig`, `createSource`, `deleteSource`, `triggerSourceSync`, `getSyncStatus`, `cancelSync`, `resetSync`, `reindexSource` ("Rescan changes"), `estimateReembed` / `startReembed` (the same route with a `folder` / `uri` scope and `force: true` — a re-embed with the active model; the estimate answers before any side effect, a scope with nothing readable queues nothing), `purgeSourceIndex` (source/folder/file estimate or apply; keeps source and recovery content), `getSourcesHealth`, `browseDirectories`, `listSourceKinds`, `getSourceKindSchema`, `setSourceEnabled` (W3K), `listDiscoverableSources` (W3E). Types: `ReembedScope`, `ReembedEstimate`, `SourceKindRecord`, `SourceKindSchema`, `ResolveListOpts`, `DiscoverableSourceSuggestion`.
-- Project packages (`projectPackages.ts`): `listProjectPackages`, `buildPackage`, `setPackageTrust`, `setPackageAccessFeature`, `getGrantableFeatureIds` (the per-project base-access governance pair — see `../ui/README.md`), `getPackagesDiagnostics` (W3F — also consumed by chat-config Packages Overview through the agent-core ports). Types: `ProjectPackageRow`, `BuildResponse`, `TrustValue`, `PackageDiagnosticEntry`, `PackagesDiagnosticsResponse`.
+- Project packages (`projectPackages.ts`): `listProjectPackages(projectId, agentId?)` (what the agent gets, native packages left out), `getPackagesDiagnostics` (W3F — also consumed by chat-config Packages Overview through the agent-core ports). Types: `ProjectPackageRow`, `PackageDiagnosticEntry`, `PackagesDiagnosticsResponse`. Trust, Build and the access feature are Admin → Packages calls, not here.
 
 ## How it plugs into the package-system kernel
 
 - A Files window passes the client its store was created with — `createPackageApi` over the window's project and BOUND agent — so the X-Project-Id / X-Agent-Id headers are the window's own, fixed before any await, whatever other window is mounted beside it; a body may still name another agent (a file read through its writing agent). `readFiles` alone also runs without a client, for the chat change card, which is not a Files window and resolves the first registered `brain-core` provider.
 - The `PackageApi` provided by `@neuralis/package-system/client` translates `.get(path, qs)`, `.post(path, body)`, `.patch`, `.del`, `.upload` into authenticated requests against `/api/packages/brain-core/<path>` with the active session attached by the host.
-- Project-package helpers go directly to host routes (`/api/packages/runtime`, `/api/projects/:id/packages/:slug/build`, `/.../trust`) — these are NOT package routes and are not part of the brain-core surface; the helpers live here only because the Files widget's Packages tab consumes them.
+- Project-package reads go directly to the host's `/api/packages/runtime` — NOT a package route and not part of the brain-core surface; the helper lives here only because the Files widget's Packages tab consumes it.
 
 ## Security & scope
 

package/app/filesystem/api/index.ts

@@ -153,6 +153,8 @@ export async function triggerSourceSync(params: {
   agentId: string;
   projectId?: string;
   source: string;
+  /** One full pass may tombstone a source whose root now holds nothing (`root_empty`). */
+  confirmEmpty?: boolean;
 }, client: PackageApi): Promise<TriggerSourceSyncResponse> {
   return client.post('sources/sync', params);
 }
@@ -297,6 +299,7 @@ export async function getGitRepos(params: {
  * Whole-repo change-set + current branch for the focused git-repo source.
  * `status.upstream`/`ahead`/`behind` (C3) are present only when the branch has
  * an upstream — the branch-bar `↑N ↓M` chips (local refs; fetch lands in G4).
+ * A checkout git could not read answers `ok:false` with a fixed `error`.
  */
 export async function getGitStatus(params: {
   agentId: string;
@@ -304,12 +307,12 @@ export async function getGitStatus(params: {
   source: string;
   repo?: string;
 }, client: PackageApi): Promise<{
-  ok: boolean;
+  ok: true;
   status: GitControlStatus;
   /** Bucket `+/-` totals for the section headers, summed server-side over the
    *  rows in `status` — see `GitDiffTotals`. Absent on an older server. */
   totals?: { changes: GitDiffTotals; staged: GitDiffTotals };
-}> {
+} | { ok: false; code: 'unavailable'; error: string }> {
   const qs: Record<string, string> = { agentId: params.agentId, source: params.source, ...repoQuery(params.repo) };
   if (params.projectId) qs.projectId = params.projectId;
   return client.get('git/status', qs);
@@ -552,7 +555,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 +735,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 +774,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
@@ -1253,23 +1256,38 @@ export async function getSourcesHealth(params: {
   return client.get('sources/health', qs);
 }
 
+/** One level of a folder listing (`GET sources/browse`). */
+export type BrowseFoldersResult = {
+  entries: Array<{ name: string; path: string; type: 'directory'; access?: 'read' | 'write' }>;
+  atRoot?: boolean;
+  /** Device only: the listing is the folders that device allows this host (empty path). */
+  roots?: boolean;
+  /** Device only: `ok`, or the device's fixed class (`ceiling_denied`, `device_offline`, `broker_outdated`, …). */
+  state?: string;
+  truncated?: boolean;
+  /** Device only: linked folders, counted and not followed. */
+  symlinks?: number;
+};
+
 /**
- * One level of directory listing, before attaching a source.
+ * One level of folders before attaching a source — on this server, or with
+ * `device` on the caller's OWN paired device (empty path there = the folders
+ * the device allows this host).
  *
- * `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
- * filesystem root and the protected host zones — so a caller who cannot attach
- * a source gets a 403 here too.
+ * `agentId` is REQUIRED: the route runs `ensureAccess` like every sibling
+ * handler. On this server the gate is `sources.mount` (`sources.privileged` for
+ * the filesystem root and the protected host zones); on a device it is the
+ * device's owner with `device.own` — anyone else gets one fixed 403.
  */
 export async function browseDirectories(params: {
   path: string;
   agentId: string;
   projectId?: string;
-}, client: PackageApi): Promise<{ entries: Array<{ name: string; path: string; type: 'directory' }> }> {
+  device?: string;
+}, client: PackageApi): Promise<BrowseFoldersResult> {
   const qs: Record<string, string> = { path: params.path, agentId: params.agentId };
   if (params.projectId) qs.projectId = params.projectId;
+  if (params.device) qs.device = params.device;
   return client.get('sources/browse', qs);
 }
 
@@ -1279,8 +1297,14 @@ export type SourceKindRecord = {
   description: string | null;
   icon: string | null;
   packageId: string;
-  trust: 'first-party' | 'trusted' | 'untrusted';
+  trust: 'native' | 'trusted' | 'untrusted';
   capabilities: string[];
+  /** A shell can run in this kind's sources (the host kind's planes, or a connector declaring `exec`) — the Exec policy bit applies. */
+  shell?: boolean;
+  /** The entry features a shell on this kind needs (an `exec` connector) — tooltip information, never a gate. */
+  execRequires?: string[];
+  /** The kind serves only while its runtime runs (the Machine desktop). */
+  runtimeGated?: boolean;
   urlScheme: string;
   configSchema: Record<string, unknown>;
   defaultScope: 'project' | 'user' | 'agent';