@remnic/core 9.3.726 → 9.3.728

package/src/chat/chat-session.ts

@@ -7,7 +7,8 @@
  * *about* memories does not create memories of the conversation itself.
  */
 
-import { mkdir, readFile, appendFile, readdir, stat, unlink } from "node:fs/promises";
+import { mkdir, readFile, appendFile, readdir, stat, unlink, open } from "node:fs/promises";
+import { constants as fsConstants } from "node:fs";
 import { join } from "node:path";
 import { randomUUID } from "node:crypto";
 
@@ -40,6 +41,36 @@ export function chatSessionFile(memoryDir: string, chatSessionId: string): strin
   return join(chatSessionDir(memoryDir), `${chatSessionId}.jsonl`);
 }
 
+// ---------------------------------------------------------------------------
+// Monotonic transcript seq (issue #1687 review — strictly increasing)
+// ---------------------------------------------------------------------------
+
+/**
+ * Last emitted transcript `seq`. Seeded from `Date.now()` on first use and
+ * incremented when two appends land in the same millisecond, so `seq` is
+ * strictly increasing within a process (review thread: `Date.now()` alone is
+ * not monotonic — same-ms entries would share a seq and break the SSE
+ * reconnect dedup-by-seq contract). Across process restarts the counter is
+ * raised above the on-disk max by `loadChatSession` (issue #1718), so a
+ * backward clock step (NTP, VM migration, manual change) cannot re-seed it
+ * below lines already persisted for a resumed session.
+ */
+let lastTranscriptSeq = 0;
+
+function nextTranscriptSeq(): number {
+  const now = Date.now();
+  lastTranscriptSeq = now > lastTranscriptSeq ? now : lastTranscriptSeq + 1;
+  return lastTranscriptSeq;
+}
+
+/**
+ * Test-only: reset the module-level transcript seq counter so a regression
+ * test can deterministically simulate a fresh process restart (issue #1718).
+ */
+export function __resetTranscriptSeqForTest(): void {
+  lastTranscriptSeq = 0;
+}
+
 /**
  * Create a new chat session.  The session binds the caller's principal and
  * sessionKey at creation (rule 42); every tool call flows through
@@ -154,6 +185,19 @@ export async function loadChatSession(
       // tolerated, never crash the engine).
     }
   }
+  // Issue #1718 — backward-clock-skew robustness: raise the module-level seq
+  // counter so the next append is strictly greater than any line already on
+  // disk for this session, regardless of clock direction across restarts
+  // (NTP step, VM migration, manual change). Without this, a backward clock
+  // skew would re-seed the counter below the on-disk max and the SSE
+  // reconnect dedup-by-seq contract could drop freshly-appended entries as
+  // duplicates. The transcript is already fully parsed above, so this is a
+  // single pass over the in-memory array.
+  for (const e of transcript) {
+    if (typeof e.seq === "number" && e.seq + 1 > lastTranscriptSeq) {
+      lastTranscriptSeq = e.seq + 1;
+    }
+  }
   return {
     id: chatSessionId,
     principal,
@@ -169,25 +213,130 @@ export async function loadChatSession(
 
 /**
  * Append a transcript entry to the session file (atomic append, rule 54).
+ *
+ * After the append resolves, in-process subscribers (open SSE connections —
+ * issue #1687) are notified synchronously so live clients receive the new
+ * entry without polling.  Listener errors are swallowed so a misbehaving
+ * subscriber can never break a transcript append (rule 54 — atomic + safe).
  */
 export async function appendTranscriptEntry(
   memoryDir: string,
   chatSessionId: string,
   entry: Omit<ChatTranscriptEntry, "seq" | "ts">,
 ): Promise<ChatTranscriptEntry> {
+  const filePath = chatSessionFile(memoryDir, chatSessionId);
   const full: ChatTranscriptEntry = {
     ...entry,
-    seq: Date.now(),
+    seq: nextTranscriptSeq(),
     ts: new Date().toISOString(),
   };
-  await appendFile(
-    chatSessionFile(memoryDir, chatSessionId),
-    JSON.stringify(full) + "\n",
-    "utf8",
-  );
+  // Atomic resurrection guard (codex P2): open with O_APPEND but WITHOUT
+  // O_CREAT so a session already unlinked by a concurrent TTL sweep fails at
+  // open-time (ENOENT) — there is no stat->appendFile TOCTOU. A headerless
+  // recreation would load with no principal binding and be treated as public
+  // by sessionBelongsToPrincipal. A concurrent unlink during the append is
+  // caught by the post-append re-stat below so the turn fails visibly rather
+  // than writing to an orphaned inode and returning 200.
+  let fh;
+  try {
+    fh = await open(filePath, fsConstants.O_APPEND | fsConstants.O_WRONLY);
+  } catch (err) {
+    // Only ENOENT (session unlinked by a concurrent TTL sweep) maps to
+    // chat_session_expired; real fs errors (EACCES, EMFILE, EISDIR, ...)
+    // are rethrown so the caller surfaces the actual failure (codex P2).
+    if (err instanceof Error && (err as NodeJS.ErrnoException).code === "ENOENT") {
+      throw new Error("chat_session_expired");
+    }
+    throw err;
+  }
+  try {
+    await fh.appendFile(JSON.stringify(full) + "\n", "utf8");
+  } finally {
+    await fh.close();
+  }
+  // Post-append re-check (codex P2): if a concurrent TTL sweep unlinked the
+  // session between open() and here, the append landed on the orphaned inode
+  // and the directory no longer references it. Re-stat the PATH (not the fd)
+  // so the turn fails with chat_session_expired instead of returning 200 with
+  // a reply the client cannot resume. A later sweep unlinking an over-TTL
+  // session is a legitimate TTL action, not a silent loss.
+  try {
+    await stat(filePath);
+  } catch (err) {
+    // Only ENOENT (concurrent TTL unlink) is session expiry; other fs
+    // errors (EACCES, EMFILE, ENOTDIR, ...) are rethrown (codex/kilo P2).
+    if (err instanceof Error && (err as NodeJS.ErrnoException).code === "ENOENT") {
+      throw new Error("chat_session_expired");
+    }
+    throw err;
+  }
+  notifyTranscriptListeners(memoryDir, chatSessionId, full);
   return full;
 }
 
