@remnic/core 9.69.32 → 9.69.34

package/src/recall-state-view-zero-diff.test.ts

@@ -156,10 +156,10 @@ function liveEntries(
   query: string,
   stateViewsEnabled: boolean,
 ): { entries: string[]; widened: { id?: string; stateLabel?: string }[] } {
-  // parseConfig intentionally does not carry `recallStateViews` (see
-  // recall-state-view-wire.ts: "parseConfig cannot grow"), so operators set it
-  // on the live config object. Setting it INSIDE parseConfig silently yields a
-  // disabled render, which makes a zero-diff assertion vacuous.
+  // parseConfig now carries `recallStateViews` (default false); the override
+  // below exercises the enabled path against the real parsed config, and the
+  // disabled path uses the parsed default — so a parse regression (flag
+  // silently ignored) makes the enabled assertions below fail.
   const parsed = parseConfig({ memoryDir: "/tmp/remnic-zero-diff-test" });
   const config = stateViewsEnabled
     ? ({ ...parsed, recallStateViews: true } as typeof parsed)
@@ -196,7 +196,7 @@ function linesFrom(
   }));
 }
 
-test("the enabled route labels an admitted superseded row; disabled leaves labels alone", () => {
+test("the enabled route labels a superseded row and renders the historical prefix", () => {
   const results = [
     { memoryId: "m-1", text: "we use PostgreSQL", stateLabel: "current" as const, score: 0.9 },
     {
@@ -224,12 +224,21 @@ test("the enabled route labels an admitted superseded row; disabled leaves label
     "current",
     "the disabled route must not touch labels",
   );
-  // NOTE: the live formatter renders no superseded prefix — formatSupersededPrefix
-  // is reachable only from renderStateViewLine, which has no production caller.
-  // So the rendered entries are identical here, and asserting a rendered
-  // annotation through this route would be asserting a feature that is not
-  // wired. That gap belongs to the rendering slice, not to this guard.
-  assert.deepEqual(enabled.entries, disabled.entries);
+  // Observable effect #2 (rendering slice): the enabled route prefixes the
+  // admitted superseded row with `[superseded <date> by <id>]`; the disabled
+  // render stays byte-identical (no prefix, same snippet).
+  const enabledOld = enabled.entries.find((entry) => entry.includes("we use SQLite"));
+  const disabledOld = disabled.entries.find((entry) => entry.includes("we use SQLite"));
+  assert.ok(enabledOld, "enabled render includes the superseded row");
+  assert.ok(disabledOld, "disabled render includes the (unlabeled) row");
+  assert.match(enabledOld!, /\[superseded 2026-08-01 by m-1\] we use SQLite/);
+  assert.doesNotMatch(disabledOld!, /\[superseded/);
+  // Current rows are untouched in both renders.
+  for (const entries of [enabled.entries, disabled.entries]) {
+    const current = entries.find((entry) => entry.includes("we use PostgreSQL"));
+    assert.ok(current);
+    assert.doesNotMatch(current!, /\[superseded/);
+  }
 });
 
 test("the enabled route drops a superseded row whose successor is absent", () => {

package/src/recall-state-view.test.ts

@@ -52,6 +52,96 @@ test("change-intent conjugations fire the annotator", () => {
   }
 });
 
+test("change-intent phrase matching uses token boundaries, not substrings", () => {
+  const positives = [
+    "When did we move offices?",
+    "we used to live in Austin",
+    "when  did   the vendor change",
+  ];
+  const negatives = [
+    "when Didi arrives", // proper noun must not fire "when did"
+    "I was confused to hear that", // "used to" inside "confused to"
+  ];
+  for (const query of positives) {
+    assert.equal(isChangeOrientedQuery(query), true, query);
+  }
+  for (const query of negatives) {
+    assert.equal(isChangeOrientedQuery(query), false, query);
+  }
+});
+
+test("bare before/after sequencing is not change intent; event-pointing is", () => {
+  const positives = [
+    "before the move",
+    "after the cutover",
+    "after a migration",
+    "before the migration",
+  ];
+  const negatives = [
+    "before lunch",
+    "after install",
+    "restart before dinner",
+    "shut down after setup",
+    "the aftermath report",
+  ];
+  for (const query of positives) {
+    assert.equal(isChangeOrientedQuery(query), true, query);
+  }
+  for (const query of negatives) {
+    assert.equal(isChangeOrientedQuery(query), false, query);
+  }
+});
+
+test("asOf mode keeps a predecessor whose successor the pin filtered out", () => {
+  const predecessor = fact("old-job", {
+    status: "superseded",
+    supersededBy: "new-job",
+    supersededAt: "2026-08-10T00:00:00.000Z",
+  });
+  const labeled = annotateStateView([predecessor], "when did the job title change", [], {
+    enabled: true,
+    asOfMs: Date.parse("2026-08-05T00:00:00.000Z"),
+  });
+  assert.equal(labeled.length, 1, "a valid asOf result must never be emptied");
+  assert.equal(
+    labeled[0]?.stateLabel,
+    "current",
+    "the pin predates the supersession, so the row was the live fact at the snapshot",
+  );
+});
+
+test("asOf mode labels a predecessor historical when the supersession predates the pin", () => {
+  const predecessor = fact("old-job", {
+    status: "superseded",
+    supersededBy: "new-job",
+    supersededAt: "2026-08-01T00:00:00.000Z",
+  });
+  const labeled = annotateStateView([predecessor], "when did the job title change", [], {
+    enabled: true,
+    asOfMs: Date.parse("2026-08-05T00:00:00.000Z"),
+  });
+  assert.equal(labeled.length, 1);
+  assert.equal(labeled[0]?.stateLabel, "historical");
+});
+
+test("asOf mode keeps pair semantics when both rows are valid at the pin", () => {
+  const rows = [
+    fact("new-job", { status: "active" }),
+    fact("old-job", { status: "superseded", supersededBy: "new-job", supersededAt: "2026-03-01" }),
+  ];
+  const labeled = annotateStateView(rows, "when did the job title change", [], {
+    enabled: true,
+    asOfMs: Date.parse("2026-08-05T00:00:00.000Z"),
+  });
+  assert.deepEqual(
+    labeled.map((row) => [row.id, row.stateLabel]),
+    [
+      ["new-job", "current"],
+      ["old-job", "historical"],
+    ],
+  );
+});
+
 test("non-change query is identical (same array reference, no labels)", () => {
   const input = PAIR_RESULTS.map((row) => ({ ...row }));
   const out = annotateStateView(input, "what is the current job title", PAIR, { enabled: true });
@@ -129,3 +219,55 @@ test("annotateStateView does not mutate input rows", () => {
   assert.equal(input[0]?.stateLabel, undefined);
   assert.equal(input[1]?.stateLabel, undefined);
 });
+
+test("disputed cycle never labels historical against a missing anchor", () => {
+  const results = [
+    fact("a", { status: "superseded", supersededBy: "b" }),
+    fact("b", { status: "superseded", supersededBy: "a" }),
+    fact("c", { status: "active" }),
+  ];
+  const labeled = annotateStateView(results, "when did this change", [], { enabled: true });
+  assert.deepEqual(
+    labeled.map((row) => [row.id, row.stateLabel]),
+    [
+      ["a", "transition"],
+      ["b", "transition"],
+      ["c", "current"],
+    ],
+    "cycle members may render as transitions, never historical-vs-current",
+  );
+});
+
+test("corrected row links through the chain when supersededBy is absent", () => {
+  const chains: StateViewChain[] = [
+    { predecessorId: "old", successorId: "new", supersededAt: "2026-02-01" },
+  ];
+  const results = [
+    fact("new", { status: "active" }),
+    fact("old", { status: "superseded", supersededAt: "2026-02-01" }),
+  ];
+  const labeled = annotateStateView(results, "before the correction what was it", chains, {
+    enabled: true,
+  });
+  assert.deepEqual(
+    labeled.map((row) => [row.id, row.stateLabel]),
+    [
+      ["new", "current"],
+      ["old", "historical"],
+    ],
+  );
+});
+
+test("transitive orphan chains collapse: A→B→(C absent) drops both A and B", () => {
+  const results = [
+    fact("a", { status: "superseded", supersededBy: "b" }),
+    fact("b", { status: "superseded", supersededBy: "c" }),
+    fact("unrelated", { status: "active" }),
+  ];
+  const labeled = annotateStateView(results, "when did this change", [], { enabled: true });
+  assert.deepEqual(
+    labeled.map((row) => row.id),
+    ["unrelated"],
+    "the fixpoint must drop A once B is dropped, not render a dangling historical",
+  );
+});

package/src/recall-state-view.ts

@@ -30,7 +30,17 @@ export interface StateViewResult {
 
 export const DEFAULT_RECALL_STATE_VIEWS = false;
 
-const CHANGE_WORDS = ["before", "after", "switch", "switches", "switched", "switching", "change", "changes", "changed", "changing"];
+const CHANGE_WORDS = ["switch", "switches", "switched", "switching", "change", "changes", "changed", "changing"];
+
+// Phrase matches are token-bounded: "when Didi" must not fire the
+// "when did" phrase, and "confused to" must not fire "used to".
+const CHANGE_PHRASE_RE = /\bwhen\s+did\b|\bused\s+to\b/;
+const CHANGE_WORD_RE = new RegExp(`\\b(?:${CHANGE_WORDS.join("|")})\\b`);
+// Bare "before"/"after" are ordinary sequencing ("before lunch",
+// "after install"). They carry change intent only when they point at a
+// specific event through a determiner ("before the move", "after the
+// cutover").
+const EVENT_POINTER_RE = /\b(?:before|after)\s+(?:the|a|an|this|that|these|those)\b/;
 
 export function parseRecallStateViews(raw: unknown): boolean {
   return coerceBooleanLike(raw, "recallStateViews") === true;
@@ -38,15 +48,7 @@ export function parseRecallStateViews(raw: unknown): boolean {
 
 export function isChangeOrientedQuery(query: string): boolean {
   const lower = query.toLowerCase();
-  if (lower.includes("when did") || lower.includes("used to")) return true;
-  return CHANGE_WORDS.some((word) => {
-    const idx = lower.indexOf(word);
-    if (idx < 0) return false;
-    const before = idx === 0 || !/[a-z0-9]/.test(lower[idx - 1] ?? "");
-    const afterIdx = idx + word.length;
-    const after = afterIdx >= lower.length || !/[a-z0-9]/.test(lower[afterIdx] ?? "");
-    return before && after;
-  });
+  return CHANGE_PHRASE_RE.test(lower) || CHANGE_WORD_RE.test(lower) || EVENT_POINTER_RE.test(lower);
 }
 
 export function shouldWidenSuperseded(
@@ -83,6 +85,7 @@ function labelFor(
   result: StateViewResult,
   byPred: Map<string, string>,
   admittedIds: ReadonlySet<string>,
+  asOfMs: number | null,
 ): StateLabel {
   const successorId = result.supersededBy ?? byPred.get(id);
   const isPred = shouldWidenSuperseded(successorId, admittedIds);
@@ -96,17 +99,39 @@ function labelFor(
   if (isPred && isSucc) return "transition";
   if (isPred) return "historical";
   if (isSucc) return "current";
-  return result.status === "superseded" ? "historical" : "current";
+  if (result.status === "superseded") {
+    // #1952 asOf mode: the successor is legitimately absent under the
+    // historical pin. The row was the live fact at the snapshot when the
+    // recorded supersession postdates the pin ("current" relative to
+    // the snapshot); already replaced at the pin is "historical".
+    return asOfMs === null ? "historical" : snapshotStateLabel(result, asOfMs);
+  }
+  return "current";
+}
+
+function snapshotStateLabel(result: StateViewResult, asOfMs: number): StateLabel {
+  const supersededAtMs = Date.parse(result.supersededAt ?? "");
+  return Number.isFinite(supersededAtMs) && supersededAtMs <= asOfMs
+    ? "historical"
+    : "current";
 }
 
 export function annotateStateView<T extends StateViewResult>(
   results: T[],
   query: string,
   chains: readonly StateViewChain[],
-  options: { enabled?: boolean } = {},
+  options: { enabled?: boolean; asOfMs?: number } = {},
 ): T[] {
   const enabled = options.enabled === true;
   if (!enabled || !isChangeOrientedQuery(query)) return results;
+  // #1952 asOf mode: under a historical pin the pipeline's isValidAsOf
+  // gate already decided validity at the pinned instant, so a predecessor
+  // must not be discarded merely because its successor is absent under
+  // the same filter. A valid asOf result is never emptied here.
+  const asOfMs =
+    typeof options.asOfMs === "number" && Number.isFinite(options.asOfMs)
+      ? options.asOfMs
+      : null;
 
   const byPred = buildSuccessorMap(results, chains);
   const candidateIds = new Set<string>();
@@ -115,24 +140,47 @@ export function annotateStateView<T extends StateViewResult>(
     if (id) candidateIds.add(id);
   }
 
-  const admitted: T[] = [];
-  for (const result of results) {
+  const isSupersededRow = (result: T): { superseded: boolean; successorId: string | undefined } => {
     const id = resultStateViewId(result);
-    const successorId = result.supersededBy ?? byPred.get(id);
-    const superseded = result.status === "superseded" || Boolean(result.supersededBy) || byPred.has(id);
-    if (!superseded || shouldWidenSuperseded(successorId, candidateIds)) {
-      admitted.push(result);
+    return {
+      superseded: result.status === "superseded" || Boolean(result.supersededBy) || byPred.has(id),
+      successorId: result.supersededBy ?? byPred.get(id),
+    };
+  };
+
+  let admitted: T[];
+  if (asOfMs !== null) {
+    admitted = results.slice();
+  } else {
+    admitted = [];
+    for (const result of results) {
+      const { superseded, successorId } = isSupersededRow(result);
+      if (!superseded || shouldWidenSuperseded(successorId, candidateIds)) {
+        admitted.push(result);
+      }
     }
-  }
 
-  const admittedIds = new Set<string>();
-  for (const result of admitted) {
-    const id = resultStateViewId(result);
-    if (id) admittedIds.add(id);
+    // #1952 contract: superseded never appears without its successor. A
+    // successor can itself be dropped (filtered elsewhere, or transitively
+    // orphaned), so reconcile to a fixpoint instead of trusting the first pass.
+    let admittedIds = new Set(admitted.map(resultStateViewId).filter(Boolean));
+    for (let changed = true; changed; ) {
+      changed = false;
+      for (let i = admitted.length - 1; i >= 0; i -= 1) {
+        const row = admitted[i]!;
+        const { superseded, successorId } = isSupersededRow(row);
+        if (superseded && !shouldWidenSuperseded(successorId, admittedIds)) {
+          admitted.splice(i, 1);
+          changed = true;
+        }
+      }
+      if (changed) admittedIds = new Set(admitted.map(resultStateViewId).filter(Boolean));
+    }
   }
 
+  const admittedIds = new Set(admitted.map(resultStateViewId).filter(Boolean));
   return admitted.map((result) => {
     const id = resultStateViewId(result);
-    return { ...result, stateLabel: labelFor(id, result, byPred, admittedIds) };
+    return { ...result, stateLabel: labelFor(id, result, byPred, admittedIds, asOfMs) };
   });
 }

package/src/recall-xray-renderer.test.ts

@@ -558,6 +558,33 @@ test("renderXrayText omits per-edge confidence line when graphEdgeConfidences ab
   assert.ok(!out.includes("edge-confidences:"));
 });
 
+// ─── Issue #1952 — state-view text rendering ──────────────────────────────
+
+test("renderXrayText renders the state-view line exactly once per result", () => {
+  const snap: RecallXraySnapshot = {
+    ...minimalSnapshot(),
+    results: [
+      {
+        memoryId: "mem-current",
+        path: "facts/job.md",
+        servedBy: "hybrid",
+        scoreDecomposition: { final: 0.9 },
+        admittedBy: [],
+        stateView: "current",
+        pathPenaltyApplied: false,
+      },
+    ],
+  };
+  const out = renderXrayText(snap);
+  const count = out.split("state-view:").length - 1;
+  assert.equal(
+    count,
+    1,
+    `state-view must render once per result (stable location after path), got ${count}:\n${out}`,
+  );
+  assert.ok(out.includes("state-view: current"));
+});
+
 test("renderXrayText tier-explain block matches shared helper output", async () => {
   // CLAUDE.md rule 22: the tier-explain text block must be a single
   // source of truth shared between recall-explain-renderer and

package/src/recall-xray-renderer.ts

@@ -152,6 +152,7 @@ function renderResultTextLines(
   const lines: string[] = [];
   lines.push(`[${rank}] ${result.memoryId} — ${servedByLabel(result.servedBy)}`);
   if (result.path) lines.push(`    path: ${result.path}`);
+  if (result.stateView) lines.push(`    state-view: ${result.stateView}`);
   lines.push(`    score: ${renderScoreDecomposition(result)}`);
   if (result.provenance) {
     lines.push(
@@ -397,6 +398,9 @@ function renderResultMarkdownLines(
       `- **Admitted by:** ${result.admittedBy.map(mdInlineCode).join(", ")}`,
     );
   }
+  if (result.stateView) {
+    lines.push(`- **State view:** ${mdInlineCode(result.stateView)}`);
+  }
   if (result.rejectedBy) {
     lines.push(`- **Rejected by:** ${mdInlineCode(result.rejectedBy)}`);
   }

package/src/recall-xray.ts

@@ -22,6 +22,7 @@ import { randomUUID } from "node:crypto";
 import { normalizeRetrievedMemoryProvenance, type RetrievedMemoryProvenance } from "./memory-provenance.js";
 import { estimateTokenCount } from "./token-estimate.js";
 import type { RecallDisclosure, RecallTierExplain } from "./types.js";
+import type { StateLabel } from "./recall-state-view.js";
 import { isRecallDisclosure } from "./types.js";
 
 /**
@@ -196,6 +197,13 @@ export interface RecallXrayResult {
     quarantined: boolean;
     quarantineReason?: string;
   };
+  /**
+   * #1952 — recall state-view label for this result (`current`,
+   * `historical`, or `transition`). Present only when state views were
+   * active for the recall AND the result was annotated at the inject
+   * seam; absent otherwise, so legacy snapshots round-trip unchanged.
+   */
+  stateView?: StateLabel;
 }
 
 /**
@@ -522,6 +530,10 @@ function cloneResult(result: RecallXrayResult): RecallXrayResult {
     typeof result.pathPenaltyApplied === "boolean"
       ? result.pathPenaltyApplied
       : undefined;
+  const stateView =
+    result.stateView === "current" || result.stateView === "historical" || result.stateView === "transition"
+      ? result.stateView
+      : undefined;
   const auditEntryId = nonEmptyString(result.auditEntryId);
   const rejectedBy = nonEmptyString(result.rejectedBy);
   const scoreDecomposition = cloneScoreDecomposition(result.scoreDecomposition);
@@ -538,6 +550,7 @@ function cloneResult(result: RecallXrayResult): RecallXrayResult {
   }
   if (pathNodeIds !== undefined) out.pathNodeIds = pathNodeIds;
   if (pathPenaltyApplied !== undefined) out.pathPenaltyApplied = pathPenaltyApplied;
+  if (stateView !== undefined) out.stateView = stateView;
   if (auditEntryId !== undefined) out.auditEntryId = auditEntryId;
   if (rejectedBy !== undefined) out.rejectedBy = rejectedBy;
   // Disclosure + token telemetry (issue #677 PR 3/4).  Only attach when

package/src/reconcile/cursor.ts

@@ -1,11 +1,7 @@
 import { createHash, randomUUID } from "node:crypto";
 import * as fs from "node:fs/promises";
 import * as path from "node:path";
-import {
-  type ReconcilePlanEntry,
-  type ReconcileSemanticAgreement,
-  semanticAgreementKey,
-} from "./plan.js";
+import { type ReconcilePlanEntry, type ReconcileSemanticAgreement, semanticAgreementKey } from "./plan.js";
 
 export type ConvergeRefreshTarget = "local" | "receiver";
 
@@ -56,21 +52,26 @@ export function normalizeConvergePeerUrl(peerUrl: string): string {
 export function hashPeerNamespace(peerUrl: string, namespace: string): string {
   const normalizedUrl = normalizeConvergePeerUrl(peerUrl);
   const normalizedNs = namespace.trim().toLowerCase();
-  return createHash("sha256")
-    .update(`${normalizedUrl}\0${normalizedNs}`)
-    .digest("hex")
-    .slice(0, 16);
+  return createHash("sha256").update(`${normalizedUrl}\0${normalizedNs}`).digest("hex").slice(0, 16);
 }
 
-export function defaultConvergeCursorPath(
-  memoryDir: string,
-  peerUrl: string,
-  namespace: string,
-): string {
+export function defaultConvergeCursorPath(memoryDir: string, peerUrl: string, namespace: string): string {
   const key = hashPeerNamespace(peerUrl, namespace);
   return path.join(path.resolve(memoryDir), ".remnic", "state", "converge-cursors", `${key}.json`);
 }
 
+/**
+ * Persistent identity cache location for a (peerUrl, namespace) pair, next
+ * to the cursor that governs the same pair. The cache stores the parsed
+ * memory identity per path keyed by content sha, so a warm manifest build
+ * skips the per-file read + frontmatter parse + content-hash identity work
+ * entirely (the dominant boot-scale plan cost on both sides).
+ */
+export function convergeIdentityCachePath(memoryDir: string, peerUrl: string, namespace: string): string {
+  const key = hashPeerNamespace(peerUrl, namespace);
+  return path.join(path.resolve(memoryDir), ".remnic", "state", "converge-identity", `identity-${key}.json`);
+}
+
 function normalizeSemanticFileState(input: unknown): { path: string; sha256: string } | undefined {
   if (!input || typeof input !== "object" || Array.isArray(input)) return undefined;
   const file = input as Record<string, unknown>;
@@ -94,7 +95,7 @@ function digestAfterReconcile(entry: ReconcilePlanEntry): string | undefined {
 export function deriveConvergeCursorBase(
   entries: readonly ReconcilePlanEntry[],
   namespace: string,
-  priorSemanticAgreements: readonly ReconcileSemanticAgreement[] = [],
+  priorSemanticAgreements: readonly ReconcileSemanticAgreement[] = []
 ): Pick<ConvergeCursorState, "baseFiles" | "semanticAgreements"> {
   const baseFiles: ConvergeCursorFileState[] = [];
   const semanticAgreementsByPathPair = new Map(
@@ -111,8 +112,8 @@ export function deriveConvergeCursorBase(
   }
   baseFiles.sort((left, right) => left.path.localeCompare(right.path));
   const semanticAgreements = [...semanticAgreementsByPathPair.values()];
-  semanticAgreements.sort((left, right) =>
-    left.local.path.localeCompare(right.local.path) || left.peer.path.localeCompare(right.peer.path)
+  semanticAgreements.sort(
+    (left, right) => left.local.path.localeCompare(right.local.path) || left.peer.path.localeCompare(right.peer.path)
   );
   return { baseFiles, semanticAgreements };
 }
@@ -182,9 +183,7 @@ export function normalizeConvergeCursor(input: unknown): ConvergeCursorState {
   };
 }
 
-export async function readConvergeCursor(
-  cursorPath: string,
-): Promise<ConvergeCursorState | null> {
+export async function readConvergeCursor(cursorPath: string): Promise<ConvergeCursorState | null> {
   try {
     const raw = await fs.readFile(path.resolve(cursorPath), "utf-8");
     const parsed = JSON.parse(raw);
@@ -195,17 +194,11 @@ export async function readConvergeCursor(
   }
 }
 
-export async function writeConvergeCursor(
-  cursorPath: string,
-  cursor: ConvergeCursorState,
-): Promise<void> {
+export async function writeConvergeCursor(cursorPath: string, cursor: ConvergeCursorState): Promise<void> {
   const normalized = normalizeConvergeCursor(cursor);
   const target = path.resolve(cursorPath);
   await fs.mkdir(path.dirname(target), { recursive: true });
-  const tmp = path.join(
-    path.dirname(target),
-    `.converge-cursor.${process.pid}.${randomUUID()}.tmp`,
-  );
+  const tmp = path.join(path.dirname(target), `.converge-cursor.${process.pid}.${randomUUID()}.tmp`);
   await fs.writeFile(tmp, JSON.stringify(normalized, null, 2) + "\n", "utf-8");
   try {
     await fs.rename(tmp, target);
@@ -221,7 +214,7 @@ export async function markConvergeRefreshPending(
     peerUrl: string;
     namespace: string;
     target: ConvergeRefreshTarget;
-  },
+  }
 ): Promise<void> {
   const current = await readConvergeCursor(cursorPath);
   const pendingRefreshes = new Set(current?.pendingRefreshes ?? []);
@@ -238,10 +231,7 @@ export async function markConvergeRefreshPending(
   });
 }
 
-export async function clearConvergeRefreshPending(
-  cursorPath: string,
-  target: ConvergeRefreshTarget,
-): Promise<void> {
+export async function clearConvergeRefreshPending(cursorPath: string, target: ConvergeRefreshTarget): Promise<void> {
   const current = await readConvergeCursor(cursorPath);
   if (!current?.pendingRefreshes?.includes(target)) return;
   await writeConvergeCursor(cursorPath, {