@remnic/core 9.6.39 → 9.7.0

package/src/orchestration/extraction-run.ts

@@ -40,7 +40,7 @@ import {
 } from "../capabilities.js";
 import { parseFlexibleIsoTimestamp } from "../utils/iso-timestamp.js";
 import { log } from "../logger.js";
-import type { PluginConfig, BufferTurn, ExtractionResult } from "../types.js";
+import type { PluginConfig, BufferTurn, ExtractionResult, MetaState, ExtractionFailureClass } from "../types.js";
 import type { TierMigrationCycleSummary } from "../recall-state.js";
 
 export interface ExtractionRunResult {
@@ -130,6 +130,66 @@ export function deriveTopicsFromExtraction(result: ExtractionResult): string[] {
   return [...topics].slice(0, 16);
 }
 
+/** Bounded cap on persisted per-fingerprint retry-state entries (per namespace meta). */
+const EXTRACTION_RETRY_STATE_MAX_ENTRIES = 500;
+
+interface ExtractionRetryStateEntry {
+  attempts: number;
+  nextEligibleAtMs: number;
+  firstFailedAtMs: number;
+  lastFailureClass: ExtractionFailureClass;
+}
+
+export interface ExtractionResilienceStatus {
+  breaker: {
+    state: "closed" | "open" | "half_open";
+    openUntilMs: number;
+    consecutiveFailures: number;
+    lastReason: string;
+  };
+  backoffFingerprintCount: number;
+}
+
+/**
+ * Pure backoff scheduler. Returns the absolute ms timestamp at which a
+ * fingerprint that has failed `attempts` times becomes eligible again:
+ * exponential via the configured schedule, clamped to `maxBackoffMs`, with
+ * ±`jitterRatio` multiplicative jitter. `rng` is injectable for deterministic
+ * tests. Never returns a timestamp before `now`.
+ */
+export function computeExtractionRetryNextEligibleMs(
+  attempts: number,
+  scheduleMs: readonly number[],
+  maxBackoffMs: number,
+  jitterRatio: number,
+  now: number,
+  rng: () => number = Math.random,
+): number {
+  const cap = Number.isFinite(maxBackoffMs) && maxBackoffMs > 0 ? maxBackoffMs : 0;
+  if (!Array.isArray(scheduleMs) || scheduleMs.length === 0) {
+    return now + cap;
+  }
+  const idx = Math.min(Math.max(attempts - 1, 0), scheduleMs.length - 1);
+  const step = scheduleMs[idx];
+  const base = Math.min(typeof step === "number" && step > 0 ? step : cap, cap);
+  const jitter = 1 + (rng() * 2 - 1) * jitterRatio;
+  return now + Math.max(0, Math.round(base * jitter));
+}
+
+/**
+ * Cap the persisted retry-state array to the newest `maxEntries` by
+ * firstFailedAt. Guards `maxEntries <= 0` so a zero cap returns [] rather than
+ * `slice(-0)`, which returns ALL entries (AGENTS.md rule 17).
+ */
+export function capExtractionRetryStateEntries<T extends { firstFailedAt: string }>(
+  entries: readonly T[],
+  maxEntries: number,
+): T[] {
+  if (maxEntries <= 0) return [];
+  const sorted = [...entries].sort((a, b) => a.firstFailedAt.localeCompare(b.firstFailedAt));
+  return sorted.slice(-maxEntries);
+}
+
 /**
  * Coordinates the extraction run pipeline. Holds the dedupe fingerprint
  * cache (`recentExtractionFingerprints`) and delegates all side effects
@@ -137,6 +197,21 @@ export function deriveTopicsFromExtraction(result: ExtractionResult): string[] {
  */
 export class ExtractionRunCoordinator {
   private readonly recentExtractionFingerprints = new Map<string, number>();
+  // Per-fingerprint extraction retry/backoff state (extraction hot-loop
+  // hardening). Outer key = namespace, inner key = fingerprint. Hydrated lazily
+  // from namespace-scoped meta so the hot path is a Map lookup; persisted back
+  // to meta on change (restart-safe, cross-process coherent via the shared
+  // meta.json). The breaker below is intentionally per-process in-memory
+  // (mirrors local-llm.cooldownUntilMs); a restart clears it but the persisted
+  // backoff still throttles, so a restart can't resurrect the hot loop.
+  private readonly extractionRetryState = new Map<string, Map<string, ExtractionRetryStateEntry>>();
+  private readonly hydratedRetryNamespaces = new Set<string>();
+  private providerBreaker: {
+    consecutiveFailures: number;
+    openUntilMs: number;
+    state: "closed" | "open" | "half_open";
+    lastReason: string;
+  } = { consecutiveFailures: 0, openUntilMs: 0, state: "closed", lastReason: "" };
 
   constructor(private readonly deps: ExtractionRunCoordinatorDeps) {}
 
@@ -238,6 +313,181 @@ export class ExtractionRunCoordinator {
     }
   }
 
+  // -------------------------------------------------------------------------
+  // Extraction retry/backoff + circuit breaker (extraction hot-loop hardening)
+  // -------------------------------------------------------------------------
+
+  /** Lazily hydrate the in-memory retry-state mirror for a namespace from meta.
+   *  One-time per namespace per coordinator; the hot path is then a Map lookup.
+   *  Cross-process coherence: a fresh coordinator hydrates from the shared
+   *  meta.json, so a failure persisted by another process is honored here. */
+  private hydrateRetryStateFromMeta(namespace: string, meta: MetaState): void {
+    if (this.hydratedRetryNamespaces.has(namespace)) return;
+    this.hydratedRetryNamespaces.add(namespace);
+    const nsMap = this.extractionRetryState.get(namespace) ?? new Map<string, ExtractionRetryStateEntry>();
+    for (const entry of meta.extractionRetryState ?? []) {
+      const nextEligibleAtMs = Date.parse(entry.nextEligibleAt);
+      const firstFailedAtMs = Date.parse(entry.firstFailedAt);
+      nsMap.set(entry.fingerprint, {
+        attempts: entry.attempts,
+        nextEligibleAtMs: Number.isFinite(nextEligibleAtMs) ? nextEligibleAtMs : 0,
+        firstFailedAtMs: Number.isFinite(firstFailedAtMs) ? firstFailedAtMs : Date.now(),
+        lastFailureClass: entry.lastFailureClass,
+      });
+    }
+    this.extractionRetryState.set(namespace, nsMap);
+  }
+
+  private logBreakerTransition(state: "closed" | "open" | "half_open"): void {
+    // Once per state change (not per attempt) — AGENTS.md observability rule.
+    log.warn("extraction: provider circuit breaker transition", {
+      state,
+      consecutiveFailures: this.providerBreaker.consecutiveFailures,
+      lastReason: this.providerBreaker.lastReason,
+      openUntilMs: this.providerBreaker.openUntilMs,
+    });
+  }
+
+  /** True while the breaker suppresses non-forced attempts. Flips an expired
+   *  `open` breaker to `half_open`, which allows exactly one probe (the next
+   *  non-forced attempt) because the extraction queue is a serial drain. */
+  private isProviderBreakerOpen(now: number): boolean {
+    if (now < this.providerBreaker.openUntilMs) return true;
+    if (this.providerBreaker.state === "open") {
+      this.providerBreaker.state = "half_open";
+      this.logBreakerTransition("half_open");
+    }
+    return false;
+  }
+
+  private onProviderFailure(cls: ExtractionFailureClass, now: number): void {
+    this.providerBreaker.consecutiveFailures += 1;
+    const trip =
+      cls === "auth_config" ||
+      // A failed half-open probe re-opens immediately (standard breaker
+      // semantics). Without this, an auth_config-opened breaker (which trips
+      // below the threshold) would get stuck half_open after a transient
+      // probe failure and stop suppressing (cursor review).
+      this.providerBreaker.state === "half_open" ||
+      this.providerBreaker.consecutiveFailures >= this.config.extractionBreakerFailureThreshold;
+    if (!trip) return;
+    const cooldown =
+      cls === "auth_config"
+        ? this.config.extractionBreakerAuthCooldownMs
+        : this.config.extractionBreakerCooldownMs;
+    this.providerBreaker.openUntilMs = now + Math.max(0, cooldown);
+    this.providerBreaker.lastReason = cls;
+    if (this.providerBreaker.state !== "open") {
+      this.providerBreaker.state = "open";
+      this.logBreakerTransition("open");
+    }
+  }
+
+  private resetProviderBreakerOnSuccess(): void {
+    const wasDisturbed =
+      this.providerBreaker.state !== "closed" ||
+      this.providerBreaker.consecutiveFailures > 0 ||
+      this.providerBreaker.openUntilMs > 0;
+    if (!wasDisturbed) return;
+    const wasOpen = this.providerBreaker.state !== "closed";
+    this.providerBreaker.consecutiveFailures = 0;
+    this.providerBreaker.openUntilMs = 0;
+    this.providerBreaker.lastReason = "";
+    this.providerBreaker.state = "closed";
+    if (wasOpen) this.logBreakerTransition("closed");
+  }
+
+  /** Rebuild `meta.extractionRetryState` from the in-memory namespace mirror,
+   *  bounded to the newest entries, and prune the mirror to match. */
+  private persistRetryStateToMeta(namespace: string, meta: MetaState): void {
+    const nsMap = this.extractionRetryState.get(namespace);
+    const entries = nsMap
+      ? Array.from(nsMap.entries()).map(([fingerprint, st]) => ({
+          fingerprint,
+          attempts: st.attempts,
+          nextEligibleAt: new Date(st.nextEligibleAtMs).toISOString(),
+          firstFailedAt: new Date(st.firstFailedAtMs).toISOString(),
+          lastFailureClass: st.lastFailureClass,
+        }))
+      : [];
+    const capped = capExtractionRetryStateEntries(entries, EXTRACTION_RETRY_STATE_MAX_ENTRIES);
+    meta.extractionRetryState = capped;
+    if (nsMap && capped.length < nsMap.size) {
+      const kept = new Set(capped.map((e) => e.fingerprint));
+      for (const key of Array.from(nsMap.keys())) {
+        if (!kept.has(key)) nsMap.delete(key);
+      }
+    }
+  }
+  /** Record an extraction failure into per-fingerprint backoff state + breaker,
+   *  persisting to namespace meta. Fail-open: never throws upward. */
+  private async recordExtractionFailure(
+    storage: StorageManager,
+    namespace: string,
+    fingerprint: string,
+    cls: ExtractionFailureClass,
+    meta: MetaState,
+    now: number,
+  ): Promise<void> {
+    try {
+      this.hydrateRetryStateFromMeta(namespace, meta);
+      const nsMap = this.extractionRetryState.get(namespace) ?? new Map<string, ExtractionRetryStateEntry>();
+      const prev = nsMap.get(fingerprint);
+      const attempts = (prev?.attempts ?? 0) + 1;
+      const firstFailedAtMs = prev?.firstFailedAtMs ?? now;
+      let nextEligibleAtMs: number;
+      if (cls === "parse_empty" && attempts > this.config.extractionParseEmptyMaxAttempts) {
+        // parse_empty exhausted its attempt budget → long-park (still never
+        // marked processed). A dead gateway also yields unparseable output.
+        nextEligibleAtMs = now + Math.max(0, this.config.extractionRetryMaxBackoffMs);
+      } else {
+        nextEligibleAtMs = computeExtractionRetryNextEligibleMs(
+          attempts,
+          this.config.extractionRetryScheduleMs,
+          this.config.extractionRetryMaxBackoffMs,
+          this.config.extractionRetryJitterRatio,
+          now,
+        );
+      }
+      nsMap.set(fingerprint, { attempts, nextEligibleAtMs, firstFailedAtMs, lastFailureClass: cls });
+      this.extractionRetryState.set(namespace, nsMap);
+      this.onProviderFailure(cls, now);
+      this.persistRetryStateToMeta(namespace, meta);
+      await storage.saveMeta(meta);
+    } catch (err) {
+      // Fail-open: recording failure state must never crash observe/recall.
+      log.warn("runExtraction: failed to record extraction retry state (non-fatal)", err);
+    }
+  }
+
+  /** Delete a fingerprint's retry entry from the mirror + meta. Returns whether
+   *  meta changed (so the caller can decide to persist). Does not touch the
+   *  breaker — callers pair this with `resetProviderBreakerOnSuccess`. */
+  private clearExtractionRetryEntry(namespace: string, fingerprint: string, meta: MetaState): boolean {
+    const nsMap = this.extractionRetryState.get(namespace);
+    if (!nsMap?.has(fingerprint)) return false;
+    nsMap.delete(fingerprint);
+    this.persistRetryStateToMeta(namespace, meta);
+    return true;
+  }
+
+  /** Live in-process resilience snapshot (breaker + backoff population). */
+  getExtractionResilienceStatus(): ExtractionResilienceStatus {
+    let backoffFingerprintCount = 0;
+    for (const nsMap of this.extractionRetryState.values()) {
+      backoffFingerprintCount += nsMap.size;
+    }
+    return {
+      breaker: {
+        state: this.providerBreaker.state,
+        openUntilMs: this.providerBreaker.openUntilMs,
+        consecutiveFailures: this.providerBreaker.consecutiveFailures,
+        lastReason: this.providerBreaker.lastReason,
+      },
+      backoffFingerprintCount,
+    };
+  }
+
   // -------------------------------------------------------------------------
   // Main extraction pipeline
   // -------------------------------------------------------------------------
@@ -268,6 +518,14 @@ export class ExtractionRunCoordinator {
        * (un-prefixed) key and storage is pinned via `writeNamespaceOverride`.
        */
       principalOverride?: string;
+      /**
+       * Force the extractor call, bypassing the retry-backoff / circuit-breaker
+       * gate (extraction hot-loop hardening). Set by explicit flush paths
+       * (before_reset / session flush / replay / bulk import) that already pass
+       * `skipDedupeCheck: true` — AGENTS.md rule 18. A forced attempt still
+       * records its failure into retry-state/breaker.
+       */
+      forceExtractionAttempt?: boolean;
     } = {}
   ): Promise<ExtractionRunResult> {
     log.debug(`running extraction on ${turns.length} turns`);
@@ -463,6 +721,54 @@ export class ExtractionRunCoordinator {
       };
     }
 
