@remnic/core 9.3.696 → 9.3.698

package/src/coding/session-delta-surfaces.ts

@@ -117,6 +117,16 @@ export type DeltaSurfaceResponse =
       delta: {
         commits: ReadonlyArray<{ sha: string; subject: string }>;
         touchedFiles: readonly string[];
+        /**
+         * Uncapped total commit count (the {@link commits} slice is capped
+         * for transport). Issue #1630 fix 1.
+         */
+        totalCommits: number;
+        /**
+         * Uncapped total touched-file count (the {@link touchedFiles} slice
+         * is capped for transport). Issue #1630 fix 1.
+         */
+        totalTouchedFiles: number;
         summaryLine: string;
       };
       nextState: LastSeenState;
@@ -161,6 +171,15 @@ export interface DeltaSurfaceStorage {
   readonly memoryDir: string;
   /** The resolved coding-scoped namespace — basis for the state filename. */
   readonly namespace: string;
+  /**
+   * Whether the calling principal may WRITE the namespace — i.e. advance the
+   * last-seen-head marker. Read-only callers (e.g. a principal with read-but-
+   * not-write on the shared namespace) receive the computed delta but the
+   * state file is NOT advanced, so they cannot move another principal's
+   * baseline (issue #1630 fix 2). Defaults to `true` when omitted so existing
+   * callers (and the surface contract tests) keep their pre-fix behavior.
+   */
+  readonly canAdvanceState?: boolean;
 }
 
 /**
@@ -265,13 +284,21 @@ async function deltaGet(
   // 5. Persist the new state (rule 25 + rule 54). Failures here are logged
   //    but do NOT fail the operation — the delta was computed; the next
   //    session may re-derive it. A write failure surfaces in doctor/xray.
+  //
+  //    Issue #1630 fix 2: the marker write is gated on a write-capable
+  //    principal. A read-only caller (e.g. read-but-not-write on the shared
+  //    namespace) receives the computed delta but does NOT advance the state
+  //    marker, so it cannot move another principal's baseline. The default
+  //    is `true` so legacy callers and the surface contract tests keep their
+  //    pre-fix behavior.
+  const canAdvanceState = storage.canAdvanceState !== false;
   let nextState: LastSeenState | null = null;
   if (result.ok) {
     nextState = result.nextState;
   } else if (result.code === "unreachable_head") {
     nextState = result.nextState;
   }
-  if (nextState) {
+  if (nextState && canAdvanceState) {
     try {
       await writeLastSeenState(statePath, nextState);
     } catch (err) {
@@ -312,6 +339,8 @@ async function deltaGet(
         delta: {
           commits: result.delta.commits,
           touchedFiles: result.delta.touchedFiles,
+          totalCommits: result.delta.totalCommits,
+          totalTouchedFiles: result.delta.totalTouchedFiles,
           summaryLine: result.delta.summaryLine,
         },
         nextState: result.nextState,

package/src/coding/session-delta.test.ts

@@ -171,6 +171,52 @@ test("computeSessionDelta caps a large delta to MAX constants", () => {
   assert.equal(result.delta.touchedFiles.length, MAX_DELTA_FILES);
 });
 
+test("computeSessionDelta reports uncapped totals alongside capped slices (issue #1630 fix 1)", () => {
+  // A repo exceeding both caps: 100 commits / 200 files. The slices are
+  // capped for transport, but totalCommits/totalTouchedFiles must report
+  // the TRUE delta size so summaries never under-report.
+  const commitCount = 100;
+  const fileCount = 200;
+  const commits: GitCommit[] = Array.from({ length: commitCount }, (_, i) => ({
+    sha: `c${i}`,
+    subject: `s ${i}`,
+  }));
+  const files = Array.from({ length: fileCount }, (_, i) => `f${i}.ts`);
+  const result = computeSessionDelta(PRIOR, slice("head", commits, files));
+  if (!result.ok || result.kind !== "changed") {
+    assert.fail(`expected changed, got ${JSON.stringify(result)}`);
+    return;
+  }
+  // Capped display lists — transport-sized.
+  assert.equal(result.delta.commits.length, MAX_DELTA_COMMITS);
+  assert.equal(result.delta.touchedFiles.length, MAX_DELTA_FILES);
+  // Uncapped totals — the true delta size, NOT the capped slice length.
+  assert.equal(result.delta.totalCommits, commitCount);
+  assert.equal(result.delta.totalTouchedFiles, fileCount);
+  // The summary line must report the UNCAPPED totals, not the capped slice
+  // length — otherwise the briefing under-reports the delta size (codex review).
+  assert.match(result.delta.summaryLine, /100 commits, 200 files touched/);
+  assert.ok(!result.delta.summaryLine.match(/^.*20 commits, 50 files/), "summary must NOT use capped counts");
+});
+
+test("computeSessionDelta totals equal slice lengths when under the cap (issue #1630 fix 1)", () => {
+  // Below the caps, totals === slice lengths (no information lost).
+  const commits: GitCommit[] = [
+    { sha: "u1", subject: "under cap 1" },
+    { sha: "u2", subject: "under cap 2" },
+  ];
+  const files = ["a.ts", "b.ts", "c.ts"];
+  const result = computeSessionDelta(PRIOR, slice("head", commits, files));
+  if (!result.ok || result.kind !== "changed") {
+    assert.fail(`expected changed, got ${JSON.stringify(result)}`);
+    return;
+  }
+  assert.equal(result.delta.totalCommits, 2);
+  assert.equal(result.delta.totalTouchedFiles, 3);
+  assert.equal(result.delta.totalCommits, result.delta.commits.length);
+  assert.equal(result.delta.totalTouchedFiles, result.delta.touchedFiles.length);
+});
+
 // ──────────────────────────────────────────────────────────────────────────
 // State persistence — rule 25 (write after compute) + rule 54 (temp+rename)
 // ──────────────────────────────────────────────────────────────────────────

package/src/coding/session-delta.ts

@@ -72,6 +72,18 @@ export interface SessionDelta {
   commits: GitCommit[];
   /** Touched files since last seen, capped to {@link MAX_DELTA_FILES}. */
   touchedFiles: string[];
