@remnic/core 9.69.85 → 9.69.87

package/src/access-service-observe-lcm-parity.test.ts

@@ -433,14 +433,13 @@ test("#2128: successful LCM flush does not bind per-call project context", async
 test("#2128: extraction force-flush uses observe's scoped target even when LCM is disabled", async () => {
   const probe = makeParityProbe(withSelfPolicyPrefix("pi-geek"));
   const service = new EngramAccessService(probe.orch);
-  const deadlineMs = Date.now() + 10_000;
   const abortController = new AbortController();
   probe.lcmEngine.enabled = false;
 
   const response = await service.extractionForceFlush({
     sessionKey: "pi-geek:force-flush",
     projectTag: "Acme/Webshop",
-    deadlineMs,
+    deadlineMs: 10_000,
     abortSignal: abortController.signal,
     authenticatedPrincipal: "pi-geek",
   });
@@ -460,7 +459,11 @@ test("#2128: extraction force-flush uses observe's scoped target even when LCM i
     false,
     "force-flush must let the orchestrator discover all session buffer keys",
   );
-  assert.equal(call.options.extractionDeadlineMs, deadlineMs);
+  // #3140: the duration budget arrives at the orchestrator as an absolute deadline.
+  assert.ok(
+    (call.options.extractionDeadlineMs ?? 0) >= Date.now() + 9_000,
+    "the orchestrator deadline is the duration converted at force-flush entry",
+  );
   assert.equal(call.options.failOnExtractionFailure, true);
   assert.equal(call.options.abortSignal, abortController.signal);
   assert.equal(call.options.writeNamespaceOverride, expectedNamespace);
@@ -573,7 +576,7 @@ test("#2128: pending extraction barriers stay isolated by authenticated principa
     sessionKey,
     namespace: "team",
     authenticatedPrincipal: "alice",
-    deadlineMs: Date.now() + 500,
+    deadlineMs: 500,
   });
   await new Promise<void>((resolve) => setImmediate(resolve));
   pending.get("alice")?.();
@@ -583,7 +586,7 @@ test("#2128: pending extraction barriers stay isolated by authenticated principa
     sessionKey,
     namespace: "team",
     authenticatedPrincipal: "bob",
-    deadlineMs: Date.now() + 500,
+    deadlineMs: 500,
   });
   pending.get("bob")?.();
   assert.equal((await bobFlush).flushed, true);
@@ -600,7 +603,7 @@ test("#2128: chained observes remain behind one force-flush barrier", async () =
   const sessionKey = "chained-observes";
 
   await service.observe(observeRequest({ sessionKey, skipExtraction: false }));
-  const flushPromise = service.extractionForceFlush({ sessionKey, deadlineMs: Date.now() + 500 });
+  const flushPromise = service.extractionForceFlush({ sessionKey, deadlineMs: 500 });
   await new Promise<void>((resolve) => setImmediate(resolve));
   await service.observe(observeRequest({ sessionKey, skipExtraction: false }));
   assert.equal(resolvers.length, 2);
@@ -669,7 +672,7 @@ test("#2128: force-flush deadline cancels the pending observe extraction", async
     await assert.rejects(
       service.extractionForceFlush({
         sessionKey,
-        deadlineMs: Date.now() + 25,
+        deadlineMs: 25,
       }),
       (error: unknown) =>
         error instanceof EngramAccessInputError &&
@@ -893,7 +896,7 @@ test("#2128: post-flush retained cleanup is best effort and receives lifecycle g
     },
   };
   const service = new EngramAccessService(probe.orch);
-  const deadlineMs = Date.now() + 10_000;
+  const deadlineMs = 10_000;
 
   const response = await service.extractionForceFlush({
     sessionKey: "pi-geek:cleanup-best-effort",
@@ -903,11 +906,15 @@ test("#2128: post-flush retained cleanup is best effort and receives lifecycle g
   });
 
   assert.equal(response.flushed, true);
-  assert.deepEqual(cleanupCalls, [{
-    sessionKey: "pi-geek:cleanup-best-effort",
-    ownerPrincipal: "pi-geek",
-    options: { abortSignal: abortController.signal, deadlineMs },
-  }]);
+  assert.equal(cleanupCalls.length, 1);
+  // #3140: cleanup receives the duration converted to an absolute deadline.
+  assert.equal(cleanupCalls[0]?.sessionKey, "pi-geek:cleanup-best-effort");
+  assert.equal(cleanupCalls[0]?.ownerPrincipal, "pi-geek");
+  assert.equal(cleanupCalls[0]?.options?.abortSignal, abortController.signal);
+  assert.ok(
+    (cleanupCalls[0]?.options?.deadlineMs ?? 0) >= Date.now() + 9_000,
+    "cleanup deadline is the duration converted at force-flush entry",
+  );
 });
 
 test("#2128: post-flush retained cleanup stops on abort or deadline", async (t) => {
@@ -982,7 +989,11 @@ test("#2128: post-flush retained cleanup stops on abort or deadline", async (t)
     /replay extraction deadline exceeded \(retained_turn_cleanup\)/,
   );
 });
-test("#2206: an expired force-flush deadline stops before scope resolution", async () => {
+test("#3140: a duration deadline reaches scope resolution and aborts it when it elapses", async () => {
+  // Regression for issue #3140: `deadlineMs` is a BUDGET from now. The old
+  // absolute-epoch reading compared a relative value (e.g. 30000) against
+  // Date.now(), so a live-session force flush was rejected INSTANTLY with
+  // `replay extraction deadline exceeded (scope_resolution)` before any work.
   const probe = makeParityProbe({ namespacesEnabled: false } as Partial<PluginConfig>);
   const service = new EngramAccessService(probe.orch);
   let scopeResolutionStarted = false;
@@ -991,17 +1002,23 @@ test("#2206: an expired force-flush deadline stops before scope resolution", asy
   };
   internals.resolveMemoryScopePlan = async () => {
     scopeResolutionStarted = true;
-    throw new Error("scope resolution must not start");
+    return new Promise<never>(() => {});
   };
 
+  const started = Date.now();
   await assert.rejects(
     service.extractionForceFlush({
-      sessionKey: "expired-scope-resolution",
-      deadlineMs: 1,
+      sessionKey: "duration-deadline-scope-resolution",
+      deadlineMs: 30,
     }),
     /scope_resolution/,
   );
-  assert.equal(scopeResolutionStarted, false);
+  assert.equal(scopeResolutionStarted, true, "the budget lets scope resolution start");
+  assert.ok(
+    Date.now() - started >= 25,
+    "the flush waits out the budget instead of failing instantly",
+  );
+  assert.equal(probe.extractionForceFlushCalls.length, 0);
 });
 
 test("#2206: abort during scope resolution cancels pre-resolution observe preparations", async () => {
@@ -1089,8 +1106,10 @@ test("#2206: scope-resolution deadline cancels preparations by raw projectTag an
         await observeScopeGate;
         return resolveMemoryScopePlan(request);
       }
+      // Blocked scope work, as a live session's pending observe preparations
+      // would hold it (#3140): the duration budget elapses while it hangs.
       flushScopeStarted = true;
-      throw new Error("scope resolution must not start");
+      return new Promise<never>(() => {});
     };
 
     const observe = service.observe(observeRequest({
@@ -1104,12 +1123,12 @@ test("#2206: scope-resolution deadline cancels preparations by raw projectTag an
       service.extractionForceFlush({
         sessionKey: "pi-geek:raw-hint-deadline",
         authenticatedPrincipal: "pi-geek",
-        deadlineMs: Date.now() - 1,
+        deadlineMs: 1,
         ...rawHintCase,
       }),
       /scope_resolution/,
     );
-    assert.equal(flushScopeStarted, false);
+    assert.equal(flushScopeStarted, true);
     releaseObserveScope();
     const response = await observe;
     assert.equal(response.extractionQueued, false);
@@ -1132,12 +1151,19 @@ test("#2128: aborted or expired extraction force-flush never touches a buffer",
       }),
     /extraction force-flush aborted/,
   );
+  // #3140: the expired-at-entry scenario is gone (durations always start in
+  // the future); a TINY budget elapsing while scope work is blocked still
+  // rejects with the same error and never reaches the buffer.
+  const internals = service as unknown as {
+    resolveMemoryScopePlan: (request: unknown) => Promise<never>;
+  };
+  internals.resolveMemoryScopePlan = async () => new Promise<never>(() => {});
   await assert.rejects(
     () =>
       service.extractionForceFlush({
         sessionKey: "pi-geek:expired-flush",
         authenticatedPrincipal: "pi-geek",
-        deadlineMs: Date.now() - 1,
+        deadlineMs: 1,
       }),
     (error: unknown) =>
       error instanceof EngramAccessInputError &&
@@ -1167,13 +1193,19 @@ test("#2128: self-deps wires force-flush cancellation into the observe tracker",
     cancellations.push({ sessionKey, principal, namespace });
   };
 
+  // #3140: a tiny budget elapsing while scope work is blocked still cancels
+  // the pending observe preparations via the same deadline hook.
+  const internals = service as unknown as {
+    resolveMemoryScopePlan: (request: unknown) => Promise<never>;
+  };
+  internals.resolveMemoryScopePlan = async () => new Promise<never>(() => {});
   await assert.rejects(
     () =>
       service.extractionForceFlush({
         sessionKey: "pi-geek:cancel-hook",
         namespace: "pi-geek",
         authenticatedPrincipal: "pi-geek",
-        deadlineMs: Date.now() - 1,
+        deadlineMs: 1,
       }),
     (error: unknown) =>
       error instanceof EngramAccessInputError &&
@@ -1198,7 +1230,7 @@ test("#2128: late extraction deadline is surfaced as an access input error", asy
       service.extractionForceFlush({
         sessionKey: "pi-geek:late-deadline",
         authenticatedPrincipal: "pi-geek",
-        deadlineMs: Date.now() + 10_000,
+        deadlineMs: 10_000,
       }),
     (error: unknown) =>
       error instanceof EngramAccessInputError &&

package/src/correction/correction-access-wiring.ts

@@ -30,6 +30,7 @@ import { writeFileAtomically } from "../maintenance/atomic-file.js";
 import type { Orchestrator } from "../orchestrator.js";
 import type { MemoryFile, MemoryStatus, PluginConfig } from "../types.js";
 import { stripAttributesSuffix } from "../structured-attributes.js";
+import { extractJsonCandidates } from "../json-extract.js";
 import { supersessionKeysForFact } from "../temporal-supersession.js";
 import { computeContentHash } from "../content-hash.js";
 import { sanitizeMemoryContent } from "../sanitize.js";
@@ -1010,16 +1011,43 @@ function parseClassifyResponse(
   raw: string,
   candidates: PlannerCandidate[],
 ): LlmClassificationResult {
-  let parsed: unknown;
-  try {
-    parsed = JSON.parse(raw);
-  } catch {
-    return fallbackClassification(candidates, "LLM returned non-JSON response");
+  // Correction plans can mutate memory: accept one schema-valid, verbatim
+  // response, never an arbitrary example or a fence-rewritten patch payload.
+  // The response envelope gates candidacy; actions need only ≥1 valid entry
+  // (an empty list is fine, an all-malformed list is unusable). Malformed
+  // siblings are dropped after selection, so one bad action cannot discard
+  // the whole plan; distinct eligible responses stay ambiguous (fail closed).
+  const responses = new Map<string, Record<string, unknown>>();
+  let sawJson = false;
+  for (const candidate of new Set([raw.trim(), ...extractJsonCandidates(raw)])) {
+    if (!raw.includes(candidate)) continue;
+    try {
+      const parsed: unknown = JSON.parse(candidate);
+      sawJson = true;
+      if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) continue;
+      const value = parsed as Record<string, unknown>;
+      if (!isClassification(value.classification) ||
+          typeof value.confidence !== "number" || !Number.isFinite(value.confidence) ||
+          value.confidence < 0 || value.confidence > 1 || !Array.isArray(value.actions)) continue;
+      const hasUsable = value.actions.some((action) => {
+        try {
+          validateCorrectionAction(action);
+          return true;
+        } catch {
+          return false;
+        }
+      });
+      if (hasUsable || value.actions.length === 0) responses.set(JSON.stringify(value), value);
+    } catch {
+      // Keep scanning after malformed JSON, not after mere syntax success.
+    }
   }
-  if (!parsed || typeof parsed !== "object") {
-    return fallbackClassification(candidates, "LLM returned non-object response");
+  if (responses.size !== 1) {
+    return fallbackClassification(candidates, responses.size > 1
+      ? "LLM returned ambiguous correction responses"
+      : sawJson ? "LLM returned invalid correction response" : "LLM returned non-JSON response");
   }
-  const obj = parsed as Record<string, unknown>;
+  const obj = responses.values().next().value as Record<string, unknown>;
   const classification = isClassification(obj.classification) ? obj.classification : "outdated";
   const confidence = typeof obj.confidence === "number" ? Math.min(1, Math.max(0, obj.confidence)) : 0.5;
   const rawActions = Array.isArray(obj.actions) ? obj.actions : [];

package/src/correction/correction-classify-parse.test.ts

@@ -0,0 +1,178 @@
+/**
+ * parseClassifyResponse regression tests (issue #3134).
+ *
+ * Proves the correction planner's single LLM-response parse chokepoint:
+ *  - fenced JSON responses (```json … ```) parse into real actions instead of
+ *    degrading to the deterministic fallback (#3134, same class as #1514);
+ *  - genuinely non-JSON responses still return the byte-identical
+ *    deterministic fallback (rule 13);
+ *  - bare JSON keeps parsing through the same candidate chain.
+ */
+import assert from "node:assert/strict";
+import { test } from "node:test";
+
+import { parseClassifyResponse } from "./correction-access-wiring.js";
+import type { PlannerCandidate } from "./correction-planner.js";
+
+const CANDIDATES: PlannerCandidate[] = [
+  { memoryId: "m1", path: "facts/m1.md", content: "m1 content", excerpt: "m1 excerpt", score: 1 },
+];
+
+const CLASSIFY_JSON = JSON.stringify({
+  classification: "wrong",
+  confidence: 0.9,
+  actions: [{ kind: "edit", memoryId: "m1", patch: "m1 corrected content" }],
+  relevance: [{ memoryId: "m1", why: "names the corrected fact" }],
+});
+
+test("#3134 fenced json classify response parses into actions instead of fallback", () => {
+  const result = parseClassifyResponse(["```json", CLASSIFY_JSON, "```"].join("\n"), CANDIDATES);
+  assert.equal(result.fallback, undefined, "a fenced response must not degrade to the fallback");
+  assert.equal(result.classification, "wrong");
+  assert.equal(result.confidence, 0.9);
+  assert.deepEqual(result.actions, [{ kind: "edit", memoryId: "m1", patch: "m1 corrected content" }]);
+  assert.deepEqual(result.relevance, [{ memoryId: "m1", why: "names the corrected fact" }]);
+  assert.deepEqual(result.warnings, []);
+});
+
+test("#3134 fenced response without a language tag parses", () => {
+  const result = parseClassifyResponse(["```", CLASSIFY_JSON, "```"].join("\n"), CANDIDATES);
+  assert.equal(result.fallback, undefined);
+  assert.equal(result.actions.length, 1);
+});
+
+test("#3134 prose-wrapped fenced response with trailing prose parses", () => {
+  const result = parseClassifyResponse(
+    ["Here is the classification:", "```json", CLASSIFY_JSON, "```", "Done."].join("\n"),
+    CANDIDATES
+  );
+  assert.equal(result.fallback, undefined);
+  assert.equal(result.actions.length, 1);
+});
+
+test("#3134 bare JSON with an inner markdown code block keeps its patch content verbatim", () => {
+  const patch = "```\nconst fixed = true;\n```";
+  const result = parseClassifyResponse(
+    JSON.stringify({
+      classification: "wrong",
+      confidence: 0.8,
+      actions: [{ kind: "edit", memoryId: "m1", patch }],
+    }),
+    CANDIDATES
+  );
+  assert.equal(result.fallback, undefined, "valid bare JSON must not degrade to the fallback");
+  assert.deepEqual(result.actions, [{ kind: "edit", memoryId: "m1", patch }], "inner code-block delimiters must survive verbatim");
+});
+
+test("#3134 outer-fenced JSON with an inner code block parses with the patch verbatim", () => {
+  const patch = "```py\nprint(\"fixed\")\n```";
+  const inner = JSON.stringify({
+    classification: "wrong",
+    confidence: 0.8,
+    actions: [{ kind: "edit", memoryId: "m1", patch }],
+  });
+  const result = parseClassifyResponse(["```json", inner, "```"].join("\n"), CANDIDATES);
+  assert.equal(result.fallback, undefined, "an outer fence plus an inner code block must not degrade to the fallback");
+  assert.deepEqual(result.actions, [{ kind: "edit", memoryId: "m1", patch }], "inner code-block delimiters must survive verbatim");
+});
+
+test("#3134 genuinely non-JSON response still returns the deterministic fallback", () => {
+  const result = parseClassifyResponse("I'm sorry, I cannot classify that request.", CANDIDATES);
+  assert.deepEqual(result, {
+    classification: "outdated",
+    confidence: 0,
+    actions: [],
+    relevance: [{ memoryId: "m1", why: "located for review" }],
+    warnings: ["LLM returned non-JSON response"],
+    fallback: true,
+  });
+});
+
+test("#3134 empty response still returns the deterministic fallback", () => {
+  const result = parseClassifyResponse("", CANDIDATES);
+  assert.equal(result.fallback, true);
+  assert.deepEqual(result.warnings, ["LLM returned non-JSON response"]);
+});
+
+test("#3134 bare JSON keeps parsing through the same candidate chain", () => {
+  const result = parseClassifyResponse(CLASSIFY_JSON, CANDIDATES);
+  assert.equal(result.fallback, undefined);
+  assert.equal(result.classification, "wrong");
+  assert.equal(result.confidence, 0.9);
+  assert.equal(result.actions.length, 1);
+});
+
+test("#3134 bare JSON object with no actions still parses without fallback", () => {
+  const result = parseClassifyResponse(
+    JSON.stringify({ classification: "incomplete", confidence: 0.4, actions: [] }),
+    CANDIDATES
+  );
+  assert.equal(result.fallback, undefined);
+  assert.equal(result.classification, "incomplete");
+  assert.equal(result.actions.length, 0);
+});
+
+test("#3145 skips unrelated JSON objects before the correction response", () => {
+  const result = parseClassifyResponse("Example: {}\nAnswer: " + CLASSIFY_JSON, CANDIDATES);
+  assert.equal(result.fallback, undefined);
+  assert.equal(result.classification, "wrong");
+  assert.equal(result.actions.length, 1);
+});
+
+test("#3145 rejects ambiguous valid correction drafts instead of choosing an example", () => {
+  const other = JSON.stringify({ classification: "outdated", confidence: 0.99,
+    actions: [{ kind: "edit", memoryId: "m1", patch: "wrong example" }] });
+  const result = parseClassifyResponse(other + "\nActual answer: " + CLASSIFY_JSON, CANDIDATES);
+  assert.equal(result.fallback, true);
+  assert.equal(result.confidence, 0);
+  assert.deepEqual(result.actions, []);
+});
+
+test("#3145 skips malformed correction actions before a valid response", () => {
+  const malformed = JSON.stringify({ classification: "wrong", confidence: 0.9,
+    actions: [{ kind: "invented-action" }] });
+  const result = parseClassifyResponse(malformed + "\n" + CLASSIFY_JSON, CANDIDATES);
+  assert.equal(result.fallback, undefined);
+  assert.deepEqual(result.actions, [{ kind: "edit", memoryId: "m1", patch: "m1 corrected content" }]);
+});
+
+test("#3145 keeps the usable action when a sibling action is malformed", () => {
+  const mixed = JSON.stringify({
+    classification: "outdated",
+    confidence: 0.8,
+    actions: [
+      { kind: "edit", memoryId: "m1", patch: "m1 corrected content" },
+      { kind: "invented-action" },
+    ],
+  });
+  const result = parseClassifyResponse(mixed, CANDIDATES);
+  assert.equal(result.fallback, undefined, "one malformed sibling must not discard the whole plan");
+  assert.deepEqual(result.actions, [{ kind: "edit", memoryId: "m1", patch: "m1 corrected content" }]);
+  assert.equal(
+    result.warnings.filter((w) => w.startsWith("dropped malformed action")).length,
+    1,
+    "exactly the malformed sibling is dropped with a warning",
+  );
+});
+
+test("#3145 a partially valid draft is ambiguous against a distinct valid draft", () => {
+  const partialDraft = JSON.stringify({
+    classification: "outdated",
+    confidence: 0.8,
+    actions: [
+      { kind: "edit", memoryId: "m1", patch: "partial example" },
+      { kind: "invented-action" },
+    ],
+  });
+  const result = parseClassifyResponse(partialDraft + "\n" + CLASSIFY_JSON, CANDIDATES);
+  assert.equal(result.fallback, true);
+  assert.equal(result.confidence, 0);
+  assert.deepEqual(result.actions, []);
+});
+
+test("#3145 an unrelated standalone object never becomes a plausible correction", () => {
+  const result = parseClassifyResponse("{}", CANDIDATES);
+  assert.equal(result.fallback, true);
+  assert.equal(result.confidence, 0);
+  assert.deepEqual(result.actions, []);
+});

package/src/extraction-liveness.ts

@@ -19,6 +19,7 @@
  * the verdict never diverges across code paths.
  */
 import { coerceBool, coerceNumber } from "./connectors/coerce.js";
+import { getExtractionLlmHealth } from "./extraction-llm-health.js";
 import { log } from "./logger.js";
 import type { OperatorDoctorCheck } from "./operator-doctor-types.js";
 import type { PluginConfig } from "./types.js";
@@ -121,6 +122,15 @@ export interface ExtractionLivenessStatus {
   degradedReason: string | null;
   watermarkPending?: boolean;
   watermarkScope: "aggregate";
+  /**
+   * Extraction-LLM availability (issue #3140): outcome of the last extraction
+   * attempt. `lastFailureReason` is non-null exactly while `llmReachable` is
+   * false. Populated by the daemon-wide status readers (`/health`, doctor,
+   * stats), not by the pure evaluators below.
+   */
+  llmReachable?: boolean;
+  lastFailureReason?: string | null;
+  lastFailureAt?: string | null;
 }
 
 interface ExtractionLivenessOrchestratorLike {
@@ -380,7 +390,9 @@ export async function computeExtractionLivenessStatus(
     nowMs,
   });
   throttle?.maybeWarn(status, config.staleWindowMs, nowMs);
-  return status;
+  // Extraction-LLM availability (#3140): a silent no_models / LLM-unreachable
+  // outage must be visible on /health (and doctor/stats) without debug logs.
+  return { ...status, ...getExtractionLlmHealth() };
 }
 
 /**

package/src/extraction-llm-health.test.ts

@@ -0,0 +1,103 @@
+/**
+ * Extraction-LLM health surfacing (issue #3140).
+ *
+ * Covers the three #3140 surfaces:
+ *   1. the singleton tracker that `/health.extraction` reads for LLM
+ *      availability + last failure reason,
+ *   2. the ERROR-level, per-reason-deduplicated failure event emitted by the
+ *      extraction run instead of debug-only lines,
+ *   3. the runExtraction integration recording failures/successes.
+ */
+
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import {
+  emitExtractionLlmFailureError,
+  getExtractionLlmHealth,
+  recordExtractionLlmFailure,
+  recordExtractionLlmSuccess,
+  resetExtractionLlmHealthForTests,
+} from "./extraction-llm-health.js";
+import { log } from "./logger.js";
+
+test("tracker: starts reachable with no failure recorded", () => {
+  resetExtractionLlmHealthForTests();
+  try {
+    assert.deepEqual(getExtractionLlmHealth(), {
+      llmReachable: true,
+      lastFailureReason: null,
+      lastFailureAt: null,
+    });
+  } finally {
+    resetExtractionLlmHealthForTests();
+  }
+});
+
+test("tracker: a failure marks the extractor unavailable with the last reason (health payload, non-debug)", () => {
+  resetExtractionLlmHealthForTests();
+  try {
+    recordExtractionLlmFailure("no_models", 1_000);
+    const health = getExtractionLlmHealth();
+    assert.equal(health.llmReachable, false);
+    assert.equal(health.lastFailureReason, "no_models");
+    assert.equal(health.lastFailureAt, new Date(1_000).toISOString());
+
+    recordExtractionLlmFailure("local_llm_unavailable", 2_000);
+    assert.equal(getExtractionLlmHealth().lastFailureReason, "local_llm_unavailable");
+  } finally {
+    resetExtractionLlmHealthForTests();
+  }
+});
+
+test("tracker: a later success clears the failure so llmReachable and the reason agree", () => {
+  resetExtractionLlmHealthForTests();
+  try {
+    recordExtractionLlmFailure("no_models");
+    recordExtractionLlmSuccess();
+    assert.deepEqual(getExtractionLlmHealth(), {
+      llmReachable: true,
+      lastFailureReason: null,
+      lastFailureAt: null,
+    });
+  } finally {
+    resetExtractionLlmHealthForTests();
+  }
+});
+
+test("dedup: the first failure of a reason logs at ERROR level, repeats are suppressed", () => {
+  resetExtractionLlmHealthForTests();
+  const errors: string[] = [];
+  const debugs: string[] = [];
+  const originalError = log.error;
+  const originalDebug = log.debug;
+  log.error = (message: unknown) => {
+    errors.push(String(message));
+  };
+  log.debug = (message: unknown) => {
+    debugs.push(String(message));
+  };
+  try {
+    assert.equal(emitExtractionLlmFailureError("no_models", "auth_config", 0), true);
+    assert.equal(errors.length, 1);
+    assert.match(errors[0] ?? "", /no_models/);
+
+    // Same reason inside the window: suppressed to debug, no second ERROR.
+    assert.equal(emitExtractionLlmFailureError("no_models", "auth_config", 60_000), false);
+    assert.equal(errors.length, 1);
+    assert.equal(debugs.length, 1);
+
+    // A different reason emits its own first ERROR.
+    assert.equal(emitExtractionLlmFailureError("local_llm_unavailable", undefined, 60_000), true);
+    assert.equal(errors.length, 2);
+    assert.match(errors[1] ?? "", /local_llm_unavailable/);
+
+    // Outside the window the same reason emits again.
+    assert.equal(emitExtractionLlmFailureError("no_models", undefined, 3_600_000), true);
+    assert.equal(errors.length, 3);
+  } finally {
+    log.error = originalError;
+    log.debug = originalDebug;
+    resetExtractionLlmHealthForTests();
+  }
+});

package/src/extraction-llm-health.ts

@@ -0,0 +1,71 @@
+/**
+ * Extraction-LLM availability tracking surfaced on `/health` (issue #3140).
+ *
+ * A failing extraction LLM (unreachable endpoint, gateway with no models)
+ * used to surface only as debug-level lines while extraction silently skipped
+ * persistence and the buffer grew for days. The extraction run records every
+ * attempt outcome here; the access `/health` payload reads the last outcome so
+ * an unavailable extractor is visible without debug logs, and each distinct
+ * failure reason logs at ERROR level at most once per window instead of once
+ * per failed flush.
+ */
+
+import { log } from "./logger.js";
+
+export interface ExtractionLlmHealth {
+  /** Whether the LAST extraction attempt completed without a failure marker. */
+  llmReachable: boolean;
+  /** `failureReason` of the last failed attempt; null while reachable. */
+  lastFailureReason: string | null;
+  /** ISO timestamp of the last failed attempt; null while reachable. */
+  lastFailureAt: string | null;
+}
+
+/** One ERROR line per distinct reason per window; repeats stay at debug. */
+const DEDUP_WINDOW_MS = 3_600_000;
+
+let lastFailureReason: string | null = null;
+let lastFailureAtMs: number | null = null;
+const lastErrorEmitByReason = new Map<string, number>();
+
+export function recordExtractionLlmSuccess(): void {
+  lastFailureReason = null;
+  lastFailureAtMs = null;
+}
+
+export function recordExtractionLlmFailure(reason: string, atMs: number = Date.now()): void {
+  lastFailureReason = reason;
+  lastFailureAtMs = atMs;
+}
+
+export function getExtractionLlmHealth(): ExtractionLlmHealth {
+  return {
+    llmReachable: lastFailureReason === null,
+    lastFailureReason,
+    lastFailureAt: lastFailureAtMs === null ? null : new Date(lastFailureAtMs).toISOString(),
+  };
+}
+
+/**
+ * ERROR-level, deduplicated failure event (issue #3140): the first failure of
+ * a given reason inside the window logs at error level; repeats inside the
+ * window log at debug so the backoff retry loop cannot flood the transcript
+ * while the outage stays visible. Returns whether the error line was emitted.
+ */
+export function emitExtractionLlmFailureError(reason: string, detail?: string, nowMs: number = Date.now()): boolean {
+  const suffix = detail ? `: ${detail}` : "";
+  const last = lastErrorEmitByReason.get(reason);
+  if (last !== undefined && nowMs - last < DEDUP_WINDOW_MS) {
+    log.debug(`extraction failure repeat suppressed for ${DEDUP_WINDOW_MS / 60_000}m: ${reason}${suffix}`);
+    return false;
+  }
+  lastErrorEmitByReason.set(reason, nowMs);
+  log.error(`extraction failed with no durable outputs (buffer retained for retry): ${reason}${suffix}`);
+  return true;
+}
+
+/** Test seam: restore pristine singleton state. */
+export function resetExtractionLlmHealthForTests(): void {
+  recordExtractionLlmSuccess();
+  lastErrorEmitByReason.clear();
+}

package/src/json-extract.ts

@@ -21,6 +21,12 @@ export function extractJsonCandidates(text: string): string[] {
   const cleaned = stripCodeFences(trimmed);
   const candidates: string[] = [];
 
+  // Verbatim balanced blocks FIRST: stripCodeFences rewrites every ``` pair, so
+  // a stripped candidate can parse while carrying altered content (e.g. a
+  // patch value that embeds an inner code block). A string-aware balanced scan
+  // of the unstripped text yields the payload unmodified; stripped candidates
+  // remain as later fallbacks for shapes the raw scan cannot cut.
+  candidates.push(...scanBalancedJsonBlocks(trimmed));
   if (cleaned.length > 0) candidates.push(cleaned);
   candidates.push(...scanBalancedJsonBlocks(cleaned));