@indigoai-us/hq-cloud 6.15.30 → 6.15.31

package/dist/cli/sync.test.js

@@ -5,7 +5,6 @@ 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
@@ -14,13 +13,6 @@ 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"]);
@@ -123,37 +115,10 @@ 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, 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]);
-}
+import { readJournal, getEntry } from "../journal.js";
 const mockConfig = {
     apiUrl: "https://vault-api.test",
     authToken: "test-jwt-token",
@@ -501,7 +466,7 @@ describe("sync", () => {
         const result = await sync({ vaultConfig: mockConfig, hqRoot: tmpDir });
         expect(result.filesDownloaded).toBe(2);
     });
-    it("detects conflicts with local changes and adopts the cloud copy on --on-conflict keep", async () => {
+    it("detects conflicts with local changes and keeps local 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");
@@ -525,66 +490,10 @@ describe("sync", () => {
         });
         expect(result.conflicts).toBe(1);
         expect(result.conflictPaths).toEqual(["docs/handoff.md"]);
-        // `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("rechecks the current local body when executing a planned conflict", async () => {
-        const companyDocs = path.join(tmpDir, "companies", "acme", "docs");
-        fs.mkdirSync(companyDocs, { recursive: true });
-        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: "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();
+        expect(result.filesSkipped).toBeGreaterThanOrEqual(1);
+        expect(fs.readFileSync(path.join(companyDocs, "handoff.md"), "utf-8")).toBe("local version");
     });
-    it("conflict skip marks the entry localDiverges (journal-honesty: the held copy never matched the recorded remote etag)", async () => {
+    it("conflict keep marks the entry localDiverges (journal-honesty: kept 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");
@@ -600,311 +509,20 @@ describe("sync", () => {
                 },
             },
         }));
-        // `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 = journalAt(journalPath);
-        // remoteEtag still recorded so the conflict can't re-fire (#137 invariant)…
-        expect(journal.files["docs/handoff.md"].remoteEtag).toBeTruthy();
-        // …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",
+            onConflict: "keep",
             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);
+        const journal = JSON.parse(fs.readFileSync(journalPath, "utf-8"));
+        // 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
+        // delete cannot fire on a journal that lies about local==remote.
         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 });
@@ -930,7 +548,7 @@ describe("sync", () => {
         ]);
         await sync({ company: "acme", vaultConfig: mockConfig, hqRoot: tmpDir });
         expect(fs.existsSync(path.join(companyDocs, "handoff.md"))).toBe(true);
-        const journal = journalAt(journalPath);
+        const journal = JSON.parse(fs.readFileSync(journalPath, "utf-8"));
         expect(journal.files["docs/handoff.md"]?.localDiverges).toBeFalsy();
     });
     it("leaves a downloaded unreadable link unjournaled without emitting a fatal error", async () => {
@@ -969,7 +587,7 @@ describe("sync", () => {
                 samplePaths: [linkKey],
             });
             expect(events.some((event) => event.type === "error")).toBe(false);
-            const journal = journalAt(journalPath);
+            const journal = JSON.parse(fs.readFileSync(journalPath, "utf-8"));
             expect(journal.files[linkKey]).toBeUndefined();
         }
         finally {
@@ -1067,7 +685,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 = journalAt(journalPath);
+        const journalAfter = JSON.parse(fs.readFileSync(journalPath, "utf-8"));
         expect(journalAfter.files["docs/handoff.md"].hash).not.toBe("stale-hash");
         expect(journalAfter.files["docs/handoff.md"].remoteEtag).toBeTruthy();
     });
@@ -1125,7 +743,7 @@ describe("sync", () => {
             });
             expect(events.some((event) => event.type === "error")).toBe(false);
             expect(fs.readFileSync(localPath, "utf-8")).toBe("local version");
-            const journal = journalAt(journalPath);
+            const journal = JSON.parse(fs.readFileSync(journalPath, "utf-8"));
             expect(journal.files[linkKey].hash).toBe("stale-hash");
         }
         finally {
@@ -1164,10 +782,13 @@ describe("sync", () => {
         });
         expect(result.conflicts).toBe(1);
         expect(result.conflictPaths).toEqual(["docs/handoff.md"]);
-        // 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");
+        // 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);
     });
     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
@@ -1280,12 +901,10 @@ 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(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);
+        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.
         const litter = fs
             .readdirSync(companyDocs)
             .filter((f) => f.includes(".conflict-"));
@@ -1345,8 +964,8 @@ describe("sync", () => {
         });
         expect(result.conflicts).toBe(1);
         expect(result.conflictPaths).toEqual(["docs/handoff.md"]);
