@remnic/core 9.3.697 → 9.3.699

package/src/access-service.ts

@@ -4665,9 +4665,26 @@ export class EngramAccessService {
         // non-default namespaces route to memoryDir/namespaces/<token>, so
         // session-delta markers must read/write from the routed tree, mirroring
         // the decision/architecture siblings (cursor review).
+        // Issue #1630 fix 2: gate the marker write on the WRITE-path resolver
+        // — it mirrors memory_store's exact authorization (base ACL for coding
+        // overlays, selectedLayer.writable for scope-profiles), not the raw
+        // canWriteNamespace which misses overlay/profile grants (cursor+codex
+        // review). A throw = read-only caller; delta computed but no advance.
+        let canAdvanceState = false;
+        try {
+          await this.resolveCodingScopedWriteNamespace({
+            namespace: req.namespace,
+            sessionKey: req.sessionKey,
+            authenticatedPrincipal,
+          });
+          canAdvanceState = true;
+        } catch {
+          canAdvanceState = false;
+        }
         return {
           memoryDir: storage.dir,
           namespace: ns,
+          canAdvanceState,
         } satisfies DeltaSurfaceStorage;
       },
       gitInvoker: (cwd, args) => {

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

@@ -81,9 +81,10 @@ function makeContext(overrides: Partial<DeltaSurfaceContext> = {}): DeltaSurface
 // shimming its filesystem. The handler imports readLastSeenState / writeLastSeenState
 // from ./session-delta.js, which hit the real fs. We point memoryDir at a
 // temp dir per-test.
-import { mkdtemp, rm } from "node:fs/promises";
+import { mkdtemp, rm, readFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import path from "node:path";
+import { sessionDeltaStatePath } from "./session-delta.js";
 
 async function makeTempStorage(): Promise<{ storage: DeltaSurfaceStorage; cleanup: () => Promise<void> }> {
   const dir = await mkdtemp(path.join(tmpdir(), "delta-surface-"));
@@ -383,3 +384,186 @@ test("handler/get: state file is created after a successful first_run", async ()
     await cleanup();
   }
 });
+
+// ──────────────────────────────────────────────────────────────────────────
+// Issue #1630 fix 1 — uncapped totals surface in the changed response
+// ──────────────────────────────────────────────────────────────────────────
+
+test("handler/get: changed response surfaces uncapped totals alongside capped slices (issue #1630 fix 1)", async () => {
+  const { storage, cleanup } = await makeTempStorage();
+  try {
+    // Seed: first run on headA.
+    const invoker1 = makeInvoker([
+      { args: ["rev-parse", "HEAD"], stdout: "headA\n" },
+    ]);
+    await handleCodingDelta(
+      { subcommand: "get", sessionKey: "s1" },
+      makeContext({ resolveStorage: async () => storage, gitInvoker: invoker1 }),
+    );
+
+    // Now head moved to headB with 25 commits / 60 files — both exceed the
+    // caps (MAX_DELTA_COMMITS=20, MAX_DELTA_FILES=50).
+    const sep = "\x1f";
+    const commitBlocks = Array.from({ length: 25 }, (_, i) => [
+      `sha${i}${sep}fix ${i}`,
+      "",
+      `src/file${i}.ts`,
+      "",
+    ].join("\n"));
+    // Add 35 more distinct files so the total crosses the file cap.
+    const extraFiles = Array.from({ length: 35 }, (_, i) => `extra${i}.ts`);
+    const lastBlock = [
+      `shaExtra${sep}extra`,
+      "",
+      ...extraFiles,
+      "",
+    ].join("\n");
+    const log = [...commitBlocks, lastBlock].join("\n");
+    const invoker2 = makeInvoker([
+      { args: ["rev-parse", "HEAD"], stdout: "headB\n" },
+      { args: ["log", "--reverse", "--pretty=format:%H\x1f%s", "--name-only", "headA..headB"], stdout: log },
+    ]);
+    const result = await handleCodingDelta(
+      { subcommand: "get", sessionKey: "s1" },
+      makeContext({ resolveStorage: async () => storage, gitInvoker: invoker2 }),
+    );
+    if (!("ok" in result) || !result.ok || result.kind !== "changed") {
+      assert.fail(`expected changed, got ${JSON.stringify(result)}`);
+      return;
+    }
+    // Capped display slices.
+    assert.equal(result.delta.commits.length, 20, "commits slice must be capped to MAX_DELTA_COMMITS");
+    assert.equal(result.delta.touchedFiles.length, 50, "touchedFiles slice must be capped to MAX_DELTA_FILES");
+    // Uncapped totals — the TRUE delta size, NOT the capped length.
+    assert.equal(result.delta.totalCommits, 26, "totalCommits must report the uncapped commit count");
+    assert.ok(
+      result.delta.totalTouchedFiles > 50,
+      `totalTouchedFiles must report the uncapped file count (got ${result.delta.totalTouchedFiles})`,
+    );
+  } finally {
+    await cleanup();
+  }
+});
+
+// ──────────────────────────────────────────────────────────────────────────
+// Issue #1630 fix 2 — read-only callers do NOT advance the state marker
+// ──────────────────────────────────────────────────────────────────────────
+
+test("handler/get: read-only caller (canAdvanceState=false) does NOT advance the state marker (issue #1630 fix 2)", async () => {
+  const { storage, cleanup } = await makeTempStorage();
+  try {
+    // Seed headA with a WRITE-capable caller (default canAdvanceState=true).
+    const invoker1 = makeInvoker([
+      { args: ["rev-parse", "HEAD"], stdout: "headA\n" },
+    ]);
+    await handleCodingDelta(
+      { subcommand: "get", sessionKey: "s1" },
+      makeContext({
+        resolveStorage: async () => ({ ...storage, canAdvanceState: true }),
+        gitInvoker: invoker1,
+      }),
+    );
+    // Confirm the marker landed at headA.
+    const statePath = sessionDeltaStatePath(storage.memoryDir, storage.namespace);
+    const seeded = JSON.parse(await readFile(statePath, "utf8"));
+    assert.equal(seeded.head, "headA");
+
+    // A READ-ONLY caller (canAdvanceState=false) on headB. The delta is
+    // computed and returned, but the marker MUST NOT advance.
+    const sep = "\x1f";
+    const log = [
+      `shaRO${sep}read only commit`,
+      "",
+      "src/ro.ts",
+      "",
+    ].join("\n");
+    const invoker2 = makeInvoker([
+      { args: ["rev-parse", "HEAD"], stdout: "headB\n" },
+      { args: ["log", "--reverse", "--pretty=format:%H\x1f%s", "--name-only", "headA..headB"], stdout: log },
+    ]);
+    const result = await handleCodingDelta(
+      { subcommand: "get", sessionKey: "s1" },
+      makeContext({
+        resolveStorage: async () => ({ ...storage, canAdvanceState: false }),
+        gitInvoker: invoker2,
+      }),
+    );
+    // The delta is still computed and returned — read-only callers see the data.
+    if (!("ok" in result) || !result.ok || result.kind !== "changed") {
+      assert.fail(`expected changed, got ${JSON.stringify(result)}`);
+      return;
+    }
+    assert.equal(result.delta.commits.length, 1);
+    // But the persisted marker stayed at headA — read-only did not advance it.
+    const persisted = JSON.parse(await readFile(statePath, "utf8"));
+    assert.equal(persisted.head, "headA", "read-only caller must NOT advance the state marker");
+  } finally {
+    await cleanup();
+  }
+});
+
+test("handler/get: write-capable caller (canAdvanceState=true) DOES advance the state marker (issue #1630 fix 2)", async () => {
+  const { storage, cleanup } = await makeTempStorage();
+  try {
+    // Seed headA.
+    const invoker1 = makeInvoker([
+      { args: ["rev-parse", "HEAD"], stdout: "headA\n" },
+    ]);
+    await handleCodingDelta(
+      { subcommand: "get", sessionKey: "s1" },
+      makeContext({
+        resolveStorage: async () => ({ ...storage, canAdvanceState: true }),
+        gitInvoker: invoker1,
+      }),
+    );
+
+    // A WRITE-capable caller on headB — the marker MUST advance.
+    const sep = "\x1f";
+    const log = [
+      `shaW${sep}write commit`,
+      "",
+      "src/w.ts",
+      "",
+    ].join("\n");
+    const invoker2 = makeInvoker([
+      { args: ["rev-parse", "HEAD"], stdout: "headB\n" },
+      { args: ["log", "--reverse", "--pretty=format:%H\x1f%s", "--name-only", "headA..headB"], stdout: log },
+    ]);
+    await handleCodingDelta(
+      { subcommand: "get", sessionKey: "s1" },
+      makeContext({
+        resolveStorage: async () => ({ ...storage, canAdvanceState: true }),
+        gitInvoker: invoker2,
+      }),
+    );
+    const statePath = sessionDeltaStatePath(storage.memoryDir, storage.namespace);
+    const persisted = JSON.parse(await readFile(statePath, "utf8"));
+    assert.equal(persisted.head, "headB", "write-capable caller must advance the state marker");
+  } finally {
+    await cleanup();
+  }
+});
+
+test("handler/get: canAdvanceState defaults to true when omitted (back-compat) (issue #1630 fix 2)", async () => {
+  // Legacy callers that don't set canAdvanceState keep pre-fix behavior:
+  // the marker advances. This protects the existing surface contract.
+  const { storage, cleanup } = await makeTempStorage();
+  try {
+    const invoker = makeInvoker([
+      { args: ["rev-parse", "HEAD"], stdout: "headDefault\n" },
+    ]);
+    await handleCodingDelta(
+      { subcommand: "get", sessionKey: "s1" },
+      makeContext({
+        // canAdvanceState intentionally omitted.
+        resolveStorage: async () => storage,
+        gitInvoker: invoker,
+      }),
+    );
+    const statePath = sessionDeltaStatePath(storage.memoryDir, storage.namespace);
+    const persisted = JSON.parse(await readFile(statePath, "utf8"));
+    assert.equal(persisted.head, "headDefault", "omitted canAdvanceState defaults to true (back-compat)");
+  } finally {
+    await cleanup();
+  }
+});

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/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