@herbertgao/pi-extensions 2026.8.11 → 2026.8.13

package/node_modules/@luxusai/pi-hindsight/extensions/lifecycle/recall.ts

@@ -0,0 +1,331 @@
+import { basename } from "node:path";
+import type { AgentMessage } from "@earendil-works/pi-agent-core";
+import {
+  RECALL_SCORE_FIELDS,
+  type HindsightLikeClient,
+  type HindsightTagGroup,
+  type RecallBlock,
+  type RecallFailure,
+  type RecallMinScores,
+  type RecallResultItem,
+  type RecallRole,
+  type ResolvedConfig,
+} from "../types.js";
+import { isInjectedHindsightMemory, projectMessageText } from "../utils/messages.js";
+import { createMemoryIdentity } from "../operations/memory-identity.js";
+import { redactError } from "../utils/sanitize.js";
+import { withTimeout } from "../client/timeout.js";
+import { loadMentalModelsForScopes } from "./mental-models.js";
+
+export interface RecallScope {
+  kind?: "project" | "global";
+  bankId: string;
+  tagGroups?: HindsightTagGroup[];
+}
+
+function sourceFactText(value: unknown): string | undefined {
+  if (!value || typeof value !== "object") return undefined;
+  const text = (value as { text?: unknown }).text;
+  return typeof text === "string" && text.trim() ? text : undefined;
+}
+
+function textFromRecallResponse(response: unknown): RecallResultItem[] {
+  const record = response as Record<string, unknown>;
+  const raw = Array.isArray(record.results)
+    ? record.results
+    : Array.isArray(record.memories)
+      ? record.memories
+      : Array.isArray(response)
+        ? response
+        : [];
+  const sourceFacts =
+    record.source_facts && typeof record.source_facts === "object"
+      ? (record.source_facts as Record<string, unknown>)
+      : undefined;
+  return raw.map((entry) => {
+    const item = entry as RecallResultItem;
+    if (!sourceFacts || !item.source_fact_ids?.length) return item;
+    const evidence = item.source_fact_ids
+      .map((id) => sourceFactText(sourceFacts[id]))
+      .filter((text): text is string => Boolean(text));
+    return evidence.length ? { ...item, sourceFacts: evidence } : item;
+  });
+}
+
+function itemText(item: RecallResultItem): string {
+  return item.text ?? item.content ?? JSON.stringify(item);
+}
+
+export interface RecallQueryPolicy {
+  roles: RecallRole[];
+  contextTurns: number;
+  maxQueryChars: number;
+  preamble?: string;
+  includeDate?: boolean;
+  now?: Date;
+  hints?: string[];
+}
+
+function messageRole(message: AgentMessage): string {
+  return (message as unknown as { role?: string }).role ?? "unknown";
+}
+
+function messageContent(message: AgentMessage): string {
+  const content = projectMessageText(message).content;
+  return typeof content === "string" ? content : JSON.stringify(content ?? "");
+}
+
+function formatQueryMessage(message: AgentMessage): string | undefined {
+  const content = messageContent(message).trim();
+  return content ? `${messageRole(message)}: ${content}` : undefined;
+}
+
+export function truncateRecallQuery(query: string, maxChars: number): string {
+  if (query.length <= maxChars) return query;
+  return query.slice(query.length - maxChars).trimStart();
+}
+
+function truncateRecallQueryLines(
+  prefixLines: string[],
+  messageLines: string[],
+  maxChars: number,
+): string {
+  const lines = [...prefixLines, ...messageLines];
+  const query = lines.join("\n\n").trim();
+  if (query.length <= maxChars) return query;
+  const prefix = prefixLines.join("\n\n").trim();
+  if (!prefix) return truncateRecallQuery(query, maxChars);
+  const separator = "\n\n";
+  const remaining = maxChars - prefix.length - separator.length;
+  if (remaining >= 20)
+    return `${prefix}${separator}${truncateRecallQuery(messageLines.join("\n\n"), remaining)}`;
+  return truncateRecallQuery(query, maxChars);
+}
+
+export function composeRecallQuery(messages: AgentMessage[], policy: RecallQueryPolicy): string {
+  const allowedRoles = new Set<string>(policy.roles);
+  const selectedLines = messages
+    .filter((message) => allowedRoles.has(messageRole(message)))
+    .filter((message) => !isInjectedHindsightMemory(message))
+    .map(formatQueryMessage)
+    .filter((line): line is string => Boolean(line))
+    .slice(-Math.max(1, policy.contextTurns));
+  const prefixLines = [
+    ...(policy.preamble?.trim() ? [policy.preamble.trim()] : []),
+    ...(policy.includeDate
+      ? [`Current date: ${(policy.now ?? new Date()).toISOString().slice(0, 10)}`]
+      : []),
+    ...(policy.hints?.length ? [`Context hints: ${policy.hints.join("; ")}`] : []),
+  ];
+  return truncateRecallQueryLines(
+    prefixLines,
+    selectedLines.length ? selectedLines : ["current Pi coding task"],
+    policy.maxQueryChars,
+  );
+}
+
+const RECALL_SOURCE_FACT_LINES = 3;
+
+export function renderRecallBlocks(blocks: RecallBlock[], topK = 12): string {
+  const nonEmpty = blocks.filter((block) => block.memoryCount > 0);
+  if (nonEmpty.length === 0) return "";
+  const lines = [
+    "<hindsight-memory>",
+    "Relevant prior memory. Use as context; do not quote unless useful.",
+  ];
+  for (const block of nonEmpty) {
+    lines.push(`\nBank: ${block.bankId}`);
+    block.results.slice(0, topK).forEach((item, index) => {
+      const tags = item.tags?.length ? ` [${item.tags.join(", ")}]` : "";
+      lines.push(`${index + 1}. ${itemText(item)}${tags}`);
+      for (const fact of (item.sourceFacts ?? []).slice(0, RECALL_SOURCE_FACT_LINES)) {
+        lines.push(`   - evidence: ${fact}`);
+      }
+    });
+  }
+  lines.push("</hindsight-memory>");
+  return lines.join("\n");
+}
+
+function preambleForScope(config: ResolvedConfig, scope: RecallScope): string {
+  if (scope.kind === "project") return config.recall.projectQueryPreamble;
+  if (scope.kind === "global") return config.recall.globalQueryPreamble;
+  return config.recall.queryPreamble;
+}
+
+// User Bank recall is a smaller, durable supplement to project context, not an equal-weight
+// second corpus, so it gets its own (smaller by default) token budget. Project Bank recall
+// keeps recall.maxTokens unchanged so single-scope callers see no behavior change.
+function maxTokensForScope(config: ResolvedConfig, scope: RecallScope): number {
+  return scope.kind === "global" ? config.recall.userMaxTokens : config.recall.maxTokens;
+}
+
+function queryHints(cwd: string, config: ResolvedConfig, scope: RecallScope): string[] {
+  const hints = scope.kind ? [`scope:${scope.kind}`] : [];
+  if (!config.recall.includeRepoHintsInQuery || scope.kind === "global") return hints;
+  const identity = createMemoryIdentity(cwd, config);
+  return [
+    ...hints,
+    `project:${identity.projectId}`,
+    `repo:${identity.repoKey}`,
+    `cwd:${basename(cwd)}`,
+  ];
+}
+
+export async function recallForContext(args: {
+  client: HindsightLikeClient;
+  config: ResolvedConfig;
+  scopes: RecallScope[];
+  messages: AgentMessage[];
+  cwd?: string;
+}): Promise<{
+  rendered: string;
+  blocks: RecallBlock[];
+  failed: number;
+  failures: RecallFailure[];
+}> {
+  const blocks: RecallBlock[] = [];
+  const failures: RecallFailure[] = [];
+  for (const scope of args.scopes) {
+    const query = composeRecallQuery(args.messages, {
+      roles: args.config.recall.roles,
+      contextTurns: args.config.recall.contextTurns,
+      maxQueryChars: args.config.recall.maxQueryChars,
+      preamble: preambleForScope(args.config, scope),
+      includeDate: args.config.recall.includeDateInQuery,
+      hints: args.cwd ? queryHints(args.cwd, args.config, scope) : [],
+    });
+    try {
+      const response = await withTimeout("hindsight recall", args.config.recall.timeoutMs, () =>
+        args.client.recall(scope.bankId, query, {
+          budget: args.config.recall.budget,
+          maxTokens: maxTokensForScope(args.config, scope),
+          types: args.config.recall.types,
+          preferObservations: args.config.recall.preferObservations,
+          ...(args.config.recall.includeSourceFacts
+            ? {
+                includeSourceFacts: true,
+                maxSourceFactsTokens: args.config.recall.maxSourceFactsTokens,
+              }
+            : {}),
+          ...(args.config.recall.queryTimestamp
+            ? { queryTimestamp: args.config.recall.queryTimestamp }
+            : {}),
+          ...(scope.tagGroups?.length ? { tagGroups: scope.tagGroups } : {}),
+        }),
+      );
+      const results = filterRecallQuality(
+        textFromRecallResponse(response),
+        args.config.recall.minScores,
+      ).items;
+      blocks.push({
+        bankId: scope.bankId,
+        query,
+        results,
+        memoryCount: results.length,
+        rendered: "",
+      });
+    } catch (error) {
+      failures.push({
+        bankId: scope.bankId,
+        query,
+        error: redactError(error),
+        ...(scope.kind ? { kind: scope.kind } : {}),
+        ...(scope.tagGroups?.length ? { tagGroups: scope.tagGroups } : {}),
+      });
+    }
+  }
+  const recallRendered = renderRecallBlocks(blocks, args.config.recall.topK);
+  const cwd = args.cwd ?? process.cwd();
+  const identity = createMemoryIdentity(cwd, args.config);
+  const mental = await loadMentalModelsForScopes({
+    client: args.client,
+    config: args.config,
+    bankIds: args.scopes.map((scope) => scope.bankId),
+    bankKinds: args.scopes.map((scope) => (scope.kind === "global" ? "user" : "project")),
+    projectId: identity.projectId,
+  });
+  const rendered = [mental.rendered, recallRendered].filter(Boolean).join("\n\n");
+  return {
+    rendered,
+    blocks: blocks.map((block) => ({ ...block, rendered: recallRendered })),
+    failed: failures.length,
+    failures,
+  };
+}
+
+export type RecallQualityDropReason =
+  | "blank-memory"
+  | "recall-contamination"
+  | "duplicate-memory"
+  | "below-score-floor";
+
+export interface RecallQualityDecision {
+  item: RecallResultItem;
+  decision: "keep" | "drop";
+  reasons: RecallQualityDropReason[];
+}
+
+function normalizedMemoryText(item: RecallResultItem): string {
+  return itemText(item).replace(/\s+/g, " ").trim().toLowerCase();
+}
+
+function isRecallContamination(text: string): boolean {
+  return /<\/?hindsight[-_]memor(?:y|ies)>|<\/?hindsight-mental-models>|<\/?mental_models>|customType["']?\s*:\s*["']hindsight-(?:recall|mental-models)|last-recall\.json/.test(
+    text,
+  );
+}
+
+function isBelowScoreFloor(item: RecallResultItem, minScores?: RecallMinScores): boolean {
+  if (!minScores) return false;
+  const scores = item.scores;
+  // Fail open when Hindsight omits scores so BM25-only hits and passthrough rerankers
+  // are not silently discarded by local policy.
+  if (!scores) return false;
+  for (const field of RECALL_SCORE_FIELDS) {
+    const floor = minScores[field];
+    const value = scores[field];
+    if (typeof floor === "number" && typeof value === "number" && value < floor) return true;
+  }
+  return false;
+}
+
+export function classifyRecallQuality(
+  item: RecallResultItem,
+  seen: Set<string>,
+  minScores?: RecallMinScores,
+): RecallQualityDecision {
+  const text = normalizedMemoryText(item);
+  const reasons: RecallQualityDropReason[] = [];
+  if (!text) reasons.push("blank-memory");
+  if (isRecallContamination(itemText(item))) reasons.push("recall-contamination");
+  if (text && seen.has(text)) reasons.push("duplicate-memory");
+  if (isBelowScoreFloor(item, minScores)) reasons.push("below-score-floor");
+  if (!reasons.length) seen.add(text);
+  return { item, decision: reasons.length ? "drop" : "keep", reasons };
+}
+
+export function filterRecallQuality(
+  items: RecallResultItem[],
+  minScores?: RecallMinScores,
+): {
+  items: RecallResultItem[];
+  decisions: RecallQualityDecision[];
+  dropped: number;
+  reasonCounts: Partial<Record<RecallQualityDropReason, number>>;
+} {
+  const seen = new Set<string>();
+  const decisions = items.map((item) => classifyRecallQuality(item, seen, minScores));
+  const reasonCounts: Partial<Record<RecallQualityDropReason, number>> = {};
+  for (const decision of decisions) {
+    for (const reason of decision.reasons) reasonCounts[reason] = (reasonCounts[reason] ?? 0) + 1;
+  }
+  return {
+    items: decisions
+      .filter((decision) => decision.decision === "keep")
+      .map((decision) => decision.item),
+    decisions,
+    dropped: decisions.filter((decision) => decision.decision === "drop").length,
+    reasonCounts,
+  };
+}