-        expect(result.filesDownloaded).toBe(1);
-        expect(fs.readFileSync(sidecarIn(path.dirname(localPath)), "utf-8")).toBe(localEdit);
+        expect(result.filesDownloaded).toBe(0);
+        expect(fs.readFileSync(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
@@ -1470,16 +1089,18 @@ 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(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");
+        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");
         // 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" && c.preserved === "local")).toBe(true);
+        expect(index.conflicts.some((c) => c.originalPath === "companies/acme/docs/handoff.md")).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
@@ -1510,7 +1131,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 = journalAt(journalPath);
+        const journal = JSON.parse(fs.readFileSync(journalPath, "utf-8"));
         expect(journal.files["docs/handoff.md"]).toBeDefined();
     });
     it("RF-F02EXEC: refuses a download whose parent symlink appears after planning", async () => {
@@ -1670,7 +1291,7 @@ describe("sync", () => {
         });
         expect(fs.readFileSync(untrackedPath, "utf-8")).toBe("brand new local work");
         expect(fs.existsSync(trackedPath)).toBe(false);
-        const journal = journalAt(journalPath);
+        const journal = JSON.parse(fs.readFileSync(journalPath, "utf-8"));
         expect(journal.files[untrackedKey]).toBeUndefined();
         expect(journal.files[trackedKey]).toBeUndefined();
     });
@@ -1743,7 +1364,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 = journalAt(journalPath);
+        const journal = JSON.parse(fs.readFileSync(journalPath, "utf-8"));
         expect(journal.files[key]?.removedAt).toBeUndefined();
     });
     it("does not canonicalize ignored remote-missing journal keys in the tombstone sweep", async () => {
@@ -1791,7 +1412,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 = journalAt(journalPath);
+        const sweptJournal = JSON.parse(fs.readFileSync(journalPath, "utf-8"));
         expect(sweptJournal.files[ignoredKey]).toBeDefined();
     });
     it("tombstone lookup failure does not resurrect a current intent-backed delete", async () => {
@@ -1825,7 +1446,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(journalAt(journalPath).files[key]
+        expect(JSON.parse(fs.readFileSync(journalPath, "utf8")).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 () => {
@@ -1861,7 +1482,7 @@ describe("sync", () => {
         await sync({ company: "acme", vaultConfig: mockConfig, hqRoot: tmpDir });
         // All restored, none tombstoned.
         expect(s3Module.downloadFile).toHaveBeenCalledTimes(12);
-        const journal = journalAt(journalPath);
+        const journal = JSON.parse(fs.readFileSync(journalPath, "utf-8"));
         for (const k of keys) {
             expect(journal.files[k]?.removedAt).toBeUndefined();
         }
@@ -1902,7 +1523,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 = journalAt(journalPath);
+        const journal = JSON.parse(fs.readFileSync(journalPath, "utf-8"));
         // Entry PRESERVED as a tombstone, not removed.
         expect(journal.files[key]?.removedAt).toBeTruthy();
         expect(journal.files[key]?.removedReason).toBe("local-delete");
@@ -1934,7 +1555,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 = journalAt(journalPath).lastSync;
+        const firstStamp = JSON.parse(fs.readFileSync(journalPath, "utf-8")).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
@@ -1942,7 +1563,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 = journalAt(journalPath).lastSync;
+        const secondStamp = JSON.parse(fs.readFileSync(journalPath, "utf-8")).lastSync;
         expect(new Date(secondStamp).getTime()).toBeGreaterThan(new Date(firstStamp).getTime());
     });
     it("journalSlug: 'personal' routes journal I/O to sync-journal.personal.json", async () => {
@@ -2033,9 +1654,13 @@ 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).
-        // 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);
+        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;
+        });
         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 () => {
@@ -2129,10 +1754,9 @@ describe("sync", () => {
         });
         expect(result.conflicts).toBe(1);
         expect(result.conflictPaths).toEqual(["workspace/threads/handoff.json"]);
-        // 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(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"));
         expect(kept.message).toBe("newer local from B");
         expect(kept.thread_path).toBe("workspace/threads/T-machineB.json");
     });
@@ -2289,7 +1913,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 = journalAt(journalPath);
+        const journal = JSON.parse(fs.readFileSync(journalPath, "utf-8"));
         expect(journal.files["docs/deleted-by-peer.md"]).toBeUndefined();
         expect(journal.files["docs/kept.md"]).toBeDefined();
     });
@@ -2354,7 +1978,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 = journalAt(journalPath);
+        const journal = JSON.parse(fs.readFileSync(journalPath, "utf-8"));
         expect(journal.files[backslashKey]).toBeUndefined();
         expect(journal.files[posixKey]).toBeDefined();
         expect(Object.keys(journal.files).some((k) => k.includes("\\"))).toBe(false);
@@ -2407,7 +2031,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 = journalAt(journalPath);
+        const journal = JSON.parse(fs.readFileSync(journalPath, "utf-8"));
         expect(journal.files["docs/edited-locally.md"]).toBeDefined();
         expect(journal.files["docs/edited-locally.md"].hash).toBe(baselineHash);
     });
