@indigoai-us/hq-cloud 6.15.31 → 6.15.32

package/dist/cli/sync.test.js

@@ -5,6 +5,7 @@ import { describe, it, expect, beforeEach, afterEach, vi } from "vitest";
 import * as fs from "fs";
 import * as path from "path";
 import * as os from "os";
+import * as crypto from "crypto";
 import { clearContextCache } from "../context.js";
 import { lockPathFor } from "../operation-lock.js";
 // Re-export node:fs as a mutable module so unreadable-link regressions can
@@ -13,6 +14,13 @@ vi.mock("fs", async (importOriginal) => {
     const actual = await importOriginal();
     return { ...actual };
 });
+// Same mutable-namespace trick as `fs` above: `skip` is an interactive-only
+// resolution, so the only way to exercise its arm is to stand in for the
+// prompt. Re-exporting the real module keeps every other call site genuine.
+vi.mock("./conflict.js", async (importOriginal) => {
+    const actual = await importOriginal();
+    return { ...actual };
+});
 describe("sync mutation stdin boundary", () => {
     it("accepts only the exact sidecar command and emits one discriminated upsert result", async () => {
         expect(SYNC_MUTATION_STDIN_COMMAND).toEqual(["sync", "mutation", "--stdin-json"]);
@@ -115,10 +123,37 @@ vi.mock("./reindex.js", () => ({
 import { sync, reportNewFilesToNotify, applyRealtimeDeltaPage, isSyncMutationStdinCommand, runSyncMutationStdinJson, SYNC_MUTATION_STDIN_COMMAND, win32SymlinkFlavorBroken, } from "./sync.js";
 import { share } from "./share.js";
 import * as s3Module from "../s3.js";
+import * as conflictModule from "./conflict.js";
 import { reindex } from "./reindex.js";
 import { readSyncProgress } from "../sync-progress.js";
 import { VaultAuthError } from "../vault-client.js";
-import { readJournal, getEntry } from "../journal.js";
+import { readJournal, getEntry, listJournals } from "../journal.js";
+/**
+ * Read a journal the way production does.
+ *
+ * These tests used to `JSON.parse` `sync-journal.<slug>.json` directly, back
+ * when that file held a full copy of the journal. It is now a small locator —
+ * the authority is the v3 state store — so the assertions below go through
+ * `readJournal`, which is what the sync engine itself uses. The slug is
+ * recovered from the path so each call site keeps naming the journal it means.
+ */
+function journalAt(journalPath) {
+    const slug = path
+        .basename(journalPath)
+        .replace(/^sync-journal\./, "")
+        .replace(/\.json$/, "");
+    return readJournal(slug);
+}
+/**
+ * The single `.conflict-` sidecar in a directory. Asserting through this rather
+ * than re-globbing inline keeps "exactly one was minted" enforced everywhere a
+ * test reaches for the preserved side.
+ */
+function sidecarIn(dir) {
+    const found = fs.readdirSync(dir).filter((f) => f.includes(".conflict-"));
+    expect(found).toHaveLength(1);
+    return path.join(dir, found[0]);
+}
 const mockConfig = {
     apiUrl: "https://vault-api.test",
     authToken: "test-jwt-token",
@@ -466,7 +501,7 @@ describe("sync", () => {
         const result = await sync({ vaultConfig: mockConfig, hqRoot: tmpDir });
         expect(result.filesDownloaded).toBe(2);
     });
-    it("detects conflicts with local changes and keeps local on --on-conflict keep", async () => {
+    it("detects conflicts with local changes and adopts the cloud copy on --on-conflict keep", async () => {
         const companyDocs = path.join(tmpDir, "companies", "acme", "docs");
         fs.mkdirSync(companyDocs, { recursive: true });
         fs.writeFileSync(path.join(companyDocs, "handoff.md"), "local version");
@@ -490,39 +525,386 @@ describe("sync", () => {
         });
         expect(result.conflicts).toBe(1);
         expect(result.conflictPaths).toEqual(["docs/handoff.md"]);
-        expect(result.filesSkipped).toBeGreaterThanOrEqual(1);
-        expect(fs.readFileSync(path.join(companyDocs, "handoff.md"), "utf-8")).toBe("local version");
+        // `keep` adopts the cloud body at the original name…
+        expect(fs.readFileSync(path.join(companyDocs, "handoff.md"), "utf-8")).toBe("mock file content");
+        // …and the local one survives beside it.
+        expect(fs.readFileSync(sidecarIn(companyDocs), "utf-8")).toBe("local version");
     });
-    it("conflict keep marks the entry localDiverges (journal-honesty: kept copy never matched the recorded remote etag)", async () => {
+    it("rechecks the current local body when executing a planned conflict", async () => {
         const companyDocs = path.join(tmpDir, "companies", "acme", "docs");
         fs.mkdirSync(companyDocs, { recursive: true });
-        fs.writeFileSync(path.join(companyDocs, "handoff.md"), "local version");
+        const localPath = path.join(companyDocs, "handoff.md");
+        fs.writeFileSync(localPath, "local body seen by the planner");
         fs.writeFileSync(journalPath, JSON.stringify({
             version: "1",
             lastSync: new Date().toISOString(),
             files: {
                 "docs/handoff.md": {
-                    hash: "old-hash-from-last-sync",
-                    size: 20,
+                    hash: "common-base-hash",
+                    size: 16,
                     syncedAt: new Date(Date.now() - 3600000).toISOString(),
                     direction: "down",
+                    remoteEtag: "common-base-etag",
                 },
             },
         }));
+        vi.mocked(s3Module.listRemoteFiles).mockResolvedValueOnce([
+            {
+                key: "docs/handoff.md",
+                size: "mock file content".length,
+                lastModified: new Date(),
+                etag: '"new-remote-etag"',
+            },
+        ]);
+        let changedAfterPlan = false;
         const result = await sync({
             company: "acme",
             onConflict: "keep",
             vaultConfig: mockConfig,
             hqRoot: tmpDir,
+            onEvent: (event) => {
+                if (event.type === "plan" && !changedAfterPlan) {
+                    changedAfterPlan = true;
+                    // The local writer converged this path with the cloud after the
+                    // whole-run preview classified it, but before its action executes.
+                    fs.writeFileSync(localPath, "mock file content");
+                }
+            },
+        });
+        expect(changedAfterPlan).toBe(true);
+        expect(result.conflicts).toBe(0);
+        expect(result.conflictPaths).toEqual([]);
+        expect(fs.readdirSync(companyDocs).filter((name) => name.includes(".conflict-")))
+            .toEqual([]);
+        const entry = journalAt(journalPath).files["docs/handoff.md"];
+        expect(entry).toMatchObject({
+            hash: crypto.createHash("sha256").update("mock file content").digest("hex"),
+            remoteEtag: "new-remote-etag",
+            direction: "down",
         });
+        expect(entry.localDiverges).toBeFalsy();
+    });
+    it("conflict skip marks the entry localDiverges (journal-honesty: the held copy never matched the recorded remote etag)", async () => {
+        const companyDocs = path.join(tmpDir, "companies", "acme", "docs");
+        fs.mkdirSync(companyDocs, { recursive: true });
+        fs.writeFileSync(path.join(companyDocs, "handoff.md"), "local version");
+        fs.writeFileSync(journalPath, JSON.stringify({
+            version: "1",
+            lastSync: new Date().toISOString(),
+            files: {
+                "docs/handoff.md": {
+                    hash: "old-hash-from-last-sync",
+                    size: 20,
+                    syncedAt: new Date(Date.now() - 3600000).toISOString(),
+                    direction: "down",
+                },
+            },
+        }));
+        // `keep` no longer holds, so the honesty flag now belongs to the arms that
+        // still do. `skip` is the interactive one and is exercised through the
+        // prompt stand-in.
+        const resolveSpy = vi
+            .spyOn(conflictModule, "resolveConflict")
+            .mockResolvedValue("skip");
+        let result;
+        try {
+            result = await sync({
+                company: "acme",
+                vaultConfig: mockConfig,
+                hqRoot: tmpDir,
+            });
+        }
+        finally {
+            resolveSpy.mockRestore();
+        }
         expect(result.conflicts).toBe(1);
-        const journal = JSON.parse(fs.readFileSync(journalPath, "utf-8"));
+        const journal = journalAt(journalPath);
         // remoteEtag still recorded so the conflict can't re-fire (#137 invariant)…
         expect(journal.files["docs/handoff.md"].remoteEtag).toBeTruthy();
-        // …but the kept-local copy is flagged divergent so a later currency-gated
+        // …but the held local copy is flagged divergent so a later currency-gated
         // delete cannot fire on a journal that lies about local==remote.
         expect(journal.files["docs/handoff.md"].localDiverges).toBe(true);
     });
+    // `publish-local` reaches the PULL leg too, because the strategy is set once
+    // for a bidirectional run. It has no meaning here — there is nothing to
+    // publish while deciding what to do with an incoming object — so it MUST
+    // degrade to `keep`. If it instead fell through to the download branch it
+    // would overwrite the very local body the operator elected to publish, which
+    // is precisely the data loss the strategy exists to prevent.
+    it("conflict publish-local on the pull leg keeps local and never downloads over it", async () => {
+        const companyDocs = path.join(tmpDir, "companies", "acme", "docs");
+        fs.mkdirSync(companyDocs, { recursive: true });
+        fs.writeFileSync(path.join(companyDocs, "handoff.md"), "my elected local version");
+        fs.writeFileSync(journalPath, JSON.stringify({
+            version: "1",
+            lastSync: new Date().toISOString(),
+            files: {
+                "docs/handoff.md": {
+                    hash: "old-hash-from-last-sync",
+                    size: 20,
+                    syncedAt: new Date(Date.now() - 3600000).toISOString(),
+                    direction: "down",
+                },
+            },
+        }));
+        const result = await sync({
+            company: "acme",
+            onConflict: "publish-local",
+            vaultConfig: mockConfig,
+            hqRoot: tmpDir,
+        });
+        expect(result.conflicts).toBe(1);
+        expect(fs.readFileSync(path.join(companyDocs, "handoff.md"), "utf-8")).toBe("my elected local version");
+        // Identical bookkeeping to `keep`: the etag is stamped so the conflict
+        // cannot re-fire, and the honesty flag is armed so the push leg knows this
+        // is the divergent body it may promote under an If-Match fence.
+        const journal = journalAt(journalPath);
+        expect(journal.files["docs/handoff.md"].remoteEtag).toBeTruthy();
+        expect(journal.files["docs/handoff.md"].localDiverges).toBe(true);
+    });
+    // --- `keep` semantics, revised 2026-08-21 -------------------------------
+    //
+    // `keep` now means "the CLOUD copy becomes the working copy; my local body is
+    // preserved beside it as a `.conflict-` sidecar." It used to mean the
+    // opposite — hold local, stamp the remote etag, arm `localDiverges` — and
+    // that combination was terminal: push refused the divergent local, pull saw
+    // the remote unchanged so it never replaced the entry, and every subsequent
+    // `keep` re-armed the flag. The file could converge in neither direction, and
+    // because the desktop app hardcodes `--on-conflict keep`, that was the
+    // default outcome for every real conflict.
+    //
+    // Electing the cloud body clears the divergence BY CONSTRUCTION — the entry
+    // then genuinely records what sits on disk — while the local bytes survive
+    // under the sidecar for the operator to re-apply. Nothing is destroyed; the
+    // working copy changes and the old one is renamed.
+    it("conflict keep takes the cloud body at the original path and preserves local in a `.conflict-` sidecar", async () => {
+        const companyDocs = path.join(tmpDir, "companies", "acme", "docs");
+        fs.mkdirSync(companyDocs, { recursive: true });
+        fs.writeFileSync(path.join(companyDocs, "handoff.md"), "local version");
+        vi.mocked(s3Module.listRemoteFiles).mockResolvedValueOnce([
+            { key: "docs/handoff.md", size: 42, lastModified: new Date(), etag: '"divergent"' },
+        ]);
+        fs.writeFileSync(journalPath, JSON.stringify({
+            version: "1",
+            lastSync: new Date().toISOString(),
+            files: {
+                "docs/handoff.md": {
+                    hash: "old-hash-from-last-sync",
+                    size: 20,
+                    syncedAt: new Date(Date.now() - 3600000).toISOString(),
+                    direction: "down",
+                },
+            },
+        }));
+        const result = await sync({
+            company: "acme",
+            onConflict: "keep",
+            vaultConfig: mockConfig,
+            hqRoot: tmpDir,
+        });
+        expect(result.conflicts).toBe(1);
+        expect(result.conflictPaths).toEqual(["docs/handoff.md"]);
+        // The cloud body is the working copy now.
+        expect(fs.readFileSync(path.join(companyDocs, "handoff.md"), "utf-8")).toBe("mock file content");
+        // …and the local body is not lost — it is sitting beside it.
+        const sidecars = fs
+            .readdirSync(companyDocs)
+            .filter((f) => f.includes(".conflict-"));
+        expect(sidecars).toHaveLength(1);
+        expect(fs.readFileSync(path.join(companyDocs, sidecars[0]), "utf-8")).toBe("local version");
+    });
+    it("conflict keep clears the fetched sidecar before rename for Windows compatibility", async () => {
+        const companyDocs = path.join(tmpDir, "companies", "acme", "docs");
+        fs.mkdirSync(companyDocs, { recursive: true });
+        const originalPath = path.join(companyDocs, "handoff.md");
+        fs.writeFileSync(originalPath, "local version");
+        vi.mocked(s3Module.listRemoteFiles).mockResolvedValueOnce([
+            { key: "docs/handoff.md", size: 42, lastModified: new Date(), etag: '"divergent"' },
+        ]);
+        fs.writeFileSync(journalPath, JSON.stringify({
+            version: "1",
+            lastSync: new Date().toISOString(),
+            files: {
+                "docs/handoff.md": {
+                    hash: "old-hash-from-last-sync",
+                    size: 20,
+                    syncedAt: new Date(Date.now() - 3600000).toISOString(),
+                    direction: "down",
+                },
+            },
+        }));
+        // Node's Windows rename does not replace an occupied destination. Model
+        // that rule only for the local→sidecar move; unrelated atomic index and
+        // journal renames keep using the host filesystem's normal behaviour.
+        const realRenameSync = fs.renameSync;
+        const renameSpy = vi.spyOn(fs, "renameSync").mockImplementation((from, to) => {
+            if (String(from) === originalPath &&
+                String(to).includes(".conflict-") &&
+                fs.existsSync(to)) {
+                throw errnoError("EEXIST");
+            }
+            return realRenameSync(from, to);
+        });
+        try {
+            await sync({
+                company: "acme",
+                onConflict: "keep",
+                vaultConfig: mockConfig,
+                hqRoot: tmpDir,
+            });
+        }
+        finally {
+            renameSpy.mockRestore();
+        }
+        expect(fs.readFileSync(originalPath, "utf-8")).toBe("mock file content");
+        expect(fs.readFileSync(sidecarIn(companyDocs), "utf-8")).toBe("local version");
+    });
+    it("conflict keep converges the journal on the REMOTE body and leaves localDiverges unset", async () => {
+        const companyDocs = path.join(tmpDir, "companies", "acme", "docs");
+        fs.mkdirSync(companyDocs, { recursive: true });
+        fs.writeFileSync(path.join(companyDocs, "handoff.md"), "local version");
+        vi.mocked(s3Module.listRemoteFiles).mockResolvedValueOnce([
+            { key: "docs/handoff.md", size: 42, lastModified: new Date(), etag: '"divergent"' },
+        ]);
+        fs.writeFileSync(journalPath, JSON.stringify({
+            version: "1",
+            lastSync: new Date().toISOString(),
+            files: {
+                "docs/handoff.md": {
+                    hash: "old-hash-from-last-sync",
+                    size: 20,
+                    syncedAt: new Date(Date.now() - 3600000).toISOString(),
+                    direction: "down",
+                },
+            },
+        }));
+        await sync({
+            company: "acme",
+            onConflict: "keep",
+            vaultConfig: mockConfig,
+            hqRoot: tmpDir,
+        });
+        const entry = journalAt(journalPath).files["docs/handoff.md"];
+        expect(entry.remoteEtag).toBeTruthy();
+        // The whole point of the change: the entry describes the body that is
+        // actually on disk, so the honesty flag has nothing to report. A set flag
+        // here would re-create the deadlock this test exists to prevent.
+        expect(entry.localDiverges).toBeFalsy();
+    });
+    it("conflict keep records the REMOTE body's hash, so the entry is pushable instead of permanently divergent", async () => {
+        // This is the deadlock in one assertion. The old `keep` wrote the LOCAL
+        // hash next to the REMOTE etag, which is a self-contradictory entry: the
+        // push leg refuses to send a body the journal calls divergent, and the pull
+        // leg sees a remote whose etag already matches and leaves it alone. Writing
+        // the remote hash is what makes the entry describable — and therefore
+        // sendable — again.
+        const companyDocs = path.join(tmpDir, "companies", "acme", "docs");
+        fs.mkdirSync(companyDocs, { recursive: true });
+        fs.writeFileSync(path.join(companyDocs, "handoff.md"), "local version");
+        vi.mocked(s3Module.listRemoteFiles).mockResolvedValueOnce([
+            { key: "docs/handoff.md", size: 42, lastModified: new Date(), etag: '"divergent"' },
+        ]);
+        fs.writeFileSync(journalPath, JSON.stringify({
+            version: "1",
+            lastSync: new Date().toISOString(),
+            files: {
+                "docs/handoff.md": {
+                    hash: "old-hash-from-last-sync",
+                    size: 20,
+                    syncedAt: new Date(Date.now() - 3600000).toISOString(),
+                    direction: "down",
+                },
+            },
+        }));
+        await sync({
+            company: "acme",
+            onConflict: "keep",
+            vaultConfig: mockConfig,
+            hqRoot: tmpDir,
+        });
+        // Pinned to the REMOTE body specifically, not to "whatever is on disk" —
+        // the old behaviour also left those two agreeing (it recorded the local
+        // hash and left the local file in place), so a disk-relative assertion
+        // would pass against the very bug this guards.
+        const remoteHash = crypto
+            .createHash("sha256")
+            .update("mock file content")
+            .digest("hex");
+        const entry = journalAt(journalPath).files["docs/handoff.md"];
+        expect(entry.hash).toBe(remoteHash);
+    });
+    it("conflict keep indexes the sidecar as the LOCAL body so /resolve-conflicts offers the right side", async () => {
+        const companyDocs = path.join(tmpDir, "companies", "acme", "docs");
+        fs.mkdirSync(companyDocs, { recursive: true });
+        fs.writeFileSync(path.join(companyDocs, "handoff.md"), "local version");
+        vi.mocked(s3Module.listRemoteFiles).mockResolvedValueOnce([
+            { key: "docs/handoff.md", size: 42, lastModified: new Date(), etag: '"divergent"' },
+        ]);
+        fs.writeFileSync(journalPath, JSON.stringify({
+            version: "1",
+            lastSync: new Date().toISOString(),
+            files: {
+                "docs/handoff.md": {
+                    hash: "old-hash-from-last-sync",
+                    size: 20,
+                    syncedAt: new Date(Date.now() - 3600000).toISOString(),
+                    direction: "down",
+                },
+            },
+        }));
+        await sync({
+            company: "acme",
+            onConflict: "keep",
+            vaultConfig: mockConfig,
+            hqRoot: tmpDir,
+        });
+        const index = JSON.parse(fs.readFileSync(path.join(tmpDir, ".hq-conflicts", "index.json"), "utf-8"));
+        expect(index.conflicts).toHaveLength(1);
+        const entry = index.conflicts[0];
+        expect(entry.originalPath).toBe("companies/acme/docs/handoff.md");
+        expect(entry.preserved).toBe("local");
+        // The sidecar it points at holds the LOCAL body — the side the operator
+        // may want back. Reading the recorded path is the contract /resolve-conflicts
+        // relies on, so assert through it rather than re-globbing the directory.
+        expect(fs.readFileSync(path.join(tmpDir, entry.conflictPath), "utf-8")).toBe("local version");
+    });
+    it("interactive `skip` still leaves local in place — skip is not keep", async () => {
+        // `skip` means "do not touch this one, I will deal with it later". It is a
+        // separate arm from `keep` and must NOT adopt the cloud body; a strategy
+        // that says "leave it alone" may not rename the operator's file.
+        const companyDocs = path.join(tmpDir, "companies", "acme", "docs");
+        fs.mkdirSync(companyDocs, { recursive: true });
+        fs.writeFileSync(path.join(companyDocs, "handoff.md"), "local version");
+        vi.mocked(s3Module.listRemoteFiles).mockResolvedValueOnce([
+            { key: "docs/handoff.md", size: 42, lastModified: new Date(), etag: '"divergent"' },
+        ]);
+        fs.writeFileSync(journalPath, JSON.stringify({
+            version: "1",
+            lastSync: new Date().toISOString(),
+            files: {
+                "docs/handoff.md": {
+                    hash: "old-hash-from-last-sync",
+                    size: 20,
+                    syncedAt: new Date(Date.now() - 3600000).toISOString(),
+                    direction: "down",
+                },
+            },
+        }));
+        const resolveSpy = vi
+            .spyOn(conflictModule, "resolveConflict")
+            .mockResolvedValue("skip");
+        try {
+            await sync({
+                company: "acme",
+                vaultConfig: mockConfig,
+                hqRoot: tmpDir,
+            });
+        }
+        finally {
+            resolveSpy.mockRestore();
+        }
+        expect(fs.readFileSync(path.join(companyDocs, "handoff.md"), "utf-8")).toBe("local version");
+    });
     it("a genuine download clears a stale localDiverges flag (entry is now truly local==remote)", async () => {
         const companyDocs = path.join(tmpDir, "companies", "acme", "docs");
         fs.mkdirSync(companyDocs, { recursive: true });
@@ -548,7 +930,7 @@ describe("sync", () => {
         ]);
         await sync({ company: "acme", vaultConfig: mockConfig, hqRoot: tmpDir });
         expect(fs.existsSync(path.join(companyDocs, "handoff.md"))).toBe(true);
-        const journal = JSON.parse(fs.readFileSync(journalPath, "utf-8"));
+        const journal = journalAt(journalPath);
         expect(journal.files["docs/handoff.md"]?.localDiverges).toBeFalsy();
     });
     it("leaves a downloaded unreadable link unjournaled without emitting a fatal error", async () => {
@@ -587,7 +969,7 @@ describe("sync", () => {
                 samplePaths: [linkKey],
             });
             expect(events.some((event) => event.type === "error")).toBe(false);
-            const journal = JSON.parse(fs.readFileSync(journalPath, "utf-8"));
+            const journal = journalAt(journalPath);
             expect(journal.files[linkKey]).toBeUndefined();
         }
         finally {
@@ -685,7 +1067,7 @@ describe("sync", () => {
         expect(litter).toEqual([]);
         // Journal re-stamped off the stale baseline (hash now matches local,
         // remoteEtag recorded) so the phantom conflict can't re-fire.
-        const journalAfter = JSON.parse(fs.readFileSync(journalPath, "utf-8"));
+        const journalAfter = journalAt(journalPath);
         expect(journalAfter.files["docs/handoff.md"].hash).not.toBe("stale-hash");
         expect(journalAfter.files["docs/handoff.md"].remoteEtag).toBeTruthy();
     });
@@ -743,7 +1125,7 @@ describe("sync", () => {
             });
             expect(events.some((event) => event.type === "error")).toBe(false);
             expect(fs.readFileSync(localPath, "utf-8")).toBe("local version");
-            const journal = JSON.parse(fs.readFileSync(journalPath, "utf-8"));
+            const journal = journalAt(journalPath);
             expect(journal.files[linkKey].hash).toBe("stale-hash");
         }
         finally {
@@ -782,13 +1164,10 @@ describe("sync", () => {
         });
         expect(result.conflicts).toBe(1);
         expect(result.conflictPaths).toEqual(["docs/handoff.md"]);
-        // Local preserved on keep.
-        expect(fs.readFileSync(path.join(companyDocs, "handoff.md"), "utf-8")).toBe("local version");
-        // Mirror retained for inspection.
-        const litter = fs
-            .readdirSync(companyDocs)
-            .filter((f) => f.includes(".conflict-"));
-        expect(litter).toHaveLength(1);
+        // Cloud body adopted at the original name on keep…
+        expect(fs.readFileSync(path.join(companyDocs, "handoff.md"), "utf-8")).toBe("mock file content");
+        // …and exactly one sidecar retained, holding the displaced local body.
+        expect(fs.readFileSync(sidecarIn(companyDocs), "utf-8")).toBe("local version");
     });
     it("cloud-authoritative file is PULL-WINS on conflict: overwrites local, no mirror, no false-stamp", async () => {
         // company-brief.md is server-regenerated (gardener), so a divergence is not
@@ -901,10 +1280,12 @@ describe("sync", () => {
         // Surfaced as a conflict, NOT a silent download.
         expect(result.conflicts).toBe(1);
         expect(result.conflictPaths).toEqual(["docs/handoff.md"]);
-        expect(result.filesDownloaded).toBe(0);
-        // The newer local bytes are intact — nothing was rolled back.
-        expect(fs.readFileSync(localPath, "utf-8")).toBe(localContent);
-        // Remote preserved as an inspection mirror rather than overwriting local.
+        expect(result.filesDownloaded).toBe(1);
+        // The newer local bytes are not lost — the rollback is survivable because
+        // `keep` renames them aside rather than discarding them. The guard's job is
+        // to route this through conflict resolution instead of a silent download;
+        // which side ends up at the original name is the strategy's call.
+        expect(fs.readFileSync(sidecarIn(path.dirname(localPath)), "utf-8")).toBe(localContent);
         const litter = fs
             .readdirSync(companyDocs)
             .filter((f) => f.includes(".conflict-"));
@@ -964,8 +1345,8 @@ describe("sync", () => {
         });
         expect(result.conflicts).toBe(1);
         expect(result.conflictPaths).toEqual(["docs/handoff.md"]);
-        expect(result.filesDownloaded).toBe(0);
-        expect(fs.readFileSync(localPath, "utf-8")).toBe(localEdit);
+        expect(result.filesDownloaded).toBe(1);
+        expect(fs.readFileSync(sidecarIn(path.dirname(localPath)), "utf-8")).toBe(localEdit);
     });
     it("anti-rollback guard is direction-gated: a SMALLER remote on a clean CONSUMER copy (direction=down) downloads, not conflict", async () => {
         // The device only ever PULLED this file (direction: "down") — a consumer
@@ -1089,18 +1470,16 @@ describe("sync", () => {
         // Surfaced as a conflict, NOT a silent download.
         expect(result.conflicts).toBe(1);
         expect(result.conflictPaths).toEqual(["docs/handoff.md"]);
-        expect(result.filesDownloaded).toBe(0);
-        // The local edit is intact.
-        expect(fs.readFileSync(localPath, "utf-8")).toBe(localContent);
-        // Cloud copy preserved alongside it for inspection / `/resolve-conflicts`.
-        const litter = fs
-            .readdirSync(companyDocs)
-            .filter((f) => f.includes(".conflict-"));
-        expect(litter).toHaveLength(1);
-        expect(fs.readFileSync(path.join(companyDocs, litter[0]), "utf-8")).toBe("mock file content");
+        expect(result.filesDownloaded).toBe(1);
+        // The unjournaled local body is not lost — it is renamed aside, which is
+        // what makes adopting the cloud copy survivable for a file that had no
+        // sync history at all.
+        expect(fs.readFileSync(sidecarIn(path.dirname(localPath)), "utf-8")).toBe(localContent);
+        // The cloud body took the original name.
+        expect(fs.readFileSync(localPath, "utf-8")).toBe("mock file content");
         // And a durable record exists so the overwrite can never be silent.
         const index = JSON.parse(fs.readFileSync(path.join(tmpDir, ".hq-conflicts", "index.json"), "utf-8"));
-        expect(index.conflicts.some((c) => c.originalPath === "companies/acme/docs/handoff.md")).toBe(true);
+        expect(index.conflicts.some((c) => c.originalPath === "companies/acme/docs/handoff.md" && c.preserved === "local")).toBe(true);
     });
     it("untracked-local guard is free on first pull: an unjournaled local file that already MATCHES the cloud reconciles silently", async () => {
         // The guard must not manufacture conflicts for the common case — a fresh
@@ -1131,7 +1510,7 @@ describe("sync", () => {
             .filter((f) => f.includes(".conflict-"));
         expect(litter).toHaveLength(0);
         // Journal stamped, so the next pass is a plain unchanged-skip.
-        const journal = JSON.parse(fs.readFileSync(journalPath, "utf-8"));
+        const journal = journalAt(journalPath);
         expect(journal.files["docs/handoff.md"]).toBeDefined();
     });
     it("RF-F02EXEC: refuses a download whose parent symlink appears after planning", async () => {
@@ -1291,7 +1670,7 @@ describe("sync", () => {
         });
         expect(fs.readFileSync(untrackedPath, "utf-8")).toBe("brand new local work");
         expect(fs.existsSync(trackedPath)).toBe(false);
-        const journal = JSON.parse(fs.readFileSync(journalPath, "utf-8"));
+        const journal = journalAt(journalPath);
         expect(journal.files[untrackedKey]).toBeUndefined();
         expect(journal.files[trackedKey]).toBeUndefined();
     });
@@ -1364,7 +1743,7 @@ describe("sync", () => {
         await sync({ company: "acme", vaultConfig: mockConfig, hqRoot: tmpDir });
         expect(s3Module.downloadFile).toHaveBeenCalledWith(expect.anything(), key, expect.anything(), expect.anything());
         expect(fs.readFileSync(localPath, "utf-8")).toBe("mock file content");
-        const journal = JSON.parse(fs.readFileSync(journalPath, "utf-8"));
+        const journal = journalAt(journalPath);
         expect(journal.files[key]?.removedAt).toBeUndefined();
     });
     it("does not canonicalize ignored remote-missing journal keys in the tombstone sweep", async () => {
@@ -1412,7 +1791,7 @@ describe("sync", () => {
         // Equivalence: an ignored key is never tombstoned — the local file and its
         // journal entry both survive, exactly as before the fix.
         expect(fs.existsSync(ignoredLocal)).toBe(true);
-        const sweptJournal = JSON.parse(fs.readFileSync(journalPath, "utf-8"));
+        const sweptJournal = journalAt(journalPath);
         expect(sweptJournal.files[ignoredKey]).toBeDefined();
     });
     it("tombstone lookup failure does not resurrect a current intent-backed delete", async () => {
@@ -1446,7 +1825,7 @@ describe("sync", () => {
         await sync({ company: "acme", vaultConfig: mockConfig, hqRoot: tmpDir });
         expect(s3Module.downloadFile).not.toHaveBeenCalledWith(expect.anything(), key, expect.anything(), expect.anything());
         expect(fs.existsSync(localPath)).toBe(false);
-        expect(JSON.parse(fs.readFileSync(journalPath, "utf8")).files[key]
+        expect(journalAt(journalPath).files[key]
             ?.removedReason).toBe("local-delete");
     });
     it("pull producer: a BULK disappearance is drift-restored, NOT tombstoned (ridge-incident guard in the pull leg)", async () => {
@@ -1482,7 +1861,7 @@ describe("sync", () => {
         await sync({ company: "acme", vaultConfig: mockConfig, hqRoot: tmpDir });
         // All restored, none tombstoned.
         expect(s3Module.downloadFile).toHaveBeenCalledTimes(12);
-        const journal = JSON.parse(fs.readFileSync(journalPath, "utf-8"));
+        const journal = journalAt(journalPath);
         for (const k of keys) {
             expect(journal.files[k]?.removedAt).toBeUndefined();
         }
@@ -1523,7 +1902,7 @@ describe("sync", () => {
         await sync({ company: "acme", vaultConfig: mockConfig, hqRoot: tmpDir });
         expect(s3Module.downloadFile).not.toHaveBeenCalledWith(expect.anything(), key, expect.anything());
         expect(fs.existsSync(localPath)).toBe(false);
-        const journal = JSON.parse(fs.readFileSync(journalPath, "utf-8"));
+        const journal = journalAt(journalPath);
         // Entry PRESERVED as a tombstone, not removed.
         expect(journal.files[key]?.removedAt).toBeTruthy();
         expect(journal.files[key]?.removedReason).toBe("local-delete");
@@ -1555,7 +1934,7 @@ describe("sync", () => {
     it("stamps journal.lastSync on every successful run, even when nothing transferred", async () => {
         // First run downloads both remote files and stamps lastSync.
         await sync({ company: "acme", vaultConfig: mockConfig, hqRoot: tmpDir });
-        const firstStamp = JSON.parse(fs.readFileSync(journalPath, "utf-8")).lastSync;
+        const firstStamp = journalAt(journalPath).lastSync;
         expect(firstStamp).not.toBe("");
         // Second run: same remote, same local — Stage-2 plan is all-skip, so
         // updateEntry never fires. lastSync must still advance, otherwise the
@@ -1563,7 +1942,7 @@ describe("sync", () => {
         await new Promise((r) => setTimeout(r, 5));
         const result = await sync({ company: "acme", vaultConfig: mockConfig, hqRoot: tmpDir });
         expect(result.filesDownloaded).toBe(0);
-        const secondStamp = JSON.parse(fs.readFileSync(journalPath, "utf-8")).lastSync;
+        const secondStamp = journalAt(journalPath).lastSync;
         expect(new Date(secondStamp).getTime()).toBeGreaterThan(new Date(firstStamp).getTime());
     });
     it("journalSlug: 'personal' routes journal I/O to sync-journal.personal.json", async () => {
@@ -1654,13 +2033,9 @@ describe("sync", () => {
         expect(fs.existsSync(path.join(tmpDir, "companies", "foo", "bar.md"))).toBe(false);
         // The whole point: it now gets a journal baseline, so the push side stops
         // re-firing a transient conflict every sync (the bug this fix closes).
-        const journaledManifest = fs
-            .readdirSync(stateDir)
-            .filter((f) => f.startsWith("sync-journal."))
-            .some((f) => {
-            const j = JSON.parse(fs.readFileSync(path.join(stateDir, f), "utf8"));
-            return j.files?.["companies/manifest.yaml"] != null;
-        });
+        // Enumerate through the API: the per-slug JSON files are locators now, so
+        // reading them directly finds no `files` map at all.
+        const journaledManifest = listJournals().some((j) => j.journal.files?.["companies/manifest.yaml"] != null);
         expect(journaledManifest).toBe(true);
     });
     it("personalMode pull lands the session-continuity pointer + active thread file under <hqRoot>/workspace/threads/ so a handoff resumes on machine B (DEV-1778)", async () => {
@@ -1754,9 +2129,10 @@ describe("sync", () => {
         });
         expect(result.conflicts).toBe(1);
         expect(result.conflictPaths).toEqual(["workspace/threads/handoff.json"]);
-        expect(result.filesSkipped).toBeGreaterThanOrEqual(1);
-        // B's newer local pointer is preserved verbatim — not clobbered by A's.
-        const kept = JSON.parse(fs.readFileSync(path.join(threadsLocal, "handoff.json"), "utf-8"));
+        // B's newer local pointer is preserved verbatim — renamed aside rather than
+        // destroyed. DEV-1778 was about the pointer being LOST; a recoverable
+        // sidecar satisfies that, and the machine can still resume from it.
+        const kept = JSON.parse(fs.readFileSync(sidecarIn(threadsLocal), "utf-8"));
         expect(kept.message).toBe("newer local from B");
         expect(kept.thread_path).toBe("workspace/threads/T-machineB.json");
     });
@@ -1913,7 +2289,7 @@ describe("sync", () => {
         expect(result.filesTombstoned).toBeGreaterThanOrEqual(1);
         // Journal entry for the deleted path must be gone too — otherwise
         // the next sync would tombstone the same key on every run.
-        const journal = JSON.parse(fs.readFileSync(journalPath, "utf-8"));
+        const journal = journalAt(journalPath);
         expect(journal.files["docs/deleted-by-peer.md"]).toBeUndefined();
         expect(journal.files["docs/kept.md"]).toBeDefined();
     });
@@ -1978,7 +2354,7 @@ describe("sync", () => {
         expect(result.filesTombstoned).toBe(0);
         // The journal is healed: the malformed key is gone, the canonical POSIX key
         // points at the live file (so a future pull stays converged, not poisoned).
-        const journal = JSON.parse(fs.readFileSync(journalPath, "utf-8"));
+        const journal = journalAt(journalPath);
         expect(journal.files[backslashKey]).toBeUndefined();
         expect(journal.files[posixKey]).toBeDefined();
         expect(Object.keys(journal.files).some((k) => k.includes("\\"))).toBe(false);
@@ -2031,7 +2407,7 @@ describe("sync", () => {
         expect(result.filesTombstoned).toBe(0);
         // Journal entry retained — next sync (push) will re-evaluate and
         // either re-upload the divergent local or surface as a conflict.
-        const journal = JSON.parse(fs.readFileSync(journalPath, "utf-8"));
+        const journal = journalAt(journalPath);
         expect(journal.files["docs/edited-locally.md"]).toBeDefined();
         expect(journal.files["docs/edited-locally.md"].hash).toBe(baselineHash);
     });
@@ -2075,7 +2451,7 @@ describe("sync", () => {
         expect(result.filesTombstoned).toBe(0);
         expect(fs.existsSync(racedPath)).toBe(true);
         expect(fs.readFileSync(racedPath, "utf-8")).toBe("concurrent local edit");
-        const journal = JSON.parse(fs.readFileSync(journalPath, "utf-8"));
+        const journal = journalAt(journalPath);
         expect(journal.files["docs/racy-delete.md"]).toBeDefined();
         expect(journal.files["docs/racy-delete.md"].hash).toBe(baselineHash);
     });
@@ -2112,7 +2488,7 @@ describe("sync", () => {
         expect(result.filesTombstoned).toBe(0);
         expect(result.conflicts).toBe(1);
         expect(fs.readFileSync(localPath, "utf-8")).toBe(baseline);
-        const journal = JSON.parse(fs.readFileSync(journalPath, "utf-8"));
+        const journal = journalAt(journalPath);
         expect(journal.files["docs/created-after-plan.md"]).toBeDefined();
     });
     it("CAS: preserves a concurrent local edit when a staged download is ready to replace it", async () => {
@@ -2196,7 +2572,7 @@ describe("sync", () => {
             propagateDeletePolicy: "all",
         });
         expect(s3Module.deleteRemoteFile).not.toHaveBeenCalled();
-        const journal = JSON.parse(fs.readFileSync(personalJournalPath, "utf-8"));
+        const journal = journalAt(personalJournalPath);
         expect(journal.files["core/core.yaml"]).toBeDefined();
         expect(journal.files[".claude/skills/core:demo/SKILL.md"]).toBeDefined();
     });
@@ -2230,7 +2606,7 @@ describe("sync", () => {
         });
         expect(s3Module.deleteRemoteFile).not.toHaveBeenCalled();
         expect(result.filesRefusedStale).toBe(2);
-        const journal = JSON.parse(fs.readFileSync(journalPath, "utf-8"));
+        const journal = journalAt(journalPath);
         expect(journal.files["docs/a.md"]).toBeDefined();
         expect(journal.files["docs/b.md"]).toBeDefined();
     });
@@ -2258,10 +2634,16 @@ describe("sync", () => {
             },
             pulls: [],
         }));
-        vi.mocked(s3Module.headRemoteFile).mockResolvedValueOnce({
+        vi.mocked(s3Module.headRemoteFile)
+            .mockResolvedValueOnce({
             etag: "old-etag",
             size: baseline.length,
             lastModified: new Date(),
+        })
+            .mockResolvedValueOnce({
+            etag: "peer-etag",
+            size: "mock file content".length,
+            lastModified: new Date(),
         });
         const preconditionError = Object.assign(new Error("remote changed"), {
             name: "PreconditionFailed",
@@ -2277,7 +2659,15 @@ describe("sync", () => {
             onConflict: "keep",
         });
         expect(result.conflictPaths).toContain("board.json");
-        expect(fs.readFileSync(boardPath, "utf-8")).toBe(localAppend);
+        // The conditional PUT still fails closed, but keep is cloud-wins: the
+        // peer body takes the working name and the local append remains in the
+        // sidecar for explicit resolution.
+        expect(fs.readFileSync(boardPath, "utf-8")).toBe("mock file content");
+        expect(fs.readFileSync(sidecarIn(companyRoot), "utf-8")).toBe(localAppend);
+        expect(journalAt(journalPath).files["board.json"]).toMatchObject({
+            remoteEtag: "peer-etag",
+            direction: "down",
+        });
         expect(s3Module.uploadFile).toHaveBeenCalledWith(expect.anything(), boardPath, "board.json", undefined, { ifMatch: "old-etag" });
     });
     it("does NOT tombstone symlinks whose readlink target has diverged from the journal (Codex P1 round 4)", async () => {
@@ -2322,7 +2712,7 @@ describe("sync", () => {
         expect(fs.lstatSync(linkPath).isSymbolicLink()).toBe(true);
         expect(fs.readlinkSync(linkPath)).toBe("new-target.md");
         expect(result.filesTombstoned).toBe(0);
-        const journal = JSON.parse(fs.readFileSync(journalPath, "utf-8"));
+        const journal = journalAt(journalPath);
         expect(journal.files["docs/link.md"]).toBeDefined();
         expect(journal.files["docs/link.md"].hash).toBe(baselineHash);
     });
@@ -2389,7 +2779,7 @@ describe("sync", () => {
         // The really-deleted file MUST be tombstoned.
         expect(fs.existsSync(reallyDeletedPath)).toBe(false);
         expect(result.filesTombstoned).toBe(1);
-        const journal = JSON.parse(fs.readFileSync(journalPath, "utf-8"));
+        const journal = journalAt(journalPath);
         // Journal entry retained for the invisible key (so next sync at
         // broader scope can re-evaluate).
         expect(journal.files["docs/invisible-to-list.md"]).toBeDefined();
@@ -2463,7 +2853,7 @@ describe("sync", () => {
         expect(result.filesDownloaded).toBe(0);
         expect(result.filesTombstoned).toBeGreaterThanOrEqual(1);
         // Journal entry dropped so it converges (no re-tombstone next run).
-        const journal = JSON.parse(fs.readFileSync(journalPath, "utf-8"));
+        const journal = journalAt(journalPath);
         expect(journal.files["docs/shared.md"]).toBeUndefined();
     });
     it("delete-resync: a re-created object NEWER than the tombstone DOES sync (tombstone is not permanent)", async () => {
@@ -2555,7 +2945,7 @@ describe("sync", () => {
         expect(result.conflicts).toBeGreaterThanOrEqual(1);
         expect(result.conflictPaths).toContain("docs/edited.md");
         expect(fs.existsSync(editedPath)).toBe(true);
-        expect(fs.readFileSync(editedPath, "utf-8")).toBe("my local edits");
+        expect(fs.readFileSync(sidecarIn(path.dirname(editedPath)), "utf-8")).toBe("my local edits");
         expect(result.filesTombstoned).toBe(0);
     });
     it("delete-resync: suppression is per-key and the fetch is company-scoped (no cross-tenant bleed)", async () => {
@@ -2627,7 +3017,7 @@ describe("sync", () => {
         });
         expect(fs.existsSync(deniedPath)).toBe(true);
         expect(result.filesTombstoned).toBe(0);
-        const journal = JSON.parse(fs.readFileSync(journalPath, "utf-8"));
+        const journal = journalAt(journalPath);
         expect(journal.files["docs/out-of-scope.md"]).toBeDefined();
     });
     it("retains the journal entry when tombstone unlink fails with EACCES (Codex P1 — Bug #9 follow-up)", async () => {
@@ -2675,7 +3065,7 @@ describe("sync", () => {
             // Tombstone NOT counted — the delete wasn't honored.
             expect(result.filesTombstoned).toBe(0);
             // Journal entry MUST be retained so the next sync retries.
-            const journal = JSON.parse(fs.readFileSync(journalPath, "utf-8"));
+            const journal = journalAt(journalPath);
             expect(journal.files["docs/locked-by-peer.md"]).toBeDefined();
             expect(journal.files["docs/locked-by-peer.md"].hash).toBe("locked-hash");
         }
@@ -2902,7 +3292,7 @@ describe("sync", () => {
             expect(s3Module.downloadFile).not.toHaveBeenCalled();
             expect(fs.existsSync(escapedPath)).toBe(false);
             expect(fs.existsSync(path.join(companyRoot, traversalKey))).toBe(false);
-            const journal = JSON.parse(fs.readFileSync(journalPath, "utf-8"));
+            const journal = journalAt(journalPath);
             expect(journal.files[traversalKey]).toBeUndefined();
         }
         finally {
@@ -2936,7 +3326,7 @@ describe("sync", () => {
             expect(s3Module.downloadFile).not.toHaveBeenCalled();
             expect(fs.existsSync(escapedPath)).toBe(false);
             expect(fs.existsSync(path.join(companyRoot, remoteKey))).toBe(false);
-            const journal = JSON.parse(fs.readFileSync(journalPath, "utf-8"));
+            const journal = journalAt(journalPath);
             expect(journal.files[remoteKey]).toBeUndefined();
         }
         finally {
@@ -3011,10 +3401,46 @@ describe("sync", () => {
             vaultConfig: mockConfig,
             hqRoot: tmpDir,
         });
-        const journal = JSON.parse(fs.readFileSync(journalPath, "utf-8"));
+        const journal = journalAt(journalPath);
         expect(journal.files["docs/handoff.md"].remoteEtag).toBe("abc123");
         expect(journal.files["knowledge/readme.md"].remoteEtag).toBe("def456");
     });
+    it("persists each downloaded hash before starting the next file", async () => {
+        process.env.HQ_SYNC_TRANSFER_CONCURRENCY = "1";
+        const remoteFiles = [
+            { key: "ordered/first.md", size: 18, lastModified: new Date(), etag: '"first-etag"' },
+            { key: "ordered/second.md", size: 18, lastModified: new Date(), etag: '"second-etag"' },
+        ];
+        const defaultDownload = vi.mocked(s3Module.downloadFile).getMockImplementation();
+        if (!defaultDownload)
+            throw new Error("missing default download mock");
+        try {
+            vi.mocked(s3Module.listRemoteFiles).mockResolvedValueOnce(remoteFiles);
+            vi.mocked(s3Module.downloadFile).mockImplementation(async (ctx, key, localPath, options) => {
+                if (key === "ordered/second.md") {
+                    const first = journalAt(journalPath).files["ordered/first.md"];
+                    expect(first).toMatchObject({
+                        hash: crypto.createHash("sha256").update("mock file content").digest("hex"),
+                        remoteEtag: "first-etag",
+                        direction: "down",
+                    });
+                    expect(first.localDiverges).toBeFalsy();
+                }
+                return defaultDownload(ctx, key, localPath, options);
+            });
+            await sync({
+                company: "acme",
+                vaultConfig: mockConfig,
+                hqRoot: tmpDir,
+                skipReindex: true,
+                onEvent: () => undefined,
+            });
+        }
+        finally {
+            vi.mocked(s3Module.downloadFile).mockImplementation(defaultDownload);
+            delete process.env.HQ_SYNC_TRANSFER_CONCURRENCY;
+        }
+    });
     it("checkpoints completed downloads so a failed bulk pass resumes only its tail", async () => {
         process.env.HQ_SYNC_TRANSFER_CONCURRENCY = "1";
         const remoteFiles = Array.from({ length: 9 }, (_, index) => ({
@@ -3032,7 +3458,7 @@ describe("sync", () => {
                 if (key === "bulk/file-8.md") {
                     // This models the next transfer crashing the process. The first
                     // eight entries must already be durable before the final writer.
-                    const checkpoint = JSON.parse(fs.readFileSync(journalPath, "utf-8"));
+                    const checkpoint = journalAt(journalPath);
                     expect(Object.keys(checkpoint.files)).toHaveLength(8);
                     throw new Error("simulated crash after checkpoint");
                 }
@@ -3046,7 +3472,7 @@ describe("sync", () => {
                 onEvent: () => undefined,
             });
             expect(first.filesDownloaded).toBe(8);
-            const checkpoint = JSON.parse(fs.readFileSync(journalPath, "utf-8"));
+            const checkpoint = journalAt(journalPath);
             expect(Object.keys(checkpoint.files)).toHaveLength(8);
             vi.mocked(s3Module.downloadFile).mockImplementation(defaultDownload);
             vi.mocked(s3Module.downloadFile).mockClear();
@@ -3497,7 +3923,7 @@ describe("sync", () => {
         // skip-unchanged works on the next tick.
         const journalMod = await import("../journal.js");
         const expectedHash = journalMod.hashSymlinkTarget(linkTarget);
-        const journal = JSON.parse(fs.readFileSync(journalPath, "utf-8"));
+        const journal = journalAt(journalPath);
         expect(journal.files[linkKey]).toMatchObject({
             hash: expectedHash,
             size: 0,
@@ -3829,7 +4255,7 @@ describe("sync", () => {
         expect(errOutput).toContain("manual");
         expect(errOutput).not.toContain("directory-overlay marker");
     });
-    it("shared-mode leg surfaces the materialization gap and names the shared→all lever (feedback_d2082110)", async () => {
+    it("shared-mode leg withholds out-of-scope keys at LIST time (scoped listing supersedes the feedback_d2082110 gap advisory)", async () => {
         // Reporter feedback_d2082110 (cody@jonesroadbeauty.com): four memberships
         // were configured as `shared` rather than `all`, so not all vault content
         // materialized on the second device — a SILENT gap the reporter had to
@@ -3862,16 +4288,19 @@ describe("sync", () => {
             onEvent: (e) => events.push(e),
         });
         // The in-scope key pulled; the out-of-scope key was NOT materialized.
+        // BEHAVIOR CHANGE (targeted-sync scoped listing): the shared leg lists
+        // ONLY its in-scope prefixes now, so the out-of-scope key never reaches
+        // the plan — filesOutOfScope is 0 and the scope-materialization-gap
+        // advisory (which counted plan-visible withheld keys) has nothing to
+        // report. The advisory's classification logic remains for full listings;
+        // the memory win of not materializing the whole vault LIST supersedes the
+        // withheld-count telemetry on scoped legs.
         expect(result.filesDownloaded).toBe(1);
-        expect(result.filesOutOfScope).toBe(1);
+        expect(result.filesOutOfScope).toBe(0);
         expect(fs.existsSync(path.join(tmpDir, "companies", "acme", "knowledge", "present.md"))).toBe(true);
         expect(fs.existsSync(path.join(tmpDir, "companies", "acme", "projects", "secret.md"))).toBe(false);
-        // The gap is now SURFACED with the count, the active mode, and the lever.
         const gap = events.find((e) => e.type === "scope-materialization-gap");
-        expect(gap).toBeDefined();
-        expect(gap.count).toBe(1);
-        expect(gap.syncMode).toBe("shared");
-        expect(gap.samplePaths).toEqual(["projects/secret.md"]);
+        expect(gap).toBeUndefined();
     });
     it("all-mode leg (default) never emits a materialization gap — no scoping, no noise", async () => {
         // Boundary for the feedback_d2082110 gap surface: in `all` mode every key is
@@ -4144,7 +4573,7 @@ describe("sync", () => {
         // The journal MUST be updated to reflect the user's keep
         // decision. Pre-fix: catch swallowed the ENOENT, journal stayed
         // at oldHash + old etag, every subsequent sync re-fired.
-        const journal = JSON.parse(fs.readFileSync(journalPath, "utf-8"));
+        const journal = journalAt(journalPath);
         const entry = journal.files[linkKey];
         expect(entry.hash).toBe(expectedNewHash);
         expect(entry.size).toBe(0);
@@ -4443,7 +4872,7 @@ describe("scope-invalid key hardening (companies/ prefix in a company vault —
         // Cleaned, not re-uploaded: local doubled-tree copy gone, journal dropped.
         expect(fs.existsSync(path.join(doubled, "poison.md"))).toBe(false);
         expect(result.filesTombstoned).toBeGreaterThanOrEqual(1);
-        const journal = JSON.parse(fs.readFileSync(journalPath, "utf-8"));
+        const journal = journalAt(journalPath);
         expect(journal.files["companies/acme/knowledge/poison.md"]).toBeUndefined();
         // No HEAD verify against the invalid key — the server validator would
         // reject it (INVALID_KEY_COMPANIES_SCOPED) and defer the cleanup forever.
@@ -4571,7 +5000,7 @@ describe("junk key-spelling guard (US-002 mixed-version amplifier)", () => {
         expect(events.filter((e) => e.type === "error")).toHaveLength(0);
         expect(result.aborted).toBe(false);
         expect(result.filesSkipped).toBe(1);
-        const journalAfter = JSON.parse(fs.readFileSync(journalPath, "utf-8"));
+        const journalAfter = journalAt(journalPath);
         expect(Object.keys(journalAfter.files)).not.toContain(junkKey);
     });
     it("still pulls a junk-spelling key that is ALREADY journaled under that exact spelling", async () => {
@@ -4616,7 +5045,7 @@ describe("junk key-spelling guard (US-002 mixed-version amplifier)", () => {
         // Junk twin still gated; the canonical journal entry tombstones out.
         expect(events.filter((e) => e.type === "skip-junk-key-spelling")).toHaveLength(1);
         expect(result.filesTombstoned).toBe(1);
-        const journalAfter = JSON.parse(fs.readFileSync(journalPath, "utf-8"));
+        const journalAfter = journalAt(journalPath);
         expect(Object.keys(journalAfter.files)).not.toContain(canonicalKey);
     });
     it("always downloads a CANONICAL remote key even when the journal holds only its junk twin (post-doctor convergence)", async () => {
@@ -4633,7 +5062,7 @@ describe("junk key-spelling guard (US-002 mixed-version amplifier)", () => {
         expect(vi.mocked(s3Module.downloadFile)).toHaveBeenCalledTimes(1);
         expect(vi.mocked(s3Module.downloadFile).mock.calls[0][1]).toBe(canonicalKey);
         expect(result.filesDownloaded).toBe(1);
-        const journalAfter = JSON.parse(fs.readFileSync(journalPath, "utf-8"));
+        const journalAfter = journalAt(journalPath);
         expect(Object.keys(journalAfter.files)).toContain(canonicalKey);
     });
     it("does not tombstone a journaled canonical key when the LIST holds only its junk twin", async () => {
@@ -4649,7 +5078,7 @@ describe("junk key-spelling guard (US-002 mixed-version amplifier)", () => {
         const { events, result } = await runSync();
         // Junk twin skipped, canonical entry NOT tombstoned.
         expect(events.filter((e) => e.type === "skip-junk-key-spelling")).toHaveLength(1);
-        const journalAfter = JSON.parse(fs.readFileSync(journalPath, "utf-8"));
+        const journalAfter = journalAt(journalPath);
         expect(Object.keys(journalAfter.files)).toContain(canonicalKey);
         expect(result.filesTombstoned ?? 0).toBe(0);
         expect(events.filter((e) => e.type === "error")).toHaveLength(0);