@remnic/cli 9.42.0 → 9.44.0

package/dist/index.js

@@ -21,7 +21,7 @@ async function persistEnrichmentCandidate(storage, entityName, candidate) {
 import fs12 from "fs";
 import os from "os";
 import path15 from "path";
-import { createHash as createHash2 } from "crypto";
+import { createHash as createHash3 } from "crypto";
 import * as childProcess2 from "child_process";
 import { fileURLToPath as fileURLToPath4 } from "url";
 import { gzipSync } from "zlib";
@@ -110,10 +110,10 @@ import {
   parseXrayCliOptions,
   renderXray,
   OFFLINE_SYNC_APPLY_MAX_BODY_BYTES,
-  OFFLINE_SYNC_FILE_CONTENT_MAX_CHUNK_BYTES,
-  OFFLINE_SYNC_FILE_CONTENT_TRANSFER_CHUNK_BYTES as OFFLINE_SYNC_FILE_CONTENT_TRANSFER_CHUNK_BYTES2,
+  OFFLINE_SYNC_FILE_CONTENT_MAX_CHUNK_BYTES as OFFLINE_SYNC_FILE_CONTENT_MAX_CHUNK_BYTES2,
+  OFFLINE_SYNC_FILE_CONTENT_TRANSFER_CHUNK_BYTES as OFFLINE_SYNC_FILE_CONTENT_TRANSFER_CHUNK_BYTES3,
   OFFLINE_SYNC_SNAPSHOT_BASE_MAX_BODY_BYTES,
-  applyOfflineSyncFileContentChunk,
+  applyOfflineSyncFileContentChunk as applyOfflineSyncFileContentChunk2,
   applyOfflineSyncSnapshot,
   buildOfflineSyncChangesetFromSnapshot,
   drainPendingLifecycleForOfflineSync,
@@ -239,27 +239,297 @@ async function loadWecloneExportModule() {
 }
 
 // src/converge.ts
-import * as fs2 from "fs";
-import * as path from "path";
+import * as fs3 from "fs";
+import { createHash as createHash2 } from "crypto";
+import * as path2 from "path";
 import {
   parseConfig as parseConfig2,
-  buildOfflineSyncSnapshotFromBase
+  buildOfflineSyncSnapshotFromBase,
+  OFFLINE_SYNC_FILE_CONTENT_MAX_CHUNK_BYTES,
+  OFFLINE_SYNC_FILE_CONTENT_TRANSFER_CHUNK_BYTES as OFFLINE_SYNC_FILE_CONTENT_TRANSFER_CHUNK_BYTES2,
+  applyOfflineSyncFileContentChunk
 } from "@remnic/core";
 import { resolveCorpusNamespaceRoots } from "@remnic/core/corpus-watermark.js";
 import { listNamespaces } from "@remnic/core/namespaces/migrate.js";
 import {
   planReconciliation
 } from "@remnic/core/reconcile/plan.js";
+import {
+  defaultConvergeCursorPath,
+  readConvergeCursor,
+  writeConvergeCursor
+} from "@remnic/core/reconcile/cursor.js";
+
+// src/offline-storage-io.ts
+import { mkdtemp, readdir, lstat, rm } from "fs/promises";
+import fs2 from "fs";
+import path from "path";
+import { createHash, createDecipheriv } from "crypto";
+import {
+  OFFLINE_SYNC_FILE_CONTENT_TRANSFER_CHUNK_BYTES,
+  StorageManager
+} from "@remnic/core";
+import { OFFLINE_DECRYPT_STAGING_DIR_PREFIX } from "@remnic/core/offline-sync-exclude-globs";
+import {
+  AUTH_TAG_LENGTH,
+  ENVELOPE_HEADER_SIZE,
+  ENVELOPE_LAYOUT,
+  ENVELOPE_SALT_LENGTH,
+  ENVELOPE_VERSION,
+  FILE_FORMAT_FLAGS,
+  FILE_FORMAT_VERSION,
+  IV_LENGTH,
+  MAGIC_BYTES,
+  MAGIC_HEADER_SIZE,
+  SecureStoreLockedError,
+  filePathAad,
+  isEncryptedFile,
+  keyring,
+  readHeader,
+  secureStoreDir
+} from "@remnic/core/secure-store";
+async function createConfiguredOfflineStorage(memoryDir, secureStoreEncryptOnWrite = true) {
+  const storage = new StorageManager(memoryDir);
+  const header = await readHeader(memoryDir);
+  let secureStoreKey = null;
+  let secureStoreRequired = false;
+  if (header) {
+    secureStoreRequired = true;
+    storage.setSecureStoreRequired(true);
+    const key = keyring.getKey(secureStoreDir(memoryDir));
+    if (key) {
+      await storage.setSecureStoreKeyAndWait(key, secureStoreEncryptOnWrite);
+      secureStoreKey = key;
+    }
+  }
+  return { storage, secureStoreKey, secureStoreRequired };
+}
+async function createOfflineStorageForPath(memoryDir, filePath, configured, secureStoreEncryptOnWrite) {
+  const memoryRoot = path.resolve(memoryDir);
+  const stateDir = path.dirname(filePath);
+  if (path.basename(stateDir) !== "state" || path.basename(filePath) !== "memory-lifecycle-ledger.jsonl") {
+    throw new Error(`invalid lifecycle ledger path: ${filePath}`);
+  }
+  const storageRoot = path.resolve(path.dirname(stateDir));
+  if (storageRoot !== memoryRoot && !storageRoot.startsWith(`${memoryRoot}${path.sep}`)) {
+    throw new Error(`lifecycle ledger path is outside the offline memory directory: ${filePath}`);
+  }
+  const storage = new StorageManager(storageRoot);
+  if (configured.secureStoreRequired) {
+    storage.setSecureStoreRequired(true);
+  }
+  if (configured.secureStoreKey) {
+    await storage.setSecureStoreKeyAndWait(configured.secureStoreKey, secureStoreEncryptOnWrite);
+  }
+  return storage;
+}
+async function createOfflineStorageIo(memoryDir, configuredStorage) {
+  await cleanupOrphanedOfflineDecryptStaging(memoryDir);
+  const { storage, secureStoreKey } = configuredStorage ?? await createConfiguredOfflineStorage(memoryDir);
+  return {
+    readFile: async ({ filePath }) => storage.readOfflineSyncFile(filePath),
+    readFileDigest: async ({ filePath }) => {
+      const hash = createHash("sha256");
+      let bytes = 0;
+      for await (const rawChunk of readOfflineSyncFileChunks({
+        filePath,
+        memoryDir,
+        secureStoreKey,
+        chunkSize: OFFLINE_SYNC_FILE_CONTENT_TRANSFER_CHUNK_BYTES
+      })) {
+        const chunk = Buffer.isBuffer(rawChunk) ? rawChunk : Buffer.from(rawChunk);
+        hash.update(chunk);
+        bytes += chunk.length;
+      }
+      return {
+        sha256: hash.digest("hex"),
+        bytes
+      };
+    },
+    readFileChunks: ({ filePath, chunkSize }) => readOfflineSyncFileChunks({
+      filePath,
+      memoryDir,
+      secureStoreKey,
+      chunkSize
+    }),
+    writeFile: async ({ filePath, content }) => storage.writeOfflineSyncFile(filePath, content),
+    writeStagingFile: async ({ filePath, content }) => storage.writeOfflineSyncStagingFile(filePath, content),
+    writeFileChunks: async ({ filePath, chunks }) => storage.writeOfflineSyncFileChunks(filePath, chunks),
+    deleteFile: async ({ filePath }) => storage.deleteOfflineSyncFile(filePath)
+  };
+}
+var OFFLINE_DECRYPT_STAGING_ORPHAN_MS = 60 * 60 * 1e3;
+async function cleanupOrphanedOfflineDecryptStaging(memoryDir) {
+  let entries;
+  try {
+    entries = await readdir(memoryDir);
+  } catch {
+    return;
+  }
+  const now = Date.now();
+  for (const name of entries) {
+    if (!name.startsWith(OFFLINE_DECRYPT_STAGING_DIR_PREFIX)) continue;
+    const dir = path.join(memoryDir, name);
+    try {
+      const info = await lstat(dir);
+      if (!info.isDirectory() || info.isSymbolicLink()) continue;
+      if (now - info.mtimeMs < OFFLINE_DECRYPT_STAGING_ORPHAN_MS) continue;
+      await rm(dir, { recursive: true, force: true });
+    } catch {
+    }
+  }
+}
+async function* readOfflineSyncFileChunks(options) {
+  const header = await readFilePrefix(options.filePath, MAGIC_HEADER_SIZE);
+  if (!isEncryptedFile(header)) {
+    yield* readPlainOfflineFileChunks(options.filePath, options.chunkSize);
+    return;
+  }
+  if (!options.secureStoreKey) {
+    throw new SecureStoreLockedError(
+      `secure-store is locked \u2014 cannot read encrypted file at ${options.filePath}. Run \`remnic secure-store unlock\` to decrypt.`
+    );
+  }
+  yield* readEncryptedOfflineFileChunks({
+    filePath: options.filePath,
+    memoryDir: options.memoryDir,
+    key: options.secureStoreKey,
+    chunkSize: options.chunkSize
+  });
+}
+async function readFilePrefix(filePath, length) {
+  const handle = await fs2.promises.open(filePath, "r");
+  try {
+    const out = Buffer.alloc(length);
+    const { bytesRead } = await handle.read(out, 0, length, 0);
+    return out.subarray(0, bytesRead);
+  } finally {
+    await handle.close();
+  }
+}
+async function* readPlainOfflineFileChunks(filePath, chunkSize) {
+  const stream = fs2.createReadStream(filePath, { highWaterMark: chunkSize });
+  for await (const chunk of stream) {
+    yield Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+  }
+}
+async function* readEncryptedOfflineFileChunks(options) {
+  const header = await readFilePrefix(options.filePath, MAGIC_HEADER_SIZE + ENVELOPE_HEADER_SIZE);
+  if (header.length < MAGIC_HEADER_SIZE + ENVELOPE_HEADER_SIZE || !isEncryptedFile(header)) {
+    throw new Error(`secure-store encrypted file is truncated: ${options.filePath}`);
+  }
+  const version = header.readUInt8(MAGIC_BYTES.length);
+  const flags = header.readUInt8(MAGIC_BYTES.length + 1);
+  if (version !== FILE_FORMAT_VERSION) {
+    throw new Error(`secure-store file has unsupported version ${version}: ${options.filePath}`);
+  }
+  if (flags !== FILE_FORMAT_FLAGS) {
+    throw new Error(`secure-store file has unsupported flags 0x${flags.toString(16)}: ${options.filePath}`);
+  }
+  const envelopeHeader = header.subarray(MAGIC_HEADER_SIZE);
+  const envelopeVersion = envelopeHeader.readUInt8(ENVELOPE_LAYOUT.version);
+  if (envelopeVersion !== ENVELOPE_VERSION) {
+    throw new Error(`secure-store envelope has unsupported version ${envelopeVersion}: ${options.filePath}`);
+  }
+  const salt = envelopeHeader.subarray(
+    ENVELOPE_LAYOUT.salt,
+    ENVELOPE_LAYOUT.salt + ENVELOPE_SALT_LENGTH
+  );
+  const iv = envelopeHeader.subarray(ENVELOPE_LAYOUT.iv, ENVELOPE_LAYOUT.iv + IV_LENGTH);
+  const authTag = envelopeHeader.subarray(
+    ENVELOPE_LAYOUT.authTag,
+    ENVELOPE_LAYOUT.authTag + AUTH_TAG_LENGTH
+  );
+  const aadCandidates = offlineFileAadCandidates(options.filePath, options.memoryDir);
+  let lastError;
+  for (const aad of aadCandidates) {
+    const tempDir = await mkdtemp(path.join(options.memoryDir, OFFLINE_DECRYPT_STAGING_DIR_PREFIX));
+    const tempPath = path.join(tempDir, "content");
+    try {
+      const decipher = createDecipheriv("aes-256-gcm", options.key, iv, {
+        authTagLength: AUTH_TAG_LENGTH
+      });
+      decipher.setAuthTag(authTag);
+      decipher.setAAD(Buffer.concat([secureStoreEnvelopeHeaderAad(salt), aad]));
+      const output = fs2.createWriteStream(tempPath, { mode: 384 });
+      try {
+        const stream = fs2.createReadStream(options.filePath, {
+          start: MAGIC_HEADER_SIZE + ENVELOPE_HEADER_SIZE,
+          highWaterMark: options.chunkSize
+        });
+        for await (const encryptedChunk of stream) {
+          const plain = decipher.update(
+            Buffer.isBuffer(encryptedChunk) ? encryptedChunk : Buffer.from(encryptedChunk)
+          );
+          if (plain.length > 0 && !output.write(plain)) {
+            await new Promise((resolve, reject) => {
+              output.once("drain", resolve);
+              output.once("error", reject);
+            });
+          }
+        }
+        const finalPlain = decipher.final();
+        if (finalPlain.length > 0 && !output.write(finalPlain)) {
+          await new Promise((resolve, reject) => {
+            output.once("drain", resolve);
+            output.once("error", reject);
+          });
+        }
+      } finally {
+        await closeWriteStream(output);
+      }
+      yield* readPlainOfflineFileChunks(tempPath, options.chunkSize);
+      return;
+    } catch (error) {
+      lastError = error;
+    } finally {
+      await rm(tempDir, { recursive: true, force: true });
+    }
+  }
+  throw lastError instanceof Error ? lastError : new Error(`secure-store could not decrypt file: ${options.filePath}`);
+}
+function offlineFileAadCandidates(filePath, memoryDir) {
+  const candidates = [filePathAad(filePath, memoryDir)];
+  const relative = path.relative(memoryDir, filePath);
+  if (!relative || relative.startsWith("..") || path.isAbsolute(relative)) return candidates;
+  const parts = relative.split(path.sep);
+  if (parts[0] === "namespaces" && parts.length >= 3 && parts[1]) {
+    candidates.push(filePathAad(filePath, path.join(memoryDir, "namespaces", parts[1])));
+  }
+  const memoryParts = path.resolve(memoryDir).split(path.sep);
+  if (memoryParts.length >= 3 && memoryParts.at(-2) === "namespaces" && memoryParts.at(-1)) {
+    const topLevelRoot = memoryParts.slice(0, -2).join(path.sep) || path.sep;
+    const topRelative = path.relative(topLevelRoot, filePath);
+    if (topRelative && !topRelative.startsWith("..") && !path.isAbsolute(topRelative) && topRelative.split(path.sep)[0] === "namespaces" && topRelative.split(path.sep)[1] === memoryParts.at(-1)) {
+      candidates.push(filePathAad(filePath, topLevelRoot));
+    }
+  }
+  return candidates;
+}
+async function closeWriteStream(stream) {
+  await new Promise((resolve, reject) => {
+    stream.once("error", reject);
+    stream.end(() => resolve());
+  });
+}
+function secureStoreEnvelopeHeaderAad(salt) {
+  const out = Buffer.alloc(1 + ENVELOPE_SALT_LENGTH);
+  out.writeUInt8(ENVELOPE_VERSION, 0);
+  Buffer.from(salt).copy(out, 1);
+  return out;
+}
+
+// src/converge.ts
 import { resolveAgentAccessAuthToken } from "@remnic/core/resolve-auth-token.js";
 async function readLocalTombstones(rootDir) {
   const shaSet = /* @__PURE__ */ new Set();
   const candidates = [
-    path.join(rootDir, "state", "tombstones.jsonl"),
-    path.join(rootDir, "tombstones.jsonl")
+    path2.join(rootDir, "state", "tombstones.jsonl"),
+    path2.join(rootDir, "tombstones.jsonl")
   ];
   for (const tombPath of candidates) {
     try {
-      const content = await fs2.promises.readFile(tombPath, "utf-8");
+      const content = await fs3.promises.readFile(tombPath, "utf-8");
       for (const line of content.split("\n")) {
         const trimmed = line.trim();
         if (!trimmed) continue;
@@ -289,44 +559,222 @@ async function fetchPeerSnapshot(peerUrl, namespace, token, fetchImpl = globalTh
     `/engram/v1/offline-sync/snapshot?namespace=${encodeURIComponent(namespace)}&content=false`
   ];
   const headers = token ? { authorization: `Bearer ${token}` } : {};
+  let lastFailure = "no snapshot route responded";
   for (const route of routes) {
+    let response;
     try {
-      const res = await fetchImpl(`${base}${route}`, { headers });
-      if (!res.ok) continue;
-      const data = await res.json();
-      const files = [];
-      if (Array.isArray(data.files)) {
-        for (const item of data.files) {
-          if (item && typeof item.path === "string" && typeof item.sha256 === "string") {
-            files.push({
-              path: item.path,
-              sha256: item.sha256,
-              mtimeMs: typeof item.mtimeMs === "number" ? item.mtimeMs : void 0,
-              bytes: typeof item.bytes === "number" ? item.bytes : void 0
-            });
-          }
-        }
+      response = await fetchImpl(`${base}${route}`, { headers });
+    } catch (error) {
+      lastFailure = error instanceof Error ? error.message : String(error);
+      continue;
+    }
+    if (!response.ok) {
+      lastFailure = `HTTP ${response.status}`;
+      continue;
+    }
+    let data;
+    try {
+      data = await response.json();
+    } catch {
+      throw new Error(`invalid peer snapshot for namespace ${namespace}: response was not JSON`);
+    }
+    if (!data || typeof data !== "object" || !("files" in data) || !Array.isArray(data.files)) {
+      throw new Error(`invalid peer snapshot for namespace ${namespace}: files must be an array`);
+    }
+    const files = data.files.map((item, index) => {
+      if (!item || typeof item !== "object" || !("path" in item) || typeof item.path !== "string" || !("sha256" in item) || typeof item.sha256 !== "string") {
+        throw new Error(`invalid peer snapshot for namespace ${namespace}: malformed file at index ${index}`);
       }
-      const tombstones = /* @__PURE__ */ new Set();
-      if (Array.isArray(data.tombstones)) {
-        for (const tomb of data.tombstones) {
-          if (typeof tomb === "string" && /^[0-9a-f]{64}$/i.test(tomb)) {
-            tombstones.add(tomb.toLowerCase());
-          }
+      return {
+        path: item.path,
+        sha256: item.sha256,
+        mtimeMs: "mtimeMs" in item && typeof item.mtimeMs === "number" ? item.mtimeMs : void 0,
+        bytes: "bytes" in item && typeof item.bytes === "number" ? item.bytes : void 0
+      };
+    });
+    const rawTombstones = "tombstones" in data ? data.tombstones : void 0;
+    if (rawTombstones !== void 0 && !Array.isArray(rawTombstones)) {
+      throw new Error(`invalid peer snapshot for namespace ${namespace}: tombstones must be an array`);
+    }
+    const tombstones = /* @__PURE__ */ new Set();
+    for (const tombstone of rawTombstones ?? []) {
+      if (typeof tombstone !== "string" || !/^[0-9a-f]{64}$/i.test(tombstone)) {
+        throw new Error(`invalid peer snapshot for namespace ${namespace}: malformed tombstone`);
+      }
+      tombstones.add(tombstone.toLowerCase());
+    }
+    return { files, tombstones };
+  }
+  throw new Error(`failed to fetch peer snapshot for namespace ${namespace}: ${lastFailure}`);
+}
+function requiredResponseNumber(response, name) {
+  const raw = response.headers.get(name);
+  const value = raw === null ? Number.NaN : Number(raw);
+  if (!Number.isFinite(value) || value < 0) {
+    throw new Error(`offline file content response had invalid ${name}`);
+  }
+  return value;
+}
+async function fetchPeerFileContent(peerUrl, namespace, filePath, token, fetchImpl = globalThis.fetch) {
+  const base = peerUrl.replace(/\/+$/, "");
+  const routes = [
+    "/remnic/v1/offline-sync/file-content",
+    "/engram/v1/offline-sync/file-content"
+  ];
+  const headers = {
+    "content-type": "application/json",
+    ...token ? { authorization: `Bearer ${token}` } : {}
+  };
+  for (const route of routes) {
+    try {
+      const chunks = [];
+      const hash = createHash2("sha256");
+      let offset = 0;
+      let expectedBytes;
+      let expectedSha256;
+      let mtimeMs;
+      do {
+        const response = await fetchImpl(`${base}${route}`, {
+          method: "POST",
+          headers,
+          body: JSON.stringify({
+            namespace,
+            includeTranscripts: false,
+            path: filePath,
+            offset,
+            length: OFFLINE_SYNC_FILE_CONTENT_MAX_CHUNK_BYTES
+          })
+        });
+        if (!response.ok) throw new Error(`offline file content request failed: ${response.status}`);
+        const content = Buffer.from(await response.arrayBuffer());
+        const chunkOffset = requiredResponseNumber(response, "x-remnic-chunk-offset");
+        const chunkBytes = requiredResponseNumber(response, "x-remnic-chunk-bytes");
+        const totalBytes = requiredResponseNumber(response, "x-remnic-file-bytes");
+        const responseMtimeMs = requiredResponseNumber(response, "x-remnic-file-mtime-ms");
+        const sha256 = response.headers.get("x-remnic-file-sha256");
+        const encodedPath = response.headers.get("x-remnic-file-path");
+        if (!sha256 || chunkOffset !== offset || chunkBytes !== content.length || encodedPath !== null && decodeURIComponent(encodedPath) !== filePath || expectedBytes !== void 0 && expectedBytes !== totalBytes || expectedSha256 !== void 0 && expectedSha256 !== sha256) {
+          throw new Error(`offline file content response changed during transfer: ${filePath}`);
+        }
+        if (content.length === 0 && offset < totalBytes) {
+          throw new Error(`offline file content chunk was empty before EOF: ${filePath}`);
         }
+        expectedBytes = totalBytes;
+        expectedSha256 = sha256;
+        mtimeMs = responseMtimeMs;
+        chunks.push(content);
+        hash.update(content);
+        offset += content.length;
+      } while (expectedBytes === void 0 || offset < expectedBytes);
+      if (expectedBytes === void 0 || expectedSha256 === void 0 || mtimeMs === void 0 || offset !== expectedBytes || hash.digest("hex") !== expectedSha256) {
+        throw new Error(`offline file content checksum mismatch: ${filePath}`);
       }
-      return { files, tombstones };
+      return {
+        content: Buffer.concat(chunks, expectedBytes),
+        sha256: expectedSha256,
+        bytes: expectedBytes,
+        mtimeMs
+      };
+    } catch {
+    }
+  }
+  return null;
+}
+function withoutTrailingSlashes(value) {
+  let end = value.length;
+  while (end > 0 && value.charCodeAt(end - 1) === 47) end -= 1;
+  return value.slice(0, end);
+}
+async function postPeerFileContent(peerUrl, namespace, filePath, content, metadata, token, fetchImpl = globalThis.fetch) {
+  const base = withoutTrailingSlashes(peerUrl);
+  const routes = [
+    `/remnic/v1/offline-sync/apply-file-content?namespace=${encodeURIComponent(namespace)}`,
+    `/engram/v1/offline-sync/apply-file-content?namespace=${encodeURIComponent(namespace)}`
+  ];
+  let previousAttemptFailed = false;
+  for (const route of routes) {
+    try {
+      let offset = 0;
+      do {
+        const chunk = content.subarray(
+          offset,
+          Math.min(content.length, offset + OFFLINE_SYNC_FILE_CONTENT_TRANSFER_CHUNK_BYTES2)
+        );
+        const headers = {
+          "content-type": "application/octet-stream",
+          "x-remnic-include-transcripts": "false",
+          "x-remnic-source-id": encodeURIComponent("remnic-converge"),
+          "x-remnic-file-path": encodeURIComponent(filePath),
+          "x-remnic-file-sha256": metadata.sha256,
+          "x-remnic-file-bytes": String(content.length),
+          "x-remnic-file-mtime-ms": String(metadata.mtimeMs),
+          "x-remnic-chunk-offset": String(offset),
+          ...metadata.baseSha256 ? { "x-remnic-base-sha256": metadata.baseSha256 } : {},
+          ...token ? { authorization: `Bearer ${token}` } : {}
+        };
+        const response = await fetchImpl(`${base}${route}`, {
+          method: "POST",
+          headers,
+          body: new Uint8Array(chunk)
+        });
+        if (!response.ok) throw new Error(`offline apply-file-content request failed: ${response.status}`);
+        const result = await response.json().catch(() => null);
+        if (!result || typeof result !== "object" || !("done" in result) || typeof result.done !== "boolean" || !("applied" in result) || typeof result.applied !== "boolean" || !("skipped" in result) || typeof result.skipped !== "boolean" || "conflict" in result && result.conflict) {
+          return false;
+        }
+        if (result.done) {
+          if (result.skipped) return previousAttemptFailed ? "applied" : "skipped";
+          if (result.applied && offset + chunk.length === content.length) return "applied";
+          return false;
+        }
+        if (result.applied || result.skipped || chunk.length === 0) {
+          return false;
+        }
+        offset += chunk.length;
+      } while (offset < content.length);
+      return false;
     } catch {
+      previousAttemptFailed = true;
     }
   }
-  return { files: [], tombstones: /* @__PURE__ */ new Set() };
+  return false;
+}
+async function postPeerConvergenceComplete(peerUrl, namespaces, token, fetchImpl = globalThis.fetch) {
+  const base = withoutTrailingSlashes(peerUrl);
+  const query = namespaces.map((namespace) => `namespace=${encodeURIComponent(namespace)}`).join("&");
+  const routes = [
+    "/remnic/v1/offline-sync/convergence-complete",
+    "/engram/v1/offline-sync/convergence-complete"
+  ];
+  for (const route of routes) {
+    const response = await fetchImpl(`${base}${route}?${query}`, {
+      method: "POST",
+      headers: {
+        "x-remnic-source-id": encodeURIComponent("remnic-converge"),
+        ...token ? { authorization: `Bearer ${token}` } : {}
+      }
+    }).catch(() => null);
+    if (!response?.ok) continue;
+    const result = await response.json().catch(() => null);
+    if (result && typeof result === "object" && "namespaces" in result && Array.isArray(result.namespaces) && result.namespaces.length === namespaces.length && result.namespaces.every((namespace, index) => namespace === namespaces[index]) && "refreshed" in result && result.refreshed === true) {
+      return true;
+    }
+  }
+  return false;
 }
 async function computeConvergePlan(options = {}) {
+  const baseMap = /* @__PURE__ */ new Map();
   const namespacesToPlan = /* @__PURE__ */ new Set();
   const localMap = /* @__PURE__ */ new Map();
   const localTombstones = /* @__PURE__ */ new Map();
   const peerMap = /* @__PURE__ */ new Map();
   const peerTombstones = /* @__PURE__ */ new Map();
+  if (options.baseFilesByNamespace) {
+    for (const [ns, files] of options.baseFilesByNamespace) {
+      namespacesToPlan.add(ns);
+      baseMap.set(ns, files);
+    }
+  }
   if (options.localFilesByNamespace) {
     for (const [ns, files] of options.localFilesByNamespace) {
       namespacesToPlan.add(ns);
@@ -403,17 +851,328 @@ async function computeConvergePlan(options = {}) {
       peerTombstones.set(ns, peerData.tombstones);
     }
   }
+  const memoryDir = options.cursorDir ?? config?.memoryDir;
+  if (!options.baseFilesByNamespace && memoryDir && options.peerUrl) {
+    for (const ns of namespacesToPlan) {
+      const cursorPath = defaultConvergeCursorPath(memoryDir, options.peerUrl, ns);
+      const cursor = await readConvergeCursor(cursorPath);
+      if (cursor?.baseFiles && cursor.baseFiles.length > 0) {
+        baseMap.set(ns, cursor.baseFiles);
+      }
+    }
+  }
   const inputs = [];
   for (const ns of [...namespacesToPlan].sort()) {
     inputs.push({
       namespace: ns,
       local: localMap.get(ns) ?? [],
       peer: peerMap.get(ns) ?? [],
+      base: baseMap.get(ns),
       tombstonedFileSha256: localTombstones.get(ns) ?? [],
       peerTombstonedFileSha256: peerTombstones.get(ns) ?? []
     });
   }
-  return planReconciliation(inputs);
+  return planReconciliation(inputs, { conflictPolicy: options.conflictPolicy });
+}
+async function executeConvergeApply(options = {}) {
+  const conflictPolicy = options.conflictPolicy ?? "manual";
+  const plan = await computeConvergePlan({ ...options, conflictPolicy });
+  if (plan.converged && !options.dryRun) {
+    await updateCursorsForPlan(plan, options);
+    return {
+      converged: true,
+      status: "converged",
+      plan,
+      transfers: { pulled: 0, pushed: 0, conflictsResolved: 0, suppressed: 0, failed: 0 },
+      cursorUpdated: true
+    };
+  }
+  const unresolvedCount = plan.byNamespace.reduce((acc, report) => acc + report.unresolved, 0);
+  if (unresolvedCount > 0 && conflictPolicy === "manual") {
+    return {
+      converged: false,
+      status: "stopped_unresolved_conflicts",
+      plan,
+      transfers: { pulled: 0, pushed: 0, conflictsResolved: 0, suppressed: 0, failed: 0 },
+      cursorUpdated: false
+    };
+  }
+  const plannedTransfers = {
+    pulled: 0,
+    pushed: 0,
+    conflictsResolved: 0,
+    suppressed: 0,
+    failed: 0
+  };
+  for (const entry of plan.entries) {
+    if (entry.action === "pull") plannedTransfers.pulled += 1;
+    else if (entry.action === "push") plannedTransfers.pushed += 1;
+    else if (entry.action === "conflict") plannedTransfers.conflictsResolved += 1;
+    else if (entry.action === "suppress") plannedTransfers.suppressed += 1;
+  }
+  if (options.dryRun) {
+    return {
+      converged: false,
+      status: "dry_run",
+      plan,
+      transfers: plannedTransfers,
+      cursorUpdated: false
+    };
+  }
+  const actualTransfers = {
+    pulled: 0,
+    pushed: 0,
+    conflictsResolved: 0,
+    suppressed: 0,
+    failed: 0
+  };
+  const peerMutatedNamespaces = /* @__PURE__ */ new Set();
+  let resolvedToken;
+  if (options.peerToken) {
+    try {
+      resolvedToken = await resolveAgentAccessAuthToken(options.peerToken, {
+        resolveSecretRef: options.resolveSecretRef
+      });
+    } catch {
+      resolvedToken = options.peerToken;
+    }
+  }
+  const fetchFn = options.fetchImpl ?? globalThis.fetch;
+  let config = options.config;
+  if (!config) {
+    try {
+      config = parseConfig2({});
+    } catch {
+    }
+  }
+  const rootMap = /* @__PURE__ */ new Map();
+  if (config) {
+    try {
+      const roots = await resolveCorpusNamespaceRoots({ config });
+      for (const r of roots) {
+        rootMap.set(r.namespace, r.rootDir);
+      }
+    } catch {
+    }
+  }
+  for (const entry of plan.entries) {
+    if (entry.action === "identical") continue;
+    let transferType = "none";
+    if (entry.action === "pull") {
+      transferType = "pull";
+    } else if (entry.action === "push") {
+      transferType = "push";
+    } else if (entry.action === "suppress") {
+      transferType = "suppress";
+    } else if (entry.action === "conflict") {
+      if (entry.resolution === "peer-wins") {
+        transferType = "pull";
+      } else if (entry.resolution === "local-wins") {
+        transferType = "push";
+      } else if (entry.resolution === "supersede-link") {
+        if (entry.newerSide === "peer") transferType = "pull";
+        else if (entry.newerSide === "local") transferType = "push";
+      }
+    }
+    if (transferType === "pull") {
+      let remoteFile = null;
+      const buffered = options.peerFileBuffers?.get(entry.namespace)?.get(entry.path);
+      if (buffered) {
+        const state = options.peerFilesByNamespace?.get(entry.namespace)?.find((file) => file.path === entry.path);
+        remoteFile = {
+          content: buffered,
+          sha256: state?.sha256 ?? entry.peerSha256 ?? createHash2("sha256").update(buffered).digest("hex"),
+          bytes: buffered.length,
+          mtimeMs: state?.mtimeMs ?? 0
+        };
+      } else if (options.peerUrl) {
+        remoteFile = await fetchPeerFileContent(
+          options.peerUrl,
+          entry.namespace,
+          entry.path,
+          resolvedToken,
+          fetchFn
+        );
+      }
+      if (remoteFile !== null && (!entry.peerSha256 || remoteFile.sha256 === entry.peerSha256)) {
+        if (options.localFileBuffers) {
+          let nsMap = options.localFileBuffers.get(entry.namespace);
+          if (!nsMap) {
+            nsMap = /* @__PURE__ */ new Map();
+            options.localFileBuffers.set(entry.namespace, nsMap);
+          }
+          nsMap.set(entry.path, remoteFile.content);
+          if (entry.action === "conflict") actualTransfers.conflictsResolved += 1;
+          else actualTransfers.pulled += 1;
+        } else {
+          const rootDir = rootMap.get(entry.namespace);
+          if (rootDir) {
+            const io = await createOfflineStorageIo(rootDir);
+            const expectedLocalSha256 = entry.action === "conflict" ? entry.localSha256 : entry.baseSha256;
+            let offset = 0;
+            let transferComplete = false;
+            do {
+              const chunk = remoteFile.content.subarray(
+                offset,
+                Math.min(
+                  remoteFile.content.length,
+                  offset + OFFLINE_SYNC_FILE_CONTENT_TRANSFER_CHUNK_BYTES2
+                )
+              );
+              const chunkResult = await applyOfflineSyncFileContentChunk({
+                root: rootDir,
+                sourceId: "remnic-converge",
+                path: entry.path,
+                sha256: remoteFile.sha256,
+                bytes: remoteFile.bytes,
+                mtimeMs: remoteFile.mtimeMs,
+                offset,
+                content: chunk,
+                ...expectedLocalSha256 ? { baseSha256: expectedLocalSha256 } : {},
+                readFile: io.readFile,
+                readFileDigest: io.readFileDigest,
+                writeFile: io.writeFile,
+                writeStagingFile: io.writeStagingFile,
+                writeFileChunks: io.writeFileChunks
+              });
+              if (chunkResult.conflict) {
+                break;
+              }
+              if (chunkResult.done) {
+                transferComplete = chunkResult.applied || chunkResult.skipped;
+                break;
+              }
+              if (chunkResult.applied || chunkResult.skipped || chunk.length === 0) {
+                break;
+              }
+              offset += chunk.length;
+            } while (offset < remoteFile.content.length);
+            if (transferComplete) {
+              if (entry.action === "conflict") actualTransfers.conflictsResolved += 1;
+              else actualTransfers.pulled += 1;
+            } else {
+              actualTransfers.failed += 1;
+            }
+          } else {
+            actualTransfers.failed += 1;
+          }
+        }
+      } else {
+        actualTransfers.failed += 1;
+      }
+    } else if (transferType === "push") {
+      let content = null;
+      let mtimeMs = options.localFilesByNamespace?.get(entry.namespace)?.find((file) => file.path === entry.path)?.mtimeMs;
+      if (options.localFileBuffers?.get(entry.namespace)?.has(entry.path)) {
+        content = options.localFileBuffers.get(entry.namespace).get(entry.path);
+      } else {
+        const rootDir = rootMap.get(entry.namespace);
+        if (rootDir) {
+          const filePath = path2.join(rootDir, entry.path);
+          try {
+            const io = await createOfflineStorageIo(rootDir);
+            content = await io.readFile({ root: rootDir, path: entry.path, filePath });
+            mtimeMs ??= (await fs3.promises.stat(filePath)).mtimeMs;
+          } catch {
+            content = null;
+          }
+        }
+      }
+      if (content !== null) {
+        if (options.peerFileBuffers) {
+          let nsMap = options.peerFileBuffers.get(entry.namespace);
+          if (!nsMap) {
+            nsMap = /* @__PURE__ */ new Map();
+            options.peerFileBuffers.set(entry.namespace, nsMap);
+          }
+          nsMap.set(entry.path, content);
+          if (entry.action === "conflict") actualTransfers.conflictsResolved += 1;
+          else actualTransfers.pushed += 1;
+        } else if (options.peerUrl && entry.localSha256) {
+          const expectedPeerSha256 = entry.action === "conflict" ? entry.peerSha256 : entry.baseSha256;
+          const applied = await postPeerFileContent(
+            options.peerUrl,
+            entry.namespace,
+            entry.path,
+            content,
+            {
+              sha256: entry.localSha256,
+              mtimeMs: mtimeMs ?? 0,
+              ...expectedPeerSha256 ? { baseSha256: expectedPeerSha256 } : {}
+            },
+            resolvedToken,
+            fetchFn
+          );
+          if (applied) {
+            if (applied === "applied") peerMutatedNamespaces.add(entry.namespace);
+            if (entry.action === "conflict") actualTransfers.conflictsResolved += 1;
+            else actualTransfers.pushed += 1;
+          } else {
+            actualTransfers.failed += 1;
+          }
+        } else {
+          actualTransfers.failed += 1;
+        }
+      } else {
+        actualTransfers.failed += 1;
+      }
+    } else if (transferType === "suppress") {
+      actualTransfers.suppressed += 1;
+    }
+  }
+  if (options.peerUrl && peerMutatedNamespaces.size > 0) {
+    const namespaces = [...peerMutatedNamespaces].sort();
+    if (!await postPeerConvergenceComplete(
+      options.peerUrl,
+      namespaces,
+      resolvedToken,
+      fetchFn
+    )) {
+      actualTransfers.failed += 1;
+    }
+  }
+  let cursorUpdated = false;
+  if (actualTransfers.failed === 0) {
+    await updateCursorsForPlan(plan, options);
+    cursorUpdated = true;
+  }
+  return {
+    converged: actualTransfers.failed === 0,
+    status: "applied",
+    plan,
+    transfers: actualTransfers,
+    cursorUpdated
+  };
+}
+async function updateCursorsForPlan(plan, options) {
+  const peerUrl = options.peerUrl ?? "local";
+  let memoryDir;
+  if (options.cursorDir) {
+    memoryDir = options.cursorDir;
+  } else if (options.config) {
+    memoryDir = options.config.memoryDir;
+  }
+  if (!memoryDir) return;
+  const namespaces = new Set(plan.byNamespace.map((n) => n.namespace));
+  for (const ns of namespaces) {
+    const cursorPath = defaultConvergeCursorPath(memoryDir, peerUrl, ns);
+    const nsEntries = plan.entries.filter((e) => e.namespace === ns);
+    const baseFiles = nsEntries.map((e) => ({
+      path: e.path,
+      sha256: e.localSha256 ?? e.peerSha256 ?? "unknown"
+    }));
+    const cursorState = {
+      version: 1,
+      peerUrl,
+      namespace: ns,
+      lastConvergedAt: (/* @__PURE__ */ new Date()).toISOString(),
+      baseFiles
+    };
+    try {
+      await writeConvergeCursor(cursorPath, cursorState);
+    } catch {
+    }
+  }
 }
 function formatConvergeReport(plan) {
   const lines = [];
@@ -435,25 +1194,49 @@ function formatConvergeReport(plan) {
   }
   return lines.join("\n");
 }
+function formatConvergeApplyReport(result) {
+  const lines = [];
+  lines.push(`Convergence Execution Status: ${result.status.toUpperCase()}`);
+  lines.push(`Converged: ${result.converged ? "YES" : "NO"}`);
+  lines.push("");
+  lines.push("Transfers Executed:");
+  lines.push(`  pulled:             ${result.transfers.pulled}`);
+  lines.push(`  pushed:             ${result.transfers.pushed}`);
+  lines.push(`  conflictsResolved:  ${result.transfers.conflictsResolved}`);
+  lines.push(`  suppressed:         ${result.transfers.suppressed}`);
+  lines.push(`  failed:             ${result.transfers.failed}`);
+  lines.push("");
+  lines.push(formatConvergeReport(result.plan));
+  return lines.join("\n");
+}
 async function cmdConverge(action, rest, json) {
   if (action === "help" || action === "--help" || action === "-h" || rest.includes("--help") || rest.includes("-h")) {
-    console.log(`Usage: remnic converge plan [--peer <url>] [--token <token>] [--json]
+    console.log(`Usage: remnic converge <plan|apply> [options]
+
+Subcommands:
+  plan              Compute and display reconciliation plan
+  apply             Execute bidirectional converge transport (alias: transport, sync)
 
 Options:
   --peer <url>      Peer server URL (or --remote-url / --remote)
   --token <token>   Bearer token or SecretRef for peer authentication
+  --conflict-policy <policy>
+                    Conflict resolution policy (manual|newest-wins|keep-both)
+  --dry-run         Simulate transfers without mutating disk or remote peer
   --json            Output detailed JSON plan report
 `);
     return;
   }
-  if (action !== "plan") {
-    process.stderr.write(`converge: unknown action "${action}". Use: plan [options].
+  if (action !== "plan" && action !== "apply" && action !== "transport" && action !== "sync") {
+    process.stderr.write(`converge: unknown action "${action}". Use: plan or apply [options].
 `);
     process.exitCode = 2;
     return;
   }
   let peerUrl;
   let peerToken;
+  let dryRun = false;
+  let conflictPolicy;
   for (let i = 0; i < rest.length; i += 1) {
     const arg = rest[i];
     if ((arg === "--peer" || arg === "--remote-url" || arg === "--remote") && rest[i + 1]) {
@@ -462,13 +1245,35 @@ Options:
     } else if (arg === "--token" && rest[i + 1]) {
       peerToken = rest[i + 1];
       i += 1;
+    } else if (arg === "--dry-run") {
+      dryRun = true;
+    } else if (arg === "--conflict-policy" && rest[i + 1]) {
+      const pol = rest[i + 1];
+      if (pol === "manual" || pol === "newest-wins" || pol === "keep-both") {
+        conflictPolicy = pol;
+      }
+      i += 1;
     }
   }
-  const plan = await computeConvergePlan({ peerUrl, peerToken });
+  if (action === "plan") {
+    const plan = await computeConvergePlan({ peerUrl, peerToken, conflictPolicy });
+    if (json) {
+      console.log(JSON.stringify(plan, null, 2));
+    } else {
+      console.log(formatConvergeReport(plan));
+    }
+    return;
+  }
+  const result = await executeConvergeApply({
+    peerUrl,
+    peerToken,
+    dryRun,
+    conflictPolicy
+  });
   if (json) {
-    console.log(JSON.stringify(plan, null, 2));
+    console.log(JSON.stringify(result, null, 2));
   } else {
-    console.log(formatConvergeReport(plan));
+    console.log(formatConvergeApplyReport(result));
   }
 }
 
@@ -605,7 +1410,7 @@ function renderReplayResult(result, targetNamespace, format) {
 }
 
 // src/quarantine-replay.ts
-import * as fs3 from "fs";
+import * as fs4 from "fs";
 import { EngramAccessService, Orchestrator as Orchestrator2, initLogger, parseConfig as parseConfig3, resolveRemnicConfigRecord as resolveRemnicConfigRecord2 } from "@remnic/core";
 import { WriteQuarantineStore } from "@remnic/core/write-quarantine.js";
 function valueFlag(args, flag) {
@@ -654,7 +1459,7 @@ async function runQuarantineReplay(rest, format, resolveConfigPath2) {
   let orchestrator;
   try {
     const configPath = resolveConfigPath2();
-    const raw = fs3.existsSync(configPath) ? JSON.parse(fs3.readFileSync(configPath, "utf8")) : {};
+    const raw = fs4.existsSync(configPath) ? JSON.parse(fs4.readFileSync(configPath, "utf8")) : {};
     const config = parseConfig3(resolveRemnicConfigRecord2(raw));
     orchestrator = new Orchestrator2(config);
     await orchestrator.initialize();
@@ -686,7 +1491,7 @@ async function runQuarantineReplay(rest, format, resolveConfigPath2) {
 }
 
 // src/offline-impression-rotation.ts
-import fs4 from "fs";
+import fs5 from "fs";
 import { parseConfig as parseConfig4, resolveRemnicConfigRecord as resolveRemnicConfigRecord3, drainPendingImpressionsForOfflineSync } from "@remnic/core";
 import { LastRecallStore } from "@remnic/core/recall-state";
 function parseConfigQuietly(raw) {
@@ -721,7 +1526,7 @@ function pickOfflineConfigRecord(raw) {
 function resolveOfflineImpressionRotation(configPath) {
   let raw;
   try {
-    raw = fs4.existsSync(configPath) ? JSON.parse(fs4.readFileSync(configPath, "utf8")) : {};
+    raw = fs5.existsSync(configPath) ? JSON.parse(fs5.readFileSync(configPath, "utf8")) : {};
   } catch {
     throw new Error(
       `cannot read recall-impression rotation from ${configPath}: config file could not be read as JSON`
@@ -749,265 +1554,6 @@ async function drainOfflineSyncImpressions(memoryDir, rotation) {
   );
 }
 
-// src/offline-storage-io.ts
-import { mkdtemp, readdir, lstat, rm } from "fs/promises";
-import fs5 from "fs";
-import path2 from "path";
-import { createHash, createDecipheriv } from "crypto";
-import {
-  OFFLINE_SYNC_FILE_CONTENT_TRANSFER_CHUNK_BYTES,
-  StorageManager
-} from "@remnic/core";
-import { OFFLINE_DECRYPT_STAGING_DIR_PREFIX } from "@remnic/core/offline-sync-exclude-globs";
-import {
-  AUTH_TAG_LENGTH,
-  ENVELOPE_HEADER_SIZE,
-  ENVELOPE_LAYOUT,
-  ENVELOPE_SALT_LENGTH,
-  ENVELOPE_VERSION,
-  FILE_FORMAT_FLAGS,
-  FILE_FORMAT_VERSION,
-  IV_LENGTH,
-  MAGIC_BYTES,
-  MAGIC_HEADER_SIZE,
-  SecureStoreLockedError,
-  filePathAad,
-  isEncryptedFile,
-  keyring,
-  readHeader,
-  secureStoreDir
-} from "@remnic/core/secure-store";
-async function createConfiguredOfflineStorage(memoryDir, secureStoreEncryptOnWrite = true) {
-  const storage = new StorageManager(memoryDir);
-  const header = await readHeader(memoryDir);
-  let secureStoreKey = null;
-  let secureStoreRequired = false;
-  if (header) {
-    secureStoreRequired = true;
-    storage.setSecureStoreRequired(true);
-    const key = keyring.getKey(secureStoreDir(memoryDir));
-    if (key) {
-      await storage.setSecureStoreKeyAndWait(key, secureStoreEncryptOnWrite);
-      secureStoreKey = key;
-    }
-  }
-  return { storage, secureStoreKey, secureStoreRequired };
-}
-async function createOfflineStorageForPath(memoryDir, filePath, configured, secureStoreEncryptOnWrite) {
-  const memoryRoot = path2.resolve(memoryDir);
-  const stateDir = path2.dirname(filePath);
-  if (path2.basename(stateDir) !== "state" || path2.basename(filePath) !== "memory-lifecycle-ledger.jsonl") {
-    throw new Error(`invalid lifecycle ledger path: ${filePath}`);
-  }
-  const storageRoot = path2.resolve(path2.dirname(stateDir));
-  if (storageRoot !== memoryRoot && !storageRoot.startsWith(`${memoryRoot}${path2.sep}`)) {
-    throw new Error(`lifecycle ledger path is outside the offline memory directory: ${filePath}`);
-  }
-  const storage = new StorageManager(storageRoot);
-  if (configured.secureStoreRequired) {
-    storage.setSecureStoreRequired(true);
-  }
-  if (configured.secureStoreKey) {
-    await storage.setSecureStoreKeyAndWait(configured.secureStoreKey, secureStoreEncryptOnWrite);
-  }
-  return storage;
-}
-async function createOfflineStorageIo(memoryDir, configuredStorage) {
-  await cleanupOrphanedOfflineDecryptStaging(memoryDir);
-  const { storage, secureStoreKey } = configuredStorage ?? await createConfiguredOfflineStorage(memoryDir);
-  return {
-    readFile: async ({ filePath }) => storage.readOfflineSyncFile(filePath),
-    readFileDigest: async ({ filePath }) => {
-      const hash = createHash("sha256");
-      let bytes = 0;
-      for await (const rawChunk of readOfflineSyncFileChunks({
-        filePath,
-        memoryDir,
-        secureStoreKey,
-        chunkSize: OFFLINE_SYNC_FILE_CONTENT_TRANSFER_CHUNK_BYTES
-      })) {
-        const chunk = Buffer.isBuffer(rawChunk) ? rawChunk : Buffer.from(rawChunk);
-        hash.update(chunk);
-        bytes += chunk.length;
-      }
-      return {
-        sha256: hash.digest("hex"),
-        bytes
-      };
-    },
-    readFileChunks: ({ filePath, chunkSize }) => readOfflineSyncFileChunks({
-      filePath,
-      memoryDir,
-      secureStoreKey,
-      chunkSize
-    }),
-    writeFile: async ({ filePath, content }) => storage.writeOfflineSyncFile(filePath, content),
-    writeStagingFile: async ({ filePath, content }) => storage.writeOfflineSyncStagingFile(filePath, content),
-    writeFileChunks: async ({ filePath, chunks }) => storage.writeOfflineSyncFileChunks(filePath, chunks),
-    deleteFile: async ({ filePath }) => storage.deleteOfflineSyncFile(filePath)
-  };
-}
-var OFFLINE_DECRYPT_STAGING_ORPHAN_MS = 60 * 60 * 1e3;
-async function cleanupOrphanedOfflineDecryptStaging(memoryDir) {
-  let entries;
-  try {
-    entries = await readdir(memoryDir);
-  } catch {
-    return;
-  }
-  const now = Date.now();
-  for (const name of entries) {
-    if (!name.startsWith(OFFLINE_DECRYPT_STAGING_DIR_PREFIX)) continue;
-    const dir = path2.join(memoryDir, name);
-    try {
-      const info = await lstat(dir);
-      if (!info.isDirectory() || info.isSymbolicLink()) continue;
-      if (now - info.mtimeMs < OFFLINE_DECRYPT_STAGING_ORPHAN_MS) continue;
-      await rm(dir, { recursive: true, force: true });
-    } catch {
-    }
-  }
-}
-async function* readOfflineSyncFileChunks(options) {
-  const header = await readFilePrefix(options.filePath, MAGIC_HEADER_SIZE);
-  if (!isEncryptedFile(header)) {
-    yield* readPlainOfflineFileChunks(options.filePath, options.chunkSize);
-    return;
-  }
-  if (!options.secureStoreKey) {
-    throw new SecureStoreLockedError(
-      `secure-store is locked \u2014 cannot read encrypted file at ${options.filePath}. Run \`remnic secure-store unlock\` to decrypt.`
-    );
-  }
-  yield* readEncryptedOfflineFileChunks({
-    filePath: options.filePath,
-    memoryDir: options.memoryDir,
-    key: options.secureStoreKey,
-    chunkSize: options.chunkSize
-  });
-}
-async function readFilePrefix(filePath, length) {
-  const handle = await fs5.promises.open(filePath, "r");
-  try {
-    const out = Buffer.alloc(length);
-    const { bytesRead } = await handle.read(out, 0, length, 0);
-    return out.subarray(0, bytesRead);
-  } finally {
-    await handle.close();
-  }
-}
-async function* readPlainOfflineFileChunks(filePath, chunkSize) {
-  const stream = fs5.createReadStream(filePath, { highWaterMark: chunkSize });
-  for await (const chunk of stream) {
-    yield Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
-  }
-}
-async function* readEncryptedOfflineFileChunks(options) {
-  const header = await readFilePrefix(options.filePath, MAGIC_HEADER_SIZE + ENVELOPE_HEADER_SIZE);
-  if (header.length < MAGIC_HEADER_SIZE + ENVELOPE_HEADER_SIZE || !isEncryptedFile(header)) {
-    throw new Error(`secure-store encrypted file is truncated: ${options.filePath}`);
-  }
-  const version = header.readUInt8(MAGIC_BYTES.length);
-  const flags = header.readUInt8(MAGIC_BYTES.length + 1);
-  if (version !== FILE_FORMAT_VERSION) {
-    throw new Error(`secure-store file has unsupported version ${version}: ${options.filePath}`);
-  }
-  if (flags !== FILE_FORMAT_FLAGS) {
-    throw new Error(`secure-store file has unsupported flags 0x${flags.toString(16)}: ${options.filePath}`);
-  }
-  const envelopeHeader = header.subarray(MAGIC_HEADER_SIZE);
-  const envelopeVersion = envelopeHeader.readUInt8(ENVELOPE_LAYOUT.version);
-  if (envelopeVersion !== ENVELOPE_VERSION) {
-    throw new Error(`secure-store envelope has unsupported version ${envelopeVersion}: ${options.filePath}`);
-  }
-  const salt = envelopeHeader.subarray(
-    ENVELOPE_LAYOUT.salt,
-    ENVELOPE_LAYOUT.salt + ENVELOPE_SALT_LENGTH
-  );
-  const iv = envelopeHeader.subarray(ENVELOPE_LAYOUT.iv, ENVELOPE_LAYOUT.iv + IV_LENGTH);
-  const authTag = envelopeHeader.subarray(
-    ENVELOPE_LAYOUT.authTag,
-    ENVELOPE_LAYOUT.authTag + AUTH_TAG_LENGTH
-  );
-  const aadCandidates = offlineFileAadCandidates(options.filePath, options.memoryDir);
-  let lastError;
-  for (const aad of aadCandidates) {
-    const tempDir = await mkdtemp(path2.join(options.memoryDir, OFFLINE_DECRYPT_STAGING_DIR_PREFIX));
-    const tempPath = path2.join(tempDir, "content");
-    try {
-      const decipher = createDecipheriv("aes-256-gcm", options.key, iv, {
-        authTagLength: AUTH_TAG_LENGTH
-      });
-      decipher.setAuthTag(authTag);
-      decipher.setAAD(Buffer.concat([secureStoreEnvelopeHeaderAad(salt), aad]));
-      const output = fs5.createWriteStream(tempPath, { mode: 384 });
-      try {
-        const stream = fs5.createReadStream(options.filePath, {
-          start: MAGIC_HEADER_SIZE + ENVELOPE_HEADER_SIZE,
-          highWaterMark: options.chunkSize
-        });
-        for await (const encryptedChunk of stream) {
-          const plain = decipher.update(
-            Buffer.isBuffer(encryptedChunk) ? encryptedChunk : Buffer.from(encryptedChunk)
-          );
-          if (plain.length > 0 && !output.write(plain)) {
-            await new Promise((resolve, reject) => {
-              output.once("drain", resolve);
-              output.once("error", reject);
-            });
-          }
-        }
-        const finalPlain = decipher.final();
-        if (finalPlain.length > 0 && !output.write(finalPlain)) {
-          await new Promise((resolve, reject) => {
-            output.once("drain", resolve);
-            output.once("error", reject);
-          });
-        }
-      } finally {
-        await closeWriteStream(output);
-      }
-      yield* readPlainOfflineFileChunks(tempPath, options.chunkSize);
-      return;
-    } catch (error) {
-      lastError = error;
-    } finally {
-      await rm(tempDir, { recursive: true, force: true });
-    }
-  }
-  throw lastError instanceof Error ? lastError : new Error(`secure-store could not decrypt file: ${options.filePath}`);
-}
-function offlineFileAadCandidates(filePath, memoryDir) {
-  const candidates = [filePathAad(filePath, memoryDir)];
-  const relative = path2.relative(memoryDir, filePath);
-  if (!relative || relative.startsWith("..") || path2.isAbsolute(relative)) return candidates;
-  const parts = relative.split(path2.sep);
-  if (parts[0] === "namespaces" && parts.length >= 3 && parts[1]) {
-    candidates.push(filePathAad(filePath, path2.join(memoryDir, "namespaces", parts[1])));
-  }
-  const memoryParts = path2.resolve(memoryDir).split(path2.sep);
-  if (memoryParts.length >= 3 && memoryParts.at(-2) === "namespaces" && memoryParts.at(-1)) {
-    const topLevelRoot = memoryParts.slice(0, -2).join(path2.sep) || path2.sep;
-    const topRelative = path2.relative(topLevelRoot, filePath);
-    if (topRelative && !topRelative.startsWith("..") && !path2.isAbsolute(topRelative) && topRelative.split(path2.sep)[0] === "namespaces" && topRelative.split(path2.sep)[1] === memoryParts.at(-1)) {
-      candidates.push(filePathAad(filePath, topLevelRoot));
-    }
-  }
-  return candidates;
-}
-async function closeWriteStream(stream) {
-  await new Promise((resolve, reject) => {
-    stream.once("error", reject);
-    stream.end(() => resolve());
-  });
-}
-function secureStoreEnvelopeHeaderAad(salt) {
-  const out = Buffer.alloc(1 + ENVELOPE_SALT_LENGTH);
-  out.writeUInt8(ENVELOPE_VERSION, 0);
-  Buffer.from(salt).copy(out, 1);
-  return out;
-}
-
 // src/bench-build-freshness.ts
 import {
   existsSync as existsSync2,
@@ -5892,7 +6438,7 @@ async function calibrateBenchJudges(parsed, rawArgs) {
     );
     process.exit(1);
   }
-  const sourceResultSha256 = createHash2("sha256").update(fs12.readFileSync(latest.path)).digest("hex");
+  const sourceResultSha256 = createHash3("sha256").update(fs12.readFileSync(latest.path)).digest("hex");
   const expandedManifestPath = expandTilde(manifestPath);
   if (!bench.resolveLocalLabJudgeProviderConfig) {
     console.error(
@@ -6756,7 +7302,7 @@ function attachPreparedJudgeCalibration(result, judgeCalibration) {
 function hashCalibrationProviderConfig(config) {
   const canonicalize = (value, key = "") => {
     if (typeof value === "string" && /(?:api.?key|authorization|token|secret)/i.test(key)) {
-      return { secretSha256: createHash2("sha256").update(value).digest("hex") };
+      return { secretSha256: createHash3("sha256").update(value).digest("hex") };
     }
     if (Array.isArray(value)) return value.map((item) => canonicalize(item));
     if (value && typeof value === "object") {
@@ -6767,7 +7313,7 @@ function hashCalibrationProviderConfig(config) {
     }
     return value;
   };
-  return createHash2("sha256").update(JSON.stringify(canonicalize(config))).digest("hex");
+  return createHash3("sha256").update(JSON.stringify(canonicalize(config))).digest("hex");
 }
 function restoreOptionalEnv(key, previousValue) {
   if (previousValue === void 0) {
@@ -9199,7 +9745,7 @@ async function cmdSync(action, rest, json) {
 }
 function localOfflineSourceId(memoryDir) {
   const host = os.hostname() || "unknown-host";
-  const dirHash = createHash2("sha256").update(path15.resolve(memoryDir)).digest("hex").slice(0, 16);
+  const dirHash = createHash3("sha256").update(path15.resolve(memoryDir)).digest("hex").slice(0, 16);
   return `remnic-local:${host}:${dirHash}`;
 }
 function normalizeOfflineRemoteUrl(raw) {
@@ -9799,7 +10345,7 @@ function resolveOfflineDirectHydrationPath(memoryDir, relPath) {
   }
   return target;
 }
-var OFFLINE_SYNC_FILE_CONTENT_UPLOAD_CHUNK_BYTES = OFFLINE_SYNC_FILE_CONTENT_TRANSFER_CHUNK_BYTES2;
+var OFFLINE_SYNC_FILE_CONTENT_UPLOAD_CHUNK_BYTES = OFFLINE_SYNC_FILE_CONTENT_TRANSFER_CHUNK_BYTES3;
 async function pushOfflineFileContent(args) {
   if (args.readFileChunks) {
     return pushOfflineFileContentFromChunkReader(args);
@@ -9807,7 +10353,7 @@ async function pushOfflineFileContent(args) {
   let offset = 0;
   let finalResult = null;
   let remoteSatisfiedResult = null;
-  const hash = createHash2("sha256");
+  const hash = createHash3("sha256");
   let bytes = 0;
   while (offset < args.file.bytes || args.file.bytes === 0 && offset === 0) {
     const chunk = await readOfflineSyncFileContentChunk({
@@ -9868,7 +10414,7 @@ async function pushOfflineFileContentFromChunkReader(args) {
   if (stat.mtimeMs !== args.file.mtimeMs) {
     throw new Error(`local file changed while pushing offline content: ${args.file.path}`);
   }
-  const hash = createHash2("sha256");
+  const hash = createHash3("sha256");
   const chunks = args.readFileChunks({
     root: path15.resolve(args.memoryDir),
     path: args.file.path,
@@ -9882,7 +10428,7 @@ async function pushOfflineFileContentFromChunkReader(args) {
   for await (const rawChunk of chunks) {
     const chunk = Buffer.from(rawChunk);
     if (chunk.length === 0) continue;
-    if (chunk.length > OFFLINE_SYNC_FILE_CONTENT_MAX_CHUNK_BYTES) {
+    if (chunk.length > OFFLINE_SYNC_FILE_CONTENT_MAX_CHUNK_BYTES2) {
       throw new Error(`local offline content chunk exceeds max size: ${args.file.path}`);
     }
     if (pending) {
@@ -9967,7 +10513,7 @@ async function hydrateOfflineFileContent(args) {
       path: args.expected.path,
       offset,
       length: Math.min(
-        OFFLINE_SYNC_FILE_CONTENT_MAX_CHUNK_BYTES,
+        OFFLINE_SYNC_FILE_CONTENT_MAX_CHUNK_BYTES2,
         Math.max(1, args.expected.bytes - offset)
       )
     });
@@ -9978,7 +10524,7 @@ async function hydrateOfflineFileContent(args) {
       throw new Error(`remote offline content chunk was empty before EOF: ${args.expected.path}`);
     }
     try {
-      finalResult = await applyOfflineSyncFileContentChunk({
+      finalResult = await applyOfflineSyncFileContentChunk2({
         root: args.memoryDir,
         sourceId: args.sourceId,
         path: args.expected.path,