@neuralis/brain-core 0.2.0 → 0.3.0

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

@@ -19,7 +19,7 @@ React surface contributed by `@neuralis/brain-core`: the Files widget, the `file
 
 - `installFilesystemHostComponents({ registry, port })` registers the lazy `FilesystemWidget` in the host `PackageHostRegistry` under `componentImport: '@neuralis/brain-core/app/filesystem'` and registers `FilesystemChangeCard` for the `filesystem.change` card type via `agent-core`'s chat card registry — WITH the card's height model (`estimateFilesystemChangeCardHeight`) AND its composer-aggregation contract (`FILESYSTEM_COMPOSER_CONTRACT` from `app/cards/diffUtils.ts`): brain-core OWNS how its card's activity reaches the composer's Changes tab and the post-stream summary (`tab: 'changes'` + the `extractFilesystemComposerChanges` paths/`version.diff` extractor); agent-core's aggregation surfaces iterate the card registry and carry zero filesystem literals. Both are module-level stable references (the registry's idempotency check compares identity). The widget is wrapped in `<PackageApiProvider slug="brain-core" projectId agentId userId>` so all internal API calls resolve through the kernel client.
 - The same install entry fills the host slot `workspace.provider:@neuralis/brain-core` with `<FilesystemPackageHost port={port}>`, which the host's provider root wraps around the workspace (registration order — after agent-core's fill, so inside it). It consumes the `WorkspaceHostPort` (active project/agent ids, agent map, file marks, event-stream URL builder) and exposes a `FilesystemHostValue` to every component below it. The `useBuildFilesystemHostValue` hook is the single adapter — the Files UI reads agents and file marks through that contract, never through host-specific imports.
-- `app/filesystem/api/` calls the brain-core package routes via `tryGetPackageApiImperativeAsync('brain-core')` (the `PackageApi` returned by the kernel client) — no direct `fetch` against `/api/packages/brain-core/*` from components.
+- `app/filesystem/api/` calls the brain-core package routes through a kernel `PackageApi` client each Files window passes (built over the window's project and bound agent) — no direct `fetch` against `/api/packages/brain-core/*` from components.
 
 ## Security & scope
 

package/app/filesystem/README.md

@@ -11,13 +11,13 @@ Files widget package — the React surface mounted by the host as the brain-core
 
 - `FilesystemWidget` — top-level component; takes `{ agentId, widgetId, state? }`. Mounted lazily by the host via `installFilesystemHostComponents`.
 - `FilesystemHostProvider`, `useFilesystemHost`, `getFilesystemHostImperative`, `FilesystemHostValue` — the host-injection contract.
-- `useFilesystemStore` and the `FileSystemState` shape — the Zustand store consumed by every component.
+- `useFilesystemStore` and the `FileSystemState` shape — the Files window's Zustand store, read through `FilesystemStoreProvider` (one store per window; see `store/README.md`).
 - `AgentInfo`, the `domain/types` re-export, the `lib/projectFiles` and `lib/agentUtils` helpers.
 - The `ui/` re-export bundle (14 symbols from `ui/index.ts`): `FilesystemWidget`, `FileTree`, `FileEditor`, `FileTab`, `FileMetaBar`, `CodeEditor` (CodeMirror 6 + Shiki editor), `ReviewDiffView` (`@codemirror/merge` review diff), `GitDiffView`, `GitFileDiff`, `GitCommitChangesView` (the Git Control diff surface — single-file and the multi-file stacked commit tab), `Toolbar`, `SourceTypeIcon`, `InlineUploader`, `PolicyEditor`. (`DiffView` — the old Myers review diff — was removed; the never-mounted `EditFileModal` / `UploadFileModal` were deleted 2026-09-04; the internal `EditorTabBar` / `DiffModeToggle` back `FileEditor`, and `PendingChangesPanel` is rendered by `FileEditor` rather than re-exported.)
 
 ## How it plugs into the package-system kernel
 
-- The widget runs inside `<PackageApiProvider slug="brain-core" projectId agentId userId>` (wired by `installFilesystemHostComponents`); every API call flows through the kernel `PackageApi` client, which translates calls into `/api/packages/brain-core/<route>` requests scoped to the active session.
+- Each window runs inside its own store (`FilesystemStoreProvider`, wired by `installFilesystemHostComponents`); every API call flows through that store's kernel `PackageApi` client — built over the window's project and bound agent — which translates calls into `/api/packages/brain-core/<route>` requests the route layer resolves to the real session.
 - `FilesystemHostProvider` is built on top of `WorkspaceHostPort`. The adapter (`host/buildFilesystemHostValue.ts`) is the single bridge between the kernel port and the brain-core view; the widget never imports host-specific symbols.
 - The SSE hook (`hooks/useFilesystemSSE.ts`) subscribes through `host.subscribeFilesystemEvents(agentId, projectId, …)`, which delegates to `WorkspaceHostPort.subscribeRealtime({ channel: 'filesystem', … })` — the ONE multiplexed `/api/events` hub, never a per-widget connection.
 
@@ -25,7 +25,7 @@ Files widget package — the React surface mounted by the host as the brain-core
 
 - API calls are scoped by the kernel session (`projectId`, `agentId`, `userId`) — the UI cannot forge a request for another project. The brain-core route layer enforces feature grants and source scope.
 - File marks (`useFileMarks(agentId)`) and the SSE event stream are per-agent. Cross-agent visibility requires the same feature grants enforced server-side.
-- The store evicts COLD rows above `FILES_LRU_HARD_CAP` (never a source root, an expanded folder, its ancestors, its direct children, or an open file) so the UI cannot accumulate unbounded data even when many sources stream events — and the dock broom empties it outright through the kernel port's `onClientStateReset`.
+- The store evicts COLD rows above `FILES_LRU_HARD_CAP` (never a source root, an expanded folder, its ancestors, its direct children, or an open file) so the UI cannot accumulate unbounded data even when many sources stream events — the cap is PER window store, so N mounted windows hold up to N × the cap — and the dock broom empties the windows it scopes through the kernel port's `onClientStateReset`.
 
 ## Add Source — key suggestion
 

package/app/filesystem/api/README.md

@@ -4,21 +4,21 @@ Typed client for brain-core package routes plus a small set of host-side helpers
 
 ## Responsibility
 
-- Wrap the kernel `PackageApi` (`tryGetPackageApiImperativeAsync('brain-core')`) into typed functions that mirror every brain-core route.
+- Wrap a kernel `PackageApi` into typed functions that mirror every brain-core route; each takes that client as its LAST argument.
 - Build raw-file URLs (`getRawFileUrl`) for the `<img>` / `<video>` preview elements. **Not for an iframe or any other document embed** — the byte lane serves the executable document class (SVG, HTML, XML) as `content-disposition: attachment`, so a document embed against it renders nothing, and making it render again would re-open a stored-XSS path. There is exactly one call site today (`FileEditor`).
 - Provide the host-side helpers (`projectPackages.ts`) used by the Packages tab — these talk to the host's `/api/packages/runtime` and `/api/projects/:id/packages/:slug/{build,trust}` routes, NOT to brain-core.
 
 ## 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`.
 
 ## How it plugs into the package-system kernel
 
-- All filesystem calls go through `tryGetPackageApiImperativeAsync('brain-core')` — the kernel resolves the `PackageApi` lazily so callers invoked at mount time don't race the `PackageApiProvider` registration.
+- A Files window passes the client its store was created with — `createPackageApi` over the window's project and BOUND agent — so the X-Project-Id / X-Agent-Id headers are the window's own, fixed before any await, whatever other window is mounted beside it; a body may still name another agent (a file read through its writing agent). `readFiles` alone also runs without a client, for the chat change card, which is not a Files window and resolves the first registered `brain-core` provider.
 - The `PackageApi` provided by `@neuralis/package-system/client` translates `.get(path, qs)`, `.post(path, body)`, `.patch`, `.del`, `.upload` into authenticated requests against `/api/packages/brain-core/<path>` with the active session attached by the host.
 - Project-package helpers go directly to host routes (`/api/packages/runtime`, `/api/projects/:id/packages/:slug/build`, `/.../trust`) — these are NOT package routes and are not part of the brain-core surface; the helpers live here only because the Files widget's Packages tab consumes them.
 
@@ -34,4 +34,4 @@ Typed client for brain-core package routes plus a small set of host-side helpers
 
 ## Tests
 
-Indirect coverage through the route tests under `test/routes/`. UI-side store interactions exercise these clients via mocked `PackageApi`.
+Indirect coverage through the route tests under `test/routes/`. `test/ui/gitApi.repo.test.ts` and `test/ui/searchApi.wire.test.ts` pass a mocked `PackageApi` as the client and pin the wire shape; `test/store/filesWindows.test.ts` pins that each window's requests carry its own client and headers.