@remnic/core 9.3.726 → 9.3.727

package/src/compat/codex-subpath-aliases.test.ts

@@ -0,0 +1,93 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+
+import * as canonicalCliFallback from "../cli-fallback.js";
+import * as canonicalThreadKey from "../thread-key.js";
+import * as aliasCliFallback from "./codex-cli-fallback.js";
+import * as aliasThreadKey from "./codex-thread-key.js";
+
+const pkgJsonPath = fileURLToPath(new URL("../../package.json", import.meta.url));
+
+test("codex-cli-fallback alias re-exports the same value symbols as cli-fallback", () => {
+  // export * forwards live bindings by reference, so the function objects and
+  // the test-hooks namespace are identical (===) across both subpaths.
+  assert.equal(
+    aliasCliFallback.callCodexCliFallback,
+    canonicalCliFallback.callCodexCliFallback,
+  );
+  assert.equal(
+    aliasCliFallback.setCodexCliFallbackRunnerForProcess,
+    canonicalCliFallback.setCodexCliFallbackRunnerForProcess,
+  );
+  assert.equal(
+    aliasCliFallback.__codexCliFallbackTestHooks,
+    canonicalCliFallback.__codexCliFallbackTestHooks,
+  );
+});
+
+test("codex-thread-key alias re-exports the same symbol as thread-key", () => {
+  assert.equal(
+    aliasThreadKey.CODEX_THREAD_KEY_PREFIX,
+    canonicalThreadKey.CODEX_THREAD_KEY_PREFIX,
+  );
+  assert.equal(aliasThreadKey.CODEX_THREAD_KEY_PREFIX, "codex-thread:");
+});
+
+test("every named runtime export of cli-fallback is forwarded by the alias", () => {
+  for (const key of Object.keys(canonicalCliFallback)) {
+    assert.equal(
+      key in aliasCliFallback,
+      true,
+      `alias missing forwarded export: ${key}`,
+    );
+  }
+});
+
+test("importing the old subpath resolves to the same symbol as the new subpath", async () => {
+  // @remnic/core self-references its own exports map. Under --conditions=
+  // remnic-source (set by preflight/test NODE_OPTIONS) the subpaths resolve to
+  // src/. Both specifiers land on the same module record, so the exported
+  // function is the same object reference.
+  const [byNew, byOld] = await Promise.all([
+    import("@remnic/core/cli-fallback"),
+    import("@remnic/core/codex-cli-fallback"),
+  ]);
+  assert.equal(byOld.callCodexCliFallback, byNew.callCodexCliFallback);
+
+  const [newKey, oldKey] = await Promise.all([
+    import("@remnic/core/thread-key"),
+    import("@remnic/core/codex-thread-key"),
+  ]);
+  assert.equal(oldKey.CODEX_THREAD_KEY_PREFIX, newKey.CODEX_THREAD_KEY_PREFIX);
+});
+
+test("the deprecated subpaths are registered with a removal timeline in the exports map", () => {
+  const pkg = JSON.parse(readFileSync(pkgJsonPath, "utf8")) as {
+    exports: Record<string, { deprecated?: string; import?: string }>;
+  };
+  const aliasEntries = [
+    "./codex-cli-fallback",
+    "./codex-cli-fallback.js",
+    "./codex-thread-key",
+    "./codex-thread-key.js",
+  ];
+  for (const subpath of aliasEntries) {
+    const entry = pkg.exports[subpath];
+    assert.ok(entry, `missing exports entry for ${subpath}`);
+    assert.ok(
+      entry.deprecated,
+      `exports entry for ${subpath} missing a deprecated field`,
+    );
+    assert.match(
+      entry.deprecated,
+      /v?10\.0\.0|remov/i,
+      `deprecated field for ${subpath} should state a removal timeline`,
+    );
+    assert.ok(
+      entry.import?.includes("/compat/"),
+      `exports entry for ${subpath} should target the compat re-export module`,
+    );
+  }
+});

