@remnic/core 9.6.39 → 9.7.0

package/src/buffer-session.test.ts

@@ -492,13 +492,19 @@ test("getTurns prepends retained deferred turns before live turns", async () =>
   assert.equal(all[1]?.content, "new live turn");
 });
 
-test("SmartBuffer never prunes logical session buffers that still have pending turns", async () => {
+test("SmartBuffer prefers pruning empty entries and bounds pending-turn buffers at the cap (#1908 policy)", async () => {
+  // Pre-#1908 this contract was "never prune non-empty entries". With retry
+  // retention (failed extractions keep their turns), unbounded non-empty
+  // growth during a provider outage would eventually OOM the daemon — the
+  // documented policy (#1908 step 7) is: retain up to MAX_BUFFER_ENTRY_COUNT
+  // session entries, then prune the OLDEST sessions with a loud warning.
+  // Empty entries are still evicted first.
   const entries = Object.fromEntries(
     Array.from({ length: 205 }, (_, index) => [
       `thread-${index}`,
       {
         turns: [makeTurn(`thread-${index}`, `memory ${index}`)],
-        lastExtractionAt: null,
+        lastExtractionAt: new Date(1_700_000_000_000 + index * 60_000).toISOString(),
         extractionCount: 0,
       },
     ]),
@@ -516,14 +522,40 @@ test("SmartBuffer never prunes logical session buffers that still have pending t
       ...entries,
     },
   });
-  const buffer = new SmartBuffer(parseConfig({}), storage as any);
+  const buffer = new SmartBuffer(parseConfig({}), storage as unknown as ConstructorParameters<typeof SmartBuffer>[1]);
 
   await buffer.addTurn("active-thread", makeTurn("active-thread", "pending memory"));
 
   const persistedKeys = Object.keys(storage.saved?.entries ?? {});
-  assert.equal(persistedKeys.length, 207);
-  assert.ok(persistedKeys.includes("default"));
-  assert.ok(persistedKeys.includes("active-thread"));
-  assert.ok(persistedKeys.includes("thread-0"));
-  assert.ok(persistedKeys.includes("thread-204"));
+  assert.ok(persistedKeys.length <= 201, `bounded at the cap plus default (got ${persistedKeys.length})`);
+  assert.ok(persistedKeys.includes("default"), "default entry never pruned");
+  assert.ok(persistedKeys.includes("active-thread"), "the just-written key is retained");
+  assert.ok(!persistedKeys.includes("thread-0"), "oldest pending entry pruned once over the cap");
+  assert.ok(persistedKeys.includes("thread-204"), "newest pending entry survives");
+});
+
+test("pruneEntries evicts oldest NON-empty session entries past the cap (#1908 retry-retention bound)", async () => {
+  // Retained failed extractions keep their turns in the buffer, so during a
+  // provider outage non-empty entries can exceed MAX_BUFFER_ENTRY_COUNT (200).
+  // The cap is the documented bound: the oldest non-empty sessions must be
+  // evicted (loudly) rather than growing without bound (codex review).
+  const entries: NonNullable<BufferState["entries"]> = {};
+  for (let i = 0; i < 210; i += 1) {
+    const at = new Date(1_700_000_000_000 + i * 60_000).toISOString();
+    entries[`session-${String(i).padStart(3, "0")}`] = {
+      turns: [{ role: "user", content: `retained turn ${i}`, timestamp: at, sessionKey: `session-${i}` }],
+      lastExtractionAt: at,
+      extractionCount: 0,
+    };
+  }
+  const storage = new FakeStorage({ turns: [], lastExtractionAt: null, extractionCount: 0, entries });
+  const buffer = new SmartBuffer(parseConfig({}), storage as unknown as ConstructorParameters<typeof SmartBuffer>[1]);
+  await buffer.load();
+  await buffer.addTurn("session-newest", makeTurn("session-newest", "new turn"));
+
+  const savedKeys = Object.keys(storage.saved?.entries ?? {});
+  assert.ok(savedKeys.length <= 200, `entries bounded at MAX_BUFFER_ENTRY_COUNT (got ${savedKeys.length})`);
+  assert.ok(savedKeys.includes("session-newest"), "the just-written key is retained");
+  assert.equal(buffer.getTurns("session-000").length, 0, "oldest non-empty entry was evicted");
+  assert.ok(buffer.getTurns("session-209").length > 0, "newest pre-existing entry survives");
 });

package/src/buffer.ts

@@ -206,28 +206,52 @@ export class SmartBuffer {
     if (keys.length <= MAX_BUFFER_ENTRY_COUNT) return;
 
     const insertionOrder = new Map(keys.map((key, index) => [key, index]));
-    const removable = keys
-      .filter((key) => key !== "default" && !retainKeys.includes(key))
-      .filter((key) => (entries[key]?.turns.length ?? 0) === 0)
-      .sort((left, right) => {
-        const leftAt = this.entryActivityAt(entries[left] ?? {
-          turns: [],
-          lastExtractionAt: null,
-          extractionCount: 0,
-        });
-        const rightAt = this.entryActivityAt(entries[right] ?? {
-          turns: [],
-          lastExtractionAt: null,
-          extractionCount: 0,
-        });
-        if (leftAt !== rightAt) return leftAt - rightAt;
-        return (insertionOrder.get(left) ?? 0) - (insertionOrder.get(right) ?? 0);
+    const byOldestActivity = (left: string, right: string): number => {
+      const leftAt = this.entryActivityAt(entries[left] ?? {
+        turns: [],
+        lastExtractionAt: null,
+        extractionCount: 0,
       });
+      const rightAt = this.entryActivityAt(entries[right] ?? {
+        turns: [],
+        lastExtractionAt: null,
+        extractionCount: 0,
+      });
+      if (leftAt !== rightAt) return leftAt - rightAt;
+      return (insertionOrder.get(left) ?? 0) - (insertionOrder.get(right) ?? 0);
+    };
+    const candidates = keys.filter((key) => key !== "default" && !retainKeys.includes(key));
+    const emptyRemovable = candidates
+      .filter((key) => (entries[key]?.turns.length ?? 0) === 0)
+      .sort(byOldestActivity);
 
     const removableCount = Math.max(0, keys.length - MAX_BUFFER_ENTRY_COUNT);
-    for (const key of removable.slice(0, removableCount)) {
+    let evicted = emptyRemovable.slice(0, removableCount);
+    if (evicted.length < removableCount) {
+      // Retained failed extractions (#1908 retry retention) keep their turns in
+      // the buffer, so empty entries alone may not bring the map back under the
+      // cap during a provider outage. The cap is the documented bound — evict
+      // the oldest NON-empty sessions too rather than growing unboundedly
+      // (codex review).
+      const nonEmptyRemovable = candidates
+        .filter((key) => (entries[key]?.turns.length ?? 0) > 0)
+        .sort(byOldestActivity);
+      evicted = evicted.concat(nonEmptyRemovable.slice(0, removableCount - evicted.length));
+    }
+    for (const key of evicted) {
       delete entries[key];
     }
+    if (evicted.length > 0) {
+      // Loud degradation (extraction hot-loop hardening, Step 7): during a
+      // prolonged provider outage the breaker holds extraction off and buffered
+      // sessions accumulate. Eviction of the oldest empty session entries past
+      // MAX_BUFFER_ENTRY_COUNT is bounded and expected, but must be observable —
+      // not silent — so operators can see buffer pressure.
+      log.warn(
+        `buffer: pruned ${evicted.length} oldest session entr${evicted.length === 1 ? "y" : "ies"} ` +
+          `past MAX_BUFFER_ENTRY_COUNT=${MAX_BUFFER_ENTRY_COUNT}; buffered turn data for those sessions was dropped`,
+      );
+    }
   }
 
   private async loadUnlocked(): Promise<void> {

package/src/capabilities.test.ts

@@ -366,6 +366,7 @@ const LIFECYCLE_FIELD_TO_FLAG: Record<keyof MemoryLifecycleCapabilitySet, string
   extractionScopeClassification: "extractionScopeClassificationEnabled",
   extractionJudge: "extractionJudgeEnabled",
   extractionDedupe: "extractionDedupeEnabled",
+  extractionRetry: "extractionRetryEnabled",
   extractionTelemetryPrefilter: "extractionTelemetryPrefilterEnabled",
   extractionJudgeTelemetry: "extractionJudgeTelemetryEnabled",
   embeddingFallback: "embeddingFallbackEnabled",

package/src/capabilities.ts

@@ -257,6 +257,8 @@ export interface MemoryLifecycleCapabilitySet {
   readonly extractionJudgeTelemetry: boolean;
   /** `embeddingFallbackEnabled` — semantic-dedup / archive-search embedding fallback. */
   readonly embeddingFallback: boolean;
+  /** `extractionRetryEnabled` — per-fingerprint backoff + provider circuit breaker on the extraction retry path. */
+  readonly extractionRetry: boolean;
 }
 
 /**
@@ -275,6 +277,7 @@ export type MemoryLifecycleConfigProjection = Pick<
   | "extractionTelemetryPrefilterEnabled"
   | "extractionJudgeTelemetryEnabled"
   | "embeddingFallbackEnabled"
+  | "extractionRetryEnabled"
 >;
 
 /**
@@ -299,6 +302,7 @@ export function resolveMemoryLifecycleCapabilities(
     extractionTelemetryPrefilter: config.extractionTelemetryPrefilterEnabled,
     extractionJudgeTelemetry: config.extractionJudgeTelemetryEnabled,
     embeddingFallback: config.embeddingFallbackEnabled,
+    extractionRetry: config.extractionRetryEnabled,
   });
 }
 

package/src/config.test.ts

@@ -2142,3 +2142,22 @@ test("parseConfig correction.maxAffected rejects non-integers (Number.isInteger,
   assert.equal(parseConfig({ correctionMaxAffected: 20 }).correctionMaxAffected, 20);
   assert.equal(parseConfig({}).correctionMaxAffected, 10, "absent → documented default");
 });
+
+test("parseConfig rejects non-positive extraction retry/breaker numerics and falls back to defaults (codex review, rule 17)", () => {
+  const c = parseConfig({
+    extractionRetryMaxBackoffMs: 0,
+    extractionRetryJitterRatio: -0.5,
+    extractionParseEmptyMaxAttempts: 0,
+    extractionBreakerFailureThreshold: -1,
+    extractionBreakerCooldownMs: -5, // 0 is a valid "half-open immediately" escape hatch; only negative is rejected
+    extractionBreakerAuthCooldownMs: -100,
+    extractionRetryScheduleMs: [1000, 0, -5],
+  });
+  assert.equal(c.extractionRetryMaxBackoffMs, 21_600_000, "non-positive cap -> default");
+  assert.equal(c.extractionRetryJitterRatio, 0.2, "out-of-range jitter -> default");
+  assert.equal(c.extractionParseEmptyMaxAttempts, 3, "non-positive attempts -> default");
+  assert.equal(c.extractionBreakerFailureThreshold, 5, "non-positive threshold -> default");
+  assert.equal(c.extractionBreakerCooldownMs, 300_000, "non-positive cooldown -> default");
+  assert.equal(c.extractionBreakerAuthCooldownMs, 1_800_000, "non-positive auth cooldown -> default");
+  assert.deepEqual(c.extractionRetryScheduleMs, [60_000, 300_000, 1_800_000, 7_200_000], "schedule with non-positive entry -> default");
+});

package/src/config.ts

@@ -2826,6 +2826,35 @@ export function parseConfig(
       typeof cfg.localLlm400TripThreshold === "number" ? cfg.localLlm400TripThreshold : 5,
     localLlm400CooldownMs:
       typeof cfg.localLlm400CooldownMs === "number" ? cfg.localLlm400CooldownMs : 120_000,
+    // Extraction retry/backoff + circuit breaker (extraction hot-loop hardening)
+    extractionRetryEnabled: coerceBooleanLike(cfg.extractionRetryEnabled) ?? true,
+    extractionRetryScheduleMs:
+      Array.isArray(cfg.extractionRetryScheduleMs) &&
+      cfg.extractionRetryScheduleMs.length > 0 &&
+      cfg.extractionRetryScheduleMs.every((n) => typeof n === "number" && Number.isFinite(n) && n > 0)
+        ? (cfg.extractionRetryScheduleMs as number[])
+        : [60_000, 300_000, 1_800_000, 7_200_000],
+    extractionRetryMaxBackoffMs:
+      typeof cfg.extractionRetryMaxBackoffMs === "number" && cfg.extractionRetryMaxBackoffMs > 0
+        ? cfg.extractionRetryMaxBackoffMs : 21_600_000,
+    extractionRetryJitterRatio:
+      typeof cfg.extractionRetryJitterRatio === "number" &&
+      cfg.extractionRetryJitterRatio >= 0 && cfg.extractionRetryJitterRatio <= 1
+        ? cfg.extractionRetryJitterRatio : 0.2,
+    extractionParseEmptyMaxAttempts:
+      typeof cfg.extractionParseEmptyMaxAttempts === "number" &&
+      Number.isInteger(cfg.extractionParseEmptyMaxAttempts) && cfg.extractionParseEmptyMaxAttempts > 0
+        ? cfg.extractionParseEmptyMaxAttempts : 3,
+    extractionBreakerFailureThreshold:
+      typeof cfg.extractionBreakerFailureThreshold === "number" &&
+      Number.isInteger(cfg.extractionBreakerFailureThreshold) && cfg.extractionBreakerFailureThreshold > 0
+        ? cfg.extractionBreakerFailureThreshold : 5,
+    extractionBreakerCooldownMs:
+      typeof cfg.extractionBreakerCooldownMs === "number" && cfg.extractionBreakerCooldownMs >= 0
+        ? cfg.extractionBreakerCooldownMs : 300_000,
+    extractionBreakerAuthCooldownMs:
+      typeof cfg.extractionBreakerAuthCooldownMs === "number" && cfg.extractionBreakerAuthCooldownMs >= 0
+        ? cfg.extractionBreakerAuthCooldownMs : 1_800_000,
     // Local LLM fast tier (v9.1)
     localLlmFastEnabled: cfg.localLlmFastEnabled === true,
     localLlmFastModel:

package/src/extraction.test.ts

@@ -0,0 +1,39 @@
+/**
+ * Extraction failure-classification tests (extraction hot-loop hardening).
+ *
+ * The retry/backoff + circuit-breaker layer keys off `ExtractionFailureClass`.
+ * These tests lock the mapping from synthetic provider errors (429/500/401/
+ * no-models/parse-empty) to the coarse class, reusing the shared
+ * `isTransientHttpError` classifier rather than a bespoke copy.
+ */
+
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import { classifyExtractionThrownError, classifyFallbackParseFailure } from "./extraction.js";
+
+test("classifyExtractionThrownError: 401/403 → auth_config", () => {
+  assert.equal(classifyExtractionThrownError({ status: 401 }), "auth_config");
+  assert.equal(classifyExtractionThrownError({ status: 403 }), "auth_config");
+  assert.equal(classifyExtractionThrownError({ statusCode: 401 }), "auth_config");
+});
+
+test("classifyExtractionThrownError: 429/5xx → provider_retryable", () => {
+  assert.equal(classifyExtractionThrownError({ status: 429 }), "provider_retryable");
+  assert.equal(classifyExtractionThrownError({ status: 500 }), "provider_retryable");
+  assert.equal(classifyExtractionThrownError({ status: 503 }), "provider_retryable");
+});
+
+test("classifyExtractionThrownError: bare network error / unknown → provider_retryable (fail-open toward retry)", () => {
+  assert.equal(classifyExtractionThrownError(new Error("socket hang up")), "provider_retryable");
+  // A terminal non-auth 4xx still defaults to retryable (capped by the attempt budget).
+  assert.equal(classifyExtractionThrownError({ status: 400 }), "provider_retryable");
+  assert.equal(classifyExtractionThrownError(null), "provider_retryable");
+  assert.equal(classifyExtractionThrownError("not an object"), "provider_retryable");
+});
+
+test("classifyFallbackParseFailure: maps the gateway parse-failure reasons", () => {
+  assert.equal(classifyFallbackParseFailure("no_models"), "auth_config");
+  assert.equal(classifyFallbackParseFailure("http_error"), "provider_retryable");
+  assert.equal(classifyFallbackParseFailure("empty"), "parse_empty");
+});

package/src/extraction.ts

@@ -26,6 +26,7 @@ import type {
   GatewayConfig,
   MemoryCategory,
   DaySummaryResult as DaySummaryResultShape,
+  ExtractionFailureClass,
 } from "./types.js";
 import { ModelRegistry } from "./model-registry.js";
 import { extractJsonCandidates } from "./json-extract.js";
@@ -38,6 +39,7 @@ import { normalizeProcedureSteps } from "./procedural/procedure-types.js";
 import { normalizeReasoningTrace } from "./reasoning-trace-types.js";
 import { looksLikeMechanicalTelemetryTranscript } from "./telemetry-transcript.js";
 import { buildFactProvenance, type ProvenanceTurnInput } from "./provenance.js";
+import { isTransientHttpError } from "./connectors/live/transient-errors.js";
 import { resolvePipelineProcessingCapabilities } from "./capabilities.js";
 import { resolveMemoryLifecycleCapabilities,
   resolveLocalLlmCapabilities,resolveRecallAuxiliaryCapabilities } from "./capabilities.js";
@@ -46,6 +48,56 @@ type ExtractionQuestion = ExtractionResult["questions"][number];
 type ExtractedFactResult = ExtractionResult["facts"][number];
 type ExtractedEntityResult = ExtractionResult["entities"][number];
 type ExtractedRelationshipResult = NonNullable<ExtractionResult["relationships"]>[number];
+
+/**
+ * Read a numeric HTTP status off a thrown error without re-implementing the
+ * shared transient classifier. Uses `in`/typeof narrowing (no inline casts).
+ */
+function httpStatusFromError(err: unknown): number | undefined {
+  if (!err || typeof err !== "object") return undefined;
+  if ("status" in err && typeof err.status === "number" && Number.isFinite(err.status)) return err.status;
+  if ("statusCode" in err && typeof err.statusCode === "number" && Number.isFinite(err.statusCode)) {
+    return err.statusCode;
+  }
+  return undefined;
+}
+
+/**
+ * Map a thrown extraction error to a coarse failure class for the retry/breaker
+ * layer. 401/403 → `auth_config` (misconfigured provider, open the breaker);
+ * transient (429/5xx/network, per the shared `isTransientHttpError`) → back off;
+ * anything else defaults to `provider_retryable` (fail-open toward retry, but
+ * capped by the per-fingerprint attempt budget). Never throws.
+ */
+export function classifyExtractionThrownError(err: unknown): ExtractionFailureClass {
+  try {
+    const status = httpStatusFromError(err);
+    if (status === 401 || status === 403) return "auth_config";
+    if (isTransientHttpError(err)) return "provider_retryable";
+    return "provider_retryable";
+  } catch {
+    return "provider_retryable";
+  }
+}
+
+/**
+ * Map the gateway fallback's discriminated parse-failure reason to a coarse
+ * extraction failure class. "no models configured" is an auth/config problem;
+ * an HTTP/transport failure backs off; an unparseable-but-present response is a
+ * genuine empty-parse.
+ */
+export function classifyFallbackParseFailure(
+  reason: "no_models" | "empty" | "http_error",
+): ExtractionFailureClass {
+  switch (reason) {
+    case "no_models":
+      return "auth_config";
+    case "http_error":
+      return "provider_retryable";
+    case "empty":
+      return "parse_empty";
+  }
+}
 const PROACTIVE_MIN_CONFIDENCE = 0.8;
 const CONSOLIDATION_RESPONSE_SCHEMA = `{
   "items": [
@@ -975,7 +1027,7 @@ export class ExtractionEngine {
     options: { temperature?: number; maxTokens?: number } = {},
   ): Promise<T | null> {
     const detailed = await this.fallbackLlm.parseWithSchemaDetailed(messages, schema, this.withGatewayAgent(options));
-    if (detailed?.result) {
+    if ("modelUsed" in detailed) {
       const durationMs = Date.now() - startedAtMs;
       this.emit({
         kind: "llm_end",
@@ -1119,11 +1171,16 @@ export class ExtractionEngine {
       localLlm: resolveLocalLlmCapabilities(this.config).localLlm,
     });
     this.profiler.startSpan("total", extractionTraceId);
+    // True when a local or direct extractor was attempted before the gateway
+    // fallback, so a gateway "no models" result doesn't re-classify a real
+    // primary failure as auth_config (codex review: preserve direct/local failures).
+    let primaryExtractorAttempted = false;
 
     try {
     // Try local LLM first if enabled
     if (this.shouldUseLocalLlm) {
       this.profiler.startSpan("local-llm", extractionTraceId);
+      primaryExtractorAttempted = true;
       try {
         const localResult = await this.extractWithLocalLlm(conversation, existingEntities);
         if (localResult) {
@@ -1144,6 +1201,7 @@ export class ExtractionEngine {
             entities: [],
             questions: [],
             extractionFailure: "local_llm_unavailable",
+            extractionFailureClass: "provider_retryable",
           };
         }
         log.info("extraction: local LLM unavailable, falling back to gateway default AI");
@@ -1156,6 +1214,7 @@ export class ExtractionEngine {
             entities: [],
             questions: [],
             extractionFailure: "local_llm_error",
+            extractionFailureClass: "provider_retryable",
           };
         }
         log.info("extraction: local LLM error, falling back to gateway default AI:", err);
@@ -1168,6 +1227,7 @@ export class ExtractionEngine {
     // Try direct OpenAI-compatible client (Scryr, OpenRouter, etc.)
     if (this.shouldUseDirectClient) {
       this.profiler.startSpan("direct-client", extractionTraceId);
+      primaryExtractorAttempted = true;
       try {
         const directResult = await this.extractWithDirectClient(conversation, existingEntities);
         if (directResult) {
@@ -1250,7 +1310,7 @@ export class ExtractionEngine {
 
       const fallbackDurationMs = Date.now() - fallbackStartTime;
 
-      if (detailed?.result && Array.isArray(detailed.result.facts)) {
+      if ("modelUsed" in detailed && Array.isArray(detailed.result.facts)) {
         const result = detailed.result;
         this.emit({
           kind: "llm_end", traceId: fallbackTraceId, model: detailed.modelUsed, operation: "extraction",
@@ -1299,12 +1359,21 @@ export class ExtractionEngine {
         durationMs: fallbackDurationMs, error: "fallback returned no parsed output",
       });
       log.warn("extraction fallback returned no parsed output");
+      const fallbackParseFailureClass: ExtractionFailureClass =
+        detailed.result === null
+          ? detailed.failureReason === "no_models" && primaryExtractorAttempted
+            ? // Gateway had no models, but a local/direct extractor already failed —
+              // the root cause is the primary (transient), not gateway auth/config.
+              "provider_retryable"
+            : classifyFallbackParseFailure(detailed.failureReason)
+          : "parse_empty";
       return {
         facts: [],
         profileUpdates: [],
         entities: [],
         questions: [],
         extractionFailure: "fallback_no_parsed_output",
+        extractionFailureClass: fallbackParseFailureClass,
       };
     } catch (err) {
       this.emit({
@@ -1318,6 +1387,7 @@ export class ExtractionEngine {
         entities: [],
         questions: [],
         extractionFailure: "fallback_failed",
+        extractionFailureClass: classifyExtractionThrownError(err),
       };
     } finally {
       try { this.profiler.endSpan("gateway-fallback", extractionTraceId); } catch { /* span may already be closed */ }

package/src/fallback-llm.ts

@@ -280,9 +280,30 @@ export class FallbackLlmClient {
     messages: Array<{ role: "system" | "user" | "assistant"; content: string }>,
     schema: { parse: (data: unknown) => T },
     options: FallbackLlmOptions = {},
-  ): Promise<{ result: T; modelUsed: string } | null> {
-    const response = await this.chatCompletion(messages, options);
-    if (!response?.content) return null;
+  ): Promise<
+    | { result: T; modelUsed: string }
+    | { result: null; failureReason: "no_models" | "empty" | "http_error" }
+  > {
+    let response: FallbackLlmResponse | null;
+    try {
+      response = await this.chatCompletion(messages, options);
+    } catch (err) {
+      // Caller aborts must propagate (e.g. recall planner cancellation) — do
+      // not swallow them as a provider failure, or abort-driven callers lose
+      // cancellation and treat it as an extraction error (codex review).
+      if (options.signal?.aborted) throw err;
+      log.warn("fallback LLM: chatCompletion threw during structured parse:", err);
+      return { result: null, failureReason: "http_error" };
+    }
+    if (!response?.content) {
+      // chatCompletion returns null both when no models are configured
+      // (auth/config) and when every configured model errored (transient).
+      // Disambiguate via the resolved model chain so the retry layer can pick
+      // the right failure class.
+      const hasModels =
+        this.getModelChain(options.agentId, options.model, options.modelChain).length > 0;
+      return { result: null, failureReason: hasModels ? "http_error" : "no_models" };
+    }
 
     try {
       const candidates = extractJsonCandidates(response.content);
@@ -294,10 +315,10 @@ export class FallbackLlmClient {
           // keep trying other candidates
         }
       }
-      return null;
+      return { result: null, failureReason: "empty" };
     } catch (err) {
       log.warn("fallback LLM: failed to parse structured output:", err);
-      return null;
+      return { result: null, failureReason: "empty" };
     }
   }
 

package/src/operator-toolkit.ts

@@ -1272,6 +1272,59 @@ export async function runOperatorDoctor(options: OperatorDoctorOptions): Promise
     details: meta,
   });
 
+  // Extraction resilience (extraction hot-loop hardening). Surfaces the
+  // persisted per-fingerprint retry/backoff state so an operator can see when
+  // the extraction provider is failing without tailing logs. auth/config
+  // failures are an error (misconfigured provider, will not self-heal at the
+  // current cadence); transient backoff is a warn; a clean state is ok. Reads
+  // the already-loaded meta — no extra I/O, cross-process safe (the in-memory
+  // breaker lives in the daemon; this derives from durable state).
+  const retryEntries = meta.extractionRetryState ?? [];
+  const authConfigFailures = retryEntries.filter((entry) => entry.lastFailureClass === "auth_config");
+  const nowMs = Date.now();
+  const parkedFingerprints = retryEntries.filter((entry) => {
+    const eligibleAt = Date.parse(entry.nextEligibleAt);
+    return Number.isFinite(eligibleAt) && eligibleAt > nowMs;
+  });
+  // The in-memory breaker opens only after extractionBreakerFailureThreshold
+  // CONSECUTIVE provider failures, each of which parks a fingerprint — so
+  // doctor infers "likely open" only when the parked transient count reaches
+  // that threshold. A single parked fingerprint is ordinary backoff, not a
+  // suspended-extraction signal (cursor review: don't overclaim). The breaker
+  // itself is per-process (daemon-only), hence the durable-signal inference.
+  const providerRetryableParked = parkedFingerprints.filter(
+    (entry) => entry.lastFailureClass === "provider_retryable",
+  );
+  const breakerLikelyOpen =
+    providerRetryableParked.length >= Math.max(1, config.extractionBreakerFailureThreshold);
+  const resilienceStatus: "ok" | "warn" | "error" =
+    authConfigFailures.length > 0 ? "error" : parkedFingerprints.length > 0 ? "warn" : "ok";
+  checks.push({
+    key: "extraction-resilience",
+    status: resilienceStatus,
+    summary:
+      resilienceStatus === "error"
+        ? `Extraction provider has ${authConfigFailures.length} auth/config failure(s); the circuit breaker opens immediately and extraction is suspended.`
+        : resilienceStatus === "warn"
+          ? `${parkedFingerprints.length} extraction fingerprint(s) in backoff after transient provider failures${
+              breakerLikelyOpen ? "; the provider circuit breaker is likely OPEN in the daemon (non-forced extraction is suspended until it half-opens)" : ""
+            }.`
+          : "No extraction provider failures are currently parked.",
+    remediation:
+      resilienceStatus === "error"
+        ? 'Check the extraction LLM gateway/model configuration (a 401/403 or "no models configured" was seen). Extraction resumes automatically once the provider is reachable.'
+        : resilienceStatus === "warn"
+          ? "Transient provider failures (e.g. 429/5xx). Backoff clears automatically as the provider recovers; no action needed unless it persists."
+          : undefined,
+    details: {
+      backoffFingerprintCount: retryEntries.length,
+      authConfigFailureCount: authConfigFailures.length,
+      parkedFingerprintCount: parkedFingerprints.length,
+      providerRetryableParkedCount: providerRetryableParked.length,
+      breakerLikelyOpen,
+    },
+  });
+
   // Memory projection health (issue #1829). Surfaces a present-but-unopenable
   // projection (wrong ABI / corrupt) that previously degraded every memory
   // list to a silent full-corpus scan. Absent and openable are both "ok".