@neuralis/brain-core 0.1.0 → 0.2.0

package/README.md

@@ -1,13 +1,13 @@
 # @neuralis/brain-core
 
-The brain of Neuralis: any system a connector can reach — local directories, repositories, machine sandboxes, the vector memory itself — joins ONE URI-addressed, vector-indexed, project/user/agent-scoped virtual filesystem, chunked and embedded on sync, revertible on write, policy-governed per path. A synced source pays back twice: its content becomes searchable memory, and its markdown becomes source packages. Concretely: URI-native filesystem, vector memory, source connectors, and the Files UI.
+The brain of Neuralis: any system a connector can reach — local directories, repositories, machine sandboxes, the vector memory itself — joins ONE URI-addressed, vector-indexed, project/user/agent-scoped virtual filesystem, chunked and indexed on sync with optional embedding, revertible on write, policy-governed per path. A synced source pays back twice: its content becomes searchable memory, and its markdown becomes source packages. Concretely: URI-native filesystem, vector memory, source connectors, and the Files UI.
 
 ## Responsibility
 
 - Read, create, modify, list, and search files across every registered source through one URI vocabulary.
 - Manage project-, user-, and agent-scoped source configurations and persist them in the platform zone.
 - Host the connector registry contract: source connectors declared by other packages plug in via `SourceKindRegistry`.
-- Sync connector content into a Qdrant-backed vector index with chunked embeddings.
+- Sync connector content into a Qdrant-backed payload/full-text index, with optional chunked embeddings.
 - Expose the Filesystem package routes (`/api/packages/brain-core/*`) and the agent tools (`fs_read`, `fs_write`, `fs_list`, `fs_search`).
 - Render the workspace Files widget and the `filesystem.change` agent-card.
 
@@ -123,10 +123,12 @@ soft — no badges); (2) reject leading-dash refs/paths (option-injection)
 and require `--` before path operands; (3) `-c core.hooksPath=/dev/null
 -c core.fsmonitor=false -c core.pager=cat` on every call, defeating a malicious
 repo-local `.git/config` (closes the malicious-checkout RCE class); (4) strip EVERY