+    // Extraction retry/backoff + circuit-breaker gate (extraction hot-loop
+    // hardening). Suppresses re-attempts of a recently-failed fingerprint and
+    // short-circuits every fingerprint while the provider breaker is open, so a
+    // failing LLM endpoint is not hammered once per observe. Forced flushes and
+    // fail-closed callers bypass the gate (rule 18) but still record failures.
+    // On a suppressed attempt the buffer is deliberately NOT cleared, so no
+    // extractable turn is dropped — it is retried after cooldown/nextEligibleAt.
+    const forcedExtractionAttempt =
+      options.failOnExtractionFailure === true || options.forceExtractionAttempt === true;
+    // Resolve the gate through the shared lifecycle capability plan (issue
+    // #1523) rather than reading the raw config flag at each call site.
+    const extractionRetryEnabled = resolveMemoryLifecycleCapabilities(this.config).extractionRetry;
+    if (extractionFingerprint && !forcedExtractionAttempt && extractionRetryEnabled) {
+      try {
+        meta ??= await storage.loadMeta();
+        this.hydrateRetryStateFromMeta(selfNamespace, meta);
+        const nowMs = Date.now();
+        let suppressReason: "provider_circuit_open" | "extraction_backoff" | null = null;
+        if (this.isProviderBreakerOpen(nowMs)) {
+          suppressReason = "provider_circuit_open";
+        } else {
+          const st = this.extractionRetryState.get(selfNamespace)?.get(extractionFingerprint);
+          if (st && nowMs < st.nextEligibleAtMs) suppressReason = "extraction_backoff";
+        }
+        if (suppressReason) {
+          // Parity with the other skip paths: passive correction capture is
+          // local (no provider call) and must not be delayed by a provider
+          // cooldown — "stop calling me X" style turns should register during
+          // a 30-minute breaker window too (codex review). Fail-open.
+          try {
+            await this.deps.maybeCapturePassiveCorrections(normalizedTurns as BufferTurn[], {
+              sessionKey,
+              principal,
+              namespace: selfNamespace,
+              bufferKey,
+              isLiveSession: clearBufferAfterExtraction,
+            });
+          } catch (captureErr) {
+            log.warn("runExtraction: passive correction capture failed on suppressed attempt (non-fatal)", captureErr);
+          }
+          return { status: "skipped", reason: suppressReason, persistedCount: 0, durableOutputCount: 0 };
+        }
+      } catch (err) {
+        // Fail-open: a gate error must never block extraction.
+        log.warn("runExtraction: extraction retry gate check failed; proceeding (fail-open)", err);
+      }
+    }
+
     // Pass existing entity names so the LLM can reuse them instead of inventing variants
     const existingEntities = await storage.listEntityNames();
     const result = await raceRecallAbort(
@@ -517,6 +823,54 @@ export class ExtractionRunCoordinator {
       typeof result.extractionFailure === "string" && result.extractionFailure.trim().length > 0
         ? result.extractionFailure
         : undefined;
+    let recordedRetryFailure = false;
+    // Record failure into backoff/breaker state, or heal on success. Runs for
+    // every result path (empty and durable), before the fail-closed throw, so a
+    // forced flush still records its failure (rule 18). Gated by
+    // extractionRetryEnabled so a disabled feature restores prior behavior.
+    if (extractionFingerprint && extractionRetryEnabled) {
+      if (extractionFailure) {
+        try {
+          meta ??= await storage.loadMeta();
+          await this.recordExtractionFailure(
+            storage,
+            selfNamespace,
+            extractionFingerprint,
+            result.extractionFailureClass ?? "provider_retryable",
+            meta,
+            Date.now(),
+          );
+          // The buffer is retained below so the backoff gate can re-attempt
+          // these turns after nextEligibleAt — clearing would orphan the
+          // retry state.
+          recordedRetryFailure = true;
+        } catch (err) {
+          // Fail-open (codex review): retry bookkeeping is best-effort — a
+          // corrupt or locked meta store must not reject the extraction task.
+          // With no backoff recorded there is nothing to retain for, so the
+          // pre-#1908 clear-buffer behavior applies below.
+          log.warn("runExtraction: failed to load meta for retry bookkeeping (non-fatal)", err);
+        }
+      } else {
+        // Provider responded without failure → breaker heals; clear any
+        // parked backoff for this fingerprint so it proceeds normally.
+        this.resetProviderBreakerOnSuccess();
+        try {
+          meta ??= await storage.loadMeta();
+          // Hydrate the in-memory mirror from persisted meta before clearing.
+          // A forced flush (forceExtractionAttempt) bypasses the retry gate and
+          // never hydrated, so without this a stale persisted backoff entry
+          // would survive a successful forced flush and keep blocking normal
+          // extraction until the timer expired (cursor/codex review).
+          this.hydrateRetryStateFromMeta(selfNamespace, meta);
+          if (this.clearExtractionRetryEntry(selfNamespace, extractionFingerprint, meta)) {
+            await storage.saveMeta(meta);
+          }
+        } catch (err) {
+          log.warn("runExtraction: failed to persist cleared retry state (non-fatal)", err);
+        }
+      }
+    }
     if (options.failOnExtractionFailure && extractionFailure) {
       throw new Error(`extraction failed: ${extractionFailure}`);
     }
@@ -550,7 +904,17 @@ export class ExtractionRunCoordinator {
         bufferKey,
         isLiveSession: clearBufferAfterExtraction,
       });
-      await clearBuffer();
+      if (recordedRetryFailure) {
+        // Retain the failed turns so the backoff gate can re-attempt them after
+        // nextEligibleAt. Clearing here would lose the data the retry state
+        // points at (cursor high + codex P1). Trigger/forced paths already
+        // retain via clearBufferAfterExtraction=false; this covers the normal
+        // live-session path. Overflow is bounded by MAX_BUFFER_ENTRY_COUNT
+        // with a loud eviction log.
+        log.debug("runExtraction: retaining buffer for backoff retry after failure");
+      } else {
+        await clearBuffer();
+      }
       return { status: "skipped", reason: "empty_extraction_result", persistedCount: 0, durableOutputCount: 0 };
     }
 

