@remnic/core 10.0.26 → 10.0.28

package/dist/who-knows-cli.js

@@ -4,9 +4,9 @@ import {
   renderWhoKnows,
   renderWhoKnowsJson,
   renderWhoKnowsText
-} from "./chunk-HGSERGFX.js";
-import "./chunk-4B7JO3LG.js";
-import "./chunk-5A4QMATS.js";
+} from "./chunk-4LJSCW24.js";
+import "./chunk-OGOADX26.js";
+import "./chunk-XALR4DOQ.js";
 import "./chunk-UHVXE24Y.js";
 import "./chunk-TRMJ6BYC.js";
 import "./chunk-V4JZCTMK.js";
@@ -31,7 +31,7 @@ import "./chunk-S2HLHAZ4.js";
 import "./chunk-MRPOZBJC.js";
 import "./chunk-DM2T26WE.js";
 import "./chunk-LDXUBPMO.js";
-import "./chunk-2DT7PIDZ.js";
+import "./chunk-EPOYPPOW.js";
 import "./chunk-AAD2ZS6P.js";
 import "./chunk-FF6N7BXC.js";
 import "./chunk-JNIVZNIB.js";
@@ -60,11 +60,11 @@ import "./chunk-IUM3VSHI.js";
 import "./chunk-C64XATK7.js";
 import "./chunk-42JKGUFJ.js";
 import "./chunk-23G5P7TA.js";
-import "./chunk-TKC5LZ43.js";
+import "./chunk-UIDWASOS.js";
 import "./chunk-I55KAVET.js";
 import "./chunk-L2EXJQJP.js";
 import "./chunk-45GF7Y3V.js";
-import "./chunk-EP6BA7VV.js";
+import "./chunk-CU5TILGD.js";
 import "./chunk-E2AWJ7KQ.js";
 import "./chunk-Z7L72ZHL.js";
 import "./chunk-4O4TKIXQ.js";
@@ -72,7 +72,7 @@ import "./chunk-YCVB7X56.js";
 import "./chunk-PQVCH2AE.js";
 import "./chunk-PJKTFXE2.js";
 import "./chunk-W5BIQOAJ.js";
-import "./chunk-42KSEX6C.js";
+import "./chunk-LDXNKEYB.js";
 import "./chunk-YBA52OKG.js";
 import "./chunk-5LRV557D.js";
 import "./chunk-BT7NVCML.js";

package/dist/who-knows.js

@@ -9,8 +9,8 @@ import {
   loadWhoKnowsEntities,
   tokenizeTopic,
   validateWhoKnowsInput
-} from "./chunk-4B7JO3LG.js";
-import "./chunk-5A4QMATS.js";
+} from "./chunk-OGOADX26.js";
+import "./chunk-XALR4DOQ.js";
 import "./chunk-UHVXE24Y.js";
 import "./chunk-TRMJ6BYC.js";
 import "./chunk-V4JZCTMK.js";
@@ -35,7 +35,7 @@ import "./chunk-S2HLHAZ4.js";
 import "./chunk-MRPOZBJC.js";
 import "./chunk-DM2T26WE.js";
 import "./chunk-LDXUBPMO.js";
-import "./chunk-2DT7PIDZ.js";
+import "./chunk-EPOYPPOW.js";
 import "./chunk-AAD2ZS6P.js";
 import "./chunk-FF6N7BXC.js";
 import "./chunk-JNIVZNIB.js";
@@ -64,11 +64,11 @@ import "./chunk-IUM3VSHI.js";
 import "./chunk-C64XATK7.js";
 import "./chunk-42JKGUFJ.js";
 import "./chunk-23G5P7TA.js";
-import "./chunk-TKC5LZ43.js";
+import "./chunk-UIDWASOS.js";
 import "./chunk-I55KAVET.js";
 import "./chunk-L2EXJQJP.js";
 import "./chunk-45GF7Y3V.js";
-import "./chunk-EP6BA7VV.js";
+import "./chunk-CU5TILGD.js";
 import "./chunk-E2AWJ7KQ.js";
 import "./chunk-Z7L72ZHL.js";
 import "./chunk-4O4TKIXQ.js";
@@ -76,7 +76,7 @@ import "./chunk-YCVB7X56.js";
 import "./chunk-PQVCH2AE.js";
 import "./chunk-PJKTFXE2.js";
 import "./chunk-W5BIQOAJ.js";