+  /**
+   * Uncapped total commit count. The {@link commits} slice is capped for
+   * transport; this total reports the true delta size so summaries and
+   * metrics never under-report on large repos (issue #1630 fix 1).
+   */
+  totalCommits: number;
+  /**
+   * Uncapped total touched-file count. The {@link touchedFiles} slice is
+   * capped for transport; this total reports the true delta size (issue
+   * #1630 fix 1).
+   */
+  totalTouchedFiles: number;
   /** A single human-readable summary line for briefing injection. */
   summaryLine: string;
 }
@@ -159,7 +171,12 @@ export function computeSessionDelta(
     delta: {
       commits,
       touchedFiles,
-      summaryLine: buildSummaryLine(commits.length, touchedFiles.length, lastSeen.at),
+      // Uncapped totals — the slices above are capped for transport, but
+      // the summary/metrics must report the true delta size so callers
+      // never under-report on large repos (issue #1630 fix 1).
+      totalCommits: current.commits.length,
+      totalTouchedFiles: current.touchedFiles.length,
+      summaryLine: buildSummaryLine(current.commits.length, current.touchedFiles.length, lastSeen.at),
     },
     nextState,
   };

package/src/config.test.ts

@@ -2050,3 +2050,35 @@ test("parseConfig rejects a present-but-non-string extractionFaithfulnessGate (s
   // A present-but-unknown string still rejects (pre-existing behavior preserved).
   assert.throws(() => parseConfig({ extractionFaithfulnessGate: "on" }), /extractionFaithfulnessGate must be one of/);
 });