package/src/compat/codex-thread-key.ts

@@ -0,0 +1,23 @@
+/**
+ * Deprecated alias subpath `@remnic/core/codex-thread-key`.
+ *
+ * PR #1638 renamed `src/codex-thread-key.ts` -> `src/thread-key.ts` to
+ * graduate the host-prefixed name per CLAUDE.md rule 31. This thin re-export
+ * keeps the old subpath resolving during the compat window so external
+ * consumers importing `@remnic/core/codex-thread-key` do not hit
+ * ERR_PACKAGE_PATH_NOT_EXPORTED. It forwards every export to the canonical
+ * module -- no logic is duplicated.
+ *
+ * Removal timeline: v10.0.0 (see issue #1643).
+ * Import from `@remnic/core/thread-key` instead.
+ */
+export * from "../thread-key.js";
+
+process.emitWarning(
+  "@remnic/core/codex-thread-key is a deprecated alias; import from @remnic/core/thread-key instead. Removed in v10.0.0 (issue #1643).",
+  {
+    type: "DeprecationWarning",
+    code: "REMNIC_DEP_CORE_SUBPATH_CODEX_THREAD_KEY",
+    detail: "PR #1638 renamed codex-thread-key.ts to thread-key.ts.",
+  },
+);

package/src/extraction-faithfulness.test.ts

@@ -26,6 +26,7 @@ import type { FaithfulnessResult } from "./extraction-faithfulness.js";
 import type { FallbackLlmClient } from "./fallback-llm.js";
 import type { LocalLlmClient } from "./local-llm.js";
 import type { MemoryFrontmatter } from "./types.js";
+import { callOpenAiCompatibleChat } from "./local-model-endpoint.js";
 
 // ---------------------------------------------------------------------------
 // Helpers — stub LLM clients
@@ -1429,3 +1430,242 @@ test("checkFaithfulnessBatch: local-endpoint failure does NOT leak the local mod
   );
   assert.equal(result.results[0]?.ok, true);
 });