package/node_modules/@luxusai/pi-hindsight/extensions/lifecycle/retain-cursor.ts

@@ -0,0 +1,354 @@
+import { createHash } from "node:crypto";
+import { mkdir, readFile, rename, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import type { AgentMessage } from "@earendil-works/pi-agent-core";
+
+export const RETAIN_CURSOR_VERSION = 3 as const;
+export const RETAIN_CURSOR_TAIL_WINDOW = 200;
+
+export interface SessionRetainCursor {
+  index: number;
+  chainHash: string;
+  idChainHash: string;
+  tailStart: number;
+  messageIds: string[];
+  fingerprints: string[];
+}
+
+export interface SessionRetainState {
+  cursor?: SessionRetainCursor;
+  legacyFingerprints?: Set<string>;
+}
+
+interface RetainCursorStoreV3 {
+  version: typeof RETAIN_CURSOR_VERSION;
+  sessions: Record<string, SessionRetainCursor | LegacySessionEntry>;
+}
+
+interface LegacySessionEntry {
+  legacyFingerprints: string[];
+}
+
+type RetainCursorStoreV1 = {
+  sessions: Record<string, string[]>;
+};
+
+interface SessionRetainCursorV2 {
+  index: number;
+  chainHash: string;
+  idChainHash: string;
+  messageIds: string[];
+  fingerprints: string[];
+}
+
+export function retainCursorPath(cwd: string): string {
+  return join(cwd, ".pi", "hindsight", "retain-cursors.json");
+}
+
+export function messageFingerprint(message: AgentMessage): string {
+  const m = message as unknown as Record<string, unknown>;
+  const stable = {
+    id: m.id,
+    role: m.role,
+    timestamp: m.timestamp,
+    content: m.content,
+    toolName: m.toolName,
+    isError: m.isError,
+    model: m.model,
+    stopReason: m.stopReason,
+  };
+  return createHash("sha256").update(JSON.stringify(stable)).digest("hex");
+}
+
+function messageId(message: AgentMessage): string {
+  const id = (message as unknown as Record<string, unknown>).id;
+  if (typeof id === "string") return id;
+  if (typeof id === "number") return String(id);
+  return "";
+}
+
+export function chainHash(fingerprints: readonly string[], throughIndex: number): string {
+  let hash = "";
+  for (let i = 0; i <= throughIndex; i++) {
+    const fingerprint = fingerprints[i];
+    if (fingerprint === undefined) break;
+    hash = createHash("sha256")
+      .update(hash + fingerprint)
+      .digest("hex");
+  }
+  return hash;
+}
+
+export function idChainHash(messages: readonly AgentMessage[], throughIndex: number): string {
+  let hash = "";
+  for (let i = 0; i <= throughIndex; i++) {
+    const message = messages[i];
+    if (!message) break;
+    hash = createHash("sha256")
+      .update(hash + messageId(message))
+      .digest("hex");
+  }
+  return hash;
+}
+
+function buildCursor(messages: readonly AgentMessage[], throughIndex: number): SessionRetainCursor {
+  const tailStart = Math.max(0, throughIndex - RETAIN_CURSOR_TAIL_WINDOW + 1);
+  const tailMessages = messages.slice(tailStart, throughIndex + 1);
+  const prefixFingerprints = messages.slice(0, throughIndex + 1).map(messageFingerprint);
+  return {
+    index: throughIndex,
+    chainHash: chainHash(prefixFingerprints, throughIndex),
+    idChainHash: idChainHash(messages, throughIndex),
+    tailStart,
+    messageIds: tailMessages.map(messageId),
+    fingerprints: tailMessages.map(messageFingerprint),
+  };
+}
+
+function migrateCursorToV3(cursor: SessionRetainCursorV2): SessionRetainCursor {
+  const tailStart = Math.max(0, cursor.index - RETAIN_CURSOR_TAIL_WINDOW + 1);
+  return {
+    index: cursor.index,
+    chainHash: cursor.chainHash,
+    idChainHash: cursor.idChainHash,
+    tailStart,
+    messageIds: cursor.messageIds.slice(tailStart),
+    fingerprints: cursor.fingerprints.slice(tailStart),
+  };
+}
+
+function isLegacySessionEntry(value: unknown): value is LegacySessionEntry {
+  return (
+    !!value &&
+    typeof value === "object" &&
+    !Array.isArray(value) &&
+    Array.isArray((value as LegacySessionEntry).legacyFingerprints)
+  );
+}
+
+function isSessionRetainCursorV2(value: unknown): value is SessionRetainCursorV2 {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return false;
+  const cursor = value as SessionRetainCursorV2;
+  return (
+    typeof cursor.index === "number" &&
+    typeof cursor.chainHash === "string" &&
+    typeof cursor.idChainHash === "string" &&
+    Array.isArray(cursor.messageIds) &&
+    Array.isArray(cursor.fingerprints) &&
+    !("tailStart" in cursor)
+  );
+}
+
+function isSessionRetainCursor(value: unknown): value is SessionRetainCursor {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return false;
+  const cursor = value as SessionRetainCursor;
+  return (
+    typeof cursor.index === "number" &&
+    typeof cursor.chainHash === "string" &&
+    typeof cursor.idChainHash === "string" &&
+    typeof cursor.tailStart === "number" &&
+    Array.isArray(cursor.messageIds) &&
+    Array.isArray(cursor.fingerprints)
+  );
+}
+
+function normalizeLegacyFingerprints(value: unknown): string[] {
+  if (!Array.isArray(value)) return [];
+  return value.filter((item): item is string => typeof item === "string");
+}
+
+function readLegacyStore(parsed: RetainCursorStoreV1): Record<string, LegacySessionEntry> {
+  const sessions: Record<string, LegacySessionEntry> = {};
+  for (const [key, value] of Object.entries(parsed.sessions ?? {})) {
+    const fingerprints = normalizeLegacyFingerprints(value);
+    if (fingerprints.length > 0) sessions[key] = { legacyFingerprints: fingerprints };
+  }
+  return sessions;
+}
+
+async function readRetainCursorStore(path: string): Promise<RetainCursorStoreV3> {
+  try {
+    const parsed = JSON.parse(await readFile(path, "utf8")) as unknown;
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+      return { version: RETAIN_CURSOR_VERSION, sessions: {} };
+    }
+
+    const version = (parsed as { version?: unknown }).version;
+    const sessions = (parsed as { sessions?: unknown }).sessions;
+    if (!sessions || typeof sessions !== "object" || Array.isArray(sessions)) {
+      return { version: RETAIN_CURSOR_VERSION, sessions: {} };
+    }
+
+    if (version === RETAIN_CURSOR_VERSION) {
+      const normalized: RetainCursorStoreV3["sessions"] = {};
+      for (const [key, value] of Object.entries(sessions)) {
+        if (isSessionRetainCursor(value)) normalized[key] = value;
+        else if (isLegacySessionEntry(value)) normalized[key] = value;
+      }
+      return { version: RETAIN_CURSOR_VERSION, sessions: normalized };
+    }
+
+    if (version === 2) {
+      const normalized: RetainCursorStoreV3["sessions"] = {};
+      for (const [key, value] of Object.entries(sessions)) {
+        if (isSessionRetainCursorV2(value)) normalized[key] = migrateCursorToV3(value);
+        else if (isLegacySessionEntry(value)) normalized[key] = value;
+      }
+      return { version: RETAIN_CURSOR_VERSION, sessions: normalized };
+    }
+
+    return {
+      version: RETAIN_CURSOR_VERSION,
+      sessions: readLegacyStore(parsed as RetainCursorStoreV1),
+    };
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") {
+      return { version: RETAIN_CURSOR_VERSION, sessions: {} };
+    }
+    throw error;
+  }
+}
+
+async function writeRetainCursorStore(path: string, store: RetainCursorStoreV3): Promise<void> {
+  await mkdir(dirname(path), { recursive: true });
+  const tmp = `${path}.tmp`;
+  await writeFile(tmp, `${JSON.stringify(store, null, 2)}\n`, "utf8");
+  await rename(tmp, path);
+}
+
+export async function readSessionRetainState(
+  cwd: string,
+  sessionId: string,
+): Promise<SessionRetainState | undefined> {
+  const store = await readRetainCursorStore(retainCursorPath(cwd));
+  const entry = store.sessions[sessionId];
+  if (!entry) return undefined;
+  if (isLegacySessionEntry(entry)) {
+    return { legacyFingerprints: new Set(entry.legacyFingerprints) };
+  }
+  return { cursor: entry };
+}
+
+function legacyRetainStart(messages: readonly AgentMessage[], legacy: ReadonlySet<string>): number {
+  for (let i = messages.length - 1; i >= 0; i--) {
+    const message = messages[i];
+    if (!message) continue;
+    if (legacy.has(messageFingerprint(message))) return i + 1;
+  }
+  return 0;
+}
+
+function prefixChainMatches(
+  messages: readonly AgentMessage[],
+  cursor: SessionRetainCursor,
+): boolean {
+  const fingerprints: string[] = [];
+  for (let i = 0; i <= cursor.index; i++) {
+    const message = messages[i];
+    if (!message) return false;
+    fingerprints.push(messageFingerprint(message));
+  }
+  return chainHash(fingerprints, cursor.index) === cursor.chainHash;
+}
+
+function filterWithCursor(
+  messages: readonly AgentMessage[],
+  cursor: SessionRetainCursor,
+): AgentMessage[] {
+  if (messages.length === 0) return [];
+
+  if (cursor.index < messages.length && prefixChainMatches(messages, cursor)) {
+    return messages.slice(cursor.index + 1);
+  }
+
+  const retained: AgentMessage[] = [];
+  let branched = false;
+
+  for (let i = 0; i < messages.length; i++) {
+    const message = messages[i];
+    if (!message) continue;
+
+    if (i > cursor.index) {
+      retained.push(message);
+      continue;
+    }
+
+    if (i < cursor.tailStart) {
+      if (branched) retained.push(message);
+      continue;
+    }
+
+    const offset = i - cursor.tailStart;
+    const idMatches = messageId(message) === cursor.messageIds[offset];
+    const fingerprintMatches = messageFingerprint(message) === cursor.fingerprints[offset];
+
+    if (!idMatches) {
+      branched = true;
+      retained.push(message);
+      continue;
+    }
+
+    if (branched) {
+      retained.push(message);
+      continue;
+    }
+
+    if (!fingerprintMatches) {
+      retained.push(message);
+    }
+  }
+
+  return retained;
+}
+
+export function filterNewRetainMessages(
+  messages: readonly AgentMessage[],
+  state: SessionRetainState | undefined,
+): AgentMessage[] {
+  if (!state) return [...messages];
+  if (state.cursor) return filterWithCursor(messages, state.cursor);
+  if (state.legacyFingerprints?.size) {
+    return messages.slice(legacyRetainStart(messages, state.legacyFingerprints));
+  }
+  return [...messages];
+}
+
+export async function advanceRetainCursor(
+  cwd: string,
+  sessionId: string,
+  allMessages: readonly AgentMessage[],
+  retainedThroughIndex: number,
+): Promise<void> {
+  if (retainedThroughIndex < 0 || retainedThroughIndex >= allMessages.length) return;
+
+  const path = retainCursorPath(cwd);
+  const store = await readRetainCursorStore(path);
+  const existing = store.sessions[sessionId];
+  const lastIndex = allMessages.length - 1;
+  let effectiveIndex = retainedThroughIndex;
+  if (isSessionRetainCursor(existing)) {
+    effectiveIndex = Math.max(existing.index, retainedThroughIndex);
+  }
+  effectiveIndex = Math.min(lastIndex, effectiveIndex);
+  store.sessions[sessionId] = buildCursor(allMessages, effectiveIndex);
+  await writeRetainCursorStore(path, store);
+}
+
+export function retainedThroughIndex(
+  allMessages: readonly AgentMessage[],
+  retainedMessages: readonly AgentMessage[],
+): number {
+  if (retainedMessages.length === 0) return -1;
+  const lastRetained = retainedMessages[retainedMessages.length - 1];
+  if (!lastRetained) return -1;
+  const lastId = messageId(lastRetained);
+  const lastFingerprint = messageFingerprint(lastRetained);
+  for (let i = 0; i < allMessages.length; i++) {
+    const message = allMessages[i];
+    if (!message) continue;
+    if (messageId(message) === lastId && messageFingerprint(message) === lastFingerprint) {
+      return i;
+    }
+  }
+  return -1;
+}