@awak-app/simy-cli 0.5.34 → 0.5.36

package/src/codex-work-pattern-sync.js

@@ -0,0 +1,940 @@
+import { createHash } from "node:crypto";
+import { constants as fsConstants } from "node:fs";
+import { lstat, mkdir, open, opendir, readFile, rename, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { basename, join, relative, resolve, sep } from "node:path";
+import { createInterface } from "node:readline";
+
+import { webApiErrorMessage, webApiHeaders, webApiUrl } from "./web-api.js";
+
+const MAX_THREADS = 10;
+const MAX_MESSAGES = 24;
+const MAX_MESSAGE_CHARS = 1_500;
+const MAX_CANDIDATE_FILES = 200;
+export const MAX_GATEWAY_BODY_BYTES = 512 * 1024;
+const DEFAULT_LOOKBACK_DAYS = 90;
+const POLL_INTERVAL_MS = 15 * 60 * 1_000;
+const STATE_SCHEMA_VERSION = "work-pattern-history-sync.v6";
+export const HISTORY_EXTRACTION_POLICY = "user_conversation.v2";
+const PROVIDER_CODEX = "codex";
+const PROVIDER_CLAUDE = "claude";
+
+export function createCodexWorkPatternSync(options = {}) {
+  let inFlight = null;
+  let abortController = null;
+  let closed = false;
+  let lastPollAt = 0;
+  return {
+    async poll(context) {
+      if (closed) return { status: "closed", uploaded: 0 };
+      const now = Number(options.now?.() ?? Date.now());
+      if (inFlight || now - lastPollAt < (options.pollIntervalMs ?? POLL_INTERVAL_MS)) {
+        return inFlight;
+      }
+      lastPollAt = now;
+      const currentController = new AbortController();
+      abortController = currentController;
+      inFlight = syncCodexWorkPatterns({
+        ...options,
+        ...context,
+        now,
+        signal: currentController.signal,
+      }).finally(() => {
+        if (abortController === currentController) abortController = null;
+        inFlight = null;
+      });
+      return inFlight;
+    },
+    async close() {
+      closed = true;
+      abortController?.abort();
+      await inFlight?.catch(() => {});
+    },
+  };
+}
+
+// History roots follow the providers' own configuration variables so a test
+// can point both at synthetic temp directories without touching real history.
+export function workPatternHistoryHomes({ codexHome, claudeHome, env = process.env } = {}) {
+  return {
+    codexHome: resolve(codexHome || env.CODEX_HOME?.trim() || join(homedir(), ".codex")),
+    claudeHome: resolve(claudeHome || env.CLAUDE_CONFIG_DIR?.trim() || join(homedir(), ".claude")),
+  };
+}
+
+export async function syncCodexWorkPatterns({
+  apiOrigin,
+  apiBaseUrl,
+  token,
+  deviceId,
+  accountId,
+  sessionRoot,
+  codexHome = workPatternHistoryHomes().codexHome,
+  claudeHome = workPatternHistoryHomes().claudeHome,
+  now = Date.now(),
+  fetchImpl = fetch,
+  onDirectoryVisited,
+  onBeforeExtract,
+  signal,
+}) {
+  if (!token || !deviceId || !sessionRoot) return { status: "not_connected", uploaded: 0 };
+  signal?.throwIfAborted();
+  // SIMY Web runs with trailingSlash=true; use the canonical slash form so the
+  // POST body never depends on a 308 redirect being replayed.
+  const endpoint = webApiUrl("work-pattern-observations/", {
+    webOrigin: apiOrigin,
+    apiBaseUrl,
+  });
+  const statusResponse = await fetchImpl(endpoint, {
+    method: "GET",
+    headers: webApiHeaders({ token }),
+    signal: signalWithTimeout(signal, 5_000),
+  });
+  const statusPayload = await statusResponse.json().catch(() => null);
+  if (!statusResponse.ok) {
+    throw new Error(webApiErrorMessage(statusPayload, statusResponse.status));
+  }
+  if (
+    !statusPayload ||
+    typeof statusPayload !== "object" ||
+    Array.isArray(statusPayload) ||
+    (Object.hasOwn(statusPayload, "enabled") &&
+      typeof statusPayload.enabled !== "boolean")
+  ) {
+    throw new Error("Work Pattern sync status response is invalid");
+  }
+  if (statusPayload?.enabled === false) return { status: "disabled", uploaded: 0 };
+
+  const lookbackDays = boundedInteger(statusPayload.lookback_days, 1, 365, DEFAULT_LOOKBACK_DAYS);
+  const statePath = workPatternSyncStatePath({
+    sessionRoot,
+    apiOrigin,
+    accountId,
+    deviceId,
+  });
+  const persistedState = await readSyncState(statePath);
+  const previousState = statusPayload.reset_cursor === true ? {} : persistedState;
+  const state = previousState.lookback_days === lookbackDays ? previousState : {};
+  const lookbackCutoffMs = now - lookbackDays * 24 * 60 * 60 * 1_000;
+  const providerSpecs = [
+    {
+      provider: PROVIDER_CODEX,
+      roots: [resolve(codexHome, "sessions"), resolve(codexHome, "archived_sessions")],
+      extract: extractCodexThreadChunks,
+      includeRelativePath: () => true,
+    },
+    {
+      provider: PROVIDER_CLAUDE,
+      roots: [resolve(claudeHome, "projects")],
+      extract: extractClaudeThreadChunks,
+      // Claude stores delegated agent transcripts below `subagents/`. They are
+      // machine-to-machine work, not a user's conversation, so exclude them.
+      includeRelativePath: (filePath) => !filePath.split(sep).includes("subagents"),
+    },
+  ];
+  const inventories = new Map();
+  let incompleteReplayRoot = false;
+  let hasCompleteRoot = false;
+  const files = (await Promise.all(providerSpecs.map(async (spec) => {
+    const providerState = providerCursor(state, spec.provider);
+    // Do not use the history window as a pre-read mtime filter: restored or
+    // migrated files can have mtimes that disagree with their message dates.
+    // The extracted record timestamp is the authority for lookback filtering.
+    const scans = await Promise.all(spec.roots.map((root) => recentSessionFiles(root, {
+      provider: spec.provider,
+      processedFiles: providerState.processed_files,
+      includeRelativePath: spec.includeRelativePath,
+      onDirectoryVisited,
+    })));
+    const priorFiles = Object.values(providerCursor(persistedState, spec.provider).processed_files);
+    scans.forEach((scan, index) => {
+      const rootKey = basename(spec.roots[index]);
+      if (!scan.complete && priorFiles.some((file) => !file.root_key || file.root_key === rootKey)) {
+        incompleteReplayRoot = true;
+      }
+    });
+    if (scans.some((scan) => scan.complete)) hasCompleteRoot = true;
+    if (scans.every((scan) => scan.complete)) {
+      inventories.set(spec.provider, new Set(scans.flatMap((scan) => [...scan.fileHashes])));
+    }
+    return scans.flatMap((scan) => scan.files);
+  }))).flat();
+  const selectedFiles = selectSessionFiles(files);
+  const threads = [];
+  const acknowledgedRevisions = new Set(providerSpecs.flatMap((spec) =>
+    Object.values(providerCursor(state, spec.provider).processed_files)
+      .filter((file) => file.lineage_ref && file.revision_ref)
+      .map((file) => `${file.lineage_ref}\0${file.revision_ref}`)));
+  const successfullyReadFiles = [];
+  const unreadableFiles = [];
+  for (const file of selectedFiles) {
+    const spec = providerSpecs.find((item) => item.provider === file.provider);
+    await onBeforeExtract?.(file);
+    const extracted = await spec.extract(file.path, {
+      deviceId,
+      fallbackObservedAt: new Date(file.mtimeMs).toISOString(),
+      lookbackCutoffMs,
+    });
+    if (extracted.readOk === false) {
+      unreadableFiles.push(file);
+      continue;
+    }
+    const withinLookback = extracted.length > 0
+      && Date.parse(extracted[0].observed_at) >= lookbackCutoffMs;
+    const revisionKey = withinLookback
+      ? `${extracted[0].lineage_ref}\0${extracted[0].revision_ref}`
+      : null;
+    successfullyReadFiles.push({
+      ...file,
+      lineage_ref: withinLookback ? extracted[0].lineage_ref : undefined,
+      revision_ref: withinLookback ? extracted[0].revision_ref : undefined,
+    });
+    // Archiving moves a transcript; it does not create another conversation.
+    // Reuse only a complete revision acknowledged in this account/device scope.
+    if (revisionKey && acknowledgedRevisions.has(revisionKey)) continue;
+    if (revisionKey) acknowledgedRevisions.add(revisionKey);
+    for (const chunk of extracted) {
+      if (
+        chunk.messages.length > 0
+        && Date.parse(chunk.observed_at) >= lookbackCutoffMs
+      ) {
+        threads.push(chunk);
+      }
+    }
+  }
+  const shouldAcknowledgeEmptyReset =
+    statusPayload.reset_cursor === true &&
+    hasCompleteRoot &&
+    !incompleteReplayRoot &&
+    selectedFiles.length === successfullyReadFiles.length &&
+    threads.length === 0;
+  if (selectedFiles.length === 0 && !shouldAcknowledgeEmptyReset) {
+    return { status: "up_to_date", uploaded: 0 };
+  }
+
+  const uploadResult = threads.length > 0
+    ? await uploadThreadBatches({ endpoint, token, threads, fetchImpl, signal })
+    : { uploaded: 0 };
+  if (shouldAcknowledgeEmptyReset) {
+    const { payload } = await postThreadBatch({ endpoint, token, threads: [], fetchImpl, signal });
+    validateThreadBatchAcknowledgement(payload, []);
+  }
+  if (selectedFiles.length === 0) return { status: "up_to_date", uploaded: 0 };
+  if (unreadableFiles.length > 0) {
+    return {
+      status: uploadResult.uploaded > 0 ? "uploaded" : "up_to_date",
+      uploaded: uploadResult.uploaded,
+    };
+  }
+
+  const providers = {};
+  for (const spec of providerSpecs) {
+    providers[spec.provider] = advanceProviderCursor(
+      providerCursor(state, spec.provider),
+      successfullyReadFiles.filter((file) => file.provider === spec.provider),
+      inventories.get(spec.provider),
+    );
+  }
+  signal?.throwIfAborted();
+  await writeSyncState(statePath, {
+    schema_version: STATE_SCHEMA_VERSION,
+    lookback_days: lookbackDays,
+    providers,
+    last_synced_at: new Date(now).toISOString(),
+  });
+  return {
+    status: uploadResult.uploaded > 0 ? "uploaded" : "up_to_date",
+    uploaded: uploadResult.uploaded,
+  };
+}
+
+export function workPatternSyncStatePath({ sessionRoot, apiOrigin, accountId, deviceId }) {
+  const normalizedOrigin = new URL(apiOrigin).origin;
+  const authenticatedSubject = cleanString(accountId, 500) || String(deviceId);
+  const scopeHash = createHash("sha256")
+    .update(`${normalizedOrigin}\0${authenticatedSubject}\0${String(deviceId)}`)
+    .digest("hex");
+  return join(sessionRoot, "work-pattern-history-sync", `${scopeHash}.json`);
+}
+
+async function uploadThreadBatches({ endpoint, token, threads, fetchImpl, signal }) {
+  const batches = [];
+  let batch = [];
+  for (const thread of threads) {
+    if (bodyByteLength([thread]) > MAX_GATEWAY_BODY_BYTES) {
+      throw new Error(
+        "Work-pattern observation chunk exceeds the local CLI gateway limit; "
+        + "the complete revision was not acknowledged.",
+      );
+    }
+    if (batch.length >= MAX_THREADS
+      || (batch.length > 0 && bodyByteLength([...batch, thread]) > MAX_GATEWAY_BODY_BYTES)) {
+      batches.push(batch);
+      batch = [];
+    }
+    batch.push(thread);
+  }
+  if (batch.length > 0) batches.push(batch);
+
+  let uploaded = 0;
+  for (const current of batches) {
+    const result = await postBatchWithBounded413Recovery({
+      endpoint,
+      token,
+      threads: current,
+      fetchImpl,
+      signal,
+    });
+    uploaded += result.uploaded;
+  }
+  return { uploaded };
+}
+
+async function postBatchWithBounded413Recovery({ endpoint, token, threads, fetchImpl, signal }) {
+  const { response, payload } = await postThreadBatch({
+    endpoint,
+    token,
+    threads,
+    fetchImpl,
+    signal,
+    allow413: true,
+  });
+  if (response.status !== 413) {
+    validateThreadBatchAcknowledgement(payload, threads);
+    return { uploaded: threads.length };
+  }
+  if (threads.length > 1) {
+    const middle = Math.ceil(threads.length / 2);
+    const left = await postBatchWithBounded413Recovery({
+      endpoint,
+      token,
+      threads: threads.slice(0, middle),
+      fetchImpl,
+      signal,
+    });
+    const right = await postBatchWithBounded413Recovery({
+      endpoint,
+      token,
+      threads: threads.slice(middle),
+      fetchImpl,
+      signal,
+    });
+    return { uploaded: left.uploaded + right.uploaded };
+  }
+  throw new Error(
+    "Work-pattern observation chunk was rejected as too large; "
+    + "the complete revision was not acknowledged and will be retried unchanged.",
+  );
+}
+
+async function postThreadBatch({
+  endpoint,
+  token,
+  threads,
+  fetchImpl,
+  signal,
+  allow413 = false,
+}) {
+  const body = JSON.stringify({ threads });
+  if (Buffer.byteLength(body, "utf8") > MAX_GATEWAY_BODY_BYTES) {
+    throw new Error("Work-pattern observation payload exceeds the local CLI gateway limit.");
+  }
+  const response = await fetchImpl(endpoint, {
+    method: "POST",
+    headers: webApiHeaders({ token }, { "Content-Type": "application/json" }),
+    body,
+    signal: signalWithTimeout(signal, 120_000),
+  });
+  const payload = await response.json().catch(() => null);
+  if (!response.ok && !(allow413 && response.status === 413)) {
+    throw new Error(webApiErrorMessage(payload, response.status));
+  }
+  return { response, payload };
+}
+
+function validateThreadBatchAcknowledgement(payload, threads) {
+  if (
+    payload?.raw_content_persisted !== false ||
+    !Number.isInteger(payload?.accepted) ||
+    payload.accepted !== threads.length ||
+    !Array.isArray(payload.accepted_receipts) ||
+    payload.accepted_receipts.length !== threads.length
+  ) {
+    throwIncompleteAcknowledgement();
+  }
+  const expected = threads.map(threadReceiptKey).sort();
+  const actual = payload.accepted_receipts.map(receiptKey).sort();
+  for (let index = 0; index < expected.length; index += 1) {
+    if (actual[index] !== expected[index]) throwIncompleteAcknowledgement();
+  }
+}
+
+function threadReceiptKey(thread) {
+  return receiptKey({
+    source_ref: thread.source_ref,
+    revision_ref: thread.revision_ref,
+    lineage_ref: thread.lineage_ref,
+    chunk_index: thread.chunk_index,
+    chunk_count: thread.chunk_count,
+    message_offset: thread.message_offset,
+    message_count: Array.isArray(thread.messages) ? thread.messages.length : -1,
+  });
+}
+
+function receiptKey(receipt) {
+  return [
+    stringPart(receipt?.source_ref),
+    stringPart(receipt?.revision_ref),
+    stringPart(receipt?.lineage_ref),
+    integerPart(receipt?.chunk_index),
+    integerPart(receipt?.chunk_count),
+    integerPart(receipt?.message_offset),
+    integerPart(receipt?.message_count),
+  ].join("\0");
+}
+
+function stringPart(value) {
+  return typeof value === "string" ? value : "";
+}
+
+function integerPart(value) {
+  return Number.isInteger(value) ? String(value) : "";
+}
+
+function throwIncompleteAcknowledgement() {
+  throw new Error(
+    "Work-pattern observation acknowledgement was incomplete; "
+    + "the revision cursor was not advanced and the exact payload will be retried.",
+  );
+}
+
+function signalWithTimeout(signal, timeoutMs) {
+  const timeoutSignal = AbortSignal.timeout(timeoutMs);
+  return signal ? AbortSignal.any([signal, timeoutSignal]) : timeoutSignal;
+}
+
+function bodyByteLength(threads) {
+  return Buffer.byteLength(JSON.stringify({ threads }), "utf8");
+}
+
+export async function extractCodexThreadChunks(filePath, { deviceId, fallbackObservedAt, lookbackCutoffMs }) {
+  let providerThreadId = basename(filePath, ".jsonl");
+  // The history record timestamp is authoritative for lookback filtering. The
+  // file mtime is only a fallback for legacy records without timestamps.
+  let observedAt = null;
+  let streamEntries = [];
+  let delegated = false;
+  const file = await readSessionRecords(filePath, (record) => {
+    if (record?.type === "session_meta") {
+      providerThreadId = cleanString(record.payload?.id, 200) || providerThreadId;
+      const source = record.payload?.source;
+      delegated ||= source === "subagent"
+        || (source && typeof source === "object" && Object.hasOwn(source, "subagent"));
+      return;
+    }
+    if (delegated) return;
+    if (record?.type === "event_msg") {
+      const type = record.payload?.type;
+      if (type === "user_message" || type === "agent_message") {
+        if (isInternalCodexMessage(record.payload)) return;
+        const messages = cleanMessageSegments(codexConversationText(record.payload?.message)).map((content) => ({
+          role: type === "user_message" ? "user" : "assistant",
+          content,
+        }));
+        if (messages.length > 0) streamEntries.push({
+          id: "", kind: "event", messages, observedAt: validIso(record.timestamp),
+        });
+        observedAt = latestIso(observedAt, record.timestamp);
+      }
+      return;
+    }
+    if (record?.type === "response_item" && record.payload?.type === "message") {
+      const role = record.payload?.role;
+      if (role !== "user" && role !== "assistant") return;
+      if (isInternalCodexMessage(record.payload)) return;
+      const contents = responseItemTextSegments(record.payload?.content);
+      if (contents.length > 0) {
+        streamEntries.push({
+          id: cleanString(record.payload?.id, 200),
+          kind: "response",
+          observedAt: validIso(record.timestamp),
+          messages: contents.map((content) => ({ role, content })),
+        });
+        observedAt = latestIso(observedAt, record.timestamp);
+      }
+      return;
+    }
+    if (record?.type === "compacted" && Array.isArray(record.payload?.replacement_history)) {
+      const nextEntries = codexReplacementHistoryEntries(record.payload.replacement_history);
+      if (nextEntries.length > 0) {
+        streamEntries = mergeCodexSnapshot(streamEntries, nextEntries);
+        observedAt = latestIso(observedAt, record.timestamp);
+      }
+    }
+  });
+  if (!file || file.readOk === false) return markReadStatus([], false);
+  if (delegated) return markReadStatus([], true);
+  // Legacy transcripts can have no record timestamps at all. In that case
+  // retain the documented file-mtime fallback; mixed dated/undated streams
+  // never let an undated entry borrow a recent timestamp from another turn.
+  if (!streamEntries.some((entry) => entry.observedAt)) {
+    const fallback = validIso(fallbackObservedAt) || new Date(file.mtimeMs).toISOString();
+    streamEntries = streamEntries.map((entry) => ({ ...entry, observedAt: fallback }));
+  }
+  const messages = mergeCodexHistoryEntries(streamEntries, lookbackCutoffMs);
+  if (!providerThreadId || messages.length === 0) return markReadStatus([], true);
+  return markReadStatus(chunkThread({
+    provider: PROVIDER_CODEX,
+    deviceId,
+    providerThreadId,
+    observedAt: validIso(observedAt)
+      || validIso(fallbackObservedAt)
+      || new Date(file.mtimeMs).toISOString(),
+    messages,
+  }), true);
+}
+
+export async function extractCodexThread(filePath, options) {
+  const chunks = await extractCodexThreadChunks(filePath, options);
+  if (chunks.length === 0) return null;
+  return {
+    source_ref: chunks.legacySourceRef,
+    observed_at: chunks.at(-1).observed_at,
+    messages: chunks.flatMap((chunk) => chunk.messages).slice(-MAX_MESSAGES),
+  };
+}
+
+export async function extractClaudeThreadChunks(filePath, { deviceId, fallbackObservedAt, lookbackCutoffMs }) {
+  let providerThreadId = basename(filePath, ".jsonl");
+  // Do not let a recent file rewrite make old conversation content look new.
+  let observedAt = null;
+  const messageEntries = [];
+  const file = await readSessionRecords(filePath, (record) => {
+    const role = record?.type;
+    if (role !== "user" && role !== "assistant") return;
+    if (record.isMeta === true || record.message?.role !== role) return;
+    providerThreadId = cleanString(record.sessionId, 200) || providerThreadId;
+    const contents = claudeMessageTextSegments(record.message?.content, role);
+    if (contents.length === 0) return;
+    messageEntries.push(...contents.map((content) => ({
+      role, content, observedAt: validIso(record.timestamp),
+    })));
+    observedAt = latestIso(observedAt, record.timestamp);
+  });
+  if (!file || file.readOk === false) return markReadStatus([], false);
+  const allUndated = !messageEntries.some((entry) => entry.observedAt);
+  const fallback = validIso(fallbackObservedAt) || new Date(file.mtimeMs).toISOString();
+  const messages = messageEntries
+    .filter((entry) => lookbackCutoffMs === undefined || Date.parse(entry.observedAt || (allUndated ? fallback : "")) >= lookbackCutoffMs)
+    .map(({ role, content }) => ({ role, content }));
+  if (!providerThreadId || messages.length === 0) return markReadStatus([], true);
+  return markReadStatus(chunkThread({
+    provider: PROVIDER_CLAUDE,
+    deviceId,
+    providerThreadId,
+    observedAt: validIso(observedAt)
+      || validIso(fallbackObservedAt)
+      || new Date(file.mtimeMs).toISOString(),
+    messages,
+  }), true);
+}
+
+export async function extractClaudeThread(filePath, options) {
+  const chunks = await extractClaudeThreadChunks(filePath, options);
+  if (chunks.length === 0) return null;
+  return {
+    source_ref: chunks.legacySourceRef,
+    observed_at: chunks.at(-1).observed_at,
+    messages: chunks.flatMap((chunk) => chunk.messages).slice(-MAX_MESSAGES),
+  };
+}
+
+export function opaqueCodexRef(deviceId, providerThreadId) {
+  return opaqueProviderRef(PROVIDER_CODEX, deviceId, providerThreadId);
+}
+
+export function opaqueClaudeRef(deviceId, providerThreadId) {
+  return opaqueProviderRef(PROVIDER_CLAUDE, deviceId, providerThreadId);
+}
+
+function opaqueProviderRef(provider, deviceId, providerThreadId) {
+  const digest = createHash("sha256")
+    // Preserve the already-shipped Codex digest while separating providers by
+    // the non-secret prefix. Identical provider-local ids cannot collide.
+    .update(`${String(deviceId)}:${String(providerThreadId)}`)
+    .digest("hex");
+  return `${provider}:${digest}`;
+}
+
+async function recentSessionFiles(root, {
+  provider,
+  processedFiles,
+  includeRelativePath,
+  onDirectoryVisited,
+}) {
+  const absoluteRoot = resolve(root);
+  let complete = true;
+  const fileHashes = new Set();
+  const rootMetadata = await lstat(absoluteRoot).catch(() => {
+    complete = false;
+    return null;
+  });
+  if (!rootMetadata?.isDirectory() || rootMetadata.isSymbolicLink()) {
+    // A missing or unavailable root may return later. It is not a complete
+    // empty inventory and must not erase acknowledgements for its histories.
+    return { files: [], fileHashes, complete: false };
+  }
+  const oldest = [];
+  const newest = [];
+  async function walk(directory) {
+    onDirectoryVisited?.(relative(absoluteRoot, directory));
+    let entries;
+    try { entries = await opendir(directory); } catch { complete = false; return; }
+    for await (const entry of entries) {
+      const candidate = resolve(directory, entry.name);
+      if (candidate !== absoluteRoot && !candidate.startsWith(absoluteRoot + sep)) continue;
+      const relativePath = relative(absoluteRoot, candidate);
+      // Reject excluded directory branches before lstat/opendir. Claude's
+      // delegated-agent trees can be large and are never user conversations.
+      if (entry.isDirectory() && !includeRelativePath(relativePath)) continue;
+      const metadata = await lstat(candidate).catch(() => { complete = false; return null; });
+      if (!metadata || metadata.isSymbolicLink()) continue;
+      if (metadata.isDirectory()) {
+        if (!includeRelativePath(relativePath)) continue;
+        await walk(candidate);
+      } else if (metadata.isFile() && entry.name.endsWith(".jsonl")) {
+        if (!includeRelativePath(relativePath)) continue;
+        const fileHash = createHash("sha256")
+          .update(`${provider}\0${basename(absoluteRoot)}\0${relativePath}`)
+          .digest("hex");
+        fileHashes.add(fileHash);
+        // A global mtime cursor hides restored files. Per-file fingerprints also
+        // detect rewrites that preserve mtime without persisting local paths.
+        const fingerprint = `${metadata.mtimeMs}:${metadata.ctimeMs}:${metadata.size}`;
+        if (processedFiles[fileHash]?.fingerprint === fingerprint) continue;
+        const file = { path: candidate, provider, mtimeMs: metadata.mtimeMs, fileHash, fingerprint, root_key: basename(absoluteRoot) };
+        oldest.push(file);
+        oldest.sort(compareSessionFiles);
+        if (oldest.length > MAX_CANDIDATE_FILES / 2) oldest.pop();
+        newest.push(file);
+        newest.sort((left, right) => compareSessionFiles(right, left));
+        if (newest.length > MAX_CANDIDATE_FILES / 2) newest.pop();
+      }
+    }
+  }
+  await walk(absoluteRoot);
+  return {
+    files: [...new Map([...oldest, ...newest].map((file) => [file.fileHash, file])).values()],
+    fileHashes,
+    complete,
+  };
+}
+
+function selectSessionFiles(files) {
+  const recent = [...files].sort((left, right) => compareSessionFiles(right, left));
+  const older = [...files].sort(compareSessionFiles);
+  const selected = recent.slice(0, MAX_THREADS - 2);
+  const seen = new Set(selected.map((file) => file.fileHash));
+  for (const file of older) {
+    if (selected.length >= MAX_THREADS) break;
+    if (!seen.has(file.fileHash)) {
+      selected.push(file);
+      seen.add(file.fileHash);
+    }
+  }
+  for (const file of recent) {
+    if (selected.length >= MAX_THREADS) break;
+    if (!seen.has(file.fileHash)) {
+      selected.push(file);
+      seen.add(file.fileHash);
+    }
+  }
+  return selected;
+}
+
+function compareSessionFiles(left, right) {
+  return left.mtimeMs - right.mtimeMs
+    || left.provider.localeCompare(right.provider)
+    || left.fileHash.localeCompare(right.fileHash);
+}
+
+async function readSessionRecords(filePath, consume) {
+  let handle;
+  try {
+    handle = await open(filePath, fsConstants.O_RDONLY | fsConstants.O_NOFOLLOW);
+    const metadata = await handle.stat();
+    if (!metadata.isFile()) return null;
+    const lines = createInterface({
+      input: handle.createReadStream({ encoding: "utf8", autoClose: false }),
+      crlfDelay: Infinity,
+    });
+    for await (const line of lines) {
+      if (!line) continue;
+      let record;
+      try { record = JSON.parse(line); } catch { return markFileReadStatus(metadata, false); }
+      consume(record);
+    }
+    return markFileReadStatus(metadata, true);
+  } catch {
+    return null;
+  } finally {
+    await handle?.close().catch(() => {});
+  }
+}
+
+function markFileReadStatus(metadata, readOk) {
+  Object.defineProperty(metadata, "readOk", {
+    value: readOk,
+    enumerable: false,
+  });
+  return metadata;
+}
+
+function responseItemTextSegments(content) {
+  if (!Array.isArray(content)) return [];
+  const text = content
+    .filter((item) => item?.type === "input_text" || item?.type === "output_text")
+    .map((item) => String(item.text || ""))
+    .join("\n");
+  return cleanMessageSegments(codexConversationText(text));
+}
+
+function isInternalCodexMessage(message) {
+  return message?.channel === "analysis"
+    || message?.phase === "analysis"
+    || (message?.role === "assistant" && message.recipient && message.recipient !== "all");
+}
+
+function codexConversationText(value) {
+  if (typeof value !== "string") return "";
+  const text = value.trim();
+  // These are runtime-generated context records, even when the persisted
+  // message envelope uses the user role. They are not personal instructions.
+  if (text.startsWith("# AGENTS.md instructions for ")
+    || text.startsWith("<environment_context>")
+    || text.startsWith("<recommended_plugins>")
+    || text.startsWith("<turn_aborted>")
+    || text.startsWith("Another language model started to solve this problem")) return "";
+  return text;
+}
+
+function codexReplacementHistoryEntries(history) {
+  const entries = [];
+  for (const item of history) {
+    if (isInternalCodexMessage(item)) continue;
+    const role = item?.type === "agent_message"
+      ? "assistant"
+      : item?.type === "message" && (item.role === "user" || item.role === "assistant")
+        ? item.role
+        : null;
+    if (!role) continue;
+    const contents = responseItemTextSegments(item.content);
+    if (contents.length === 0) continue;
+    entries.push({
+      id: cleanString(item.id, 200),
+      kind: "snapshot",
+      observedAt: validIso(item.timestamp),
+      messages: contents.map((content) => ({ role, content })),
+    });
+  }
+  return entries;
+}
+
+function entryKey(entry) {
+  return JSON.stringify(entry.messages);
+}
+
+function mergeCodexSnapshot(streamEntries, snapshotEntries) {
+  const merged = [...streamEntries];
+  let position = 0;
+  for (const entry of snapshotEntries) {
+    // Match in order, so genuinely repeated instructions remain repeated. A
+    // snapshot is a replacement view of prior history, not a fresh user turn.
+    const key = entryKey(entry);
+    const index = merged.findIndex((existing, i) => i >= position
+      && ((entry.id && existing.id === entry.id) || entryKey(existing) === key));
+    if (index >= 0) position = index + 1;
+    else {
+      merged.splice(position, 0, entry);
+      position += 1;
+    }
+  }
+  return merged;
+}
+
+function mergeCodexHistoryEntries(entries, lookbackCutoffMs) {
+  const seenIds = new Set();
+  const merged = [];
+  for (const entry of entries) {
+    if (entry.id) {
+      if (seenIds.has(entry.id)) continue;
+      seenIds.add(entry.id);
+    }
+    const previous = merged.at(-1);
+    const complementary = previous && !previous.paired && previous.kind !== entry.kind;
+    if (complementary && entryKey(previous) === entryKey(entry)) {
+      previous.paired = true;
+      previous.observedAt = latestIso(previous.observedAt, entry.observedAt);
+      continue;
+    }
+    merged.push({ ...entry });
+  }
+  return merged
+    .filter((entry) => lookbackCutoffMs === undefined
+      || (entry.observedAt && Date.parse(entry.observedAt) >= lookbackCutoffMs))
+    .flatMap((entry) => entry.messages);
+}
+
+function markReadStatus(chunks, readOk) {
+  Object.defineProperty(chunks, "readOk", {
+    value: readOk,
+    enumerable: false,
+  });
+  return chunks;
+}
+
+function claudeMessageTextSegments(content, role) {
+  const text = typeof content === "string"
+    ? content
+    : Array.isArray(content)
+      ? content
+        .filter((item) => item?.type === "text" && typeof item.text === "string")
+        .map((item) => item.text)
+        .join("\n")
+      : "";
+  return cleanMessageSegments(role === "user" ? stripClaudeInternalBlocks(text) : text);
+}
+
+function stripClaudeInternalBlocks(value) {
+  return String(value)
+    .replace(/<system-reminder>[\s\S]*?<\/system-reminder>/gi, "")
+    .replace(/<local-command-caveat>[\s\S]*?<\/local-command-caveat>/gi, "")
+    .replace(/<command-(?:name|message|args)>[\s\S]*?<\/command-(?:name|message|args)>/gi, "");
+}
+
+function cleanMessageSegments(value) {
+  if (typeof value !== "string") return [];
+  const cleaned = value.replaceAll("\u0000", "").trim();
+  if (!cleaned) return [];
+  const points = Array.from(cleaned);
+  const segments = [];
+  for (let offset = 0; offset < points.length; offset += MAX_MESSAGE_CHARS) {
+    segments.push(points.slice(offset, offset + MAX_MESSAGE_CHARS).join(""));
+  }
+  return segments;
+}
+
+function chunkThread({ provider, deviceId, providerThreadId, observedAt, messages }) {
+  const revisionRef = createHash("sha256")
+    .update(JSON.stringify({ extraction_policy: HISTORY_EXTRACTION_POLICY, messages }))
+    .digest("hex");
+  const chunkCount = Math.ceil(messages.length / MAX_MESSAGES);
+  const chunks = Array.from({ length: chunkCount }, (_, chunkIndex) => {
+    const messageOffset = chunkIndex * MAX_MESSAGES;
+    const chunkIdentity = `${providerThreadId}:revision:${revisionRef}:chunk:${chunkIndex}`;
+    return {
+      extraction_policy: HISTORY_EXTRACTION_POLICY,
+      source_ref: opaqueProviderRef(provider, deviceId, chunkIdentity),
+      lineage_ref: opaqueProviderRef(provider, deviceId, providerThreadId),
+      observed_at: observedAt,
+      revision_ref: revisionRef,
+      chunk_index: chunkIndex,
+      chunk_count: chunkCount,
+      message_offset: messageOffset,
+      messages: messages.slice(messageOffset, messageOffset + MAX_MESSAGES),
+    };
+  });
+  Object.defineProperty(chunks, "legacySourceRef", {
+    value: opaqueProviderRef(provider, deviceId, providerThreadId),
+    enumerable: false,
+  });
+  return chunks;
+}
+
+function cleanString(value, maxLength) {
+  if (typeof value !== "string") return "";
+  return value.replaceAll("\u0000", "").trim().slice(0, maxLength);
+}
+
+function validIso(value) {
+  if (typeof value !== "string" || !Number.isFinite(Date.parse(value))) return null;
+  return new Date(value).toISOString();
+}
+
+function latestIso(current, candidate) {
+  const left = validIso(current);
+  const right = validIso(candidate);
+  if (!right) return left || current;
+  if (!left) return right;
+  return Date.parse(right) > Date.parse(left) ? right : left;
+}
+
+function boundedInteger(value, min, max, fallback) {
+  const parsed = Number(value);
+  return Number.isInteger(parsed) && parsed >= min && parsed <= max ? parsed : fallback;
+}
+
+async function readSyncState(filePath) {
+  try {
+    const parsed = JSON.parse(await readFile(filePath, "utf8"));
+    // Earlier schemas acknowledge truncated or unfiltered history. Replay with
+    // the corrected extraction policy rather than inheriting those receipts.
+    return parsed?.schema_version === STATE_SCHEMA_VERSION ? parsed : {};
+  } catch {
+    return {};
+  }
+}
+
+function providerCursor(state, provider) {
+  const cursor = state?.providers?.[provider];
+  const files = cursor?.processed_files;
+  const processedFiles = {};
+  if (files && typeof files === "object" && !Array.isArray(files)) {
+    for (const [hash, file] of Object.entries(files)) {
+      if (!/^[0-9a-f]{64}$/.test(hash) || typeof file?.fingerprint !== "string") continue;
+      processedFiles[hash] = { fingerprint: file.fingerprint };
+      if (["sessions", "archived_sessions", "projects"].includes(file.root_key)) {
+        processedFiles[hash].root_key = file.root_key;
+      }
+      if (new RegExp(`^${provider}:[0-9a-f]{64}$`).test(file.lineage_ref)
+        && /^[0-9a-f]{64}$/.test(file.revision_ref)) {
+        processedFiles[hash].lineage_ref = file.lineage_ref;
+        processedFiles[hash].revision_ref = file.revision_ref;
+      }
+    }
+  }
+  return {
+    last_uploaded_mtime_ms: Number(cursor?.last_uploaded_mtime_ms || 0),
+    processed_files: processedFiles,
+  };
+}
+
+function advanceProviderCursor(cursor, selectedFiles, currentFileHashes) {
+  // Drop deleted/moved path fingerprints only after a complete inventory.
+  // Inaccessible directories must not erase acknowledgements for their files.
+  const processedFiles = Object.fromEntries(Object.entries(cursor.processed_files)
+    .filter(([hash]) => !currentFileHashes || currentFileHashes.has(hash)));
+  for (const file of selectedFiles) {
+    processedFiles[file.fileHash] = {
+      fingerprint: file.fingerprint,
+      root_key: file.root_key,
+      ...(file.lineage_ref && file.revision_ref
+        ? { lineage_ref: file.lineage_ref, revision_ref: file.revision_ref }
+        : {}),
+    };
+  }
+  return {
+    last_uploaded_mtime_ms: Math.max(
+      cursor.last_uploaded_mtime_ms,
+      ...selectedFiles.map((file) => file.mtimeMs),
+    ),
+    processed_files: processedFiles,
+  };
+}
+
+async function writeSyncState(filePath, state) {
+  await mkdir(resolve(filePath, ".."), { recursive: true, mode: 0o700 });
+  const temporary = `${filePath}.tmp`;
+  await writeFile(temporary, `${JSON.stringify(state)}\n`, { mode: 0o600 });
+  await rename(temporary, filePath);
+}