+
+// ---------------------------------------------------------------------------
+// Issue #1700 nits #5 + #6: probe signal forwarding + local parse-fallback
+// ---------------------------------------------------------------------------
+
+test("callOpenAiCompatibleChat: a pre-aborted batch signal aborts the probe immediately, not after timeoutMs (#1700 nit #5)", async () => {
+  // The batch signal is ALREADY aborted when the probe starts. With nit #5 the
+  // probe forwards it and aborts instantly; without it the probe would wait for
+  // its own timeoutMs (5000ms here). Assert the probe returns null fast.
+  const endpoint = { baseUrl: "http://localhost:11434/v1", model: "remnic-faithfulness-gate-v1" };
+  const batchController = new AbortController();
+  batchController.abort();
+  const spy = ((_url: string, init: RequestInit) =>
+    new Promise<Response>((_resolve, reject) => {
+      const sig = init.signal;
+      if (!sig) return reject(new Error("no signal"));
+      if (sig.aborted) return reject(new Error("aborted"));
+      sig.addEventListener("abort", () => reject(new Error("aborted")), { once: true });
+    })) as unknown as typeof fetch;
+  const start = Date.now();
+  const result = await callOpenAiCompatibleChat(
+    endpoint,
+    [{ role: "user", content: "hi" }],
+    { timeoutMs: 5000, signal: batchController.signal },
+    spy,
+  );
+  const elapsed = Date.now() - start;
+  assert.equal(result, null, "a pre-aborted signal must fail the probe closed (null)");
+  assert.ok(
+    elapsed < 1000,
+    `probe must abort immediately on a pre-aborted signal (${elapsed}ms), not wait timeoutMs`,
+  );
+});
+
+test("checkFaithfulnessBatch: default surfaces malformed_output for a 200-with-garbage local response (#1700 nit #6)", async () => {
+  // extractionFaithfulnessLocalParseFallback unset (default false): a local
+  // endpoint returning 200 with non-verdict JSON surfaces malformed_output so a
+  // misconfigured endpoint is visible. The configured chain must NOT run.
+  const inputs = [{ factText: "Fact", quote: "Quote" }];
+  const config = parseConfig({
+    extractionFaithfulnessModel: "remnic-faithfulness-gate-v1",
+    extractionFaithfulnessBaseUrl: "http://localhost:11434/v1",
+    extractionFaithfulnessTimeoutMs: 5000,
+  });
+  const fallbackCalls: Array<{ messages: unknown; options: unknown }> = [];
+  const { fetch: garbageFetch } = fakeFetchFor("http://localhost:11434/v1", () => ({
+    model: "remnic-faithfulness-gate-v1",
+    choices: [{ message: { content: "this is not a verdict array" } }],
+  }));
+  const result = await checkFaithfulnessBatch(
+    inputs,
+    config,
+    null,
+    stubFallbackLlm(JSON.stringify([{ index: 0, verdict: "entailed" }]), fallbackCalls),
+    garbageFetch,
+  );
+  assert.equal(fallbackCalls.length, 0, "chain must NOT run when flag is off — garbage surfaces loudly");
+  assert.equal(result.results[0]?.ok, false);
+  if (!result.results[0]?.ok) {
+    assert.equal(result.results[0].error.code, "malformed_output");
+  }
+});
+
+test("checkFaithfulnessBatch: extractionFaithfulnessLocalParseFallback falls back to the chain on local parse failure (#1700 nit #6)", async () => {
+  // Flag ON: the same 200-with-garbage local response now falls through to the
+  // configured chain instead of surfacing malformed_output (resilient fallback).
+  const inputs = [{ factText: "Fact", quote: "Quote" }];
+  const config = parseConfig({
+    extractionFaithfulnessModel: "remnic-faithfulness-gate-v1",
+    extractionFaithfulnessBaseUrl: "http://localhost:11434/v1",
+    extractionFaithfulnessTimeoutMs: 5000,
+    extractionFaithfulnessLocalParseFallback: true,
+  });
+  const fallbackCalls: Array<{ messages: unknown; options: unknown }> = [];
+  const { fetch: garbageFetch } = fakeFetchFor("http://localhost:11434/v1", () => ({
+    model: "remnic-faithfulness-gate-v1",
+    choices: [{ message: { content: "this is not a verdict array" } }],
+  }));
+  const result = await checkFaithfulnessBatch(
+    inputs,
+    config,
+    null,
+    stubFallbackLlm(JSON.stringify([{ index: 0, verdict: "entailed" }]), fallbackCalls),
+    garbageFetch,
+  );
+  assert.equal(
+    fallbackCalls.length,
+    1,
+    "chain MUST run when flag is on and the local response is unparseable",
+  );
+  assert.equal(result.results[0]?.ok, true);
+  if (result.results[0]?.ok) {
+    assert.equal(result.results[0].verdict, "entailed", "fallback chain verdict is used");
+  }
+});
+
+test("checkFaithfulnessBatch: extractionFaithfulnessLocalParseFallback does NOT fall back when the local response is valid (#1700 nit #6 regression)", async () => {
+  // Flag ON but the local response IS a valid verdict array → use it, do not
+  // call the chain. Guards against the flag over-triggering on good responses.
+  const inputs = [{ factText: "Fact", quote: "Quote" }];
+  const config = parseConfig({
+    extractionFaithfulnessModel: "remnic-faithfulness-gate-v1",
+    extractionFaithfulnessBaseUrl: "http://localhost:11434/v1",
+    extractionFaithfulnessTimeoutMs: 5000,
+    extractionFaithfulnessLocalParseFallback: true,
+  });
+  const fallbackCalls: Array<{ messages: unknown; options: unknown }> = [];
+  const { fetch: goodFetch } = fakeFetchFor("http://localhost:11434/v1", () => ({
+    model: "remnic-faithfulness-gate-v1",
+    choices: [{ message: { content: JSON.stringify([{ index: 0, verdict: "contradicted" }]) } }],
+  }));
+  const result = await checkFaithfulnessBatch(
+    inputs,
+    config,
+    null,
+    stubFallbackLlm(JSON.stringify([{ index: 0, verdict: "entailed" }]), fallbackCalls),
+    goodFetch,
+  );
+  assert.equal(fallbackCalls.length, 0, "chain must NOT run when the local response is valid, even with the flag on");
+  assert.equal(result.results[0]?.ok, true);
+  if (result.results[0]?.ok) {
+    assert.equal(result.results[0].verdict, "contradicted", "valid local verdict is used");
+  }
+});
+
+test("checkFaithfulnessBatch: extractionFaithfulnessLocalParseFallback falls back when the local response is a PARTIAL verdict array (codex P2 PRRT_kwDORJXyws6O6zwZ)", async () => {
+  // Flag ON: a local endpoint that returns a valid-but-INCOMPLETE verdict
+  // array (1 of N entries) must fall through to the configured chain, NOT be
+  // accepted as-is. parseFaithfulnessResponse is truthy as soon as ONE entry
+  // is valid, so the previous guard accepted the partial response and the
+  // missing indexes surfaced as malformed_output downstream -- defeating the
+  // resilient fallback. Accept the local response only when it covers every
+  // expected index.
+  const inputs = [
+    { factText: "Fact A", quote: "Quote A" },
+    { factText: "Fact B", quote: "Quote B" },
+  ];
+  const config = parseConfig({
+    extractionFaithfulnessModel: "remnic-faithfulness-gate-v1",
+    extractionFaithfulnessBaseUrl: "http://localhost:11434/v1",
+    extractionFaithfulnessTimeoutMs: 5000,
+    extractionFaithfulnessLocalParseFallback: true,
+  });
+  const fallbackCalls: Array<{ messages: unknown; options: unknown }> = [];
+  // Local endpoint returns only index 0 -- index 1 is missing (partial).
+  const { fetch: partialFetch } = fakeFetchFor("http://localhost:11434/v1", () => ({
+    model: "remnic-faithfulness-gate-v1",
+    choices: [{ message: { content: JSON.stringify([{ index: 0, verdict: "contradicted" }]) } }],
+  }));
+  const result = await checkFaithfulnessBatch(
+    inputs,
+    config,
+    null,
+    stubFallbackLlm(
+      JSON.stringify([
+        { index: 0, verdict: "entailed" },
+        { index: 1, verdict: "unsupported" },
+      ]),
+      fallbackCalls,
+    ),
+    partialFetch,
+  );
+  assert.equal(
+    fallbackCalls.length,
+    1,
+    "a partial local verdict array must fall through to the configured chain",
+  );
+  // The chain's complete verdict array is used for both indexes.
+  assert.equal(result.results[0]?.ok && result.results[0].verdict, "entailed");
+  assert.equal(result.results[1]?.ok && result.results[1].verdict, "unsupported");
+});
+
+test("checkFaithfulnessBatch: extractionFaithfulnessLocalParseFallback falls back when local indexes are fractional/non-contiguous (codex P2 PRRT_kwDORJXyws6O7PfY)", async () => {
+  // Flag ON: a malformed local response with expectedCount distinct but
+  // NON-INTEGER indexes (e.g. 0 and 0.5 for a two-item batch) must NOT be
+  // accepted. parseFaithfulnessResponse used to admit any numeric index, so a
+  // size-only check passed while index 1 stayed missing -> malformed_output.
+  // parseEntries now rejects non-integer indexes, and the gate requires every
+  // integer key 0..N-1 before accepting the local response.
+  const inputs = [
+    { factText: "Fact A", quote: "Quote A" },
+    { factText: "Fact B", quote: "Quote B" },
+  ];
+  const config = parseConfig({
+    extractionFaithfulnessModel: "remnic-faithfulness-gate-v1",
+    extractionFaithfulnessBaseUrl: "http://localhost:11434/v1",
+    extractionFaithfulnessTimeoutMs: 5000,
+    extractionFaithfulnessLocalParseFallback: true,
+  });
+  const fallbackCalls: Array<{ messages: unknown; options: unknown }> = [];
+  // Local endpoint returns indexes 0 and 0.5 -- two distinct keys, but index 1
+  // is missing (fractional index is invalid).
+  const { fetch: fracFetch } = fakeFetchFor("http://localhost:11434/v1", () => ({
+    model: "remnic-faithfulness-gate-v1",
+    choices: [{ message: { content: JSON.stringify([
+      { index: 0, verdict: "contradicted" },
+      { index: 0.5, verdict: "entailed" },
+    ]) } }],
+  }));
+  const result = await checkFaithfulnessBatch(
+    inputs,
+    config,
+    null,
+    stubFallbackLlm(
+      JSON.stringify([
+        { index: 0, verdict: "entailed" },
+        { index: 1, verdict: "unsupported" },
+      ]),
+      fallbackCalls,
+    ),
+    fracFetch,
+  );
+  assert.equal(
+    fallbackCalls.length,
+    1,
+    "a fractional/non-contiguous local response must fall through to the chain",
+  );
+  assert.equal(result.results[0]?.ok && result.results[0].verdict, "entailed");
+  assert.equal(result.results[1]?.ok && result.results[1].verdict, "unsupported");
+});
+
+test('parseConfig: extractionFaithfulnessLocalParseFallback coerces CLI string "true" (#1700 review — coerceBool parity)', () => {
+  // A CLI override reaches the parser as the string "true"; === true would
+  // silently leave the flag disabled. coerceBool must turn it on (gotcha 36).
+  const onByString = parseConfig({
+    extractionFaithfulnessLocalParseFallback: "true",
+  });
+  assert.equal(onByString.extractionFaithfulnessLocalParseFallback, true);
+  const onByBool = parseConfig({
+    extractionFaithfulnessLocalParseFallback: true,
+  });
+  assert.equal(onByBool.extractionFaithfulnessLocalParseFallback, true);
+  const offDefault = parseConfig({});
+  assert.equal(offDefault.extractionFaithfulnessLocalParseFallback, false);
+  const offByString = parseConfig({
+    extractionFaithfulnessLocalParseFallback: "false",
+  });
+  assert.equal(offByString.extractionFaithfulnessLocalParseFallback, false);
+});

