@remnic/core 10.0.73 → 10.0.75

package/src/local-llm-json-schema-fallback.test.ts

@@ -1,9 +1,14 @@
 import assert from "node:assert/strict";
+import fs from "node:fs";
 import http from "node:http";
+import os from "node:os";
 import type { AddressInfo } from "node:net";
+import { join } from "node:path";
 import test, { mock } from "node:test";
 
 import { LocalLlmClient } from "./local-llm.js";
+import { ModelRegistry } from "./model-registry.js";
+import { NativeSchemaGate, type LocalLlmChatRequestBody } from "./local-llm-native-schema.js";
 import { ChatTransport } from "./local-llm-transport.js";
 import { parseConfig } from "./config.js";
 import type { LocalLlmChatCompletionOptions } from "./local-llm-helpers.js";
@@ -276,3 +281,313 @@ test("request without response_format is unchanged", async () => {
   }
 });
 
+// ── Schema-validation rejections (the provider parses our json_schema) ──────
+//
+// Production signature (2026-11-05, MiniMax-M3.1-Flash via local proxy): a
+// 400 "invalid params — Mismatch type string with value array" quoting a
+// schema fragment like `"episodeTitle": {"type": ["string","null"]}`. The
+// provider accepts structured output in principle but its strict parser
+// rejects our draft-7 nullable type unions. Unlike capability rejections
+// these errors never name response_format, so nothing stripped the format,
+// every drain attempt re-sent the identical payload, and the 400 breaker
+// opened. The zod draft-7 schema legitimately contains `type` arrays
+// (nullable fields), so the provider dialect, not our request, is the
+// constraint: degrade to the pre-schema request shape and remember it.
+
+const schemaValidationRejection = {
+  error: {
+    // Verbatim production body shape (2026-11-05): "Mismatch type" (no "ed"),
+    // JSON-escaped quotes around the schema fragment, and no mention of
+    // response_format anywhere.
+    message:
+      'invalid params, Mismatch type string with value array "at index 13779: \\"episodeTitle\\": {\\"type\\": [\\"string\\",\\"null\\"]}"',
+  },
+};
+
+test("a schema-validation 400 strips the format and retries without it", async () => {
+  const server = await startRecordingServer((_req, count) =>
+    count === 1
+      ? { status: 400, body: schemaValidationRejection }
+      : { status: 200, body: okCompletion },
+  );
+  try {
+    const client = new LocalLlmClient(createConfig({ localLlmUrl: server.url }));
+    primeClient(client);
+    const result = await client.chatCompletion([{ role: "user", content: "hello" }], {
+      responseFormat,
+    });
+    assert.equal(result?.content, "done");
+    assert.equal(server.requests.length, 2, "exactly one strip-and-retry");
+    assert.ok(server.requests[0].body.response_format, "the schema-shaped request went out first");
+    assert.equal(server.requests[1].body.response_format, undefined);
+  } finally {
+    await server.close();
+  }
+});
+
+test("a rejected schema format is not re-sent on later requests", async () => {
+  const server = await startRecordingServer((_req, count) =>
+    count === 1
+      ? { status: 400, body: schemaValidationRejection }
+      : { status: 200, body: okCompletion },
+  );
+  try {
+    const client = new LocalLlmClient(createConfig({ localLlmUrl: server.url }));
+    primeClient(client);
+    assert.equal(
+      (await client.chatCompletion([{ role: "user", content: "hello" }], { responseFormat }))?.content,
+      "done",
+    );
+    assert.equal(
+      (await client.chatCompletion([{ role: "user", content: "hello again" }], { responseFormat }))?.content,
+      "done",
+    );
+    assert.equal(server.requests.length, 3, "second call sends one request, not a new 400");
+    assert.equal(
+      server.requests[2].body.response_format,
+      undefined,
+      "the learned rejection skips the format entirely",
+    );
+  } finally {
+    await server.close();
+  }
+});
+
+test("a learned schema rejection persists in the model registry for fresh clients", async () => {
+  const memoryDir = fs.mkdtempSync(join(os.tmpdir(), "remnic-schema-cap-"));
+  const server = await startRecordingServer((_req, count) =>
+    count === 1
+      ? { status: 400, body: schemaValidationRejection }
+      : { status: 200, body: okCompletion },
+  );
+  try {
+    const registry = new ModelRegistry(memoryDir);
+    const client = new LocalLlmClient(createConfig({ localLlmUrl: server.url }), registry);
+    primeClient(client);
+    assert.equal(
+      (await client.chatCompletion([{ role: "user", content: "hello" }], { responseFormat }))?.content,
+      "done",
+    );
+    // SAFETY: we wrote model-capabilities.json through ModelRegistry above; the
+    // document is an object keyed by normalized model id.
+    const persisted = JSON.parse(
+      fs.readFileSync(join(memoryDir, ".registry", "model-capabilities.json"), "utf8"),
+    ) as { models: Record<string, { structuredOutput?: string }> };
+    assert.equal(persisted.models["test-local-model"]?.structuredOutput, "none");
+
+    const fresh = new LocalLlmClient(createConfig({ localLlmUrl: server.url }), new ModelRegistry(memoryDir));
+    primeClient(fresh);
+    assert.equal(
+      (await fresh.chatCompletion([{ role: "user", content: "hello" }], { responseFormat }))?.content,
+      "done",
+    );
+    const formatRequests = server.requests.filter((r) => r.body.response_format);
+    assert.equal(formatRequests.length, 1, "only the first-ever request carries the format");
+  } finally {
+    await server.close();
+    fs.rmSync(memoryDir, { recursive: true, force: true });
+  }
+});
+
+test("a schema-carrying success records native and keeps sending the format", async () => {
+  const memoryDir = fs.mkdtempSync(join(os.tmpdir(), "remnic-schema-cap-"));
+  const server = await startRecordingServer(() => ({ status: 200, body: okCompletion }));
+  try {
+    const registry = new ModelRegistry(memoryDir);
+    const client = new LocalLlmClient(createConfig({ localLlmUrl: server.url }), registry);
+    primeClient(client);
+    await client.chatCompletion([{ role: "user", content: "hello" }], { responseFormat });
+    await client.chatCompletion([{ role: "user", content: "hello again" }], { responseFormat });
+    // SAFETY: we wrote model-capabilities.json through ModelRegistry above; the
+    // document is an object keyed by normalized model id.
+    const persisted = JSON.parse(
+      fs.readFileSync(join(memoryDir, ".registry", "model-capabilities.json"), "utf8"),
+    ) as { models: Record<string, { structuredOutput?: string }> };
+    assert.equal(persisted.models["test-local-model"]?.structuredOutput, "native");
+    assert.equal(server.requests.length, 2);
+    assert.ok(server.requests[1].body.response_format, "structured output remains for supporting providers");
+  } finally {
+    await server.close();
+    fs.rmSync(memoryDir, { recursive: true, force: true });
+  }
+});
+
+test("an expired registry rejection is re-probed instead of honored forever", async () => {
+  const memoryDir = fs.mkdtempSync(join(os.tmpdir(), "remnic-schema-cap-"));
+  const server = await startRecordingServer(() => ({ status: 200, body: okCompletion }));
+  try {
+    const registry = new ModelRegistry(memoryDir);
+    registry.setStructuredOutput("test-local-model", "none");
+    // Age the entry past the 7-day registry TTL, as a long-lived deployment
+    // would: the learned rejection must not be honored forever.
+    const registryPath = join(memoryDir, ".registry", "model-capabilities.json");
+    // SAFETY: we wrote model-capabilities.json through ModelRegistry above; the
+    // document is an object keyed by normalized model id.
+    const persisted = JSON.parse(fs.readFileSync(registryPath, "utf8")) as {
+      models: Record<string, { fetchedAt: string }>;
+    };
+    persisted.models["test-local-model"].fetchedAt = new Date(
+      Date.now() - 8 * 24 * 60 * 60 * 1000,
+    ).toISOString();
+    fs.writeFileSync(registryPath, JSON.stringify(persisted));
+
+    const client = new LocalLlmClient(createConfig({ localLlmUrl: server.url }), new ModelRegistry(memoryDir));
+    primeClient(client);
+    const result = await client.chatCompletion([{ role: "user", content: "hello" }], {
+      responseFormat,
+    });
+    assert.equal(result?.content, "done");
+    assert.ok(server.requests[0].body.response_format, "expired rejection is re-probed with the schema");
+    // The provider accepts it this time: the native record refreshes.
+    // SAFETY: the file above was written by ModelRegistry's own persistence;
+    // the document is an object keyed by normalized model id.
+    const refreshed = JSON.parse(fs.readFileSync(registryPath, "utf8")) as {
+      models: Record<string, { structuredOutput?: string }>;
+    };
+    assert.equal(refreshed.models["test-local-model"]?.structuredOutput, "native");
+  } finally {
+    await server.close();
+    fs.rmSync(memoryDir, { recursive: true, force: true });
+  }
+});
+
+test("a later capabilities write preserves the learned structuredOutput", async () => {
+  const memoryDir = fs.mkdtempSync(join(os.tmpdir(), "remnic-schema-cap-"));
+  try {
+    const registry = new ModelRegistry(memoryDir);
+    registry.setStructuredOutput("test-local-model", "none");
+    // Mirrors getCachedContextWindow's LM Studio detection replacing the record.
+    registry.setCapabilities("test-local-model", {
+      maxPositionEmbeddings: 131072,
+      contextWindow: 131072,
+      supportsExtendedContext: true,
+      typicalOutputTokens: 8192,
+      source: "lmstudio",
+    });
+    assert.equal(registry.getStructuredOutput("test-local-model"), "none");
+  } finally {
+    fs.rmSync(memoryDir, { recursive: true, force: true });
+  }
+});
+
+test("an expired structuredOutput decision is not renewed by a capability refresh", async () => {
+  const memoryDir = fs.mkdtempSync(join(os.tmpdir(), "remnic-schema-cap-"));
+  try {
+    const registry = new ModelRegistry(memoryDir);
+    registry.setStructuredOutput("test-local-model", "none");
+    // Age the learned decision past the registry TTL exactly as a long-lived
+    // deployment would.
+    const registryPath = join(memoryDir, ".registry", "model-capabilities.json");
+    // SAFETY: we wrote model-capabilities.json through ModelRegistry above; the
+    // document is an object keyed by normalized model id.
+    const persisted = JSON.parse(fs.readFileSync(registryPath, "utf8")) as {
+      models: Record<string, { fetchedAt: string }>;
+    };
+    persisted.models["test-local-model"].fetchedAt = new Date(
+      Date.now() - 8 * 24 * 60 * 60 * 1000,
+    ).toISOString();
+    fs.writeFileSync(registryPath, JSON.stringify(persisted));
+    // The refresh happens in a process that loaded the AGED state from disk
+    // (a restart or another runtime sharing the memory dir).
+    const refreshedRegistry = new ModelRegistry(memoryDir);
+    refreshedRegistry.setCapabilities("test-local-model", {
+      maxPositionEmbeddings: 131072,
+      contextWindow: 131072,
+      supportsExtendedContext: true,
+      typicalOutputTokens: 8192,
+      source: "lmstudio",
+    });
+    assert.equal(
+      refreshedRegistry.getStructuredOutput("test-local-model"),
+      undefined,
+      "an expired decision must not be renewed into a fresh record — the re-probe stays due",
+    );
+  } finally {
+    fs.rmSync(memoryDir, { recursive: true, force: true });
+  }
+});
+
+test("a stale in-flight schema success does not overwrite a current rejection", () => {
+  const memoryDir = fs.mkdtempSync(join(os.tmpdir(), "remnic-schema-cap-"));
+  try {
+    const registry = new ModelRegistry(memoryDir);
+    const gate = new NativeSchemaGate(() => registry);
+    // Two schema-bearing requests attach before either settles.
+    const body: LocalLlmChatRequestBody = {
+      model: "test-local-model",
+      messages: [{ role: "user", content: "hello" }],
+      temperature: 0.1,
+      max_tokens: 16,
+      stream: false,
+    };
+    gate.attach(body, { responseFormat }, "test-local-model");
+    // The rejection settles first: "none" is the newest evidence.
+    gate.rememberRejection("test-local-model");
+    // The older in-flight success settles last: it must not flip the
+    // decision back, or later requests re-send the rejected schema.
+    gate.recordSuccess(body, "test-local-model");
+    assert.equal(registry.getStructuredOutput("test-local-model"), "none");
+    // A fresh success with no rejection standing still records native.
+    const otherBody: LocalLlmChatRequestBody = { ...body, model: "other-model" };
+    const freshGate = new NativeSchemaGate(() => registry);
+    freshGate.attach(otherBody, { responseFormat }, "other-model");
+    freshGate.recordSuccess(otherBody, "other-model");
+    assert.equal(registry.getStructuredOutput("other-model"), "native");
+  } finally {
+    fs.rmSync(memoryDir, { recursive: true, force: true });
+  }
+});
+
+test("invalid params without schema evidence is not treated as a schema rejection", async () => {
+  const server = await startRecordingServer(() => ({
+    status: 400,
+    body: { error: { message: "invalid params: temperature must be between 0 and 2" } },
+  }));
+  try {
+    const client = new LocalLlmClient(createConfig({ localLlmUrl: server.url }));
+    primeClient(client);
+    assert.equal(await client.chatCompletion([{ role: "user", content: "hello" }], { responseFormat }), null);
+    assert.equal(server.requests.length, 1, "unrelated invalid-param errors must not strip the format");
+  } finally {
+    await server.close();
+  }
+});
+
+test("an echoed format name inside an unrelated invalid-param error does not strip", async () => {
+  const server = await startRecordingServer(() => ({
+    status: 400,
+    body: {
+      error: {
+        message: "invalid params: quota exceeded; request included response_format json_schema",
+      },
+    },
+  }));
+  try {
+    const client = new LocalLlmClient(createConfig({ localLlmUrl: server.url }));
+    primeClient(client);
+    assert.equal(await client.chatCompletion([{ role: "user", content: "hello" }], { responseFormat }), null);
+    assert.equal(server.requests.length, 1, "an echo of the format name is not schema-rejection evidence");
+  } finally {
+    await server.close();
+  }
+});
+
+test("a type mismatch on an unrelated parameter does not strip the schema", async () => {
+  const server = await startRecordingServer(() => ({
+    status: 400,
+    body: { error: { message: "invalid params: mismatch type for temperature, expected number" } },
+  }));
+  try {
+    const client = new LocalLlmClient(createConfig({ localLlmUrl: server.url }));
+    primeClient(client);
+    assert.equal(await client.chatCompletion([{ role: "user", content: "hello" }], { responseFormat }), null);
+    assert.equal(
+      server.requests.length,
+      1,
+      "no schema fragment quoted: the mismatch is not evidence our schema was rejected",
+    );
+  } finally {
+    await server.close();
+  }
+});
+