-ambient `GIT_*` env var and force `GIT_CONFIG_GLOBAL`/`SYSTEM=/dev/null`. Setting
-floors (3)/(4) defensively requires simple-git's explicit `unsafe:{…}` opt-ins,
-since simple-git blocks those same flags/env as attacker-injection vectors — which
-is why stripping ALL `GIT_*` (not a denylist) is the robust rule. It exports the
+ambient `GIT_*` env var, then set `GIT_CONFIG_GLOBAL=/dev/null`,
+`GIT_CONFIG_SYSTEM=/dev/null`, `GIT_TERMINAL_PROMPT=0` and `GIT_OPTIONAL_LOCKS=0`.
+Simple-git v4 requires top-level `allowEnvironment` naming exactly those four
+fixed defensive overrides, together with the existing explicit `unsafe:{…}`
+opt-ins for floors (3)/(4). It blocks those same flags/env as attacker-injection
+vectors — stripping ALL ambient `GIT_*` (not a denylist) remains the robust rule. It exports the
 pure helpers `classifyGitOp(op, args) → 'read'|'mutating'|'destructive'` (for the
 later approval gate) and `normalizeStatus`. Read primitives are fully implemented;
 local-mutating ops are implemented but NOT yet tool-exposed (they wait on the
@@ -687,8 +689,8 @@ through the ordinary user/agent-equality filter, unchanged.
 Lifecycle exports (`src/lifecycle.ts`):
 
 - `init`, `start`, `onBootstrapComplete`, `drain`, `stop`, `api`, `onCredentialChanged`, `health`, `onPrincipalRevoked`, `provisionProject` (`usecases/provisionProject.ts` — a NEW project's declared `seed:'auto'` sources, written complete through the same create path as the boot repair; see Declared sources), `deprovisionProject` (`usecases/deprovisionProject.ts` — on a PERMANENT project delete, ALL of the project's vector points leave the shared index in ONE bounded `deleteByFilter({ must: [{ field: 'projectId', equals: id }] })` — chunks + folder-ancestor points covered by the same keyword-index filter. MUST-HAVE: a failed delete throws, and so does a degraded boot where Qdrant is configured but the in-memory index is wired (a delete there would leave every real point in Qdrant); the host then stops the purge before any file is removed. It runs BEFORE the fs tree is removed, so resolving the brain infra cannot re-materialize the project dir).
-- `init` state exposes `services["package-source-roots"]` for kernel registration; its delegate is the same function as the direct API method.
-- `BrainCoreApi` — `getProjectServices`, `getProjectInfra`, `getFilesystem`, `upsertSourceConfig`, `listShellSourceRoots(projectId)` (every shell-capable source with its persisted permissions; feeds agent-core's shell uri-policy gate and the terminal's host-tab resolver; NOT access-filtered — consumers evaluate the policy against the caller's own `SessionContext`. Rows carry an explicit **`plane`**: `container` sources contribute their `containerRoot`, resolved by the canonical `resolveLocalRoot`; **host-plane** sources contribute a raw `hostRoot` and an intentionally EMPTY `containerRoot` — no container path exists for them, and the empty value is load-bearing, because the consumer's container-plane filter drops rootless entries so a host source can never leak into a container-plane lookup even if `plane` were ignored. The plane is derived from the connector KIND, never from the slug string — an ordinary local source may legitimately be named `host-notes`. Kinds that host no shell at all (brain vectors, webtop) contribute nothing), and `listSourceRuntimeSummaries(projectId, { userId, agentId, role?, grantedFeatures? })` (the READ sibling of `listShellSourceRoots`, feeding agent-core's `<runtime_stack>` source rendering — **all** connector kinds, **access-filtered** (host-plane rows carry `containerDir: null` — their root is a path in the OPERATOR's filesystem with no container equivalent, and the local-shaped derivation would otherwise print a container path that does not exist, baked into every agent's cached system prompt) via `canAccessScope` → `filesystem.observeScoped`/deny-by-default, each row carrying connector, `os_uri`/`container_dir`, the caller-effective uri-policy, `description`, and the cached index snapshot; reads persisted source-config JSON ONLY — no live walk / no vector count — so it is safe to call once per stream. Agent-core renders the stable structure in the cached `<runtime_stack>` prefix and the volatile counts + on/off in `<workspace_live>`. Disabled sources are INCLUDED, marked `enabledEffective:false`). `listPackageSourceRoots(projectId)` (enumerate every project-associated source as a runtime-WASM package-source candidate `{ slug, uriRoot, containerRoot, scope, recognizesPackages, enabled, kind }`; identity-free like `listShellSourceRoots`, ALL candidates returned so the host applies the floor — project-scope + flagged + enabled + local; the host's `projectPackages` consumes it to scan + hot-reload flagged source dirs alongside `_packages/`). Filesystem events reach the `/brain-core/events` SSE route and the discovered `filesystem` channel of the host `/api/events` hub through ONE authorization adapter: it takes the real session, authorizes EACH requested agent deny-by-default (a foreign agent yields zero events, never an existence-confirming error), and filters events by user/project/types and the authorized agent or source.
+- `init` state exposes `services["package-source-roots"]` for kernel registration; its `listPackageSourceRoots` delegate is the same function as the direct API method, and its `subscribePackageSourceRoots(listener)` calls `listener(projectId)` after every committed source-config write of the app root (`SourceConfigMutation.onChanged` — fired outside the write lock, a no-op write never fires, a throwing listener is logged and never reaches the writer), so the host re-derives that project's flagged package roots at once.
+- `BrainCoreApi` — `getProjectServices`, `getProjectInfra`, `getFilesystem`, `upsertSourceConfig`, `listShellSourceRoots(projectId)` (every shell-capable source with its persisted permissions; feeds agent-core's shell uri-policy gate and the terminal's host-tab resolver; NOT access-filtered — consumers evaluate the policy against the caller's own `SessionContext`. Rows carry an explicit **`plane`**: `container` sources contribute their `containerRoot`, resolved by the canonical `resolveLocalRoot`; **host-plane** sources contribute a raw `hostRoot` and an intentionally EMPTY `containerRoot` — no container path exists for them, and the empty value is load-bearing, because the consumer's container-plane filter drops rootless entries so a host source can never leak into a container-plane lookup even if `plane` were ignored. The plane is derived from the connector KIND, never from the slug string — an ordinary local source may legitimately be named `host-notes`. Kinds that host no shell at all (brain vectors, webtop) contribute nothing), and `listSourceRuntimeSummaries(projectId, { userId, agentId, role?, grantedFeatures? })` (the READ sibling of `listShellSourceRoots`, feeding agent-core's `<runtime_stack>` source rendering — **all** connector kinds, **access-filtered** (host-plane rows carry `containerDir: null` — their root is a path in the OPERATOR's filesystem with no container equivalent, and the local-shaped derivation would otherwise print a container path that does not exist, baked into every agent's cached system prompt) via `canAccessScope` → `filesystem.observeScoped`/deny-by-default, each row carrying connector, `os_uri`/`container_dir`, the caller-effective uri-policy, `description`, and the cached index snapshot; reads persisted source-config JSON ONLY — no live walk / no vector count — so it is safe to call once per stream. Agent-core renders the stable structure in the cached `<runtime_stack>` prefix and the volatile counts + on/off in `<workspace_live>`. Disabled sources are INCLUDED, marked `enabledEffective:false`). `listPackageSourceRoots(projectId)` (enumerate every project-associated source as a runtime package-source candidate `{ slug, uriRoot, containerRoot, scope, recognizesPackages, enabled, kind }`; identity-free like `listShellSourceRoots`, ALL candidates returned so the host applies the floor — project-scope + flagged + enabled + local; the host's `projectPackages` consumes it to scan + hot-reload flagged source dirs alongside `_packages/`). Filesystem events reach the `/brain-core/events` SSE route and the discovered `filesystem` channel of the host `/api/events` hub through ONE authorization adapter: it takes the real session, authorizes EACH requested agent deny-by-default (a foreign agent yields zero events, never an existence-confirming error), and filters events by user/project/types and the authorized agent or source.
 
 **Cross-package writes go through `FilesystemService` itself, and its permission check is
 the ONLY gate on that path.** `getProjectServices(projectId).filesystem` hands back the live
@@ -806,10 +808,9 @@ whole index: `enrichment_revision` (`src/sync/categoryInference.ts`) marks a pay
 derived fields are what the current rules give for its own uri + content, a stamped point
 is skipped before anything reads its content back, and only the unstamped candidates are
 hydrated — payload-only upserts, existing vector reused, no re-embed. On a settled source
-the sweep WRITES nothing. A point holding no inline text is HEALED there: an indexable uri
-whose file still hashes to the point's `content_hash` gets that text back, payload-only; one
-that cannot be healed never becomes stamped, so it stays a candidate and is re-hydrated each
-full pass, but it is never re-written. The
+the sweep WRITES nothing. A point holding no inline text (a media point) never becomes
+stamped, so it stays a candidate and is re-hydrated each full pass, but it is never
+re-written unless a URI-derived field drifted. The
 stamp is written by ONE boundary,
 `src/vector/FilesystemVectorIndex.ts`, on every index write from every path; a payload it
 cannot derive from (a chunk, a tombstone, a `pending_review` draft, a node holding no
@@ -920,11 +921,11 @@ The embedding model registry (`src/embeddings/models.ts`, `EMBEDDING_MODELS`) is
 
 Every cloud provider has its OWN platform credential (`embedding.<provider>`), never the chat provider's `llm.*` key — so an embed call is counted by the credential-use rules and priced by the embedding spend meter on its own; an operator endpoint's key is `embedding.endpoint.<endpointId>`. Every call to a public provider or endpoint is address-checked and IP-pinned by the kernel's SSRF floor on every call. Many rows expose MRL / Matryoshka selectable dimensions (`supportedDimensions`).
 
-**Active vs target, and the switch.** The embedding lock records the ACTIVE generation (model, dimension, recipe, collection): every write and every search embeds with it, so one collection never mixes vector spaces. The configured `embeddingModelId`/`embeddingDimension` are the TARGET; a target that differs is a pending switch the admin Vector section shows with a sampled estimate — nothing switches by itself. The switch is a generation rebuild (`health/collection` `rebuild-generation`): the target re-embeds eligible points from their stored text into a new collection while the old one keeps serving, every write that lands meanwhile is mirrored onto it, and the swap moves the lock one generation on — `brain://` content and version history survive, and the dimension may change freely. It can be cancelled (the shadow is dropped, nothing else changes) and resumed after a restart (a restart pauses it). Separately, `sources/reindex` with `force` re-embeds a file, a folder or a source with the ACTIVE model, estimate first — an unchanged file keeps its payload (`updatedAt`, version history), so a re-embed never reads as an edit. Already recovery-only points with unavailable input retain their complete payload without vectors in the target; verified available input restores ordinary embedding. Unmarked missing input still pauses the rebuild. Recovery retention, cleanup and generation eligibility follow the constraints under Manifest-baseline merge below.
+**Active vs target, and the switch.** The v3 serving lock records metadata mode or a certified ACTIVE dense generation (model, dimension, recipe, collection). `embeddingEnabled:false` makes payload sync/writes and keyword/filter search provider-free; semantic requests fall back with `requested_mode`, `effective_mode` and `embedding_degraded`. Result rows expose current/stale/missing/unknown embedding status, so old vectors never imply fresh content. Existing no-lock collections preserve unknown vectors in metadata mode without inferring a model. Dense work uses the certified active generation. The configured `embeddingModelId`/`embeddingDimension` are the TARGET; a target that differs is a pending switch the admin Vector section shows with a sampled estimate — nothing switches by itself. The switch is a generation rebuild (`health/collection` `rebuild-generation`): the target re-embeds eligible points from their stored text into a new collection while the old one keeps serving, every write that lands meanwhile is mirrored onto it, and the swap moves the lock one generation on — `brain://` content and version history survive, and the dimension may change freely. It can be cancelled (the shadow is dropped, nothing else changes) and resumed after a restart (a restart pauses it). Separately, `sources/reindex` with `force` re-embeds a file, a folder or a source with the ACTIVE model, estimate first — an unchanged file keeps its payload (`updatedAt`, version history), so a re-embed never reads as an edit. Already recovery-only points with unavailable input retain their complete payload without vectors in the target; verified available input restores ordinary embedding. Unmarked missing input still pauses the rebuild. Recovery retention, cleanup and generation eligibility follow the constraints under Manifest-baseline merge below.
 
-**Media — images, PDFs, video, audio.** With a multimodal ACTIVE model (`gemini-embedding-2` or `voyage-multimodal-3.5` — the registry `modalities` as far as the model's client can send them: an operator endpoint speaks the text-only `/v1/embeddings` wire, so its row's declared media modalities are kept but not embedded) the sync embeds media files from their BYTES: an image is one point, a PDF is embedded page by page through the connector's PDF renderer (the document point carries page 1, pages 2..`brainSyncMaxPdfPages` are page chunks), each point marked `modality` and carrying no stored bytes — a rebuild or a forced re-embed reads the source again. Each source chooses the kinds in its sync settings (`sync.media`): images and PDFs on, video and audio off by default; `brainSyncMaxMediaMb` bounds one file, and a kind switched off is purged by the next full pass. A text-only active model embeds no media file, and the source's last-sync line says how many it left out. Invoked PNG inputs receive bounded structural signature/chunk/CRC checks before provider work; an invalid skip preserves existing indexed and recovery payloads and is counted separately. This preflight does not decode pixels. A semantic search returns media hits with their `modality` (and a PDF's `page`); full-text search never matches them, they carry no text.
+**Media — images, PDFs, video, audio.** With a multimodal ACTIVE model (`gemini-embedding-2` or `voyage-multimodal-3.5` — the registry `modalities` as far as the model's client can send them: an operator endpoint speaks the text-only `/v1/embeddings` wire, so its row's declared media modalities are kept but not embedded) the sync embeds media files from their BYTES: an image is one point, a PDF is embedded page by page through the connector's PDF renderer (the document point carries page 1, pages 2..`brainSyncMaxPdfPages` are page chunks), each point marked `modality` and carrying no stored bytes — a rebuild or a forced re-embed reads the source again. Each source chooses the kinds in its sync settings (`sync.media`): images and PDFs on, video and audio off by default; `brainSyncMaxMediaMb` bounds one file, and a kind switched off is purged by the next full pass. A text-only model or disabled embedding still indexes enabled media metadata and PDF page inventory without provider calls, reporting embedding debt; it never invents OCR text or semantic vectors. Invoked PNG inputs receive bounded structural signature/chunk/CRC checks before provider work; an invalid skip preserves existing indexed and recovery payloads and is counted separately. This preflight does not decode pixels. A semantic search returns media hits with their `modality` (and a PDF's `page`); full-text search never matches them, they carry no text.
 
-**Embedding spend.** Every priced or keyed embed call leaves one row in `<appRoot>/data/brain-core/embedding-usage.jsonl` (`{ts, model, tokens, estUsd, calls}`; an unpriced model is counted, never priced) and adds to today's aggregate the Vector section shows; `embeddingDailyUsdCap` (0 = off) stops embedding for the rest of the UTC day once reached — sync pauses with one resumable error, semantic search falls back to full-text.
+**Embedding spend.** Every priced or keyed embed call leaves one row in `<appRoot>/data/brain-core/embedding-usage.jsonl` (`{ts, model, tokens, estUsd, calls}`; an unpriced model is counted, never priced) and adds to today's aggregate the Vector section shows; `embeddingDailyUsdCap` (0 = off) stops embedding for the rest of the UTC day once reached — payload sync continues with embedding debt and stops later provider calls for that job; semantic search falls back to full-text.
 
 **Credential-use limits (v1).** Embedding spend is governed by the platform's per-credential
 calls/period rules through `embeddings/usageGate.ts`: brain-core's `init` stashes the
@@ -934,13 +935,12 @@ batch that splits into several posts counts one use per post. This per-call hook
 REAL enforcement for the embed class (not telemetry): the key is construction-captured and
 `LazyEmbedder` memoizes the client, so the host's resolve-time counter sees roughly one
 grant per process. A deny throws the typed `CredentialUseLimitedError`
-(`code: 'credential_use_limited'`): **sync** breaks its per-file loop with one resumable
-`CREDENTIAL_USE_LIMITED` job error (the scheduler re-enqueues next tick; content-hash skip
-makes the retry cheap; there is no backoff — a denied source fail-fasts every tick),
+(`code: 'credential_use_limited'`): **sync** continues payload indexing and records
+`embeddingDegraded`; later provider calls in that job stop, while already running calls finish,
 **semantic search** soft-degrades to the full-text filter search with a `warning` on the
 response envelope — as it does for the embedding daily cap, a missing `embedding.*` key
 (`EmbeddingCredentialMissingError`) and an active model the platform no longer defines;
-every OTHER embed error keeps its propagate-don't-mask behavior.
+Typed provider/network/timeout/quota unavailability degrades; validation, parse and local authorization errors propagate before the payload lands, storage errors propagate, and after the durable payload every embedding error — typed or not — is named debt in the answer (`usage.metadata.embeddingDeferred`), never a failed write. A sync against an out-of-credit embedder COMPLETES with `lastSyncResult.embeddingDegraded` (at most the concurrency's worth of provider calls, then no more that job) and writes its checkpoint, so the source is not due again until its own interval; only the embedding-only pass pauses, with the reason.
 
 since 2026-08-18 the search degrade covers a SECOND typed code:
 `ProviderQuotaExhaustedError` (`code: 'provider_quota_exhausted'`,
@@ -950,7 +950,7 @@ thrown immediately instead of burning the retry budget on a wait that cannot hel
 semantic search answers from full-text rather than a 500. The classification **fails toward
 retryable** — an unparseable or unrecognised body keeps the old backoff, because an
 OpenAI-compatible custom `baseUrl` may return anything — and a genuine, retry-exhausted rate
-limit still propagates, because masking that would hide a real outage. Every degrade code lives on
+limit becomes typed availability after its retry budget, retaining the safe degraded reason. Every degrade code lives on
 the USE-CASE, so the `fs_search` tool inherits it, not just the route.
 Deterministic/Ollama models carry no credential and are never gated. Rules are set on the
 admin Credentials tab (exact-id). The `embedding.*` keys are ordinary counted credentials —
@@ -973,9 +973,9 @@ There is intentionally no README inside the contribution folders; this section i
 - `start(state)` begins the background vector activity watch (`startQdrantWatch` wires `usecases/vectorActivityWatch.ts`, every `brainQdrantWatchIntervalMs` — 30 s — `BRAIN_INFRA_MODE=local` only). The vector backend wired at init is **not** hot-swapped (out of scope); the watch surfaces a degraded flag and logs transitions — `vector.qdrant.lost` and `vector.qdrant.recovered` (the latter notes that a restart re-enables Qdrant-backed search when the wired backend is in-memory). While Qdrant is reachable the same tick reads the server's optimizer tracker (one `GET /collections/<c>/optimizations?with=completed`, at most 50 finished runs) — Qdrant does not log its own background optimization — and writes `vector.optimizer.completed {optimizer, status, points, segments, durationMs}` once per finished run (the SERVER's start/finish times, so a run shorter than the tick is not lost), `vector.optimizer.long` once for a run still going after 10 minutes, and `vector.optimizer.overflow {returned}` when every returned run is new while earlier ones were seen (the tracker rolled past runs between two reads). The first read only seeds: runs finished before the process started are not re-logged at every boot. These lines go to the console (`docker logs`) AND `vector.jsonl`; the per-probe `vector.qdrant.health` line stays file-only. The lifecycle `health(state)` returns structured backend/connectivity checks to the generic runtime health aggregate; no vector-status package API is exposed. The interval is cleared in `stop()`.
 - `onBootstrapComplete(state, ctx: BootstrapCompleteContext)` is the single deferred-wiring entry point: it reads the published registries through `ctx.platform.connectorRegistries()` and starts the `SyncScheduler` from `ctx.platform.hostIdentity()`. The factory resolves those registries lazily through its init context. There are no imperative setters (`setHostIdentity`, `setConnectorRegistries`).
 - `init` delegates to `wiring.buildBrainState`, wiring the declared `ctx.config` reader and GLOBAL-only `ctx.credentials.resolveCredential` into the embedding provider before shared infrastructure is built. Platform facts are read lazily through `ctx.platform`; no config setter or source-running bootstrap push is exposed. Credential changes reach the bounded lifecycle hook, and runtime health reads structured vector checks.
-- **Data formats.** brain-core's three durable record kinds — `brain-core/embedding-lock` (v2), `brain-core/source-config` (v1) and `brain-core/pending-changes` (v1, the `_pending/changes.jsonl` journal) — are declared on the kernel's data-format ledger at module load (`src/store/dataFormats.ts`) and claimed at the top of `init`, before the first read: a kind a newer binary raised stops the init by name. Per record, the lock's `version` and a source config's or pending change's `formatVersion` (absent = 1) are checked before every rewrite — a newer record is never rewritten (the journal's appends stay open; its compaction refuses). Source configs are written durably, and one that fails validation is skipped AND logged (`source-config.invalid-skipped`), never silently gone.
+- **Data formats.** brain-core's three durable record kinds — `brain-core/embedding-lock` (v3), `brain-core/source-config` (v2) and `brain-core/pending-changes` (v1, the `_pending/changes.jsonl` journal) — are declared on the kernel's data-format ledger at module load (`src/store/dataFormats.ts`) and claimed at the top of `init`, before the first read: a kind a newer binary raised stops the init by name. Per record, the lock's `version` and a source config's or pending change's `formatVersion` (absent = 1) are checked before every rewrite — the check reads the STORED record, never the incoming one, so a config built fresh over a newer file is refused too — and a newer record is never rewritten (the journal's appends stay open; its compaction refuses). Every source-config write stamps the declared version (`SOURCE_CONFIG_FORMAT.version`, 2); an identical re-upsert still writes nothing. `embedding-lock` v3 and `source-config` v2 are `upgrade: offline` kinds: the app refuses to start over older data naming `neuralis upgrade`, which raises them (`scripts/embeddingLockV3.ts`, exported as `@neuralis/brain-core/upgrade`). Source configs are written durably, and one that fails validation is skipped AND logged (`source-config.invalid-skipped`), never silently gone.
 - **Declared credentials + dead-sweep.** brain-core's manifest declares the four embedding credentials — `embedding.openai`, `embedding.gemini`, `embedding.qwen`, `embedding.voyage` — in `neuralis.credentials[]` (`category: 'vector'`), so they appear in the admin catalog for an owner to set; an operator endpoint's `embedding.endpoint.<id>` is a dynamic family, never declared. `qdrant.apiKey` is deliberately NOT declared: `getQdrantClient()` is synchronous and boot-critical, so it structurally cannot read the credential store; the value comes from `QDRANT_API_KEY` in the boot env (Qdrant is infrastructure topology, not a per-scope secret — see `src/config/README.md`; setup writes the line itself and the server enforces the key on every request, with a mismatch surfacing as the structured `vector.qdrant.unauthorized` log line + a degraded Vector tab, not a boot death). `src/config/env.ts` was swept of dead credential plumbing: the old `resolveCredential()` helper, `BRAIN_CREDENTIAL_MAP`, and the `s3.*` / `media.apiKey` env reads (declared nowhere, consumed nowhere) are all removed. Only `getNeuralisEnv().qdrant.*` (URL/apiKey/collection — boot-critical infra topology from `process.env`) and the registry-driven embedding resolvers remain.
-- **Declared config settings.** brain-core's manifest declares its **78** platform-config keys in `neuralis.configSettings[]` (`PackageConfigSetting[]`) — sync/scan/chunking/media/git-panel/watch-recovery/vector-maintenance/vector-write-retry/pending-orphan-probe/search caps and timeouts across three categories: `brain` (72 keys), `vector` (5) and `debug` (1). (Re-count the manifest array before quoting this; it has been stale before.) The originals: the `brain` category (`brainAutoSyncMode`, `brainMaxScanFiles`, `inlineVideoMaxMb`, `brainSyncConcurrency`, `brainOllamaEmbedConcurrency`, `brainDebug` — `brainEmbedConcurrency` was DELETED: every embedder implements `embedBatch`, so the only fan-out fallback was dead code), the `vector` category (`embeddingModelId`, `embeddingDimension`, `ollamaUrl`, `openaiBaseUrl`, and `embeddingEndpoints` — written only through the host's endpoint route — rendered by the admin Vector tab, not the flat list), the embedding keys in `brain` (`qwenEmbeddingBaseUrl`, `embeddingDailyUsdCap`, `vectorKeepPreviousGeneration`), the media lane's `brainSyncMaxMediaMb` and `brainSyncMaxPdfPages`, and the `debug` category (`brainVectorLogConsole` — the stdout tee described under Observability below). The host registers them into `PlatformConfigStore` at bootstrap via the agent-core collector (first-party trust-gated); values reach brain-core through the injected `BrainConfigProvider`; the shared `getBrainConfigNumber(key, env, default)` live reader (config/env.ts) backs `brainSyncConcurrency` (DeltaSyncRunner) and `brainOllamaEmbedConcurrency` (the OllamaEmbedder semaphore, embeddings/factory.ts — applies on restart/embedder rebuild). The agent-core `configDeclarationDrift` test pins brain-core's consumed ⊆ declared set bidirectionally.
+- **Declared config settings.** brain-core's manifest declares its **84** platform-config keys in `neuralis.configSettings[]` (`PackageConfigSetting[]`) — sync/scan/chunking/media/binary-sniff/git-panel/watch-recovery/vector-maintenance/vector-write-retry/pending-orphan-probe/search caps and timeouts across three categories: `brain` (78 keys), `vector` (5) and `debug` (1). (Re-count the manifest array before quoting this; it has been stale before.) The originals: the `brain` category (`brainAutoSyncMode`, `brainMaxScanFiles`, `inlineVideoMaxMb`, `brainSyncConcurrency`, `brainOllamaEmbedConcurrency`, `brainDebug` — `brainEmbedConcurrency` was DELETED: every embedder implements `embedBatch`, so the only fan-out fallback was dead code), the `vector` category (`embeddingModelId`, `embeddingDimension`, `ollamaUrl`, `openaiBaseUrl`, and `embeddingEndpoints` — written only through the host's endpoint route — rendered by the admin Vector tab, not the flat list), the embedding keys in `brain` (`embeddingEnabled`, `embeddingRequestTimeoutMs`, `qwenEmbeddingBaseUrl`, `embeddingDailyUsdCap`, `vectorKeepPreviousGeneration`), the media lane's `brainSyncMaxMediaMb` and `brainSyncMaxPdfPages`, and the `debug` category (`brainVectorLogConsole` — the stdout tee described under Observability below). The host registers them into `PlatformConfigStore` at bootstrap via the agent-core collector (first-party trust-gated); values reach brain-core through the injected `BrainConfigProvider`; the shared `getBrainConfigNumber(key, env, default)` live reader (config/env.ts) backs `brainSyncConcurrency` (DeltaSyncRunner) and `brainOllamaEmbedConcurrency` (the OllamaEmbedder semaphore, embeddings/factory.ts — applies on restart/embedder rebuild). The agent-core `configDeclarationDrift` test pins brain-core's consumed ⊆ declared set bidirectionally.
 - The `CommunityInfraFactory` uses the kernel’s bounded `ProjectServiceFactory` internally. Routes and tools resolve services via `state.infraFactory.getServices(projectId)` — no global default-project state.
 - Source connectors are declared in package manifests via `neuralis.connectors[]`. Connector **kinds** register into the host's `SourceKindRegistry` at boot (the factory templates); Brain-core itself contributes the built-in `local` and `brain` kinds via `LocalDiskConnector` and `BrainInternalConnector`. Connector **instances** are bound PER PROJECT — `buildCommunityFilesystemInfra` constructs a fresh `ConnectorRegistry` inside each project's `FilesystemInfra` and `registerForSource`s that project's source slugs into it. Two projects with the same local slugs (`data`/`packages`/`brain`/`app`) therefore never collide; the previously-shared host registry was last-writer-wins and leaked one tenant's filesystem (and poisoned the shared vector index) into another. The host-shared registry handed in at bootstrap is retained only as the boot-readiness gate, no longer a source-binding store.
 - Brain-core declares **no hooks**. The former `hooks.json` / `host.ts` `onFileCreated` / `onFileModified` PostToolUse callbacks were deleted: they were intentional no-ops (the create/modify use cases update the vector index inline), and their registration produced a noisy `[hooks] Callback resolution failed` warning whenever `dist/src/host.js` drifted. The `./host` package export was removed with them.
