agent-nuvira 3.3.12 → 3.3.14

package/dist/learning/model-registry.js

@@ -37,10 +37,12 @@
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { envBuff, resolveNuviraHome } from '../config/paths.js';
 import { formatCount } from '../utils/format.js';
+import { stableJson, withFileLockSync, writeFileAtomicSync } from '../utils/atomic-store.js';
 import { join } from 'node:path';
 import { getVectorStore } from '../memory/vector-store.js';
 import { reasoningCapabilityFromAdvertised } from '../inference/reasoning-effort.js';
 import { isNonChatModel } from '../inference/model-catalog.js';
+import { emptyCapabilityRecord, foldCallOutcome, foldLatency, foldVerification, } from './capability-evidence.js';
 import { getQuotaLedger } from './quota-ledger.js';
 import { getEventBus, EventNames } from '../observability/event-bus.js';
 import { appendChainedRecordFast, rechainRecords, writeHeadState, headOfLines, } from '../enterprise/audit-chain.js';
@@ -73,6 +75,14 @@ export const DEGRADED_UNAVAILABLE_THRESHOLD = 3;
  * permanently penalizes a recovered model in preferredModelsFor().
  */
 export const ERROR_RATE_HEAL_STEP = 0.1;
+/**
+ * How long a pair that resolved with an UNUSABLE (empty) response is parked.
+ *
+ * fix_model_routing P1/P2. Short enough to self-heal (a genuinely transient
+ * empty), long enough that the same broken pair is not re-picked on the next
+ * turn. Model-scoped: the provider's healthy siblings stay routable.
+ */
+export const EMPTY_RESPONSE_PARK_MS = 120_000;
 function memoryDir() {
     return envBuff('MEMORY_DIR') || DEFAULT_MEMORY_DIR;
 }
