@remnic/core 10.0.69 → 10.0.71

package/src/orchestration/extraction-drain.ts

@@ -1,11 +1,4 @@
-/**
- * Chunked trigger-drain for the extraction pipeline.
- *
- * Split out of `turn-ingestion.ts`: that file is at the structural ratchet's
- * line cap (issue #1995), and the drain is a self-contained unit — it only
- * needs the host's `runExtraction`, the buffer drop, the storage side-file
- * copy and the preemption hook.
- */
+/** Chunked trigger-drain for the extraction pipeline. */
 
 import { createHash } from "node:crypto";
 import { isAbortError, preemptedExtractionError } from "../abort-error.js";
@@ -36,12 +29,18 @@ export interface ExtractionDrainDeps {
     extractionChunkDropAfterFailures: number;
   };
   extractionWindowBudgetChars?(): number;
+  /** Rendered-size oracle: the exact character count the extraction renderer */
+  measureRenderedTurns?(turns: readonly BufferTurn[]): number;
   runExtraction(turns: BufferTurn[], options: RunOptions): Promise<ExtractionRunResult>;
   getStorage(): Promise<{
     saveDroppedExtractionChunk(bufferKey: string, reason: string, turns: readonly BufferTurn[]): Promise<string>;
   }>;
   buffer: {
-    dropExtractionChunk(bufferKey: string, turns: readonly BufferTurn[], options?: { allowNonPrefix?: boolean }): Promise<number>;
+    dropExtractionChunk(
+      bufferKey: string,
+      turns: readonly BufferTurn[],
+      options?: { allowNonPrefix?: boolean }
+    ): Promise<number>;
   };
 }
 
@@ -52,14 +51,28 @@ function chunkFingerprint(chunk: readonly BufferTurn[]): string {
   return hash.digest("hex");
 }
 