@@ -1094,16 +1094,7 @@ URI the same way it ingests `machine_use screenshot`.
   rather than as a re-resolvable `ref{uri}` — re-reading the `.pdf` uri on
   replay would re-render non-deterministically (or, with rendering off,
   return text → an empty image → a provider 400).
-- **Capability gate (default emit).** `readFilesUseCase` attaches a
-  vision block whenever the connector returns `bytes`. It degrades the
-  file to a marker only when the runtime EXPLICITLY declares the matching
-  capability disabled — `runtime.modelCapabilities.imageInput === false`
-  or `videoInput === false`. Absent / partial `modelCapabilities`
-  (programmatic callers, agent-core boundaries that don't snapshot the
-  model registry) still emit the block; provider adapters that cannot
-  accept it strip it at adapter time. The explicit-deny marker reads
-  `[image/png 248 KB — imageInput disabled for this turn]`. This matches
-  the `machine_use screenshot` semantics (unconditional emit).
+- **Unconditional producer.** `readFilesUseCase` emits media whenever the connector supplies bytes and a recognized media MIME. Both direct-URI and indexed reads use the existing binary-extension table when a byte-bearing connector omits MIME. Unknown valid UTF-8 remains text; invalid UTF-8 and opaque files keep their source URI and an honest marker. Upload/write paths preserve original bytes. The agent-core per-step delivery boundary alone decides model acceptance, image integrity and explicitly declared subtype limits; converters only translate shapes.
 - **Per-batch budget.** The use-case sums approximate decoded sizes of
   every attached block; once the running total crosses 12 MB, remaining
   blocks downgrade to a `[batch image budget exceeded — request fewer
@@ -1339,7 +1330,7 @@ the package-manager content stores — `node_modules`, `.pnpm-store`, `.yarn/cac
 root and nested — because an in-container `pnpm install` on a bind-mounted
 repository lands `.pnpm-store/` at the repo root (5 124 files on one mounted
 package, 2026-08-27), and a source's `sync.exclude` is ADDITIVE over this floor,