@@ -2451,7 +2075,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 = journalAt(journalPath);
+        const journal = JSON.parse(fs.readFileSync(journalPath, "utf-8"));
         expect(journal.files["docs/racy-delete.md"]).toBeDefined();
         expect(journal.files["docs/racy-delete.md"].hash).toBe(baselineHash);
     });
@@ -2488,7 +2112,7 @@ describe("sync", () => {
         expect(result.filesTombstoned).toBe(0);
         expect(result.conflicts).toBe(1);
         expect(fs.readFileSync(localPath, "utf-8")).toBe(baseline);
-        const journal = journalAt(journalPath);
+        const journal = JSON.parse(fs.readFileSync(journalPath, "utf-8"));
         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 () => {
@@ -2572,7 +2196,7 @@ describe("sync", () => {
             propagateDeletePolicy: "all",
         });
         expect(s3Module.deleteRemoteFile).not.toHaveBeenCalled();
-        const journal = journalAt(personalJournalPath);
+        const journal = JSON.parse(fs.readFileSync(personalJournalPath, "utf-8"));
         expect(journal.files["core/core.yaml"]).toBeDefined();
         expect(journal.files[".claude/skills/core:demo/SKILL.md"]).toBeDefined();
     });
@@ -2606,7 +2230,7 @@ describe("sync", () => {
         });
         expect(s3Module.deleteRemoteFile).not.toHaveBeenCalled();
         expect(result.filesRefusedStale).toBe(2);
-        const journal = journalAt(journalPath);
+        const journal = JSON.parse(fs.readFileSync(journalPath, "utf-8"));
         expect(journal.files["docs/a.md"]).toBeDefined();
         expect(journal.files["docs/b.md"]).toBeDefined();
     });
@@ -2634,16 +2258,10 @@ 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",
@@ -2659,15 +2277,7 @@ describe("sync", () => {
             onConflict: "keep",
         });
         expect(result.conflictPaths).toContain("board.json");
-        // 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(fs.readFileSync(boardPath, "utf-8")).toBe(localAppend);
         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 () => {
@@ -2712,7 +2322,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 = journalAt(journalPath);
+        const journal = JSON.parse(fs.readFileSync(journalPath, "utf-8"));
         expect(journal.files["docs/link.md"]).toBeDefined();
         expect(journal.files["docs/link.md"].hash).toBe(baselineHash);
     });
