@remnic/core 10.0.69 → 10.0.71

package/src/orchestration/extraction-run.ts

@@ -106,6 +106,13 @@ export interface ExtractionRunCoordinatorDeps {
     fingerprint: string,
     preloadedMeta?: Awaited<ReturnType<StorageManager["loadMeta"]>>
   ) => Promise<void>;
+  /**
+   * Orchestrator-wide provider resilience state. Absent for a standalone
+   * coordinator (own breaker); the orchestrator passes ITS breaker so every
+   * isolated claim-backed drain accumulates failures toward the same
+   * threshold and honors a foreground-opened breaker (review round).
+   */
+  providerBreaker?: ProviderCircuitBreaker;
 }
 
 // Recall/extraction abort helpers live in orchestrator-helpers.ts since
@@ -151,9 +158,11 @@ export class ExtractionRunCoordinator {
   // 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 readonly providerBreaker = new ProviderCircuitBreaker();
+  private readonly providerBreaker: ProviderCircuitBreaker;
 
-  constructor(private readonly deps: ExtractionRunCoordinatorDeps) {}
+  constructor(private readonly deps: ExtractionRunCoordinatorDeps) {
+    this.providerBreaker = deps.providerBreaker ?? new ProviderCircuitBreaker();
+  }
 
   private get config(): PluginConfig {
     return this.deps.config;
@@ -661,10 +670,14 @@ export class ExtractionRunCoordinator {
         log.warn(
           `runExtraction: skipping scope profile ${scopeProfileWritePlan.profileId} because write layer ${scopeProfileWritePlan.writeLayer} is not writable inside the profile read stack`
         );
-        await clearBuffer();
+        // Policy refusal (same family as namespace_write_revoked): the window
+        // stays in the buffer/claim pending a later attempt. Clearing here
+        // would destroy content policy never wrote — the claim drain would
+        // erase denied backlog and ack it as drained.
         return {
           status: "skipped",
           reason: "scope_profile_no_writable_layer",
+          retainedBuffer: true,
           persistedCount: 0,
           durableOutputCount: 0,
         };
@@ -854,10 +867,13 @@ export class ExtractionRunCoordinator {
       if (options.failOnExtractionFailure) {
         throw new Error("extraction failed: invalid_extraction_result");
       }
-      await clearBuffer();
+      // Actual extraction failure: the window is retained for a retry (same
+      // no-drop contract as a recorded provider failure), never destroyed.
       return {
         status: "skipped",
         reason: "invalid_extraction_result",
+        retainedBuffer: true,
+        failureClass: "parse_empty",
         persistedCount: 0,
         durableOutputCount: 0,
       };
@@ -878,10 +894,13 @@ export class ExtractionRunCoordinator {
       if (options.failOnExtractionFailure) {
         throw new Error("extraction failed: invalid_extraction_result");
       }
-      await clearBuffer();
+      // Actual extraction failure: the window is retained for a retry (same
+      // no-drop contract as a recorded provider failure), never destroyed.
       return {
         status: "skipped",
         reason: "invalid_extraction_result",
+        retainedBuffer: true,
+        failureClass: "parse_empty",
         persistedCount: 0,
         durableOutputCount: 0,
       };

package/src/orchestration/extraction-task-queueing.ts

@@ -0,0 +1,87 @@
+/**
+ * Extraction task queueing — the scope-group and execution-context pieces of
+ * the turn-ingestion coordinator, split out to keep that module inside the
+ * house source-size cap (issue #1995).
+ */
+
+import type { SmartBuffer } from "../buffer.js";
+import { groupTurnsByExtractionScope } from "../buffer-turn-helpers.js";
+import { log } from "../logger.js";
+import type { ResolvedScopeProfilePlan } from "../namespaces/scope-profiles.js";
+import type { BufferTurn, CodingContext } from "../types.js";
+import type { ExtractionDrain } from "./extraction-drain.js";
+import type { TurnIngestionDeps } from "./turn-ingestion.js";
+
+/**
+ * Isolated per-task execution context (claim-backed backlog drain).
+ * Bound at enqueue time and read ONLY inside the enqueued closure, so the
+ * task runs against its own buffer/extraction/drain no matter which async
+ * context the coordinator's processor executes it from. Absent for live
+ * work, which keeps the shared orchestrator state.
+ */
+export interface ExtractionTaskExecutionContext {
+  /** The task's own buffer (a claim-backed SmartBuffer). */
+  buffer: SmartBuffer;
+  /**
+   * The task's own chunked drain; its deps carry the isolated runExtraction +
+   * buffer (claim tasks build one with `dropFailedChunks: false` — the
+   * no-drop backlog policy).
+   */
+  drain: ExtractionDrain;
+}
+
+/** Queue options the capture-scope grouping forwards to the coordinator. */
+export interface CaptureScopeGroupQueueOptions {
+  deadlineMs?: number;
+  abortSignal?: AbortSignal;
+  writeNamespaceOverride?: string;
+  principalOverride?: string;
+  scopeProfileWritePlan?: ResolvedScopeProfilePlan | null;
+  codingContext?: CodingContext;
+  onExtractionQueued?: (extraction: Promise<void>) => void;
+}
+
+/**
+ * Buffer-approved captures skip threshold/dedupe rechecks, not provider
+ * retry cooldowns. Scope and staleness are enforced at the shared
+ * queueBufferedExtraction boundary.
+ */
+export function queueBufferedCaptureScopeGroups(
+  queueBufferedExtraction: TurnIngestionDeps["queueBufferedExtraction"],
+  extractionTurns: BufferTurn[],
+  bufferKey: string,
+  options: CaptureScopeGroupQueueOptions,
+): void {
+  for (const group of groupTurnsByExtractionScope(extractionTurns)) {
+    const groupIsAccepted = group.turns.some((turn) => turn.acceptedCapture === true);
+    if (!groupIsAccepted) {
+      // Native groups keep their own routing; skipped accepted prefixes require identity clearing.
+      void queueBufferedExtraction(group.turns, "trigger_mode", {
+        bufferKey,
+        clearMatchingTurns: true,
+        preemptable: true,
+      }).catch((err) => log.error(`native trigger extraction failed: ${err}`));
+      continue;
+    }
+    // Accepted groups use ONLY their own pins — no fallback to the
+    // triggering observe's scope.
+    const { promise: extraction, resolve, reject } = Promise.withResolvers<void>();
+    void queueBufferedExtraction(group.turns, "trigger_mode", {
+      bufferKey,
+      clearBufferAfterExtraction: true,
+      clearMatchingTurns: true,
+      skipDedupeCheck: true,
+      skipCharThreshold: true,
+      skipUserTurnThreshold: true,
+      abortSignal: options.abortSignal,
+      extractionDeadlineMs: options.deadlineMs,
+      writeNamespaceOverride: group.writeNamespaceOverride,
+      principalOverride: group.principalOverride,
+      scopeProfileWritePlan: group.scopeProfileWritePlan ?? null,
+      preemptable: true,
+      onTaskSettled: (err) => (err ? reject(err) : resolve()),
+    }).catch(reject);
+    if (options.onExtractionQueued) options.onExtractionQueued(extraction);
+    else extraction.catch((err) => log.error(`buffered capture extraction failed: ${err}`));
+  }
+}

package/src/orchestration/turn-ingestion.ts

@@ -44,6 +44,11 @@ import type { BufferTurn, PluginConfig, SourceConnectorProvenance } from "../typ
 import { groupTurnsByExtractionScope, bufferTurnsEqual } from "../buffer-turn-helpers.js";
 import { ExtractionDrain } from "./extraction-drain.js";
 import { skipClaimedSession } from "./buffer-drain-gate.js";
+import {
+  queueBufferedCaptureScopeGroups,
+  type CaptureScopeGroupQueueOptions,
+  type ExtractionTaskExecutionContext,
+} from "./extraction-task-queueing.js";
 import { resolveScopeProfilePlan, type ResolvedScopeProfilePlan, hasExplicitNamespacePolicy } from "../namespaces/scope-profiles.js";
 import { resolveCodingNamespaceOverlay, combineNamespaces } from "../coding/coding-namespace.js";
 import { canWriteNamespace, defaultNamespaceForPrincipal } from "../namespaces/principal.js";
@@ -224,7 +229,7 @@ export class TurnIngestionCoordinator {
       // #3251: native triggers must not run mixed accepted scopes under one
       // policy — each scope group drains through the shared execution
       // boundary with its own pins.
-      this.queueBufferedCaptureScopeGroups(outcome.extractionTurns, bufferKey, {});
+      queueBufferedCaptureScopeGroups(this.deps.queueBufferedExtraction, outcome.extractionTurns, bufferKey, {});
       return;
     }
     await this.deps.queueBufferedExtraction(
@@ -463,7 +468,12 @@ export class TurnIngestionCoordinator {
           );
         }
         if (outcome.decision !== "keep_buffering" && outcome.extractionTurns) {
-          this.queueBufferedCaptureScopeGroups(outcome.extractionTurns, bufferKey, options);
+          queueBufferedCaptureScopeGroups(
+            this.deps.queueBufferedExtraction,
+            outcome.extractionTurns,
+            bufferKey,
+            options,
+          );
         }
       }
       // Acceptance durability barrier (#1909 seam): surfaces storage failures
@@ -472,58 +482,6 @@ export class TurnIngestionCoordinator {
     }
   }
 
-  /**
-   * Buffer-approved captures skip threshold/dedupe rechecks, not provider retry cooldowns.
-   * Scope and staleness are enforced at the shared queueBufferedExtraction boundary.
-   */
-  private queueBufferedCaptureScopeGroups(
-    extractionTurns: BufferTurn[],
-    bufferKey: string,
-    options: {
-      deadlineMs?: number;
-      abortSignal?: AbortSignal;
-      writeNamespaceOverride?: string;
-      principalOverride?: string;
-      scopeProfileWritePlan?: ResolvedScopeProfilePlan | null;
-      codingContext?: import("../types.js").CodingContext;
-      onExtractionQueued?: (extraction: Promise<void>) => void;
-    },
-  ): void {
-    for (const group of groupTurnsByExtractionScope(extractionTurns)) {
-      const groupIsAccepted = group.turns.some((turn) => turn.acceptedCapture === true);
-      if (!groupIsAccepted) {
-        // Native groups keep their own routing; skipped accepted prefixes require identity clearing.
-        void this.deps.queueBufferedExtraction(group.turns, "trigger_mode", {
-          bufferKey,
-          clearMatchingTurns: true,
-          preemptable: true,
-        }).catch((err) => log.error(`native trigger extraction failed: ${err}`));
-        continue;
-      }
-      // Accepted groups use ONLY their own pins — no fallback to the
-      // triggering observe's scope.
-      const extraction = new Promise<void>((resolve, reject) => {
-        void this.deps.queueBufferedExtraction(group.turns, "trigger_mode", {
-          bufferKey,
-          clearBufferAfterExtraction: true,
-          clearMatchingTurns: true,
-          skipDedupeCheck: true,
-          skipCharThreshold: true,
-          skipUserTurnThreshold: true,
-          abortSignal: options.abortSignal,
-          extractionDeadlineMs: options.deadlineMs,
-          writeNamespaceOverride: group.writeNamespaceOverride,
-          principalOverride: group.principalOverride,
-          scopeProfileWritePlan: group.scopeProfileWritePlan ?? null,
-          preemptable: true,
-          onTaskSettled: (err) => (err ? reject(err) : resolve()),
-        }).catch(reject);
-      });
-      if (options.onExtractionQueued) options.onExtractionQueued(extraction);
-      else extraction.catch((err) => log.error(`buffered capture extraction failed: ${err}`));
-    }
-  }
-
   /**
    * Ingest a batch of bulk-import turns (#460). Like ingestReplayBatch, this
    * normalizes user/assistant turns into the extraction buffer and awaits
@@ -802,7 +760,7 @@ export class TurnIngestionCoordinator {
         if (turns.some((turn) => turn.acceptedCapture === true)) {
           // #3251: heartbeat triggers must not run mixed accepted scopes
           // under one policy — per-scope groups via the shared boundary.
-          this.queueBufferedCaptureScopeGroups(turns, bufferKey, {});
+          queueBufferedCaptureScopeGroups(this.deps.queueBufferedExtraction, turns, bufferKey, {});
           return;
         }
         await this.deps.queueBufferedExtraction(turns, "heartbeat_observer", {
@@ -842,6 +800,14 @@ export class TurnIngestionCoordinator {
       abortSignal?: AbortSignal;
       /** Automatic buffered work only. Replay and import must not set this. */
       preemptable?: boolean;
+      /**
+       * Invoked when the queued closure has FULLY exited (after settlement).
+       * Settlement can fire before the closure exits — e.g. an abort listener
+       * settles while persistence is still in flight — so callers that
+       * release resources on settlement (claim leases) can use this to wait
+       * for the actual task exit first.
+       */
+      onTaskExit?: () => void;
       /** Fail-closed force-flush only. Not implied by failOnExtractionFailure. */
       preemptRunning?: boolean;
       writeNamespaceOverride?: string;
@@ -852,10 +818,14 @@ export class TurnIngestionCoordinator {
        */
       principalOverride?: string;
       scopeProfileWritePlan?: ResolvedScopeProfilePlan | null;
+      /** Isolated per-task execution context (claim-backed backlog drain). */
+      execution?: ExtractionTaskExecutionContext;
     } = {},
   ): Promise<void> {
     const bufferKey = options.bufferKey ?? turnsToExtract[0]?.sessionKey ?? "default";
-    if (skipClaimedSession(this.deps.buffer, bufferKey, (result) => options.onTaskSettled?.(undefined, result))) return;
+    // The execution context owns the gate's buffer view: a claim-backed task
+    // reads its own claim (never "claimed"), not the live buffer's gate.
+    if (skipClaimedSession(options.execution?.buffer ?? this.deps.buffer, bufferKey, (result) => options.onTaskSettled?.(undefined, result))) return;
     if (
       !options.skipDedupeCheck &&
       !this.deps.shouldQueueExtraction(turnsToExtract, { bufferKey })
@@ -933,7 +903,8 @@ export class TurnIngestionCoordinator {
     if (settled) return;
     const preemptable = options.preemptable === true && options.preemptRunning !== true;
     const accepted = this.deps.extractionQueueCoordinator.enqueue(async (preemptHandle) => {
-      await this.deps.extractionQueueCoordinator.runPreemptable(preemptHandle, preemptable, options.abortSignal, async (abortSignal) => {
+      try {
+        await this.deps.extractionQueueCoordinator.runPreemptable(preemptHandle, preemptable, options.abortSignal, async (abortSignal) => {
       if (settled) return;
       if (
         typeof extractionDeadlineMs === "number" &&
@@ -943,6 +914,17 @@ export class TurnIngestionCoordinator {
         return;
       }
       clearQueueWaitTimer();
+      // Execution-time claim recheck (review round): the scheduler's
+      // async claim decision may complete while this LIVE task sits queued;
+      // its turns then belong to the claim runner, and extracting the stale
+      // snapshot here would persist duplicate outputs. The enqueue-time gate
+      // plus the key reservation only park the task until the decision
+      // settles. Isolated claim tasks (options.execution) read their own
+      // claim-backed buffer and bypass this gate by construction.
+      if (
+        options.execution === undefined &&
+        skipClaimedSession(this.deps.buffer, bufferKey, (result) => settleTask(undefined, result))
+      ) return;
       try {
         // #3251 shared execution boundary for accepted captures (trigger and
         // flush drains both converge here): re-read the live buffer so a
@@ -951,8 +933,9 @@ export class TurnIngestionCoordinator {
         // WITHOUT clearing, and the plan is never retargeted.
         let effectiveTurns = turnsToExtract;
         let effectiveScopePlan = options.scopeProfileWritePlan;
+        const executionBuffer = options.execution?.buffer;
         if (effectiveTurns.some((turn) => turn.acceptedCapture === true)) {
-          const liveTurns = this.deps.buffer
+          const liveTurns = (executionBuffer ?? this.deps.buffer)
             .getTurns(bufferKey)
             .filter((live) => effectiveTurns.some((snapshotted) => bufferTurnsEqual(live, snapshotted)));
           if (liveTurns.length === 0) {
@@ -1073,7 +1056,7 @@ export class TurnIngestionCoordinator {
             effectiveScopePlan = fresh;
           }
         }
-        const result = await this.drain.run(effectiveTurns, {
+        const result = await (options.execution?.drain ?? this.drain).run(effectiveTurns, {
           clearBufferAfterExtraction:
             options.clearBufferAfterExtraction ?? true,
           clearMatchingTurns: options.clearMatchingTurns === true,
@@ -1099,9 +1082,13 @@ export class TurnIngestionCoordinator {
         }
       }
       });
+      } finally {
+        options.onTaskExit?.();
+      }
     }, { front: options.preemptRunning === true, key: bufferKey });
     if (!accepted) {
       settleTask(new Error("extraction queue is stopped"));
+      options.onTaskExit?.();
       return;
     }
 

package/src/orchestrator-extraction-queue.test.ts

@@ -184,7 +184,6 @@ test("logExtractionQueueFailure names the right layer (task vs processor)", asyn
   );
 });
 
-
 test("pauseAndDrain waits for accepted work after its observation timeout", async () => {
   const coordinator = createCoordinator();
   const started = Promise.withResolvers<void>();
@@ -270,7 +269,6 @@ test("a front enqueue does not abort a task that did not register as preemptable
   assert.deepEqual(order, ["protected", "flush"]);
 });
 
-
 // ── Bounded-parallel queue (extractionQueueConcurrency) ─────────────────────
 
 function createParallelCoordinator(limit: number): ExtractionQueueCoordinator {
@@ -441,3 +439,49 @@ test("pauseAndDrain waits for concurrent accepted work and rejects new producers
   assert.equal(second.outcome, "finished");
   assert.equal(coordinator.isProcessing, false);
 });
+
+// ── Key reservations (daemon backlog scheduler) ────────────────────────────
+
+function delay(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+test("tryReserveKey defers a queued task's start until the reservation releases", async () => {
+  const queue = createCoordinator();
+  assert.equal(queue.tryReserveKey("s1"), true, "a free key reserves synchronously");
+
+  let ran = false;
+  queue.pushRaw(async () => {
+    ran = true;
+  }, { key: "s1" });
+  const processing = queue.processQueue();
+  await delay(20);
+  assert.equal(ran, false, "a reserved key's queued task must not start");
+  assert.equal(queue.tryReserveKey("s1"), false, "the pending reservation is exclusive");
+
+  queue.releaseKeyReservation("s1");
+  await processing;
+  assert.equal(ran, true, "the task runs once the claim decision settles");
+});
+
+test("tryReserveKey refuses active and queued keys, and releases idempotently", async () => {
+  const queue = createCoordinator();
+  let release: () => void = () => {};
+  const gate = new Promise<void>((resolve) => {
+    release = resolve;
+  });
+  queue.pushRaw(async () => {
+    await gate;
+  }, { key: "s1" });
+  const processing = queue.processQueue();
+  await delay(20);
+  assert.equal(queue.tryReserveKey("s1"), false, "an active key cannot be reserved");
+
+  queue.releaseKeyReservation("s1");
+  queue.releaseKeyReservation("s1"); // idempotent
+  release();
+  await processing;
+
+  assert.equal(queue.tryReserveKey("s1"), true, "a settled key reserves again");
+  queue.releaseKeyReservation("s1");
+});

package/src/orchestrator-flush.test.ts

@@ -1492,7 +1492,10 @@ test("runExtraction skips active scope profile writes when no layer is writable"
 
   assert.equal(result.status, "skipped");
   assert.equal(result.reason, "scope_profile_no_writable_layer");
-  assert.equal(clearCalls, 1);
+  // Policy refusal (review round): the window is RETAINED, never
+  // cleared — clearing here would destroy content policy never wrote.
+  assert.equal(clearCalls, 0);
+  assert.equal(result.retainedBuffer, true);
 });
 
 test("runExtraction writes buffered turns to active scope profile write layer", async () => {

package/src/orchestrator.ts

@@ -98,6 +98,7 @@ import {
   gatewayTaskChainOptions,
 } from "./fallback-llm.js";
 import { MaintenanceScheduler } from "./orchestration/maintenance.js";
+import { ProviderCircuitBreaker } from "./orchestration/provider-breaker.js";
 import { TierMigrationCoordinator } from "./orchestration/tier-migration-coordinator.js";
 import { ExtractionQueueCoordinator } from "./orchestration/extraction-queue-coordinator.js";
 import { CompressionGuidelineCoordinator } from "./orchestration/compression-guideline-coordinator.js";
@@ -119,6 +120,7 @@ import {
 } from "./orchestration/contradiction-linking-coordinator.js";
 import {
   ExtractionRunCoordinator,
+  type ExtractionRunCoordinatorDeps,
   type ExtractionRunResult,
   type ExtractionResilienceStatus,
 } from "./orchestration/extraction-run.js";
@@ -756,33 +758,57 @@ export class Orchestrator {
 
   readonly extractionQueueCoordinator: ExtractionQueueCoordinator;
   private _extractionRunCoordinator: ExtractionRunCoordinator | undefined;
+  private _providerBreaker: ProviderCircuitBreaker | undefined;
+
+  /** One breaker per orchestrator: foreground and every isolated claim-backed
+   *  drain accumulate toward the same threshold and honor each other's open
+   *  state (review round — isolated coordinators must not reset
+   *  provider resilience). */
+  private get providerBreaker(): ProviderCircuitBreaker {
+    if (!this._providerBreaker) this._providerBreaker = new ProviderCircuitBreaker();
+    return this._providerBreaker;
+  }
+
+  /** The run-coordinator deps bundle, parameterized by its buffer accessor so
+   * an isolated claim-backed drain can bind its own SmartBuffer (the daemon
+   * backlog scheduler) while live extraction keeps `this.buffer`. */
+  private extractionRunDeps(getBuffer: () => SmartBuffer): ExtractionRunCoordinatorDeps {
+    return {
+      config: this.config,
+      getBuffer,
+      providerBreaker: this.providerBreaker,
+      getExtraction: () => this.extraction,
+      getStorageRouter: () => this.storageRouter,
+      getThreading: () => this.threading,
+      persistExtraction: (result, storage, threadId, sourceContext, baseNamespace, scopeProfileWritePlan, sourceText, graphCaps, lifecycleCaps) =>
+        this.persistExtraction(result, storage, threadId, sourceContext, baseNamespace, scopeProfileWritePlan, sourceText, graphCaps, lifecycleCaps),
+      maybeCapturePassiveCorrections: (turns, opts) => this.maybeCapturePassiveCorrections(turns, opts),
+      resolveSelfNamespace: (sessionKey) => this.resolveSelfNamespace(sessionKey),
+      getCodingContextForSession: (sessionKey) => this.getCodingContextForSession(sessionKey),
+      applyCodingNamespaceOverlay: (sessionKey, namespace) => this.applyCodingNamespaceOverlay(sessionKey, namespace),
+      boxBuilderFor: (storage) => this.boxBuilderFor(storage),
+      appendPersistedThreadEpisodes: (threadId, ids, pendingReviewIds) =>
+        this.appendPersistedThreadEpisodes(threadId, ids, pendingReviewIds),
+      maybeScheduleConsolidation: (nonZero) => this.maybeScheduleConsolidation(nonZero),
+      requestQmdMaintenance: () => this.requestQmdMaintenance(),
+      runTierMigrationCycle: (storage, trigger, options) => this.runTierMigrationCycle(storage, trigger, options),
+      recordProcessedExtractionFingerprint: (storage, fingerprint, preloadedMeta) =>
+        this.recordProcessedExtractionFingerprint(storage, fingerprint, preloadedMeta),
+    };
+  }
 
   private get extractionRunCoordinator(): ExtractionRunCoordinator {
     if (!this._extractionRunCoordinator) {
-      this._extractionRunCoordinator = new ExtractionRunCoordinator({
-        config: this.config,
-        getBuffer: () => this.buffer,
-        getExtraction: () => this.extraction,
-        getStorageRouter: () => this.storageRouter,
-        getThreading: () => this.threading,
-        persistExtraction: (result, storage, threadId, sourceContext, baseNamespace, scopeProfileWritePlan, sourceText, graphCaps, lifecycleCaps) =>
-          this.persistExtraction(result, storage, threadId, sourceContext, baseNamespace, scopeProfileWritePlan, sourceText, graphCaps, lifecycleCaps),
-        maybeCapturePassiveCorrections: (turns, opts) => this.maybeCapturePassiveCorrections(turns, opts),
-        resolveSelfNamespace: (sessionKey) => this.resolveSelfNamespace(sessionKey),
-        getCodingContextForSession: (sessionKey) => this.getCodingContextForSession(sessionKey),
-        applyCodingNamespaceOverlay: (sessionKey, namespace) => this.applyCodingNamespaceOverlay(sessionKey, namespace),
-        boxBuilderFor: (storage) => this.boxBuilderFor(storage),
-        appendPersistedThreadEpisodes: (threadId, ids, pendingReviewIds) =>
-          this.appendPersistedThreadEpisodes(threadId, ids, pendingReviewIds),
-        maybeScheduleConsolidation: (nonZero) => this.maybeScheduleConsolidation(nonZero),
-        requestQmdMaintenance: () => this.requestQmdMaintenance(),
-        runTierMigrationCycle: (storage, trigger, options) => this.runTierMigrationCycle(storage, trigger, options),
-        recordProcessedExtractionFingerprint: (storage, fingerprint, preloadedMeta) =>
-          this.recordProcessedExtractionFingerprint(storage, fingerprint, preloadedMeta),
-      });
+      this._extractionRunCoordinator = new ExtractionRunCoordinator(this.extractionRunDeps(() => this.buffer));
     }
     return this._extractionRunCoordinator;
   }
+
+  /** An extraction run coordinator bound to `buffer` — per drain task, so a
+   * claim-backed drain never shares the live buffer's mutable state. */
+  extractionRunCoordinatorForBuffer(buffer: SmartBuffer): ExtractionRunCoordinator {
+    return new ExtractionRunCoordinator(this.extractionRunDeps(() => buffer));
+  }
   private _consolidationRunCoordinator: ConsolidationRunCoordinator | undefined;
   private get consolidationRunCoordinator(): ConsolidationRunCoordinator {
     if (!this._consolidationRunCoordinator) {

package/src/storage/buffer-drain-claims.ts

@@ -239,6 +239,10 @@ function parseLease(raw: string): DrainLease | null {
   };
 }
 
+/** Claim bodies `listPage` may read per requested entry: bounds one scan's
+ *  I/O even when the directory is mostly empty tombstones. */
+const LIST_PAGE_SCAN_FACTOR = 8;
+
 export class BufferDrainClaims {
   constructor(
     private readonly stateDir: string,
@@ -582,6 +586,57 @@ export class BufferDrainClaims {
     return out;
   }
 
+  /**
+   * Paged listing for bounded periodic scans: at most `limit` claims with
+   * pending turns, starting AFTER `afterName` (a raw entry name returned as
+   * `nextCursor` by a previous page — file-name order is stable, so a
+   * rotating cursor visits every claim fairly without ever materializing
+   * the whole directory's bodies). Empty tombstones never count toward the
+   * limit; the number of bodies read per call is bounded separately
+   * (`LIST_PAGE_SCAN_FACTOR` per requested entry), and the cursor advances
+   * past every scanned name so a long tombstone run is crossed over several
+   * pages instead of starving the pending claims behind it.
+   */
+  async listPage(afterName: string | undefined, limit: number): Promise<{ entries: DrainClaimListing[]; nextCursor?: string }> {
+    let names: string[];
+    try {
+      names = (await readdir(this.dir)).filter((name) => name.endsWith(".json") && !name.endsWith(".lease.json")).sort();
+    } catch (err) {
+      // SAFETY: readdir rejects with NodeJS system errors; only the ENOENT
+      // (no claims directory yet) case maps to an empty listing.
+      const errno = (err as NodeJS.ErrnoException | undefined)?.code;
+      if (errno === "ENOENT") return { entries: [] };
+      throw err;
+    }
+    const start = afterName === undefined ? 0 : names.findIndex((name) => name > afterName);
+    const out: DrainClaimListing[] = [];
+    // The cursor is the LAST CONSUMED entry name: the next page starts
+    // strictly after it, so the first unconsumed name is never skipped.
+    // Returning the first unconsumed name instead would make every page
+    // boundary permanently skip one claim.
+    let cursor: string | undefined;
+    const scanBudget = Math.max(limit, 1) * LIST_PAGE_SCAN_FACTOR;
+    let scanned = 0;
+    for (let index = start < 0 ? names.length : start; index < names.length; index += 1) {
+      if (out.length >= limit || scanned >= scanBudget) break;
+      const name = names[index]!;
+      scanned += 1;
+      cursor = name;
+      const claim = await this.readClaimBodyByKey(name);
+      if (!claim) continue;
+      const turnCount = claim.entry.turns.length + (claim.entry.retainedTurns?.length ?? 0);
+      if (turnCount <= 0) continue;
+      const lease = await this.readLease(claim.key);
+      out.push({
+        key: claim.key,
+        turnCount,
+        leased: lease !== null,
+        leaseExpired: lease !== null ? isLeaseExpired(lease) : true,
+      });
+    }
+    return { entries: out, nextCursor: cursor };
+  }
+
   private async readClaimBodyByKey(name: string): Promise<DrainClaimFile | null> {
     try {
       return parseBody(await this.io.read(path.join(this.dir, name)));