-so every existing source inherits a new floor entry at its next sync. Pattern/media exclusions remove obsolete parent/chunk search data. Recovery-bearing parents — pending/deleted records, saved baselines and sole-copy `brain://` content — retain their complete payload with `recovery_only:true`, no embedding stamp and no dense or BM25 vectors. Retrieval, browsing and review remain policy-gated; search, enrichment and source-package discovery exclude retained recovery points. Re-inclusion produces a real new embedding before clearing the marker. Enabled/auto inactivity never purges an index, and an immutable READ floor alone never authorizes cleanup. Generation rebuilding classifies current source policy before provider work and again at its config-coordinated swap: unknown provenance or unavailable/invalid configuration pauses without swapping. The dollar estimate samples only eligible content and exposes protected/excluded/unresolved counts; it remains a range, not a hard spending bound. Full sync runs this cleanup at its existing end; targeted sync never purges.
+so every existing source inherits a new floor entry at its next sync. Pattern/media exclusions remove obsolete parent/chunk search data. Recovery-bearing parents — pending/deleted records, saved baselines and sole-copy `brain://` content — retain their complete payload with `recovery_only:true`, no embedding stamp and no dense or BM25 vectors. Retrieval, browsing and review remain policy-gated; search, enrichment and source-package discovery exclude retained recovery points. Verified source input permits ordinary payload indexing again; missing/stale embedding debt remains explicit until real dense completion. Enabled/auto inactivity never purges an index, and an immutable READ floor alone never authorizes cleanup. Generation rebuilding classifies current source policy before provider work and again at its config-coordinated swap: unknown provenance or unavailable/invalid configuration pauses without swapping. The dollar estimate samples only eligible content and exposes protected/excluded/unresolved counts; it remains a range, not a hard spending bound. Full sync runs this cleanup at its existing end; targeted sync never purges.
 
 **The READ FLOOR is the INDEX FLOOR.** Since 2026-08-05 the immutable `floor: true`
 rows govern a THIRD axis: `isUriSyncIndexable` evaluates them alongside the