+// ---------------------------------------------------------------------------
+// In-process transcript pub/sub (issue #1687 SSE push)
+// ---------------------------------------------------------------------------
+
+/**
+ * Per-session listener sets, keyed by `memoryDir + chatSessionId` so two
+ * memory stores sharing a legacy/imported session id cannot leak transcript
+ * entries to each other (AGENTS.md State Scoping — module-level singletons
+ * are scoped per store).  Kept module-level so appendTranscriptEntry can fan
+ * out new entries to open SSE connections regardless of which caller
+ * appended (HTTP, MCP, or CLI).  Empty sets are pruned so the map never
+ * grows unbounded (rule 47 — no leak).
+ */
+const transcriptListeners = new Map<string, Set<(entry: ChatTranscriptEntry) => void>>();
+
+function transcriptListenerKey(memoryDir: string, chatSessionId: string): string {
+  return `${memoryDir}\x00${chatSessionId}`;
+}
+
+function notifyTranscriptListeners(memoryDir: string, chatSessionId: string, entry: ChatTranscriptEntry): void {
+  const set = transcriptListeners.get(transcriptListenerKey(memoryDir, chatSessionId));
+  if (!set) return;
+  for (const fn of set) {
+    try {
+      fn(entry);
+    } catch {
+      // A listener must never break the append path (rule 54).
+    }
+  }
+}
+
+/**
+ * Subscribe to live transcript entries for a chat session in a given memory
+ * store.  Returns an unsubscribe function that removes the listener and
+ * prunes the session's set when it becomes empty.  Used by the SSE handler
+ * to push new user/assistant entries to connected clients (issue #1687).
+ *
+ * The `memoryDir` scopes the subscription to its store so a process hosting
+ * two Remnic services cannot cross-deliver transcript entries (AGENTS.md
+ * State Scoping).
+ */
+export function subscribeChatTranscript(
+  memoryDir: string,
+  chatSessionId: string,
+  listener: (entry: ChatTranscriptEntry) => void,
+): () => void {
+  const key = transcriptListenerKey(memoryDir, chatSessionId);
+  let set = transcriptListeners.get(key);
+  if (!set) {
+    set = new Set();
+    transcriptListeners.set(key, set);
+  }
+  set.add(listener);
+  return () => {
+    const current = transcriptListeners.get(key);
+    if (!current) return;
+    current.delete(listener);
+    if (current.size === 0) {
+      transcriptListeners.delete(key);
+    }
+  };
+}
+
 /**
  * Append a pending-plan marker so a later turn can confirm the plan
  * (append-only state — loadChatSession scans for the latest unresolved one).
@@ -271,6 +420,16 @@ export async function cleanupExpiredChatSessions(
       // boundary is inclusive; sub-millisecond APFS mtime skew is negligible
       // against an hour-scale threshold (rule 54 — deterministic cleanup).
       if (ttlHours <= 0 || ageHours >= ttlHours) {
+        // Re-check mtime immediately before unlinking so a turn appended
+        // mid-sweep (which refreshes mtime) is not deleted by the stale age
+        // decision captured above (codex P2). ttlHours <= 0 (expire-all)
+        // skips the re-check. The residual microsecond window is a
+        // legitimate sweep of an over-TTL file.
+        if (ttlHours > 0) {
+          const fresh = await stat(filePath);
+          const freshAge = (Date.now() - fresh.mtimeMs) / (1000 * 60 * 60);
+          if (freshAge < ttlHours) continue;
+        }
         await unlink(filePath);
         removed++;
       }

package/src/cli.ts

@@ -4,6 +4,7 @@ import { access, lstat, readFile, readdir, realpath, unlink } from "node:fs/prom
 import { createHash } from "node:crypto";
 import type { Readable, Writable } from "node:stream";
 import type { Orchestrator } from "./orchestrator.js";
+import { resolveMemoryLifecycleCapabilities } from "./capabilities.js";
 import { ThreadingManager } from "./threading.js";
 import { utcDayRange } from "./transcript.js";
 import { runWearablesCliCommand } from "./wearables/cli.js";
@@ -3728,7 +3729,7 @@ export function registerCli(
           console.log("=== Extraction Judge Verdict Stats ===\n");
           console.log(`Total verdicts: ${stats.total}`);
           if (stats.total === 0) {
-            if (!orchestrator.config.extractionJudgeTelemetryEnabled) {
+            if (!resolveMemoryLifecycleCapabilities(orchestrator.config).extractionJudgeTelemetry) {
               console.log(
                 "\nNote: extractionJudgeTelemetryEnabled is OFF. Enable it in plugin config to collect verdict telemetry.",
               );
@@ -8541,7 +8542,7 @@ export function registerCli(
             config: orchestrator.config,
             memoryDir: orchestrator.config.memoryDir,
             embeddingLookupFactory: (storage) => {
-              if (!orchestrator.config.embeddingFallbackEnabled) return undefined;
+              if (!resolveMemoryLifecycleCapabilities(orchestrator.config).embeddingFallback) return undefined;
               return async (content: string, limit: number) => {
                 try {
                   return await orchestrator.semanticDedupLookup(content, limit, storage);

package/src/compat/codex-cli-fallback.ts

@@ -0,0 +1,23 @@
+/**
+ * Deprecated alias subpath `@remnic/core/codex-cli-fallback`.
+ *
+ * PR #1638 renamed `src/codex-cli-fallback.ts` -> `src/cli-fallback.ts` to
+ * graduate the host-prefixed name per CLAUDE.md rule 31 (generic @remnic/core
+ * modules must not carry a host prefix). This thin re-export keeps the old
+ * subpath resolving during the compat window so external consumers importing
+ * `@remnic/core/codex-cli-fallback` 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/cli-fallback` instead.
+ */
+export * from "../cli-fallback.js";
+
+process.emitWarning(
+  "@remnic/core/codex-cli-fallback is a deprecated alias; import from @remnic/core/cli-fallback instead. Removed in v10.0.0 (issue #1643).",
+  {
+    type: "DeprecationWarning",
+    code: "REMNIC_DEP_CORE_SUBPATH_CODEX_CLI_FALLBACK",
+    detail: "PR #1638 renamed codex-cli-fallback.ts to cli-fallback.ts.",
+  },
+);

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/embedding-fallback.ts

@@ -1,6 +1,7 @@
 import path from "node:path";
 import { mkdir, readFile, rename, rm, writeFile } from "node:fs/promises";
 import { log } from "./logger.js";
+import { resolveMemoryLifecycleCapabilities } from "./capabilities.js";
 import { readEnvVar } from "./runtime/env.js";
 import type { PluginConfig } from "./types.js";
 import {
@@ -397,7 +398,7 @@ export class EmbeddingFallback {
   private async resolveProvider(
     options: { includeHost?: boolean } = {},
   ): Promise<ProviderConfig | null> {
-    if (!this.config.embeddingFallbackEnabled) return null;
+    if (!resolveMemoryLifecycleCapabilities(this.config).embeddingFallback) return null;
 
     if (
       options.includeHost !== false &&

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);
+});