package/src/extraction-faithfulness.ts

@@ -220,6 +220,27 @@ export function parseFaithfulnessResponse(
   return null;
 }
 
+/**
+ * True when `map` contains an entry for every integer index in
+ * [0, expectedCount). The local parse-fallback gate uses this to accept a
+ * local model-lab response only when it is COMPLETE: size alone is
+ * insufficient because a malformed response with duplicate/fractional indexes
+ * can yield expectedCount distinct map keys without covering index 0..N-1
+ * (codex P2 PRRT_kwDORJXyws6O7PfY). parseEntries now rejects non-integer
+ * indexes so the two checks agree, but the explicit coverage loop documents
+ * the invariant and stays robust to any future parser relaxation.
+ */
+function coversAllIndexes(
+  map: Map<number, ParsedFaithfulnessEntry>,
+  expectedCount: number,
+): boolean {
+  if (map.size < expectedCount) return false;
+  for (let i = 0; i < expectedCount; i++) {
+    if (!map.has(i)) return false;
+  }
+  return true;
+}
+
 function parseEntries(
   data: unknown,
   expectedCount: number,
@@ -243,7 +264,7 @@ function parseEntries(
     if (!entry || typeof entry !== "object") continue;
     const obj = entry as Record<string, unknown>;
     const idx = typeof obj.index === "number" ? obj.index : undefined;
-    if (idx === undefined || idx < 0 || idx >= expectedCount) continue;
+    if (idx === undefined || !Number.isInteger(idx) || idx < 0 || idx >= expectedCount) continue;
     const verdictRaw = typeof obj.verdict === "string" ? obj.verdict : undefined;
     if (!verdictRaw || !VALID_VERDICTS.has(verdictRaw)) continue;
     const rationale =
@@ -279,6 +300,7 @@ interface LlmCallResult {
 async function callFaithfulnessLlm(
   systemPrompt: string,
   userPrompt: string,
+  expectedCount: number,
   config: PluginConfig,
   localLlm: LocalLlmClient | null,
   fallbackLlm: FallbackLlmClient | null,
@@ -311,15 +333,44 @@ async function callFaithfulnessLlm(
     const result = await callOpenAiCompatibleChat(
       localEndpoint,
       messages,
-      { temperature: 0.1, maxTokens: 2048, responseFormatJson: true, timeoutMs: probeBudgetMs },
+      {
+        temperature: 0.1,
+        maxTokens: 2048,
+        responseFormatJson: true,
+        timeoutMs: probeBudgetMs,
+        // Forward the batch signal so the probe aborts the instant the batch
+        // budget elapses, not after probeBudgetMs (issue #1700 nit #5).
+        ...(signal ? { signal } : {}),
+      },
       fetchImpl,
     );
     if (result?.content) {
-      return { content: result.content, modelUsed: result.modelUsed };
+      // Issue #1700 nit #6: pre-validate the local endpoint response shape.
+      // Default (extractionFaithfulnessLocalParseFallback=false) returns the
+      // content as-is -- a 200-with-garbage local response surfaces
+      // malformed_output, alerting the operator to a misconfigured endpoint.
+      // When the operator opts into resilient fallback, an unparseable OR
+      // PARTIAL local response falls through to the configured chain instead
+      // of surfacing. parseFaithfulnessResponse is truthy as soon as ONE entry
+      // is valid, so accept the local response only when the parsed verdict
+      // map covers every expected index -- otherwise the missing indexes would
+      // surface as malformed_output downstream, defeating the resilient
+      // fallback (codex P2 PRRT_kwDORJXyws6O6zwZ).
+      if (!config.extractionFaithfulnessLocalParseFallback) {
+        return { content: result.content, modelUsed: result.modelUsed };
+      }
+      const parsedLocal = parseFaithfulnessResponse(result.content, expectedCount);
+      if (parsedLocal && coversAllIndexes(parsedLocal, expectedCount)) {
+        return { content: result.content, modelUsed: result.modelUsed };
+      }
+      log.debug(
+        "extraction-faithfulness: local endpoint returned incomplete/unparseable output; falling back to configured chain",
+      );
+    } else {
+      log.debug(
+        "extraction-faithfulness: local model-lab endpoint unavailable, trying configured chain",
+      );
     }
-    log.debug(
-      "extraction-faithfulness: local model-lab endpoint unavailable, trying configured chain",
-    );
   }
 
   // extractionFaithfulnessModel is the LOCAL served model's name (e.g.
@@ -532,6 +583,7 @@ export async function checkFaithfulnessBatch(
     const callPromise = callFaithfulnessLlm(
       FAITHFULNESS_SYSTEM_PROMPT,
       userPrompt,
+      checkableInputs.length,
       config,
       localLlm,
       fallbackLlm,

package/src/faithfulness-config.ts

@@ -17,7 +17,7 @@
  * `config.ts` spread the result in one line.
  */
 
-import { coerceNumber } from "./connectors/coerce.js";
+import { coerceBool, coerceNumber } from "./connectors/coerce.js";
 
 /**
  * Parse a value as a strict integer >= `min`, throwing on anything else.
@@ -67,6 +67,7 @@ export function parseFaithfulnessGateConfig(cfg: Record<string, unknown>): {
   extractionFaithfulnessBaseUrl: string;
   extractionFaithfulnessContextChars: number;
   extractionFaithfulnessTimeoutMs: number;
+  extractionFaithfulnessLocalParseFallback: boolean;
 } {
   const gateValue = cfg.extractionFaithfulnessGate;
   let extractionFaithfulnessGate: "off" | "shadow" | "enforce";
@@ -105,12 +106,26 @@ export function parseFaithfulnessGateConfig(cfg: Record<string, unknown>): {
     60_000,
   );
 
+  // Issue #1700 nit #6: resilient-fallback toggle for the local model-lab
+  // endpoint. Default false preserves the loud-signal behavior (a 200-with-
+  // garbage local response surfaces malformed_output so a misconfigured
+  // endpoint is visible); true falls back to the configured chain on local
+  // parse failure. Byte-identical pre-feature when unset (rule 39).
+  // coerceBool for CLI-string parity: a CLI override like
+  // --config extractionFaithfulnessLocalParseFallback=true reaches here as the
+  // string "true"; === true would silently leave the flag disabled. Matches
+  // every other CLI-settable boolean in config.ts (gotcha 36, codex P2
+  // PRRT_kwDORJXyws6O6gDQ / cursor BUGBOT e273b22c).
+  const extractionFaithfulnessLocalParseFallback =
+    coerceBool(cfg.extractionFaithfulnessLocalParseFallback) === true;
+
   return {
     extractionFaithfulnessGate,
     extractionFaithfulnessModel,
     extractionFaithfulnessBaseUrl,
     extractionFaithfulnessContextChars,
     extractionFaithfulnessTimeoutMs,
+    extractionFaithfulnessLocalParseFallback,
   };
 }
 

package/src/local-model-endpoint.ts

@@ -42,10 +42,15 @@ export interface EndpointChatMessage {
 
 /** Options for a single local-endpoint chat call. */
 export interface EndpointChatOptions {
-  /** Per-call timeout in ms. The caller's batch AbortSignal is NOT forwarded
-   *  (matches the local-LLM precedent: each attempt is bounded by its own
-   *  timer so one slow server can't starve the batch). */
+  /** Per-call timeout in ms. Bounds each attempt so one slow server can't
+   *  starve the batch (matches the local-LLM precedent). */
   timeoutMs: number;
+  /** Optional batch AbortSignal forwarded into the probe (issue #1700 nit #5).
+   *  When the batch budget elapses (or the caller aborts), the in-flight probe
+   *  aborts immediately instead of waiting for its own `timeoutMs` — a
+   *  micro-optimization, not a correctness fix (the outer race already bounds
+   *  the total). Undefined preserves the prior per-attempt-only behavior. */
+  signal?: AbortSignal;
   /** Sampling temperature — classification wants low entropy (0.0–0.2). */
   temperature?: number;
   /** Max output tokens. */
@@ -119,6 +124,21 @@ export async function callOpenAiCompatibleChat(
   const url = joinBaseUrl(endpoint.baseUrl, "/chat/completions");
   const controller = new AbortController();
   const timer = setTimeout(() => controller.abort(), options.timeoutMs);
+  // Forward the batch AbortSignal into the probe (issue #1700 nit #5): if the
+  // batch budget already elapsed, abort the in-flight probe immediately rather
+  // than waiting for the probe's own timeoutMs. AbortSignal.any is ES2024
+  // (forbidden here); wire the listener manually + guard the already-aborted
+  // case. The fetch still uses the probe's controller, so clearing the timer
+  // below is the only cleanup needed.
+  const batchSignal = options.signal;
+  const onBatchAbort = () => controller.abort();
+  if (batchSignal) {
+    if (batchSignal.aborted) {
+      controller.abort();
+    } else {
+      batchSignal.addEventListener("abort", onBatchAbort, { once: true });
+    }
+  }
   try {
     const body: Record<string, unknown> = {
       model: endpoint.model,
@@ -150,6 +170,7 @@ export async function callOpenAiCompatibleChat(
     return { content, modelUsed: extractModel(parsed) ?? endpoint.model };
   } finally {
     clearTimeout(timer);
+    if (batchSignal) batchSignal.removeEventListener("abort", onBatchAbort);
   }
 }