@@ -1501,7 +1492,7 @@ ADD gate remain AUTHORITATIVE for both families; a declaration's
 `visibility.seeRequires` is defense-in-depth, unioned into the SEE filter, never
 the boundary.
 
-The package declares the optional singleton `package-source-roots` service, delegating to its existing source-root enumerator with scope, enabled state and package-recognition flags intact. Project infrastructure uses the loader's bounded project factory; running jobs and event subscriptions pin the same infrastructure through idle eviction. Permanent purge fences new queue work and waits for existing writes before vector deletion, subscription disposal and cache invalidation. Shutdown `drain` stops background admission and awaits completion bookkeeping under the runtime bound.
+The package declares the optional singleton `package-source-roots` service, delegating to its existing source-root enumerator with scope, enabled state and package-recognition flags intact, plus a change subscription off the one source-config commit funnel. Project infrastructure uses the loader's bounded project factory; running jobs and event subscriptions pin the same infrastructure through idle eviction. Permanent purge fences new queue work and waits for existing writes before vector deletion, subscription disposal and cache invalidation. Shutdown `drain` stops background admission and awaits completion bookkeeping under the runtime bound.
 
 ## Gotchas
 
@@ -1509,7 +1500,7 @@ The package declares the optional singleton `package-source-roots` service, dele
 - `FilePresence` is per-node: `brain` (vector-only), `synced` (index + connector agree), `unindexed` (on-disk but not yet indexed), `stale_indexed` (in index but no longer on connector). `fs_list` emits a single-character glyph (`●` / `○` / `✗`) only when a child's presence differs from its parent.
 - `fs_read` and `fs_list` are **connector-first**: they take live data (and, for `fs_list`, the tree structure) from the connector even when the vector index is cold or unreachable, and reconcile presence by a targeted index lookup over exactly the listed URIs. Consequence: the live-merge `fs_list` tree shows `brain` / `synced` / `unindexed` only — `stale_indexed` appears in the `only_indexed:true` view, on the source registry's `indexed_count` vs `on_disk` drift, and on a per-source connector failure (the broken source's indexed slice is surfaced as `stale_indexed`). See `src/usecases/README.md` for the phase/budget model. `fs_search` in `semantic` / `filter` modes requires the index to be warm; `grep` mode bypasses the index entirely and runs ripgrep / git grep / grep over the live connector. The keyword surface (filter mode + the hybrid text prefetch) rides the `content` full-text payload index (word tokenizer, lowercase, max token 255 — the Lucene/ES convention; the whole content is indexed, only over-length junk tokens are skipped) — `ensurePayloadIndexes` RECONCILES a drifted text index (param mismatch or missing params → delete + recreate) instead of no-opping on "already exists", so a legacy case-sensitive index heals on the first vector op after deploy. Search failures surface as fixed client-safe error rows with `count.errors` (backend detail is server-logged only). `fs_search` now enforces the per-uri `read` policy on every result across all three modes (closing the prior gap where it only feature-gated) — so a `read:false` path is never search-visible, and `grep` is the uri-policy-gated path to literal search without `execute`/shell.
 - Source slugs are URI schemes. Scoped clones use distinct schemes (`machine-alice://`, `local-bob://`) — never reuse a slug across scopes.