+/** The chunking decision for one trigger-drain window. */
+interface ChunkPlan {
+  singleRun: boolean;
+  chunks: BufferTurn[][];
+  resumed: boolean;
+}
+
+/** The drain-loop action for one chunk result. */
+interface ChunkVerdict {
+  action: "continue" | "return" | "failed";
+  result: ExtractionRunResult;
+  aggregate: ExtractionRunResult | null;
+}
+
+/** Per-chunk run options plus the chunk-local preemption controller. */
+interface ChunkExecutionOptions {
+  options: DrainRunOptions;
+  preempt?: AbortController;
+}
+
 export class ExtractionDrain {
-  /**
-   * Consecutive failed attempts on the head chunk, per buffer key. In memory on
-   * purpose (a restart re-counts from zero). Bound to the chunk's content: a
-   * count recorded for one chunk never applies to a different one, so a force
-   * flush that clears a failing chunk cannot make unrelated content inherit its
-   * failures.
-   */
+  /** Consecutive failed attempts on the head chunk, per buffer key. In memory on */
   private readonly failures = new Map<string, { fingerprint: string; count: number }>();
 
   /**
@@ -71,7 +84,15 @@ export class ExtractionDrain {
    */
   private readonly qualified = new Map<string, string>();
 
-  constructor(private readonly deps: ExtractionDrainDeps) {}
+  /** The claim drain runs with `dropFailedChunks: false`: a chunk that keeps */
+  private readonly dropFailedChunks: boolean;
+
+  private readonly deps: ExtractionDrainDeps;
+
+  constructor(deps: ExtractionDrainDeps, options?: { dropFailedChunks?: boolean }) {
+    this.deps = deps;
+    this.dropFailedChunks = options?.dropFailedChunks !== false;
+  }
 
   /** Characters the coordinator would count for this window: user/assistant text, trimmed and capped per turn, context-only turns left out. */
   private windowChars(turns: readonly BufferTurn[]): number {
@@ -118,36 +139,77 @@ export class ExtractionDrain {
     turns: BufferTurn[],
     runOptions: DrainRunOptions,
     preemptable = false,
-    preemptHandle?: ExtractionPreemptHandle,
+    preemptHandle?: ExtractionPreemptHandle
   ): Promise<ExtractionRunResult> {
     const budgetChars = this.deps.extractionWindowBudgetChars?.() ?? Number.POSITIVE_INFINITY;
-    const chunkable =
-      runOptions.clearBufferAfterExtraction &&
-      !runOptions.forceExtractionAttempt &&
-      !runOptions.failOnExtractionFailure &&
-      !turns.some((turn) => turn.acceptedCapture === true) &&
-      Number.isFinite(budgetChars) &&
-      budgetChars > 0;
-    const chunks = chunkable ? chunkExtractionWindow(turns, budgetChars) : [];
-    const resumed =
-      chunks.length > 0 && this.qualified.get(runOptions.bufferKey) === chunkFingerprint(chunks[0].slice(0, 1));
+    const plan = this.chunkPlan(turns, runOptions, budgetChars);
     // The tail of a window that already qualified goes through the chunk loop even when it now fits in one
     // chunk, so its failures still count toward the drop threshold.
-    if (chunks.length <= 1 && !resumed) return await this.deps.runExtraction(turns, runOptions);
+    if (plan.singleRun) return await this.deps.runExtraction(turns, runOptions);
     // Eligibility (minimum user turns and characters) belongs to the whole
     // window: a window that never qualified keeps the single-run path, which
     // judges it exactly as before.
-    if (!resumed) {
-      const windowUserTurns = turns.filter((turn) => turn.role === "user").length;
-      const belowChars = !runOptions.skipCharThreshold && this.windowChars(turns) < this.deps.config.extractionMinChars;
-      if ((!runOptions.skipUserTurnThreshold && windowUserTurns < this.deps.config.extractionMinUserTurns) || belowChars) {
-        return await this.deps.runExtraction(turns, runOptions);
-      }
+    if (!plan.resumed && this.windowBelowThreshold(turns, runOptions)) {
+      return await this.deps.runExtraction(turns, runOptions);
     }
-    // The window qualified as a whole; its chunks must not be re-judged one by
-    // one (an assistant-only or short chunk would be cleared unextracted).
-    const baseOptions = { ...runOptions, skipCharThreshold: true, skipUserTurnThreshold: true };
+    return await this.runChunked(plan.chunks, runOptions, preemptable, preemptHandle);
+  }
+
+  /** Chunking plan for one trigger-drain window. Accepted-capture groups */
+  private chunkPlan(
+    turns: readonly BufferTurn[],
+    runOptions: DrainRunOptions,
+    budgetChars: number
+  ): ChunkPlan {
+    const chunks = this.chunkable(runOptions, turns, budgetChars)
+      ? this.deps.measureRenderedTurns !== undefined
+        ? this.chunkByRenderedSize(turns, budgetChars)
+        : chunkExtractionWindow(turns, budgetChars)
+      : [];
+    const resumed =
+      chunks.length > 0 && this.qualified.get(runOptions.bufferKey) === chunkFingerprint(chunks[0].slice(0, 1));
+    return { singleRun: chunks.length <= 1 && !resumed, chunks, resumed };
+  }
+
+  /** Automatic chunking needs a clearable window, no fail-closed/forced
+   *  caller, and a real budget to chunk against. */
+  private chunkable(runOptions: DrainRunOptions, turns: readonly BufferTurn[], budgetChars: number): boolean {
+    return (
+      runOptions.clearBufferAfterExtraction &&
+      !runOptions.forceExtractionAttempt &&
+      !runOptions.failOnExtractionFailure &&
+      this.identityCleared(runOptions, turns) &&
+      Number.isFinite(budgetChars) &&
+      budgetChars > 0
+    );
+  }
+
+  /** A native group clears its turns by identity (a pinned capture can sit
+   *  in front); a drop must find them the same way. */
+  private identityCleared(runOptions: DrainRunOptions, turns: readonly BufferTurn[]): boolean {
+    return runOptions.clearMatchingTurns === true || !turns.some((turn) => turn.acceptedCapture === true);
+  }
 
+  /** Eligibility (minimum user turns and characters) belongs to the whole
+   *  window: a window that never qualified keeps the single-run path, which
+   *  judges it exactly as before. */
+  private windowBelowThreshold(turns: readonly BufferTurn[], runOptions: DrainRunOptions): boolean {
+    const windowUserTurns = turns.filter((turn) => turn.role === "user").length;
+    const belowChars = !runOptions.skipCharThreshold && this.windowChars(turns) < this.deps.config.extractionMinChars;
+    return (
+      (!runOptions.skipUserTurnThreshold && windowUserTurns < this.deps.config.extractionMinUserTurns) || belowChars
+    );
+  }
+
+  /** The window qualified as a whole; its chunks must not be re-judged one by
+   *  one (an assistant-only or short chunk would be cleared unextracted). */
+  private async runChunked(
+    chunks: readonly BufferTurn[][],
+    runOptions: DrainRunOptions,
+    preemptable: boolean,
+    preemptHandle?: ExtractionPreemptHandle
+  ): Promise<ExtractionRunResult> {
+    const baseOptions = { ...runOptions, skipCharThreshold: true, skipUserTurnThreshold: true };
     const bufferKey = runOptions.bufferKey;
     // A native group clears its turns by identity (a pinned capture can sit in front); a drop must find them the same way.
     const byIdentity = runOptions.clearMatchingTurns === true;
@@ -155,78 +217,184 @@ export class ExtractionDrain {
     let aggregate: ExtractionRunResult | null = null;
     for (const [position, chunk] of chunks.entries()) {
       this.qualified.set(bufferKey, chunkFingerprint(chunk.slice(0, 1)));
-      // retentionWindow: the chunks processed so far. A chunk's deferred retention replaces theirs (retained turns do not pile
-      // up across chunks) and leaves the retained turns of chunks not yet processed in the buffer.
-      let chunkOptions: DrainRunOptions = { ...baseOptions, retentionWindow: chunks.slice(0, position + 1).flat() };
-      let preempt: AbortController | undefined;
-      if (preemptable && position > 0) {
-        const local = new AbortController();
-        preempt = local;
-        preemptHandle?.arm(() => local.abort(preemptedExtractionError()));
-        chunkOptions = {
-          ...chunkOptions,
-          abortSignal: runOptions.abortSignal ? AbortSignal.any([runOptions.abortSignal, local.signal]) : local.signal,
-        };
-      }
-      let failures = this.failureCount(bufferKey, chunk);
+      const { options: chunkOptions, preempt } = this.chunkOptionsFor(
+        chunks,
+        position,
+        baseOptions,
+        runOptions,
+        preemptable,
+        preemptHandle
+      );
+      const failures = this.failureCount(bufferKey, chunk);
       let result: ExtractionRunResult;
       try {
         result = await this.deps.runExtraction(chunk, chunkOptions);
       } catch (err) {
-        // The chunk-local abort leaves the outer signal untouched, so hand back the
-        // preemption reason the host looks for (as it does for the first chunk).
-        if (isAbortError(err)) throw preempt && preempt.signal.aborted && !runOptions.abortSignal?.aborted ? preempt.signal.reason : err;
-        failures += 1;
-        if (failures < dropAfter) {
-          this.setFailureCount(bufferKey, chunk, failures);
-          throw err;
-        }
-        // A chunk that keeps throwing is dropped like one that keeps failing,
-        // so later chunks are not stuck behind it.
-        const thrown: ExtractionRunResult = {
-          status: "skipped",
-          reason: `thrown: ${describeError(err)}`,
-          persistedCount: 0,
-          durableOutputCount: 0,
-        };
-        if (!(await this.dropFailedChunk(bufferKey, chunk, dropAfter, thrown, byIdentity))) {
-          this.setFailureCount(bufferKey, chunk, failures);
-          throw err;
-        }
-        this.setFailureCount(bufferKey, chunk, 0);
+        this.rethrowChunkAbort(err, preempt, runOptions.abortSignal?.aborted === true);
+        // A successfully dropped thrown chunk does not end the drain: later
+        // chunks still run this pass (live drop policy).
+        aggregate = await this.settleThrownChunk(bufferKey, chunk, failures, dropAfter, err, byIdentity, aggregate);
         continue;
       }
-      const verdict = classifyDrainResult(result);
-      if (verdict === "drained") {
-        this.setFailureCount(bufferKey, chunk, 0);
-        aggregate = mergeDrainResults(aggregate, result);
+      const settled = this.settleVerdict(bufferKey, chunk, result, aggregate);
+      if (settled.action === "continue") {
+        aggregate = settled.result;
         continue;
       }
-      // Provider breaker/backoff retention: keep everything for retry.
-      if (verdict === "deferred") return mergeDrainResults(aggregate, result);
-      // An outage or a bad key is not the chunk's fault: keep the chunk and do not count toward dropping it.
-      if (result.failureClass === "provider_retryable" || result.failureClass === "auth_config") {
-        return mergeDrainResults(aggregate, result);
-      }
-      failures += 1;
-      if (failures >= dropAfter) {
-        if (!(await this.dropFailedChunk(bufferKey, chunk, dropAfter, result, byIdentity))) {
-          // No recovery copy: keep the only buffered copy and retry later.
-          this.setFailureCount(bufferKey, chunk, failures);
-          return mergeDrainResults(aggregate, result);
-        }
-        this.setFailureCount(bufferKey, chunk, 0);
-        aggregate = mergeDrainResults(aggregate, result);
+      if (settled.action === "return") return settled.result;
+      const failed = await this.settleFailedChunk({
+        bufferKey,
+        chunk,
+        failures,
+        dropAfter,
+        result: settled.result,
+        byIdentity,
+        aggregate: settled.aggregate,
+      });
+      if (failed.action === "continue") {
+        aggregate = failed.result;
         continue;
       }
-      this.setFailureCount(bufferKey, chunk, failures);
-      // Retain the remaining window for the next trigger (existing behavior).
-      return mergeDrainResults(aggregate, result);
+      return failed.result;
     }
     this.qualified.delete(bufferKey);
     return aggregate ?? { status: "skipped", persistedCount: 0, durableOutputCount: 0 };
   }
 
+  /** retention replaces theirs (retained turns do not pile up across chunks) */
+  private chunkOptionsFor(
+    chunks: readonly BufferTurn[][],
+    position: number,
+    baseOptions: DrainRunOptions,
+    runOptions: DrainRunOptions,
+    preemptable: boolean,
+    preemptHandle?: ExtractionPreemptHandle
+  ): ChunkExecutionOptions {
+    let options: DrainRunOptions = { ...baseOptions, retentionWindow: chunks.slice(0, position + 1).flat() };
+    let preempt: AbortController | undefined;
+    if (preemptable && position > 0) {
+      preempt = this.armChunkPreempt(preemptHandle);
+      options = {
+        ...options,
+        abortSignal: runOptions.abortSignal
+          ? AbortSignal.any([runOptions.abortSignal, preempt.signal])
+          : preempt.signal,
+      };
+    }
+    return { options, preempt };
+  }
+
+  /** A chunk-local abort controller so a fail-closed flush can abort the
+   *  next chunk instead of waiting behind the whole window. */
+  private armChunkPreempt(preemptHandle?: ExtractionPreemptHandle): AbortController {
+    const local = new AbortController();
+    preemptHandle?.arm(() => local.abort(preemptedExtractionError()));
+    return local;
+  }
+
+  /** An abort error is rethrown (the chunk-local abort leaves the outer
+   *  signal untouched, so the host gets the preemption reason it looks for,
+   *  as it does for the first chunk). */
+  private rethrowChunkAbort(cause: unknown, preempt: AbortController | undefined, outerAborted: boolean): void {
+    if (!isAbortError(cause)) return;
+    throw preempt && preempt.signal.aborted && !outerAborted ? preempt.signal.reason : cause;
+  }
+
+  /** A chunk whose extraction THREW: count the failure; below the drop
+   *  threshold (or on a no-drop drain) rethrow so the window is retained;
+   *  at the threshold a chunk that keeps throwing is dropped like one that
+   *  keeps failing, so later chunks are not stuck behind it. */
+  private async settleThrownChunk(
+    bufferKey: string,
+    chunk: readonly BufferTurn[],
+    failures: number,
+    dropAfter: number,
+    cause: unknown,
+    byIdentity: boolean,
+    aggregate: ExtractionRunResult | null
+  ): Promise<ExtractionRunResult> {
+    failures += 1;
+    if (failures < dropAfter || !this.dropFailedChunks) {
+      this.setFailureCount(bufferKey, chunk, failures);
+      throw cause;
+    }
+    const thrown: ExtractionRunResult = {
+      status: "skipped",
+      reason: `thrown: ${describeError(cause)}`,
+      persistedCount: 0,
+      durableOutputCount: 0,
+    };
+    if (!(await this.dropFailedChunk(bufferKey, chunk, dropAfter, thrown, byIdentity))) {
+      this.setFailureCount(bufferKey, chunk, failures);
+      throw cause;
+    }
+    this.setFailureCount(bufferKey, chunk, 0);
+    return mergeDrainResults(aggregate, thrown);
+  }
+
+  /** Map one chunk result to the drain-loop action: drained chunks continue
+   *  to the next chunk; breaker/backoff retention and provider faults keep
+   *  everything for retry without counting a chunk failure. */
+  private settleVerdict(
+    bufferKey: string,
+    chunk: readonly BufferTurn[],
+    result: ExtractionRunResult,
+    aggregate: ExtractionRunResult | null
+  ): ChunkVerdict {
+    const verdict = classifyDrainResult(result);
+    if (verdict === "drained") {
+      this.setFailureCount(bufferKey, chunk, 0);
+      return { action: "continue", result: mergeDrainResults(aggregate, result), aggregate };
+    }
+    // Provider breaker/backoff retention: keep everything for retry.
+    if (verdict === "deferred") return { action: "return", result: mergeDrainResults(aggregate, result), aggregate };
+    // An outage or a bad key is not the chunk's fault: keep the chunk and do not count toward dropping it.
+    if (result.failureClass === "provider_retryable" || result.failureClass === "auth_config") {
+      return { action: "return", result: mergeDrainResults(aggregate, result), aggregate };
+    }
+    return { action: "failed", result, aggregate };
+  }
+
+  /** (live drains, recovery copy first) or keep it as durable retryable */
+  private async settleFailedChunk(args: {
+    bufferKey: string;
+    chunk: readonly BufferTurn[];
+    failures: number;
+    dropAfter: number;
+    result: ExtractionRunResult;
+    byIdentity: boolean;
+    aggregate: ExtractionRunResult | null;
+  }): Promise<{ action: "continue" | "return"; result: ExtractionRunResult }> {
+    const failures = args.failures + 1;
+    if (failures >= args.dropAfter && this.dropFailedChunks) {
+      if (!(await this.dropFailedChunk(args.bufferKey, args.chunk, args.dropAfter, args.result, args.byIdentity))) {
+        // No recovery copy: keep the only buffered copy and retry later.
+        this.setFailureCount(args.bufferKey, args.chunk, failures);
+        return { action: "return", result: mergeDrainResults(args.aggregate, args.result) };
+      }
+      this.setFailureCount(args.bufferKey, args.chunk, 0);
+      return { action: "continue", result: mergeDrainResults(args.aggregate, args.result) };
+    }
+    this.setFailureCount(args.bufferKey, args.chunk, failures);
+    return { action: "return", result: mergeDrainResults(args.aggregate, args.result) };
+  }
+
+  /** Greedy chunking sized by the RENDERED conversation (the oracle the model */
+  private chunkByRenderedSize(turns: readonly BufferTurn[], budgetChars: number): BufferTurn[][] {
+    const measure = this.deps.measureRenderedTurns!;
+    const chunks: BufferTurn[][] = [];
+    let current: BufferTurn[] = [];
+    for (const turn of turns) {
+      if (current.length > 0 && measure([...current, turn]) > budgetChars) {
+        chunks.push(current);
+        current = [];
+      }
+      current.push(turn);
+    }
+    if (current.length > 0) chunks.push(current);
+    return chunks;
+  }
+
   /** Side-file copy first (content survives a failed drop), then remove the failing chunk from the buffer. Never throws:
    *  the drop must not fail the extraction task that already settled its result. */
   private async dropFailedChunk(
@@ -234,22 +402,14 @@ export class ExtractionDrain {
     chunk: readonly BufferTurn[],
     dropAfter: number,
     result: ExtractionRunResult,
-    byIdentity: boolean,
+    byIdentity: boolean
   ): Promise<boolean> {
     const reason =
       `dropped after ${dropAfter} repeated extraction failures ` +
       `(last result: status=${result.status} reason=${result.reason ?? "n/a"})`;
-    try {
-      const storage = await this.deps.getStorage();
-      const path = await storage.saveDroppedExtractionChunk(bufferKey, reason, chunk);
-      log.warn(`buffer[${bufferKey}]: dropping ${chunk.length} turns — ${reason}; copy saved to ${path}`);
-    } catch (err) {
-      // Never destroy the only buffered copy without a recovery file.
-      log.warn(
-        `buffer[${bufferKey}]: could not save the dropped-chunk recovery copy; keeping the chunk in the buffer: ${describeError(err)}`,
-      );
-      return false;
-    }
+    const copyPath = await this.saveRecoveryCopy(bufferKey, reason, chunk);
+    if (copyPath === null) return false;
+    log.warn(`buffer[${bufferKey}]: dropping ${chunk.length} turns — ${reason}; copy saved to ${copyPath}`);
     try {
       const dropped = await this.deps.buffer.dropExtractionChunk(bufferKey, chunk, { allowNonPrefix: byIdentity });
       if (dropped > 0) {
@@ -260,9 +420,28 @@ export class ExtractionDrain {
       log.warn(`buffer[${bufferKey}]: dropped chunk no longer matches the buffer; keeping it and its failure count`);
     } catch (err) {
       log.warn(
-        `buffer[${bufferKey}]: failed to remove dropped chunk from buffer (will retry next trigger): ${describeError(err)}`,
+        `buffer[${bufferKey}]: failed to remove dropped chunk from buffer (will retry next trigger): ${describeError(err)}`
       );
     }
     return false;
   }
+
+  /** The recovery side-file copy for a dropped chunk. null = the copy could
+   *  not be written — the caller must keep the only buffered copy. */
+  private async saveRecoveryCopy(
+    bufferKey: string,
+    reason: string,
+    chunk: readonly BufferTurn[]
+  ): Promise<string | null> {
+    try {
+      const storage = await this.deps.getStorage();
+      return await storage.saveDroppedExtractionChunk(bufferKey, reason, chunk);
+    } catch (err) {
+      // Never destroy the only buffered copy without a recovery file.
+      log.warn(
+        `buffer[${bufferKey}]: could not save the dropped-chunk recovery copy; keeping the chunk in the buffer: ${describeError(err)}`
+      );
+      return null;
+    }
+  }
 }

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

@@ -79,6 +79,13 @@ export class ExtractionQueueCoordinator {
   private accepting = true;
   /** Buffer keys with a task currently running (per-key exclusion). */
   private readonly activeKeys = new Set<string>();
+  /**
+   * Buffer keys with a claim DECISION in flight (daemon backlog scheduler).
+   * A reservation is taken synchronously BEFORE the async claim/decision so
+   * no queued task for the key can start past the gate while the decision is
+   * unsettled; selection skips reserved keys until release.
+   */
+  private readonly reservedKeys = new Set<string>();
   /** Preempt slots of the currently running tasks, keyed by slot identity. */
   private readonly preemptSlots = new Map<object, PreemptSlot>();
   private preemptSeq = 0;
@@ -133,6 +140,44 @@ export class ExtractionQueueCoordinator {
     return true;
   }
 
+  /**
+   * Synchronously reserve `key` so no task for it starts until the key's
+   * owner (the backlog scheduler's claim decision) settles and releases.
+   * Returns false when the key is active, queued, or already reserved —
+   * single-threaded JS makes this check+add atomic.
+   */
+  tryReserveKey(key: string): boolean {
+    if (this.activeKeys.has(key) || this.reservedKeys.has(key)) return false;
+    if (this.queue.some((entry) => entry.key === key)) return false;
+    this.reservedKeys.add(key);
+    // The processor may be parked with ONLY reserved entries left: restart
+    // it so selection is re-evaluated (it will skip the reserved key).
+    if (!this.processing && this.queue.length > 0) {
+      this.processing = true;
+      this.processQueue().catch((err) => {
+        this.logExtractionQueueFailure(err, "processor");
+        this.processing = false;
+      });
+    }
+    return true;
+  }
+
+  /** Settle a reservation: the key's decision is made and enqueued work (if
+   * any) now carries the key authority itself. Idempotent; wakes a parked
+   * processor waiting only on this release. */
+  releaseKeyReservation(key: string): void {
+    if (!this.reservedKeys.delete(key)) return;
+    if (this.queue.length > 0 && !this.processing) {
+      this.processing = true;
+      this.processQueue().catch((err) => {
+        this.logExtractionQueueFailure(err, "processor");
+        this.processing = false;
+      });
+    } else {
+      this.wake?.();
+    }
+  }
+
   preemptRunning(preferredKey?: string): void {
     const armed = Array.from(this.preemptSlots.values()).filter((slot) => slot.armed !== undefined);
     if (armed.length === 0) return;
@@ -200,7 +245,10 @@ export class ExtractionQueueCoordinator {
         }
         // Park until a task settles OR a new task is enqueued. A queued task
         // whose key is still held always implies an in-flight task holding
-        // it, so inFlight is non-empty here whenever the loop must wait.
+        // it, so inFlight is non-empty here whenever the loop must wait. A
+        // queued task behind a RESERVATION (no in-flight holder) leaves the
+        // loop instead; releaseKeyReservation and enqueue restart the
+        // processor when it is not running.
         if (inFlight.size === 0) break;
         const { promise: wakePromise, resolve: wake } = Promise.withResolvers<void>();
         this.wake = wake;
@@ -215,11 +263,11 @@ export class ExtractionQueueCoordinator {
     }
   }
 
-  /** Take the next queue entry whose key is not already running (FIFO within a key). */
+  /** Take the next queue entry whose key is not already running or reserved (FIFO within a key). */
   private takeRunnable(): QueueEntry | undefined {
     for (let index = 0; index < this.queue.length; index += 1) {
       const entry = this.queue[index];
-      if (entry.key !== undefined && this.activeKeys.has(entry.key)) continue;
+      if (entry.key !== undefined && (this.activeKeys.has(entry.key) || this.reservedKeys.has(entry.key))) continue;
       this.queue.splice(index, 1);
       if (entry.key !== undefined) this.activeKeys.add(entry.key);
       return entry;

package/src/orchestration/extraction-run.test.ts

@@ -24,6 +24,7 @@ import {
 } from "./extraction-run.js";
 import { StorageManager } from "../storage.js";
 import { parseConfig } from "../config.js";
+import { ProviderCircuitBreaker } from "./provider-breaker.js";
 import type { ExtractionEngine } from "../extraction.js";
 import type { ThreadingManager } from "../threading.js";
 import type { BufferTurn, ExtractionResult, ExtractionFailureClass, PluginConfig } from "../types.js";
@@ -102,6 +103,7 @@ interface Harness {
     fn: ExtractionRunCoordinatorDeps["recordProcessedExtractionFingerprint"],
   ) => void;
   recordedProcessedCount: () => number;
+  makeDeps: () => ExtractionRunCoordinatorDeps;
   run: (
     coord: ExtractionRunCoordinator,
     content: string,
@@ -233,6 +235,7 @@ async function makeHarness(overrides: Record<string, unknown> = {}): Promise<Har
       persistHandler = fn;
     },
     recordedProcessedCount: () => recordedProcessedCount,
+    makeDeps,
     passiveCapture: () => passiveCapture,
     run: async (coord, content, opts = {}) => {
       const result = await coord.runExtraction(makeTurns(content), {
@@ -1416,3 +1419,41 @@ test("the retention window a chunk run is given reaches the buffer as the proces
     await h.cleanup();
   }
 });
+
+test("isolated claim drains share the orchestrator's provider breaker (review round)", async () => {
+  const harness = await makeHarness({
+    extractionBreakerFailureThreshold: 1,
+    extractionBreakerCooldownMs: 60_000,
+  });
+  try {
+    // extractionRunCoordinatorForBuffer builds a fresh coordinator per claim
+    // drain; the ORCHESTRATOR-wide breaker must be the one they all consult.
+    const shared = new ProviderCircuitBreaker();
+    const makeIsolated = () =>
+      new ExtractionRunCoordinator({ ...harness.makeDeps(), providerBreaker: shared });
+    harness.setRespond(() => ({
+      facts: [],
+      profileUpdates: [],
+      entities: [],
+      questions: [],
+      extractionFailure: "provider down",
+      extractionFailureClass: "provider_retryable",
+    }));
+
+    // The first failing attempt opens the SHARED breaker.
+    const first = await harness.run(makeIsolated(), "breaker-share");
+    assert.equal(first.reason, "empty_extraction_result");
+
+    // A DIFFERENT isolated coordinator (a fresh claim drain) must observe the
+    // opened breaker instead of re-calling the failing provider. Distinct
+    // fingerprint, so only the breaker can suppress this attempt.
+    const second = await harness.run(makeIsolated(), "breaker-share-2");
+    assert.equal(
+      second.reason,
+      "provider_circuit_open",
+      "a fresh isolated drain must honor the orchestrator-wide breaker instead of hammering the failing provider",
+    );
+  } finally {
+    await harness.cleanup();
+  }
+});