@@ -2779,7 +2389,7 @@ describe("sync", () => {
         // The really-deleted file MUST be tombstoned.
         expect(fs.existsSync(reallyDeletedPath)).toBe(false);
         expect(result.filesTombstoned).toBe(1);
-        const journal = journalAt(journalPath);
+        const journal = JSON.parse(fs.readFileSync(journalPath, "utf-8"));
         // 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();
@@ -2853,7 +2463,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 = journalAt(journalPath);
+        const journal = JSON.parse(fs.readFileSync(journalPath, "utf-8"));
         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 () => {
@@ -2945,7 +2555,7 @@ describe("sync", () => {
         expect(result.conflicts).toBeGreaterThanOrEqual(1);
         expect(result.conflictPaths).toContain("docs/edited.md");
         expect(fs.existsSync(editedPath)).toBe(true);
-        expect(fs.readFileSync(sidecarIn(path.dirname(editedPath)), "utf-8")).toBe("my local edits");
+        expect(fs.readFileSync(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 () => {
@@ -3017,7 +2627,7 @@ describe("sync", () => {
         });
         expect(fs.existsSync(deniedPath)).toBe(true);
         expect(result.filesTombstoned).toBe(0);
-        const journal = journalAt(journalPath);
+        const journal = JSON.parse(fs.readFileSync(journalPath, "utf-8"));
         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 () => {
@@ -3065,7 +2675,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 = journalAt(journalPath);
+            const journal = JSON.parse(fs.readFileSync(journalPath, "utf-8"));
             expect(journal.files["docs/locked-by-peer.md"]).toBeDefined();
             expect(journal.files["docs/locked-by-peer.md"].hash).toBe("locked-hash");
         }
@@ -3292,7 +2902,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 = journalAt(journalPath);
+            const journal = JSON.parse(fs.readFileSync(journalPath, "utf-8"));
             expect(journal.files[traversalKey]).toBeUndefined();
         }
         finally {
@@ -3326,7 +2936,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 = journalAt(journalPath);
+            const journal = JSON.parse(fs.readFileSync(journalPath, "utf-8"));
             expect(journal.files[remoteKey]).toBeUndefined();
         }
         finally {
@@ -3401,46 +3011,10 @@ describe("sync", () => {
             vaultConfig: mockConfig,
             hqRoot: tmpDir,
         });
-        const journal = journalAt(journalPath);
+        const journal = JSON.parse(fs.readFileSync(journalPath, "utf-8"));
         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) => ({
@@ -3458,7 +3032,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 = journalAt(journalPath);
+                    const checkpoint = JSON.parse(fs.readFileSync(journalPath, "utf-8"));
                     expect(Object.keys(checkpoint.files)).toHaveLength(8);
                     throw new Error("simulated crash after checkpoint");
                 }
@@ -3472,7 +3046,7 @@ describe("sync", () => {
                 onEvent: () => undefined,
             });
             expect(first.filesDownloaded).toBe(8);
-            const checkpoint = journalAt(journalPath);
+            const checkpoint = JSON.parse(fs.readFileSync(journalPath, "utf-8"));
             expect(Object.keys(checkpoint.files)).toHaveLength(8);
             vi.mocked(s3Module.downloadFile).mockImplementation(defaultDownload);
             vi.mocked(s3Module.downloadFile).mockClear();
@@ -3923,7 +3497,7 @@ describe("sync", () => {
         // skip-unchanged works on the next tick.
         const journalMod = await import("../journal.js");
         const expectedHash = journalMod.hashSymlinkTarget(linkTarget);
-        const journal = journalAt(journalPath);
+        const journal = JSON.parse(fs.readFileSync(journalPath, "utf-8"));
         expect(journal.files[linkKey]).toMatchObject({
             hash: expectedHash,
             size: 0,
@@ -4255,7 +3829,7 @@ describe("sync", () => {
         expect(errOutput).toContain("manual");
         expect(errOutput).not.toContain("directory-overlay marker");
     });
-    it("shared-mode leg withholds out-of-scope keys at LIST time (scoped listing supersedes the feedback_d2082110 gap advisory)", async () => {
+    it("shared-mode leg surfaces the materialization gap and names the shared→all lever (feedback_d2082110)", 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
@@ -4288,19 +3862,16 @@ 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(0);
+        expect(result.filesOutOfScope).toBe(1);
         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).toBeUndefined();
+        expect(gap).toBeDefined();
+        expect(gap.count).toBe(1);
+        expect(gap.syncMode).toBe("shared");
+        expect(gap.samplePaths).toEqual(["projects/secret.md"]);
     });
     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
@@ -4573,7 +4144,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 = journalAt(journalPath);
+        const journal = JSON.parse(fs.readFileSync(journalPath, "utf-8"));
         const entry = journal.files[linkKey];
         expect(entry.hash).toBe(expectedNewHash);
         expect(entry.size).toBe(0);
@@ -4872,7 +4443,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 = journalAt(journalPath);
+        const journal = JSON.parse(fs.readFileSync(journalPath, "utf-8"));
         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.
@@ -5000,7 +4571,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 = journalAt(journalPath);
+        const journalAfter = JSON.parse(fs.readFileSync(journalPath, "utf-8"));
         expect(Object.keys(journalAfter.files)).not.toContain(junkKey);
     });
     it("still pulls a junk-spelling key that is ALREADY journaled under that exact spelling", async () => {
@@ -5045,7 +4616,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 = journalAt(journalPath);
+        const journalAfter = JSON.parse(fs.readFileSync(journalPath, "utf-8"));
         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 () => {
@@ -5062,7 +4633,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 = journalAt(journalPath);
+        const journalAfter = JSON.parse(fs.readFileSync(journalPath, "utf-8"));
         expect(Object.keys(journalAfter.files)).toContain(canonicalKey);
     });
     it("does not tombstone a journaled canonical key when the LIST holds only its junk twin", async () => {
@@ -5078,7 +4649,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 = journalAt(journalPath);
+        const journalAfter = JSON.parse(fs.readFileSync(journalPath, "utf-8"));
         expect(Object.keys(journalAfter.files)).toContain(canonicalKey);
         expect(result.filesTombstoned ?? 0).toBe(0);
         expect(events.filter((e) => e.type === "error")).toHaveLength(0);