@remnic/core 10.0.14 → 10.0.15

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@remnic/core",
-  "version": "10.0.14",
+  "version": "10.0.15",
   "description": "Framework-agnostic Remnic memory engine — orchestrator, storage, extraction, search, trust zones",
   "type": "module",
   "main": "dist/index.js",
@@ -3347,7 +3347,7 @@
     "core"
   ],
   "peerDependencies": {
-    "@remnic/coding-graph": "^10.0.14"
+    "@remnic/coding-graph": "^10.0.15"
   },
   "peerDependenciesMeta": {
     "@remnic/coding-graph": {

package/src/calibration.ts

@@ -19,6 +19,7 @@ import { resolveLocalLlmCapabilities } from "./capabilities.js";
 import { OUTPUT_LANGUAGE_POLICY } from "./extraction-prompt.js";
 import { FallbackLlmClient } from "./fallback-llm.js";
 import { listJsonFiles } from "./json-store.js";
+import { isMacOsReplicationJunkBasename } from "./utils/macos-replication-junk.js";
 import { LocalLlmClient } from "./local-llm.js";
 import { log } from "./logger.js";
 import { writeFileAtomically } from "./maintenance/atomic-file.js";
@@ -195,7 +196,7 @@ async function readCorrectionsImpl(memoryDir: string): Promise<CorrectionMemory[
     for (const day of dayDirs) {
       const dayPath = path.join(factsDir, day);
       const dayFiles = (await readdir(dayPath))
-        .filter((f: string) => f.startsWith("correction-") && f.endsWith(".md"))
+        .filter((f: string) => !isMacOsReplicationJunkBasename(f) && f.startsWith("correction-") && f.endsWith(".md"))
         .map((f: string) => path.join(dayPath, f));
       files.push(...dayFiles);
     }
@@ -207,7 +208,7 @@ async function readCorrectionsImpl(memoryDir: string): Promise<CorrectionMemory[
   try {
     const { readdir } = await import("node:fs/promises");
     const corrFiles = (await readdir(correctionsDir))
-      .filter((f: string) => f.endsWith(".md"))
+      .filter((f: string) => !isMacOsReplicationJunkBasename(f) && f.endsWith(".md"))
       .map((f: string) => path.join(correctionsDir, f));
     files.push(...corrFiles);
   } catch {

package/src/cli.ts

@@ -13,6 +13,7 @@ import { ThreadingManager } from "./threading.js";
 import { bumpMemoryCorpusVersionForDir } from "./memory-corpus-version.js";
 import { utcDayRange } from "./transcript.js";
 import { padEndDisplay, truncateGraphemeSafe } from "./whitespace.js";
+import { isMacOsReplicationJunkBasename } from "./utils/macos-replication-junk.js";
 import { runWearablesCliCommand } from "./wearables/cli.js";
 import { registerMeetingsCommands } from "./cli/meetings-commands.js"; import { registerDeepRecallCommands } from "./cli/deep-recall-commands.js"; import { registerRecallNavigationCommands } from "./cli/recall-navigation-commands.js"; import { registerMemoryBrowseCommands } from "./cli/memory-browse-commands.js";
 import { registerExportOkfCommand, registerOkfCommands } from "./cli/okf-commands.js";
@@ -3334,7 +3335,6 @@ export async function resolveMemoryDirForNamespace(
   }
   return candidate;
 }
-
 /**
  * Walk every recall category directory under `memoryDir` recursively and invoke
  * `visit` for every `*.md` file. The directory set is `RECALL_FALLBACK_DIRS`
@@ -3392,6 +3392,7 @@ async function walkMemoryMarkdownFiles(
     for (const entry of entries) {
       if (entry.isSymbolicLink()) continue; // never follow symlinked entries
       const entryName = typeof entry.name === "string" ? entry.name : entry.name.toString("utf-8");
+      if (isMacOsReplicationJunkBasename(entryName)) continue;
       const fullPath = path.join(dir, entryName);
       try {
         assertPathInsideRoot(memoryRootReal, await realpath(fullPath), fullPath);
@@ -3412,7 +3413,6 @@ async function walkMemoryMarkdownFiles(
     await walk(root);
   }
 }
-
 /**
  * List absolute paths of every `*.md` file under each recall category directory
  * of `memoryDir` (facts/, corrections/, decisions/, ...; see

package/src/consolidation-provenance-check.ts

@@ -30,6 +30,7 @@ import {
 // lock-step with the doctor scan.
 import { sidecarKey } from "./page-versioning.js";
 import { RECALL_FALLBACK_DIRS } from "./utils/category-dir.js";
+import { isMacOsReplicationJunkBasename } from "./utils/macos-replication-junk.js";
 
 /**
  * Regex to spot a `derived_via: <value>` line in the raw YAML frontmatter
@@ -549,6 +550,7 @@ async function* walkMarkdownFiles(root: string, memoryDir: string): AsyncGenerat
     return;
   }
   for (const entry of entries) {
+    if (isMacOsReplicationJunkBasename(entry.name)) continue;
     const full = path.join(root, entry.name);
     if (entry.isSymbolicLink()) continue;
     if (entry.isDirectory()) {

package/src/correction/correction-planner.ts

@@ -26,6 +26,7 @@ import { readFile, readdir, unlink } from "node:fs/promises";
 import path from "node:path";
 import { throwIfAborted } from "../abort-error.js";
 import { writeFileAtomically } from "../maintenance/atomic-file.js";
+import { isMacOsReplicationJunkBasename } from "../utils/macos-replication-junk.js";
 import { serializeMutations } from "../utils/serialize-mutations.js";
 import {
   CORRECTION_TEXT_MAX,
@@ -576,7 +577,7 @@ export class CorrectionPlanner {
     }
     const plans: CorrectionPlan[] = [];
     for (const f of files) {
-      if (!f.endsWith(".json")) continue;
+      if (isMacOsReplicationJunkBasename(f) || !f.endsWith(".json")) continue;
       let plan: CorrectionPlan | null = null;
       try {
         plan = await this.loadPlan(namespace, f.replace(/\.json$/, ""));
@@ -702,7 +703,7 @@ export class CorrectionPlanner {
     }
     const recovered: string[] = [];
     for (const f of files) {
-      if (!f.endsWith(".json")) continue;
+      if (isMacOsReplicationJunkBasename(f) || !f.endsWith(".json")) continue;
       const planId = f.replace(/\.json$/, "");
       let plan: CorrectionPlan | null;
       try {

package/src/json-store.ts

@@ -14,6 +14,7 @@ import {
 } from "node:fs/promises";
 import path from "node:path";
 import { isErrnoCode } from "./utils/errno.js";
+import { isMacOsReplicationJunkBasename } from "./utils/macos-replication-junk.js";
 
 async function listJsonFilesStrictInner(dir: string, allowMissingDirectory: boolean): Promise<string[]> {
   let entries: Dirent[];
@@ -25,6 +26,7 @@ async function listJsonFilesStrictInner(dir: string, allowMissingDirectory: bool
   }
   const out: string[] = [];
   for (const entry of entries) {
+    if (isMacOsReplicationJunkBasename(entry.name)) continue;
     const fullPath = path.join(dir, entry.name);
     if (entry.isDirectory()) {
       out.push(...(await listJsonFilesStrictInner(fullPath, false)));
@@ -55,6 +57,7 @@ export async function listNamedFiles(dir: string, fileName: string): Promise<str
     const entries = await readdir(dir, { withFileTypes: true });
     const out: string[] = [];
     for (const entry of entries) {
+      if (isMacOsReplicationJunkBasename(entry.name)) continue;
       const fullPath = path.join(dir, entry.name);
       if (entry.isDirectory()) {
         out.push(...(await listNamedFiles(fullPath, fileName)));

package/src/macos-replication-junk-scanners.test.ts

@@ -0,0 +1,275 @@
+import assert from "node:assert/strict";
+import { mkdir, mkdtemp, readFile, rm, utimes, writeFile } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import test from "node:test";
+
+import { readCalibrationCorrections } from "./calibration.js";
+import { CorrectionPlanner, type PlannerDeps } from "./correction/correction-planner.js";
+import { listJsonFiles } from "./json-store.js";
+import { parseConfig } from "./config.js";
+import { ProfilingCollector } from "./profiling.js";
+import { TranscriptManager } from "./transcript.js";
+import { resolveDefaultNamespaceRoot } from "./namespaces/storage.js";
+import { runDirectAgent } from "./retrieval-agents.js";
+import { scanMemoryDir } from "./search/document-scanner.js";
+import { StorageManager } from "./storage.js";
+import { hasSupersessionAudit } from "./storage/supersession-audit.js";
+import type { PluginConfig } from "./types.js";
+
+const CORRECTION_BODY = [
+  "---",
+  "id: correction-sidecar",
+  "confidence: 0.9",
+  "---",
+  "Synthetic correction that must not be loaded from Finder metadata.",
+].join("\n");
+
+test("scanMemoryDir ignores AppleDouble and .DS_Store index inputs", async () => {
+  const memoryDir = await mkdtemp(path.join(os.tmpdir(), "remnic-scan-macos-junk-"));
+  try {
+    const factsDir = path.join(memoryDir, "facts", "2026-02-22");
+    await mkdir(factsDir, { recursive: true });
+    await writeFile(
+      path.join(factsDir, "inside.md"),
+      ["---", "id: inside", "category: fact", "---", "A real fact."].join("\n"),
+      "utf8"
+    );
+    await writeFile(path.join(factsDir, "._inside.md"), Buffer.from([0, 5, 22]));
+    await writeFile(path.join(factsDir, ".DS_Store"), "finder");
+
+    const docs = await scanMemoryDir(memoryDir);
+    assert.deepEqual(
+      docs.map((doc) => doc.docid),
+      ["inside"]
+    );
+  } finally {
+    await rm(memoryDir, { recursive: true, force: true });
+  }
+});
+
+test("memory reads skip macOS replication junk beside real facts", async () => {
+  const memoryDir = await mkdtemp(path.join(os.tmpdir(), "remnic-memories-macos-junk-"));
+  try {
+    const storage = new StorageManager(memoryDir);
+    const written = await storage.writeMemory("fact", "Synthetic dome schedule is stored once.");
+    const factDir = path.dirname(written.memory.path);
+    await writeFile(path.join(factDir, "._inside.md"), CORRECTION_BODY, "utf8");
+    await writeFile(path.join(factDir, ".DS_Store"), "finder");
+
+    const memories = await storage.readAllMemories();
+    assert.deepEqual(
+      memories.map((memory) => memory.frontmatter.id),
+      [written.id]
+    );
+  } finally {
+    await rm(memoryDir, { recursive: true, force: true });
+  }
+});
+
+test("correction scans and calibration ignore macOS replication junk", async () => {
+  const memoryDir = await mkdtemp(path.join(os.tmpdir(), "remnic-corrections-macos-junk-"));
+  try {
+    const correctionsDir = path.join(memoryDir, "corrections");
+    await mkdir(correctionsDir, { recursive: true });
+    await writeFile(
+      path.join(correctionsDir, "correction-real.md"),
+      CORRECTION_BODY.replace("correction-sidecar", "correction-real"),
+      "utf8"
+    );
+    await writeFile(path.join(correctionsDir, "._sidecar.md"), CORRECTION_BODY, "utf8");
+    await writeFile(path.join(correctionsDir, ".DS_Store"), "finder");
+
+    const corrections = await readCalibrationCorrections(memoryDir);
+    assert.deepEqual(
+      corrections.map((correction) => correction.id),
+      ["correction-real"]
+    );
+
+    const reads: string[] = [];
+    const found = await hasSupersessionAudit(
+      {
+        correctionsDir,
+        async readMemoryByPath(filePath) {
+          reads.push(path.basename(filePath));
+          return null;
+        },
+      },
+      "old-id",
+      "new-id",
+      "audit body"
+    );
+    assert.equal(found, false);
+    assert.deepEqual(reads, ["correction-real.md"]);
+  } finally {
+    await rm(memoryDir, { recursive: true, force: true });
+  }
+});
+
+test("state JSON listings and pending correction plans ignore macOS replication junk", async () => {
+  const root = await mkdtemp(path.join(os.tmpdir(), "remnic-state-macos-junk-"));
+  try {
+    const stateDir = path.join(root, "state");
+    await mkdir(stateDir, { recursive: true });
+    await writeFile(path.join(stateDir, "real.json"), "{}\n");
+    await writeFile(path.join(stateDir, "._state.json"), "{}\n");
+    await writeFile(path.join(stateDir, ".DS_Store"), "finder");
+    const listed = (await listJsonFiles(stateDir)).map((file) => path.basename(file));
+    assert.deepEqual(listed, ["real.json"]);
+
+    const pendingDir = path.join(stateDir, "corrections", "pending");
+    await mkdir(pendingDir, { recursive: true });
+    await writeFile(path.join(pendingDir, "._plan.json"), "{}\n");
+    await writeFile(path.join(pendingDir, ".DS_Store"), "finder");
+    const planner = new CorrectionPlanner({
+      storageDir: async () => root,
+    } as unknown as PlannerDeps);
+    assert.deepEqual(await planner.listPending("default"), []);
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});
+
+test("profiling prune keeps AppleDouble traces and deletes only real jsonl files", async () => {
+  const storageDir = await mkdtemp(path.join(os.tmpdir(), "remnic-profiling-macos-junk-"));
+  try {
+    const junk = path.join(storageDir, "._trace.jsonl");
+    const older = path.join(storageDir, "recall-old.jsonl");
+    const newer = path.join(storageDir, "recall-new.jsonl");
+    await writeFile(junk, "sidecar\n");
+    await writeFile(older, "old\n");
+    await writeFile(newer, "new\n");
+    const oldTime = new Date("2020-01-01T00:00:00Z");
+    const newTime = new Date("2024-01-01T00:00:00Z");
+    await utimes(older, oldTime, oldTime);
+    await utimes(newer, newTime, newTime);
+
+    const collector = new ProfilingCollector({ enabled: false, storageDir, maxTraces: 1 });
+    await collector.pruneFiles();
+
+    assert.equal(await readFile(junk, "utf8"), "sidecar\n");
+    assert.equal(await readFile(newer, "utf8"), "new\n");
+    await assert.rejects(() => readFile(older), { code: "ENOENT" });
+  } finally {
+    await rm(storageDir, { recursive: true, force: true });
+  }
+});
+
+test("direct entity recall ignores AppleDouble sidecars and malformed entities", async () => {
+  const memoryDir = await mkdtemp(path.join(os.tmpdir(), "remnic-direct-macos-junk-"));
+  try {
+    const entitiesDir = path.join(memoryDir, "entities");
+    await mkdir(entitiesDir, { recursive: true });
+    await writeFile(path.join(entitiesDir, "project-real.md"), "# Real\n**Type:** project\n");
+    await writeFile(path.join(entitiesDir, "project-real-gap.md"), "# \n**Type:** project\n");
+    await writeFile(path.join(entitiesDir, "project-real-tab.md"), "#\tTabbed\n**Type:** project\n");
+    await writeFile(path.join(entitiesDir, "._project-real.md"), Buffer.from([0, 5, 22]));
+    await writeFile(path.join(entitiesDir, ".DS_Store"), "finder");
+    const encrypted = Buffer.alloc(12);
+    Buffer.from("REMNIC-ENC").copy(encrypted);
+    await writeFile(path.join(entitiesDir, "project-real-locked.md"), encrypted);
+
+    const hits = await runDirectAgent("real", memoryDir);
+    assert.deepEqual(
+      hits.map((hit) => path.basename(hit.path)).sort(),
+      ["project-real-locked.md", "project-real.md"],
+    );
+  } finally {
+    await rm(memoryDir, { recursive: true, force: true });
+  }
+});
+
+test("transcript writes ignore AppleDouble jsonl sidecars", async () => {
+  const memoryDir = await mkdtemp(path.join(os.tmpdir(), "remnic-transcript-macos-junk-"));
+  try {
+    const transcript = new TranscriptManager(parseConfig({
+      memoryDir,
+      transcriptEnabled: true,
+      transcriptSkipChannelTypes: [],
+    }));
+    await transcript.initialize();
+    const sessionKey = "agent:main:desk";
+    const located = transcript.getTranscriptPath(sessionKey);
+    const channelDir = path.join(memoryDir, "transcripts", located.dir);
+    const toolDir = path.join(memoryDir, "state", "tool-usage", located.dir);
+    await mkdir(channelDir, { recursive: true });
+    await mkdir(toolDir, { recursive: true });
+    const sidecar = Buffer.from([0, 5, 22]);
+    await writeFile(path.join(channelDir, `._${located.file}`), sidecar);
+    await writeFile(path.join(toolDir, `._${located.file}`), sidecar);
+
+    await transcript.append({
+      timestamp: "2026-04-13T10:00:00.000Z",
+      role: "user",
+      content: "North Dome schedule",
+      sessionKey,
+      turnId: "turn-1",
+    });
+    await transcript.appendToolUse({
+      timestamp: "2026-04-13T10:00:01.000Z",
+      sessionKey,
+      tool: "lookup",
+    });
+
+    assert.match(await readFile(path.join(channelDir, located.file), "utf8"), /North Dome schedule/);
+    assert.match(await readFile(path.join(toolDir, located.file), "utf8"), /lookup/);
+    assert.deepEqual(await readFile(path.join(channelDir, `._${located.file}`)), sidecar);
+    await assert.rejects(
+      () => readFile(path.join(memoryDir, "transcripts", located.alternateDir, located.file)),
+      { code: "ENOENT" },
+    );
+  } finally {
+    await rm(memoryDir, { recursive: true, force: true });
+  }
+});
+
+test("archive and summary reads ignore macOS replication junk", async () => {
+  const dir = await mkdtemp(path.join(os.tmpdir(), "remnic-archive-macos-junk-"));
+  try {
+    const storage = new StorageManager(dir);
+    await storage.ensureDirectories();
+    const archive = path.join(dir, "archive");
+    await mkdir(archive, { recursive: true });
+    await writeFile(
+      path.join(archive, "archived-real.md"),
+      ["---", "id: archived-real", "category: fact", "---", "Kept."].join("\n"),
+      "utf8",
+    );
+    await writeFile(path.join(archive, "._archived-real.md"), "{not-a-memory");
+    await writeFile(path.join(archive, ".DS_Store"), "finder");
+    const archived = await storage.readArchivedMemories();
+    assert.deepEqual(archived.map((memory) => memory.frontmatter.id), ["archived-real"]);
+
+    const summaries = path.join(dir, "summaries");
+    await mkdir(summaries, { recursive: true });
+    await writeFile(path.join(summaries, "sum-real.json"), JSON.stringify({ id: "sum-real", text: "ok" }));
+    await writeFile(path.join(summaries, "._sum-real.json"), "{not-json");
+    const loaded = await storage.readSummaries();
+    assert.deepEqual(loaded.map((summary) => summary.id), ["sum-real"]);
+  } finally {
+    await rm(dir, { recursive: true, force: true });
+  }
+});
+
+test("namespace routing ignores macOS replication junk in the legacy root", async () => {
+  const memoryDir = await mkdtemp(path.join(os.tmpdir(), "remnic-ns-macos-junk-"));
+  try {
+    const config = {
+      memoryDir,
+      namespacesEnabled: true,
+      defaultNamespace: "default",
+    } as PluginConfig;
+    await mkdir(path.join(memoryDir, "namespaces", "default", "facts"), { recursive: true });
+    await mkdir(path.join(memoryDir, "entities"), { recursive: true });
+    await writeFile(path.join(memoryDir, "entities", ".DS_Store"), "finder");
+    await writeFile(path.join(memoryDir, "entities", "._sidecar.md"), Buffer.from([0, 5]));
+    assert.equal(
+      await resolveDefaultNamespaceRoot(config),
+      path.join(memoryDir, "namespaces", "default"),
+    );
+    await writeFile(path.join(memoryDir, "entities", "project-real.md"), "# Real\n");
+    assert.equal(await resolveDefaultNamespaceRoot(config), memoryDir);
+  } finally {
+    await rm(memoryDir, { recursive: true, force: true });
+  }
+});

package/src/maintenance/dreams-ledger.ts

@@ -16,6 +16,7 @@ import path from "node:path";
 import { createReadStream, type ReadStream } from "node:fs";
 import { appendFile, lstat, mkdir, readdir, readFile } from "node:fs/promises";
 import { createInterface } from "node:readline";
+import { isMacOsReplicationJunkBasename } from "../utils/macos-replication-junk.js";
 
 // ── Types ─────────────────────────────────────────────────────────────────────
 
@@ -553,6 +554,7 @@ async function listMemoryFiles(memoryDir: string): Promise<string[]> {
     }
     for (const entry of entries) {
       if (entry.isSymbolicLink()) continue;
+      if (isMacOsReplicationJunkBasename(entry.name)) continue;
       const full = path.join(dir, entry.name);
       if (entry.isDirectory()) {
         // Skip state/ and archive/ subdirs.

package/src/maintenance/memory-governance.ts

@@ -6,6 +6,7 @@ import type { MemoryFile, MemoryStatus } from "../types.js";
 import { RECALL_FALLBACK_DIRS } from "../utils/category-dir.js";
 import { bumpMemoryCorpusVersionForDir } from "../memory-corpus-version.js";
 import { assertPathInsideRoot } from "../utils/path-containment.js";
+import { isMacOsReplicationJunkBasename } from "../utils/macos-replication-junk.js";
 import { requestEntityCanonicalIdReconcile } from "../storage/entity-canonical-id-references.js";
 import { excludeSupportPassportPrivateMemories } from "../support-passport/card-projection.js";
 
@@ -361,6 +362,7 @@ async function listMarkdownFiles(root: string, containmentRoot: string): Promise
       const entries = await readdir(dir, { withFileTypes: true });
       for (const entry of entries) {
         if (entry.isSymbolicLink()) continue; // never follow symlinked entries
+        if (isMacOsReplicationJunkBasename(entry.name)) continue;
         const fullPath = path.join(dir, entry.name);
         if (entry.isDirectory()) {
           await walk(fullPath);

package/src/namespaces/storage.ts

@@ -6,6 +6,7 @@ import { StorageManager } from "../storage.js";
 import { keyring, secureStoreDir } from "../secure-store/index.js";
 import type { PluginConfig } from "../types.js";
 import { ALL_CATEGORY_DIRS } from "../utils/category-dir.js";
+import { isMacOsReplicationJunkBasename } from "../utils/macos-replication-junk.js";
 import {
   namespaceIdentityLegacyToken,
   namespaceIdentityToken,
@@ -30,6 +31,7 @@ async function hasStoredEntries(p: string): Promise<boolean> {
     if (!entry.isDirectory()) return true;
     const children = await readdir(p, { withFileTypes: true });
     for (const child of children) {
+      if (isMacOsReplicationJunkBasename(child.name)) continue;
       const childPath = path.join(p, child.name);
       if (child.isSymbolicLink() || child.isFile()) return true;
       if (child.isDirectory() && (await hasStoredEntries(childPath))) return true;

package/src/offline-sync-macos-junk.test.ts

@@ -0,0 +1,169 @@
+import assert from "node:assert/strict";
+import { createHash } from "node:crypto";
+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";
+
+import {
+  OFFLINE_SYNC_CHANGESET_FORMAT,
+  OFFLINE_SYNC_SNAPSHOT_FORMAT,
+  applyOfflineSyncFileContentChunk,
+  applyOfflineSyncSnapshot,
+  buildOfflineSyncSnapshot,
+  buildOfflineSyncSnapshotForPaths,
+  buildOfflineSyncSnapshotFromBase,
+  normalizeOfflineSyncChangeset,
+  normalizeOfflineSyncSnapshot,
+} from "./offline-sync.js";
+
+async function write(root: string, relPath: string, content: string | Buffer): Promise<void> {
+  const filePath = path.join(root, relPath);
+  await mkdir(path.dirname(filePath), { recursive: true });
+  await writeFile(filePath, content);
+}
+
+test("offline sync omits macOS replication junk on snapshot, push, and pull", async () => {
+  const root = await mkdtemp(path.join(os.tmpdir(), "remnic-offline-macos-junk-"));
+  const dest = await mkdtemp(path.join(os.tmpdir(), "remnic-offline-macos-junk-dest-"));
+  try {
+    await write(root, "namespaces/lab/entities/project-real.md", "real entity");
+    await write(root, "namespaces/lab/entities/._sidecar.md", Buffer.from([0, 5, 22]));
+    await write(root, "namespaces/lab/.DS_Store", "finder");
+    await write(root, "entities/._root.md", Buffer.from([0, 5, 22]));
+    await write(root, ".DS_Store", "finder-root");
+    await write(root, "facts/._ignored/record.md", "nested junk");
+
+    const snapshot = await buildOfflineSyncSnapshot({
+      root,
+      sourceId: "remote",
+      includeContent: true,
+    });
+    assert.deepEqual(
+      snapshot.files.map((file) => file.path),
+      ["namespaces/lab/entities/project-real.md"]
+    );
+
+    const pullSide = await buildOfflineSyncSnapshotFromBase({
+      root,
+      sourceId: "local",
+      includeContent: false,
+      excludeNodeLocalState: false,
+    });
+    assert.deepEqual(
+      pullSide.files.map((file) => file.path),
+      ["namespaces/lab/entities/project-real.md"]
+    );
+
+    await assert.rejects(
+      () =>
+        buildOfflineSyncSnapshotForPaths({
+          root,
+          sourceId: "remote",
+          paths: ["namespaces/lab/entities/._sidecar.md"],
+          includeContent: true,
+        }),
+      /offline sync snapshot path is excluded/
+    );
+    await assert.rejects(
+      () =>
+        buildOfflineSyncSnapshotForPaths({
+          root,
+          sourceId: "remote",
+          paths: ["facts/._ignored/record.md"],
+          includeContent: true,
+        }),
+      /offline sync snapshot path is excluded/
+    );
+    await assert.rejects(
+      () =>
+        applyOfflineSyncFileContentChunk({
+          root: dest,
+          sourceId: "remote",
+          path: "namespaces/lab/.DS_Store",
+          sha256: createHash("sha256").update("finder").digest("hex"),
+          bytes: 6,
+          mtimeMs: 1,
+          content: Buffer.from("finder"),
+        }),
+      /offline sync file content path is excluded/
+    );
+
+    const real = snapshot.files[0];
+    const incoming = {
+      format: OFFLINE_SYNC_SNAPSHOT_FORMAT,
+      schemaVersion: 1 as const,
+      createdAt: snapshot.createdAt,
+      sourceId: "remote",
+      includeTranscripts: true,
+      files: [
+        real,
+        {
+          ...real,
+          path: "namespaces/lab/entities/._sidecar.md",
+          contentBase64: Buffer.from("sidecar").toString("base64"),
+          sha256: createHash("sha256").update("sidecar").digest("hex"),
+          bytes: Buffer.byteLength("sidecar"),
+        },
+        {
+          ...real,
+          path: "namespaces/other/.DS_Store",
+          contentBase64: Buffer.from("finder").toString("base64"),
+          sha256: createHash("sha256").update("finder").digest("hex"),
+          bytes: Buffer.byteLength("finder"),
+        },
+        {
+          ...real,
+          path: "facts/._ignored/record.md",
+          contentBase64: Buffer.from("nested junk").toString("base64"),
+          sha256: createHash("sha256").update("nested junk").digest("hex"),
+          bytes: Buffer.byteLength("nested junk"),
+        },
+      ],
+      deletions: [
+        { path: "facts/removed.md", mtimeMs: 2 },
+        { path: "entities/._root.md", mtimeMs: 1 },
+        { path: "facts/._ignored/record.md", mtimeMs: 3 },
+      ],
+    };
+    const normalized = normalizeOfflineSyncSnapshot(incoming);
+    assert.deepEqual(
+      normalized.files.map((file) => file.path),
+      ["namespaces/lab/entities/project-real.md"]
+    );
+    assert.deepEqual(normalized.deletions, [{ path: "facts/removed.md", mtimeMs: 2 }]);
+
+    const applied = await applyOfflineSyncSnapshot({ root: dest, snapshot: incoming });
+    assert.equal(applied.upserted, 1);
+    assert.equal(await readFile(path.join(dest, "namespaces/lab/entities/project-real.md"), "utf8"), "real entity");
+    await assert.rejects(() => readFile(path.join(dest, "namespaces/lab/entities/._sidecar.md")), { code: "ENOENT" });
+    await assert.rejects(() => readFile(path.join(dest, "namespaces/other/.DS_Store")), { code: "ENOENT" });
+    await assert.rejects(() => readFile(path.join(dest, "facts/._ignored/record.md")), { code: "ENOENT" });
+
+    const changeset = normalizeOfflineSyncChangeset({
+      format: OFFLINE_SYNC_CHANGESET_FORMAT,
+      schemaVersion: 1,
+      createdAt: snapshot.createdAt,
+      sourceId: "remote",
+      includeTranscripts: true,
+      changes: [
+        { type: "upsert", path: real.path, file: real },
+        {
+          type: "upsert",
+          path: "namespaces/lab/.DS_Store",
+          file: {
+            ...real,
+            path: "namespaces/lab/.DS_Store",
+          },
+        },
+      ],
+    });
+    assert.deepEqual(
+      changeset.changes.map((change) => change.path),
+      ["namespaces/lab/entities/project-real.md"]
+    );
+  } finally {
+    await rm(root, { recursive: true, force: true });
+    await rm(dest, { recursive: true, force: true });
+  }
+});

package/src/offline-sync.ts

@@ -26,6 +26,7 @@ import {
 import { parseFlexibleIsoTimestamp } from "./utils/iso-timestamp.js";
 import { EmbeddingIndexStorageError } from "./embedding-index-storage.js";
 import { isEmbeddingGenerationMarkerPath, matchesOfflineSyncDefaultExclude } from "./offline-sync-exclude-globs.js";
+import { isMacOsReplicationJunkBasename } from "./utils/macos-replication-junk.js";
 import {
   applyIncomingEmbeddingGenerations,
   assertEmbeddingGenerationStillIncluded,
@@ -699,6 +700,7 @@ function shouldExcludeRelPath(relPosix: string, includeTranscripts: boolean): bo
   if (parts.some((part) => part === SYNC_INTERNAL_DIR)) return true;
   if (!includeTranscripts && parts[0] === "transcripts") return true;
   const basename = parts[parts.length - 1] ?? "";
+  if (parts.some((part) => isMacOsReplicationJunkBasename(part))) return true;
   if (isCanonicalRuntimeStatePath(parts) && basename.includes(".tmp-")) return true;
   if (EXCLUDED_FILE_NAMES.has(basename)) return true;
   if (EXCLUDED_FILE_PREFIXES.some((prefix) => basename.startsWith(prefix))) return true;
@@ -748,6 +750,11 @@ function shouldIgnoreIncomingRuntimePath(relPosix: string): boolean {
   if (isInternalRemnicStatePath(relPosix)) return true;
   const parts = relPosix.split("/");
   const basename = parts[parts.length - 1] ?? "";
+  // Drop Finder metadata before the structural-exclude throw. An older
+  // peer snapshot that still lists `._*` or `.DS_Store` — including a file
+  // nested under a junk directory — must not fail the whole pull; those
+  // paths are never written.
+  if (parts.some((part) => isMacOsReplicationJunkBasename(part))) return true;
   return isCanonicalRuntimeStatePath(parts) && basename.includes(".tmp-");
 }