@neuralis/brain-core 0.1.0 → 0.2.1

package/app/filesystem/ui/PendingReviewDialog.tsx

@@ -8,7 +8,7 @@
  * per record, a refused revert included — nothing fails silently.
  */
 
-import React, { useCallback, useEffect, useMemo, useState } from 'react';
+import React, { useCallback, useEffect, useMemo, useRef, useState } from 'react';
 import { createPortal } from 'react-dom';
 import { Check, CheckCheck, Loader2, ShieldAlert, Undo2, X, XCircle } from 'lucide-react';
 import {
@@ -18,7 +18,9 @@ import {
 import { DiffView } from '../../cards/DiffView';
 import { detectLanguage } from '../../cards/diffUtils';
 import type { VisibleDiffQueue } from '../hooks/useVisibleDiffCards';
-import { classifyReviewOutcome, hunksOf, type ReviewOutcome } from './pendingChangesModel';
+import { acceptsAbsence, classifyReviewOutcome, hunksOf, type ReviewOutcome } from './pendingChangesModel';
+import { useFilesystemStore } from '../store/filesystemStore';
+import type { PackageApi } from '@neuralis/package-system/client';
 
 export type ReviewAction = 'approve' | 'dismiss' | 'revert';
 export type ReviewRequest =
@@ -34,7 +36,7 @@ const REASONS: Record<Reason, { label: string; chip: string }> = {
 };
 const OUTCOME: Record<ReviewOutcome, { label: string; tone: string }> = {
   ok: { label: 'Done', tone: 'text-emerald-300' },
-  changed: { label: 'Changed since the preview — reopen it', tone: 'text-amber-300' },
+  changed: { label: 'Changed since the preview — check the fresh state and confirm again', tone: 'text-amber-300' },
   'needs-ack': { label: 'Still needs a confirmation', tone: 'text-amber-300' },
   error: { label: 'Refused', tone: 'text-rose-300' },
 };
@@ -42,13 +44,13 @@ const OUTCOME: Record<ReviewOutcome, { label: string; tone: string }> = {
 export type ReviewResult = { id: string; uri: string; action: ReviewAction; outcome: ReviewOutcome; detail?: string };
 
 /** Run one review verb with the record's own fingerprint; never throws. */
-export async function applyReview(params: { agentId: string; projectId: string | null }, rec: PendingChangeRecord,
+export async function applyReview(params: { agentId: string; projectId: string | null; client: PackageApi }, rec: PendingChangeRecord,
   preview: PendingPreview, action: ReviewAction, acknowledge: boolean): Promise<ReviewResult> {
   const body = { agentId: params.agentId, ...(params.projectId ? { projectId: params.projectId } : {}), id: rec.id,
     expectedFingerprint: preview.expectedFingerprint, ...(acknowledge ? { acknowledgeCurrentState: true as const } : {}) };
   try {
-    const result = action === 'approve' ? await approveFileReview({ ...body, uri: rec.uri })
-      : action === 'revert' ? await revertPendingChange(body) : await dismissPendingChange(body);
+    const result = action === 'approve' ? await approveFileReview({ ...body, uri: rec.uri }, params.client)
+      : action === 'revert' ? await revertPendingChange(body, params.client) : await dismissPendingChange(body, params.client);
     if (result && result.ok === false) {
       const detail = 'error' in result && result.error ? String(result.error) : 'Review refused';
       return { id: rec.id, uri: rec.uri, action, outcome: classifyReviewOutcome(detail), detail };
@@ -62,6 +64,12 @@ export async function applyReview(params: { agentId: string; projectId: string |
 
 function PreviewBody({ rec, preview }: { rec: PendingChangeRecord; preview: PendingPreview }) {
   const hunks = useMemo(() => hunksOf(preview), [preview]);
+  if (acceptsAbsence(rec, preview)) {
+    return <div className="px-2.5 py-2 text-[10.5px] text-white/60 leading-relaxed">
+      The file is gone. Approving or dismissing accepts that it stays gone — nothing is recreated and the saved
+      earlier version stays in history. Revert restores that version.
+    </div>;
+  }
   if (!hunks) {
     return <div className="px-2.5 py-2 text-[10.5px] text-white/50">
       Diff {preview.diffState}: current {preview.current.state}, baseline {preview.baseline.state} ({preview.baselineProvenance}).
@@ -74,30 +82,42 @@ function PreviewBody({ rec, preview }: { rec: PendingChangeRecord; preview: Pend
 
 const BUTTON = 'h-7 px-2.5 rounded-md text-[11px] font-medium transition disabled:opacity-40 inline-flex items-center gap-1.5';
 
-export function PendingReviewDialog({ request, agentId, projectId, run, onClose, onDone, next = 0, onNext }: {
+export function PendingReviewDialog({ request, agentId, projectId, run, onClose, onDone, next = 0, onNext, refetch, onBatchStart }: {
   request: ReviewRequest; agentId: string; projectId: string | null; run: VisibleDiffQueue['run'];
+  /** The post-409 refetch, when the host owns it (the panel's card then reuses this ONE answer). */
+  refetch?: (rec: PendingChangeRecord) => Promise<PendingPreview>;
+  /** A batch starts writing: the host holds its revision-driven re-reads until `onDone`. */
+  onBatchStart?: () => void;
   onClose: () => void; onDone: (results: ReviewResult[]) => void;
   /** Records still waiting outside this batch; `onNext` (given this batch's ids) opens the next one. */
   next?: number; onNext?: (batch: string[]) => void;
 }): React.ReactElement | null {
+  const client = useFilesystemStore((s) => s.client);
   const records = useMemo(() => request.kind === 'single' ? [request.rec] : request.records, [request]);
   const [previews, setPreviews] = useState<Record<string, PendingPreview | Error>>(
     () => request.kind === 'single' && request.preview ? { [request.rec.id]: request.preview } : {});
   const [busy, setBusy] = useState(false);
   const [results, setResults] = useState<Record<string, ReviewResult>>({});
+  // Liveness is cleared on UNMOUNT only; a per-record sequence drops a superseded answer.
+  const mounted = useRef(true);
+  const loads = useRef(new Map<string, number>());
+  useEffect(() => { mounted.current = true; return () => { mounted.current = false; }; }, []);
+
+  const loadPreview = useCallback((rec: PendingChangeRecord, again = false) => {
+    const seq = (loads.current.get(rec.id) ?? 0) + 1;
+    loads.current.set(rec.id, seq);
+    const current = () => mounted.current && loads.current.get(rec.id) === seq;
+    const load = () => previewPendingChange({ agentId, ...(projectId ? { projectId } : {}), id: rec.id }, client);
+    void (again && refetch ? refetch(rec) : run(load, current))
+      .then(preview => { if (current() && preview) setPreviews(p => ({ ...p, [rec.id]: preview })); },
+        error => { if (current()) setPreviews(p => ({ ...p, [rec.id]: error instanceof Error ? error : new Error('Preview failed') })); });
+  }, [agentId, projectId, run, refetch]);
 
   useEffect(() => {
-    let live = true;
-    for (const rec of records) {
-      if (previews[rec.id]) continue;
-      void run(() => previewPendingChange({ agentId, ...(projectId ? { projectId } : {}), id: rec.id }), () => live)
-        .then(preview => { if (live && preview) setPreviews(p => ({ ...p, [rec.id]: preview })); },
-          error => { if (live) setPreviews(p => ({ ...p, [rec.id]: error instanceof Error ? error : new Error('Preview failed') })); });
-    }
-    return () => { live = false; };
+    for (const rec of records) if (!previews[rec.id] && !loads.current.has(rec.id)) loadPreview(rec);
     // Previews are fetched once per opened request; `previews` is read, not tracked.
     // eslint-disable-next-line react-hooks/exhaustive-deps
-  }, [records, agentId, projectId, run]);
+  }, [records, loadPreview]);
 
   const groups = useMemo(() => {
     const out = new Map<Reason, PendingChangeRecord[]>();
@@ -110,24 +130,32 @@ export function PendingReviewDialog({ request, agentId, projectId, run, onClose,
     return out;
   }, [records, previews]);
   const pending = records.filter(rec => !previews[rec.id]).length;
-  // A batch is finished once every record has an outcome (or a failed preview); its
-  // group buttons stop accepting clicks and the footer offers the next batch.
+  // A batch is finished once every record has a final outcome (or a failed preview);
+  // `changed` is not final — its fresh preview waits for a new click. Its group
+  // buttons stop accepting clicks and the footer offers the next batch.
+  const settled = (rec: PendingChangeRecord) => results[rec.id] !== undefined && results[rec.id].outcome !== 'changed';
   const finished = request.kind === 'group' && pending === 0 && !busy
-    && records.every(rec => results[rec.id] || previews[rec.id] instanceof Error);
+    && records.every(rec => settled(rec) || previews[rec.id] instanceof Error);
 
   const execute = useCallback(async (targets: PendingChangeRecord[], action: ReviewAction) => {
-    setBusy(true);
+    setBusy(true); onBatchStart?.();
     const done: ReviewResult[] = [];
     for (const rec of targets) {
       const preview = previews[rec.id];
       if (!preview || preview instanceof Error || results[rec.id]?.outcome === 'ok') continue;
-      const result = await applyReview({ agentId, projectId }, rec, preview, action, preview.requiresAcknowledgement.length > 0);
+      const result = await applyReview({ agentId, projectId, client }, rec, preview, action, preview.requiresAcknowledgement.length > 0);
       done.push(result);
       setResults(r => ({ ...r, [rec.id]: result }));
+      // The state moved under the preview: fetch ONE fresh preview for this record
+      // and wait for a new click — a refused action is never replayed by itself.
+      if (result.outcome === 'changed') {
+        setPreviews(p => { const { [rec.id]: _stale, ...rest } = p; return rest; });
+        loadPreview(rec, true);
+      }
     }
     setBusy(false);
     onDone(done);
-  }, [previews, results, agentId, projectId, onDone]);
+  }, [previews, results, agentId, projectId, onDone, loadPreview, onBatchStart]);
 
   if (typeof document === 'undefined') return null;
   const single = request.kind === 'single' ? request : null;
@@ -160,11 +188,11 @@ export function PendingReviewDialog({ request, agentId, projectId, run, onClose,
                   {REASONS[reason].label} · {recs.length}
                 </span>
                 {!single ? <div className="ml-auto flex items-center gap-1.5">
-                  <button type="button" disabled={busy || recs.every(rec => results[rec.id])} onClick={() => void execute(recs, 'dismiss')}
+                  <button type="button" disabled={busy || recs.every(settled)} onClick={() => void execute(recs, 'dismiss')}
                     className={`${BUTTON} bg-white/[0.04] hover:bg-white/[0.08] text-white/70`}>
                     <XCircle className="h-3 w-3" /> Confirm &amp; dismiss {recs.length}
                   </button>
-                  <button type="button" disabled={busy || recs.every(rec => results[rec.id])} onClick={() => void execute(recs, 'approve')}
+                  <button type="button" disabled={busy || recs.every(settled)} onClick={() => void execute(recs, 'approve')}
                     className={`${BUTTON} bg-emerald-500/20 hover:bg-emerald-500/30 border border-emerald-400/40 text-emerald-100 font-semibold`}>
                     <CheckCheck className="h-3 w-3" /> Confirm &amp; approve {recs.length}
                   </button>

package/app/filesystem/ui/README.md

@@ -14,9 +14,9 @@ View components for the Files widget: tree, editor, sources panel, packages pane
 Re-exported from `app/filesystem/ui/index.ts`:
 
 - `FilesystemWidget` — top-level widget; takes `{ agentId, widgetId, state? }`.
-- `FileTree`, `FileTreeNode`, `FileTreeSearch`, `SourceBranchHeader` — virtualised tree components (uses `@tanstack/react-virtual`). `FileTreeSearch` is the search PANEL body only (mode selector `keyword|semantic|grep`, filter row, results) — the query input rides inline in the sidebar HEADER (`FilesystemWidget`), panel visibility keys on `sidebarView === 'search'` alone (the header toggle/Escape clears + closes even with text), and the ≥2-char gate inside the panel only switches results-vs-hint.
+- `FileTree`, `FileTreeNode`, `FileTreeSearch`, `SourceBranchHeader` — virtualised tree components (uses `@tanstack/react-virtual`). `FileTreeSearch` is the search PANEL body only (mode selector `keyword|semantic|grep`, filter row, results) — the query input rides inline in the sidebar HEADER (`FilesystemWidget`), panel visibility keys on `sidebarView === 'search'` alone (the header toggle/Escape clears + closes even with text), and the ≥2-char gate inside the panel only switches results-vs-hint. The store keeps the answer's `requested_mode`/`effective_mode`/`embedding_degraded`/`warning` as `searchEffect` (a `contextResetPatch` key) and the panel prints ONE `searchEffectLine` ("Searched as keyword — semantic search unavailable (<reason>)") plus an `embedding missing|stale` badge per row.
 - `FileTreeContextMenu`, `TreeDeleteConfirm` — the VS Code-style file-management surface (see the section below).
-- `ReembedDialog` — the ONE "Re-embed…" dialog, shared by the Sources panel (a whole source) and the tree's context menu (a folder or a file): opening it asks `sources/reindex` for a sample-based ESTIMATE only (no queue job, no sync-marker change); the forced re-embed with the active model starts on its Re-embed button and nowhere else. Portaled like `TreeDeleteConfirm`.
+- `ReembedDialog` — the ONE estimate-first embed dialog, shared by the Sources panel (a whole source) and the tree's context menu (a folder or a file): opening it asks `sources/reindex` for a sample-based ESTIMATE only (no queue job, no sync-marker change); the work starts on its button and nowhere else. `kind="reembed"` (default) = the forced re-embed of every file with the active model; `kind="pending"` = **Embed pending…**, the `embeddingOnly` debt pass (only missing/stale embeddings; the estimate is the scope's upper bound). Portaled like `TreeDeleteConfirm`.
 - `DiscoverDock` — the **Discover** list of attachable-but-unattached sources (`GET /sources/discoverable`), pinned below the tree. **It is a SIBLING of the virtualized scroller, never a `FlatItemKind`**: a sixth item kind would have to join the `rowEstimate`/`isMeasuredRow` contract for a list that is never long enough to need virtualizing. Two placements, one component — COLLAPSED it sits in normal flow below the scroller (takes height, covers nothing, bounded to 5 rows); EXPANDED the tree renders it as an `absolute bottom-0` overlay, the ONLY state in which it may hide tree rows. Never both, so the scroller's height cannot change while the overlay is up. Visible only while EVERY source branch is collapsed (`sourceBranchExpanded`, the React-local BRANCH state — not the store's `expandedFolders`) and only for a caller holding `drive.mount`. **Consequence to know:** `activeFile` is persisted and `FileTree`'s auto-expand opens its source branch, so a returning user with an open tab lands with the dock hidden until they collapse that branch. Clicking a row hands the whole suggestion to the Sources panel through the store (`pendingSourceSuggestion`) and opens it — the prefill body lives in `SourcesPanel.applySuggestion`, ONE body shared with the panel's own Discoverable list.
 - `FileEditor`, `FileTab`, `FileMetaBar`, `CodeEditor`, `ReviewDiffView`, `EditorTabBar`, `DiffModeToggle` — the **VS Code-like editor stack**.
   - **`CodeEditor`** (CodeMirror 6 + an in-repo Shiki bridge under `codeEditor/`) is the ONE editor instance behind BOTH the read view (`readOnly`) and edit — toggling Edit only flips the `readOnly` Compartment, so the `EditorView` never remounts (no flash / scroll loss / re-tokenize). Syntax colors are the exact VS Code `dark-plus` TextMate grammars via Shiki's **JavaScript regex engine** — so **no web worker, no `.wasm`, no host CSP change** (`codeEditor/shikiHighlighter.ts` = the memoized core + `tokenizeLines` for the git-diff path — the core, the engine, both themes and all 50 `@shikijs/langs` grammars are dynamic imports, one split chunk each, so nothing of Shiki is on the module's cold path; the 15 base grammars load WITH the core so a markdown fence in one of them colours at once, the rest on first use; `codeEditor/shikiChunks.ts` = the INCREMENTAL tokenizer — position-anchored, line-aligned chunks closed at 64 lines OR 4 KB of text (whichever first) with TextMate grammar-state continuation, chunk-relative token offsets, the visible chunks tokenized synchronously under a 16 KB per-paint character budget (CodeMirror's `visibleRanges` right after a whole-document replace spans thousands of unmeasured lines — the budget, not the viewport estimate, bounds the sync path) and the prefix + a 4-chunk horizon after the viewport in idle slices (a slice is at least one chunk: measured ~90 ms worst case on dense TS/TSX and on long-line markdown, ~50 ms typical code, ~2–5 ms short-line prose — chunks past the horizon wait until scrolled to, so opening a file costs the viewport, not the document), a keystroke re-tokenizing its own chunk and walking forward only until the grammar state converges, a far scroll coloured provisionally first and corrected by the idle pass, and a whole-document replace (every file switch / reload / revert is one) split back into chunks eagerly so the first paint never tokenizes the whole file; `codeEditor/shikiDecorations.ts` = the per-view `ViewPlugin`→`DecorationSet` bridge that owns one engine per editor, because `@shikijs/codemirror` does not exist). The 120k wall is gone; `MAX_HIGHLIGHT_CHARS` (2 MB) is a memory guard on the document (above it the file renders plain), not a tokenization budget. Shared 12px/18px base theme (`codeEditor/editorTheme.ts`).
@@ -27,7 +27,7 @@ Re-exported from `app/filesystem/ui/index.ts`:
   - `DiffView` (the old hand-rolled Myers review diff) was **DELETED** — superseded by `ReviewDiffView`. NB `app/cards/DiffView.tsx` is a DIFFERENT file (the chat-card single-column diff) and stays.
 - `Toolbar` — top toolbar with the active agent’s standalone configured icon (no visible name or identity badge), sidebar toggle, refresh, upload, and panel switches. The Changes switch carries the caller's visible pending COUNT as a static badge (`pendingCount`, the server `count_only` answer — `1000+` at the listing cap); the client `pendingReviewPaths` set only tones tree rows.
 - `SourcesPanel`, `PackagesPanel`, `VectorHealthPanel`, `PanelScaffold` — right-hand panels. Sources offers advisory metrics exclusions only when enabling an attested own data source with no sync block; Save persists the editable draft. Media summaries include local structural PNG failures, and chunk-only cleanup refreshes Files separately from removed-file counts.
-- `PendingChangesPanel` — Changes groups current Git status and pending review by source/repository, including non-Git sources. Normalized URI joining renders a file once while retaining separately labeled staged/unstaged comparisons for each overlapping repository and one pending review. All cards start expanded in ONE `useVirtualizer` list (`pendingChangesModel.ts` owns the filters, the flat row list, `rowEstimate`/`isMeasuredRow` and the Approve split; the compact row pins `h-8`, every card is measured; `overflow-anchor:none` plus an above-the-fold size adjustment keep the view still); the content lanes cache every loaded preview/diff, and source revisions plus context sequences fence obsolete replies. A **Type** filter (all · pending · Git) narrows the layers; the repository picker uses the Git panel's `resolveRepoLabel`. **Approve N** counts records with no acknowledgement on their own fields (`ackHintFor`, the server preview's own predicate); the rest open `PendingReviewDialog` grouped by reason, each record sent with its own fingerprint, and every sweep reports a per-record result row (a refused revert included). The orphan probe runs on mount, Refresh and Repair only — a source revision re-reads the plain list. Source inventory is separate from content, completed siblings are cached, truncation is shown, and Git errors do not hide other sources. Review reads a bounded pending preview/fingerprint with typed current/baseline/index states; ack-required state opens an explicit confirmation. Actual WRITE access gates card, compact, bulk and repair controls; historical cards remain read-only. Orphan ids arrive with the same pending listing, so Repair remains orphan-only and re-authorized server-side.
+- `PendingChangesPanel` — Changes groups current Git status and pending review by source/repository, including non-Git sources. Normalized URI joining renders a file once while retaining separately labeled staged/unstaged comparisons for each overlapping repository and one pending review. All cards start expanded in ONE `useVirtualizer` list (`pendingChangesModel.ts` owns the filters, the flat row list, `rowEstimate`/`isMeasuredRow` and the Approve split; the compact row pins `h-8`, every card is measured; `overflow-anchor:none` plus an above-the-fold size adjustment keep the view still); the content lanes cache every loaded preview/diff, and source revisions plus context sequences fence obsolete replies. A **Type** filter (all · pending · Git) narrows the layers; the repository picker uses the Git panel's `resolveRepoLabel`. **Approve N** counts records with no acknowledgement on their own fields (`ackHintFor`, the server preview's own predicate) or in an already-loaded preview (`splitApprovable`'s `knownPreview`, no fetch of its own); the rest open `PendingReviewDialog` grouped by reason, each record sent with its own fingerprint, and every sweep reports a per-record result row (a refused revert included) — a record the sweep found needing an acknowledgement is reported AND handed to that grouped dialog (approve or dismiss with the acknowledgement). A batch (the sweep, a dialog group) HOLDS the source revisions its own writes bump (`holdRevisions`, released in `afterMutation`): N writes cost N verb requests, ONE re-list and at most one re-preview per card still listed — never a re-list plus every visible card's re-preview per write. A `changed` answer (`PENDING_STATE_CHANGED` / `PENDING_GENERATION_CHANGED`) is not final: the dialog fetches ONE fresh preview for that record (per-record sequence, liveness cleared on unmount only) and waits for a new click — never a replay. In the panel that ONE fetch is the panel's `refetch`: it waits for the re-list, the record's card holds meanwhile and adopts the answer under its final key (`takeRefetch`), so the card sends nothing of its own; a direct (dialog-less) refusal bumps only that card's preview nonce. A confirmed absence with a saved baseline is named in the preview body (`acceptsAbsence`). The orphan probe runs on mount, Refresh and Repair only — a source revision re-reads the plain list. Source inventory is separate from content, completed siblings are cached, truncation is shown, and Git errors do not hide other sources. Review reads a bounded pending preview/fingerprint with typed current/baseline/index states; ack-required state opens an explicit confirmation. Actual WRITE access gates card, compact, bulk and repair controls; historical cards remain read-only. Orphan ids arrive with the same pending listing, so Repair remains orphan-only and re-authorized server-side.
 
 - `InlineUploader` — the Upload tab (folder pick, new folder, drop zone). The two modals it once sat beside (`EditFileModal`, `UploadFileModal`) were deleted 2026-09-04: nothing had mounted either since the repository's baseline, so the settling-sandpiper M9 reconcile tails had been fixed on dead code while the live in-place Edit still called the upsert-only `refresh`. Those tails are store actions now (`saveFileInPlace` / `markFileDeleted`, `../store/README.md`) that `FileEditor` calls.
 - `GitControlPanel`, `StackedSections` (+ pure `stackedSectionsLayout.ts`), `GitCommitGraph` (+ pure `gitGraphLayout.ts`/`gitGraphPaging.ts`/`gitGraphItems.ts` — the item model: expandable rows, the outgoing divider, ref-chip/dot classing, the branch-bar ahead/behind chips), `GitDiffView` + `GitFileDiff` + `GitCommitChangesView` (re-exported; + pure `gitDiffExpand.ts`/`gitDiffPatch.ts`/`gitFileDiffMode.ts`), `GitStatusBadge`, `DiffCountBadge` — the Git Control surface: the sidebar pane-stack panel, the in-panel virtualized commit graph with commit drill-in + outgoing markers, the side-by-side diff view (single + multi-file stacked tab), the per-file tree badge. The owning narrative (sections, paging/live-refresh, drill-in, outgoing, caps, write gating) is the package-root README "Git Control panel" section — this bullet only anchors the files.
@@ -38,19 +38,20 @@ Re-exported from `app/filesystem/ui/index.ts`:
 - `SourceTypeIcon` — icon resolver per source kind.
 - `PolicyEditor` — compact admin-style permissions editor for the source-config panel. Renders the persisted JSON tree (`default`, `byRole`, `byUser`, `byAgent`, `paths[]`) with tri-state R/W/X pill badges (allow / deny / inherit cycle), per-role/user/agent override rows (with `+ Add` input + trash), and path rules with clickable role chips + per-rule agent chips (`$self/agentId`, inline-add). `OVR` toggles the rule's `override` flag. Adding a rule **prepends** it (visible at the top of long policy sets; first-match-wins means the fresh rule also takes precedence). Two modes: `edit` (Save button visible when dirty) and `view` (read-only chat-config render). It is wired into `SourcesPanel`, laid out admin-style, and carries the By Role / By User / By Agent sections. Save threads through `handlePolicySave` → `updateSourceConfig` without disturbing the user's pending sync/credential edits.
 - `SourcesPanel` "Discoverable" section — lives INSIDE the Vector Health expandable, alongside a `mount.mts` explainer card. Suggestions arrive from `GET /sources/discoverable` and use the shared `dimmedSourceTone('unattached')` util. The icon name (`AppWindow`, `GitBranch`, `FolderTree`, …) resolves through the shared `resolveLucideIcon` helper (same `ICON_MAP` as the workspace dock-left). Click pre-fills the add-source form with `{ key, path, kind, hostRoot? }` from the suggestion, plus the suggestion's optional `suggestedAccess` (read/write/exec) which overrides the connector-kind default, and — for `seed:'discoverable'` package declarations (e.g. the admin app zone, suggestion id `discover:decl:app`) — the **declared `description`** prefills the add form's description field. The **Full Host** suggestion (native/non-Docker only — `/` is the readable host root; in Docker the host must first be bound via `pnpm neuralis:mount add /`) ships `suggestedAccess: { read:true, write:false, exec:false }` so the whole-host root attaches **read-only by default** — the owner widens it (or narrows the uri-policy) in the form before saving. A host source is readable from the container shell, but host-native binaries still won't execute under the container runtime (a host PTY broker is a separate, future capability).
-- `SourcesPanel` row actions say what they do: **Rescan changes** (the `reindex` route without `force` — changed files are embedded again, unchanged ones keep their vectors), **Re-embed…** (`ReembedDialog` — every file of the source with the active model, estimate first), **Forget sync state** (the `reset` route — the next sync compares every file again; deletes no file and no vector). A started re-embed is followed by the same job poll + count refresh as a rescan (`followReindex`).
+- `SourcesPanel` row actions say what they do: **Rescan changes** (the `reindex` route without `force` — changed files are embedded again, unchanged ones keep their vectors), **Re-embed…** (`ReembedDialog` — every file of the source with the active model, estimate first), **Embed pending…** (`ReembedDialog kind="pending"`; it and **Re-embed…** are disabled while the row's live `embedding_enabled` says off), **Forget sync state** (the `reset` route — the next sync compares every file again; deletes no file and no vector). A started re-embed is followed by the same job poll + count refresh as a rescan (`followReindex`); an embedding pass that ends `paused` (terminal, not failed) shows "Embedding paused: <reason>" with **Resume** (the same owed-only apply). The Modify-source body states `binarySkipLine` ("N binary files not indexed" — the last count a pass measured) and `embeddingLine` beside `mediaSkipLine`: off — the live `embedding_enabled`, never the last pass — reads neutral ("Semantic embedding off — text and field search only"); the last pass's other reasons read amber ("Semantic embedding pending: <reasons>").
 - `SourcesPanel` row is **name-first** (the redesign for the always-narrow widget). The source name is the dominant element (`flex-1`, larger/bold); the kind icon uses the SAME resolved icon set as the file tree (`resolveIconWithFallback` over the connector-manifest `kind_icon`/`meta.icon`) and is **coloured by `getSourceVisualTone`** — so the icon tone IS the sync/live signal, matching the tree (the old `Healthy/Idle/Error` status text + `statusTone` are gone). The per-row **trust badge** (`first-party`/…) and the **scope badge** (`project`/`user`/`agent` — already a tab filter above) are removed; only `observed`, `orphan`, `unsaved`, and the enabled toggle remain inline. Rows are **grouped by `origin_package`** — the **declaring package id** the server resolves per source (the CONTRACT-BACKED `PackageSourceDeclaration` owner, returned on each `SourceRuntimeSummary` / `s.origin_package`), one group **per package**: each real `@neuralis/*` (or any other) package sorts **alphabetically** and user-added mounts collapse into a single **`Mounted (user-added)`** group that sorts **LAST** (`sourceOriginGroup` / `MOUNTED_GROUP`). The small left-indented group header **replaces** the per-row trust/`first-party` badge. The old client-side heuristic that inferred the owner from the connector kind's npm scope (`sourceOriginLabel`) is **gone** — attribution is now resolved server-side from the declarations (`matchDeclaredSource`, slug + resolved-root for rooted kinds; kind-only for rootless sandbox kinds), so a user mount named `app` that is NOT rooted at the platform app zone is NOT attributed to admin — the grouping is **unspoofable**.
 - `SourcesPanel` source body: when a row is expanded it renders at **full height** (no `max-h` clamp) so every Path Rule / uri-policy is visible and the outer panel scrolls — the closed state keeps the collapse animation. The Sync sub-section shows a per-trigger explainer (Manual = only the Sync button; Auto = file-watch + reconcile; Scheduled = interval) and clarifies the "Always active" pin. Disabling sync (unchecking "Enable sync" + Save) sends `clearSync: true` — an omitted `sync` means "no change" server-side, so without the flag the disable would silently revert.
 - `SourcesPanel` per-source counts are **lazy** — the exact `connector` / `indexed` / `unindexed` stats row is fetched ONLY when its row is opened (`toggleSource` → `fetchSourceCounts` → a list scoped to `<source>://` with `include_counts`, so `computeSourcesRegistry` walks that ONE source), cached in `countsBySource`, and shown behind a "Loading counts…" placeholder. Panel-open itself does a **count-FREE** `refresh()` (no `withCounts`) — that still populates `sourceSummaries` (`s.sources`) for source discovery (observed-only sources, project scope) + per-row connector liveness dim, but fires **zero** project-wide count walks. There is deliberately no eager `refresh({withCounts:true})` on open — that, together with the Vector Health walk below, is what used to make opening one panel slow everything. Counted refreshes are narrowed to the operations that actually MOVE a number: sync, reindex, and a config save that changed the sync FILTER set (`syncFilterChanged` — exclude/include/`maxScanFiles`/a cleared sync block, which `connector.count()` applies, so the on-disk total shifts at once). A permissions save, a delete and an add refresh count-FREE: the indexed count is a project-scoped `countByFilter` with no per-caller policy input, the on-disk count is physical truth, a deleted row is gone and a brand-new row's numbers are one expand away. Every counted path also evicts that source's cached counts (`clearCachedCounts`) so the fresh summary is what renders — the lazy cache used to shadow it indefinitely after an exclude edit. `pollSyncJob` (1.5 s × `MAX_POLLS` 2400 = a sixty-minute ceiling) checks a `mountedRef` each turn and returns the moment the panel unmounts; the ref is cleared on UNMOUNT ONLY, never in a dependency-change cleanup, so a live poll is never dropped while the panel is still there. And EVERY hook in `SourcesPanel` sits above its `if (!open) return null` guard: two `useCallback`s used to live below it, so the component rendered a different number of hooks open than closed — React refuses that on one instance, and only the parent's mount gate carrying the same `workspacePanels.sources` flag kept it from ever firing.
 - `useFilesystemSSE` `sync:completed`: the handler is matched **before** the `if (!uri) return` guard — the event carries `source` (the slug), NOT a file `uri`. It runs the authoritative `reconcileSourceFolders` over that source's VISIBLE folders (a sync can have removed files), skips the pass entirely when every change count on the payload is zero (a missing count is unknown and still re-lists), and falls back to `refreshTree` only when no source is present. That pass rides the ONE per-source reconcile schedule shared with external-change events (a trailing quiet window with a max-wait), so a burst of changes becomes one pass. Owner: `app/filesystem/hooks/README.md`.
 - `lib/iconResolver.ts` (2026-05-07) — single source of truth for lucide icon name → component lookup. Exports `ICON_MAP`, `resolveLucideIcon`, `resolveIconWithFallback`, and the `IconComponent` type. Both PascalCase keys (mirror lucide-react) and lowercase aliases (`agent`, `admin`, `brain`, `terminal`, …). The workspace dock-left re-exports it via `neuralis/src/workspace/shell/dockIcons.ts`; the filetree's `usePackageIconBySlug` hook (in `host/buildFilesystemHostValue.ts`) feeds it package-icon names from `/packages/overview` so `packages://<slug>/` and `data://<slug>/` top-level folders render the package's dock-icon instead of the generic Folder.
 - `VectorHealthPanel` per-source table — joins `getSourcesHealth()` with `checkVectorHealth()` to surface a real "Last sync" column (relative age + sync-status colour) per source, instead of being a counts-only view.
+- `VectorHealthPanel` heads its stats with ONE `semanticLine` from the report's `embedding` block (`Semantic: off / metadata only / dense (N missing · M stale)`).
 - `VectorHealthPanel` = **janitor** — the panel's role is "remove leftover records" (deleted past retention, orphaned chunks, duplicate report). Full per-source vector wipe lives on `SourceDeleteConfirm`, not here. `dryRun` default is `false` (clicking actually deletes); destructive buttons need a 2-click confirm; the Deleted stat card shows a `before → after (−Δ)` line after `GC`. Per-action explainer copy + tooltips spell out what each button does (GC / Repair are destructive; Deduplicate is read-only on the service side).
-- `VectorHealthPanel` is **lazy** — `SourcesPanel` renders it ONLY when the "Vector Health" section is expanded (`{healthOpen && …}`), never a CSS-only collapse, because the panel auto-fetches on mount; a mounted-but-hidden panel would fire the health request every time the Sources tab opens. On open it fetches the CHEAP count stats (`checkVectorHealth` → `/health`, count-only). The **Orphans** card and **Duplicate groups** count come from the EXPENSIVE on-demand scan (`scanVectorHealth` → `/health/scan`) behind an explicit **"Scan for problems"** button — they show `—` until the user runs it (and re-scan after a destructive action only if a scan was already loaded). This is the "ne lassítson 1 dolog mindent" rule: opening Sources triggers no collection walk.
+- `VectorHealthPanel` is **lazy** — `SourcesPanel` renders it ONLY when the "Vector Health" section is expanded (`{healthOpen && …}`, the store's `vectorHealthOpen`, so a notification's `open-vector-health` nav can open it; a `contextResetPatch` key), never a CSS-only collapse, because the panel auto-fetches on mount; a mounted-but-hidden panel would fire the health request every time the Sources tab opens. On open it fetches the CHEAP count stats (`checkVectorHealth` → `/health`, count-only). The **Orphans** card and **Duplicate groups** count come from the EXPENSIVE on-demand scan (`scanVectorHealth` → `/health/scan`) behind an explicit **"Scan for problems"** button — they show `—` until the user runs it (and re-scan after a destructive action only if a scan was already loaded). This is the "ne lassítson 1 dolog mindent" rule: opening Sources triggers no collection walk.
 - `SourcesPanel` add form, the ROOT field — **derived from the declaration, not from `isDocker` and not from the kind name** (`lib/sourceKindForm.ts` `rootFieldMeta`, drift-tested against the real manifests in `test/ui/sourceKindForm.test.ts`). Every other field in that form already rendered from its declared `x-neuralis.ui`; `root` was the one hand-written, kind-BLIND exception, which is why the **Host Machine** kind used to show the `local` connector's `/mounts` volume picker, its `pnpm neuralis:mount add` callout and a `/mounts/...` placeholder while its own declaration said `Host root path` / `/home/you/projects` (warded-wren, closing the UI half of F-B5). The discriminator is the declared `x-neuralis.ui.control` on `root`: `container-path` gets the volume picker + callout + Browse; `host-path` gets none of them; a bare legacy `path` (or an absent control) is treated as container-plane, so an externally authored connector is unchanged. **Not `isHostPlaneKind`** — that is a NAME test whose own docstring says a future `ssh`/`smb` kind joins the plane by being added to its body, so a negative test on it would hand the container chrome to every future non-`local` kind. Browse is additionally gated on `canMount` (the shared `meetsRequires` mirror `FileTree` uses) and stays absent for host-plane roots at all times: `GET /sources/browse` readdirs in the SERVER process, the wrong machine for a broker-resolved host root — a host-plane root browser would need a broker-backed listing route, which does not exist.
 - `SourcesPanel` description field — the VALUE is empty whenever the description is RESOLVED rather than stored (`description_effective`), and that is load-bearing: prefilling the value would freeze a copy of the package's wording into this source's config and stop it tracking the package. The resolved text therefore rides as the **placeholder** in edit state (with a one-line note saying an empty box keeps following the package) and as **labelled** text — `"… (from the package)"` — in the read state and the collapsed summary. **Both states must carry the label**: live-testing warded-wren caught it present in the read state and absent in the edit state, where the box simply looked empty; an opacity difference alone is not a label, because it does not survive the state that matters (editing).
 
-- `SourceDeleteConfirm` — inline rose-tinted popover under the row (no modal, matches the panel's "no overlay" pattern). Headline + one-line reminder that the host folder is not touched + `[ ] Purge vector index entries (~N point(s))` checkbox (default OFF — conservative) + Docker-bind-mount warning ribbon when `connection.config.hostRoot` is set, telling the user to run `pnpm neuralis:mount remove <slug>` before restarting the container. On confirm, `SourcesPanel.handleDelete` calls `deleteSource({ purgeVectors })` and surfaces a transient `successMsg` ("Deleted "<source>" (vectors purged: N)").
+- `SourceDeleteConfirm` — inline rose-tinted popover under the row (no modal, matches the panel's "no overlay" pattern). Headline + one-line reminder that the host folder is not touched + `[ ] Purge vector index entries (~N point(s))` checkbox (default OFF — conservative) + Docker-bind-mount warning ribbon when `connection.config.hostRoot` is set, telling the user to run `neuralis mount remove <slug>` before restarting the container. On confirm, `SourcesPanel.handleDelete` calls `deleteSource({ purgeVectors })` and surfaces a transient `successMsg` ("Deleted "<source>" (vectors purged: N)").
 - **`SkillLauncher` coverage** (`@neuralis/package-system/client`, additive "+" launchers) — every filesystem function the LLM can drive has a visible composer-prefill trace. Clicking a launcher PREFILLS the chat composer with the skill (+ scripts) like a `/` slash pick; it never sends/streams. **No launcher states a feature list**: visibility is DERIVED from the host's per-caller skill catalog, so it cannot drift from each skill's own `SKILL.md` `requiredFeatures` and an unresolved catalog renders nothing (the gate named per row below is the SKILL's, documented here, not repeated in the JSX). `packageId` is the REGISTRY id (`@neuralis/brain-core`), matched as an exact pair with the skill id. The launchers resolve the `WorkspaceHostPort` from the `WorkspaceHostPortProvider` mounted once in `host/installFilesystemHostComponents.tsx` — without it they render `null` silently. Current placements:
   - `Toolbar` — `sync` (`drive.sync`, icon-`brain`, script-less) next to the Sources panel toggle, and `manage-files` (`drive.write`; `scripts: mkdir, copy, modify, search`) as the general file-ops handoff. The tree's CONTEXT MENU deliberately carries none: it is a keyboard-navigable click-to-act list with one uniform item model, and a composer-prefill affordance would need a bespoke item kind there.
   - `SourcesPanel` header — `manage-sources` (`drive.read`, attached-left to the `+ Source` button; `scripts: sync, reindex, set-enabled`).
@@ -69,7 +70,7 @@ Re-exported from `app/filesystem/ui/index.ts`:
 
 ### `recognizesPackages` source toggle + package access-feature governance
 
-- **`SourcesPanel`** renders a **Recognize packages** checkbox on BOTH the Add-source wizard and the Modify-source body — shown only for `local`-kind sources AND only to an owner/admin-effective caller (`host.currentRole.priority <= 2`); it is hidden otherwise and the server re-gates. On create it rides the `createSource` body; on edit it joins the shared draft + Save (and is **stripped** from the PATCH of any caller below that strength, so an unrelated description/sync edit never trips the server's strength gate). Turning it on makes the source a runtime-WASM package source (additive to `_packages/`); the loaded packages are advertised only within the source's own scope.
+- **`SourcesPanel`** renders a **Recognize packages** checkbox on BOTH the Add-source wizard and the Modify-source body — shown only for `local`-kind sources AND only to an owner/admin-effective caller (`host.currentRole.priority <= 2`); it is hidden otherwise and the server re-gates. On create it rides the `createSource` body; on edit it joins the shared draft + Save (and is **stripped** from the PATCH of any caller below that strength, so an unrelated description/sync edit never trips the server's strength gate). Turning it on makes the source a runtime package source (additive to `_packages/`); the loaded packages are advertised only within the source's own scope.
 - **`PackagesPanel`** is the consumption-governance surface. Per package (first-party AND project WASM — both appear in the snapshot it lists), an owner/admin-effective caller sees a **base-access feature** control: attach or clear an override feature id (`ProjectRecord.packageAccessFeature`, restrict-only) that hides the whole package from anyone lacking it. The control is a **datalist picker** sourced from the project feature catalog (`getGrantableFeatureIds` → `/api/admin/feature-catalog`; free-text fallback if the fetch fails) — datalist, not a native `<select>`, to avoid the option-popup opacity gotcha; the route rejects an unknown feature id (400). A manifest-declared `requires.accessFeature` shows read-only (cannot be cleared here; an override adds an additional requirement). Non-owners see the effective feature read-only. (Grant the chosen feature to a role in Admin → Roles — a declared/overridden access feature is grantable there.)
 
 ## Security & scope

package/app/filesystem/ui/ReembedDialog.tsx

@@ -17,7 +17,8 @@
 import { useEffect, useState } from 'react';
 import { createPortal } from 'react-dom';
 import { Loader2, RefreshCcw, X } from 'lucide-react';
-import { estimateReembed, startReembed, type ReembedEstimate } from '../api';
+import { estimateReembed, startReembed, type ReembedEstimate, type ReembedKind } from '../api';
+import { useFilesystemStore } from '../store/filesystemStore';
 
 export type ReembedTarget = {
   source: string;
@@ -47,14 +48,18 @@ export function ReembedDialog({
   target,
   onClose,
   onStarted,
+  kind = 'reembed',
 }: {
   agentId: string;
   projectId?: string;
   target: ReembedTarget;
+  /** `pending` embeds only what is owed (missing / stale) — the same estimate-first confirm. */
+  kind?: ReembedKind;
   onClose: () => void;
   /** Called after a job was queued — the caller follows it however it follows sync jobs. */
   onStarted?: () => void;
 }) {
+  const client = useFilesystemStore((s) => s.client);
   const [estimate, setEstimate] = useState<ReembedEstimate | null>(null);
   const [estimating, setEstimating] = useState(true);
   const [starting, setStarting] = useState(false);
@@ -72,7 +77,7 @@ export function ReembedDialog({
   useEffect(() => {
     let live = true;
     setEstimating(true);
-    estimateReembed(scope)
+    estimateReembed(scope, kind, client)
       .then((result) => {
         if (live) setEstimate(result);
       })
@@ -105,7 +110,7 @@ export function ReembedDialog({
     setStarting(true);
     setError(null);
     try {
-      const started = await startReembed(scope);
+      const started = await startReembed(scope, kind, client);
       if (!started.job) {
         // Nothing readable in scope — the route queued nothing. Say so.
         setNothingToDo(true);
@@ -129,17 +134,25 @@ export function ReembedDialog({
     >
       <div
         role="dialog"
-        aria-label={`Re-embed ${target.label}`}
+        aria-label={`${kind === 'pending' ? 'Embed pending files of' : 'Re-embed'} ${target.label}`}
         className="w-[360px] rounded-xl border border-cyan-400/25 bg-[#15151d] p-4 shadow-[0_30px_80px_-24px_rgba(0,0,0,0.85)]"
       >
         <div className="flex items-start gap-2.5">
           <RefreshCcw className="h-4 w-4 text-cyan-300 shrink-0 mt-0.5" />
           <div className="min-w-0 flex-1">
-            <div className="truncate text-[12px] font-semibold text-white/90">Re-embed {target.label}?</div>
+            <div className="truncate text-[12px] font-semibold text-white/90">
+              {kind === 'pending' ? `Embed pending files of ${target.label}?` : `Re-embed ${target.label}?`}
+            </div>
             <div className="mt-1 text-[10.5px] text-white/55 leading-relaxed">
-              Every file in this scope is read again and embedded with the <span className="text-white/75">active</span>{' '}
-              model, whether it changed or not. File contents and history are not touched — only the vectors are
-              replaced.
+              {kind === 'pending' ? (
+                <>Only files whose semantic embedding is missing or stale are embedded, with the{' '}
+                  <span className="text-white/75">active</span> model. The figures below cover the whole scope — an upper
+                  bound; files already embedded are skipped. Contents and text search are not touched.</>
+              ) : (
+                <>Every file in this scope is read again and embedded with the <span className="text-white/75">active</span>{' '}
+                  model, whether it changed or not. File contents and history are not touched — only the vectors are
+                  replaced.</>
+              )}
             </div>
             <div className="mt-2 rounded-md bg-white/[0.03] px-2 py-1.5 text-[10.5px] text-white/65 space-y-0.5">
               {estimating ? (
@@ -192,7 +205,7 @@ export function ReembedDialog({
             className="h-7 px-3 rounded-md text-[11px] font-semibold transition disabled:opacity-40 inline-flex items-center gap-1.5 bg-cyan-500/20 hover:bg-cyan-500/30 border border-cyan-400/40 text-cyan-100"
           >
             {starting ? <Loader2 className="h-3 w-3 animate-spin" /> : <RefreshCcw className="h-3 w-3" />}
-            Re-embed
+            {kind === 'pending' ? 'Embed pending' : 'Re-embed'}
           </button>
         </div>
       </div>

package/app/filesystem/ui/SourceDeleteConfirm.tsx

@@ -75,7 +75,7 @@ export function SourceDeleteConfirm({
           if checked). To also drop the underlying compose bind, run the
           infra-only:{' '}
           <code className="font-mono not-italic text-amber-100/90">
-            pnpm neuralis:mount remove {source}
+            neuralis mount remove {source}
           </code>
         </div>
       )}