@remnic/cli 1.0.23 → 1.0.25

package/dist/index.js

@@ -5,6 +5,7 @@ import path11 from "path";
 import { createDecipheriv, createHash } from "crypto";
 import * as childProcess2 from "child_process";
 import { fileURLToPath as fileURLToPath4 } from "url";
+import { gzipSync } from "zlib";
 import {
   parseConfig,
   isOpenaiApiKeyDisabled,
@@ -91,15 +92,19 @@ import {
   OFFLINE_SYNC_APPLY_MAX_BODY_BYTES,
   OFFLINE_SYNC_FILE_CONTENT_MAX_CHUNK_BYTES,
   OFFLINE_SYNC_FILE_CONTENT_TRANSFER_CHUNK_BYTES,
+  OFFLINE_SYNC_SNAPSHOT_BASE_MAX_BODY_BYTES,
+  applyOfflineSyncFileContentChunk,
   applyOfflineSyncSnapshot,
-  buildOfflineSyncChangeset,
-  buildOfflineSyncSnapshot,
+  buildOfflineSyncChangesetFromSnapshot,
+  buildOfflineSyncSnapshotFromBase,
   defaultOfflineSyncStatePath,
   normalizeOfflineSyncSnapshot,
   offlineSyncStateFromSnapshot,
   readOfflineSyncFileContentChunk,
   readOfflineSyncState,
+  shouldPreferIncomingOfflineRuntimeFile,
   summarizeOfflineSyncPendingChanges,
+  summarizeOfflineSyncPendingFiles,
   writeOfflineSyncState,
   buildActionConfidenceInputFromOptions,
   evaluateActionConfidence,
@@ -6643,29 +6648,230 @@ function offlineEndpoint(remoteUrl, pathname, params = {}) {
   }
   return url.toString();
 }
+var OFFLINE_SYNC_REQUEST_TIMEOUT_DEFAULT_MS = 15 * 6e4;
+var OFFLINE_SYNC_SNAPSHOT_BASE_POST_PREFERRED_MAX_BODY_BYTES = 16 * 1024 * 1024;
+function parseOfflineSyncRequestTimeoutMs(raw, fallback = OFFLINE_SYNC_REQUEST_TIMEOUT_DEFAULT_MS) {
+  if (raw === void 0 || raw.trim().length === 0) return fallback;
+  const parsed = Number(raw);
+  if (!Number.isInteger(parsed) || parsed < 1e3) {
+    throw new Error("REMNIC_OFFLINE_REQUEST_TIMEOUT_MS must be an integer >= 1000");
+  }
+  return parsed;
+}
+function formatOfflineRequestForError(url, init = {}) {
+  const method = (init.method ?? "GET").toString().toUpperCase();
+  try {
+    const parsed = new URL(url);
+    return `${method} ${parsed.pathname}${parsed.search}`;
+  } catch {
+    return `${method} ${url}`;
+  }
+}
+function offlineRequestTimeoutMs() {
+  return parseOfflineSyncRequestTimeoutMs(
+    process.env.REMNIC_OFFLINE_REQUEST_TIMEOUT_MS ?? process.env.ENGRAM_OFFLINE_REQUEST_TIMEOUT_MS
+  );
+}
+function offlineFetchHeaders(token, initHeaders, defaultContentType) {
+  const headers = new Headers(initHeaders);
+  headers.set("authorization", `Bearer ${token}`);
+  if (defaultContentType && !headers.has("content-type")) {
+    headers.set("content-type", defaultContentType);
+  }
+  return headers;
+}
+async function fetchOfflineWithResponse(url, token, init = {}, options = {}, consume) {
+  const timeoutMs = offlineRequestTimeoutMs();
+  const controller = new AbortController();
+  const upstreamSignal = init.signal;
+  const requestContext = formatOfflineRequestForError(url, init);
+  let didTimeout = false;
+  const timeout = setTimeout(() => {
+    didTimeout = true;
+    controller.abort();
+  }, timeoutMs);
+  const abortFromUpstream = () => controller.abort(upstreamSignal?.reason);
+  if (upstreamSignal) {
+    if (upstreamSignal.aborted) controller.abort(upstreamSignal.reason);
+    else upstreamSignal.addEventListener("abort", abortFromUpstream, { once: true });
+  }
+  let response;
+  try {
+    response = await fetch(url, {
+      ...init,
+      signal: controller.signal,
+      headers: offlineFetchHeaders(token, init.headers, options.defaultContentType)
+    });
+  } catch (error) {
+    clearTimeout(timeout);
+    upstreamSignal?.removeEventListener("abort", abortFromUpstream);
+    if (didTimeout) {
+      throw new Error(`offline sync request timed out after ${timeoutMs}ms: ${requestContext}`);
+    }
+    const message = error instanceof Error ? error.message : String(error);
+    throw new Error(`offline sync request failed before response: ${requestContext} - ${message}`);
+  }
+  try {
+    return await consume(response);
+  } catch (error) {
+    if (didTimeout) {
+      throw new Error(`offline sync request timed out after ${timeoutMs}ms: ${requestContext}`);
+    }
+    throw error;
+  } finally {
+    clearTimeout(timeout);
+    upstreamSignal?.removeEventListener("abort", abortFromUpstream);
+  }
+}
+async function throwOfflineResponseError(response, url, init, label = "offline sync request") {
+  let detail = "";
+  try {
+    detail = await response.text();
+  } catch {
+    detail = "";
+  }
+  throw new Error(
+    `${label} failed: ${formatOfflineRequestForError(url, init)} returned ${response.status} ${response.statusText}${detail ? ` - ${detail.slice(0, 500)}` : ""}`
+  );
+}
 async function fetchOfflineJson(url, token, init = {}) {
-  const response = await fetch(url, {
-    ...init,
-    headers: {
-      authorization: `Bearer ${token}`,
-      ...init.body !== void 0 ? { "content-type": "application/json" } : {},
-      ...init.headers ?? {}
+  return fetchOfflineWithResponse(
+    url,
+    token,
+    init,
+    { defaultContentType: init.body !== void 0 ? "application/json" : void 0 },
+    async (response) => {
+      if (!response.ok) {
+        await throwOfflineResponseError(response, url, init);
+      }
+      return await response.json();
+    }
+  );
+}
+async function parseOfflineSnapshotStreamResponse(response) {
+  if (!response.body) {
+    throw new Error("offline sync snapshot stream response omitted body");
+  }
+  const reader = response.body.getReader();
+  const decoder = new TextDecoder();
+  let buffered = "";
+  let header = null;
+  const files = [];
+  const handleLine = (line) => {
+    if (line.trim().length === 0) return;
+    const parsed = JSON.parse(line);
+    if (parsed.type === "snapshot") {
+      if (header) throw new Error("offline sync snapshot stream repeated header");
+      header = {
+        ...typeof parsed.namespace === "string" && parsed.namespace.length > 0 ? { namespace: parsed.namespace } : {},
+        format: parsed.format,
+        schemaVersion: parsed.schemaVersion,
+        createdAt: parsed.createdAt,
+        sourceId: parsed.sourceId,
+        includeTranscripts: parsed.includeTranscripts
+      };
+      return;
     }
+    if (parsed.type === "file") {
+      if (!header) throw new Error("offline sync snapshot stream file arrived before header");
+      files.push(parsed.file);
+      return;
+    }
+    throw new Error("offline sync snapshot stream contained unknown event");
+  };
+  for (; ; ) {
+    const { value, done } = await reader.read();
+    if (done) break;
+    buffered += decoder.decode(value, { stream: true });
+    for (; ; ) {
+      const newline = buffered.indexOf("\n");
+      if (newline < 0) break;
+      const line = buffered.slice(0, newline);
+      buffered = buffered.slice(newline + 1);
+      handleLine(line);
+    }
+  }
+  buffered += decoder.decode();
+  handleLine(buffered);
+  const finalHeader = header;
+  if (!finalHeader) throw new Error("offline sync snapshot stream omitted header");
+  const snapshot = normalizeOfflineSyncSnapshot({
+    format: finalHeader.format,
+    schemaVersion: finalHeader.schemaVersion,
+    createdAt: finalHeader.createdAt,
+    sourceId: finalHeader.sourceId,
+    includeTranscripts: finalHeader.includeTranscripts,
+    files
   });
-  if (!response.ok) {
-    let detail = "";
-    try {
-      detail = await response.text();
-    } catch {
-      detail = "";
+  return {
+    ...finalHeader.namespace ? { namespace: finalHeader.namespace } : {},
+    ...snapshot
+  };
+}
+async function fetchOfflineSnapshotStream(args) {
+  const url = offlineEndpoint(args.remoteUrl, "/remnic/v1/offline-sync/snapshot-stream", {
+    namespace: args.namespace,
+    include_transcripts: args.includeTranscripts ? "true" : "false",
+    content: "false"
+  });
+  return fetchOfflineWithResponse(
+    url,
+    args.token,
+    {},
+    {},
+    async (response) => {
+      if (!response.ok) {
+        await throwOfflineResponseError(response, url, {}, "offline sync snapshot-stream request");
+      }
+      return parseOfflineSnapshotStreamResponse(response);
     }
-    throw new Error(
-      `offline sync request failed: ${response.status} ${response.statusText}${detail ? ` - ${detail.slice(0, 500)}` : ""}`
-    );
-  }
-  return await response.json();
+  );
 }
 async function fetchOfflineSnapshot(args) {
+  let tryStreamSnapshot = false;
+  if (args.includeContent === false && args.baseFiles && args.baseFiles.length > 0) {
+    if (args.baseFiles.length > OFFLINE_SYNC_SNAPSHOT_BASE_POST_MAX_FILES) {
+      tryStreamSnapshot = true;
+    } else {
+      const postBody = offlineSnapshotBasePostBody({
+        namespace: args.namespace,
+        includeTranscripts: args.includeTranscripts,
+        baseFiles: args.baseFiles,
+        baseCapturedAt: args.baseCapturedAt
+      });
+      const postRequest = offlineSnapshotBasePostRequest(postBody);
+      if (postRequest) {
+        const postRequestUsesGzip = new Headers(postRequest.headers).get("content-encoding")?.toLowerCase() === "gzip";
+        try {
+          return await fetchOfflineJson(
+            offlineEndpoint(args.remoteUrl, "/remnic/v1/offline-sync/snapshot"),
+            args.token,
+            {
+              method: "POST",
+              ...postRequest
+            }
+          );
+        } catch (error) {
+          if (!isOfflineSnapshotPostFallbackError(error, { compressed: postRequestUsesGzip })) throw error;
+          tryStreamSnapshot = true;
+        }
+      } else {
+        tryStreamSnapshot = true;
+      }
+    }
+  }
+  if (tryStreamSnapshot) {
+    try {
+      return await fetchOfflineSnapshotStream({
+        remoteUrl: args.remoteUrl,
+        token: args.token,
+        namespace: args.namespace,
+        includeTranscripts: args.includeTranscripts
+      });
+    } catch (error) {
+      if (!isOfflineSnapshotStreamFallbackError(error)) throw error;
+    }
+  }
   return fetchOfflineJson(
     offlineEndpoint(args.remoteUrl, "/remnic/v1/offline-sync/snapshot", {
       namespace: args.namespace,
@@ -6675,6 +6881,47 @@ async function fetchOfflineSnapshot(args) {
     args.token
   );
 }
+function offlineSnapshotBasePostBody(args) {
+  return JSON.stringify({
+    namespace: args.namespace,
+    includeTranscripts: args.includeTranscripts,
+    includeContent: false,
+    baseFiles: args.baseFiles,
+    ...args.baseCapturedAt ? { baseCapturedAt: args.baseCapturedAt.toISOString() } : {}
+  });
+}
+function offlineSnapshotBasePostBodyFits(body) {
+  const bytes = Buffer.byteLength(body, "utf-8");
+  return bytes <= OFFLINE_SYNC_SNAPSHOT_BASE_MAX_BODY_BYTES && bytes <= OFFLINE_SYNC_SNAPSHOT_BASE_POST_PREFERRED_MAX_BODY_BYTES;
+}
+var OFFLINE_SYNC_SNAPSHOT_BASE_POST_MAX_FILES = 5e4;
+function offlineSnapshotBasePostRequest(body) {
+  const bytes = Buffer.byteLength(body, "utf-8");
+  if (bytes > OFFLINE_SYNC_SNAPSHOT_BASE_MAX_BODY_BYTES) return null;
+  if (bytes <= OFFLINE_SYNC_SNAPSHOT_BASE_POST_PREFERRED_MAX_BODY_BYTES) {
+    return { body };
+  }
+  const compressed = gzipSync(body);
+  if (compressed.byteLength > OFFLINE_SYNC_SNAPSHOT_BASE_POST_PREFERRED_MAX_BODY_BYTES) {
+    return null;
+  }
+  return {
+    body: compressed,
+    headers: {
+      "content-encoding": "gzip"
+    }
+  };
+}
+function isOfflineSnapshotPostFallbackError(error, options = {}) {
+  const message = error instanceof Error ? error.message : String(error);
+  if (/offline-sync\/snapshot\b.* returned (404|405|413)\b/.test(message)) return true;
+  if (!options.compressed) return false;
+  return /offline-sync\/snapshot\b.* returned (400|415)\b/.test(message) && /\b(unsupported_content_encoding|invalid_gzip_body|invalid_json)\b/.test(message);
+}
+function isOfflineSnapshotStreamFallbackError(error) {
+  const message = error instanceof Error ? error.message : String(error);
+  return /offline-sync\/snapshot-stream\b.* returned (404|405)\b/.test(message);
+}
 async function fetchOfflineFiles(args) {
   return fetchOfflineJson(
     offlineEndpoint(args.remoteUrl, "/remnic/v1/offline-sync/files"),
@@ -6702,6 +6949,28 @@ var OFFLINE_SYNC_DIRECT_PUSH_MIN_BYTES = Math.min(
   OFFLINE_SYNC_INLINE_CONTENT_MAX_BYTES
 );
 var OFFLINE_SYNC_DIRECT_HYDRATE_MIN_BYTES = OFFLINE_SYNC_DIRECT_PUSH_MIN_BYTES;
+var OFFLINE_SYNC_CHANGESET_RETRY_MAX = 1024;
+var OfflineRemoteFileChangedError = class extends Error {
+  path;
+  constructor(path12) {
+    super(`remote file changed while fetching offline content: ${path12}`);
+    this.name = "OfflineRemoteFileChangedError";
+    this.path = path12;
+  }
+};
+function isOfflineRemoteFileChangedError(error) {
+  return error instanceof OfflineRemoteFileChangedError || error instanceof Error && error.message.startsWith("remote file changed while fetching offline content: ");
+}
+function isOfflineLocalFileChangedError(error) {
+  return error instanceof Error && error.message.startsWith("local file changed while pushing offline content: ");
+}
+function offlineChangesetFileChangedPath(error) {
+  if (!(error instanceof Error)) return null;
+  const prefix = "offline sync file changed while building changeset: ";
+  if (!error.message.startsWith(prefix)) return null;
+  const relPath = error.message.slice(prefix.length).trim();
+  return relPath.length > 0 ? relPath : null;
+}
 function parseOfflineHeaderNumber(headers, name) {
   const raw = headers.get(name);
   if (raw === null) throw new Error(`offline file content response omitted ${name}`);
@@ -6712,86 +6981,77 @@ function parseOfflineHeaderNumber(headers, name) {
   return parsed;
 }
 async function fetchOfflineFileContentChunk(args) {
-  const response = await fetch(
-    offlineEndpoint(args.remoteUrl, "/remnic/v1/offline-sync/file-content"),
-    {
-      method: "POST",
-      headers: {
-        authorization: `Bearer ${args.token}`,
-        "content-type": "application/json"
-      },
-      body: JSON.stringify({
-        namespace: args.namespace,
-        includeTranscripts: args.includeTranscripts,
-        path: args.path,
-        offset: args.offset,
-        length: args.length
-      })
+  const url = offlineEndpoint(args.remoteUrl, "/remnic/v1/offline-sync/file-content");
+  const init = {
+    method: "POST",
+    body: JSON.stringify({
+      namespace: args.namespace,
+      includeTranscripts: args.includeTranscripts,
+      path: args.path,
+      offset: args.offset,
+      length: args.length
+    })
+  };
+  return fetchOfflineWithResponse(
+    url,
+    args.token,
+    init,
+    { defaultContentType: "application/json" },
+    async (response) => {
+      if (!response.ok) {
+        await throwOfflineResponseError(response, url, init, "offline sync file-content request");
+      }
+      const encodedPath = response.headers.get("x-remnic-file-path");
+      const relPath = encodedPath ? decodeURIComponent(encodedPath) : args.path;
+      const content = Buffer.from(await response.arrayBuffer());
+      const chunkBytes = parseOfflineHeaderNumber(response.headers, "x-remnic-chunk-bytes");
+      const sha256 = response.headers.get("x-remnic-file-sha256") ?? void 0;
+      if (content.length !== chunkBytes) {
+        throw new Error(`offline file content response length mismatch for ${relPath}`);
+      }
+      return {
+        path: relPath,
+        ...sha256 ? { sha256 } : {},
+        bytes: parseOfflineHeaderNumber(response.headers, "x-remnic-file-bytes"),
+        mtimeMs: parseOfflineHeaderNumber(response.headers, "x-remnic-file-mtime-ms"),
+        offset: parseOfflineHeaderNumber(response.headers, "x-remnic-chunk-offset"),
+        chunkBytes,
+        content
+      };
     }
   );
-  if (!response.ok) {
-    let detail = "";
-    try {
-      detail = await response.text();
-    } catch {
-      detail = "";
-    }
-    throw new Error(
-      `offline sync file-content request failed: ${response.status} ${response.statusText}${detail ? ` - ${detail.slice(0, 500)}` : ""}`
-    );
-  }
-  const encodedPath = response.headers.get("x-remnic-file-path");
-  const relPath = encodedPath ? decodeURIComponent(encodedPath) : args.path;
-  const content = Buffer.from(await response.arrayBuffer());
-  const chunkBytes = parseOfflineHeaderNumber(response.headers, "x-remnic-chunk-bytes");
-  const sha256 = response.headers.get("x-remnic-file-sha256") ?? void 0;
-  if (content.length !== chunkBytes) {
-    throw new Error(`offline file content response length mismatch for ${relPath}`);
-  }
-  return {
-    path: relPath,
-    ...sha256 ? { sha256 } : {},
-    bytes: parseOfflineHeaderNumber(response.headers, "x-remnic-file-bytes"),
-    mtimeMs: parseOfflineHeaderNumber(response.headers, "x-remnic-file-mtime-ms"),
-    offset: parseOfflineHeaderNumber(response.headers, "x-remnic-chunk-offset"),
-    chunkBytes,
-    content
-  };
 }
 async function postOfflineFileContentChunk(args) {
-  const response = await fetch(
-    offlineEndpoint(args.remoteUrl, "/remnic/v1/offline-sync/apply-file-content", {
-      namespace: args.namespace
-    }),
-    {
-      method: "POST",
-      headers: {
-        authorization: `Bearer ${args.token}`,
-        "content-type": "application/octet-stream",
-        "x-remnic-include-transcripts": args.includeTranscripts ? "true" : "false",
-        "x-remnic-source-id": encodeURIComponent(args.sourceId),
-        "x-remnic-file-path": encodeURIComponent(args.file.path),
-        "x-remnic-file-sha256": args.file.sha256,
-        "x-remnic-file-bytes": String(args.file.bytes),
-        "x-remnic-file-mtime-ms": String(args.file.mtimeMs),
-        "x-remnic-chunk-offset": String(args.offset),
-        ...args.baseSha256 ? { "x-remnic-base-sha256": args.baseSha256 } : {}
-      },
-      body: new Blob([new Uint8Array(args.content)])
+  const url = offlineEndpoint(args.remoteUrl, "/remnic/v1/offline-sync/apply-file-content", {
+    namespace: args.namespace
+  });
+  const init = {
+    method: "POST",
+    headers: {
+      "content-type": "application/octet-stream",
+      "x-remnic-include-transcripts": args.includeTranscripts ? "true" : "false",
+      "x-remnic-source-id": encodeURIComponent(args.sourceId),
+      "x-remnic-file-path": encodeURIComponent(args.file.path),
+      "x-remnic-file-sha256": args.file.sha256,
+      "x-remnic-file-bytes": String(args.file.bytes),
+      "x-remnic-file-mtime-ms": String(args.file.mtimeMs),
+      "x-remnic-chunk-offset": String(args.offset),
+      ...args.baseSha256 ? { "x-remnic-base-sha256": args.baseSha256 } : {}
+    },
+    body: new Blob([new Uint8Array(args.content)])
+  };
+  return fetchOfflineWithResponse(
+    url,
+    args.token,
+    init,
+    {},
+    async (response) => {
+      if (!response.ok) {
+        await throwOfflineResponseError(response, url, init, "offline sync apply-file-content request");
+      }
+      return await response.json();
     }
   );
-  if (!response.ok) {
-    let detail = "";
-    try {
-      detail = await response.text();
-    } catch {
-      detail = "";
-    }
-    throw new Error(
-      `offline sync apply-file-content request failed: ${response.status} ${response.statusText}${detail ? ` - ${detail.slice(0, 500)}` : ""}`
-    );
-  }
-  return await response.json();
 }
 function resolvedOfflineSnapshotNamespace(snapshot, requestedNamespace) {
   const resolved = typeof snapshot.namespace === "string" && snapshot.namespace.trim().length > 0 ? snapshot.namespace.trim() : void 0;
@@ -6831,10 +7091,29 @@ function offlineFileStateMap(files) {
 function offlineSnapshotContentFilesForApply(options) {
   const base = offlineFileStateMap(options.baseFiles);
   const current = options.currentFiles ? offlineFileStateMap(options.currentFiles) : null;
+  const conflictContentMaxBytes = options.conflictContentMaxBytes ?? Number.POSITIVE_INFINITY;
+  const deferredPaths = new Set(options.deferredPaths ?? []);
   const files = [];
   for (const incoming of options.snapshot.files) {
-    if (current?.get(incoming.path)?.sha256 === incoming.sha256) continue;
-    if (base.get(incoming.path)?.sha256 === incoming.sha256) continue;
+    if (deferredPaths.has(incoming.path)) continue;
+    const baseEntry = base.get(incoming.path);
+    const currentEntry = current?.get(incoming.path);
+    if (currentEntry?.sha256 === incoming.sha256) continue;
+    if (currentEntry && baseEntry && incoming.sha256 === baseEntry.sha256) continue;
+    if (shouldPreferIncomingOfflineRuntimeFile(incoming.path)) {
+      files.push(incoming);
+      continue;
+    }
+    if (!currentEntry && baseEntry && incoming.sha256 === baseEntry.sha256) continue;
+    if (!currentEntry && !baseEntry) {
+      files.push(incoming);
+      continue;
+    }
+    if (baseEntry && currentEntry && currentEntry.sha256 === baseEntry.sha256) {
+      files.push(incoming);
+      continue;
+    }
+    if (incoming.bytes > conflictContentMaxBytes) continue;
     files.push(incoming);
   }
   return files.sort((left, right) => left.path.localeCompare(right.path));
@@ -6842,15 +7121,24 @@ function offlineSnapshotContentFilesForApply(options) {
 function shouldDirectHydrateOfflineFile(options) {
   if (options.incoming.bytes < OFFLINE_SYNC_DIRECT_HYDRATE_MIN_BYTES) return false;
   if (options.current?.sha256 === options.incoming.sha256) return false;
+  if (shouldPreferIncomingOfflineRuntimeFile(options.incoming.path)) return true;
   if (options.current && options.base && options.current.sha256 === options.base.sha256) {
     return true;
   }
   return !options.current && !options.base;
 }
+function offlinePartialHydrationForPaths(options) {
+  const hydratedPaths = new Set(options.hydratedPaths);
+  return {
+    hydratedFiles: options.files.filter((file) => hydratedPaths.has(file.path)),
+    remoteDeferredPaths: [...options.deferredPaths]
+  };
+}
 function offlineDirectPushFiles(options) {
   const base = offlineFileStateMap(options.baseFiles);
   return options.currentFiles.filter((current) => {
     if (current.bytes < OFFLINE_SYNC_DIRECT_PUSH_MIN_BYTES) return false;
+    if (shouldPreferIncomingOfflineRuntimeFile(current.path)) return false;
     return current.sha256 !== base.get(current.path)?.sha256;
   }).sort((left, right) => right.bytes - left.bytes || left.path.localeCompare(right.path));
 }
@@ -6870,6 +7158,9 @@ async function pushOfflineFileContent(args) {
   }
   let offset = 0;
   let finalResult = null;
+  let remoteSatisfiedResult = null;
+  const hash = createHash("sha256");
+  let bytes = 0;
   while (offset < args.file.bytes || args.file.bytes === 0 && offset === 0) {
     const chunk = await readOfflineSyncFileContentChunk({
       root: args.memoryDir,
@@ -6888,23 +7179,36 @@ async function pushOfflineFileContent(args) {
     if (chunk.chunkBytes === 0 && args.file.bytes > 0) {
       throw new Error(`local offline content chunk was empty before EOF: ${args.file.path}`);
     }
-    finalResult = await postOfflineFileContentChunk({
-      remoteUrl: args.remoteUrl,
-      token: args.token,
-      namespace: args.namespace,
-      includeTranscripts: args.includeTranscripts,
-      sourceId: args.sourceId,
-      file: args.file,
-      baseSha256: args.baseSha256,
-      offset,
-      content: chunk.content
-    });
-    if (finalResult.conflict) {
-      return finalResult;
+    hash.update(chunk.content);
+    bytes += chunk.chunkBytes;
+    if (!remoteSatisfiedResult) {
+      finalResult = await postOfflineFileContentChunk({
+        remoteUrl: args.remoteUrl,
+        token: args.token,
+        namespace: args.namespace,
+        includeTranscripts: args.includeTranscripts,
+        sourceId: args.sourceId,
+        file: args.file,
+        baseSha256: args.baseSha256,
+        offset,
+        content: chunk.content
+      });
+      if (finalResult.conflict) {
+        return finalResult;
+      }
+      if (finalResult.done && finalResult.skipped) {
+        remoteSatisfiedResult = finalResult;
+      }
     }
     offset += chunk.chunkBytes;
     if (args.file.bytes === 0) break;
   }
+  if (hash.digest("hex") !== args.file.sha256 || bytes !== args.file.bytes) {
+    throw new Error(`local file changed while pushing offline content: ${args.file.path}`);
+  }
+  if (remoteSatisfiedResult) {
+    return remoteSatisfiedResult;
+  }
   if (!finalResult?.done) {
     throw new Error(`offline sync large-file push did not finish for ${args.file.path}`);
   }
@@ -6926,6 +7230,7 @@ async function pushOfflineFileContentFromChunkReader(args) {
   let offset = 0;
   let pending = null;
   let finalResult = null;
+  let remoteSatisfiedResult = null;
   for await (const rawChunk of chunks) {
     const chunk = Buffer.from(rawChunk);
     if (chunk.length === 0) continue;
@@ -6934,19 +7239,24 @@ async function pushOfflineFileContentFromChunkReader(args) {
     }
     if (pending) {
       hash.update(pending);
-      finalResult = await postOfflineFileContentChunk({
-        remoteUrl: args.remoteUrl,
-        token: args.token,
-        namespace: args.namespace,
-        includeTranscripts: args.includeTranscripts,
-        sourceId: args.sourceId,
-        file: args.file,
-        baseSha256: args.baseSha256,
-        offset,
-        content: pending
-      });
-      if (finalResult.conflict) {
-        return finalResult;
+      if (!remoteSatisfiedResult) {
+        finalResult = await postOfflineFileContentChunk({
+          remoteUrl: args.remoteUrl,
+          token: args.token,
+          namespace: args.namespace,
+          includeTranscripts: args.includeTranscripts,
+          sourceId: args.sourceId,
+          file: args.file,
+          baseSha256: args.baseSha256,
+          offset,
+          content: pending
+        });
+        if (finalResult.conflict) {
+          return finalResult;
+        }
+        if (finalResult.done && finalResult.skipped) {
+          remoteSatisfiedResult = finalResult;
+        }
       }
       offset += pending.length;
     }
@@ -6958,6 +7268,9 @@ async function pushOfflineFileContentFromChunkReader(args) {
   if (digest !== args.file.sha256 || finalBytes !== args.file.bytes) {
     throw new Error(`local file changed while pushing offline content: ${args.file.path}`);
   }
+  if (remoteSatisfiedResult) {
+    return remoteSatisfiedResult;
+  }
   if (pending) {
     finalResult = await postOfflineFileContentChunk({
       remoteUrl: args.remoteUrl,
@@ -6973,6 +7286,9 @@ async function pushOfflineFileContentFromChunkReader(args) {
     if (finalResult.conflict) {
       return finalResult;
     }
+    if (finalResult.done && finalResult.skipped) {
+      return finalResult;
+    }
   } else if (args.file.bytes === 0) {
     finalResult = await postOfflineFileContentChunk({
       remoteUrl: args.remoteUrl,
@@ -6991,11 +7307,10 @@ async function pushOfflineFileContentFromChunkReader(args) {
   }
   return finalResult;
 }
-async function fetchOfflineFileContent(args) {
-  const chunks = [];
-  const hash = createHash("sha256");
+async function hydrateOfflineFileContent(args) {
   let offset = 0;
-  while (offset < args.expected.bytes) {
+  let finalResult = null;
+  while (offset < args.expected.bytes || args.expected.bytes === 0 && offset === 0) {
     const chunk = await fetchOfflineFileContentChunk({
       remoteUrl: args.remoteUrl,
       token: args.token,
@@ -7005,54 +7320,92 @@ async function fetchOfflineFileContent(args) {
       offset,
       length: Math.min(
         OFFLINE_SYNC_FILE_CONTENT_MAX_CHUNK_BYTES,
-        args.expected.bytes - offset
+        Math.max(1, args.expected.bytes - offset)
       )
     });
     if (chunk.path !== args.expected.path || chunk.sha256 !== void 0 && chunk.sha256 !== args.expected.sha256 || chunk.bytes !== args.expected.bytes || chunk.mtimeMs !== args.expected.mtimeMs || chunk.offset !== offset || chunk.chunkBytes !== chunk.content.length) {
-      throw new Error(`remote file changed while fetching offline content: ${args.expected.path}`);
+      throw new OfflineRemoteFileChangedError(args.expected.path);
     }
-    if (chunk.chunkBytes === 0) {
+    if (chunk.chunkBytes === 0 && args.expected.bytes > 0) {
       throw new Error(`remote offline content chunk was empty before EOF: ${args.expected.path}`);
     }
-    chunks.push(chunk.content);
-    hash.update(chunk.content);
+    finalResult = await applyOfflineSyncFileContentChunk({
+      root: args.memoryDir,
+      sourceId: args.sourceId,
+      path: args.expected.path,
+      sha256: args.expected.sha256,
+      bytes: args.expected.bytes,
+      mtimeMs: args.expected.mtimeMs,
+      offset,
+      content: chunk.content,
+      ...args.baseSha256 ? { baseSha256: args.baseSha256 } : {},
+      includeTranscripts: args.includeTranscripts,
+      readFile: args.readFile,
+      readFileDigest: args.readFileDigest,
+      writeFile: args.writeFile,
+      writeStagingFile: args.writeStagingFile,
+      writeFileChunks: args.writeFileChunks
+    });
+    if (finalResult.conflict) {
+      return finalResult;
+    }
+    if (finalResult.done && finalResult.skipped) {
+      return finalResult;
+    }
     offset += chunk.chunkBytes;
+    if (args.expected.bytes === 0) break;
   }
-  const content = Buffer.concat(chunks, offset);
-  const digest = hash.digest("hex");
-  if (digest !== args.expected.sha256 || content.length !== args.expected.bytes) {
-    throw new Error(`remote offline content checksum mismatch for ${args.expected.path}`);
+  if (!finalResult?.done) {
+    throw new Error(`offline sync large-file hydrate did not finish for ${args.expected.path}`);
   }
-  return content;
+  return finalResult;
 }
 async function directHydrateLargeOfflineFiles(args) {
-  if (!args.writeFile) return /* @__PURE__ */ new Set();
+  if (!args.readFile || !args.writeFile || !args.writeStagingFile || !args.writeFileChunks) {
+    return { hydratedPaths: /* @__PURE__ */ new Set(), deferredPaths: /* @__PURE__ */ new Set() };
+  }
   const snapshot = normalizeOfflineSyncSnapshot(args.snapshot);
   const base = offlineFileStateMap(args.baseFiles);
   const current = offlineFileStateMap(args.currentFiles);
-  const hydrated = /* @__PURE__ */ new Set();
+  const hydratedPaths = args.hydrationProgress?.hydratedPaths ?? /* @__PURE__ */ new Set();
+  const deferredPaths = args.hydrationProgress?.deferredPaths ?? /* @__PURE__ */ new Set();
   const candidates = snapshot.files.filter((incoming) => shouldDirectHydrateOfflineFile({
     incoming,
     base: base.get(incoming.path),
     current: current.get(incoming.path)
   })).sort((left, right) => right.bytes - left.bytes || left.path.localeCompare(right.path));
   for (const incoming of candidates) {
-    const content = await fetchOfflineFileContent({
-      remoteUrl: args.remoteUrl,
-      token: args.token,
-      namespace: args.namespace,
-      includeTranscripts: args.includeTranscripts,
-      expected: incoming
-    });
-    await args.writeFile({
-      root: args.memoryDir,
-      path: incoming.path,
-      filePath: resolveOfflineDirectHydrationPath(args.memoryDir, incoming.path),
-      content
-    });
-    hydrated.add(incoming.path);
+    let result;
+    try {
+      result = await hydrateOfflineFileContent({
+        remoteUrl: args.remoteUrl,
+        token: args.token,
+        namespace: args.namespace,
+        includeTranscripts: args.includeTranscripts,
+        memoryDir: args.memoryDir,
+        sourceId: "remote",
+        expected: incoming,
+        baseSha256: base.get(incoming.path)?.sha256,
+        readFile: args.readFile,
+        readFileDigest: args.readFileDigest,
+        writeFile: args.writeFile,
+        writeStagingFile: args.writeStagingFile,
+        writeFileChunks: args.writeFileChunks
+      });
+    } catch (error) {
+      if (!isOfflineRemoteFileChangedError(error)) throw error;
+      deferredPaths.add(incoming.path);
+      continue;
+    }
+    if (result.conflict) {
+      deferredPaths.add(result.conflict.path);
+      continue;
+    }
+    if (result.applied || result.skipped) {
+      hydratedPaths.add(incoming.path);
+    }
   }
-  return hydrated;
+  return { hydratedPaths, deferredPaths };
 }
 function chunkOfflineFileContentBatches(files) {
   const chunks = [];
@@ -7076,7 +7429,7 @@ function chunkOfflineFileContentBatches(files) {
 }
 function isOfflineFilesUnsupportedError(error) {
   const message = error instanceof Error ? error.message : String(error);
-  return /offline sync request failed: 404\b/.test(message);
+  return /offline sync request failed: .* returned 404\b/.test(message);
 }
 function isMissingOfflineContentError(error) {
   const message = error instanceof Error ? error.message : String(error);
@@ -7087,7 +7440,9 @@ async function hydrateOfflineSnapshotContent(args) {
   const neededFiles = offlineSnapshotContentFilesForApply({
     snapshot,
     baseFiles: args.baseFiles,
-    currentFiles: args.currentFiles
+    currentFiles: args.currentFiles,
+    conflictContentMaxBytes: OFFLINE_SYNC_FILES_CONTENT_MAX_BATCH_BYTES,
+    deferredPaths: args.deferredPaths
   });
   if (neededFiles.length === 0) return { ...args.snapshot, files: snapshot.files };
   const expectedByPath = new Map(snapshot.files.map((file) => [file.path, file]));
@@ -7180,7 +7535,8 @@ async function postOfflineChangesBatch(args) {
       method: "POST",
       body: JSON.stringify({
         namespace: args.namespace,
-        changeset: args.changeset
+        changeset: args.changeset,
+        returnCurrentFiles: false
       })
     }
   );
@@ -7201,6 +7557,7 @@ async function pushOfflineChanges(args) {
     appliedDeletes += result.appliedDeletes;
     skipped += result.skipped;
     conflicts.push(...result.conflicts);
+    args.onBatchApplied?.({ changeset, result });
   }
   return {
     namespace,
@@ -7246,6 +7603,24 @@ async function createOfflineStorageIo(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_UPLOAD_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,
@@ -7253,6 +7628,8 @@ async function createOfflineStorageIo(memoryDir) {
       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)
   };
 }
@@ -7366,6 +7743,39 @@ var OfflineLargeFilePushError = class extends Error {
     this.failures = failures;
   }
 };
+function advanceOfflineBaseFilesForSuccessfulPush(options) {
+  const next = offlineFileStateMap(options.baseFiles);
+  const current = offlineFileStateMap(options.currentFiles);
+  const conflictPaths = new Set((options.conflicts ?? []).map((conflict) => conflict.path));
+  for (const relPath of options.directPushedPaths ?? []) {
+    if (conflictPaths.has(relPath)) continue;
+    const file = current.get(relPath);
+    if (file) next.set(relPath, file);
+  }
+  for (const change of options.changeset.changes) {
+    if (conflictPaths.has(change.path)) continue;
+    if (change.type === "delete") {
+      next.delete(change.path);
+    } else {
+      next.set(change.path, {
+        path: change.file.path,
+        sha256: change.file.sha256,
+        bytes: change.file.bytes,
+        mtimeMs: change.file.mtimeMs
+      });
+    }
+  }
+  for (const file of options.hydratedFiles ?? []) {
+    if (conflictPaths.has(file.path)) continue;
+    next.set(file.path, {
+      path: file.path,
+      sha256: file.sha256,
+      bytes: file.bytes,
+      mtimeMs: file.mtimeMs
+    });
+  }
+  return [...next.values()].sort((left, right) => left.path.localeCompare(right.path));
+}
 async function runOfflineSyncOnce(options) {
   fs7.mkdirSync(options.memoryDir, { recursive: true });
   let activeStatePath = options.statePath;
@@ -7404,21 +7814,23 @@ async function runOfflineSyncOnce(options) {
     });
   }
   const baseFiles = priorState?.baseFiles ?? [];
+  const baseCapturedAt = priorState ? new Date(priorState.lastSyncedAt) : void 0;
   const storageIo = await createOfflineStorageIo(options.memoryDir);
   const localSourceId = localOfflineSourceId(options.memoryDir);
-  const pendingSummary = await summarizeOfflineSyncPendingChanges({
+  const currentSnapshotForPush = await buildOfflineSyncSnapshotFromBase({
     root: options.memoryDir,
     sourceId: localSourceId,
     baseFiles,
-    includeTranscripts: options.includeTranscripts,
-    readFile: storageIo.readFile
-  });
-  const currentSnapshotForPush = await buildOfflineSyncSnapshot({
-    root: options.memoryDir,
-    sourceId: localSourceId,
+    baseCapturedAt,
     includeContent: false,
     includeTranscripts: options.includeTranscripts,
-    readFile: storageIo.readFile
+    readFile: storageIo.readFile,
+    readFileDigest: storageIo.readFileDigest
+  });
+  const pendingSummary = summarizeOfflineSyncPendingFiles({
+    baseFiles,
+    currentFiles: currentSnapshotForPush.files,
+    includeTranscripts: options.includeTranscripts
   });
   const baseByPath = offlineFileStateMap(baseFiles);
   let directPushAppliedUpserts = 0;
@@ -7426,6 +7838,7 @@ async function runOfflineSyncOnce(options) {
   let directPushNamespace;
   const directPushConflicts = [];
   const directPushedPaths = /* @__PURE__ */ new Set();
+  const directPushDeferredPaths = /* @__PURE__ */ new Set();
   const directPushFailures = [];
   for (const file of offlineDirectPushFiles({
     currentFiles: currentSnapshotForPush.files,
@@ -7446,6 +7859,10 @@ async function runOfflineSyncOnce(options) {
         readFileChunks: storageIo.readFileChunks
       });
     } catch (error) {
+      if (isOfflineLocalFileChangedError(error)) {
+        directPushDeferredPaths.add(file.path);
+        continue;
+      }
       directPushFailures.push({
         path: file.path,
         error: error instanceof Error ? error.message : String(error)
@@ -7465,100 +7882,343 @@ async function runOfflineSyncOnce(options) {
       if (result.skipped) directPushSkipped += 1;
     }
   }
-  if (directPushFailures.length > 0) {
-    throw new OfflineLargeFilePushError(directPushFailures);
-  }
-  const changeset = await buildOfflineSyncChangeset({
-    root: options.memoryDir,
+  let changeset = {
+    format: "remnic.offline-sync.changeset.v1",
+    schemaVersion: 1,
+    createdAt: (/* @__PURE__ */ new Date()).toISOString(),
     sourceId: localSourceId,
-    baseFiles,
-    excludePaths: [...directPushedPaths],
     includeTranscripts: options.includeTranscripts,
-    readFile: storageIo.readFile
-  });
-  const pushedInline = changeset.changes.length > 0 ? await pushOfflineChanges({
-    remoteUrl: options.remoteUrl,
-    token: options.token,
-    namespace: syncNamespace,
-    changeset
-  }) : null;
-  const pushed = directPushedPaths.size > 0 || pushedInline ? {
-    namespace: pushedInline?.namespace ?? directPushNamespace ?? syncNamespace ?? "",
-    appliedUpserts: (pushedInline?.appliedUpserts ?? 0) + directPushAppliedUpserts,
-    appliedDeletes: pushedInline?.appliedDeletes ?? 0,
-    skipped: (pushedInline?.skipped ?? 0) + directPushSkipped,
-    conflicts: [...directPushConflicts, ...pushedInline?.conflicts ?? []]
+    changes: []
+  };
+  let pushed = null;
+  const buildPushedSummary = (pushedInline2) => directPushedPaths.size > 0 || pushedInline2 ? {
+    namespace: pushedInline2?.namespace ?? directPushNamespace ?? syncNamespace ?? "",
+    appliedUpserts: (pushedInline2?.appliedUpserts ?? 0) + directPushAppliedUpserts,
+    appliedDeletes: pushedInline2?.appliedDeletes ?? 0,
+    skipped: (pushedInline2?.skipped ?? 0) + directPushSkipped,
+    conflicts: [...directPushConflicts, ...pushedInline2?.conflicts ?? []]
   } : null;
-  const remoteSnapshotMetadata = await fetchOfflineSnapshot({
-    remoteUrl: options.remoteUrl,
-    token: options.token,
-    namespace: syncNamespace,
-    includeTranscripts: options.includeTranscripts,
-    includeContent: false
-  });
-  const currentSnapshot = await buildOfflineSyncSnapshot({
-    root: options.memoryDir,
-    sourceId: localSourceId,
-    includeContent: false,
-    includeTranscripts: options.includeTranscripts,
-    readFile: storageIo.readFile
+  const mergeInlinePushSummary = (prior, result) => ({
+    namespace: result.namespace || prior?.namespace || syncNamespace || "",
+    appliedUpserts: (prior?.appliedUpserts ?? 0) + result.appliedUpserts,
+    appliedDeletes: (prior?.appliedDeletes ?? 0) + result.appliedDeletes,
+    skipped: (prior?.skipped ?? 0) + result.skipped,
+    conflicts: [...prior?.conflicts ?? [], ...result.conflicts]
   });
-  const directHydratedPaths = await directHydrateLargeOfflineFiles({
-    remoteUrl: options.remoteUrl,
-    token: options.token,
-    namespace: syncNamespace,
-    includeTranscripts: options.includeTranscripts,
-    snapshot: remoteSnapshotMetadata,
-    baseFiles,
-    currentFiles: currentSnapshot.files,
+  pushed = buildPushedSummary(null);
+  const stateWritePathsFor = (resolvedNamespace2) => offlineStatePathsForNamespace({
     memoryDir: options.memoryDir,
-    writeFile: storageIo.writeFile
+    remoteUrl: options.remoteUrl,
+    requestedNamespace: options.namespace,
+    resolvedNamespace: resolvedNamespace2,
+    explicitStatePath: options.statePathExplicit ? activeStatePath : void 0
   });
-  const applyCurrentSnapshot = directHydratedPaths.size > 0 ? await buildOfflineSyncSnapshot({
+  const writePartialPushState = async (error, partial, checkpointChangeset = changeset) => {
+    const resolvedNamespace2 = partial?.resolvedNamespace ?? resolvedOfflineSnapshotNamespace({ namespace: pushed?.namespace ?? "" }, syncNamespace);
+    const stateWritePaths2 = stateWritePathsFor(resolvedNamespace2);
+    const nextBaseFiles = advanceOfflineBaseFilesForSuccessfulPush({
+      baseFiles,
+      currentFiles: currentSnapshotForPush.files,
+      directPushedPaths: [...directPushedPaths],
+      hydratedFiles: partial?.hydratedFiles,
+      changeset: checkpointChangeset,
+      conflicts: pushed?.conflicts ?? directPushConflicts
+    });
+    const state2 = {
+      version: 1,
+      remoteId: options.remoteUrl,
+      ...resolvedNamespace2 ? { namespace: resolvedNamespace2 } : {},
+      includeTranscripts: options.includeTranscripts,
+      // Partial checkpoints do not recapture conflicted/deferred paths, so keep
+      // the original capture time for safe fast-base reuse on the next run.
+      lastSyncedAt: priorState?.lastSyncedAt ?? (/* @__PURE__ */ new Date()).toISOString(),
+      baseFiles: nextBaseFiles
+    };
+    for (const statePath of stateWritePaths2) {
+      await writeOfflineSyncState(statePath, state2);
+    }
+    const message = error instanceof Error ? error.message : String(error);
+    return {
+      statePath: stateWritePaths2[0] ?? activeStatePath,
+      namespace: resolvedNamespace2,
+      prepared: priorState === null,
+      pushed,
+      pull: null,
+      pullError: message,
+      partial: true,
+      pendingSummary,
+      remoteFileCount: partial?.remoteFileCount ?? null,
+      deferred: {
+        localChangedDuringPush: [...directPushDeferredPaths].sort(),
+        remoteChangedDuringHydrate: [...partial?.remoteDeferredPaths ?? []].sort(),
+        total: directPushDeferredPaths.size + (partial?.remoteDeferredPaths?.length ?? 0)
+      }
+    };
+  };
+  if (directPushFailures.length > 0) {
+    const error = new OfflineLargeFilePushError(directPushFailures);
+    if (pushed) return writePartialPushState(error);
+    throw error;
+  }
+  let currentSnapshotForChangeset = directPushedPaths.size > 0 ? await buildOfflineSyncSnapshotFromBase({
     root: options.memoryDir,
     sourceId: localSourceId,
+    baseFiles,
+    baseCapturedAt,
     includeContent: false,
     includeTranscripts: options.includeTranscripts,
-    readFile: storageIo.readFile
-  }) : currentSnapshot;
-  const remoteSnapshot = await hydrateOfflineSnapshotContent({
-    remoteUrl: options.remoteUrl,
-    token: options.token,
-    namespace: syncNamespace,
-    includeTranscripts: options.includeTranscripts,
-    snapshot: remoteSnapshotMetadata,
-    baseFiles,
-    currentFiles: applyCurrentSnapshot.files
-  });
-  const resolvedNamespace = resolvedOfflineSnapshotNamespace(remoteSnapshot, syncNamespace);
-  let pull;
+    readFile: storageIo.readFile,
+    readFileDigest: storageIo.readFileDigest
+  }) : currentSnapshotForPush;
+  let changesetRetryCount = 0;
+  for (; ; ) {
+    try {
+      changeset = await buildOfflineSyncChangesetFromSnapshot({
+        root: options.memoryDir,
+        sourceId: localSourceId,
+        currentFiles: currentSnapshotForChangeset.files,
+        baseFiles,
+        excludePaths: [...directPushedPaths, ...directPushDeferredPaths],
+        includeTranscripts: options.includeTranscripts,
+        readFile: storageIo.readFile
+      });
+      break;
+    } catch (error) {
+      const changedPath = offlineChangesetFileChangedPath(error);
+      if (!changedPath) {
+        if (pushed) return writePartialPushState(error);
+        throw error;
+      }
+      if (directPushDeferredPaths.has(changedPath)) {
+        const stalledError = new Error(`offline sync changeset retry stalled on already-deferred path: ${changedPath}`);
+        if (pushed) return writePartialPushState(stalledError);
+        throw stalledError;
+      }
+      if (changesetRetryCount >= OFFLINE_SYNC_CHANGESET_RETRY_MAX) {
+        const retryError = new Error(
+          `offline sync changeset retry limit exceeded after ${OFFLINE_SYNC_CHANGESET_RETRY_MAX} volatile files; last changed path: ${changedPath}`
+        );
+        if (pushed) return writePartialPushState(retryError);
+        throw retryError;
+      }
+      changesetRetryCount += 1;
+      directPushDeferredPaths.add(changedPath);
+      currentSnapshotForChangeset = await buildOfflineSyncSnapshotFromBase({
+        root: options.memoryDir,
+        sourceId: localSourceId,
+        baseFiles,
+        baseCapturedAt,
+        includeContent: false,
+        includeTranscripts: options.includeTranscripts,
+        readFile: storageIo.readFile,
+        readFileDigest: storageIo.readFileDigest
+      });
+    }
+  }
+  const inlineAppliedChanges = [];
+  let pushedInlineProgress = null;
+  let pushedInline = null;
   try {
-    pull = await applyOfflineSyncSnapshot({
+    pushedInline = changeset.changes.length > 0 ? await pushOfflineChanges({
+      remoteUrl: options.remoteUrl,
+      token: options.token,
+      namespace: syncNamespace,
+      changeset,
+      onBatchApplied: (batch) => {
+        inlineAppliedChanges.push(...batch.changeset.changes);
+        pushedInlineProgress = mergeInlinePushSummary(pushedInlineProgress, batch.result);
+        pushed = buildPushedSummary(pushedInlineProgress);
+      }
+    }) : null;
+  } catch (error) {
+    if (pushed || inlineAppliedChanges.length > 0) {
+      return writePartialPushState(error, void 0, {
+        ...changeset,
+        changes: inlineAppliedChanges
+      });
+    }
+    throw error;
+  }
+  pushed = buildPushedSummary(pushedInline);
+  let remoteSnapshotMetadata;
+  try {
+    remoteSnapshotMetadata = await fetchOfflineSnapshot({
+      remoteUrl: options.remoteUrl,
+      token: options.token,
+      namespace: syncNamespace,
+      includeTranscripts: options.includeTranscripts,
+      includeContent: false,
+      baseFiles,
+      baseCapturedAt
+    });
+  } catch (error) {
+    if (pushed) return writePartialPushState(error);
+    throw error;
+  }
+  let currentSnapshot;
+  try {
+    currentSnapshot = await buildOfflineSyncSnapshotFromBase({
       root: options.memoryDir,
-      snapshot: remoteSnapshot,
+      sourceId: localSourceId,
+      baseFiles,
+      baseCapturedAt,
+      includeContent: false,
+      includeTranscripts: options.includeTranscripts,
+      readFile: storageIo.readFile,
+      readFileDigest: storageIo.readFileDigest
+    });
+  } catch (error) {
+    if (pushed) return writePartialPushState(error);
+    throw error;
+  }
+  let directHydration;
+  const directHydrationProgress = {
+    hydratedPaths: /* @__PURE__ */ new Set(),
+    deferredPaths: /* @__PURE__ */ new Set()
+  };
+  try {
+    directHydration = await directHydrateLargeOfflineFiles({
+      remoteUrl: options.remoteUrl,
+      token: options.token,
+      namespace: syncNamespace,
+      includeTranscripts: options.includeTranscripts,
+      snapshot: remoteSnapshotMetadata,
       baseFiles,
+      currentFiles: currentSnapshot.files,
+      memoryDir: options.memoryDir,
       readFile: storageIo.readFile,
+      readFileDigest: storageIo.readFileDigest,
       writeFile: storageIo.writeFile,
-      deleteFile: storageIo.deleteFile
+      writeStagingFile: storageIo.writeStagingFile,
+      writeFileChunks: storageIo.writeFileChunks,
+      hydrationProgress: directHydrationProgress
     });
   } catch (error) {
-    if (!isMissingOfflineContentError(error)) throw error;
-    const retrySnapshot = await hydrateOfflineSnapshotContent({
+    const partial = offlinePartialHydrationForPaths({
+      files: remoteSnapshotMetadata.files,
+      hydratedPaths: directHydrationProgress.hydratedPaths,
+      deferredPaths: directHydrationProgress.deferredPaths
+    });
+    if (pushed || partial.hydratedFiles.length > 0) {
+      return writePartialPushState(error, {
+        ...partial,
+        resolvedNamespace: resolvedOfflineSnapshotNamespace(remoteSnapshotMetadata, syncNamespace),
+        remoteFileCount: remoteSnapshotMetadata.files.length
+      });
+    }
+    throw error;
+  }
+  const directHydratedPaths = directHydration.hydratedPaths;
+  const remoteDeferredPaths = directHydration.deferredPaths;
+  const partialHydration = offlinePartialHydrationForPaths({
+    files: remoteSnapshotMetadata.files,
+    hydratedPaths: directHydratedPaths,
+    deferredPaths: remoteDeferredPaths
+  });
+  const partialHydrationWithContext = {
+    ...partialHydration,
+    resolvedNamespace: resolvedOfflineSnapshotNamespace(remoteSnapshotMetadata, syncNamespace),
+    remoteFileCount: remoteSnapshotMetadata.files.length
+  };
+  const buildCurrentSnapshotForApply = async () => buildOfflineSyncSnapshotFromBase({
+    root: options.memoryDir,
+    sourceId: localSourceId,
+    baseFiles,
+    baseCapturedAt,
+    includeContent: false,
+    includeTranscripts: options.includeTranscripts,
+    readFile: storageIo.readFile,
+    readFileDigest: storageIo.readFileDigest
+  });
+  const applyCurrentSnapshot = directHydratedPaths.size > 0 ? await buildCurrentSnapshotForApply() : currentSnapshot;
+  let remoteSnapshot;
+  try {
+    remoteSnapshot = await hydrateOfflineSnapshotContent({
       remoteUrl: options.remoteUrl,
       token: options.token,
       namespace: syncNamespace,
       includeTranscripts: options.includeTranscripts,
       snapshot: remoteSnapshotMetadata,
-      baseFiles
+      baseFiles,
+      currentFiles: applyCurrentSnapshot.files,
+      deferredPaths: [...remoteDeferredPaths]
     });
+  } catch (error) {
+    if (pushed || partialHydration.hydratedFiles.length > 0) {
+      return writePartialPushState(error, partialHydrationWithContext);
+    }
+    throw error;
+  }
+  const resolvedNamespace = resolvedOfflineSnapshotNamespace(remoteSnapshot, syncNamespace);
+  let pull;
+  try {
+    const latestApplySnapshot = await buildCurrentSnapshotForApply();
     pull = await applyOfflineSyncSnapshot({
       root: options.memoryDir,
-      snapshot: retrySnapshot,
+      snapshot: remoteSnapshot,
       baseFiles,
+      currentFiles: latestApplySnapshot.files,
+      deferredPaths: [...remoteDeferredPaths],
+      allowMissingConflictContent: true,
       readFile: storageIo.readFile,
+      readFileDigest: storageIo.readFileDigest,
       writeFile: storageIo.writeFile,
       deleteFile: storageIo.deleteFile
     });
+  } catch (error) {
+    if (!isMissingOfflineContentError(error)) {
+      if (pushed || partialHydration.hydratedFiles.length > 0) {
+        return writePartialPushState(error, {
+          ...partialHydrationWithContext,
+          resolvedNamespace
+        });
+      }
+      throw error;
+    }
+    let retrySnapshot;
+    try {
+      retrySnapshot = await hydrateOfflineSnapshotContent({
+        remoteUrl: options.remoteUrl,
+        token: options.token,
+        namespace: syncNamespace,
+        includeTranscripts: options.includeTranscripts,
+        snapshot: remoteSnapshotMetadata,
+        baseFiles,
+        currentFiles: applyCurrentSnapshot.files,
+        deferredPaths: [...remoteDeferredPaths]
+      });
+    } catch (retryError) {
+      if (pushed || partialHydration.hydratedFiles.length > 0) {
+        return writePartialPushState(retryError, {
+          ...partialHydrationWithContext,
+          resolvedNamespace
+        });
+      }
+      throw retryError;
+    }
+    try {
+      const latestRetryApplySnapshot = await buildCurrentSnapshotForApply();
+      pull = await applyOfflineSyncSnapshot({
+        root: options.memoryDir,
+        snapshot: retrySnapshot,
+        baseFiles,
+        currentFiles: latestRetryApplySnapshot.files,
+        deferredPaths: [...remoteDeferredPaths],
+        allowMissingConflictContent: true,
+        readFile: storageIo.readFile,
+        readFileDigest: storageIo.readFileDigest,
+        writeFile: storageIo.writeFile,
+        deleteFile: storageIo.deleteFile
+      });
+    } catch (retryApplyError) {
+      if (pushed || partialHydration.hydratedFiles.length > 0) {
+        return writePartialPushState(retryApplyError, {
+          ...partialHydrationWithContext,
+          resolvedNamespace
+        });
+      }
+      throw retryApplyError;
+    }
   }
   const state = offlineSyncStateFromSnapshot({
     remoteId: options.remoteUrl,
@@ -7566,13 +8226,7 @@ async function runOfflineSyncOnce(options) {
     snapshot: remoteSnapshot,
     baseFiles: pull.nextBaseFiles
   });
-  const stateWritePaths = offlineStatePathsForNamespace({
-    memoryDir: options.memoryDir,
-    remoteUrl: options.remoteUrl,
-    requestedNamespace: options.namespace,
-    resolvedNamespace,
-    explicitStatePath: options.statePathExplicit ? activeStatePath : void 0
-  });
+  const stateWritePaths = stateWritePathsFor(resolvedNamespace);
   for (const statePath of stateWritePaths) {
     await writeOfflineSyncState(statePath, state);
   }
@@ -7582,8 +8236,53 @@ async function runOfflineSyncOnce(options) {
     prepared: priorState === null,
     pushed,
     pull,
+    partial: false,
     pendingSummary,
-    remoteFileCount: remoteSnapshot.files.length
+    remoteFileCount: remoteSnapshot.files.length,
+    deferred: {
+      localChangedDuringPush: [...directPushDeferredPaths].sort(),
+      remoteChangedDuringHydrate: [...remoteDeferredPaths].sort(),
+      total: directPushDeferredPaths.size + remoteDeferredPaths.size
+    }
+  };
+}
+function sumOfflineFileBytes(files) {
+  return files.reduce((total, file) => total + file.bytes, 0);
+}
+function offlineStateJsonSummary(state) {
+  if (!state) return null;
+  return {
+    remoteId: state.remoteId,
+    namespace: state.namespace ?? null,
+    includeTranscripts: state.includeTranscripts,
+    lastSyncedAt: state.lastSyncedAt,
+    baseFileCount: state.baseFiles.length,
+    baseBytes: sumOfflineFileBytes(state.baseFiles)
+  };
+}
+function offlinePullJsonSummary(pull) {
+  return {
+    upserted: pull.upserted,
+    deleted: pull.deleted,
+    skipped: pull.skipped,
+    pendingLocal: pull.pendingLocal,
+    conflicts: pull.conflicts,
+    nextBaseFileCount: pull.nextBaseFiles.length,
+    nextBaseBytes: sumOfflineFileBytes(pull.nextBaseFiles)
+  };
+}
+function offlineSyncResultJsonSummary(result) {
+  return {
+    statePath: result.statePath,
+    namespace: result.namespace ?? null,
+    prepared: result.prepared,
+    partial: result.partial,
+    pushed: result.pushed,
+    pull: result.pull ? offlinePullJsonSummary(result.pull) : null,
+    pullError: result.pullError ?? null,
+    pendingSummary: result.pendingSummary,
+    remoteFileCount: result.remoteFileCount,
+    deferred: result.deferred
   };
 }
 function assertOfflineStateMatches(options) {
@@ -7664,6 +8363,7 @@ Environment fallbacks:
       snapshot: remoteSnapshot,
       baseFiles: existingState?.state.baseFiles ?? [],
       readFile: storageIo.readFile,
+      readFileDigest: storageIo.readFileDigest,
       writeFile: storageIo.writeFile,
       deleteFile: storageIo.deleteFile
     });
@@ -7677,7 +8377,12 @@ Environment fallbacks:
       await writeOfflineSyncState(pathToWrite, state);
     }
     if (json) {
-      console.log(JSON.stringify({ statePath: activeStatePath, namespace: resolvedNamespace, remoteFiles: remoteSnapshot.files.length, pull }, null, 2));
+      console.log(JSON.stringify({
+        statePath: activeStatePath,
+        namespace: resolvedNamespace,
+        remoteFiles: remoteSnapshot.files.length,
+        pull: offlinePullJsonSummary(pull)
+      }, null, 2));
     } else {
       console.log(`Offline cache prepared: ${memoryDir}`);
       console.log(`Namespace: ${resolvedNamespace ?? "(default)"}`);
@@ -7699,12 +8404,19 @@ Environment fallbacks:
       statePathExplicit
     });
     if (json) {
-      console.log(JSON.stringify(result, null, 2));
+      console.log(JSON.stringify(offlineSyncResultJsonSummary(result), null, 2));
     } else {
       console.log(`Offline sync complete${result.prepared ? " (initialized state)" : ""}.`);
       console.log(`Pushed: ${result.pushed ? `${result.pushed.appliedUpserts} upserts, ${result.pushed.appliedDeletes} deletes, ${result.pushed.conflicts.length} conflicts` : "nothing pending"}`);
-      console.log(`Pulled: ${result.pull.upserted} upserts, ${result.pull.deleted} deletes, ${result.pull.conflicts.length} conflicts`);
+      if (result.pull) {
+        console.log(`Pulled: ${result.pull.upserted} upserts, ${result.pull.deleted} deletes, ${result.pull.conflicts.length} conflicts`);
+      } else {
+        console.log(`Pulled: deferred (${result.pullError ?? "pull unavailable"})`);
+      }
       console.log(`Pending local before push: ${result.pendingSummary.total}`);
+      if (result.deferred.total > 0) {
+        console.log(`Deferred volatile files: ${result.deferred.total}`);
+      }
       console.log(`Namespace: ${result.namespace ?? "(default)"}`);
       console.log(`State: ${result.statePath}`);
     }
@@ -7727,11 +8439,17 @@ Environment fallbacks:
       root: memoryDir,
       sourceId: localOfflineSourceId(memoryDir),
       baseFiles: state?.baseFiles ?? [],
+      baseCapturedAt: state ? new Date(state.lastSyncedAt) : void 0,
       includeTranscripts,
-      readFile: storageIo.readFile
+      readFile: storageIo.readFile,
+      readFileDigest: storageIo.readFileDigest
     });
     if (json) {
-      console.log(JSON.stringify({ statePath: statePath ?? null, state, pending: summary }, null, 2));
+      console.log(JSON.stringify({
+        statePath: statePath ?? null,
+        state: offlineStateJsonSummary(state),
+        pending: summary
+      }, null, 2));
     } else {
       console.log(`Offline state: ${state ? "ready" : "not prepared"}`);
       console.log(`State: ${statePath ?? "(not selected; pass --state or --remote-url to inspect a prepared remote state)"}`);
@@ -7762,8 +8480,10 @@ Environment fallbacks:
           statePath,
           statePathExplicit
         });
+        const pulled = result.pull ? result.pull.upserted + result.pull.deleted : 0;
+        const conflicts = (result.pushed?.conflicts.length ?? 0) + (result.pull?.conflicts.length ?? 0);
         console.log(
-          `[${(/* @__PURE__ */ new Date()).toISOString()}] sync ok: pushed=${result.pushed ? result.pushed.appliedUpserts + result.pushed.appliedDeletes : 0}, pulled=${result.pull.upserted + result.pull.deleted}, conflicts=${(result.pushed?.conflicts.length ?? 0) + result.pull.conflicts.length}`
+          `[${(/* @__PURE__ */ new Date()).toISOString()}] sync ${result.partial ? "partial" : "ok"}: pushed=${result.pushed ? result.pushed.appliedUpserts + result.pushed.appliedDeletes : 0}, pulled=${pulled}, conflicts=${conflicts}, deferred=${result.deferred.total}${result.pullError ? `, pullError=${result.pullError}` : ""}`
         );
       } catch (error) {
         console.log(`[${(/* @__PURE__ */ new Date()).toISOString()}] sync waiting: ${error instanceof Error ? error.message : String(error)}`);
@@ -10676,32 +11396,50 @@ if (argv1Base.endsWith("remnic.ts") || argv1Base.endsWith("remnic.js") || argv1B
 export {
   BENCHMARK_CATALOG,
   OFFLINE_SYNC_APPLY_MAX_REQUEST_BYTES,
+  OFFLINE_SYNC_CHANGESET_RETRY_MAX,
   OFFLINE_SYNC_DIRECT_HYDRATE_MIN_BYTES,
   OFFLINE_SYNC_DIRECT_PUSH_MIN_BYTES,
   OFFLINE_SYNC_FILE_CONTENT_UPLOAD_CHUNK_BYTES,
+  OFFLINE_SYNC_REQUEST_TIMEOUT_DEFAULT_MS,
+  OFFLINE_SYNC_SNAPSHOT_BASE_POST_MAX_FILES,
+  OFFLINE_SYNC_SNAPSHOT_BASE_POST_PREFERRED_MAX_BODY_BYTES,
   TAXONOMY_RESOLVE_BOOLEAN_FLAGS,
   TAXONOMY_RESOLVE_VALUE_FLAGS,
   __benchDatasetTestHooks,
+  advanceOfflineBaseFilesForSuccessfulPush,
   buildBenchRuntimeProfileRequest,
   buildPackageBenchExecutionPlans,
   buildQueryRecallRequest,
   chunkOfflineChangesetApplyBatches,
   chunkOfflineFileContentBatches,
+  directHydrateLargeOfflineFiles,
   extractXrayRawArgs,
+  fetchOfflineSnapshot,
   formatOfflineLargeFilePushFailureMessage,
+  formatOfflineRequestForError,
   getBenchUsageText,
   hasFlag,
+  isOfflineSnapshotPostFallbackError,
   main,
+  offlinePartialHydrationForPaths,
+  offlineSnapshotBasePostBody,
+  offlineSnapshotBasePostBodyFits,
+  offlineSnapshotBasePostRequest,
+  offlineSnapshotContentFilesForApply,
   parseBenchArgs,
   parseCapsuleForkArgs,
   parseConnectorConfig,
+  parseOfflineSyncRequestTimeoutMs,
   parseTaxonomyResolveArgs,
   parseTrainingExportArgs,
+  pushOfflineFileContent,
+  pushOfflineFileContentFromChunkReader,
   renderQueryTextLines,
   resolveConfigPath,
   resolveFlag,
   resolveMemoryDir,
   resolveSyncSourceDir,
+  runOfflineSyncOnce,
   runTrainingExport,
   runXrayCommand,
   shouldDirectHydrateOfflineFile,