-- The embedding lock (`src/embeddings/lock.ts`, `~/.neuralis/app/config/embedding-lock.json`) records the ACTIVE model and dimension; changing `embeddingModelId`/`embeddingDimension` only sets the target, and the switch is the generation rebuild — never a silent re-point, never a reset. `QDRANT_COLLECTION_DIMENSION_MISMATCH` (`src/vector/QdrantVectorIndex.ts`) still fires when the live collection's vector size disagrees with the lock. **`pnpm reset:vector`** drops every collection AND the lock — and with them the `brain://` content and its version history, which live only in Qdrant; it is the last resort, not the model switch. Config resolution (`src/config/env.ts`, surfaced through the embedder factory) throws `EMBEDDING_CREDENTIAL_MISSING` / `UNSUPPORTED_EMBEDDING_DIMENSION` instead of silently falling back to a different provider, dimension or key.
+- The v3 embedding lock (`src/embeddings/lock.ts`, `~/.neuralis/app/config/embedding-lock.json`) records metadata serving or the certified ACTIVE model and dimension; changing `embeddingModelId`/`embeddingDimension` only sets the target, and the switch is the generation rebuild — never a silent re-point, never a reset. `QDRANT_COLLECTION_DIMENSION_MISMATCH` (`src/vector/QdrantVectorIndex.ts`) still fires when the live collection's vector size disagrees with the lock. The explicit `dense-clear` collection action removes only dense embeddings, preserving text/payload/history and leaving durable catchup debt. **`pnpm reset:vector`** requires proven offline quiescence and drops owned collections AND the lock only after all selected deletions succeed — and with them the `brain://` content and its version history, which live only in Qdrant; it is the last resort, not the model switch. Config resolution (`src/config/env.ts`, surfaced through the embedder factory) throws `EMBEDDING_CREDENTIAL_MISSING` / `UNSUPPORTED_EMBEDDING_DIMENSION` instead of silently falling back to a different provider, dimension or key.
 - Every write snapshots `version.baseline` on the node, enabling `fs_write {revert:true}` (1-level undo) without an external embedder. The chain is the recovery contract — the policy layer does not consult a separate `getMutationSafety` resolver.
 - A write's success response also surfaces `version: { diff: { added, removed }, changedAt? }` (real previous-vs-next line delta from `computeLineChangeStats`, not an input estimate). The `filesystem.change` card and the chat composer's Changes & Actions panel consume this directly so the `+N/-M` badge stays accurate even for `replace_text` where the find/replace fragments don't equal the actual line change.
 - `commitWrite` (`usecases/write/commit.ts`) orders the slow phases so a write pays the least it can, and **every step of that order is an invariant** — the full rule, with its degrade matrix, lives in `src/usecases/README.md` and is stated there alone.

package/app/cards/DiffView.tsx

@@ -72,12 +72,14 @@ export const DiffView = memo(
 
     return (
       <div className="font-mono text-[11px] leading-[18px] overflow-x-auto overflow-y-clip">
-        {elements}
-        {truncated && (
-          <div className="text-[10px] text-white/40 bg-white/4 px-3 py-1 text-center">
-            ··· {hunks.reduce((n, h) => n + h.lines.length, 0) - maxLines} more lines ···
-          </div>
-        )}
+        <div className="min-w-full w-max">
+          {elements}
+          {truncated && (
+            <div className="w-full text-[10px] text-white/40 bg-white/4 px-3 py-1 text-center">
+              ··· {hunks.reduce((n, h) => n + h.lines.length, 0) - maxLines} more lines ···
+            </div>
+          )}
+        </div>
       </div>
     );
   },
@@ -111,7 +113,7 @@ export const DiffView = memo(
 
 function SkippedLines({ label }: { label: string }) {
   return (
-    <div className="text-[10px] text-white/35 bg-white/[0.03] px-3 py-0.5 text-center border-y border-white/6 select-none">
+    <div className="w-full text-[10px] text-white/35 bg-white/[0.03] px-3 py-0.5 text-center border-y border-white/6 select-none">
       {label}
     </div>
   );

package/app/cards/README.md

@@ -17,7 +17,7 @@ Filesystem agent-card: an IDE-style diff view rendered for `fs_write` tool calls
 - `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".
 - `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. **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).
+- `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`.
 - 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).
 

package/app/cards/diffLine.tsx