package/src/orchestration/session-context.ts

@@ -52,6 +52,7 @@ export interface SessionContextDeps {
       skipUserTurnThreshold?: boolean;
       extractionDeadlineMs?: number;
       failOnExtractionFailure?: boolean;
+      forceExtractionAttempt?: boolean;
       onTaskSettled?: (
         error?: unknown,
         result?: ExtractionRunResult,
@@ -347,6 +348,7 @@ export class SessionContextCoordinator {
             bufferKey,
             clearBufferAfterExtraction: true,
             skipDedupeCheck: true,
+            forceExtractionAttempt: true,
             abortSignal: options.abortSignal,
             onTaskSettled: (error) => (error ? reject(error) : resolve()),
           })

package/src/orchestration/turn-ingestion.ts

@@ -68,6 +68,7 @@ export interface TurnIngestionDeps {
       skipUserTurnThreshold?: boolean;
       extractionDeadlineMs?: number;
       failOnExtractionFailure?: boolean;
+      forceExtractionAttempt?: boolean;
       onTaskSettled?: (
         error?: unknown,
         result?: ExtractionRunResult,
@@ -288,6 +289,7 @@ export class TurnIngestionCoordinator {
           new Promise<void>((resolve, reject) => {
             void this.deps.queueBufferedExtraction(sessionSlice, "trigger_mode", {
               skipDedupeCheck: true,
+              forceExtractionAttempt: true,
               clearBufferAfterExtraction: false,
               skipCharThreshold: true,
               skipUserTurnThreshold: true,
@@ -463,6 +465,7 @@ export class TurnIngestionCoordinator {
           (resolve, reject) => {
             void this.deps.queueBufferedExtraction(sessionSlice, "trigger_mode", {
               skipDedupeCheck: true,
+              forceExtractionAttempt: true,
               clearBufferAfterExtraction: false,
               skipCharThreshold: true,
               skipUserTurnThreshold: true,
@@ -606,6 +609,7 @@ export class TurnIngestionCoordinator {
       skipUserTurnThreshold?: boolean;
       extractionDeadlineMs?: number;
       failOnExtractionFailure?: boolean;
+      forceExtractionAttempt?: boolean;
       onTaskSettled?: (
         error?: unknown,
         result?: ExtractionRunResult,
@@ -700,6 +704,7 @@ export class TurnIngestionCoordinator {
           failOnExtractionFailure: options.failOnExtractionFailure === true,
           writeNamespaceOverride: options.writeNamespaceOverride,
           principalOverride: options.principalOverride,
+          forceExtractionAttempt: options.forceExtractionAttempt === true,
         });
         settleTask(undefined, result);
       } catch (err) {

package/src/orchestrator-flush.test.ts

@@ -1060,11 +1060,45 @@ test("runExtraction does not persist processed fingerprints for failed empty ext
   assert.equal(result.status, "skipped");
   assert.equal(result.reason, "empty_extraction_result");
   assert.equal(persistCalls, 0);
-  assert.equal(saveMetaCalls, 0);
-  assert.equal(clearCalls, 1);
+  // #1908: a failed extraction now persists per-fingerprint retry-state to meta (one
+  // saveMeta call), but MUST NOT record a processed fingerprint — the invariant
+  // below (processedExtractionFingerprints stays []) is the real contract.
+  assert.ok(saveMetaCalls <= 1, `expected at most one retry-state meta save, got ${saveMetaCalls}`);
+  // #1908: a retryable failure retains the buffer (clearCalls===0) so the backoff
+  // gate can re-attempt the turns after nextEligibleAt — clearing would orphan
+  // the persisted retry state (cursor high + codex P1).
+  assert.equal(clearCalls, 0);
   assert.deepEqual(meta.processedExtractionFingerprints, []);
 });
 
+test("runExtraction clears the buffer on a failed extraction when extractionRetryEnabled=false (behavior parity)", async () => {
+  // With retry disabled the failure path must match pre-#1908 behavior: the
+  // buffer is cleared (no retry state is recorded, so there is nothing to retain).
+  const config = parseConfig({ extractionRetryEnabled: false });
+  config.extractionMinChars = 0;
+  config.extractionMinUserTurns = 1;
+  let clearCalls = 0;
+  const orchestrator = Object.create(Orchestrator.prototype) as any;
+  orchestrator.config = config;
+  orchestrator.buffer = { clearAfterExtraction: async () => { clearCalls += 1; } };
+  orchestrator.storageRouter = {
+    storageFor: async () => ({
+      listEntityNames: async () => [],
+      loadMeta: async () => ({ extractionCount: 0, lastExtractionAt: null, lastConsolidationAt: null, totalMemories: 0, totalEntities: 0, processedExtractionFingerprints: [] }),
+      saveMeta: async () => {},
+    }),
+  };
+  orchestrator.extraction = {
+    extract: async () => ({ facts: [], entities: [], questions: [], profileUpdates: [], extractionFailure: "gateway_unavailable" }),
+  };
+  orchestrator.persistExtraction = async () => [];
+  const turns = [{ ...makeTurn("session-retry-off", "failed gateway"), logicalSessionKey: "logical-thread:retry-off", turnFingerprint: "fp-retry-off", persistProcessedFingerprint: true }];
+  const result = await orchestrator.runExtraction(turns, { bufferKey: "logical-thread:retry-off" });
+  assert.equal(result.status, "skipped");
+  assert.equal(result.reason, "empty_extraction_result");
+  assert.equal(clearCalls, 1, "retry disabled → buffer cleared (pre-#1908 behavior)");
+});
+
 test("runExtraction preserves empty-result buffers when fingerprint persistence fails", async () => {
   const config = parseConfig({});
   config.extractionMinChars = 0;

package/src/orchestrator.ts

@@ -106,7 +106,11 @@ import { RecallRerankCoordinator } from "./orchestration/recall-rerank-coordinat
 import { RecallSectionCoordinator } from "./orchestration/recall-section-coordinator.js";
 import { QmdResultResolver, qmdCollectionPathParts, qmdResultPathCandidates } from "./orchestration/qmd-result-resolver.js";
 import { ContradictionLinkingCoordinator } from "./orchestration/contradiction-linking-coordinator.js";
-import { ExtractionRunCoordinator, type ExtractionRunResult } from "./orchestration/extraction-run.js";
+import {
+  ExtractionRunCoordinator,
+  type ExtractionRunResult,
+  type ExtractionResilienceStatus,
+} from "./orchestration/extraction-run.js";
 import { ConsolidationRunCoordinator } from "./orchestration/consolidation-run.js";
 import { ExtractionPersistCoordinator } from "./orchestration/extraction-persist.js";
 import { RecallInternalCoordinator } from "./orchestration/recall-internal.js";
@@ -2937,6 +2941,7 @@ export class Orchestrator {
       skipUserTurnThreshold?: boolean;
       extractionDeadlineMs?: number;
       failOnExtractionFailure?: boolean;
+      forceExtractionAttempt?: boolean;
       onTaskSettled?: (
         error?: unknown,
         result?: ExtractionRunResult,
@@ -3010,6 +3015,12 @@ export class Orchestrator {
     return this.extractionRunCoordinator.runExtraction(...args);
   }
 
+  /** Live extraction resilience snapshot (provider circuit breaker + per-
+   *  fingerprint backoff population) for status/doctor surfaces. */
+  getExtractionResilienceStatus(): ExtractionResilienceStatus {
+    return this.extractionRunCoordinator.getExtractionResilienceStatus();
+  }
+
   private async recordProcessedExtractionFingerprint(
     storage: StorageManager,
     fingerprint: string,

package/src/storage.ts

@@ -110,6 +110,7 @@ import type {
   BufferSurpriseEvent,
   MemorySummary,
   MetaState,
+  ExtractionFailureClass,
   CompressionGuidelineOptimizerState,
   PluginConfig,
   ScoredEntity,
@@ -2263,6 +2264,38 @@ export interface MemoryWriteResult {
   blockedBy?: string;
 }
 
+/**
+ * Defensively parse the persisted per-fingerprint extraction retry state from
+ * meta.json. Mirrors the tolerance of the `processedExtractionFingerprints`
+ * loader: unknown/legacy shapes are dropped, never thrown on. Uses `in`/typeof
+ * narrowing (no inline casts) so a malformed entry can't slip through typed.
+ */
+function parseExtractionRetryStateEntries(
+  raw: unknown,
+): NonNullable<MetaState["extractionRetryState"]> {
+  if (!Array.isArray(raw)) return [];
+  const valid: NonNullable<MetaState["extractionRetryState"]> = [];
+  for (const entry of raw) {
+    if (!entry || typeof entry !== "object") continue;
+    if (!("fingerprint" in entry) || typeof entry.fingerprint !== "string") continue;
+    if (!("attempts" in entry) || typeof entry.attempts !== "number" || !Number.isFinite(entry.attempts)) continue;
+    if (!("nextEligibleAt" in entry) || typeof entry.nextEligibleAt !== "string") continue;
+    if (!("firstFailedAt" in entry) || typeof entry.firstFailedAt !== "string") continue;
+    if (!("lastFailureClass" in entry)) continue;
+    const cls = entry.lastFailureClass;
+    if (cls !== "provider_retryable" && cls !== "parse_empty" && cls !== "auth_config") continue;
+    const lastFailureClass: ExtractionFailureClass = cls;
+    valid.push({
+      fingerprint: entry.fingerprint,
+      attempts: entry.attempts,
+      nextEligibleAt: entry.nextEligibleAt,
+      firstFailedAt: entry.firstFailedAt,
+      lastFailureClass,
+    });
+  }
+  return valid;
+}
+
 export class StorageManager {
   private knowledgeIndexCache: { result: string; builtAt: number } | null = null;
   private artifactIndexCache: { memories: MemoryFile[]; loadedAtMs: number; writeVersion: number } | null = null;
@@ -4917,6 +4950,7 @@ export class StorageManager {
                 observedAt: (entry as { observedAt: string }).observedAt,
               }))
           : [],
+        extractionRetryState: parseExtractionRetryStateEntries(parsed.extractionRetryState),
       };
     } catch (err) {
       if (err instanceof SecureStoreLockedError) throw err;