package/src/local-llm-native-schema.ts

@@ -0,0 +1,78 @@
+/**
+ * Native json_schema capability shaping for the local LLM client.
+ *
+ * A provider that rejects the schema PAYLOAD itself (strict parsers that die
+ * on draft-7 nullable `type` unions, e.g. MiniMax-M3.1-Flash on 2026-11-05:
+ * "invalid params, Mismatch type string with value array") gets the pre-#3248
+ * shape: no response_format, the JSON contract stays in the prompt. The
+ * rejection is learned per model and persisted through the ModelRegistry so
+ * fresh runtimes shape requests correctly without re-proving it; a
+ * schema-carrying success persists `structuredOutput: "native"`.
+ */
+
+import type { ResponseFormatJSONSchema } from "openai/resources/shared";
+import type { LocalLlmChatCompletionOptions } from "./local-llm-helpers.js";
+import type { ModelRegistry } from "./model-registry.js";
+
+/** The chat-completions wire body; optional keys are capability-gated additions. */
+export interface LocalLlmChatRequestBody {
+  model: string;
+  messages: Array<{ role: string; content: string }>;
+  temperature: number;
+  max_tokens: number;
+  stream: boolean;
+  response_format?: { type: string } | ResponseFormatJSONSchema;
+  chat_template_kwargs?: { enable_thinking: boolean };
+  reasoning_effort?: string;
+}
+
+/** Learned structured-output shaping for one local endpoint. */
+export class NativeSchemaGate {
+  /** Models rejected in this process — the fallback for registry-less clients. */
+  private readonly rejectedByProcess = new Set<string>();
+
+  constructor(private readonly registry: () => ModelRegistry | undefined) {}
+
+  /** False when the model is known to reject the native json_schema payload. */
+  usable(modelId: string): boolean {
+    const registry = this.registry();
+    // Registry-backed decisions honor the registry TTL: an expired entry is
+    // re-probed instead of being honored forever. The in-memory set only
+    // serves clients without a registry.
+    if (registry) return registry.getStructuredOutput(modelId) !== "none";
+    return !this.rejectedByProcess.has(modelId);
+  }
+
+  rememberRejection(modelId: string): void {
+    const registry = this.registry();
+    if (registry) registry.setStructuredOutput(modelId, "none");
+    else this.rejectedByProcess.add(modelId);
+  }
+
+  /** Attach the schema format unless the gate suppresses it for this model. */
+  attach(
+    requestBody: LocalLlmChatRequestBody,
+    options: Pick<LocalLlmChatCompletionOptions, "responseFormat">,
+    modelId: string,
+  ): void {
+    if (options.responseFormat?.type === "json_schema" && this.usable(modelId)) {
+      requestBody.response_format = options.responseFormat;
+    }
+  }
+
+  /** A schema-carrying 200: persist the native capability once. A CURRENT
+   *  "none" stands — that success is stale in-flight evidence from before the
+   *  rejection, and overwriting it would make later requests re-send the
+   *  rejected schema. */
+  recordSuccess(requestBody: LocalLlmChatRequestBody, modelId: string): void {
+    const registry = this.registry();
+    if (
+      !requestBody.response_format ||
+      !registry ||
+      registry.getStructuredOutput(modelId) !== undefined
+    ) {
+      return;
+    }
+    registry.setStructuredOutput(modelId, "native");
+  }
+}

