@neuralis/brain-core 0.2.1 → 0.3.1

package/README.md

@@ -68,6 +68,11 @@ occupancy answer is ONE primitive (`uriOccupied` in `usecases/write/occupancy.ts
 at any status ∪ the connector — the disk decides, never the user-scoped index alone). A HUMAN's
 structural op commits immediately; an AGENT's stays `pending_review` (the
 `interactive` marker — see `src/routes/README.md` + `app/filesystem/ui/README.md`).
+Pending pages expose visible-id continuation and complete/partial/restart state. Full
+projected vector reconstruction plus canonical URI twins occurs before slicing, so page
+size bounds output rather than scan cost. Journal retention defaults to 32 MiB; oversize
+journals rebuild per operation. Repair defaults to 50 visible records per batch with fresh
+per-record authorization.
 
 URI schemes you will see in production:
 
@@ -975,7 +980,7 @@ There is intentionally no README inside the contribution folders; this section i
 - `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` (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 **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.
+- **Declared config settings.** brain-core's manifest declares its **86** 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` (80 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.
@@ -1178,7 +1183,7 @@ a deletion; it declares `Allow: POST` (the host catch-all forwards route headers
 only on content-type-bearing responses, so it is not on the wire yet). The arm is
 fenced, not removed: a `drive.write` holder (manager tier and up) runs every
 action exactly as before, and the Vector Health panel already posts.
-`action:"repair-pending"` (dry-run first in the panel) works on the CALLER's own
+`action:"repair-pending"` (dry-run supported in the panel) works on the CALLER's own
 visible pending records, never the project scope: it counts orphaned and
 older unknown-original records and, applied, discards the orphans through the
 per-record discard (WRITE re-authorized per record); the unknown-original ones
@@ -1520,7 +1525,7 @@ the `execute action="skill"` + `execute action="shell"` pipeline:
 | `manage-sources` | `/sources/*` CRUD + sync / sync-status / cancel / reset / reindex / enabled lifecycle, scoped index purge, kind catalog, browse + discoverable roots (both `drive.mount`, not the skill's `drive.read` floor) | 17 |
 | `manage-files` | `/list`, `/search`, `/read`, `/raw`, `/create`, `/modify`, `/mkdir`, `/copy`, `/upload`, `/approve`, `/pending` (bulk; `fs_*` tools remain primary for one-offs). `/create` and `/upload` both use the write engine and `drive.write`; agent-origin uploads are journaled as pending review, while interactive human uploads land committed | 11 |
 | `manage-uri-policy` | `/policies/uri/*` — read manifests baselines, read effective merged policy, patch path rules. Reads are the route's `drive.read` module feature (every built-in role holds it); the patch escalates in-handler to `drive.policy` — a feature check, not a role-name check. Immutable `floor:true` rules (trusted-manifest-only) can't be created or removed here — the route answers `409 immutable_policy_floor`. | 3 |
-| `git` | `/git/*` — the same routes the Git Control panel drives. Reads: status / branch / diff / log / log-stats / commit / outgoing / show / repos. Writes: stage / unstage / discard, commit, branch / checkout, `restore`, and fetch / pull / push (uri-policy `exec` + connected remote). ONE generic `git.sh <GET\|POST> <route>` helper; also documents the raw-shell and external-GitHub-MCP git planes (a routes-based skill, NOT a `git_*` MCP bundle). **The helper takes its HTTP VERB as a positional argument, so the mutating half of the skill is invisible to anything that classifies an example by the SCRIPT FILE** — 10 of the 19 routes are POST writes, and the skill's write examples are marked `NOT DISPOSABLE` (git routes only act on an already-attached source; there is no throwaway repo) with point-of-use consequences for commit / checkout / pull / push | 1 |
+| `git` | `/git/*` — the same routes the Git Control panel drives. Reads: status / branch / diff / log / log-stats / commit / outgoing / show / repos. Writes: stage / unstage / discard, commit, branch / checkout, `restore`, and fetch / pull / push (uri-policy `exec` + connected remote). its routes taught as `neuralis request <METHOD> @neuralis/brain-core/git/<route>` lines; also documents the raw-shell and external-GitHub-MCP git planes (a routes-based skill, NOT a `git_*` MCP bundle). **The helper takes its HTTP VERB as a positional argument, so the mutating half of the skill is invisible to anything that classifies an example by the SCRIPT FILE** — 10 of the 19 routes are POST writes, and the skill's write examples are marked `NOT DISPOSABLE` (git routes only act on an already-attached source; there is no throwaway repo) with point-of-use consequences for commit / checkout / pull / push | 1 |
 
 `manage-uri-policy` migrated here from `@neuralis/agent-core` on
 2026-05-16 because the route lives in brain-core (`src/routes/policies.ts`)

package/app/filesystem/api/README.md

@@ -11,7 +11,7 @@ Typed client for brain-core package routes plus a small set of host-side helpers
 ## Public Surface
 
 - Filesystem (`index.ts`): `resolveList`, `fetchSourceCounts`, `readFiles`, `searchFiles`, `writeFile` (every write verb on the ONE `write` route) + `writeRefusalMessage`, `approveFileReview`, `uploadFile` (the multipart byte lane), `getRawFileUrl`, `checkVectorHealth` (cheap count-only stats), `scanVectorHealth` (expensive on-demand orphan/duplicate scan → `/health/scan`), `runHealthAction`.
-- Pending changes (`index.ts`): `listPendingChanges` (with `include_orphans` it returns `orphanIds` beside the rows, from the server's SAME listing pass — the panel needs both on every mount, and two calls ran the whole dual-source listing twice), `previewPendingChange` (authoritative current/baseline states and fingerprint), `revertPendingChange`, `scanOrphanedPending` (the orphaned subset alone; kept for callers that want only that), `discardPendingChange`, `dismissPendingChange`, `discardOrphanedPending`. Pending-backed approve/dismiss/revert carry the fresh `expectedFingerprint` and any required acknowledgement; a stale intent returns409. Types: `PendingChangeRecord`, `PendingChangesQuery`, `PendingPreview`, `PendingReviewIntent`.
+- Pending changes (`index.ts`): `listPendingChanges` (with `include_orphans` it returns `orphanIds` beside the rows, from the server's SAME listing pass — the panel needs both on every mount, and two calls ran the whole dual-source listing twice), `previewPendingChange` (authoritative current/baseline states and fingerprint), `revertPendingChange`, `scanOrphanedPending` (the complete scanned page in `changes`, its orphan subset in `orphans`, and the same continuation), `discardPendingChange`, `dismissPendingChange`, `discardOrphanedPending`. Pending-backed approve/dismiss/revert carry the fresh `expectedFingerprint` and any required acknowledgement; a stale intent returns409. Types: `PendingChangeRecord`, `PendingChangesQuery`, `PendingPreview`, `PendingReviewIntent`. Pending clients preserve the page envelope and URI/cursor filters; count returns `{count, exact, complete, partial}` and safe unavailable branches; the store preserves its previous count when both branches fail.
 - Git (`index.ts`) — the `/git/*` client behind the Git Control panel. Reads: `getGitRepos`, `getGitStatus`, `getGitBranches`, `getGitDiff`, `getGitLog`, `getGitLogStats`, `getGitCommitFiles`, `getGitOutgoing`, `getGitShow`. Writes: `stagePaths`, `unstagePaths`, `stageHunk`, `unstageHunk`, `discardPaths`, `commitGit`, `createGitBranch`, `deleteGitBranch`, `restoreGit`, `checkoutGitBranch`. Remote (uri-policy `exec`): `fetchGit`, `pullGit`, `pushGit`. Type: `GitRescue` — the typed carrier a destructive op returns and `restoreGit` echoes back.
 - Sources (`index.ts`): `listSourceConfigs`, `updateSourceConfig`, `createSource`, `deleteSource`, `triggerSourceSync`, `getSyncStatus`, `cancelSync`, `resetSync`, `reindexSource` ("Rescan changes"), `estimateReembed` / `startReembed` (the same route with a `folder` / `uri` scope and `force: true` — a re-embed with the active model; the estimate answers before any side effect, a scope with nothing readable queues nothing), `purgeSourceIndex` (source/folder/file estimate or apply; keeps source and recovery content), `getSourcesHealth`, `browseDirectories`, `listSourceKinds`, `getSourceKindSchema`, `setSourceEnabled` (W3K), `listDiscoverableSources` (W3E). Types: `ReembedScope`, `ReembedEstimate`, `SourceKindRecord`, `SourceKindSchema`, `ResolveListOpts`, `DiscoverableSourceSuggestion`.
 - Project packages (`projectPackages.ts`): `listProjectPackages`, `buildPackage`, `setPackageTrust`, `setPackageAccessFeature`, `getGrantableFeatureIds` (the per-project base-access governance pair — see `../ui/README.md`), `getPackagesDiagnostics` (W3F — also consumed by chat-config Packages Overview through the agent-core ports). Types: `ProjectPackageRow`, `BuildResponse`, `TrustValue`, `PackageDiagnosticEntry`, `PackagesDiagnosticsResponse`.

package/app/filesystem/api/index.ts

@@ -943,7 +943,8 @@ export async function approveFileReview(params: {
 // ---------------------------------------------------------------------------
 
 export type { PendingChangeRecord, PendingPreview, PendingReviewIntent } from '@neuralis/brain-core/domain/pending-change';
-import type { PendingChangeRecord, PendingPreview } from '@neuralis/brain-core/domain/pending-change';
+import type { PendingChangeRecord, PendingPreview, PendingChangePage, PendingCount, PendingRepairPage } from '@neuralis/brain-core/domain/pending-change';
+export type { PendingChangePage, PendingCount, PendingRepairPage } from '@neuralis/brain-core/domain/pending-change';
 
 export async function previewPendingChange(params: { agentId: string; projectId?: string; id: string }, client: PackageApi): Promise<PendingPreview> {
   const result = await client.post('pending', { ...params, action: 'preview' }) as { preview: PendingPreview };
@@ -951,6 +952,8 @@ export async function previewPendingChange(params: { agentId: string; projectId?
 }
 
 export type PendingChangesQuery = {
+  cursor?: string;
+  uri?: string;
   agentId: string;
   projectId?: string;
   userId?: string;
@@ -974,26 +977,24 @@ export type PendingChangesQuery = {
 export async function listPendingChanges(
   params: PendingChangesQuery,
   client: PackageApi,
-): Promise<{ ok: boolean; changes: PendingChangeRecord[]; orphanIds: string[] }> {
-  const res = await client.post('pending', params) as {
-    ok?: boolean; changes?: PendingChangeRecord[]; orphanIds?: string[];
-  };
-  return {
-    ok: res?.ok !== false,
-    changes: Array.isArray(res?.changes) ? res.changes : [],
-    orphanIds: Array.isArray(res?.orphanIds) ? res.orphanIds : [],
-  };
+): Promise<PendingChangePage & { ok: boolean }> {
+  const res = await client.post('pending', params) as PendingChangePage & { ok: boolean };
+  if (!Array.isArray(res.changes) || typeof res.complete !== 'boolean' || typeof res.partial !== 'boolean') {
+    throw new Error('Pending listing unavailable; retry the request');
+  }
+  return res;
 }
 
 /**
  * The caller's visible pending COUNT — the list's own per-record floor, no orphan
  * probe and no rows on the wire. Feeds the Changes badge.
  */
-export async function countPendingChanges(params: { agentId: string; projectId?: string }, client: PackageApi): Promise<number> {
+export async function countPendingChanges(params: { agentId: string; projectId?: string }, client: PackageApi): Promise<PendingCount> {
   const qs: Record<string, string> = { agentId: params.agentId, count_only: '1' };
   if (params.projectId) qs.projectId = params.projectId;
-  const res = await client.get('pending', qs) as { count?: number };
-  return typeof res?.count === 'number' ? res.count : 0;
+  const res = await client.get('pending', qs) as PendingCount;
+  if (!Number.isInteger(res.count) || res.count < 0 || typeof res.exact !== 'boolean') throw new Error('Pending count unavailable');
+  return res;
 }
 
 export async function revertPendingChange(params: {
@@ -1013,9 +1014,10 @@ export async function scanOrphanedPending(params: {
   agentId: string;
   projectId?: string;
   conversationId?: string;
-}, client: PackageApi): Promise<{ ok: boolean; orphans: PendingChangeRecord[] }> {
-  const res = await client.post('pending', { ...params, action: 'scan-orphans' }) as { ok?: boolean; orphans?: PendingChangeRecord[] };
-  return { ok: res?.ok !== false, orphans: Array.isArray(res?.orphans) ? res.orphans : [] };
+  cursor?: string;
+  uri?: string;
+}, client: PackageApi): Promise<PendingChangePage & { ok: boolean; orphans: PendingChangeRecord[] }> {
+  return client.post('pending', { ...params, action: 'scan-orphans' }) as Promise<PendingChangePage & { ok: boolean; orphans: PendingChangeRecord[] }>;
 }
 
 /** Discard ONE orphaned pending record (journal mark + blob + vector point) —
@@ -1042,15 +1044,12 @@ export async function dismissPendingChange(params: {
   return client.post('pending', { ...params, action: 'dismiss' }) as Promise<{ ok: boolean; id: string; uri?: string; error?: string; retryable?: boolean }>;
 }
 
-/** Bulk-discard every orphaned pending change the caller can write (the Repair
- * button). Returns the actual discarded count. */
+/** Repair one visible page through the shared owner; callers continue explicitly
+ * with nextCursor and pause on partial/failure. Counters describe actual effects. */
 export async function discardOrphanedPending(params: {
-  agentId: string;
-  projectId?: string;
-  conversationId?: string;
-}, client: PackageApi): Promise<{ ok: boolean; discarded: number }> {
-  const res = await client.post('pending', { ...params, action: 'discard-orphans' }) as { ok?: boolean; discarded?: number };
-  return { ok: res?.ok !== false, discarded: typeof res?.discarded === 'number' ? res.discarded : 0 };
+  agentId: string; projectId?: string; conversationId?: string; cursor?: string;
+}, client: PackageApi): Promise<PendingRepairPage> {
+  return client.post('pending', { ...params, action: 'discard-orphans' }) as Promise<PendingRepairPage>;
 }
 
 export function getRawFileUrl(agentId: string, uri: string, projectId?: string): string {
@@ -1088,6 +1087,7 @@ export async function runHealthAction(params: {
   action: 'gc' | 'repair-orphans' | 'deduplicate' | 'repair-pending';
   dryRun?: boolean;
   retentionHours?: number;
+  cursor?: string;
 }, client: PackageApi): Promise<Record<string, unknown>> {
   return client.post('health/gc', params);
 }

package/app/filesystem/store/README.md

@@ -16,7 +16,7 @@ Zustand stores powering the Files windows — ONE live store per window (file di
 
 - `reconcileSourceFolders({ agentId, projectId, source })` — re-lists ONE source's VISIBLE folders (its root + every loaded folder that is expanded AND whose every ancestor is expanded — a loaded folder under a collapsed ancestor is off screen and never a target) and applies absence semantics per **direct child** of a **non-truncated** listing: prune an `unindexed` external-only file, flip a tracked/`synced` file to `status:'deleted'` (struck-through and revertible, matching an in-platform delete), keep an existing tombstone, prune a folder when it parents nothing live — `presence` deliberately does NOT gate this: a folder has no pending record and no revert, so once it is gone from the listing there is nothing to preserve it for, and a `synced` folder left in place rendered with the ORDINARY tone, clearable only by a browser reload. A gone folder that still hosts revertible tombstones is KEPT but toned `deleted`, never left looking live. A **truncated** listing stays upsert-only (absence ≠ deletion).
 - `reconcileFolders({ agentId, projectId, folders })` — the same pass over specific folders. Every mutation tail uses it: a move/delete/paste knows exactly which parents changed. Targets that are not in `loadedFolders` are dropped and flag the source dirty; a STALE target (`false`) is dropped silently, because opening it re-lists it authoritatively. The list is grouped per source so the coalescer applies.
-- `refreshPendingCount({ agentId, projectId })` — re-reads `pendingCount` (the Changes badge) through `count_only`; a newer call or a context the store has left drops the answer (a same-context reset does not — the mount count must land), a failed count keeps the last number. `pendingCount` is a `contextResetPatch()` key.
+- `refreshPendingCount({ agentId, projectId })` — re-reads `pendingCount` (the Changes badge) through `count_only`; a newer call or a context the store has left drops the answer (a same-context reset does not — the mount count must land), a failed count keeps the last number. `pendingCount` is a `contextResetPatch()` key. The badge stores exact/partial/stale state; failed requests preserve the previous number as stale, and context reset clears its authority.
 - `refreshTree({ agentId, projectId })` — the toolbar Refresh: source summaries + an absence pass over every hydrated source. `refresh` is deliberately NOT rewritten in place — the Sources panel's `withCounts` calls depend on its loading semantics.
 
 Two guards make this safe against the races a plain re-list would lose:

package/app/filesystem/store/filesystemStore.ts

@@ -978,6 +978,7 @@ interface FilesystemStore extends FileSystemState, SearchSliceActions, ListSlice
   pendingReviewPaths: Set<string>;
   /** The caller's visible pending-review count (server `count_only`), shown on the Changes button. */
   pendingCount: number;
+  pendingCountState: 'exact' | 'partial' | 'stale';
   /** Re-read `pendingCount`; a newer call or another active context drops the answer. */
   refreshPendingCount: (params: { agentId: string; projectId: string | null }) => Promise<void>;
 
@@ -1194,6 +1195,7 @@ export function createFilesystemStore(init: FilesystemStoreInit): FilesystemStor
   snapshotError: undefined,
   pendingReviewPaths: new Set<string>(),
   pendingCount: 0,
+  pendingCountState: 'stale',
 
   ...searchSliceInitial,
   ...createSearchSlice(set as any, get),
@@ -1791,15 +1793,21 @@ export function createFilesystemStore(init: FilesystemStoreInit): FilesystemStor
     if (!agentId) return;
     const mine = ++fences.pendingCountSeq;
     // A failed count keeps the last known number — the next event, focus or reconnect re-asks.
-    let count: number;
-    try { count = await countPendingChanges({ agentId, ...(projectId ? { projectId } : {}) }, client); } catch { return; }
+    let count: Awaited<ReturnType<typeof countPendingChanges>>;
+    try { count = await countPendingChanges({ agentId, ...(projectId ? { projectId } : {}) }, client); } catch {
+      if (mine === fences.pendingCountSeq && get().activeAgentId === agentId && get().activeProjectId === projectId) set({ pendingCountState: 'stale' });
+      return;
+    }
     // No reset-epoch fence: the count is the context's own server answer, so one
     // that resolves after a reset of the SAME context is still right; the context
     // check below is what keeps another context's number out.
     if (mine !== fences.pendingCountSeq) return;
     const s = get();
     if (s.activeAgentId !== agentId || s.activeProjectId !== projectId) return;
-    set(() => ({ pendingCount: count }));
+    if (count.unavailable?.includes('journal') && count.unavailable.includes('vector')) {
+      set({ pendingCountState: 'stale' }); return;
+    }
+    set(() => ({ pendingCount: count.count, pendingCountState: count.exact ? 'exact' : 'partial' }));
   },
 
   async markFileDeleted({ agentId, projectId, node }) {

package/app/filesystem/store/listSlice.ts

@@ -76,6 +76,7 @@ export function contextResetPatch(): Record<string, unknown> {
     pendingReviewPaths: new Set<string>(),
     // The Changes badge count is the context's own server answer.
     pendingCount: 0,
+    pendingCountState: 'stale',
     // Nothing is pre-expanded — under lazy hydration an expanded entry is a
     // FETCH, and every source branch (including `brain://`) starts collapsed.
     expandedFolders: new Set<string>(),

package/app/filesystem/ui/FileEditor.tsx

@@ -21,6 +21,10 @@ import { getRawFileUrl, approveFileReview, writeFile, writeRefusalMessage, getGi
 import { InlineUploader } from './InlineUploader';
 import { SourcesPanel } from './SourcesPanel';
 import { PackagesPanel } from './PackagesPanel';
+import { PendingReviewDialog, type ReviewRequest, type ReviewAction } from './PendingReviewDialog';
+import { useVisibleDiffCards } from '../hooks/useVisibleDiffCards';
+import { normalizePolicyUri } from '@neuralis/package-system/policies';
+import { listPendingChanges } from '../api';
 import { PendingChangesPanel } from './PendingChangesPanel';
 import { getDeltaTone } from '../lib/treeVisualState';
 import { fileKeyFromNode, folderUri, hasCompletedRead, sourceFromUri, extractFilename, sourceRootUri } from '../store/helpers';
@@ -99,6 +103,7 @@ export function FileEditor() {
   const [reverting, setReverting] = useState(false);
   const [showDiff, setShowDiff] = useState(true);
   const [metaExpanded, setMetaExpanded] = useState(false);
+  const refreshPendingCount = useFilesystemStore((s) => s.refreshPendingCount);
   const filePrevByPath = useFilesystemStore((s) => s.filePrevByPath);
   const activePrev = activeFile ? filePrevByPath[activeFile] : undefined;
   const hasPendingChanges = !!activePrev && activeNode?.status === 'pending_review';
@@ -138,6 +143,31 @@ export function FileEditor() {
     !showUploadTab && !showSourcesTab && !showPackagesTab && !showPendingTab && !showGitDiff && !showGitCommit;
   const rawAgentId = activeNode?.sourceAgentId ?? agentId ?? undefined;
   const targetAgentId = activeNode?.sourceAgentId ?? agentId ?? null;
+  const reviewQueue = useVisibleDiffCards(null);
+  const [pendingReview, setPendingReview] = useState<ReviewRequest | null>(null);
+  const [pendingReviewError, setPendingReviewError] = useState<string | null>(null);
+  const reviewEpoch = useRef(0);
+  const pendingReviewEpoch = useRef(0);
+  useEffect(() => {
+    reviewEpoch.current++; setPendingReview(null); setPendingReviewError(null);
+    return () => { reviewEpoch.current++; };
+  }, [client, targetAgentId, projectId, activeUri, activeFile]);
+  const openPendingReview = useCallback(async (action: ReviewAction) => {
+    if (!targetAgentId || !activeUri) return;
+    const epoch = reviewEpoch.current;
+    setPendingReviewError(null);
+    try {
+      const page = await listPendingChanges({ agentId: targetAgentId, ...(projectId ? { projectId } : {}), uri: activeUri }, client);
+      if (epoch !== reviewEpoch.current) return;
+      const records = page.changes.filter(rec => normalizePolicyUri(rec.uri) === normalizePolicyUri(activeUri));
+      if (page.partial || page.complete === false || page.restartRequired || records.length !== 1) {
+        setPendingReviewError('The pending change is unavailable or ambiguous. Refresh and try again.'); return;
+      }
+      pendingReviewEpoch.current = epoch;
+      setPendingReview({ kind: 'single', rec: records[0]!, action });
+    } catch (error) { if (epoch === reviewEpoch.current) setPendingReviewError(error instanceof Error ? error.message : 'Could not load the pending change.'); }
+  }, [client, targetAgentId, projectId, activeUri]);
+
   const rawUrl = useMemo(() => {
     if (!activeNode?.uri || !rawAgentId) return null;
     return getRawFileUrl(rawAgentId, activeNode.uri, projectId ?? undefined);
@@ -267,7 +297,7 @@ export function FileEditor() {
   const handleApprove = useCallback(async () => {
     if (!targetAgentId || !activeNode || approving) return;
     if (activeNode.status === 'pending_review') {
-      setWorkspacePanelOpen('pending', true); setActiveWorkspaceTab('pending'); return;
+      await openPendingReview('approve'); return;
     }
     setApproving(true);
     try {
@@ -296,12 +326,12 @@ export function FileEditor() {
     } finally {
       setApproving(false);
     }
-  }, [targetAgentId, activeNode, approving, projectId, openFile, resolvedAgent?.id, activeFile, patchFileNode, clearFilePrev]);
+  }, [openPendingReview, client, targetAgentId, activeNode, approving, projectId, openFile, resolvedAgent?.id, activeFile, patchFileNode, clearFilePrev]);
 
   const handleRevert = useCallback(async () => {
     if (!targetAgentId || !activeNode || reverting) return;
     if (activeNode.status === 'pending_review') {
-      setWorkspacePanelOpen('pending', true); setActiveWorkspaceTab('pending'); return;
+      await openPendingReview('revert'); return;
     }
     setReverting(true);
     try {
@@ -335,7 +365,7 @@ export function FileEditor() {
     } finally {
       setReverting(false);
     }
-  }, [targetAgentId, activeNode, reverting, projectId, openFile, resolvedAgent?.id, activeFile, activePrev, patchFileNode, clearFilePrev]);
+  }, [openPendingReview, client, targetAgentId, activeNode, reverting, projectId, openFile, resolvedAgent?.id, activeFile, activePrev, patchFileNode, clearFilePrev]);
 
   useEffect(() => {
     if (!activeNode) {
@@ -420,6 +450,14 @@ export function FileEditor() {
 
   return (
     <div className="h-full w-full flex flex-col min-w-0 min-h-0">
+      {pendingReviewError ? <div role="alert" className="px-3 py-2 text-xs text-red-300">{pendingReviewError}</div> : null}
+      {pendingReview && targetAgentId ? <PendingReviewDialog request={pendingReview} agentId={targetAgentId} projectId={projectId}
+        run={reviewQueue.run} onClose={() => setPendingReview(null)} onDone={done => {
+          if (pendingReviewEpoch.current !== reviewEpoch.current || !done.some(result => result.outcome === 'ok')) return;
+          setPendingReview(null);
+          void refreshPendingCount({ agentId: targetAgentId, projectId });
+          void openFile({ agentId: targetAgentId, projectId: projectId ?? null, uri: activeUri, force: true });
+        }} /> : null}
       {openFiles.length > 0 || workspacePanels.upload || (supportsSources && workspacePanels.sources) || workspacePanels.packages || workspacePanels.pending || gitDiffTarget || gitCommitTarget ? (
         <div
           className="flex shrink-0 items-stretch"

package/app/filesystem/ui/GitControlPanel.tsx

@@ -1202,7 +1202,6 @@ export function GitControlPanel({ agentId }: { agentId: string }) {
             size="sm"
             skill="git"
             packageId="@neuralis/brain-core"
-            scripts={["scripts/git.sh"]}
             label="Status, diff, commit, branch, fetch or push with the agent"
             icon="GitBranch"
           />

package/app/filesystem/ui/GitDiffView.tsx

@@ -27,15 +27,20 @@ export function GitDiffView({
   projectId: string | null;
 }): React.ReactElement {
   const client = useFilesystemStore((s) => s.client);
-  const [canWrite, setCanWrite] = useState(false);
   const revision = useFilesystemStore(state => state.sourceChangeRevision[target.source] ?? 0);
+  const context = `${agentId ?? ''}\u0000${projectId ?? ''}\u0000${target.source}\u0000${target.repo ?? ''}`;
+  const [permission, setPermission] = useState<{ client: typeof client; context: string; revision: number; allowed: boolean; pending: boolean } | null>(null);
+  const current = permission?.client === client && permission.context === context;
+  const canWrite = current && !permission.pending && permission.revision === revision && permission.allowed;
+  const stageRows = current && permission.allowed;
   useEffect(() => {
-    let alive = true; setCanWrite(false);
+    let alive = true;
+    setPermission(previous => ({ client, context, revision, pending: true, allowed: previous?.client === client && previous.context === context && previous.allowed }));
     if (agentId) void getGitRepos({ agentId, ...(projectId ? { projectId } : {}), source: target.source }, client).then(result => {
-      if (alive) setCanWrite(result.repos.find(repo => repo.rel === (target.repo ?? ''))?.canWrite === true);
-    }).catch(() => { if (alive) setCanWrite(false); });
+      if (alive) setPermission({ client, context, revision, pending: false, allowed: result.repos.find(repo => repo.rel === (target.repo ?? ''))?.canWrite === true });
+    }).catch(() => { if (alive) setPermission({ client, context, revision, pending: false, allowed: false }); });
     return () => { alive = false; };
-  }, [agentId, projectId, target.source, target.repo, revision]);
+  }, [client, context, agentId, projectId, target.source, target.repo, revision]);
   const mode = useMemo(() => gitDiffModeFromTarget(target), [target]);
   return (
     <GitFileDiff
@@ -49,6 +54,8 @@ export function GitDiffView({
       projectId={projectId}
       variant="tab"
       canWrite={canWrite}
+      stageRows={stageRows}
+      permissionPending={!current || permission.pending || permission.revision !== revision}
       revision={revision}
     />
   );

package/app/filesystem/ui/GitFileDiff.tsx

@@ -130,6 +130,8 @@ export function GitFileDiff({
   variant = 'tab',
   revision = 0,
   canWrite = false,
+  stageRows = canWrite,
+  permissionPending = false,
   runContent,
   peekContent,
 }: {
@@ -151,6 +153,8 @@ export function GitFileDiff({
   variant?: 'tab' | 'card';
   revision?: number;
   canWrite?: boolean;
+  stageRows?: boolean;
+  permissionPending?: boolean;
   /** A virtualized list's content lane; `cache` lets a re-mounted card reuse its answer. */
   runContent?: VisibleDiffQueue['run'];
   /** The lane's synchronous cache read: a re-mounted card paints its last answer on its first frame. */
@@ -230,7 +234,7 @@ export function GitFileDiff({
   }, [language]);
 
   useEffect(() => {
-    sourceCacheRef.current.clear();
+    sourceCacheRef.current.clear(); setHunkBusy(null); setHunkError(null);
     // New target/revision (or post-stage refetch): drop cached source and expansion state —
     // the ranges are relative to the OLD raw's original hunks — AND the
     // server-flag states: `serverTruncated`/`tooLarge` belong to the PREVIOUS
@@ -293,7 +297,7 @@ export function GitFileDiff({
       }
     })();
     return () => { seqRef.current++; };
-  }, [agentId, projectId, source, repo, path, normalizedMode, reloadNonce, revision, runContent]);
+  }, [client, agentId, projectId, source, repo, path, normalizedMode, reloadNonce, revision, runContent]);
 
   // The ONE parse of the raw diff — the ORIGINAL (staging) model.
   const { files, truncated, hunkPatches } = useMemo(
@@ -317,7 +321,7 @@ export function GitFileDiff({
   // parsed count, or the index→patch mapping is unsafe.
   const singleFile: FileData | null = files.length === 1 ? files[0] : null;
   const canStageHunks =
-    canWrite && kind === 'working' &&
+    stageRows && kind === 'working' &&
     !!agentId &&
     !!singleFile &&
     singleFile.type === 'modify' &&
@@ -386,7 +390,7 @@ export function GitFileDiff({
     } catch {
       return settle({ ok: false });
     }
-  }, [agentId, projectId, source, repo, path, expanderSrc, runContent]);
+  }, [client, agentId, projectId, source, repo, path, expanderSrc, runContent]);
 
   // The synthetic OLD-side lines (`expandFromRawCode` slices by old-line
   // numbers) + the RENDER-ONLY expanded hunk list. `oldTotal` also sizes the
@@ -458,12 +462,13 @@ export function GitFileDiff({
   const applyHunk = useCallback(
     async (hunkIndex: number) => {
       // A raw shown while its fresh answer loads may be an older revision's — never stage from it.
-      if (loading || !canStageHunks || !hunkPatches || !agentId) return;
+      if (loading || permissionPending || !canWrite || !canStageHunks || !hunkPatches || !agentId) return;
       const patch = assembleHunkPatch(hunkPatches.header, hunkPatches.hunks[hunkIndex]);
       if (!patch) {
         setHunkError('Could not build a hunk patch for this change.');
         return;
       }
+      const mySeq = seqRef.current;
       setHunkBusy(hunkIndex);
       setHunkError(null);
       try {
@@ -472,6 +477,7 @@ export function GitFileDiff({
         } else {
           await stageHunk({ agentId, ...(projectId ? { projectId } : {}), source, ...(repo ? { repo } : {}), hunk: patch }, client);
         }
+        if (mySeq !== seqRef.current) return;
         // The index changed → the cached `rev=index` source is stale (the WT
         // entry would survive, but a whole-map clear is cheap and race-free).
         sourceCacheRef.current.clear();
@@ -487,12 +493,12 @@ export function GitFileDiff({
         void loadGitStatus({ agentId, projectId });
         setReloadNonce((n) => n + 1);
       } catch (e) {
-        setHunkError(e instanceof Error ? e.message : 'Hunk apply failed');
+        if (mySeq === seqRef.current) setHunkError(e instanceof Error ? e.message : 'Hunk apply failed');
       } finally {
-        setHunkBusy(null);
+        if (mySeq === seqRef.current) setHunkBusy(null);
       }
     },
-    [loading, canStageHunks, hunkPatches, agentId, projectId, source, repo, staged, loadGitStatus],
+    [client, loading, permissionPending, canWrite, canStageHunks, hunkPatches, agentId, projectId, source, repo, staged, loadGitStatus],
   );
 
   /** One collapsed-gap row: clickable expander, or static text once refused. */
@@ -542,7 +548,7 @@ export function GitFileDiff({
               key={idx}
               type="button"
               onClick={() => void applyHunk(idx)}
-              disabled={hunkBusy !== null || loading}
+              disabled={hunkBusy !== null || loading || permissionPending || !canWrite}
               className={cn(
                 'inline-flex items-center gap-1 rounded-md border px-2 py-0.5 text-[10px] transition-colors disabled:opacity-40',
                 staged