@@ -34,11 +34,9 @@ export const DiffLineRow = memo(function DiffLineRow({
   type: DiffLineType;
   content: string;
 }) {
-  // `min-w-full w-max`: the row is at least the container width (full-bleed
-  // green/red background) and grows with long lines so the parent's
-  // `overflow-x-auto` scrolls horizontally instead of clipping.
+  // Every row fills the shared content width, including space beyond shorter lines.
   return (
-    <div className={`flex h-[18px] min-w-full w-max ${DIFF_LINE_BG[type]}`}>
+    <div className={`flex h-[18px] w-full ${DIFF_LINE_BG[type]}`}>
       <span className="shrink-0 w-10 text-right pr-2 select-none text-white/25 tabular-nums">
         {lineNo ?? ''}
       </span>

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.
+`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.
 
 ## Open-to-file tree hydration
 

package/app/filesystem/api/index.ts

@@ -1191,12 +1191,20 @@ function normalizeReembedEstimate(raw: unknown): ReembedEstimate | null {
 }
 
 /**
- * Estimate a forced re-embed of the scope. The route answers BEFORE it touches
- * the queue or the source's sync markers — an estimate has no side effect.
+ * `reembed` = every file in scope again (`force`); `pending` = only the files
+ * whose semantic embedding is missing or stale (`embeddingOnly`, the debt pass).
  */
-export async function estimateReembed(params: ReembedScope): Promise<ReembedEstimate | null> {
+export type ReembedKind = 'reembed' | 'pending';
+const reembedVerb = (kind: ReembedKind) => (kind === 'pending' ? { embeddingOnly: true } : { force: true });
+
+/**
+ * Estimate the scope. The route answers BEFORE it touches the queue or the
+ * source's sync markers — an estimate has no side effect. For `pending` the
+ * figures are an upper bound: the whole scope, of which only the owed part runs.
+ */
+export async function estimateReembed(params: ReembedScope, kind: ReembedKind = 'reembed'): Promise<ReembedEstimate | null> {
   return normalizeReembedEstimate(
-    await (await api()).post<unknown>('sources/reindex', { ...params, force: true, estimate: true }),
+    await (await api()).post<unknown>('sources/reindex', { ...params, ...reembedVerb(kind), estimate: true }),
   );
 }
 
@@ -1207,8 +1215,9 @@ export async function estimateReembed(params: ReembedScope): Promise<ReembedEsti
  */
 export async function startReembed(
   params: ReembedScope,
+  kind: ReembedKind = 'reembed',
 ): Promise<{ documents: number | null; truncated: boolean; job: SyncJobSnapshotRecord | null }> {
-  const raw = await (await api()).post<Record<string, unknown> | null>('sources/reindex', { ...params, force: true });
+  const raw = await (await api()).post<Record<string, unknown> | null>('sources/reindex', { ...params, ...reembedVerb(kind) });
   const job = raw?.job && typeof raw.job === 'object' ? (raw.job as SyncJobSnapshotRecord) : null;
   return { documents: finiteOrNull(raw?.documents), truncated: raw?.truncated === true, job };
 }

package/app/filesystem/domain/types.ts

@@ -373,6 +373,10 @@ export interface SourceConfigRecord {
       error?: string;
       /** Media files the run did not embed, by reason — absent when none. */
       mediaSkipped?: { textOnlyModel: number; off: number; tooLarge: number; unavailable: number; invalid: number };
+      /** Why the run left semantic embedding owed (`disabled`, `quota`, …) — the data still landed. */
+      embeddingDegraded?: string[];
+      /** Binary files the run did not index as text — absent when none. */
+      binarySkipped?: number;
     };
   };
   last_updated?: string;
@@ -385,6 +389,8 @@ export interface SourceConfigRecord {
   orphan?: boolean;
   orphan_hint?: string | null;
   observed?: boolean;
+  /** The platform's LIVE semantic-embedding intent (`embeddingEnabled`), read per request — never a last pass's echo. */
+  embedding_enabled?: boolean;
   /** Server-evaluated source maintenance authority. */
   canMaintain?: boolean;
   owner?: { userId?: string; agentId?: string };
@@ -400,7 +406,7 @@ export interface SourceConfigRecord {
   /** Why `live === false` — fixed enum, mapped to a display string in the UI. */
   live_reason?: SourceLiveReason;
   /**
-   * R2b — local-kind source ALSO acts as a WASM-package source (additive to the
+   * R2b — local-kind source ALSO acts as a runtime package source (additive to the
    * default `_packages/` drop-zone). Owner/admin-effective to set; honored for
    * project AND user/agent scope (advertise isolation enforced downstream).
    */
@@ -456,7 +462,7 @@ export interface UpdateSourceConfigRequest {
    * the existing config, so disabling sync needs this explicit flag.
    */
   clearSync?: boolean;
-  /** R2b — toggle WASM-package recognition (owner/admin-effective, local-only). */
+  /** R2b — toggle runtime package recognition (owner/admin-effective, local-only). */
   recognizesPackages?: boolean;
 }
 
@@ -478,7 +484,7 @@ export interface CreateSourceRequest {
     /** Per-source override of the platform `brainMaxScanFiles` scan cap. */
     maxScanFiles?: number;
   };
-  /** R2b — create the (local-kind) source as a WASM-package source (owner/admin). */
+  /** R2b — create the (local-kind) source as a runtime package source (owner/admin). */
   recognizesPackages?: boolean;
 }
 
@@ -490,8 +496,8 @@ export interface CreateSourceRequest {
 export interface SyncJobSnapshotRecord {
   jobId: string;
   source: string;
-  mode: 'full' | 'targeted' | 'purge';
-  status: 'pending' | 'running' | 'completed' | 'failed' | 'cancelled';
+  mode: 'full' | 'targeted' | 'purge' | 'embedding';
+  status: 'pending' | 'running' | 'completed' | 'paused' | 'failed' | 'cancelled';
   userId: string;
   projectId: string;
   agentId: string;
@@ -508,6 +514,8 @@ export interface SyncJobSnapshotRecord {
     filesSkipped: number;
     durationMs: number;
     error?: string;
+    /** An embedding-only pass: what it embedded, and why it paused when it did. */
+    embedding?: { audited: number; embedded: number; settled: boolean; pausedReason?: string };
   };
   error?: string;
 }
@@ -626,9 +634,12 @@ export interface FileSystemState {
     chunk_end?: number;
     match_type?: 'semantic' | 'keyword' | 'hybrid';
     score?: number;
+    embedding_status?: string;
   }>;
   searchLoading: boolean;
   searchError?: string;
+  /** What the last search ran as when that differs from what was asked (`SearchEffect`). */
+  searchEffect: { requestedMode?: string; effectiveMode?: string; embeddingDegraded?: string; warning?: string };
   /**
    * `true` = enumerated by a successful listing and current · `false` = enumerated
    * once, then taken off screen by a collapse (no reconcile lists a hidden folder),
@@ -740,10 +751,18 @@ export type FSSearchResponse = {
     chunk_end?: number;
     match_type?: 'semantic' | 'keyword' | 'hybrid';
     version?: FileVersionInfo;
+    /** The point's dense proof: `current`, or why it is not (`missing` / `stale` / `unknown` / …). */
+    embedding_status?: string;
     error?: string;
   }>;
   count: { found: number; errors: number };
   usage?: { vectorQueries?: number; embeddingCalls?: number };
+  /** The mode asked for, and the one that ran — a semantic request runs as `filter` when embedding is unavailable. */
+  requested_mode?: 'semantic' | 'filter' | 'grep';
+  effective_mode?: 'semantic' | 'filter' | 'grep';
+  /** Why semantic search fell back (`disabled`, `quota`, `credentials`, …). */
+  embedding_degraded?: string;
+  warning?: string;
 };
 
 export type FSUploadResponse = {

package/app/filesystem/store/filesystemStore.ts

@@ -756,7 +756,7 @@ function evictColdSubtrees(
 }
 
 type FilesystemNavRef =
-  | { kind: 'filesystem'; action: string; uri?: string; query?: string; filter?: PendingPanelFilter }
+  | { kind: 'filesystem'; action: string; uri?: string; query?: string; filter?: PendingPanelFilter; source?: string }
   | undefined;
 
 
@@ -897,6 +897,14 @@ interface FilesystemStore extends FileSystemState, SearchSliceActions, ListSlice
    */
   pendingSourceSuggestion: DiscoverableSourceSuggestion | null;
   setPendingSourceSuggestion: (suggestion: DiscoverableSourceSuggestion | null) => void;
+  /**
+   * Is the Sources panel's Vector Health section open? In the STORE so a
+   * notification's `open-vector-health` nav can open it while the panel is not
+   * mounted; context data (a `contextResetPatch` key), never persisted. The
+   * section still mounts its panel only while open (no CSS-only collapse).
+   */
+  vectorHealthOpen: boolean;
+  setVectorHealthOpen: (open: boolean) => void;
   setWorkspacePanelOpen: (panel: WorkspacePanelId, open: boolean) => void;
   setActiveWorkspaceTab: (tab: 'file' | 'git-diff' | 'git-commit' | WorkspacePanelId) => void;
   diffViewMode: DiffViewMode;
@@ -1110,6 +1118,7 @@ export const useFilesystemStore = create<FilesystemStore>()(persist((set, get) =
   workspacePanels: { upload: false, sources: false, packages: false, pending: false },
   activeWorkspaceTab: 'file',
   pendingSourceSuggestion: null,
+  vectorHealthOpen: false,
   diffViewMode: 'auto',
   pendingPanelFilter: {},
   // Nothing is hydrated at boot. `brain://` is EXPANDED by default (below) and the
@@ -1180,6 +1189,7 @@ export const useFilesystemStore = create<FilesystemStore>()(persist((set, get) =
       return { workspacePanels: nextPanels, activeWorkspaceTab };
     }),
   setPendingSourceSuggestion: (suggestion) => set(() => ({ pendingSourceSuggestion: suggestion })),
+  setVectorHealthOpen: (open) => set(() => ({ vectorHealthOpen: open })),
   setActiveWorkspaceTab: (tab) => set(() => ({ activeWorkspaceTab: tab })),
   setDiffViewMode: (mode) => set(() => ({ diffViewMode: mode })),
   setPreviewEditorsEnabled: (enabled) => set(() => ({ previewEditorsEnabled: enabled })),
@@ -2217,6 +2227,15 @@ export const useFilesystemStore = create<FilesystemStore>()(persist((set, get) =
       get().setWorkspacePanelOpen('pending', true);
       return;
     }
+    // A notification's target: the Sources panel (a source's sync or embedding
+    // outcome), or its Vector Health section (an operator's collection action).
+    // Navigation only — the panel's own listing re-applies every gate.
+    if (action === 'open-sources' || action === 'open-vector-health') {
+      set(() => ({ activeAgentId: agentId, activeProjectId: projectId,
+        ...(action === 'open-vector-health' ? { vectorHealthOpen: true } : {}) }));
+      get().setWorkspacePanelOpen('sources', true);
+      return;
+    }
     if (action === 'list' && uri) {
       set((state) => {
         const root = sourceRootUri(uri);

package/app/filesystem/store/listSlice.ts

@@ -92,10 +92,12 @@ export function contextResetPatch(): Record<string, unknown> {
     // Sources panel must not survive an agent/project switch — the panel
     // would then prefill an Add-Source form for the PREVIOUS context.
     pendingSourceSuggestion: null,
+    vectorHealthOpen: false,
     searchQuery: '',
     searchResults: [],
     searchLoading: false,
     searchError: undefined,
+    searchEffect: {},
     // Git Control state resets with the context (gitViewMode — a UI
     // preference — intentionally persists, mirroring searchMode).
     gitStatus: null,

package/app/filesystem/store/searchSlice.ts

@@ -13,6 +13,16 @@ export type SearchSliceHit = {
   chunk_end?: number;
   match_type?: 'semantic' | 'keyword' | 'hybrid';
   score?: number;
+  /** `current`, or why the point's semantic embedding is not (`missing` / `stale` / …). */
+  embedding_status?: string;
+};
+
+/** What the last search ran as, when that differs from what was asked (or carries a warning). */
+export type SearchEffect = {
+  requestedMode?: string;
+  effectiveMode?: string;
+  embeddingDegraded?: string;
+  warning?: string;
 };
 
 /** UI search modes → wire `search_mode`: keyword→filter, semantic→semantic, grep→grep. */
@@ -39,6 +49,8 @@ export interface SearchSliceState {
   searchResults: SearchSliceHit[];
   searchLoading: boolean;
   searchError?: string;
+  /** Empty when the search ran as asked, with no warning. */
+  searchEffect: SearchEffect;
 }
 
 export interface SearchSliceActions {
@@ -66,6 +78,7 @@ export const searchSliceInitial: SearchSliceState = {
   searchResults: [],
   searchLoading: false,
   searchError: undefined,
+  searchEffect: {},
 };
 
 /** Grep needs a live-connector folder scope; brain:// has no live text to scan. */
@@ -94,6 +107,7 @@ export function createSearchSlice(
         searchResults: [],
         searchLoading: false,
         searchError: undefined,
+        searchEffect: {},
       })),
 
     async runSearch({ agentId, projectId }) {
@@ -108,7 +122,7 @@ export function createSearchSlice(
           ? query.length >= 2 || glob.length >= 2
           : query.length >= 2;
       if (!agentId || !runnable) {
-        set(() => ({ searchResults: [], searchLoading: false, searchError: undefined }));
+        set(() => ({ searchResults: [], searchLoading: false, searchError: undefined, searchEffect: {} }));
         return;
       }
 
@@ -127,6 +141,7 @@ export function createSearchSlice(
           searchResults: [],
           searchLoading: false,
           searchError: 'Grep needs a non-brain folder scope — select a folder in a disk-backed source.',
+          searchEffect: {},
         }));
         return;
       }
@@ -170,11 +185,18 @@ export function createSearchSlice(
             chunk_end: r.chunk_end,
             match_type: r.match_type,
             score: r.score,
+            ...(typeof r.embedding_status === 'string' ? { embedding_status: r.embedding_status } : {}),
           }));
         set(() => ({
           searchResults: hits,
           searchLoading: false,
           searchError: errorRow ? String((errorRow as any).error) : undefined,
+          searchEffect: {
+            ...(res.requested_mode ? { requestedMode: res.requested_mode } : {}),
+            ...(res.effective_mode ? { effectiveMode: res.effective_mode } : {}),
+            ...(res.embedding_degraded ? { embeddingDegraded: res.embedding_degraded } : {}),
+            ...(res.warning ? { warning: res.warning } : {}),
+          },
         }));
       } catch (error) {
         if (mySeq !== searchSeq) return;
@@ -182,6 +204,7 @@ export function createSearchSlice(
           searchResults: [],
           searchLoading: false,
           searchError: error instanceof Error ? error.message : 'Search failed',
+          searchEffect: {},
         }));
       }
     },