package/src/local-llm.ts

@@ -24,6 +24,7 @@ import {
   type LocalLlmChatCompletionOptions,
   type LocalLlmChatCompletionResult,
 } from "./local-llm-helpers.js";
+import { NativeSchemaGate, type LocalLlmChatRequestBody } from "./local-llm-native-schema.js";
 import {
   isObjectRecord,
   orderedLocalServers,
@@ -189,6 +190,7 @@ export class LocalLlmClient {
   private consecutive400s: number = 0;
   private cooldownUntilMs: number = 0;
   private modelRegistry?: ModelRegistry;
+  private readonly nativeSchemaGate = new NativeSchemaGate(() => this.modelRegistry);
   private _disableThinking: boolean = false;
   private readonly requestQueues: Record<LocalLlmRequestPriority, LocalLlmQueuedRequest[]> = {
     "recall-critical": [],
@@ -887,21 +889,16 @@ export class LocalLlmClient {
       }
 
       const promptChars = messages.reduce((sum, m) => sum + (m.content?.length ?? 0), 0);
-      const requestBody: Record<string, unknown> = {
-        model: options.model ?? this.config.localLlmModel,
+      const requestModel = options.model ?? this.config.localLlmModel;
+      const requestBody: LocalLlmChatRequestBody = {
+        model: requestModel,
         messages,
         temperature: options.temperature ?? 0.7,
         // Use max_tokens consistent with cloud models
         max_tokens: options.maxTokens ?? 4096,
         stream: false,
       };
-
-      // Skip response_format for local LLMs - they don't support json_object type
-      // The prompts already instruct the model to output JSON
-      // Only send if it's json_schema type which some local LLMs support
-      if (options.responseFormat?.type === "json_schema") {
-        requestBody.response_format = options.responseFormat;
-      }
+      this.nativeSchemaGate.attach(requestBody, options, requestModel);
 
       // Suppress thinking/reasoning for operations that benefit from terse,
       // structured output. Thinking-capable models (Qwen 3.5, Gemma 4,
@@ -1016,6 +1013,7 @@ export class LocalLlmClient {
             requestBody.response_format &&
             isUnsupportedJsonSchemaError(`400 ${responseBody}`)
           ) {
+            this.nativeSchemaGate.rememberRejection(requestModel);
             // Match gateway degradation without extending this attempt's deadline.
             delete requestBody.response_format;
             requestBodyJson = JSON.stringify(requestBody);
@@ -1150,6 +1148,7 @@ export class LocalLlmClient {
         return null;
       }
       this.consecutive400s = 0;
+      this.nativeSchemaGate.recordSuccess(requestBody, requestModel);
 
       const data = JSON.parse(responseBody) as {
         choices?: Array<{

package/src/model-registry.ts

@@ -19,6 +19,8 @@ export interface ModelCapabilities {
   };
   typicalOutputTokens: number;
   source: "huggingface" | "lmstudio" | "manual" | "default";
+  /** Learned structured-output shaping (see ModelRegistry.getStructuredOutput). */
+  structuredOutput?: "native" | "none";
   fetchedAt: string;
 }
 
@@ -193,6 +195,9 @@ export class ModelRegistry {
           ...capabilities,
           modelId: normalizedId,
           source: "default",
+          // Reachable only with a missing or expired cached record, so any
+          // learned structuredOutput is stale here — leave it unset and let
+          // getStructuredOutput's freshness rules drive the re-probe.
           fetchedAt: new Date().toISOString(),
         };
         this.data.models[normalizedId] = caps;
@@ -214,8 +219,15 @@ export class ModelRegistry {
    */
   setCapabilities(modelId: string, capabilities: Omit<ModelCapabilities, "modelId" | "fetchedAt">): void {
     const normalizedId = this.normalizeModelId(modelId);
+    const previous = this.data.models[normalizedId];
     const caps: ModelCapabilities = {
       ...capabilities,
+      // A replacement record (e.g. fresh LM Studio detection) must not erase a
+      // learned structuredOutput shaping — but an EXPIRED decision must not be
+      // renewed either: drop it so the re-probe stays due.
+      structuredOutput:
+        capabilities.structuredOutput ??
+        (previous && !this.isCacheExpired(previous) ? previous.structuredOutput : undefined),
       modelId: normalizedId,
       fetchedAt: new Date().toISOString(),
     };
@@ -224,6 +236,34 @@ export class ModelRegistry {
     log.info(`ModelRegistry: stored capabilities for ${modelId}`);
   }
 
+  /**
+   * Learned structured-output shaping for a model, persisted so fresh
+   * runtimes shape requests correctly without re-proving a rejection.
+   * Honors the cache TTL: a provider that later gains schema support is
+   * re-probed (one degraded request) after the window lapses.
+   */
+  getStructuredOutput(modelId: string): "native" | "none" | undefined {
+    const cached = this.data.models[this.normalizeModelId(modelId)];
+    if (!cached || this.isCacheExpired(cached)) return undefined;
+    return cached.structuredOutput;
+  }
+
+  /** Merge-and-persist: preserves any previously learned capabilities. */
+  setStructuredOutput(modelId: string, mode: "native" | "none"): void {
+    const normalizedId = this.normalizeModelId(modelId);
+    const base = this.data.models[normalizedId] ?? {
+      ...DEFAULT_CAPABILITIES,
+      modelId: normalizedId,
+    };
+    this.data.models[normalizedId] = {
+      ...base,
+      structuredOutput: mode,
+      fetchedAt: new Date().toISOString(),
+    };
+    this.saveRegistry();
+    log.info(`ModelRegistry: stored structuredOutput=${mode} for ${modelId}`);
+  }
+
   /**
    * Calculate optimal input/output sizes for a model
    * @param maxContextOverride - Optional override for max context (e.g., if LLM server defaults to smaller window)

package/src/orchestration/backlog-scheduler.ts

@@ -32,6 +32,7 @@ import type { BufferDrainClaims, DrainLease } from "../storage/buffer-drain-clai
 import { BufferDrainRunner } from "./buffer-drain-runner.js";
 import type { DrainRunnerEvent, DrainSessionOutcome } from "./buffer-drain-runner.js";
 import type { ExtractionQueueCoordinator } from "./extraction-queue-coordinator.js";
+import type { ProviderBreakerSnapshot } from "./provider-breaker.js";
 
 /** What the scheduler needs from its host (structurally satisfied by the
  *  orchestrator wiring); injectable so tests drive ticks deterministically. */
@@ -50,6 +51,13 @@ export interface BacklogSchedulerDeps {
     key: string,
     options: { ownerId: string; signal: AbortSignal; onEvent?: (event: DrainRunnerEvent) => void }
   ): Promise<DrainSessionOutcome>;
+  /** Shared provider circuit-breaker snapshot (the same instance the run
+   *  coordinator gates attempts on). While OPEN inside its cooldown window
+   *  the scheduler skips submission entirely — claims stay durable, and the
+   *  breaker's single half-open probe (one attempt through once the window
+   *  lapses) keeps recovery automatic. Optional: hosts without a breaker
+   *  never skip. */
+  breakerSnapshot?(): ProviderBreakerSnapshot;
   /** Test seam: monotonic-ish clock for backoff windows. */
   now?(): number;
 }
@@ -211,6 +219,18 @@ export class BacklogScheduler {
     this.ticking = true;
     const cursorBeforeTick = this.claimCursor;
     try {
+      // Fast bail: a breaker already open must not pay discovery I/O
+      // (listPage reads and parses claim bodies on every poll). The
+      // submitCandidates guard below still catches a breaker that opens
+      // while discovery awaits.
+      const breakerBeforeDiscovery = this.deps.breakerSnapshot?.();
+      if (
+        breakerBeforeDiscovery &&
+        breakerBeforeDiscovery.state === "open" &&
+        this.now() < breakerBeforeDiscovery.openUntilMs
+      ) {
+        return;
+      }
       // stop() may land while discovery's I/O is pending: re-check before
       // submitting anything, and again per candidate.
       // A discovery failure (EACCES/EIO on the claims dir) must not reject
@@ -269,6 +289,15 @@ export class BacklogScheduler {
 
   /** Submit discovery candidates within the queue's concurrency bound. */
   private submitCandidates(candidates: { key: string; needsClaim: boolean }[]): boolean {
+    // Breaker-open churn guard: a full attempt reads the claim, rebuilds the
+    // buffer/coordinator and re-renders chunks before the breaker fails it
+    // fast — pure heap pressure per poll during a provider stall. Skip while
+    // the window is open; once it lapses, submissions resume and the
+    // breaker's half-open probe runs as usual.
+    const breaker = this.deps.breakerSnapshot?.();
+    if (breaker && breaker.state === "open" && this.now() < breaker.openUntilMs) {
+      return true;
+    }
     let dropped = false;
     for (const candidate of candidates) {
       if (this.stopped || this.inFlight.size >= this.submissionLimit()) {
@@ -475,6 +504,9 @@ export function wireBacklogScheduler(
         };
       },
       drainKey: (key, drainOptions) => runner.drainSession(key, drainOptions),
+      // The orchestrator's one shared provider breaker (foreground and every
+      // claim-backed drain accumulate toward the same threshold).
+      breakerSnapshot: () => orchestrator.getExtractionResilienceStatus().breaker,
     },
     { ...options, ownerId }
   );

package/src/orchestration/extraction-queue-coordinator.ts

@@ -115,10 +115,27 @@ export class ExtractionQueueCoordinator {
    * Enqueue a task and start the processor when capacity is free. This is
    * the production entry point — the orchestrator's `queueBufferedExtraction`
    * builds each task closure and hands it here with its buffer key.
+   *
+   * Per-key coalescing: a queued-not-started task for key K is superseded by
+   * a newer enqueue for K instead of stacking another full turn snapshot
+   * behind it (extraction reads live state at run time, so the newest
+   * closure is the authoritative one). Keyless tasks are independent work
+   * and never coalesce.
    */
   enqueue(task: ExtractionQueueTask, options?: ExtractionQueueEnqueueOptions): boolean {
     if (!this.accepting) return false;
-    const entry: QueueEntry = { run: task, key: options?.key };
+    const key = options?.key;
+    if (key !== undefined) {
+      const queuedAt = this.queue.findIndex((entry) => entry.key === key);
+      if (!options?.front && queuedAt >= 0) {
+        this.queue[queuedAt] = { run: task, key };
+        return true;
+      }
+      if (options?.front && queuedAt >= 0) {
+        this.queue.splice(queuedAt, 1);
+      }
+    }
+    const entry: QueueEntry = { run: task, key };
     if (options?.front) {
       this.preemptRunning(options.key);
       this.queue.unshift(entry);