-import "./chunk-42KSEX6C.js";
+import "./chunk-LDXNKEYB.js";
 import "./chunk-YBA52OKG.js";
 import "./chunk-5LRV557D.js";
 import "./chunk-BT7NVCML.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@remnic/core",
-  "version": "10.0.26",
+  "version": "10.0.28",
   "description": "Framework-agnostic Remnic memory engine — orchestrator, storage, extraction, search, trust zones",
   "type": "module",
   "main": "dist/index.js",
@@ -3347,7 +3347,7 @@
     "core"
   ],
   "peerDependencies": {
-    "@remnic/coding-graph": "^10.0.26"
+    "@remnic/coding-graph": "^10.0.28"
   },
   "peerDependenciesMeta": {
     "@remnic/coding-graph": {

package/src/ambient-provenance.test.ts

@@ -11,6 +11,8 @@ import {
 import { parseConfig } from "./config.js";
 import { bufferTurnsEqual, copyBufferTurn } from "./buffer-turn-helpers.js";
 import { ExtractionEngine } from "./extraction.js";
+import { extractionProviderJsonSchema } from "./extraction-span-wire.js";
+import type { LocalLlmChatCompletionOptions } from "./local-llm-helpers.js";
 import { SUMMARY_SYSTEM_PROMPT } from "./meetings/summary-extractor.js";
 import { emptySpeakerRegistry } from "./wearables/speakers.js";
 import { buildExtractionTurns } from "./wearables/memory-gen.js";
@@ -77,20 +79,26 @@ const MODEL_REGISTRY_FIXTURE = {
 };
 
 /** Run the local-LLM path, returning the prompt the model saw + the result. */
-async function runLocal(turns: BufferTurn[]): Promise<{ prompt: string; result: ExtractionResult }> {
+async function runLocal(turns: BufferTurn[]): Promise<{
+  prompt: string;
+  result: ExtractionResult;
+  options: LocalLlmChatCompletionOptions;
+}> {
   const engine = new ExtractionEngine(
     parseConfig({ localLlmEnabled: true, localLlmModel: "fixture-local", localLlmFallback: false }),
   );
   let prompt = "";
+  let options: LocalLlmChatCompletionOptions = {};
   const localLlm = {
-    async chatCompletion(messages: ChatMessage[], _options: { signal?: AbortSignal } = {}) {
+    async chatCompletion(messages: ChatMessage[], seen: LocalLlmChatCompletionOptions = {}) {
       prompt = messages[1]?.content ?? "";
+      options = seen;
       return { content: JSON.stringify(HIGH_IMPACT_EXTRACTION) };
     },
   };
   assert.equal(Reflect.set(engine, "localLlm", localLlm), true);
   assert.equal(Reflect.set(engine, "modelRegistry", MODEL_REGISTRY_FIXTURE), true);
-  return { result: await engine.extract(turns), prompt };
+  return { result: await engine.extract(turns), prompt, options };
 }
 
 /** Run the gateway-fallback path. */
@@ -169,6 +177,16 @@ for (const [name, run] of PATHS) {
   });
 }
 
+test("local extraction supplies the provider JSON schema as responseFormat with an object root", async () => {
+  const { options } = await runLocal([TYPED_TURN]);
+  const schema = extractionProviderJsonSchema("off");
+  assert.deepEqual(options.responseFormat, {
+    type: "json_schema",
+    json_schema: { name: "extraction_result", strict: false, schema },
+  });
+  assert.equal(schema.type, "object");
+});
+
 test("an ambient turn marked context-only does not trigger the ambient prompt", async () => {
   const { prompt } = await runGateway([
     { ...AMBIENT_TURN, extractionContextOnly: true },

package/src/extraction-span-wire.ts

@@ -58,3 +58,14 @@ export function extractionProviderJsonSchema(
     ? EXTRACTION_PROVIDER_JSON_SCHEMA_WITHOUT_SPAN
     : EXTRACTION_PROVIDER_JSON_SCHEMA_WITH_SPAN;
 }
+
+export function extractionProviderResponseFormat(spanMode: ExtractionSpanConfig["spanMode"] = "off") {
+  return {
+    type: "json_schema" as const,
+    json_schema: {
+      name: "extraction_result",
+      schema: extractionProviderJsonSchema(spanMode),
+      strict: false,
+    },
+  };
+}

package/src/extraction.ts

@@ -54,7 +54,7 @@ import {
 } from "./extraction-prompt.js";
 import { containsExtractionPlaceholder, extractionAttributes, extractionCueAnchors, extractionText, isPlainRecord } from "./extraction-normalization.js";
 import { applyExtractionSpanMaterialization, bindLocalExtractionPrompt, buildSpanMaterializeTurns, stripUntrustedFactSpans, truncateLocalExtractionConversation, type SpanMaterializeTurn } from "./extraction-span-materialize.js";
-import { extractionProviderJsonSchema } from "./extraction-span-wire.js";
+import { extractionProviderJsonSchema, extractionProviderResponseFormat } from "./extraction-span-wire.js";
 import { resolveLocalLlmCapabilities, resolveMemoryLifecycleCapabilities, resolvePipelineProcessingCapabilities, resolveRecallAuxiliaryCapabilities } from "./capabilities.js";
 type ExtractionQuestion = ExtractionResult["questions"][number];
 type ExtractedFactResult = ExtractionResult["facts"][number];
@@ -1506,6 +1506,7 @@ ${truncatedConversation}`;
         temperature: 0.1,
         maxTokens: contextSizes.maxOutputTokens,
         operation: "extraction",
+        responseFormat: extractionProviderResponseFormat(this.config.extraction?.spanMode ?? "off"),
         disableThinking: shouldEnableLocalExtractionThinking(this.config, conversation.length)
           ? false
           : undefined,
@@ -1513,7 +1514,6 @@ ${truncatedConversation}`;
         signal,
       },
     );
-
     if (!response?.content) {
       log.debug("extractWithLocalLlm: chatCompletion returned null or empty content");
       return null;

package/src/fallback-llm-codex-subscription.ts

@@ -194,18 +194,15 @@ export function withCodexRuntimeShutdown<T extends { signal?: AbortSignal }>(
 
 export function isUnsupportedJsonSchemaError(error: unknown): boolean {
   const message = error instanceof Error ? error.message : String(error);
-  // Require an HTTP status plus explicit schema/format context. A bare
-  // "unsupported" (e.g. "'temperature' is unsupported with this model") must
-  // NOT trigger the schema-stripping retry, or we pay a duplicate request
-  // for unrelated provider errors.
+  // An echoed request format is not a capability rejection.
   if (!/\b(?:400|404|422)\b/.test(message)) {
     return false;
   }
-  if (/(?:response[_ ]?format|json[_ ]?schema|structured[_ ]?output)/i.test(message)) {
-    return true;
-  }
-  // "unsupported" only counts when adjacent to schema/format terminology.
-  return /\bunsupported\b[\s\S]{0,40}\b(?:schema|format)\b/i.test(message);
+  return (
+    /(?:response[_ ]?format|json[_ ]?schema|structured[_ ]?output)\b[^;,\n]{0,60}\b(?:unsupported|not supported|not implemented|not available)\b/i.test(message) ||
+    /\b(?:unsupported|unknown|unrecognized)(?:[\s:"'=]|parameter|argument|request|supplied|field|type|value){1,40}\b(?:response[_ ]?format|json[_ ]?schema|structured[_ ]?output|schema|format)\b/i.test(message) ||
+    /\b(?:does not|doesn't|cannot|can't) support(?:[\s:"'=]|the|native|type){1,20}\b(?:response[_ ]?format|json[_ ]?schema|structured[_ ]?output|schema|format)\b/i.test(message)
+  );
 }
 
 export function extractResponsesOutputText(data: {

package/src/local-llm-helpers.ts

@@ -1,10 +1,11 @@
+import type { ResponseFormatJSONSchema } from "openai/resources/shared";
 import { log } from "./logger.js";
 import type { LocalLlmRequestPriority } from "./local-llm.js";
 
 export interface LocalLlmChatCompletionOptions {
   temperature?: number;
   maxTokens?: number;
-  responseFormat?: { type: string };
+  responseFormat?: { type: string } | ResponseFormatJSONSchema;
   timeoutMs?: number;
   operation?: string;
   forceDisableThinking?: boolean;

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

@@ -0,0 +1,278 @@
+import assert from "node:assert/strict";
+import http from "node:http";
+import type { AddressInfo } from "node:net";
+import test, { mock } from "node:test";
+
+import { LocalLlmClient } from "./local-llm.js";
+import { ChatTransport } from "./local-llm-transport.js";
+import { parseConfig } from "./config.js";
+import type { LocalLlmChatCompletionOptions } from "./local-llm-helpers.js";
+import type { PluginConfig } from "./types.js";
+
+function createConfig(overrides: Partial<PluginConfig> = {}): PluginConfig {
+  return parseConfig({
+    localLlmEnabled: true,
+    localLlmModel: "test-local-model",
+    localLlmUrl: "http://127.0.0.1:1234",
+    localLlmTimeoutMs: 5_000,
+    localLlmRetry5xxCount: 0,
+    localLlmRateLimitRetryCount: 0,
+    localLlmRetryBackoffMs: 1,
+    localLlmHeaders: { "X-Test": "yes" },
+    localLlmApiKey: undefined,
+    localLlmAuthHeader: false,
+    localLlm400TripThreshold: 50,
+    localLlm400CooldownMs: 60_000,
+    debug: false,
+    localLlmReasoningEffort: "none",
+    slowLogEnabled: false,
+    slowLogThresholdMs: 60_000,
+    ...overrides,
+  });
+}
+
+function primeClient(client: LocalLlmClient): void {
+  mock.method(client, "checkAvailability", async () => true);
+}
+
+interface RecordedRequest {
+  headers: http.IncomingHttpHeaders;
+  body: { model: string; response_format?: LocalLlmChatCompletionOptions["responseFormat"] };
+}
+
+async function startRecordingServer(
+  respond: (req: http.IncomingMessage, requestCount: number) => {
+    status: number;
+    body: unknown;
+  },
+): Promise<{
+  url: string;
+  requests: RecordedRequest[];
+  close: () => Promise<void>;
+}> {
+  const requests: RecordedRequest[] = [];
+  const server = http.createServer((req, res) => {
+    let raw = "";
+    req.setEncoding("utf8");
+    req.on("data", (chunk: string) => {
+      raw += chunk;
+    });
+    req.on("end", () => {
+      requests.push({ headers: req.headers, body: JSON.parse(raw) });
+      const { status, body } = respond(req, requests.length);
+      res.writeHead(status, { "content-type": "application/json" });
+      res.end(JSON.stringify(body));
+    });
+  });
+  await new Promise<void>((resolve) => server.listen(0, "127.0.0.1", resolve));
+  // SAFETY: listen(0, "127.0.0.1") above binds TCP, so its address is AddressInfo.
+  const { port } = server.address() as AddressInfo;
+  return {
+    url: `http://127.0.0.1:${port}/v1`,
+    requests,
+    close: async () => {
+      await new Promise<void>((resolve) => server.close(() => resolve()));
+    },
+  };
+}
+
+const okCompletion = {
+  choices: [{ message: { content: "done" } }],
+  usage: { prompt_tokens: 1, completion_tokens: 1, total_tokens: 2 },
+};
+
+const responseFormat = {
+  type: "json_schema",
+  json_schema: {
+    name: "result",
+    schema: { type: "object", properties: { ok: { type: "boolean" } } },
+  },
+};
+
+test("forwards json_schema response_format when the backend accepts it", async () => {
+  const server = await startRecordingServer(() => ({ status: 200, body: okCompletion }));
+  try {
+    const client = new LocalLlmClient(createConfig({ localLlmUrl: server.url }));
+    primeClient(client);
+    const result = await client.chatCompletion([{ role: "user", content: "hello" }], {
+      responseFormat,
+    });
+    assert.equal(result?.content, "done");
+    assert.equal(server.requests.length, 1);
+    assert.deepEqual(server.requests[0].body.response_format, responseFormat);
+  } finally {
+    await server.close();
+  }
+});
+
+test("400 rejecting json_schema triggers exactly one retry without the format", async (t) => {
+  const server = await startRecordingServer((_req, count) =>
+    count === 1
+      ? {
+          status: 400,
+          body: {
+            error: { message: "response_format type json_schema is not supported" },
+          },
+        }
+      : { status: 200, body: okCompletion },
+  );
+  try {
+    const client = new LocalLlmClient(createConfig({ localLlmUrl: server.url }));
+    primeClient(client);
+    const post = ChatTransport.prototype.post;
+    const attempts: Array<Parameters<ChatTransport["post"]>[0]> = [];
+    t.mock.method(ChatTransport.prototype, "post", async function (this: ChatTransport, request: Parameters<ChatTransport["post"]>[0]) {
+      attempts.push(request);
+      return post.call(this, request);
+    });
+    const result = await client.chatCompletion([{ role: "user", content: "hello" }], {
+      responseFormat,
+    });
+    assert.equal(result?.content, "done");
+    assert.equal(server.requests.length, 2, "exactly one strip-and-retry");
+    assert.deepEqual(server.requests[0].body.response_format, responseFormat);
+    assert.equal(server.requests[1].body.response_format, undefined);
+    // headers/model/deadline preserved on the retry
+    assert.equal(server.requests[1].headers["x-test"], "yes");
+    assert.equal(server.requests[1].body.model, "test-local-model");
+    assert.equal(attempts[0].signal, attempts[1].signal, "retry shares the attempt deadline and caller abort");
+    assert.equal(attempts[0].budgetMs, attempts[1].budgetMs);
+    assert.deepEqual(attempts[0].headers, attempts[1].headers);
+  } finally {
+    await server.close();
+  }
+});
+
+test("timeout before strip-retry headers uses the configured transport retry", async (t) => {
+  const bodies: RecordedRequest["body"][] = [];
+  t.mock.method(ChatTransport.prototype, "post", async (request: Parameters<ChatTransport["post"]>[0]) => {
+    bodies.push(JSON.parse(request.body));
+    if (bodies.length === 1) return new Response("json_schema is not supported", { status: 400 });
+    if (bodies.length === 2) throw new DOMException("Timed out before headers", "AbortError");
+    return new Response(JSON.stringify(okCompletion), { status: 200 });
+  });
+  const client = new LocalLlmClient(createConfig({ localLlmRetry5xxCount: 1, localLlm400TripThreshold: 1 }));
+  primeClient(client);
+  const result = await client.chatCompletion([{ role: "user", content: "hello" }], { responseFormat });
+  assert.equal(result?.content, "done");
+  assert.equal(bodies.length, 3);
+  assert.deepEqual(bodies[0].response_format, responseFormat);
+  assert.equal(bodies[1].response_format, undefined);
+  assert.equal(bodies[2].response_format, undefined);
+});
+
+test("a diagnostic echo of the format is not a schema capability rejection", async () => {
+  for (const message of [
+    "Context length exceeded; request included response_format json_schema",
+    "Unsupported parameter temperature; request included response_format json_schema",
+  ]) {
+    const server = await startRecordingServer(() => ({ status: 400, body: { error: { message } } }));
+    try {
+      const client = new LocalLlmClient(createConfig({ localLlmUrl: server.url }));
+      primeClient(client);
+      assert.equal(await client.chatCompletion([{ role: "user", content: "hello" }], { responseFormat }), null);
+      assert.equal(server.requests.length, 1, "unrelated provider errors must not strip the format");
+    } finally {
+      await server.close();
+    }
+  }
+});
+
+test("an explicit unknown response_format field retries without the format", async () => {
+  const server = await startRecordingServer((_req, count) => count === 1
+    ? { status: 400, body: { error: { message: "Unknown field response_format" } } }
+    : { status: 200, body: okCompletion });
+  try {
+    const client = new LocalLlmClient(createConfig({ localLlmUrl: server.url }));
+    primeClient(client);
+    assert.equal((await client.chatCompletion([{ role: "user", content: "hello" }], { responseFormat }))?.content, "done");
+    assert.equal(server.requests.length, 2);
+    assert.deepEqual(server.requests[0].body.response_format, responseFormat);
+    assert.equal(server.requests[1].body.response_format, undefined);
+  } finally {
+    await server.close();
+  }
+});
+
+test("format removal persists for later 5xx attempts", async () => {
+  const server = await startRecordingServer((_req, count) =>
+    count === 1
+      ? { status: 400, body: { error: { message: "json_schema unsupported by backend" } } }
+      : count === 2
+        ? { status: 500, body: { error: { message: "boom" } } }
+        : { status: 200, body: okCompletion },
+  );
+  try {
+    const client = new LocalLlmClient(
+      createConfig({ localLlmUrl: server.url, localLlmRetry5xxCount: 2 }),
+    );
+    primeClient(client);
+    const result = await client.chatCompletion([{ role: "user", content: "hello" }], {
+      responseFormat,
+    });
+    assert.equal(result?.content, "done");
+    assert.equal(server.requests.length, 3);
+    assert.equal(server.requests[2].body.response_format, undefined);
+  } finally {
+    await server.close();
+  }
+});
+
+test("unrelated 400 and 429 are not retried with a stripped format", async () => {
+  for (const status of [400, 429]) {
+    const server = await startRecordingServer(() => ({
+      status,
+      body: { error: { message: "some other problem" } },
+    }));
+    try {
+      const client = new LocalLlmClient(createConfig({ localLlmUrl: server.url }));
+      primeClient(client);
+      const result = await client.chatCompletion([{ role: "user", content: "hello" }], {
+        responseFormat,
+      });
+      assert.equal(result, null);
+      assert.equal(server.requests.length, 1);
+      assert.ok(server.requests[0].body.response_format, "format still present");
+    } finally {
+      await server.close();
+    }
+  }
+});
+
+test("caller abort still fails closed during the strip retry", async () => {
+  const controller = new AbortController();
+  const server = await startRecordingServer((_req, count) => {
+    if (count === 2) controller.abort();
+    return count === 1
+      ? { status: 400, body: { error: { message: "response_format json_schema is not supported" } } }
+      : { status: 200, body: okCompletion };
+  });
+  try {
+    const client = new LocalLlmClient(createConfig({ localLlmUrl: server.url }));
+    primeClient(client);
+    const pending = client.chatCompletion([{ role: "user", content: "hello" }], {
+      responseFormat,
+      signal: controller.signal,
+    });
+    const result = await pending;
+    assert.equal(result, null);
+    assert.equal(server.requests.length, 2, "caller abort happens during the strip retry, not before the first request");
+  } finally {
+    await server.close();
+  }
+});
+
+test("request without response_format is unchanged", async () => {
+  const server = await startRecordingServer(() => ({ status: 200, body: okCompletion }));
+  try {
+    const client = new LocalLlmClient(createConfig({ localLlmUrl: server.url }));
+    primeClient(client);
+    const result = await client.chatCompletion([{ role: "user", content: "hello" }]);
+    assert.equal(result?.content, "done");
+    assert.equal(server.requests.length, 1);
+    assert.equal(server.requests[0].body.response_format, undefined);
+  } finally {
+    await server.close();
+  }
+});
+

package/src/local-llm-rate-limit.test.ts

@@ -339,7 +339,10 @@ test("process-wide concurrency cap bounds in-flight requests across clients", as
       const config = createConfig({ localLlmUrl: "http://127.0.0.1:1007", localLlmMaxConcurrency: 2 });
       const clients = [new LocalLlmClient(config), new LocalLlmClient(config), new LocalLlmClient(config)];
       const results = await Promise.all(
-        Array.from({ length: 7 }, (_, i) => clients[i % 3].chatCompletion([{ role: "user", content: `q${i}` }]))
+        Array.from({ length: 7 }, (_, i) => clients[i % 3].chatCompletion(
+          [{ role: "user", content: `q${i}` }],
+          { priority: i % 2 === 0 ? "recall-critical" : "background" }
+        ))
       );
       assert.equal(results.filter((r) => r?.content === "ok").length, 7);
       assert.equal(peak, 2);
@@ -404,3 +407,58 @@ test("waiting for a concurrency slot is bounded by the wait budget", async () =>
     }
   );
 });
+
+test("limiter reserves one finite permit for recall-critical work", async () => {
+  const limiter = new LocalLlmConcurrencyLimiter(2);
+  const background = await limiter.acquire();
+  const secondBackground = await limiter.acquire({ timeoutMs: 0 });
+  try {
+    assert.ok(background);
+    assert.equal(secondBackground, null, "background must not consume the recall permit");
+    const foreground = await limiter.acquire({ highPriority: true, timeoutMs: 0 });
+    assert.ok(foreground, "recall must start without waiting for background completion");
+    foreground();
+    foreground();
+    assert.equal(limiter.inFlight, 1, "release remains idempotent");
+  } finally {
+    secondBackground?.();
+    background?.();
+  }
+});
+
+test("reserved background queue survives aborts and responds to resizing", async () => {
+  const limiter = new LocalLlmConcurrencyLimiter(2);
+  const background = await limiter.acquire();
+  assert.ok(background);
+  const controller = new AbortController();
+  const aborted = limiter.acquire({ signal: controller.signal });
+  controller.abort();
+  const abortedRelease = await aborted;
+  abortedRelease?.();
+  assert.equal(abortedRelease, null);
+  const queued = limiter.acquire();
+  const foreground = await limiter.acquire({ highPriority: true, timeoutMs: 0 });
+  assert.ok(foreground);
+  assert.equal(limiter.queued, 1);
+  limiter.setMax(3);
+  const nextBackground = await queued;
+  assert.ok(nextBackground);
+  assert.equal(limiter.inFlight, 3);
+  nextBackground();
+  background();
+  foreground();
+  assert.equal(limiter.inFlight, 0);
+});
+
+test("one-permit and unlimited limits still admit background work", async () => {
+  for (const max of [1, 0]) {
+    const limiter = new LocalLlmConcurrencyLimiter(max);
+    const first = await limiter.acquire({ timeoutMs: 0 });
+    assert.ok(first);
+    const second = await limiter.acquire({ timeoutMs: 0 });
+    assert.equal(second === null, max === 1);
+    second?.();
+    first();
+    assert.equal(limiter.inFlight, 0);
+  }
+});

package/src/local-llm-rate-limit.ts

@@ -151,9 +151,10 @@ export function computeRateLimitDelayMs(
 
 type Waiter = { highPriority: boolean; grant: () => void };
 
-/** FIFO counting semaphore with a high-priority lane (recall-critical first). */
+/** FIFO semaphore; finite caps above one reserve a permit for recall-critical work. */
 export class LocalLlmConcurrencyLimiter {
   private active = 0;
+  private activeBackground = 0;
   private max: number;
   private readonly waiters: Waiter[] = [];
 
@@ -182,20 +183,25 @@ export class LocalLlmConcurrencyLimiter {
     options: { highPriority?: boolean; signal?: AbortSignal; timeoutMs?: number } = {}
   ): Promise<(() => void) | null> {
     const { signal, timeoutMs } = options;
+    const highPriority = options.highPriority === true;
     if (signal?.aborted) return Promise.resolve(null);
-    if (this.max <= 0 || (this.active < this.max && this.waiters.length === 0)) {
+    if (
+      this.canAcquire(highPriority) &&
+      (this.waiters.length === 0 || (highPriority && !this.waiters[0].highPriority))
+    ) {
       this.active += 1;
-      return Promise.resolve(this.releaser());
+      if (!highPriority) this.activeBackground += 1;
+      return Promise.resolve(this.releaser(highPriority));
     }
     if (timeoutMs !== undefined && timeoutMs <= 0) return Promise.resolve(null);
     return new Promise((resolve) => {
       let timer: NodeJS.Timeout | undefined;
       const waiter: Waiter = {
-        highPriority: options.highPriority === true,
+        highPriority,
         grant: () => {
           signal?.removeEventListener("abort", onAbort);
           if (timer) clearTimeout(timer);
-          resolve(this.releaser());
+          resolve(this.releaser(highPriority));
         },
       };
       const onAbort = (): void => {
@@ -217,21 +223,30 @@ export class LocalLlmConcurrencyLimiter {
     });
   }
 
-  private releaser(): () => void {
+  private canAcquire(highPriority: boolean): boolean {
+    return this.max <= 0 || (
+      this.active < this.max &&
+      (highPriority || this.max === 1 || this.activeBackground < this.max - 1)
+    );
+  }
+
+  private releaser(highPriority: boolean): () => void {
     let released = false;
     return () => {
       if (released) return;
       released = true;
       this.active -= 1;
+      if (!highPriority) this.activeBackground -= 1;
       this.pump();
     };
   }
 
   private pump(): void {
-    while (this.waiters.length > 0 && (this.max <= 0 || this.active < this.max)) {
+    while (this.waiters.length > 0 && this.canAcquire(this.waiters[0].highPriority)) {
       const next = this.waiters.shift();
       if (!next) break;
       this.active += 1;
+      if (!next.highPriority) this.activeBackground += 1;
       next.grant();
     }
   }