@remnic/core 10.0.35 → 10.0.37

package/src/buffer-incremental-persistence.test.ts

@@ -0,0 +1,256 @@
+/**
+ * Per-session incremental buffer persistence (SmartBuffer layer).
+ *
+ * Pins the hot-path contract on top of the storage primitives tested in
+ * storage-buffer-sessions.test.ts:
+ *
+ *   - a storage that exposes saveBufferSession/deleteBufferSession gets
+ *     INCREMENTAL saves: only the sessions whose state actually changed are
+ *     written, only on boundaries that need durability;
+ *   - sessions whose state did not change are never rewritten;
+ *   - eviction and resetToEmpty delete the corresponding session files;
+ *   - a legacy storage (only loadBuffer/saveBuffer) keeps the exact old
+ *     whole-state behavior — existing deployments and test doubles are
+ *     unaffected.
+ *
+ * All saves flow through SmartBuffer's mutation chain, so there is exactly
+ * one writer per session file.
+ */
+import test from "node:test";
+import assert from "node:assert/strict";
+import { mkdtemp, rm } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+
+import { SmartBuffer } from "./buffer.js";
+import { parseConfig } from "./config.js";
+import { StorageManager } from "./storage.js";
+import type { BufferEntryState, BufferState, BufferTurn } from "./types.js";
+
+interface SessionFileRecord {
+  entry: BufferEntryState;
+  writeCount: number;
+}
+
+/**
+ * Storage double implementing the incremental per-session surface. Records
+ * per-session writes/deletes and whole-state saves separately so tests can
+ * assert exactly which files the hot path touched.
+ */
+class IncrementalStorage {
+  readonly sessions = new Map<string, SessionFileRecord>();
+  readonly deleted: string[] = [];
+  wholeStateSaves = 0;
+  private initial: BufferState;
+
+  constructor(initial: BufferState) {
+    this.initial = initial;
+  }
+
+  async loadBuffer(): Promise<BufferState> {
+    return structuredClone(this.initial);
+  }
+
+  async saveBuffer(state: BufferState): Promise<void> {
+    this.wholeStateSaves += 1;
+    this.initial = structuredClone(state);
+  }
+
+  async saveBufferSession(key: string, entry: BufferEntryState): Promise<void> {
+    const record = this.sessions.get(key) ?? { entry, writeCount: 0 };
+    record.entry = structuredClone(entry);
+    record.writeCount += 1;
+    this.sessions.set(key, record);
+  }
+
+  async deleteBufferSession(key: string): Promise<void> {
+    this.deleted.push(key);
+    this.sessions.delete(key);
+  }
+}
+
+/**
+ * Storage double implementing ONLY the legacy whole-state surface — every
+ * pre-existing test double in the repo looks like this from SmartBuffer's
+ * point of view, and must keep working unchanged.
+ */
+class LegacyOnlyStorage {
+  wholeStateSaves = 0;
+  lastSaved: BufferState | null = null;
+
+  constructor(private initial: BufferState) {}
+
+  async loadBuffer(): Promise<BufferState> {
+    return structuredClone(this.initial);
+  }
+
+  async saveBuffer(state: BufferState): Promise<void> {
+    this.wholeStateSaves += 1;
+    this.lastSaved = structuredClone(state);
+  }
+}
+
+function makeTurn(sessionKey: string, content: string): BufferTurn {
+  return {
+    role: "user",
+    content,
+    timestamp: "2026-10-29T12:00:00.000Z",
+    sessionKey,
+  };
+}
+
+function emptyState(): BufferState {
+  return { turns: [], lastExtractionAt: null, extractionCount: 0 };
+}
+
+test("steady-state observe persists only the active session's file", async () => {
+  const storage = new IncrementalStorage(emptyState());
+  const buffer = new SmartBuffer(parseConfig({ triggerMode: "every_n", bufferMaxTurns: 100 }), storage);
+
+  await buffer.addTurn("thread-a", makeTurn("thread-a", "alpha"));
+  await buffer.flushPendingSave();
+  assert.equal(storage.wholeStateSaves, 0, "hot path fell back to whole-state save");
+  assert.equal(storage.sessions.get("thread-a")?.writeCount, 1);
+  assert.equal(storage.sessions.get("thread-a")?.entry.turns[0]?.content, "alpha");
+
+  await buffer.addTurn("thread-b", makeTurn("thread-b", "beta"));
+  await buffer.flushPendingSave();
+  assert.equal(storage.sessions.get("thread-b")?.writeCount, 1);
+  // Session A's turn did NOT touch session A's file again.
+  assert.equal(storage.sessions.get("thread-a")?.writeCount, 1, "unchanged session file was rewritten");
+});
+
+test("a second turn in the same session rewrites only that session's file", async () => {
+  const storage = new IncrementalStorage(emptyState());
+  const buffer = new SmartBuffer(parseConfig({ triggerMode: "every_n", bufferMaxTurns: 100 }), storage);
+
+  await buffer.addTurn("thread-a", makeTurn("thread-a", "one"));
+  await buffer.flushPendingSave();
+  await buffer.addTurn("thread-a", makeTurn("thread-a", "two"));
+  await buffer.flushPendingSave();
+
+  const record = storage.sessions.get("thread-a");
+  assert.equal(record?.writeCount, 2);
+  assert.equal(record?.entry.turns.length, 2);
+});
+
+test("extraction-boundary turn persists inline and durably", async () => {
+  const storage = new IncrementalStorage(emptyState());
+  // bufferMaxTurns: 1 → the very first turn triggers extract_batch.
+  const buffer = new SmartBuffer(parseConfig({ triggerMode: "every_n", bufferMaxTurns: 1 }), storage);
+
+  const outcome = await buffer.addTurnWithOutcome("thread-a", makeTurn("thread-a", "trigger"));
+  assert.equal(outcome.decision, "extract_batch");
+  // Inline save already ran inside the mutation — no flush needed.
+  assert.equal(storage.sessions.get("thread-a")?.writeCount, 1);
+  assert.equal(storage.wholeStateSaves, 0, "extraction boundary fell back to whole-state save");
+});
+
+test("clearAfterExtraction persists the cleared session state", async () => {
+  const storage = new IncrementalStorage(emptyState());
+  const buffer = new SmartBuffer(parseConfig({ triggerMode: "every_n", bufferMaxTurns: 100 }), storage);
+
+  await buffer.addTurn("thread-a", makeTurn("thread-a", "alpha"));
+  await buffer.flushPendingSave();
+  const before = storage.sessions.get("thread-a")?.writeCount ?? 0;
+
+  await buffer.clearAfterExtraction("thread-a");
+  const record = storage.sessions.get("thread-a");
+  assert.equal(record?.writeCount, before + 1, "clearAfterExtraction did not persist the session");
+  assert.equal(record?.entry.turns.length, 0);
+  assert.equal(record?.entry.extractionCount, 1);
+});
+
+test("evicted sessions get their files deleted", async () => {
+  const storage = new IncrementalStorage(emptyState());
+  const buffer = new SmartBuffer(parseConfig({ triggerMode: "every_n", bufferMaxTurns: 100 }), storage);
+
+  // normalizeState always materializes a "default" entry, so 198 seeded
+  // sessions + default = 199; new-session reaches exactly 200 (the
+  // addTurnBounded cap). One more UNBOUNDED addTurn pushes to 201 and
+  // pruneEntries evicts the oldest non-default session (s0).
+  for (let i = 0; i < 198; i++) {
+    const key = `s${i}`;
+    await buffer.addTurnBounded(key, makeTurn(key, `content ${i}`));
+  }
+  await buffer.flushPendingSave();
+
+  const outcome = await buffer.addTurnBounded("new-session", makeTurn("new-session", "fresh"));
+  assert.notEqual(outcome, null, "addTurnBounded refused below capacity");
+  await buffer.addTurn("overflow", makeTurn("overflow", "one too many"));
+  // The evicted key's file deletion lands on the next persist, like any
+  // other buffered state change.
+  await buffer.flushPendingSave();
+  assert.ok(storage.deleted.includes("s0"), "oldest session was not evicted under capacity pressure");
+  assert.ok(
+    storage.deleted.length > 0,
+    "capacity pressure evicted entries without deleting their session files",
+  );
+  for (const key of storage.deleted) {
+    assert.equal(storage.sessions.has(key), false, `evicted session ${key} still has a file record`);
+  }
+});
+
+test("resetToEmpty drops every session file on the next persist", async () => {
+  const storage = new IncrementalStorage(emptyState());
+  const buffer = new SmartBuffer(parseConfig({ triggerMode: "every_n", bufferMaxTurns: 100 }), storage);
+
+  await buffer.addTurn("thread-a", makeTurn("thread-a", "alpha"));
+  await buffer.flushPendingSave();
+  buffer.resetToEmpty();
+  await buffer.flushPendingSave();
+  // resetToEmpty marks every known key for deletion; deleting a key whose
+  // file never existed is an ENOENT no-op on real storage (covered in the
+  // storage contract tests). The session that HAD a file must be gone.
+  assert.ok(storage.deleted.includes("thread-a"));
+  assert.equal(storage.sessions.size, 0);
+});
+
+test("retained turns survive the per-session persist", async () => {
+  const storage = new IncrementalStorage(emptyState());
+  const buffer = new SmartBuffer(parseConfig({ triggerMode: "every_n", bufferMaxTurns: 100 }), storage);
+
+  await buffer.addTurn("thread-a", makeTurn("thread-a", "alpha"));
+  await buffer.flushPendingSave();
+  await buffer.retainDeferredTurns("thread-a", [makeTurn("thread-a", "alpha")], 5);
+  await buffer.flushPendingSave();
+
+  const record = storage.sessions.get("thread-a");
+  assert.equal(record?.entry.retainedTurns?.length, 1, "retained turns were not persisted");
+  assert.equal(record?.entry.retainedTurns?.[0]?.content, "alpha");
+});
+
+test("buffer state survives a restart through per-session files", async () => {
+  const root = await mkdtemp(path.join(os.tmpdir(), "remnic-bufio-restart-"));
+  try {
+    const storage = new StorageManager(root);
+    const config = parseConfig({ triggerMode: "every_n", bufferMaxTurns: 100 });
+    const first = new SmartBuffer(config, storage);
+    await first.addTurn("thread-a", makeTurn("thread-a", "alpha"));
+    await first.addTurn("thread-b", makeTurn("thread-b", "beta"));
+    await first.flushPendingSave();
+
+    // A fresh process reads the buffer back from the per-session files.
+    const second = new SmartBuffer(config, storage);
+    await second.load();
+    assert.equal(second.getTurns("thread-a").length, 1);
+    assert.equal(second.getTurns("thread-a")[0]?.content, "alpha");
+    assert.equal(second.getTurns("thread-b")[0]?.content, "beta");
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});
+
+test("legacy-only storage keeps the whole-state saveBuffer behavior", async () => {
+  const storage = new LegacyOnlyStorage(emptyState());
+  const buffer = new SmartBuffer(parseConfig({ triggerMode: "every_n", bufferMaxTurns: 100 }), storage);
+
+  await buffer.addTurn("thread-a", makeTurn("thread-a", "alpha"));
+  await buffer.flushPendingSave();
+  await buffer.addTurn("thread-b", makeTurn("thread-b", "beta"));
+  await buffer.flushPendingSave();
+
+  assert.ok(storage.wholeStateSaves >= 2, "legacy storage did not receive whole-state saves");
+  assert.equal(storage.lastSaved?.entries?.["thread-a"]?.turns[0]?.content, "alpha");
+  assert.equal(storage.lastSaved?.entries?.["thread-b"]?.turns[0]?.content, "beta");
+});

package/src/buffer-persistence.ts

@@ -0,0 +1,89 @@
+import type { BufferEntryState, BufferState, BufferSurpriseEvent } from "./types.js";
+
+/**
+ * The buffer persistence surface SmartBuffer depends on.
+ *
+ * `saveBufferSession` / `deleteBufferSession` are the per-session incremental
+ * writes (one file per session); when a storage backend does not provide
+ * them, the buffer falls back to the whole-state `saveBuffer`. Both are
+ * optional in the type so a storage double only has to implement what it
+ * actually supports.
+ */
+export interface BufferStorage {
+  loadBuffer(): Promise<BufferState>;
+  saveBuffer(state: BufferState): Promise<void>;
+  saveBufferSession?(key: string, entry: BufferEntryState): Promise<void>;
+  deleteBufferSession?(key: string): Promise<void>;
+  /** Optional surprise-telemetry sink; older storage and test doubles omit it. */
+  appendBufferSurpriseEvents?(events: BufferSurpriseEvent[]): Promise<number>;
+}
+
+/**
+ * Tracks which sessions' persisted files are stale and writes only those.
+ *
+ * Marks are cleared only after a durable write of that session. All calls
+ * happen under SmartBuffer's serialized mutation chain: one writer.
+ */
+export class BufferSessionPersistence {
+  private readonly dirty = new Set<string>();
+  private readonly deleted = new Set<string>();
+
+  markDirty(key: string): void {
+    this.dirty.add(key);
+    this.deleted.delete(key);
+  }
+
+  markDeleted(key: string): void {
+    this.deleted.add(key);
+    this.dirty.delete(key);
+  }
+
+  /** Eviction removed `key` from memory: its session file must go, any pending write is moot. */
+  markEvicted(keys: readonly string[]): void {
+    for (const key of keys) this.markDeleted(key);
+  }
+
+  hasPending(): boolean {
+    return this.dirty.size > 0 || this.deleted.size > 0;
+  }
+
+  /**
+   * Persist buffer state. On session-capable storage this writes ONLY the
+   * sessions whose state changed since the last successful persist and
+   * deletes files for evicted/reset sessions, so the observe path never
+   * re-serializes other sessions' turns. On legacy storage it falls back to
+   * the whole-state saveBuffer. Files are deleted before dirty writes: a
+   * crash mid-persist can then only resurrect already-evicted data (the same
+   * exposure as a whole-file rewrite), never drop sessions the state says
+   * exist.
+   */
+  async persist(
+    storage: BufferStorage,
+    state: BufferState,
+    peekEntry: (key: string) => BufferEntryState | undefined,
+  ): Promise<void> {
+    const saveSession = storage.saveBufferSession?.bind(storage);
+    const deleteSession = storage.deleteBufferSession?.bind(storage);
+    if (!saveSession || !deleteSession) {
+      await storage.saveBuffer(state);
+      this.dirty.clear();
+      this.deleted.clear();
+      return;
+    }
+    for (const key of [...this.deleted]) {
+      await deleteSession(key);
+      this.deleted.delete(key);
+    }
+    for (const key of [...this.dirty]) {
+      const entry = peekEntry(key);
+      if (!entry) {
+        // A dirty key without state must not be written from a fabricated
+        // empty entry: treat it as a deletion instead.
+        this.markDeleted(key);
+        continue;
+      }
+      await saveSession(key, entry);
+      this.dirty.delete(key);
+    }
+  }
+}

package/src/buffer.ts

@@ -1,7 +1,8 @@
 import { log } from "./logger.js";
 import { throwIfAborted } from "./abort-error.js";
 import { scanSignals } from "./signal.js";
-import type { StorageManager } from "./storage.js";
+import { BufferSessionPersistence, type BufferStorage } from "./buffer-persistence.js";
+import { selectEvictedBufferKeys } from "./buffer-eviction.js";
 import type {
   BufferEntryState,
   BufferState,
@@ -175,9 +176,12 @@ export class SmartBuffer {
    * activity (see BUFFER_SAVE_MAX_DEFER_MULTIPLIER). */
   private firstPendingAtMs: number | null = null;
 
+  /** Which sessions' persisted files are stale (per-session incremental saves). */
+  private readonly persistence = new BufferSessionPersistence();
+
   constructor(
     private readonly config: PluginConfig,
-    private readonly storage: StorageManager,
+    private readonly storage: BufferStorage,
     surpriseProbe: BufferSurpriseProbe | null = null,
   ) {
     this.state = { turns: [], lastExtractionAt: null, extractionCount: 0 };
@@ -261,60 +265,20 @@ export class SmartBuffer {
     );
   }
 
+  /** Evict oldest entries past MAX_BUFFER_ENTRY_COUNT and queue their session files for deletion. */
   private pruneEntries(retainKeys: string[]): void {
     const entries = this.state.entries;
     if (!entries) return;
-    const keys = Object.keys(entries);
-    if (keys.length <= MAX_BUFFER_ENTRY_COUNT) return;
-
-    const insertionOrder = new Map(keys.map((key, index) => [key, index]));
-    const byOldestActivity = (left: string, right: string): number => {
-      const leftAt = this.entryActivityAt(entries[left] ?? {
-        turns: [],
-        lastExtractionAt: null,
-        extractionCount: 0,
-      });
-      const rightAt = this.entryActivityAt(entries[right] ?? {
-        turns: [],
-        lastExtractionAt: null,
-        extractionCount: 0,
-      });
-      if (leftAt !== rightAt) return leftAt - rightAt;
-      return (insertionOrder.get(left) ?? 0) - (insertionOrder.get(right) ?? 0);
-    };
-    const candidates = keys.filter(
-      (key) =>
-        key !== "default" &&
-        !retainKeys.includes(key) &&
-        // #3251: accepted captures exit via refusal/backpressure, never eviction.
-        !this.entryHoldsAcceptedCapture(entries[key]),
-    );
-    const emptyRemovable = candidates
-      .filter((key) => (entries[key]?.turns.length ?? 0) === 0)
-      .sort(byOldestActivity);
-
-    const removableCount = Math.max(0, keys.length - MAX_BUFFER_ENTRY_COUNT);
-    let evicted = emptyRemovable.slice(0, removableCount);
-    if (evicted.length < removableCount) {
-      // Retained failed extractions (#1908 retry retention) keep their turns in
-      // the buffer, so empty entries alone may not bring the map back under the
-      // cap during a provider outage. The cap is the documented bound — evict
-      // the oldest NON-empty sessions too rather than growing unboundedly
-      // (codex review).
-      const nonEmptyRemovable = candidates
-        .filter((key) => (entries[key]?.turns.length ?? 0) > 0)
-        .sort(byOldestActivity);
-      evicted = evicted.concat(nonEmptyRemovable.slice(0, removableCount - evicted.length));
-    }
-    for (const key of evicted) {
-      delete entries[key];
-    }
+    const evicted = selectEvictedBufferKeys(entries, retainKeys, MAX_BUFFER_ENTRY_COUNT, {
+      activityAt: (entry) => this.entryActivityAt(entry),
+      holdsAcceptedCapture: (entry) => this.entryHoldsAcceptedCapture(entry),
+    });
+    for (const key of evicted) delete entries[key];
+    this.persistence.markEvicted(evicted);
     if (evicted.length > 0) {
-      // Loud degradation (extraction hot-loop hardening, Step 7): during a
-      // prolonged provider outage the breaker holds extraction off and buffered
-      // sessions accumulate. Eviction of the oldest empty session entries past
-      // MAX_BUFFER_ENTRY_COUNT is bounded and expected, but must be observable —
-      // not silent — so operators can see buffer pressure.
+      // Loud degradation (extraction hot-loop hardening, Step 7): buffer
+      // pressure during a provider outage is bounded and expected, but must
+      // be observable, not silent.
       log.warn(
         `buffer: pruned ${evicted.length} oldest session entr${evicted.length === 1 ? "y" : "ies"} ` +
           `past MAX_BUFFER_ENTRY_COUNT=${MAX_BUFFER_ENTRY_COUNT}; buffered turn data for those sessions was dropped`,
@@ -376,12 +340,15 @@ export class SmartBuffer {
    * so the buffer can still accept new turns for the rest of the session.
    */
   resetToEmpty(): void {
+    for (const key of Object.keys(this.state.entries ?? {})) {
+      this.persistence.markDeleted(key);
+    }
     this.state = { turns: [], lastExtractionAt: null, extractionCount: 0 };
     this.loaded = true;
   }
 
   private async saveUnlocked(): Promise<void> {
-    await this.storage.saveBuffer(this.state);
+    await this.persistence.persist(this.storage, this.state, (key) => this.peekEntry(key) ?? undefined);
   }
 
   async save(): Promise<void> {
@@ -495,13 +462,16 @@ export class SmartBuffer {
       clearTimeout(this.saveTimer);
       this.saveTimer = null;
     }
-    if (!this.pendingSave) return;
+    // resetToEmpty-only deletions are pending work too, even with no
+    // pending-save flag set.
+    if (!this.pendingSave && !this.persistence.hasPending()) return;
     try {
       await this.enqueueMutation(async () => {
         // Re-check under the serializer: a concurrent flush may have already
         // persisted this pending save. Skip the redundant write (no phantom
-        // writes).
-        if (!this.pendingSave) return;
+        // writes). resetToEmpty-only deletions also land here without a
+        // pending-save flag.
+        if (!this.pendingSave && !this.persistence.hasPending()) return;
         await this.saveUnlocked();
         // Clear the pending flag INSIDE the same serialized mutation as the
         // write (issue #1909 review). Clearing it after the enqueue await
@@ -579,6 +549,7 @@ export class SmartBuffer {
     for (const key of emptyRemovable) {
       if (Object.keys(entries).length < MAX_BUFFER_ENTRY_COUNT) break;
       delete entries[key];
+      this.persistence.markDeleted(key);
     }
   }
 
@@ -714,6 +685,7 @@ export class SmartBuffer {
     const decision = this.evaluate(entry, signal.level);
     const turnCountInWindow = entry.turns.length;
 
+    this.persistence.markDirty(bufferKey);
     this.pruneEntries([bufferKey]);
     if (decision === "keep_buffering" && this.config.bufferSaveDebounceMs > 0) {
       // Steady-state buffering: coalesce the whole-state serialize onto a
@@ -792,11 +764,7 @@ export class SmartBuffer {
   private async emitSurpriseEventSafe(
     params: SurpriseTelemetryQueueEntry,
   ): Promise<void> {
-    const storage = this.storage as StorageManager & {
-      appendBufferSurpriseEvents?: (
-        events: BufferSurpriseEvent[],
-      ) => Promise<number>;
-    };
+    const storage = this.storage;
     if (typeof storage.appendBufferSurpriseEvents !== "function") {
       // Older StorageManager / test double without the telemetry sink.
       // Silently skip — core path is still covered by the log line above.
@@ -955,6 +923,7 @@ export class SmartBuffer {
       );
       if (retained.length > 0) entry.retainedTurns = retained;
       else delete entry.retainedTurns;
+      this.persistence.markDirty(bufferKey);
       await this.saveUnlocked();
     });
   }
@@ -1062,6 +1031,7 @@ export class SmartBuffer {
         if (remainingTurns.length > 0) entry.retainedTurns = remainingTurns;
         else delete entry.retainedTurns;
         if (bufferKey === "default") this.state.turns = entry.turns;
+        this.persistence.markDirty(bufferKey);
       }
       if (changed || hadPendingSave) {
         assertLifecycle();
@@ -1172,6 +1142,7 @@ export class SmartBuffer {
         this.state.lastExtractionAt = entry.lastExtractionAt;
         this.state.extractionCount = entry.extractionCount;
       }
+      this.persistence.markDirty(bufferKey);
       this.pruneEntries([bufferKey]);
       await this.saveNowRetainingPendingOnFailure("clearAfterExtraction");
     });

package/src/local-llm-headers-timeout.test.ts

@@ -12,6 +12,7 @@ import {
 } from "undici";
 
 import { LocalLlmClient } from "./local-llm.js";
+import { probeFetch } from "./local-llm-helpers.js";
 import { classifyAnalysisProviderError } from "./activity/timeline/analysis-provider.js";
 import { ChatTransport } from "./local-llm-transport.js";
 import { initLogger, resetLogger } from "./logger.js";
@@ -466,6 +467,69 @@ test("a process-wide custom dispatcher is left in place", async () => {
   await restored.close();
 });
 
+test("an explicit opt-in widens the pool even when a custom global dispatcher is installed", async () => {
+  // Some hosts install a process-wide dispatcher (for example an agent runtime's
+  // managed proxy) that is unrelated to the LAN model server. There the 300s
+  // header cap stood silently and every slow completion died with `fetch failed`
+  // at 301s. REMNIC_LOCAL_LLM_DIRECT=1 declares that the local endpoint is
+  // reached directly, so the transport uses its own pool. Without the flag the
+  // previous behavior (leave the custom dispatcher alone) is unchanged.
+  const original = getGlobalDispatcher();
+  const proxy = new ProxyAgent("http://127.0.0.1:9");
+  const priorFlag = process.env.REMNIC_LOCAL_LLM_DIRECT;
+  try {
+    setGlobalDispatcher(proxy);
+    delete process.env.REMNIC_LOCAL_LLM_DIRECT;
+    assert.equal(new ChatTransport().dispatcherFor(900_000), undefined, "no flag: custom dispatcher stays");
+
+    process.env.REMNIC_LOCAL_LLM_DIRECT = "1";
+    const transport = new ChatTransport();
+    const agent = transport.dispatcherFor(900_000);
+    assert.ok(agent instanceof Agent, "flag set: the widened pool must be used");
+    assert.ok(!(agent instanceof ProxyAgent), "flag set: the proxy dispatcher must not be used");
+    await agent.close();
+
+    process.env.REMNIC_LOCAL_LLM_DIRECT = "0";
+    assert.equal(new ChatTransport().dispatcherFor(900_000), undefined, "flag 0: custom dispatcher stays");
+  } finally {
+    if (priorFlag === undefined) delete process.env.REMNIC_LOCAL_LLM_DIRECT;
+    else process.env.REMNIC_LOCAL_LLM_DIRECT = priorFlag;
+    setGlobalDispatcher(original);
+    await proxy.close();
+  }
+});
+
+test("REMNIC_LOCAL_LLM_DIRECT=1 also sends availability probes around a global proxy dispatcher", async () => {
+  // A host whose global dispatcher cannot reach the LAN model server would fail
+  // checkAvailability() before any chat request runs, so direct mode must cover
+  // the probe as well as ChatTransport.post.
+  const server = http.createServer((_req, res) => {
+    res.setHeader("content-type", "application/json");
+    res.end('{"data":[]}');
+  });
+  await new Promise<void>((resolve) => server.listen(0, "127.0.0.1", resolve));
+  // SAFETY: listen(0, "127.0.0.1") above binds a TCP port, so address() is an AddressInfo, never a pipe string or null.
+  const { port } = server.address() as AddressInfo;
+  const url = `http://127.0.0.1:${port}/v1/models`;
+  const original = getGlobalDispatcher();
+  const priorFlag = process.env.REMNIC_LOCAL_LLM_DIRECT;
+  try {
+    setGlobalDispatcher(new ProxyAgent("http://127.0.0.1:9"));
+    delete process.env.REMNIC_LOCAL_LLM_DIRECT;
+    const viaProxy = await probeFetch(url, { timeoutMs: 2_000, headers: {} });
+    assert.equal(viaProxy.ok, false, "no flag: the probe goes through the (unreachable) proxy");
+
+    process.env.REMNIC_LOCAL_LLM_DIRECT = "1";
+    const direct = await probeFetch(url, { timeoutMs: 2_000, headers: {} });
+    assert.equal(direct.ok, true, "flag set: the probe reaches the endpoint directly");
+  } finally {
+    if (priorFlag === undefined) delete process.env.REMNIC_LOCAL_LLM_DIRECT;
+    else process.env.REMNIC_LOCAL_LLM_DIRECT = priorFlag;
+    setGlobalDispatcher(original);
+    await new Promise<void>((resolve) => server.close(() => resolve()));
+  }
+});
+
 test("aborting during a retry backoff stops the local request lane", async () => {
   const original = globalThis.fetch;
   const abortController = new AbortController();

package/src/local-llm-helpers.ts

@@ -1,5 +1,7 @@
 import type { ResponseFormatJSONSchema } from "openai/resources/shared";
+import type { Agent } from "undici";
 import { log } from "./logger.js";
+import { directProbeDispatcher } from "./local-llm-transport.js";
 import type { LocalLlmRequestPriority } from "./local-llm.js";
 
 export interface LocalLlmChatCompletionOptions {
@@ -167,7 +169,10 @@ export async function probeFetch(
     : controller.signal;
   const timeout = setTimeout(() => controller.abort(), options.timeoutMs);
   try {
-    const response = await fetch(url, { signal: requestSignal, headers: options.headers });
+    const init: RequestInit & { dispatcher?: Agent } = { signal: requestSignal, headers: options.headers };
+    const dispatcher = directProbeDispatcher();
+    if (dispatcher) init.dispatcher = dispatcher;
+    const response = await fetch(url, init);
     clearTimeout(timeout);
     if (!response.ok) {
       log.debug(`local LLM probe: ${url} returned HTTP ${response.status}`);

package/src/local-llm-transport.ts

@@ -40,6 +40,18 @@ function isPlainPoolingAgent(dispatcher: unknown): boolean {
   return ctor.name === "Agent";
 }
 
+/**
+ * REMNIC_LOCAL_LLM_DIRECT=1 declares that the local endpoint is reached
+ * directly. Availability probes use this shared plain pool in that mode so they
+ * take the same route as chat requests; `undefined` keeps the global dispatcher.
+ */
+let directProbeAgent: Agent | null = null;
+export function directProbeDispatcher(): Agent | undefined {
+  if (process.env.REMNIC_LOCAL_LLM_DIRECT !== "1") return undefined;
+  directProbeAgent ??= new Agent();
+  return directProbeAgent;
+}
+
 /**
  * Connection pool whose header/body inactivity budgets track the configured
  * request budget.
@@ -72,7 +84,8 @@ export class ChatTransport {
    * because only the dispatcher's owner knows how to rebuild it.
    */
   dispatcherFor(budgetMs: number): Agent | undefined {
-    if (!isPlainPoolingAgent(getGlobalDispatcher())) {
+    // REMNIC_LOCAL_LLM_DIRECT=1: the operator declares the local endpoint is reached directly even though the process installed a global dispatcher for other traffic (an agent runtime's managed proxy). Without it the 300s header cap stands silently on such hosts and every completion slower than five minutes dies with `fetch failed`. Off by default so deployments that must use a proxy keep it.
+    if (!isPlainPoolingAgent(getGlobalDispatcher()) && process.env.REMNIC_LOCAL_LLM_DIRECT !== "1") {
       if (!this.warnedAboutCustomDispatcher) {
         this.warnedAboutCustomDispatcher = true;
         log.debug(