+
+test("parseConfig extractionFaithfulnessContextChars rejects non-numeric and non-integer input (#1634)", () => {
+  // Issue #1634 (#1576 follow-up): migrate from coerce+clamp/default to the
+  // strict-integer validator used by qmdDaemonTimeoutMs / commitmentDecayDays.
+  // A malformed budget must reject, not silently default or round.
+  assert.equal(parseConfig({}).extractionFaithfulnessContextChars, 400);
+  assert.equal(parseConfig({ extractionFaithfulnessContextChars: null }).extractionFaithfulnessContextChars, 400);
+  assert.equal(parseConfig({ extractionFaithfulnessContextChars: "2400" }).extractionFaithfulnessContextChars, 2400);
+  assert.equal(parseConfig({ extractionFaithfulnessContextChars: 5000 }).extractionFaithfulnessContextChars, 4000);
+  for (const value of ["abc", "", 0, 1.5, "1.5", Number.NaN, Infinity, true, {}] as unknown[]) {
+    assert.throws(
+      () => parseConfig({ extractionFaithfulnessContextChars: value } as Record<string, unknown>),
+      /extractionFaithfulnessContextChars must be an integer/,
+      `invalid extractionFaithfulnessContextChars ${String(value)} should throw`,
+    );
+  }
+});
+
+test("parseConfig extractionFaithfulnessTimeoutMs rejects non-numeric and non-integer input (#1634)", () => {
+  // Issue #1634: same strict-integer contract as extractionFaithfulnessContextChars.
+  assert.equal(parseConfig({}).extractionFaithfulnessTimeoutMs, 8000);
+  assert.equal(parseConfig({ extractionFaithfulnessTimeoutMs: null }).extractionFaithfulnessTimeoutMs, 8000);
+  assert.equal(parseConfig({ extractionFaithfulnessTimeoutMs: "12000" }).extractionFaithfulnessTimeoutMs, 12_000);
+  assert.equal(parseConfig({ extractionFaithfulnessTimeoutMs: 999_999 }).extractionFaithfulnessTimeoutMs, 60_000);
+  for (const value of ["abc", "", 0, 1.5, "1.5", Number.NaN, Infinity, true, {}] as unknown[]) {
+    assert.throws(
+      () => parseConfig({ extractionFaithfulnessTimeoutMs: value } as Record<string, unknown>),
+      /extractionFaithfulnessTimeoutMs must be an integer/,
+      `invalid extractionFaithfulnessTimeoutMs ${String(value)} should throw`,
+    );
+  }
+});

package/src/config.ts

@@ -2927,18 +2927,18 @@ export function parseConfig(
       typeof cfg.extractionFaithfulnessModel === "string"
         ? cfg.extractionFaithfulnessModel
         : "",
-    // Numeric knobs go through coerceNumber so CLI operators can pass
-    // --config extractionFaithfulnessTimeoutMs=4000 without the string
-    // silently dropping to the default. Matches the coercion contract applied
-    // to other numeric config keys (CLAUDE.md rule #28 / gotcha #36).
-    extractionFaithfulnessContextChars: (() => {
-      const n = coerceNumber(cfg.extractionFaithfulnessContextChars);
-      return n !== undefined && n > 0 ? Math.min(Math.round(n), 4000) : 400;
-    })(),
-    extractionFaithfulnessTimeoutMs: (() => {
-      const n = coerceNumber(cfg.extractionFaithfulnessTimeoutMs);
-      return n !== undefined && n > 0 ? Math.min(Math.round(n), 60_000) : 8000;
-    })(),
+    // Issue #1634 (#1576 follow-up): strict-integer validation via
+    // parseIntegerAtLeast — reject non-numeric, <=0, non-integer, NaN,
+    // Infinity, booleans, objects (gotcha #51). Mirrors qmdDaemonTimeoutMs.
+    // Valid CLI-string integers still coerce and clamp to the budget cap.
+    extractionFaithfulnessContextChars: Math.min(
+      parseIntegerAtLeast(cfg.extractionFaithfulnessContextChars, 400, 1, "extractionFaithfulnessContextChars"),
+      4000,
+    ),
+    extractionFaithfulnessTimeoutMs: Math.min(
+      parseIntegerAtLeast(cfg.extractionFaithfulnessTimeoutMs, 8000, 1, "extractionFaithfulnessTimeoutMs"),
+      60_000,
+    ),
     // Inline source attribution (issue #369). Opt-in to preserve
     // backwards compatibility with existing downstream consumers.
     inlineSourceAttributionEnabled: cfg.inlineSourceAttributionEnabled === true,

package/src/extraction-faithfulness.test.ts

@@ -794,12 +794,13 @@ test("applyFaithfulnessVerdict: per-fact backend failure (ok:false) → unchecke
   assert.equal(r.enforceStatus, undefined);
 });
 
