@remnic/core 10.0.49 → 10.0.50

package/src/offline-sync-file-io.ts

@@ -77,9 +77,16 @@ export async function plainFileDigest(filePath: string): Promise<string> {
   return hash.digest("hex");
 }
 
-import { lstat, utimes } from "node:fs/promises";
+import { lstat, realpath, utimes } from "node:fs/promises";
 import { isCensusMtimeMs } from "./census-validation.js";
-import { resolveSafeArchiveTarget, type SafeArchiveRoot } from "./transfer/fs-utils.js";
+import path from "node:path";
+import {
+  fromPosixRelPath,
+  isPathInsideRoot,
+  resolveSafeArchiveTarget,
+  type SafeArchiveRoot,
+  validateArchiveRelativePath,
+} from "./transfer/fs-utils.js";
 
 /** Sync-internal directory spooling partial uploads and coordination state. */
 export const SYNC_INTERNAL_DIR = ".offline-sync";
@@ -124,3 +131,55 @@ export async function setSafeFileMtime(
   await utimes(target, mtime, mtime);
   return true;
 }
+
+/**
+ * True when a regular (non-symlink) file exists at the archive-relative path.
+ * A symlink is not a regular local file and reads as absent, so callers treat
+ * it like any other missing path instead of failing the whole push.
+ */
+export async function offlineSyncRegularFilePresent(
+  root: SafeArchiveRoot,
+  relPath: string,
+): Promise<boolean> {
+  const target = path.resolve(root.abs, fromPosixRelPath(validateArchiveRelativePath(relPath, root.errorPrefix)));
+  if (!isPathInsideRoot(root.abs, target)) {
+    throw new Error(`${root.errorPrefix}: record path escapes target root: ${relPath}`);
+  }
+  const st = await lstat(target).catch((error: NodeJS.ErrnoException) => {
+    // SAFETY: Node fs errors carry `code`; only ENOENT means absent, all other
+    // errno codes must propagate so census uncertainty fails closed.
+    if (error.code === "ENOENT") return null;
+    throw error;
+  });
+  if (!st || st.isSymbolicLink() || !st.isFile()) return false;
+  // A regular file still has to resolve inside the root (a symlinked parent directory escapes it).
+  await resolveSafeArchiveTarget(root, relPath);
+  // The census skips a symlinked directory, so a file reached only through one is absent here too.
+  return (await realpath(target)) === path.join(root.real, path.relative(root.abs, target));
+}
+
+/** A path the census observed vanished before its digest was read: a retryable race, never a confirmed delete. */
+export class OfflineSyncCensusRaceError extends Error {
+  constructor(readonly relPath: string, cause?: unknown) {
+    super(
+      `offline sync census race: ${relPath} vanished during digest; retry the snapshot`,
+      cause === undefined ? undefined : { cause },
+    );
+    this.name = "OfflineSyncCensusRaceError";
+  }
+}
+
+/** The message the CLI push retry loop matches: it defers the path and rebuilds the census. */
+export function changedWhileBuildingChangesetError(relPath: string, cause?: unknown): Error {
+  return new Error(
+    `offline sync file changed while building changeset: ${relPath}`,
+    cause === undefined ? undefined : { cause },
+  );
+}
+
+/** A `.catch` handler: a census race while building a changeset upsert stays retryable. */
+export function censusRaceAsChangedWhileBuilding(relPath: string): (error: Error) => never {
+  return (error) => {
+    throw error instanceof OfflineSyncCensusRaceError ? changedWhileBuildingChangesetError(relPath, error) : error;
+  };
+}

package/src/offline-sync.test.ts

@@ -1,6 +1,6 @@
 import assert from "node:assert/strict";
 import { createHash } from "node:crypto";
-import { chmod, mkdir, mkdtemp, readdir, readFile, rm, stat, utimes, writeFile } from "node:fs/promises";
+import { chmod, mkdir, mkdtemp, readdir, readFile, rm, stat, symlink, utimes, writeFile } from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
 import test from "node:test";
@@ -3714,33 +3714,37 @@ test("applyOfflineSyncSnapshot consumes readIncomingFile for records without inl
   }
 });
 