@@ -114,13 +124,6 @@ function actionLogPath() {
 function entryKey(provider, model) {
     return `${provider}|${model || 'default'}`;
 }
-/**
- * Does an `unavailable` REASON mean the provider/model pair cannot exist?
- *
- * Deliberately narrow: it must be an explicit "this model does not exist on
- * this endpoint", never a permission/per-account answer (a 403 or a quota
- * denial can be repaired, so the pair must stay reachable).
- */
 /**
  * Does an `unavailable` REASON mean the provider/model pair cannot exist?
  *
@@ -130,19 +133,59 @@ function entryKey(provider, model) {
  */
 const MODEL_NOT_FOUND_REASON_RE = /model not found|not in live model list|does not exist|no such model|model_not_found/i;
 /**
- * Is this entry a DEAD PAIR?
+ * Is this entry a NONEXISTENT pair — the provider cannot serve this id at all?
  *
  * The flag is the primary signal, but the reason check heals data written
  * BEFORE the flag existed (and by any surface): an entry sitting at
  * `unavailable` with a not-found reason IS a retired pair, and without this the
  * live `local/gemini-3.1-flash-lite` entry would keep being offered until it
  * failed one more time.
+ *
+ * EXPORTED for `learning/pair-entitlement.ts`, which needs the SAME verdict the
+ * dead-pair machinery uses. Two predicates for one question is how the registry
+ * and the router start disagreeing about which pairs are offerable.
  */
-function isDeadEntry(e) {
+export function isNonexistentPair(e) {
     if (e.deadPair)
         return true;
     return e.status === 'unavailable' && MODEL_NOT_FOUND_REASON_RE.test(e.lastError ?? '');
 }
+/**
+ * Does an `unavailable` REASON describe an ACCOUNT-level refusal that a fresh
+ * catalogue listing cannot refute?
+ *
+ * The complement of {@link MODEL_NOT_FOUND_REASON_RE}, and deliberately disjoint
+ * from it. "This model does not exist on this endpoint" IS refuted by the
+ * provider listing the model again — but "this account cannot pay for this
+ * call" and "this key is not authorized" are facts about the ACCOUNT, and a
+ * public model list says nothing about them. Collapsing the two is what let a
+ * metadata probe re-arm a pair `recordCall` had already proven dead (see the
+ * note in `markListed`).
+ *
+ * Narrow on purpose: transient refusals (`rate-limit`, quota parks, 5xx) are
+ * NOT entitlement failures — a listing, a park expiry or a recovered key may
+ * legitimately re-open those, and `quotaParkedUntil` already models the clock.
+ *
+ * EXPORTED for `learning/pair-entitlement.ts` — see `isNonexistentPair`.
+ */
+export function isEntitlementFailure(lastError) {
+    if (!lastError)
+        return false;
+    if (MODEL_NOT_FOUND_REASON_RE.test(lastError))
+        return false;
+    const t = lastError.toLowerCase();
+    return (t.includes('credit-exhausted') ||
+        t.includes('insufficient credit') ||
+        t.includes('payment required') ||
+        t.includes('billing') ||
+        t.includes('unauthorized') ||
+        t.includes('forbidden') ||
+        t.includes('invalid api key') ||
+        t.includes('invalid_api_key') ||
+        t.includes('authentication failed') ||
+        /\bauth\b/.test(t) ||
+        /\b40[123]\b/.test(t));
+}
 /**
  * The config value `'default'` is a SENTINEL meaning "use the provider's
  * default model" — it is NOT a model id. Telemetry must never track it: a
@@ -156,6 +199,71 @@ export function isSentinelModel(model) {
 function emptyState() {
     return { version: CURRENT_VERSION, entries: {}, updatedAt: Date.now() };
 }
+/** A deep copy of registry state, so a snapshot cannot be mutated through aliasing. */
+function cloneRegistryData(data) {
+    return JSON.parse(JSON.stringify(data));
+}
+/**
+ * Merge three views of the registry into the one that should be on disk.
+ *
+ * The problem it solves, measured (2026-10-07): the singleton loads the mirror
+ * once at construction and `persist()` writes its WHOLE entry map back, so a
+ * long-lived process flushes a snapshot of every model it never touched —
+ * silently reverting what the dashboard, the gateway or a CLI run verified in
+ * the meantime. On this machine that flipped a strict-pin verdict from
+ * `credit-exhausted` back to `unverified` between two runs of one command, which
+ * re-armed the exact pre-flight F6 had just closed.
+ *
+ * The resolution needs no bookkeeping in the mutators, because `boot` already
+ * records what this process was told:
+ *
+ *  - an entry this process CHANGED since boot (`memory` differs from `boot`) is
+ *    this process's knowledge, and wins;
+ *  - an entry it never touched is whatever `disk` now holds, because another
+ *    process may have learned something about it;
+ *  - an entry present at boot but ABSENT from `memory` was deliberately dropped
+ *    (`pruneAbsentModels`), so the deletion wins — otherwise the prune would
+ *    undo itself the moment the next persist re-added it from disk;
+ *  - an entry in neither `boot` nor `memory` but on `disk` is a peer's new row,
+ *    and is adopted.
+ *
+ * Comparing with `stableJson` (not a bare deep-equal) is deliberate: two entries
+ * built by different code paths can be structurally identical yet serialize with
+ * different key order, which would read as "changed" and clobber the peer.
+ */
+export function mergeRegistryMirror(boot, memory, disk) {
+    const entries = {};
+    const keys = new Set([
+        ...Object.keys(boot.entries),
+        ...Object.keys(memory.entries),
+        ...Object.keys(disk.entries),
+    ]);
+    for (const key of keys) {
+        const mine = memory.entries[key];
+        const base = boot.entries[key];
+        const theirs = disk.entries[key];
+        if (!mine) {
+            if (base)
+                continue; // this process removed it — the deletion is the update
+            if (theirs)
+                entries[key] = theirs; // a peer's new row
+            continue;
+        }
+        const changedHere = !base || stableJson(mine) !== stableJson(base);
+        if (changedHere) {
+            entries[key] = mine;
+            continue;
+        }
+        // Unchanged HERE, so the file decides — including its ABSENCE. Re-adding a
+        // key the file no longer has would resurrect a peer's deletion (a prune, or
+        // a `reset`), which is the same lost-update bug pointing the other way.
+        if (theirs === undefined)
+            continue;
+        entries[key] = theirs;
+    }
+    // Scalars (version, updatedAt) come from this process; only the entry map merges.
+    return { ...disk, ...memory, entries };
+}
 /**
  * Aggregate raw action-telemetry entries into the per-action dashboard view.
  * Pure + sync — the dashboard server calls this on the raw JSONL lines, and
@@ -303,6 +411,13 @@ export function aggregateActionTelemetry(entries, options = {}) {
  */
 export class ModelRegistry {
     data;
+    /**
+     * The registry as this process loaded it, kept so `persist()` can tell WHICH
+     * entries this process actually changed (see `mergeRegistryMirror`). Without
+     * it, a persist flushes every entry it merely READ back over whatever other
+     * processes have learned since — the measured lost-update bug.
+     */
+    bootSnapshot;
     /** Cached VectorStore for the enterprise mirror (null until first mirror). */
     vectorStore = null;
     /** Whether the vector mirror has been confirmed usable. */
@@ -311,6 +426,7 @@ export class ModelRegistry {
     actionLogCount = -1;
     constructor() {
         this.data = this.loadMirror();
+        this.bootSnapshot = cloneRegistryData(this.data);
     }
     // ─── Synchronous read path (lightning fast — no I/O, no network) ─────────
     /**
@@ -385,7 +501,7 @@ export class ModelRegistry {
     getDeadPairs() {
         const out = [];
         for (const e of Object.values(this.data.entries)) {
-            if (isDeadEntry(e))
+            if (isNonexistentPair(e))
                 out.push({ provider: e.provider, model: e.model });
         }
         return out;
@@ -395,7 +511,7 @@ export class ModelRegistry {
         if (!model || model === 'default')
             return false;
         const entry = this.data.entries[entryKey(provider, model)];
-        return !!entry && isDeadEntry(entry);
+        return !!entry && isNonexistentPair(entry);
     }
     /** Providers that currently have at least one verified, usable model. Sync. */
     getUsableProviders(now = Date.now()) {
@@ -497,6 +613,23 @@ export class ModelRegistry {
     getEntry(provider, model) {
         return this.data.entries[entryKey(provider, model)];
     }
+    /**
+     * Every verified, usable pair across ALL providers (A1).
+     *
+     * `getVerifiedModels(provider)` answers "what works on THIS provider"; this
+     * answers "what works anywhere", which is the question a pin pre-flight has to
+     * ask: when a pair is refused, the useful next sentence is "the same model is
+     * verified on <other provider>". Built on the SAME `isUsable()` gate as
+     * routing, so a suggestion here can never name a pair the router would reject.
+     *
+     * The `'default'` sentinel is excluded — it is a config marker ("use the
+     * provider's default"), not a model id, and suggesting it would be nonsense.
+     */
+    getAllUsablePairs(now = Date.now()) {
+        return Object.values(this.data.entries)
+            .filter((e) => !isSentinelModel(e.model) && this.isUsable(e.provider, e.model, now))
+            .map((e) => ({ provider: e.provider, model: e.model }));
+    }
     /**
      * The learned reasoning-parameter support for a provider × model, or
      * `undefined` when nothing has been established (callers treat absent as
@@ -593,7 +726,9 @@ export class ModelRegistry {
     }
     /**
      * listModels probe: mark the model as seen (unverified unless already
-     * verified). Does NOT downgrade a verified entry — real verification wins.
+     * verified). Does NOT downgrade a verified entry — real verification wins —
+     * and does NOT clear a definitive ACCOUNT-level refusal (see
+     * `isEntitlementFailure`).
      * Accepts either bare ids (legacy callers) or full model descriptors; when
      * a descriptor carries the provider-advertised context window, it is
      * recorded so the router's context preflight can use the LIVE value.
@@ -623,10 +758,24 @@ export class ModelRegistry {
                     existing.reasoningCapability = reasoningCapability;
                 continue;
             }
+            // ── A DEFINITIVE ENTITLEMENT REFUSAL SURVIVES A CATALOGUE LISTING ───────
+            // Being in the provider's model list proves the provider SERVES the model.
+            // It proves nothing about whether THIS ACCOUNT may use it — and those are
+            // different axes, the same distinction `errorRate`/`partialRate` already
+            // draw below. Measured (2026-10-06): `openrouter|deepseek/deepseek-v4.1-flash`
+            // is in OpenRouter's public catalogue, while the account behind the key had
+            // never purchased credits. `recordCall` had learned the definitive
+            // `credit-exhausted` verdict; a catalogue refresh re-listed the provider,
+            // this loop reset the entry to `unverified`, and the pin that one run
+            // refused before any network call was offered again by the next — which got
+            // a raw `402 Insufficient credits` body back. Same pin, same registry,
+            // opposite outcomes, decided by a metadata probe. An entitlement verdict
+            // only real traffic can clear.
+            const entitled = existing?.status === 'unavailable' && isEntitlementFailure(existing?.lastError);
             this.data.entries[key] = {
                 provider,
                 model,
-                status: 'unverified',
+                status: entitled ? 'unavailable' : 'unverified',
                 lastVerifiedAt: existing?.lastVerifiedAt || 0,
                 lastProbedAt: now,
                 lastUsedAt: existing?.lastUsedAt || 0,
@@ -642,6 +791,7 @@ export class ModelRegistry {
                 quotaParkedUntil: existing?.quotaParkedUntil || 0,
                 reasoningCapability,
                 source: 'probe',
+                capability: existing?.capability,
                 lastError: existing?.lastError,
                 // The provider's OWN model list is authoritative about what it serves:
                 // a pair that appears in a fresh list is not a dead pair, so the flag is
@@ -718,6 +868,11 @@ export class ModelRegistry {
             // Reasoning-parameter support is model metadata, independent of the verify
             // event — it survives a re-verify exactly like contextWindowTokens does.
             reasoningCapability: existing?.reasoningCapability,
+            // Bundle 3b: the measured scorecard is model metadata too. A verification
+            // proves the pair ANSWERS; it says nothing about how well it does the work,
+            // so the accuracy samples must not be reset by it (nor by any availability
+            // flip — see markListed/markUnavailable).
+            capability: existing?.capability,
         };
         this.persist();
         // A GENUINE promotion (was not verified → now verified) is a state change
@@ -734,6 +889,60 @@ export class ModelRegistry {
             this.appendActionLog({ timestamp: now, action, provider, model, outcome: 'verified', latencyMs, costUsd, callId });
         }
     }
+    /**
+     * Fold one observation into this pair's capability scorecard (Bundle 3b).
+     *
+     * Silent and best-effort by design: a scorecard write must never fail a call or
+     * an availability write. The record is model metadata — created on first
+     * observation, never reset by an availability flip (see `markVerified`).
+     */
+    foldCapability(provider, model, observation) {
+        if (isSentinelModel(model))
+            return;
+        try {
+            const key = entryKey(provider, model);
+            const entry = this.data.entries[key];
+            if (!entry)
+                return;
+            const now = observation.now ?? Date.now();
+            let record = entry.capability ?? emptyCapabilityRecord(now);
+            if (observation.verification !== undefined) {
+                record = foldVerification(record, observation.verification, now);
+            }
+            if (observation.ok !== undefined) {
+                record = foldCallOutcome(record, observation.ok, now);
+            }
+            if (observation.latencyMs !== undefined) {
+                record = foldLatency(record, observation.latencyMs, now);
+            }
+            if (record === entry.capability)
+                return;
+            entry.capability = record;
+            this.persist();
+        }
+        catch {
+            // Best-effort — the scorecard is learning, never a gate.
+        }
+    }
+    /**
+     * Record a completed TURN's verification verdict for a pair (Bundle 3b).
+     *
+     * The accuracy parameter's real feed: `TurnReport.verification` is derived from
+     * recorded tool/plan evidence and cannot be talked up by the model, so the
+     * sample this writes is an observation rather than a claim. `blocked` and
+     * `not-applicable` contribute NOTHING — a wall the run hit, and a turn with
+     * nothing to check, are both silent about the model.
+     *
+     * A pair with no entry yet is skipped rather than invented: the scorecard hangs
+     * off a registry row, and creating one from a turn would claim the pair exists.
+     */
+    recordCapabilityEvidence(provider, model, verification) {
+        this.foldCapability(provider, model, { verification });
+    }
+    /** This pair's measured scorecard, or undefined when nothing was measured. */
+    getCapability(provider, model) {
+        return this.data.entries[entryKey(provider, model)]?.capability;
+    }
     /**
      * M2.2: record EXACT tokens from a provider-reported usage payload. The
      * per-call token EMAs (α=0.3, matching latency) feed getMeasuredUsage(),
@@ -821,6 +1030,7 @@ export class ModelRegistry {
             reasoningCapability: existing?.reasoningCapability,
             quotaParkedUntil: Math.max(existing?.quotaParkedUntil || 0, quotaParkedUntil),
             source,
+            capability: existing?.capability,
             lastError: reason,
             // A "model not found" answer is definitive for this provider × model, so
             // the pair is retired from every candidate pool (see `deadPair`). The flag
@@ -990,6 +1200,13 @@ export class ModelRegistry {
         if (ok) {
             this.markVerified(provider, model, 'telemetry', latencyMs, action, costUsd, callId);
             this.data.entries[key].lastUsedAt = now;
+            // Bundle 3b: every real call is also capability evidence — how the pair held
+            // up (robustness) and how fast it answered (performance). Folded HERE (the
+            // single telemetry entry point) and AFTER markVerified, because markVerified
+            // is what creates the row for a pair's first-ever call — folding earlier
+            // would silently drop the first observation of every model. Availability is
+            // not touched: this is evidence about the model, not a status write.
+            this.foldCapability(provider, model, { ok, latencyMs, now });
             // P4 M4.4: a clean success heals mid-stream flakiness (the provider
             // demonstrably finishes). Decay the EMA toward 0 — never hard-reset,
             // so a single success doesn't erase a flaky streak. markVerified already
@@ -1055,8 +1272,41 @@ export class ModelRegistry {
             entry.providerParked = false;
             flipped = true;
         }
+        else if (errorType === 'empty-response') {
+            // fix_model_routing P1/P2 — the provider RESOLVED but carried nothing.
+            // This used to be recorded as a SUCCESS (the walk had no notion of a
+            // usable response), so a model that answers every turn with an empty body
+            // kept `verified` and `errorRate 0` and the router kept choosing it. The
+            // error-rate bump above already sinks it in scoring; the park is the hard
+            // stop, and it is MODEL-scoped so the provider's healthy siblings remain
+            // routable and the pair returns automatically after the window.
+            entry.lastError = 'empty-response (no text, no tool call)';
+            entry.quotaParkedUntil = Math.max(entry.quotaParkedUntil, now + EMPTY_RESPONSE_PARK_MS);
+            entry.providerParked = false;
+            flipped = true;
+        }
+        else if (errorType === 'credit-exhausted') {
+            // DEFINITIVE, and NOT a cooldown (A4). The account cannot pay, so there is
+            // no window to wait out — a park would expire and the router would offer
+            // the pair again, which is precisely how `openrouter/deepseek-v4.1-flash`
+            // kept being chosen and kept answering 402. Demoted like `auth`: it takes
+            // a funded key (or `models unblock` / a re-probe) to restore.
+            //
+            // This is honest about WHAT failed: the check is on the PAIR because that
+            // is the granularity the registry stores, but the sentence names the
+            // account, not the model — a different host may serve this same model,
+            // and the failover walk is free to try one.
+            entry.status = 'unavailable';
+            entry.lastError = 'credit-exhausted (that provider account cannot pay for this call)';
+            entry.quotaParkedUntil = 0;
+            entry.providerParked = false;
+            flipped = true;
+        }
         this.data.entries[key] = entry;
         this.persist();
+        // Bundle 3b — a FAILED call is capability evidence too (robustness), and the
+        // row now exists on both paths (markVerified above, or the entry built here).
+        this.foldCapability(provider, model, { ok, latencyMs, now });
         if (flipped)
             this.emitUpdated([provider], `telemetry failure (${errorType})`, 'telemetry');
         if (action) {
@@ -1413,7 +1663,11 @@ export class ModelRegistry {
      * Only call this with an AUTHORITATIVE live list (the refresh probe of a
      * keyless/local runner). Entries whose model is NOT in the list are handled:
      *   - UNVERIFIED / UNAVAILABLE entries are DELETED entirely (never checked
-     *     again — they have no learned value worth keeping).
+     *     again — they have no learned value worth keeping), EXCEPT an entry whose
+     *     unavailability is an ACCOUNT-level refusal (`isEntitlementFailure`): that
+     *     one is the only record that this key cannot pay or is not authorized, so
+     *     deleting it loses the verdict and the next model listing re-creates the
+     *     pair as `unverified` — re-arming exactly the pin A2 exists to refuse.
      *   - VERIFIED entries are DEMOTED to `unavailable` with reason "model
      *     deleted from local system" instead of being hard-deleted — a partial
      *     listModels response (a model mid-pull, a gateway hiccup) must not
@@ -1433,6 +1687,14 @@ export class ModelRegistry {
                 continue;
             if (e.status === 'verified')
                 demotedKeys.push(key);
+            // Absence from a model list is evidence about the CATALOGUE, not about the
+            // account. Deleting an entitlement verdict hands the pair straight back to
+            // the next `markListed` as a fresh `unverified` entry (observed live: the
+            // `credit-exhausted` verdict on `openrouter/deepseek/deepseek-v4.1-flash`
+            // was gone after a refresh, so the strict pre-flight stopped firing and a
+            // run that had refused before any call sent the request and got a raw 402).
+            else if (isEntitlementFailure(e.lastError))
+                continue;
             else
                 removedKeys.push(key);
         }
@@ -1491,19 +1753,38 @@ export class ModelRegistry {
      */
     reloadFromMirror() {
         this.data = this.loadMirror();
+        this.bootSnapshot = cloneRegistryData(this.data);
     }
     /**
      * Persist: JSON mirror synchronously (canonical, guaranteed), then mirror to
      * the VectorStore namespace asynchronously (best-effort, auto-tiers to JSON
      * when FAISS/native aren't installed — so it can never throw).
      */
-    persist() {
+    persist(opts = {}) {
         this.data.updatedAt = Date.now();
         const dir = memoryDir();
+        const path = mirrorPath();
         try {
-            if (!existsSync(dir))
-                mkdirSync(dir, { recursive: true });
-            writeFileSync(mirrorPath(), JSON.stringify(this.data, null, 2), 'utf-8');
+            mkdirSync(dir, { recursive: true });
+            // The read-merge-write runs UNDER the lock, so two processes cannot
+            // interleave it: the second one to run re-reads what the first wrote and
+            // merges rather than overwriting. `writeFileAtomicSync` then makes the
+            // publication all-or-nothing, so a concurrent READER can never parse a
+            // half-written file (which every loader here turns into an empty state
+            // that the next persist would write back).
+            const merged = withFileLockSync(`${path}.lock`, () => {
+                // A deliberate wipe (`reset`) must not adopt a peer's concurrent row —
+                // the operator asked for an empty registry, so it is written as-is.
+                const next = opts.replace
+                    ? this.data
+                    : mergeRegistryMirror(this.bootSnapshot, this.data, this.loadMirror());
+                writeFileAtomicSync(path, JSON.stringify(next, null, 2));
+                return next;
+            });
+            // Adopt the merge, and re-baseline: this process's view is now the file's,
+            // so the NEXT persist compares against it instead of against boot.
+            this.data = merged.value;
+            this.bootSnapshot = cloneRegistryData(this.data);
         }
         catch {
             // Best-effort — a failed mirror write must never break routing.
@@ -1525,27 +1806,31 @@ export class ModelRegistry {
     mirrorToVector(dir) {
         try {
             const indexPath = join(dir, 'vectors-model-registry.json');
-            if (!existsSync(dir))
-                mkdirSync(dir, { recursive: true });
-            let entries = {};
-            try {
-                if (existsSync(indexPath)) {
-                    const raw = JSON.parse(readFileSync(indexPath, 'utf-8'));
-                    if (raw && typeof raw === 'object' && raw.entries && typeof raw.entries === 'object') {
-                        entries = raw.entries;
+            mkdirSync(dir, { recursive: true });
+            // Same cross-process shape as `persist()`: the read-merge-write is one
+            // critical section, and the publication is atomic. Two processes mirroring
+            // this namespace concurrently would otherwise drop each other's snapshot.
+            withFileLockSync(`${indexPath}.lock`, () => {
+                let entries = {};
+                try {
+                    if (existsSync(indexPath)) {
+                        const raw = JSON.parse(readFileSync(indexPath, 'utf-8'));
+                        if (raw && typeof raw === 'object' && raw.entries && typeof raw.entries === 'object') {
+                            entries = raw.entries;
+                        }
                     }
                 }
-            }
-            catch {
-                // Corrupt/missing file — start from an empty index.
-            }
-            entries[VECTOR_SNAPSHOT_ID] = {
-                id: VECTOR_SNAPSHOT_ID,
-                vector: [1], // 1-dim placeholder — we never search, only store.
-                metadata: { snapshot: this.data },
-                createdAt: Date.now(),
-            };
-            writeFileSync(indexPath, JSON.stringify({ entries, version: 2 }, null, 2), 'utf-8');
+                catch {
+                    // Corrupt/missing file — start from an empty index.
+                }
+                entries[VECTOR_SNAPSHOT_ID] = {
+                    id: VECTOR_SNAPSHOT_ID,
+                    vector: [1], // 1-dim placeholder — we never search, only store.
+                    metadata: { snapshot: this.data },
+                    createdAt: Date.now(),
+                };
+                writeFileAtomicSync(indexPath, JSON.stringify({ entries, version: 2 }, null, 2));
+            });
             this.vectorMirrored = true;
         }
         catch {
@@ -1684,7 +1969,8 @@ export class ModelRegistry {
     /** Clear the registry (CLI / tests). */
     reset() {
         this.data = emptyState();
-        this.persist(); // persist() also overwrites the vector snapshot with the empty state.
+        // Also overwrites the vector snapshot with the empty state.
+        this.persist({ replace: true });
     }
 }
 // ─── Singleton ──────────────────────────────────────────────────────────────