-test("locateFactQuote: finds the best-overlap sentence", () => {
+test("locateFactQuote: finds the best-overlap sentence (returns LocatedQuote, issue #1633)", () => {
   const src = "I drove to Berlin yesterday. My favorite editor is Vim.";
-  assert.equal(
-    locateFactQuote("The user likes Vim.", src),
-    "My favorite editor is Vim.",
-  );
+  const located = locateFactQuote("The user likes Vim.", src);
+  assert.ok(located, "expected a located quote");
+  assert.equal(located!.quote, "My favorite editor is Vim.");
+  // offset must point at the matched candidate's actual position in sourceText.
+  assert.equal(located!.offset, src.indexOf("My favorite editor is Vim."));
 });
 
 test("locateFactQuote: returns undefined below the overlap threshold", () => {
@@ -812,6 +813,120 @@ test("locateFactQuote: empty inputs → undefined", () => {
   assert.equal(locateFactQuote("fact", ""), undefined);
 });
 
+test("locateFactQuote: centers the bounded window on matched terms for >maxQuoteChars candidates (issue #1633, codex :747)", () => {
+  // The supporting terms ("PostgreSQL", "migration") fall well past the
+  // ~maxQuoteChars prefix. Returning the prefix would drop the evidence and
+  // route an actually-entailed fact to pending_review in enforce mode.
+  const filler = "Lorem ipsum dolor sit amet ".repeat(28); // ~728-char preamble
+  const sourceText = filler + "The team completed the PostgreSQL migration last quarter.";
+  const located = locateFactQuote(
+    "The team finished the PostgreSQL migration.",
+    sourceText,
+    200,
+  );
+  assert.ok(located, "expected a located quote");
+  assert.ok(
+    located!.quote.length <= 200,
+    `bounded quote must respect maxQuoteChars (got ${located!.quote.length})`,
+  );
+  // The matched evidence must survive truncation — the whole point of centering.
+  assert.ok(located!.quote.includes("PostgreSQL"), "bounded quote keeps 'PostgreSQL'");
+  assert.ok(located!.quote.includes("migration"), "bounded quote keeps 'migration'");
+  // offset must locate the returned (possibly bounded) quote within sourceText.
+  assert.equal(
+    sourceText.slice(located!.offset, located!.offset + located!.quote.length),
+    located!.quote,
+    "offset must point at the returned quote within sourceText",
+  );
+});
+
+test("locateFactQuote: tracks the matched occurrence offset for repeated anaphoric lines (issue #1633, codex :710, :710-thread-S)", () => {
+  // Two entities with the EXACT SAME anaphoric sentence afterward — the
+  // fact is about Zeta, which appears SECOND. Both "It launched in March."
+  // candidates score identically on own-overlap, so the locator must use the
+  // preceding-neighbor tiebreak to pick the occurrence whose neighbor ("Zeta")
+  // names the fact's entity. The offset must then point at the Zeta clause.
+  const sourceText =
+    "We started the Acme project in January. It launched in March. " +
+    "Then we began the Zeta initiative in February. It launched in March.";
+  const located = locateFactQuote("The Zeta initiative launched in March.", sourceText);
+  assert.ok(located, "expected a located quote");
+  // The matched quote is the (identical) anaphoric line; offset must point at
+  // the SECOND occurrence (the one after the Zeta clause), not the first.
+  const firstOccurrence = sourceText.indexOf("It launched in March.");
+  const secondOccurrence = sourceText.indexOf("It launched in March.", firstOccurrence + 1);
+  assert.ok(secondOccurrence > firstOccurrence, "test fixture must contain two occurrences");
+  assert.equal(
+    located!.offset,
+    secondOccurrence,
+    "offset must point at the second (Zeta) occurrence, not the first (Acme)",
+  );
+  assert.equal(
+    sourceText.slice(located!.offset, located!.offset + located!.quote.length),
+    located!.quote,
+    "offset must point at the start of the matched quote",
+  );
+});
+
+test("locateFactQuote: bounded window keeps the densest evidence cluster when matches span wider than maxQuoteChars (codex :747-thread-O)", () => {
+  // Fact tokens appear at BOTH ENDS of a long candidate with filler between.
+  // A naive midpoint-centered window would land in the filler and contain no
+  // evidence. The densest-cluster window must capture actual matched terms.
+  const head = "PostgreSQL migration completed. "; // matches at the very start
+  const filler = "and ".repeat(220); // ~880 chars of filler (no fact tokens)
+  const tail = " for the user."; // matches at the very end
+  const sourceText = head + filler + tail; // one long sentence, no period inside
+  // Fact spans tokens from both ends: postgresql, migration (head) + user (tail).
+  const located = locateFactQuote(
+    "The user completed the PostgreSQL migration.",
+    sourceText,
+    120,
+  );
+  assert.ok(located, "expected a located quote");
+  assert.ok(
+    located!.quote.length <= 120,
+    `bounded quote must respect maxQuoteChars (got ${located!.quote.length})`,
+  );
+  // The densest cluster is the head (2 matches: postgresql, migration); the
+  // window must contain at least one of them. (user appears alone at the tail,
+  // so a tail-anchored window would be sparser and is not chosen.)
+  assert.ok(
+    located!.quote.includes("PostgreSQL") || located!.quote.includes("migration"),
+    "bounded window must include matched evidence, not pure filler",
+  );
+});
+
+test("locateFactQuote: bounded window stays linear with many repeated matched tokens (codex PRRT_kwDORJXyws6Ocih3)", () => {
+  // A long unpunctuated candidate with thousands of repeats of a fact token
+  // (pasted logs / minified text). The densest-cluster selection must stay
+  // O(n) via the two-pointer sliding window; the O(n^2) nested loop would
+  // stall extraction on ~5k repeats. This test asserts both correctness (the
+  // bounded window contains the densest cluster) and that the call returns
+  // promptly — under O(n^2) this fixture (~5k repeats) would take seconds.
+  const repeats = 5000;
+  const token = "PostgreSQL "; // one fact token per repeat
+  const filler = "x ".repeat(50); // leading filler so the cluster is mid-string
+  const sourceText = filler + token.repeat(repeats) + "migration done";
+  const start = Date.now();
+  const located = locateFactQuote("PostgreSQL migration done.", sourceText, 200);
+  const elapsed = Date.now() - start;
+  assert.ok(located, "expected a located quote");
+  assert.ok(
+    located!.quote.length <= 200,
+    `bounded quote must respect maxQuoteChars (got ${located!.quote.length})`,
+  );
+  // The densest cluster is the run of PostgreSQL repeats; the window must be
+  // anchored inside it (not in the leading filler) and contain evidence.
+  assert.ok(
+    located!.quote.includes("PostgreSQL"),
+    "bounded window must anchor inside the densest cluster",
+  );
+  assert.ok(
+    elapsed < 1000,
+    `bounded window must stay linear (took ${elapsed}ms for ${repeats} repeats)`,
+  );
+});
+
 test("applyFaithfulnessVerdict: bumps verdict counters at apply time (cursor review)", () => {
   const counters = createFaithfulnessCounters();
   const map: Map<number, FaithfulnessResult> = new Map([
@@ -1042,6 +1157,35 @@ test("extractContextWindow: returns undefined when quote is absent from sourceTe
   assert.equal(extractContextWindow("source", "s", 0), undefined);
 });
 
+test("extractContextWindow: matchedOffset selects the matched occurrence, not the first (issue #1633, codex :710)", () => {
+  // The same anaphoric line appears twice — once about Acme, once about Zeta.
+  // Without matchedOffset, indexOf centers context on Acme (the first hit).
+  // With the locator's offset, the window must center on the matched (Zeta) hit.
+  const sourceText =
+    "Acme context before. It launched in March. Acme context after. " +
+    "Zeta context before. It launched in March. Zeta context after.";
+  const quote = "It launched in March.";
+  const firstOccurrence = sourceText.indexOf(quote);
+  const zetaOccurrence = sourceText.indexOf("Zeta context before");
+  assert.ok(firstOccurrence >= 0 && zetaOccurrence > firstOccurrence);
+  // Budget 50 captures the surrounding entity tag without spanning both
+  // occurrences (which would make them indistinguishable).
+  const ctxDefault = extractContextWindow(sourceText, quote, 50);
+  const ctxMatched = extractContextWindow(sourceText, quote, 50, zetaOccurrence);
+  const ctxFirst = extractContextWindow(sourceText, quote, 50, firstOccurrence);
+  assert.ok(ctxDefault && ctxMatched && ctxFirst, "all windows must resolve");
+  assert.ok(
+    ctxDefault!.includes("Acme") && !ctxDefault!.includes("Zeta"),
+    "default (no offset) centers on the first (Acme) occurrence, not Zeta",
+  );
+  assert.ok(
+    ctxMatched!.includes("Zeta") && !ctxMatched!.includes("Acme"),
+    "matchedOffset centers on the matched (Zeta) occurrence, not Acme",
+  );
+  assert.notEqual(ctxMatched, ctxDefault, "windows must differ when offset disambiguates");
+  assert.equal(ctxFirst, ctxDefault, "explicit first-occurrence offset equals the default");
+});
+
 test("runFaithfulnessGateBatch: fallback locator injects CONTEXT into the verifier prompt (codex P2 PRRT_kwDORJXyws6OblI1)", async () => {
   // No #1575 sources → the fallback locator locates a quote from sourceText.
   // Previously the input never set `context`, so the surrounding turn text

package/src/extraction-faithfulness.ts

@@ -718,9 +718,26 @@ export function extractContextWindow(
   sourceText: string,
   quote: string,
   contextChars: number,
+  /**
+   * Character offset of `quote` within `sourceText` (from `locateFactQuote`).
+   * When the quote string appears more than once — e.g. repeated anaphoric
+   * lines after different entities — pass the matched occurrence's offset so
+   * the context window centers on the actual match, not the first occurrence
+   * (issue #1633, codex PRRT_kwDORJXyws6ObzwI). Defaults to the first
+   * occurrence via indexOf for backward compatibility.
+   */
+  matchedOffset?: number,
 ): string | undefined {
   if (!sourceText || !quote || !(contextChars > 0)) return undefined;
-  const idx = sourceText.indexOf(quote);
+  let idx: number;
+  if (matchedOffset !== undefined && matchedOffset >= 0) {
+    const at = sourceText.indexOf(quote, matchedOffset);
+    // Fall back to the first occurrence if the matched offset is stale (e.g.
+    // the quote was bounded and is not a literal substring at that offset).
+    idx = at >= 0 ? at : sourceText.indexOf(quote);
+  } else {
+    idx = sourceText.indexOf(quote);
+  }
   if (idx < 0) return undefined;
   const quoteEnd = idx + quote.length;
   const center = Math.floor((idx + quoteEnd) / 2);
@@ -733,31 +750,179 @@ export function extractContextWindow(
   return window.length > 0 ? window : undefined;
 }
 
+/**
+ * A located fallback quote plus the offset it begins at in the source text.
+ * `offset` lets `extractContextWindow` disambiguate repeated occurrences of
+ * the same quote string (issue #1633).
+ */
+export interface LocatedQuote {
+  /** Verbatim source span, centered on the matched terms when truncated. */
+  quote: string;
+  /** Character offset of `quote` within sourceText. */
+  offset: number;
+}
+
+interface SourceCandidate {
+  /** Trimmed candidate text. */
+  text: string;
+  /** Character offset of `text` within the source string. */
+  start: number;
+}
+
+/**
+ * Split source text into candidate spans (sentences, then line segments as a
+ * fallback for transcripts without sentence punctuation), tracking each
+ * candidate's start offset so repeated occurrences can be disambiguated
+ * (issue #1633).
+ */
+function splitSourceCandidates(sourceText: string): SourceCandidate[] {
+  const candidates: SourceCandidate[] = [];
+  const re = /(?<=[.!?])\s+|\n+/g;
+  let lastEnd = 0;
+  let m: RegExpExecArray | null;
+  while ((m = re.exec(sourceText)) !== null) {
+    pushCandidate(candidates, sourceText, lastEnd, m.index);
+    lastEnd = re.lastIndex;
+  }
+  pushCandidate(candidates, sourceText, lastEnd, sourceText.length);
+  return candidates;
+}
+
+function pushCandidate(
+  out: SourceCandidate[],
+  source: string,
+  begin: number,
+  end: number,
+): void {
+  const seg = source.slice(begin, end);
+  const leadingWS = seg.length - seg.trimStart().length;
+  const trimmed = seg.trim();
+  if (trimmed.length > 0) {
+    out.push({ text: trimmed, start: begin + leadingWS });
+  }
+}
+
+/**
+ * Locate the start offsets of fact-token matches inside a candidate. Used by
+ * `locateFactQuote` to build a bounded window that is guaranteed to contain
+ * real evidence (issue #1633, codex PRRT_kwDORJXyws6Obrwe / PRRT_kwDORJXyws6Oce-O).
+ */
+function locateMatchedTokens(factTokens: Set<string>, candidate: string): number[] {
+  const lower = candidate.toLowerCase();
+  const wordRe = /[a-z0-9]+/g;
+  const positions: number[] = [];
+  let m: RegExpExecArray | null;
+  while ((m = wordRe.exec(lower)) !== null) {
+    const word = m[0];
+    if (word.length <= 1) continue;
+    if (STOPWORDS.has(word)) continue;
+    if (factTokens.has(crudeStem(word))) {
+      positions.push(m.index);
+    }
+  }
+  return positions;
+}
+
+/**
+ * Build a bounded window of `maxChars` from `text` that contains the densest
+ * cluster of matched-token positions. Slides a maxChars-wide window anchored
+ * at each matched token and keeps the one that captures the most matches
+ * (tiebreak: earliest anchor). This guarantees the window includes real
+ * evidence even when the matched span is wider than `maxChars` (e.g. fact
+ * tokens at both ends of a long sentence with filler between). Centering on
+ * the densest cluster's midpoint then uses any leftover budget as leading and
+ * trailing context. Returns the window text and its start offset within `text`
+ * so callers can translate the in-candidate offset back to a source-text offset.
+ */
+function boundedWindow(
+  text: string,
+  matchedPositions: number[],
+  maxChars: number,
+): { text: string; start: number } {
+  if (matchedPositions.length === 0) {
+    // Defensive: overlap scoring accepted the candidate but no individual
+    // token matched (e.g. all matches were stopwords). Fall back to prefix.
+    const end = Math.min(text.length, maxChars);
+    return { text: text.slice(0, end), start: 0 };
+  }
+  // matchedPositions is sorted ascending (the regex scans left-to-right), so a
+  // two-pointer sliding window finds the densest maxChars-wide cluster in O(n)
+  // instead of O(n^2). This matters when a long unpunctuated candidate carries
+  // many repeats of a fact token (pasted logs, minified text) — thousands of
+  // positions would otherwise stall extraction before the LLM call (codex
+  // PRRT_kwDORJXyws6Ocih3).
+  let bestAnchor = matchedPositions[0]!;
+  let bestCount = 0;
+  let bestLast = bestAnchor;
+  let j = 0;
+  for (let i = 0; i < matchedPositions.length; i++) {
+    const anchor = matchedPositions[i]!;
+    const winEnd = anchor + maxChars;
+    if (j < i) j = i;
+    while (j + 1 < matchedPositions.length && matchedPositions[j + 1]! < winEnd) {
+      j++;
+    }
+    const count = j - i + 1;
+    if (count > bestCount) {
+      bestCount = count;
+      bestAnchor = anchor;
+      bestLast = matchedPositions[j]!;
+    }
+  }
+  // The densest cluster [bestAnchor, bestLast] fits within maxChars by
+  // construction; center a maxChars window on its midpoint, clamped to text.
+  const center = Math.floor((bestAnchor + bestLast) / 2);
+  const half = Math.floor(maxChars / 2);
+  let start = Math.max(0, center - half);
+  const end = Math.min(text.length, start + maxChars);
+  // Re-anchor start so the window uses the full budget when end clamped.
+  start = Math.max(0, end - maxChars);
+  return { text: text.slice(start, end), start };
+}
+
 export function locateFactQuote(
   factText: string,
   sourceText: string,
   maxQuoteChars = 600,
-): string | undefined {
+): LocatedQuote | undefined {
   if (!factText || !sourceText) return undefined;
   const factTokens = tokenize(factText);
   if (factTokens.size === 0) return undefined;
-  // Split source into candidate spans: sentences, then line segments as a
-  // fallback for transcripts without sentence punctuation.
-  const candidates: string[] = [];
-  for (const sentence of sourceText.split(/(?<=[.!?])\s+|\n+/)) {
-    const s = sentence.trim();
-    if (s.length > 0) candidates.push(s);
-  }
+  const candidates = splitSourceCandidates(sourceText);
   if (candidates.length === 0) return undefined;
-  let best: { quote: string; score: number } | null = null;
-  for (const candidate of candidates) {
-    const score = overlapCoefficient(factTokens, tokenize(candidate));
-    if (!best || score > best.score) best = { quote: candidate, score };
+  // Pick the best-overlap candidate. Tiebreak equal own-overlap scores by a
+  // "context" score that includes the immediately PRECEDING candidate's text,
+  // so a repeated anaphoric line ("It launched in March") resolves to the
+  // occurrence whose neighbor names the fact's entity (issue #1633, codex
+  // PRRT_kwDORJXyws6Oce-S). Without this tiebreak the first occurrence wins
+  // even when the second is the one the fact refers to.
+  let best: { candidate: SourceCandidate; score: number; contextScore: number } | null = null;
+  for (let i = 0; i < candidates.length; i++) {
+    const candidate = candidates[i]!;
+    const score = overlapCoefficient(factTokens, tokenize(candidate.text));
+    const prevText = i > 0 ? candidates[i - 1]!.text : "";
+    const contextText = prevText ? `${prevText} ${candidate.text}` : candidate.text;
+    const contextScore = overlapCoefficient(factTokens, tokenize(contextText));
+    if (
+      !best ||
+      score > best.score ||
+      (score === best.score && contextScore > best.contextScore)
+    ) {
+      best = { candidate, score, contextScore };
+    }
   }
   if (!best || best.score < LOCATE_QUOTE_MIN_OVERLAP) return undefined;
-  return best.quote.length > maxQuoteChars
-    ? best.quote.slice(0, maxQuoteChars)
-    : best.quote;
+  const { text, start } = best.candidate;
+  if (text.length <= maxQuoteChars) {
+    return { quote: text, offset: start };
+  }
+  // Build a bounded window around the densest cluster of matched terms instead
+  // of returning the first maxQuoteChars prefix (issue #1633). Returning the
+  // prefix drops supporting words that fall after char ~600, routing
+  // actually-entailed facts to pending_review in enforce mode.
+  const matched = locateMatchedTokens(factTokens, text);
+  const win = boundedWindow(text, matched, maxQuoteChars);
+  return { quote: win.text, offset: start + win.start };
 }
 export async function runFaithfulnessGateBatch(
   facts: readonly FaithfulnessGateFact[],
@@ -793,11 +958,19 @@ export async function runFaithfulnessGateBatch(
       .map((s) => (s && typeof s.quote === "string" ? s.quote.trim() : ""))
       .filter((q) => q.length > 0);
     const usingFallbackLocator = sourceQuotes.length === 0;
-    const quote =
-      sourceQuotes.length > 0
-        ? sourceQuotes.join("\n")
-        : locateFactQuote(f.content, sourceText);
-    if (!quote) continue; // no located span — applyFaithfulnessVerdict tags skipped_no_span
+    let quote: string;
+    let matchedOffset: number | undefined;
+    if (sourceQuotes.length > 0) {
+      quote = sourceQuotes.join("\n");
+    } else {
+      // Fallback locator returns the matched span AND its offset so the
+      // context window centers on the occurrence that actually matched the
+      // fact, not the first indexOf hit (issue #1633).
+      const located = locateFactQuote(f.content, sourceText);
+      if (!located) continue; // no located span — applyFaithfulnessVerdict tags skipped_no_span
+      quote = located.quote;
+      matchedOffset = located.offset;
+    }
     // Pass source context into the verifier so extractionFaithfulnessContextChars
     // actually applies in the fallback-locator path (codex P2
     // PRRT_kwDORJXyws6OblI1). #1575 verified spans already carry full evidence,
@@ -808,6 +981,7 @@ export async function runFaithfulnessGateBatch(
             sourceText,
             quote,
             config.extractionFaithfulnessContextChars,
+            matchedOffset,
           )
         : undefined;
     inputs.push({

package/src/fallback-llm.test.ts

@@ -3,7 +3,7 @@ import path from "node:path";
 import test from "node:test";
 
 import { FallbackLlmClient, gatewayTaskChainOptions } from "./fallback-llm.js";
-import { __codexCliFallbackTestHooks } from "./codex-cli-fallback.js";
+import { __codexCliFallbackTestHooks } from "./cli-fallback.js";
 import { clearModelsJsonCache, __setModelsJsonForTest } from "./models-json.js";
 import {
   __setGatewayRuntimeAuthForModelForTest,