-test("buildOfflineSyncSnapshot skips a file that vanishes during the walk", async () => {
+test("buildOfflineSyncSnapshot fails closed when a file vanishes during digest", async () => {
   const root = await tempDir("remnic-offline-vanish");
   try {
     await write(root, "facts/keep.md", "keep");
     await write(root, "facts/gone.md", "gone");
-    const snapshot = await buildOfflineSyncSnapshot({
-      root,
-      sourceId: "local",
-      includeContent: false,
-      readFileDigest: async ({ path: relPath, filePath }) => {
-        if (relPath.endsWith("gone.md")) {
-          await rm(filePath);
-          throw Object.assign(new Error("ENOENT: vanished"), { code: "ENOENT" });
-        }
-        const content = await readFile(filePath);
-        return {
-          sha256: createHash("sha256").update(content).digest("hex"),
-          bytes: content.length,
-        };
-      },
-    });
-    assert.deepEqual(snapshot.files.map((file) => file.path), ["facts/keep.md"]);
+    await assert.rejects(
+      () => buildOfflineSyncSnapshot({
+        root,
+        sourceId: "local",
+        includeContent: false,
+        readFileDigest: async ({ path: relPath, filePath }) => {
+          if (relPath.endsWith("gone.md")) {
+            await rm(filePath);
+            throw Object.assign(new Error("ENOENT: vanished"), { code: "ENOENT" });
+          }
+          const content = await readFile(filePath);
+          return {
+            sha256: createHash("sha256").update(content).digest("hex"),
+            bytes: content.length,
+          };
+        },
+      }),
+      /census race|vanished during digest|retry the snapshot/i,
+    );
+    assert.equal(await readUtf8(root, "facts/keep.md"), "keep");
   } finally {
     await rm(root, { recursive: true, force: true });
   }
 });
 
+
 test("base snapshot fails when a base-known file vanishes before the fast-base stat", async () => {
   const root = await tempDir("remnic-offline-base-vanish");
   try {
@@ -3770,7 +3774,7 @@ test("base snapshot fails when a base-known file vanishes before the fast-base s
   }
 });
 
-test("base snapshot omits a brand-new file that vanishes during the walk", async () => {
+test("base snapshot omits a brand-new file that vanishes before the fast-base stat", async () => {
   const root = await tempDir("remnic-offline-new-vanish");
   try {
     await write(root, "facts/keep.md", "keep");
@@ -3798,6 +3802,7 @@ test("base snapshot omits a brand-new file that vanishes during the walk", async
   }
 });
 
+
 test("snapshot fails when an embedding generation member vanishes during the walk", async () => {
   const root = await tempDir("remnic-offline-shard-vanish");
   try {
@@ -3822,3 +3827,291 @@ test("snapshot fails when an embedding generation member vanishes during the wal
     await rm(root, { recursive: true, force: true });
   }
 });
+
+test("a transient snapshot omission must not emit a delete for a shared-base file", async () => {
+  const root = await tempDir("remnic-offline-uncertain-delete");
+  try {
+    await write(root, "facts/keep.md", "keep");
+    await write(root, "facts/race.md", "race-v1");
+    const base = await buildOfflineSyncSnapshot({
+      root,
+      sourceId: "local",
+      includeContent: false,
+    });
+    // Live census fail-closes on digest ENOENT. A stale/incomplete currentFiles
+    // list is still possible from an older client cache — that path must not
+    // emit a confirmed delete when the file is back on disk.
+    const incompleteFiles = base.files.filter((file) => file.path !== "facts/race.md");
+    assert.deepEqual(
+      incompleteFiles.map((file) => file.path),
+      ["facts/keep.md"],
+      "fixture: the race path is absent from the incomplete currentFiles view",
+    );
+    await write(root, "facts/race.md", "race-v1");
+    const changeset = await buildOfflineSyncChangesetFromSnapshot({
+      root,
+      sourceId: "local",
+      currentFiles: incompleteFiles,
+      baseFiles: base.files,
+    });
+    assert.equal(
+      changeset.changes.filter((change) => change.path === "facts/race.md" && change.type === "delete").length,
+      0,
+      "an unreadable/recreated path must not become a confirmed delete against the shared base",
+    );
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});
+
+test("apply must not overwrite a recreated local file omitted from the local census", async () => {
+  const root = await tempDir("remnic-offline-uncertain-overwrite");
+  try {
+    const recreated = "recreated local bytes";
+    const incoming = "incoming remote bytes";
+    await write(root, "facts/race.md", recreated);
+    const incomingSha = createHash("sha256").update(incoming).digest("hex");
+    // Local census omitted the recreated path (stale/racy currentFiles).
+    // Incoming is base-less, so the apply path would treat it as a pure create.
+    const result = await applyOfflineSyncSnapshot({
+      root,
+      currentFiles: [],
+      baseFiles: [],
+      snapshot: {
+        format: OFFLINE_SYNC_SNAPSHOT_FORMAT,
+        schemaVersion: 1,
+        createdAt: new Date().toISOString(),
+        sourceId: "remote",
+        includeTranscripts: false,
+        files: [{
+          path: "facts/race.md",
+          sha256: incomingSha,
+          bytes: Buffer.byteLength(incoming),
+          mtimeMs: 2,
+          contentBase64: Buffer.from(incoming).toString("base64"),
+        }],
+      },
+    });
+    assert.equal(
+      await readUtf8(root, "facts/race.md"),
+      recreated,
+      "recreated local content must survive when the local census omitted it",
+    );
+    assert.equal(result.upserted, 0, "must not publish over an uncertain local path");
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});
+
+test("changeset apply must not overwrite a recreated local file omitted by controlled digest census", async () => {
+  // Public applyOfflineSyncChangeset builds local currentFiles via
+  // buildOfflineSyncSnapshotForPaths when currentFiles is omitted. A controlled
+  // digest that recreates local bytes then throws ENOENT must fail closed at
+  // the shared census boundary — never export confirmed absence and overwrite.
+  const root = await tempDir("remnic-offline-changeset-uncertain-overwrite");
+  try {
+    const recreated = "recreated local bytes";
+    const incoming = "incoming remote bytes";
+    const incomingSha = createHash("sha256").update(incoming).digest("hex");
+    await write(root, "facts/race.md", recreated);
+
+    await assert.rejects(
+      () => applyOfflineSyncChangeset({
+        root,
+        // No currentFiles: exercise the public snapshotForPaths census path.
+        returnCurrentFiles: false,
+        writeConflictCopies: false,
+        readFileDigest: async ({ path: relPath, filePath }) => {
+          if (relPath === "facts/race.md") {
+            await writeFile(filePath, recreated);
+            throw Object.assign(new Error("ENOENT: vanished during census"), { code: "ENOENT" });
+          }
+          const content = await readFile(filePath);
+          return {
+            sha256: createHash("sha256").update(content).digest("hex"),
+            bytes: content.length,
+          };
+        },
+        changeset: {
+          format: "remnic.offline-sync.changeset.v1",
+          schemaVersion: 1,
+          createdAt: new Date().toISOString(),
+          sourceId: "remote",
+          includeTranscripts: false,
+          changes: [{
+            type: "upsert",
+            path: "facts/race.md",
+            file: {
+              path: "facts/race.md",
+              sha256: incomingSha,
+              bytes: Buffer.byteLength(incoming),
+              mtimeMs: 2,
+              contentBase64: Buffer.from(incoming).toString("base64"),
+            },
+          }],
+        },
+      }),
+      /census race|vanished during digest|retry the snapshot/i,
+    );
+
+    assert.equal(
+      await readUtf8(root, "facts/race.md"),
+      recreated,
+      "recreated local content must survive a fail-closed public changeset census race",
+    );
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});
+
+test("sender snapshot omission from digest race must not delete receiver shared-base file", async () => {
+  // Root premise: sender digest race must not export an apparently-complete
+  // snapshot that omits the path. Fail closed at the shared census boundary so
+  // no consumer can assign confirmed absence. Sender and receiver bytes stay.
+  const senderRoot = await tempDir("remnic-offline-sender-uncertain-omit");
+  const receiverRoot = await tempDir("remnic-offline-receiver-shared-base");
+  try {
+    const good = "unchanged good fact bytes";
+    const keep = "keep peer";
+    await write(senderRoot, "facts/race.md", good);
+    await write(senderRoot, "facts/keep.md", keep);
+    await write(receiverRoot, "facts/race.md", good);
+    await write(receiverRoot, "facts/keep.md", keep);
+
+    const sharedBase = await buildOfflineSyncSnapshot({
+      root: receiverRoot,
+      sourceId: "shared",
+      includeContent: false,
+    });
+    assert.ok(
+      sharedBase.files.some((file) => file.path === "facts/race.md"),
+      "fixture: shared base includes the good race path",
+    );
+
+    await assert.rejects(
+      () => buildOfflineSyncSnapshot({
+        root: senderRoot,
+        sourceId: "sender",
+        includeContent: false,
+        readFileDigest: async ({ path: relPath, filePath }) => {
+          if (relPath === "facts/race.md") {
+            await writeFile(filePath, good);
+            throw Object.assign(new Error("ENOENT: vanished during sender census"), { code: "ENOENT" });
+          }
+          const content = await readFile(filePath);
+          return {
+            sha256: createHash("sha256").update(content).digest("hex"),
+            bytes: content.length,
+          };
+        },
+      }),
+      /census race|vanished during digest|retry the snapshot/i,
+    );
+
+    assert.equal(await readUtf8(senderRoot, "facts/race.md"), good, "sender bytes preserved");
+    assert.equal(await readUtf8(receiverRoot, "facts/race.md"), good, "receiver bytes preserved without a false snapshot");
+    assert.equal(await readUtf8(receiverRoot, "facts/keep.md"), keep);
+  } finally {
+    await rm(senderRoot, { recursive: true, force: true });
+    await rm(receiverRoot, { recursive: true, force: true });
+  }
+});
+
+
+test("a file vanishing during the changeset upsert read keeps the retryable changed-while-building message", async () => {
+  const root = await mkdtemp(path.join(os.tmpdir(), "remnic-offline-changeset-vanish-"));
+  try {
+    const rel = "facts/volatile.md";
+    const bytes = Buffer.from("volatile bytes\n");
+    await mkdir(path.join(root, "facts"), { recursive: true });
+    await writeFile(path.join(root, rel), bytes);
+    const currentFile = {
+      path: rel,
+      sha256: createHash("sha256").update(bytes).digest("hex"),
+      bytes: bytes.byteLength,
+      mtimeMs: 1,
+    };
+    await assert.rejects(
+      buildOfflineSyncChangesetFromSnapshot({
+        root,
+        sourceId: "laptop",
+        baseFiles: [],
+        currentFiles: [currentFile],
+        readFile: async () => {
+          await rm(path.join(root, rel), { force: true });
+          throw Object.assign(new Error("ENOENT: file vanished"), { code: "ENOENT" });
+        },
+      }),
+      (error: Error) => {
+        // The CLI retry loop matches this exact prefix to defer the path and rebuild the census.
+        assert.equal(error.message, `offline sync file changed while building changeset: ${rel}`);
+        return true;
+      },
+    );
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});
+
+test("a tracked file replaced by a symlink is a local delete, not a push-blocking error", async () => {
+  const root = await mkdtemp(path.join(os.tmpdir(), "remnic-offline-symlink-replaced-"));
+  const outside = await mkdtemp(path.join(os.tmpdir(), "remnic-offline-symlink-target-"));
+  try {
+    const rel = "facts/tracked.md";
+    const bytes = Buffer.from("tracked bytes\n");
+    await mkdir(path.join(root, "facts"), { recursive: true });
+    await writeFile(path.join(outside, "target.md"), "outside\n");
+    await symlink(path.join(outside, "target.md"), path.join(root, rel));
+    const baseFile = {
+      path: rel,
+      sha256: createHash("sha256").update(bytes).digest("hex"),
+      bytes: bytes.byteLength,
+      mtimeMs: 1,
+    };
+    const changeset = await buildOfflineSyncChangesetFromSnapshot({
+      root,
+      sourceId: "laptop",
+      baseFiles: [baseFile],
+      currentFiles: [],
+    });
+    assert.deepEqual(
+      changeset.changes.map((change) => [change.type, change.path]),
+      [["delete", rel]],
+      "a symlink is not a regular local file: it reads as a delete, as before the census change",
+    );
+  } finally {
+    await rm(root, { recursive: true, force: true });
+    await rm(outside, { recursive: true, force: true });
+  }
+});
+
+test("a tracked file under a directory replaced by an in-root symlink is a local delete", async () => {
+  const root = await mkdtemp(path.join(os.tmpdir(), "remnic-offline-symlink-parent-"));
+  try {
+    const rel = "facts/tracked.md";
+    const bytes = Buffer.from("tracked bytes\n");
+    await mkdir(path.join(root, "elsewhere"), { recursive: true });
+    await writeFile(path.join(root, "elsewhere", "tracked.md"), bytes);
+    // The census skips a symlinked directory, so facts/tracked.md is not in it.
+    await symlink(path.join(root, "elsewhere"), path.join(root, "facts"));
+    const baseFile = {
+      path: rel,
+      sha256: createHash("sha256").update(bytes).digest("hex"),
+      bytes: bytes.byteLength,
+      mtimeMs: 1,
+    };
+    const changeset = await buildOfflineSyncChangesetFromSnapshot({
+      root,
+      sourceId: "laptop",
+      baseFiles: [baseFile],
+      currentFiles: [],
+    });
+    assert.deepEqual(
+      changeset.changes.map((change) => [change.type, change.path]),
+      [["delete", rel]],
+      "a path reached only through a symlinked parent is absent, as the census sees it",
+    );
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});

package/src/offline-sync.ts

@@ -70,6 +70,10 @@ import {
   setSafeFileMtime,
   assertNonNegativeFinite,
   assertOfflineSyncMtimeMs,
+  offlineSyncRegularFilePresent,
+  OfflineSyncCensusRaceError,
+  censusRaceAsChangedWhileBuilding,
+  changedWhileBuildingChangesetError,
   OFFLINE_SYNC_FAST_BASE_MTIME_TOLERANCE_MS,
 } from "./offline-sync-file-io.js";
 import { CENSUS_MAX_MTIME_MS, isSha256Hex } from "./census-validation.js";
@@ -793,19 +797,29 @@ async function canReuseFastBaseFileStateFromDisk(
 
 async function readOfflineSyncFileRecord(
   options: OfflineSyncFileRecordOptions,
-): Promise<OfflineSyncFileRecord | null> {
+): Promise<OfflineSyncFileRecord> {
   try {
     return await readPresentOfflineSyncFileRecord(options);
   } catch (error) {
-    // A file removed between readdir and stat/hash is a race, not a corrupt corpus.
-    if (isNotFoundError(error)) return null;
+    // Caller already observed the path (readdir/lstat). Digest ENOENT is an
+    // ambiguous race: exporting a silent omission assigns confirmed absence to
+    // every consumer (full snapshot apply + changeset apply). Fail closed.
+    if (isNotFoundError(error)) {
+      if (embeddingGenerationMembership(options.relPath) !== null) {
+        throw new Error(
+          `offline sync embedding generation member vanished during snapshot walk: ${options.relPath}`,
+        );
+      }
+      throw new OfflineSyncCensusRaceError(options.relPath, error);
+    }
     throw error;
   }
 }
 
-// A vanished path may only be omitted when nothing can misread the gap:
-// embedding generations travel and replace as one unit (issue #3148), and a
-// base-known file omitted here would fabricate a delete in
+
+// Pre-stat vanish (readdir then lstat/stat ENOENT) may omit only when nothing
+// can misread the gap: embedding generations travel as one unit (issue #3148),
+// and a base-known file omitted here would fabricate a delete in
 // buildOfflineSyncChangesetFromSnapshot.
 function assertSnapshotVanishIsSafe(relPath: string, base: ReadonlyMap<string, unknown> | undefined): void {
   if (embeddingGenerationMembership(relPath) !== null) {
@@ -816,6 +830,7 @@ function assertSnapshotVanishIsSafe(relPath: string, base: ReadonlyMap<string, u
   }
 }
 
+
 async function readPresentOfflineSyncFileRecord(
   options: OfflineSyncFileRecordOptions,
 ): Promise<OfflineSyncFileRecord> {
@@ -923,7 +938,7 @@ export async function* iterateOfflineSyncSnapshotFileRecords(options: {
         path: relPosix,
         filePath: abs,
       })) continue;
-      const record = await readOfflineSyncFileRecord({
+      yield await readOfflineSyncFileRecord({
         root,
         relPath: relPosix,
         filePath: abs,
@@ -932,8 +947,7 @@ export async function* iterateOfflineSyncSnapshotFileRecords(options: {
         readFileDigest: options.readFileDigest,
         signal: options.signal,
       });
-      if (record) yield record;
-      else assertSnapshotVanishIsSafe(relPosix, undefined);
+
     }
   }
 
@@ -1094,8 +1108,7 @@ export async function buildOfflineSyncSnapshotFromBase(options: {
       try {
         st = await stat(abs);
       } catch (error) {
-        // Same race readOfflineSyncFileRecord tolerates, unless omitting the
-        // path could fabricate a delete or downgrade a generation.
+        // Pre-stat vanish after readdir: omit only when assertSnapshotVanishIsSafe allows.
         if (isNotFoundError(error)) {
           assertSnapshotVanishIsSafe(relPosix, base);
           continue;
@@ -1112,7 +1125,7 @@ export async function buildOfflineSyncSnapshotFromBase(options: {
         files.push(baseEntry);
         continue;
       }
-      const record = await readOfflineSyncFileRecord({
+      files.push(await readOfflineSyncFileRecord({
         root,
         relPath: relPosix,
         filePath: abs,
@@ -1120,9 +1133,7 @@ export async function buildOfflineSyncSnapshotFromBase(options: {
         readFile: options.readFile,
         readFileDigest: options.readFileDigest,
         signal: options.signal,
-      });
-      if (record) files.push(record);
-      else assertSnapshotVanishIsSafe(relPosix, base);
+      }));
     }
   }
 
@@ -1208,7 +1219,7 @@ export async function buildOfflineSyncSnapshotForPaths(options: {
     })) {
       throw new Error(`offline sync snapshot path is excluded: ${relPath}`);
     }
-    const record = await readOfflineSyncFileRecord({
+    files.push(await readOfflineSyncFileRecord({
       root,
       relPath,
       filePath,
@@ -1216,9 +1227,7 @@ export async function buildOfflineSyncSnapshotForPaths(options: {
       readFile: options.readFile,
       readFileDigest: options.readFileDigest,
       signal: options.signal,
-    });
-    if (record) files.push(record);
-    else assertSnapshotVanishIsSafe(relPath, undefined);
+    }));
   }
   throwIfOfflineSyncAborted(options.signal);
 
@@ -1414,6 +1423,11 @@ export async function buildOfflineSyncChangesetFromSnapshot(options: {
   excludeNodeLocalState?: boolean;
   readFile?: (target: OfflineSyncFileTarget) => Promise<Buffer>;
 }): Promise<OfflineSyncChangeset> {
+  const root = await prepareSafeArchiveRoot(
+    path.resolve(options.root),
+    "buildOfflineSyncChangesetFromSnapshot",
+    "root",
+  );
   const includeTranscripts = options.includeTranscripts !== false;
   const excludedPaths = new Set(
     (options.excludePaths ?? []).map((relPath) => normalizeRelativePath(relPath, "excludePaths[]")),
@@ -1453,10 +1467,10 @@ export async function buildOfflineSyncChangesetFromSnapshot(options: {
         now: options.now,
         userExcludeRegexps: options.userExcludeRegexps,
         readFile: options.readFile,
-      });
+      }).catch(censusRaceAsChangedWhileBuilding(relPath));
       const record = file.files[0];
       if (!record || typeof record.contentBase64 !== "string" || record.sha256 !== currentEntry.sha256) {
-        throw new Error(`offline sync file changed while building changeset: ${relPath}`);
+        throw changedWhileBuildingChangesetError(relPath);
       }
       changes.push({
         type: "upsert",
@@ -1467,6 +1481,8 @@ export async function buildOfflineSyncChangesetFromSnapshot(options: {
       continue;
     }
     if (!currentEntry && baseEntry) {
+      // Census miss is not confirmed delete — recheck disk (transient ENOENT / recreate).
+      if (await offlineSyncRegularFilePresent(root, relPath)) continue;
       const mtimeMs = deletionMtimeByPath?.get(relPath);
       changes.push({
         type: "delete",
@@ -1808,6 +1824,12 @@ export async function applyOfflineSyncSnapshot(options: {
         continue;
       }
       if (!currentEntry && !base) {
+        // Census miss with on-disk file: uncertain local presence, do not overwrite.
+        if (await offlineSyncRegularFilePresent(root, relPath)) {
+          pendingLocal += 1;
+          skipped += 1;
+          continue;
+        }
         await writeSafeFile(root, relPath, requiredBuffer(incomingBuffers, relPath), options.writeFile, incoming.mtimeMs);
         nextBase.set(relPath, toFileState(incoming));
         upserted += 1;

package/src/orchestrator-init.test.ts

@@ -1,5 +1,6 @@
 import assert from "node:assert/strict";
-import { mkdir, mkdtemp, rm } from "node:fs/promises";
+import { existsSync } from "node:fs";
+import { mkdir, mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
 import test from "node:test";
@@ -1547,3 +1548,50 @@ test("startupSearchSync composes its caller abort into the QMD probe", async ()
     await rm(memoryDir, { recursive: true, force: true, maxRetries: 3, retryDelay: 50 });
   }
 });
+
+// Both startup call sites must open read readiness without migration replay.
+for (const namespace of ["default", "shared"]) {
+  test(`startup defers entity migration for ${namespace} storage`, async () => {
+    const memoryDir = await mkdtemp(path.join(os.tmpdir(), "remnic-init-migration-defer-"));
+    const orchestrator = new Orchestrator(
+      parseConfig({
+        memoryDir,
+        workspaceDir: path.join(memoryDir, "workspace"),
+        qmdEnabled: false,
+        namespacesEnabled: namespace === "shared",
+        namespaceCatalogEnabled: false,
+        defaultNamespace: "default",
+        sharedNamespace: "shared",
+        namespacePolicies: [],
+        embeddingFallbackEnabled: false,
+        identityContinuityEnabled: false,
+        transcriptEnabled: false,
+        hourlySummariesEnabled: false,
+        compoundingEnabled: false,
+        knowledgeIndexEnabled: false,
+      }),
+    );
+    const storage = await orchestrator.getStorage(namespace);
+    const lockPath = path.join(storage.dir, "state", "entity-canonical-id-migration.lock");
+    const journalPath = path.join(storage.dir, "state", "entity-canonical-id-migration-v1.json");
+    try {
+      await mkdir(path.dirname(lockPath), { recursive: true });
+      await writeFile(lockPath, `${process.pid} init-migration-test ${new Date().toISOString()}\n`);
+      const outcome = await withTestDeadline(
+        orchestrator.initialize().then(() => "settled" as const, () => "rejected" as const),
+      );
+      assert.equal(outcome, "settled", "startup must succeed while the migration lock is held");
+      assert.equal(existsSync(lockPath), true);
+      assert.equal(existsSync(journalPath), false, "startup must not run the migration");
+      await rm(lockPath);
+      await storage.ensureDirectories();
+      // SAFETY: the journal is written by the migration under test and carries an optional boolean `complete`.
+      const state = JSON.parse(await readFile(journalPath, "utf8")) as { complete?: boolean };
+      assert.equal(state.complete, true, "default setup must still run migration");
+    } finally {
+      await rm(lockPath, { force: true });
+      await orchestrator.destroy();
+      await rm(memoryDir, { recursive: true, force: true, maxRetries: 3, retryDelay: 50 });
+    }
+  });
+}