@indigoai-us/hq-cloud 6.15.20 → 6.15.22

package/dist/cli/share.test.js

@@ -55,7 +55,39 @@ import * as readline from "readline";
 import { share, isForbiddenCompanyVaultKey, UnreachablePushPathsError, currentUploadBytes, _testing as shareTesting } from "./share.js";
 import { deleteRemoteFile, downloadFile, headRemoteFile, uploadFile, uploadSymlink, WindowsSymlinkPrivilegeError } from "../s3.js";
 import { VaultAuthError } from "../vault-client.js";
-import { hashFile } from "../journal.js";
+import { hashFile, readJournal, writeJournal } 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.
+ */
+/**
+ * Seed a journal the way production does.
+ *
+ * These fixtures used to write `sync-journal.<slug>.json` by hand, which worked
+ * only while that file WAS the journal. It is a locator now, so a hand-written
+ * copy is simply ignored and the test silently runs against an empty journal.
+ * Going through `writeJournal` puts the state where the engine actually reads
+ * it, and migrates v1 fixtures on the way in exactly as a real upgrade would.
+ */
+function seedJournalAt(journalPath, journal) {
+    const slug = path
+        .basename(journalPath)
+        .replace(/^sync-journal\./, "")
+        .replace(/\.json$/, "");
+    writeJournal(slug, journal);
+}
+function journalAt(journalPath) {
+    const slug = path
+        .basename(journalPath)
+        .replace(/^sync-journal\./, "")
+        .replace(/\.json$/, "");
+    return readJournal(slug);
+}
 const mockConfig = {
     apiUrl: "https://vault-api.test",
     authToken: "test-jwt-token",
@@ -528,7 +560,7 @@ describe("share", () => {
         const { hashFile } = await import("../journal.js");
         const hash = hashFile(testFile);
         const journalPath = path.join(stateDir, "sync-journal.acme.json");
-        fs.writeFileSync(journalPath, JSON.stringify({
+        seedJournalAt(journalPath, ({
             version: "1",
             lastSync: new Date().toISOString(),
             files: {
@@ -559,7 +591,7 @@ describe("share", () => {
         // Journal has a stale hash for this path — simulating "local has been
         // edited since the last push".
         const journalPath = path.join(stateDir, "sync-journal.acme.json");
-        fs.writeFileSync(journalPath, JSON.stringify({
+        seedJournalAt(journalPath, ({
             version: "1",
             lastSync: new Date().toISOString(),
             files: {
@@ -581,6 +613,226 @@ describe("share", () => {
         expect(result.filesUploaded).toBe(1);
         expect(uploadFile).toHaveBeenCalledWith(expect.anything(), testFile, "changed.md", undefined, expect.anything());
     });
+    // ── Stat fast path for change detection ─────────────────────────────────
+    // Push used to hash EVERY regular file every pass before deciding whether to
+    // skip it — half a million reads on a real vault — because stat metadata was
+    // considered untrustworthy: a tool can rewrite a file to the same length and
+    // restore its mtime, and a size+mtime check would then skip that edit
+    // forever.
+    //
+    // These tests pin the narrower claim the fast path actually rests on: size,
+    // mtime AND ctime together. ctime is the inode-change stamp, and userspace
+    // cannot restore it — `cp -p`, `touch -r` and `rsync --times` all reset mtime
+    // while ctime moves to now. So the same-length-plus-restored-mtime rewrite
+    // that the old comment warned about is still caught, without reading a byte.
+    //
+    // Differential proof: drop ctime from the comparison and the "restored mtime"
+    // test below fails — the edit is skipped and never uploaded.
+    describe("stat fast path for change detection", () => {
+        const CONTENT_A = "aaaaaaaaaa"; // 10 bytes
+        const CONTENT_B = "bbbbbbbbbb"; // 10 bytes — same length, different bytes
+        /** Write `body` at `key` under the acme company root; return its path. */
+        function writeFile(key, body) {
+            const companyRoot = path.join(tmpDir, "companies", "acme");
+            fs.mkdirSync(companyRoot, { recursive: true });
+            const abs = path.join(companyRoot, key);
+            fs.writeFileSync(abs, body);
+            return abs;
+        }
+        function seed(key, entry) {
+            seedJournalAt(path.join(stateDir, "sync-journal.acme.json"), {
+                version: "2",
+                lastSync: new Date().toISOString(),
+                files: { [key]: { syncedAt: new Date().toISOString(), direction: "up", ...entry } },
+                pulls: [],
+            });
+        }
+        function push(abs, onConflict) {
+            return share({
+                paths: [abs],
+                company: "acme",
+                vaultConfig: mockConfig,
+                hqRoot: tmpDir,
+                skipUnchanged: true,
+                ...(onConflict ? { onConflict } : {}),
+            });
+        }
+        it("skips a file whose size, mtime and ctime all match — without reading it", async () => {
+            const abs = writeFile("untouched.md", CONTENT_A);
+            const stat = fs.lstatSync(abs);
+            // The recorded hash is deliberately WRONG. Hashing the file would find a
+            // mismatch and upload, so a skip here can only mean the bytes were never
+            // read — which is the whole point of the fast path.
+            seed("untouched.md", {
+                hash: "deliberately-not-the-hash-of-this-file",
+                size: stat.size,
+                mtimeMs: stat.mtimeMs,
+                ctimeMs: stat.ctimeMs,
+            });
+            const result = await push(abs);
+            expect(result.filesSkipped).toBe(1);
+            expect(result.filesUploaded).toBe(0);
+            expect(uploadFile).not.toHaveBeenCalled();
+        });
+        it("re-reads when the size differs", async () => {
+            const abs = writeFile("resized.md", CONTENT_A + "extra");
+            const stat = fs.lstatSync(abs);
+            seed("resized.md", {
+                hash: hashFile(abs) + "-stale",
+                size: CONTENT_A.length, // shorter than what is on disk now
+                mtimeMs: stat.mtimeMs,
+                ctimeMs: stat.ctimeMs,
+            });
+            const result = await push(abs);
+            expect(result.filesUploaded).toBe(1);
+            expect(uploadFile).toHaveBeenCalled();
+        });
+        it("re-reads when the mtime differs", async () => {
+            const abs = writeFile("retimed.md", CONTENT_B);
+            const stat = fs.lstatSync(abs);
+            seed("retimed.md", {
+                hash: "hash-of-the-previous-body",
+                size: stat.size, // same length
+                mtimeMs: stat.mtimeMs - 60_000, // journal remembers an older edit time
+                ctimeMs: stat.ctimeMs,
+            });
+            const result = await push(abs);
+            expect(result.filesUploaded).toBe(1);
+            expect(uploadFile).toHaveBeenCalled();
+        });
+        it("re-reads a same-length rewrite whose mtime was restored — ctime still moves", async () => {
+            // The exact case the old hash-everything comment existed to defend
+            // against, as produced by `cp -p`, `touch -r` or `rsync --times`.
+            const abs = writeFile("mtime-restored.md", CONTENT_A);
+            const before = fs.lstatSync(abs);
+            await new Promise((resolve) => setTimeout(resolve, 5));
+            fs.writeFileSync(abs, CONTENT_B); // same length, different bytes
+            fs.utimesSync(abs, before.atime, before.mtime); // put the old mtime back
+            const after = fs.lstatSync(abs);
+            // Preconditions. The disguise worked on size, and as closely on mtime as
+            // the OS allows — `utimes` takes whole milliseconds, so a restored stamp
+            // lands within 1ms of the original rather than exactly on it. It failed
+            // on ctime, which is the only signal left.
+            expect(after.size).toBe(before.size);
+            expect(Math.abs(after.mtimeMs - before.mtimeMs)).toBeLessThan(1);
+            expect(after.ctimeMs).not.toBe(before.ctimeMs);
+            // Seed the mtime that is actually on disk, so mtime matches EXACTLY and
+            // cannot be what triggers the re-read. Only the stale ctime can.
+            seed("mtime-restored.md", {
+                hash: "hash-of-content-a",
+                size: before.size,
+                mtimeMs: after.mtimeMs,
+                ctimeMs: before.ctimeMs,
+            });
+            const result = await push(abs);
+            expect(result.filesUploaded).toBe(1);
+            expect(uploadFile).toHaveBeenCalled();
+        });
+        it("falls back to reading when the journal predates stat tracking, then stamps it", async () => {
+            // Entries written before ctime was recorded carry no stat metadata. They
+            // must not be skipped on faith; they are read once and stamped so the
+            // next pass takes the fast path.
+            const abs = writeFile("legacy.md", CONTENT_A);
+            seed("legacy.md", { hash: hashFile(abs), size: CONTENT_A.length });
+            const result = await push(abs);
+            expect(result.filesSkipped).toBe(1);
+            expect(uploadFile).not.toHaveBeenCalled();
+            const entry = journalAt(path.join(stateDir, "sync-journal.acme.json")).files["legacy.md"];
+            const stat = fs.lstatSync(abs);
+            expect(entry.mtimeMs).toBe(stat.mtimeMs);
+            expect(entry.ctimeMs).toBe(stat.ctimeMs);
+        });
+        it("never lets the fast path skip a localDiverges entry", async () => {
+            // A pull-kept divergent entry stores the LOCAL hash and local stat, so
+            // every field matches by construction. Skipping on that asserts "local
+            // matches remote", which is exactly what the flag exists to deny.
+            const abs = writeFile("divergent.md", CONTENT_A);
+            const stat = fs.lstatSync(abs);
+            seed("divergent.md", {
+                hash: hashFile(abs),
+                size: stat.size,
+                mtimeMs: stat.mtimeMs,
+                ctimeMs: stat.ctimeMs,
+                localDiverges: true,
+            });
+            // `keep` so the divergence resolves without an interactive prompt. Under
+            // `keep` the file is deliberately NOT uploaded, so the proof that the
+            // fast path did not swallow it is that it reached Stage 2 at all: a
+            // fast-path skip returns before any remote HEAD is issued.
+            await push(abs, "keep");
+            expect(headRemoteFile).toHaveBeenCalled();
+        });
+        it("stamps size, mtime and ctime on upload so the next pass can skip", async () => {
+            const abs = writeFile("fresh.md", CONTENT_A);
+            const result = await push(abs);
+            expect(result.filesUploaded).toBe(1);
+            const entry = journalAt(path.join(stateDir, "sync-journal.acme.json")).files["fresh.md"];
+            const stat = fs.lstatSync(abs);
+            expect(entry.size).toBe(stat.size);
+            expect(entry.mtimeMs).toBe(stat.mtimeMs);
+            expect(entry.ctimeMs).toBe(stat.ctimeMs);
+        });
+        it("does not stamp ctime when the file changes between the hash and the stamp", async () => {
+            // Codex P1. Stage 1 hashes the file; the stamp happens later, after the
+            // upload. If the bytes change in between, pairing the OLD hash with the
+            // NEW timestamps would make every later pass skip the new body on stat
+            // alone — the edit would never upload. Withholding ctime forces the next
+            // pass to hash, which is the pre-fast-path behaviour.
+            const abs = writeFile("edited-mid-flight.md", CONTENT_A);
+            // Land the edit inside the exact window: Stage 1 has hashed the file, and
+            // the asynchronous remote probe runs before the stamp is taken.
+            let mutated = false;
+            vi.mocked(headRemoteFile).mockImplementation(async () => {
+                if (!mutated) {
+                    mutated = true;
+                    fs.writeFileSync(abs, CONTENT_B); // same length, different bytes
+                }
+                return null;
+            });
+            await push(abs);
+            const entry = journalAt(path.join(stateDir, "sync-journal.acme.json")).files["edited-mid-flight.md"];
+            expect(entry.ctimeMs).toBeUndefined();
+            // Proof it is not stranded: the next pass reads it and ships the new body.
+            vi.mocked(uploadFile).mockClear();
+            const second = await push(abs);
+            expect(second.filesUploaded).toBe(1);
+            expect(uploadFile).toHaveBeenCalled();
+        });
+        it("distrusts whole-second timestamps as a coarse-filesystem signal", () => {
+            // Codex P2. FAT/exFAT, some FUSE mounts and cached network filesystems
+            // report timestamps rounded to whole seconds, so a same-size rewrite
+            // inside one tick can leave both mtime and ctime equal to the journal's
+            // and be skipped indefinitely. Every filesystem HQ can trust here (APFS,
+            // ext4, NTFS) records sub-second precision, so a pair that is exactly on
+            // the second is treated as untrustworthy and sent back to hashing.
+            const abs = writeFile("coarse.md", CONTENT_A);
+            const coarse = { size: CONTENT_A.length, mtimeMs: 1_700_000_000_000, ctimeMs: 1_700_000_000_000 };
+            const spy = vi.spyOn(fs, "lstatSync").mockReturnValue({
+                isFile: () => true,
+                ...coarse,
+            });
+            try {
+                expect(shareTesting.statMatchesJournal(abs, {
+                    hash: "h",
+                    direction: "up",
+                    syncedAt: new Date().toISOString(),
+                    ...coarse,
+                })).toBe(false);
+                // Same values, one of them sub-second: a real filesystem, so trusted.
+                const fine = { ...coarse, ctimeMs: coarse.ctimeMs + 0.5 };
+                spy.mockReturnValue({ isFile: () => true, ...fine });
+                expect(shareTesting.statMatchesJournal(abs, {
+                    hash: "h",
+                    direction: "up",
+                    syncedAt: new Date().toISOString(),
+                    ...fine,
+                })).toBe(true);
+            }
+            finally {
+                spy.mockRestore();
+            }
+        });
+    });
     // ── Push-side FILE_TOMBSTONE consult (delete-resync, 3B) ────────────────────
     // An authoritative delete (`hq files delete`) writes a FILE_TOMBSTONE and
     // removes the S3 object. Without a push-side consult, a behind peer that still
@@ -593,7 +845,7 @@ describe("share", () => {
     // share.ts makes the first test fail (uploadFile IS called → resurrection).
     describe("push-side tombstone consult", () => {
         function seedJournal(key, hash, size) {
-            fs.writeFileSync(path.join(stateDir, "sync-journal.acme.json"), JSON.stringify({
+            seedJournalAt(path.join(stateDir, "sync-journal.acme.json"), ({
                 version: "1",
                 lastSync: new Date().toISOString(),
                 files: {
@@ -737,7 +989,7 @@ describe("share", () => {
             size: 99,
         });
         const journalPath = path.join(stateDir, "sync-journal.acme.json");
-        fs.writeFileSync(journalPath, JSON.stringify({
+        seedJournalAt(journalPath, ({
             version: "1",
             lastSync: new Date().toISOString(),
             files: {
@@ -789,7 +1041,7 @@ describe("share", () => {
         // assert it is never consulted below — the skip is cheap, and a leftover
         // mockResolvedValueOnce would otherwise leak into a later test's HEAD queue.
         const journalPath = path.join(stateDir, "sync-journal.acme.json");
-        fs.writeFileSync(journalPath, JSON.stringify({
+        seedJournalAt(journalPath, ({
             version: "1",
             lastSync: new Date().toISOString(),
             files: {
@@ -969,7 +1221,7 @@ describe("share", () => {
             direction: "push",
         });
         expect(fs.readdirSync(companyRoot).filter((name) => name.includes(".conflict-"))).toEqual([]);
-        const journal = JSON.parse(fs.readFileSync(path.join(stateDir, "sync-journal.acme.json"), "utf-8"));
+        const journal = readJournal("acme");
         expect(journal.files["kms-scaffold.md"]).toMatchObject({
             direction: "up",
             remoteEtag: "288bfa91684ae21f9ae27c061254d412",
@@ -1085,7 +1337,7 @@ describe("share", () => {
                 size: 5,
             });
             const journalPath = path.join(stateDir, "sync-journal.acme.json");
-            fs.writeFileSync(journalPath, JSON.stringify({
+            seedJournalAt(journalPath, ({
                 version: "1",
                 lastSync: syncedAt,
                 files: {
@@ -1158,7 +1410,7 @@ describe("share", () => {
             // No journal stamp for the failed PUT — next pass re-evaluates fresh.
             const journalPath = path.join(stateDir, "sync-journal.acme.json");
             if (fs.existsSync(journalPath)) {
-                const journal = JSON.parse(fs.readFileSync(journalPath, "utf-8"));
+                const journal = journalAt(journalPath);
                 expect(journal.files?.["raced.md"]).toBeUndefined();
             }
         });
@@ -1240,7 +1492,7 @@ describe("share", () => {
                 return { etag: '"should-not-land"' };
             });
             const journalPath = path.join(stateDir, "sync-journal.acme.json");
-            fs.writeFileSync(journalPath, JSON.stringify({
+            seedJournalAt(journalPath, ({
                 version: "1",
                 lastSync: new Date(Date.now() - 60_000).toISOString(),
                 files: {
@@ -1300,7 +1552,7 @@ describe("share", () => {
             });
             vi.mocked(uploadFile).mockResolvedValueOnce({ etag: '"new-upload-etag"' });
             const journalPath = path.join(stateDir, "sync-journal.acme.json");
-            fs.writeFileSync(journalPath, JSON.stringify({
+            seedJournalAt(journalPath, ({
                 version: "1",
                 lastSync: new Date(Date.now() - 60_000).toISOString(),
                 files: {
@@ -1335,7 +1587,7 @@ describe("share", () => {
                 size: 20,
             });
             const journalPath = path.join(stateDir, "sync-journal.acme.json");
-            fs.writeFileSync(journalPath, JSON.stringify({
+            seedJournalAt(journalPath, ({
                 version: "1",
                 lastSync: new Date().toISOString(),
                 files: {
@@ -1377,7 +1629,7 @@ describe("share", () => {
                 size: 40,
             });
             const journalPath = path.join(stateDir, "sync-journal.acme.json");
-            fs.writeFileSync(journalPath, JSON.stringify({
+            seedJournalAt(journalPath, ({
                 version: "1",
                 lastSync: new Date().toISOString(),
                 files: {
@@ -1423,7 +1675,7 @@ describe("share", () => {
             });
             vi.mocked(uploadFile).mockResolvedValueOnce({ etag: '"forced-etag"' });
             const journalPath = path.join(stateDir, "sync-journal.acme.json");
-            fs.writeFileSync(journalPath, JSON.stringify({
+            seedJournalAt(journalPath, ({
                 version: "1",
                 lastSync: new Date().toISOString(),
                 files: {
@@ -1506,7 +1758,7 @@ describe("share", () => {
             expect(vi.mocked(uploadFile).mock.calls[0][4]).toEqual({ ifMatch: REMOTE });
             // The entry is rewritten as an ordinary upload: local is now authority,
             // so the journal-honesty flag must be gone rather than re-armed.
-            const journal = JSON.parse(fs.readFileSync(journalPath, "utf-8"));
+            const journal = journalAt(journalPath);
             expect(journal.files["publish-divergent.md"].direction).toBe("up");
             expect(journal.files["publish-divergent.md"].localDiverges).toBeFalsy();
             expect(journal.files["publish-divergent.md"].remoteEtag).toBe("published-etag");
@@ -1559,7 +1811,7 @@ describe("share", () => {
             expect(result.conflictPaths).toContain("publish-raced.md");
             // Consent was for a remote that no longer exists, so the flag stays put
             // and the operator is asked again rather than silently overruled.
-            const journal = JSON.parse(fs.readFileSync(journalPath, "utf-8"));
+            const journal = journalAt(journalPath);
             expect(journal.files["publish-raced.md"].localDiverges).toBe(true);
             expect(fs.readFileSync(testFile, "utf-8")).toBe(localBytes);
         });
@@ -1614,7 +1866,7 @@ describe("share", () => {
             });
             expect(result.filesUploaded).toBe(1);
             expect(vi.mocked(uploadFile).mock.calls[0][4]).toEqual({ ifMatch: REMOTE });
-            const journal = JSON.parse(fs.readFileSync(journalPath, "utf-8"));
+            const journal = journalAt(journalPath);
             expect(journal.files["stuck-under-skip-unchanged.md"].direction).toBe("up");
             expect(journal.files["stuck-under-skip-unchanged.md"].localDiverges).toBeFalsy();
         });
@@ -1704,7 +1956,7 @@ describe("share", () => {
             expect(uploadFile).not.toHaveBeenCalled();
             expect(result.filesUploaded).toBe(0);
             expect(result.conflictPaths).toContain("peer-deleted.md");
-            const journal = JSON.parse(fs.readFileSync(journalPath, "utf-8"));
+            const journal = journalAt(journalPath);
             expect(journal.files["peer-deleted.md"].localDiverges).toBe(true);
             expect(fs.readFileSync(testFile, "utf-8")).toBe(localBytes);
         });
@@ -1765,7 +2017,7 @@ describe("share", () => {
             vi.mocked(headRemoteFile).mockResolvedValueOnce(null);
             vi.mocked(uploadFile).mockResolvedValueOnce({ etag: '"recreated-etag"' });
             const journalPath = path.join(stateDir, "sync-journal.acme.json");
-            fs.writeFileSync(journalPath, JSON.stringify({
+            seedJournalAt(journalPath, ({
                 version: "1",
                 lastSync: new Date(Date.now() - 60_000).toISOString(),
                 files: {
@@ -1795,7 +2047,7 @@ describe("share", () => {
             const pc = vi.mocked(uploadFile).mock.calls[0][4];
             expect(pc?.ifMatch).toBeUndefined();
             expect(pc?.ifNoneMatch).toBe("*");
-            const journal = JSON.parse(fs.readFileSync(journalPath, "utf-8"));
+            const journal = journalAt(journalPath);
             expect(journal.files["recreate-deleted.md"]).toMatchObject({
                 hash: localHash,
                 remoteEtag: "recreated-etag",
@@ -1816,7 +2068,7 @@ describe("share", () => {
                 return undefined;
             });
             const journalPath = path.join(stateDir, "sync-journal.acme.json");
-            fs.writeFileSync(journalPath, JSON.stringify({
+            seedJournalAt(journalPath, ({
                 version: "1",
                 lastSync: new Date(Date.now() - 60_000).toISOString(),
                 files: {
@@ -1848,7 +2100,7 @@ describe("share", () => {
             expect(vi.mocked(uploadFile).mock.calls[0][4]).toEqual({ ifNoneMatch: "*" });
             // Journal not advanced to a successful upload etag (entry may still be
             // the prior baseline — next pass re-evaluates).
-            const journal = JSON.parse(fs.readFileSync(journalPath, "utf-8"));
+            const journal = journalAt(journalPath);
             expect(journal.files["race-recreate.md"]?.remoteEtag).toBe("etag-before-delete");
             expect(journal.files["race-recreate.md"]?.hash).toBe("old-hash");
             expect(fs.readFileSync(testFile, "utf-8")).toBe("my recreated local");
@@ -2172,7 +2424,7 @@ describe("share", () => {
             size: 5,
         });
         const journalPath = path.join(stateDir, "sync-journal.acme.json");
-        fs.writeFileSync(journalPath, JSON.stringify({
+        seedJournalAt(journalPath, ({
             version: "1",
             lastSync: syncedAt,
             files: {
@@ -2212,7 +2464,7 @@ describe("share", () => {
             size: 5,
         });
         const journalPath = path.join(stateDir, "sync-journal.acme.json");
-        fs.writeFileSync(journalPath, JSON.stringify({
+        seedJournalAt(journalPath, ({
             version: "1",
             lastSync: syncedAt,
             files: {
@@ -2248,7 +2500,7 @@ describe("share", () => {
             hqRoot: tmpDir,
         });
         const journalPath = path.join(stateDir, "sync-journal.acme.json");
-        const journal = JSON.parse(fs.readFileSync(journalPath, "utf-8"));
+        const journal = journalAt(journalPath);
         expect(journal.files["fresh.md"].remoteEtag).toBe("new-upload-etag");
     });
     it("forwards UploadAuthor to uploadFile when present (created-by metadata)", async () => {
@@ -2293,7 +2545,7 @@ describe("share", () => {
         const { hashFile } = await import("../journal.js");
         const hash = hashFile(testFile);
         const journalPath = path.join(stateDir, "sync-journal.acme.json");
-        fs.writeFileSync(journalPath, JSON.stringify({
+        seedJournalAt(journalPath, ({
             version: "1",
             lastSync: new Date().toISOString(),
             files: {
@@ -2513,7 +2765,7 @@ describe("share", () => {
             .update("stable content")
             .digest("hex");
         const journalPath = path.join(stateDir, "sync-journal.acme.json");
-        fs.writeFileSync(journalPath, JSON.stringify({
+        seedJournalAt(journalPath, ({
             version: "1",
             lastSync: new Date().toISOString(),
             files: {
@@ -2574,7 +2826,7 @@ describe("share", () => {
         // not be queued for delete.
         fs.writeFileSync(path.join(tmpDir, ".hqinclude"), "companies/*/knowledge/\n");
         const journalPath = path.join(stateDir, "sync-journal.acme.json");
-        fs.writeFileSync(journalPath, JSON.stringify({
+        seedJournalAt(journalPath, ({
             version: "1",
             lastSync: new Date().toISOString(),
             files: {
@@ -2611,7 +2863,7 @@ describe("share", () => {
             operation: "delete",
         });
         expect(deleteRemoteFile).toHaveBeenCalledWith(expect.anything(), "knowledge");
-        const journal = JSON.parse(fs.readFileSync(journalPath, "utf-8"));
+        const journal = journalAt(journalPath);
         expect(journal.files["knowledge"]).toBeUndefined();
     });
     it("propagateDeletes: a dangling local symlink is NOT classified as gone (lstat, not existsSync)", async () => {
@@ -2628,7 +2880,7 @@ describe("share", () => {
         const danglingLink = path.join(companyRoot, "dangling-link.md");
         fs.symlinkSync("./missing-target.md", danglingLink);
         const journalPath = path.join(stateDir, "sync-journal.acme.json");
-        fs.writeFileSync(journalPath, JSON.stringify({
+        seedJournalAt(journalPath, ({
             version: "1",
             lastSync: new Date().toISOString(),
             files: {
@@ -2658,7 +2910,7 @@ describe("share", () => {
         expect(result.filesDeleted).toBe(0);
         expect(deleteRemoteFile).not.toHaveBeenCalled();
         // Journal entry must survive the run.
-        const journal = JSON.parse(fs.readFileSync(journalPath, "utf-8"));
+        const journal = journalAt(journalPath);
         expect(journal.files["dangling-link.md"]).toBeDefined();
     });
     it("vault-litter drain: a `.drift-*` marker with direction:'down' and NO delete intent tombstones " +
@@ -2723,7 +2975,7 @@ describe("share", () => {
             });
             expect(result.filesDeleted).toBe(1);
             expect(deleteRemoteFile).toHaveBeenCalledWith(expect.anything(), "personal/scripts/run-project.sh.drift-1779863862-42519");
-            const journal = JSON.parse(fs.readFileSync(journalPath, "utf-8"));
+            const journal = journalAt(journalPath);
             expect(journal.files["personal/scripts/run-project.sh.drift-1779863862-42519"]).toBeUndefined();
         }
         finally {
@@ -2796,7 +3048,7 @@ describe("share", () => {
         fs.mkdirSync(companyRoot, { recursive: true });
         // No file on disk under companies/acme/peer-uploaded.md → local missing.
         const journalPath = path.join(stateDir, "sync-journal.acme.json");
-        fs.writeFileSync(journalPath, JSON.stringify({
+        seedJournalAt(journalPath, ({
             version: "1",
             lastSync: new Date().toISOString(),
             files: {
@@ -2821,7 +3073,7 @@ describe("share", () => {
         });
         expect(result.filesDeleted).toBe(0);
         expect(deleteRemoteFile).not.toHaveBeenCalled();
-        const journal = JSON.parse(fs.readFileSync(journalPath, "utf-8"));
+        const journal = journalAt(journalPath);
         expect(journal.files["peer-uploaded.md"]).toBeDefined();
     });
     it("ROLLBACK KNOB: owned-only is honored on a prs_ personal vault — an intent-less entry with a " +
@@ -2912,7 +3164,7 @@ describe("share", () => {
             ]);
             // Journal entry survives, so a later run (or a watcher-minted intent)
             // can still authorize the delete properly.
-            const journal = JSON.parse(fs.readFileSync(journalPath, "utf-8"));
+            const journal = journalAt(journalPath);
             expect(journal.files["personal/knowledge/gone.md"]).toBeDefined();
         }
         finally {
@@ -2929,7 +3181,7 @@ describe("share", () => {
         // deleted by the user.
         fs.writeFileSync(path.join(companyRoot, "kept.md"), "still here");
         const journalPath = path.join(stateDir, "sync-journal.acme.json");
-        fs.writeFileSync(journalPath, JSON.stringify({
+        seedJournalAt(journalPath, ({
             version: "1",
             lastSync: new Date().toISOString(),
             files: {
@@ -2965,7 +3217,7 @@ describe("share", () => {
         expect(deleteRemoteFile).toHaveBeenCalledTimes(1);
         expect(deleteRemoteFile).toHaveBeenCalledWith(expect.anything(), "gone.md");
         // Journal entry for the gone file is removed; the kept entry stays.
-        const journal = JSON.parse(fs.readFileSync(journalPath, "utf-8"));
+        const journal = journalAt(journalPath);
         expect(journal.files["gone.md"]).toBeUndefined();
         expect(journal.files["kept.md"]).toBeDefined();
     });
@@ -2973,7 +3225,7 @@ describe("share", () => {
         const companyRoot = path.join(tmpDir, "companies", "acme");
         fs.mkdirSync(companyRoot, { recursive: true });
         const journalPath = path.join(stateDir, "sync-journal.acme.json");
-        fs.writeFileSync(journalPath, JSON.stringify({
+        seedJournalAt(journalPath, ({
             version: "1",
             lastSync: new Date().toISOString(),
             files: {
@@ -3015,7 +3267,7 @@ describe("share", () => {
         const companyRoot = path.join(tmpDir, "companies", "acme");
         fs.mkdirSync(companyRoot, { recursive: true });
         const journalPath = path.join(stateDir, "sync-journal.acme.json");
-        fs.writeFileSync(journalPath, JSON.stringify({
+        seedJournalAt(journalPath, ({
             version: "1",
             lastSync: new Date().toISOString(),
             files: {
@@ -3038,7 +3290,7 @@ describe("share", () => {
         expect(result.filesDeleted).toBe(0);
         expect(deleteRemoteFile).not.toHaveBeenCalled();
         // Journal entry survives so the next opt-in run can still propagate.
-        const journal = JSON.parse(fs.readFileSync(journalPath, "utf-8"));
+        const journal = journalAt(journalPath);
         expect(journal.files["gone.md"]).toBeDefined();
     });
     it("propagateDeletes: scope is constrained to the supplied paths — sibling deletes are not swept", async () => {
@@ -3046,7 +3298,7 @@ describe("share", () => {
         fs.mkdirSync(path.join(companyRoot, "in-scope"), { recursive: true });
         fs.mkdirSync(path.join(companyRoot, "other"), { recursive: true });
         const journalPath = path.join(stateDir, "sync-journal.acme.json");
-        fs.writeFileSync(journalPath, JSON.stringify({
+        seedJournalAt(journalPath, ({
             version: "1",
             lastSync: new Date().toISOString(),
             files: {
@@ -3081,7 +3333,7 @@ describe("share", () => {
         expect(result.filesDeleted).toBe(1);
         expect(deleteRemoteFile).toHaveBeenCalledTimes(1);
         expect(deleteRemoteFile).toHaveBeenCalledWith(expect.anything(), "in-scope/gone.md");
-        const journal = JSON.parse(fs.readFileSync(journalPath, "utf-8"));
+        const journal = journalAt(journalPath);
         expect(journal.files["in-scope/gone.md"]).toBeUndefined();
         // Sibling tree's journal entry is untouched — `hq share <subtree>` must
         // not act on files outside the named scope.
@@ -3097,7 +3349,7 @@ describe("share", () => {
         fs.mkdirSync(path.join(companyRoot, "in-scope"), { recursive: true });
         fs.mkdirSync(path.join(companyRoot, "other"), { recursive: true });
         const journalPath = path.join(stateDir, "sync-journal.acme.json");
-        fs.writeFileSync(journalPath, JSON.stringify({
+        seedJournalAt(journalPath, ({
             version: "1",
             lastSync: new Date().toISOString(),
             files: {
@@ -3132,7 +3384,7 @@ describe("share", () => {
         });
         expect(result.filesDeleted).toBe(1);
         expect(deleteRemoteFile).toHaveBeenCalledWith(expect.anything(), "in-scope/gone.md");
-        const journal = JSON.parse(fs.readFileSync(journalPath, "utf-8"));
+        const journal = journalAt(journalPath);
         expect(journal.files["in-scope/gone.md"]).toBeUndefined();
         // Scope stays exactly as narrow as the absolute spelling's — no wider.
         expect(journal.files["other/also-gone.md"]).toBeDefined();
@@ -3149,7 +3401,7 @@ describe("share", () => {
         fs.mkdirSync(acmeRepo, { recursive: true });
         fs.symlinkSync(acmeRepo, path.join(companyRoot, "knowledge"));
         const journalPath = path.join(stateDir, "sync-journal.acme.json");
-        fs.writeFileSync(journalPath, JSON.stringify({
+        seedJournalAt(journalPath, ({
             version: "1",
             lastSync: new Date().toISOString(),
             files: {
@@ -3179,14 +3431,14 @@ describe("share", () => {
         });
         expect(result.filesDeleted).toBe(0);
         expect(deleteRemoteFile).not.toHaveBeenCalled();
-        const journal = JSON.parse(fs.readFileSync(journalPath, "utf-8"));
+        const journal = journalAt(journalPath);
         expect(journal.files["knowledge/agents/brief.md"]).toBeDefined();
     });
     it("propagateDeletes: a failed DeleteObject leaves the journal entry intact for retry", async () => {
         const companyRoot = path.join(tmpDir, "companies", "acme");
         fs.mkdirSync(companyRoot, { recursive: true });
         const journalPath = path.join(stateDir, "sync-journal.acme.json");
-        fs.writeFileSync(journalPath, JSON.stringify({
+        seedJournalAt(journalPath, ({
             version: "1",
             lastSync: new Date().toISOString(),
             files: {
@@ -3219,7 +3471,7 @@ describe("share", () => {
         const errorEvent = events.find((e) => e.type === "error");
         expect(errorEvent).toMatchObject({ path: "flaky.md", message: expect.stringContaining("S3 down") });
         // Entry survives — next run will retry the delete.
-        const journal = JSON.parse(fs.readFileSync(journalPath, "utf-8"));
+        const journal = journalAt(journalPath);
         expect(journal.files["flaky.md"]).toBeDefined();
     });
     // ── Delete propagation safety: direction + filter guards (Bug B + C) ──────
@@ -3253,7 +3505,7 @@ describe("share", () => {
         // and one this machine uploaded (direction:'up'). Only the 'up' one should
         // be eligible for delete-propagation.
         const journalPath = path.join(stateDir, "sync-journal.acme.json");
-        fs.writeFileSync(journalPath, JSON.stringify({
+        seedJournalAt(journalPath, ({
             version: "1",
             lastSync: new Date().toISOString(),
             files: {
@@ -3290,7 +3542,7 @@ describe("share", () => {
         const companyRoot = path.join(tmpDir, "companies", "acme");
         fs.mkdirSync(companyRoot, { recursive: true });
         const journalPath = path.join(stateDir, "sync-journal.acme.json");
-        fs.writeFileSync(journalPath, JSON.stringify({
+        seedJournalAt(journalPath, ({
             version: "1",
             lastSync: new Date().toISOString(),
             files: {
@@ -3323,7 +3575,7 @@ describe("share", () => {
         // absence is a filter outcome, not a user-intended delete.
         fs.writeFileSync(path.join(tmpDir, ".hqignore"), "companies/acme/legacy/**\n");
         const journalPath = path.join(stateDir, "sync-journal.acme.json");
-        fs.writeFileSync(journalPath, JSON.stringify({
+        seedJournalAt(journalPath, ({
             version: "1",
             lastSync: new Date().toISOString(),
             files: {
@@ -3382,7 +3634,7 @@ describe("share", () => {
         // Under owned-only this would be stuck on remote forever; currency-gated
         // checks the ETag and propagates the delete cleanly when match holds.
         const journalPath = path.join(stateDir, "sync-journal.acme.json");
-        fs.writeFileSync(journalPath, JSON.stringify({
+        seedJournalAt(journalPath, ({
             version: "1",
             lastSync: new Date().toISOString(),
             files: {
@@ -3412,7 +3664,7 @@ describe("share", () => {
         });
         expect(result.filesDeleted).toBe(1);
         expect(deleteRemoteFile).toHaveBeenCalledWith(expect.anything(), "core/policies/old.md");
-        const journal = JSON.parse(fs.readFileSync(journalPath, "utf-8"));
+        const journal = journalAt(journalPath);
         expect(journal.files["core/policies/old.md"]).toBeUndefined();
     });
     it("currency-gated: propagates the S3 delete for a local-delete tombstone (pull-leg producer hand-off)", async () => {
@@ -3423,7 +3675,7 @@ describe("share", () => {
         const companyRoot = path.join(tmpDir, "companies", "acme");
         fs.mkdirSync(companyRoot, { recursive: true });
         const journalPath = path.join(stateDir, "sync-journal.acme.json");
-        fs.writeFileSync(journalPath, JSON.stringify({
+        seedJournalAt(journalPath, ({
             version: "2",
             lastSync: new Date().toISOString(),
             files: {
@@ -3459,7 +3711,7 @@ describe("share", () => {
         });
         expect(result.filesDeleted).toBe(1);
         expect(deleteRemoteFile).toHaveBeenCalledWith(expect.anything(), "docs/deleted.md");
-        const journal = JSON.parse(fs.readFileSync(journalPath, "utf-8"));
+        const journal = journalAt(journalPath);
         expect(journal.files["docs/deleted.md"]).toBeUndefined();
     });
     it("currency-gated: refuses delete + emits stale-etag event when remote moved since last sync", async () => {
@@ -3468,7 +3720,7 @@ describe("share", () => {
         // Another device modified `shared.md` after this device's last sync.
         // The journal still records the old etag; HEAD returns the new one.
         const journalPath = path.join(stateDir, "sync-journal.acme.json");
-        fs.writeFileSync(journalPath, JSON.stringify({
+        seedJournalAt(journalPath, ({
             version: "1",
             lastSync: new Date().toISOString(),
             files: {
@@ -3500,7 +3752,7 @@ describe("share", () => {
         // No remote DELETE issued, journal entry preserved (pull will re-pull).
         expect(result.filesDeleted).toBe(0);
         expect(deleteRemoteFile).not.toHaveBeenCalled();
-        const journal = JSON.parse(fs.readFileSync(journalPath, "utf-8"));
+        const journal = journalAt(journalPath);
         expect(journal.files["shared.md"]).toBeDefined();
         // Dedicated event fired so UIs surface the refusal. `reason` field
         // discriminates "stale-etag" (real drift) from "legacy-no-etag" so
@@ -3522,7 +3774,7 @@ describe("share", () => {
         fs.mkdirSync(companyRoot, { recursive: true });
         const recreatedPath = path.join(companyRoot, "racy.md");
         const journalPath = path.join(stateDir, "sync-journal.acme.json");
-        fs.writeFileSync(journalPath, JSON.stringify({
+        seedJournalAt(journalPath, ({
             version: "2",
             lastSync: new Date().toISOString(),
             files: {
@@ -3558,7 +3810,7 @@ describe("share", () => {
         expect(result.filesDeleted).toBe(0);
         expect(deleteRemoteFile).not.toHaveBeenCalled();
         expect(fs.readFileSync(recreatedPath, "utf-8")).toBe("recreated after planning");
-        const journal = JSON.parse(fs.readFileSync(journalPath, "utf-8"));
+        const journal = journalAt(journalPath);
         expect(journal.files["racy.md"]).toBeDefined();
         expect(events).toContainEqual(expect.objectContaining({
             type: "delete-refused-stale-etag",
@@ -3580,7 +3832,7 @@ describe("share", () => {
         // genuine local==remote sync, so propagating the delete would destroy the
         // (different) remote version. Must be REFUSED, not propagated.
         const journalPath = path.join(stateDir, "sync-journal.acme.json");
-        fs.writeFileSync(journalPath, JSON.stringify({
+        seedJournalAt(journalPath, ({
             version: "2",
             lastSync: new Date().toISOString(),
             files: {
@@ -3615,7 +3867,7 @@ describe("share", () => {
         // Refusal short-circuits before the currency HEAD — no network needed.
         expect(headRemoteFile).not.toHaveBeenCalled();
         // Journal entry preserved, not silently dropped.
-        const journal = JSON.parse(fs.readFileSync(journalPath, "utf-8"));
+        const journal = journalAt(journalPath);
         expect(journal.files["core/policies/kept.md"]).toBeDefined();
         // Surfaced as a refusal with the divergent-local reason.
         const refused = events.find((e) => e.type === "delete-refused-stale-etag");
@@ -3632,7 +3884,7 @@ describe("share", () => {
         // S3 console). Local copy also missing. Currency-gated should drop the
         // journal entry without issuing a DELETE — the remote is already gone.
         const journalPath = path.join(stateDir, "sync-journal.acme.json");
-        fs.writeFileSync(journalPath, JSON.stringify({
+        seedJournalAt(journalPath, ({
             version: "1",
             lastSync: new Date().toISOString(),
             files: {
@@ -3665,7 +3917,7 @@ describe("share", () => {
         // from real deletes without re-counting events.
         expect(result.filesTombstoned).toBe(1);
         expect(result.filesRefusedStale).toBe(0);
-        const journal = JSON.parse(fs.readFileSync(journalPath, "utf-8"));
+        const journal = journalAt(journalPath);
         expect(journal.files["removed-out-of-band.md"]).toBeUndefined();
         // Synthetic progress event carries the tombstone marker. Without this,
         // the tty stream renders tombstones identically to real deletes — operator
@@ -3686,7 +3938,7 @@ describe("share", () => {
         // against. Refuse the delete in the safe direction; a future sync with
         // a recorded etag can re-evaluate.
         const journalPath = path.join(stateDir, "sync-journal.acme.json");
-        fs.writeFileSync(journalPath, JSON.stringify({
+        seedJournalAt(journalPath, ({
             version: "1",
             lastSync: new Date().toISOString(),
             files: {
@@ -3740,7 +3992,7 @@ describe("share", () => {
         const companyRoot = path.join(tmpDir, "companies", "acme");
         fs.mkdirSync(companyRoot, { recursive: true });
         const journalPath = path.join(stateDir, "sync-journal.acme.json");
-        fs.writeFileSync(journalPath, JSON.stringify({
+        seedJournalAt(journalPath, ({
             version: "1",
             lastSync: new Date().toISOString(),
             files: {
@@ -3792,7 +4044,7 @@ describe("share", () => {
         const companyRoot = path.join(tmpDir, "companies", "acme");
         fs.mkdirSync(companyRoot, { recursive: true });
         const journalPath = path.join(stateDir, "sync-journal.acme.json");
-        fs.writeFileSync(journalPath, JSON.stringify({
+        seedJournalAt(journalPath, ({
             version: "1",
             lastSync: new Date().toISOString(),
             files: {
@@ -3826,7 +4078,7 @@ describe("share", () => {
         const companyRoot = path.join(tmpDir, "companies", "acme");
         fs.mkdirSync(companyRoot, { recursive: true });
         const journalPath = path.join(stateDir, "sync-journal.acme.json");
-        fs.writeFileSync(journalPath, JSON.stringify({
+        seedJournalAt(journalPath, ({
             version: "1",
             lastSync: new Date().toISOString(),
             files: {
@@ -3876,7 +4128,7 @@ describe("share", () => {
         fs.mkdirSync(companyRoot, { recursive: true });
         const recreatedPath = path.join(companyRoot, "notes", "gone.md");
         const journalPath = path.join(stateDir, "sync-journal.acme.json");
-        fs.writeFileSync(journalPath, JSON.stringify({
+        seedJournalAt(journalPath, ({
             version: "1",
             lastSync: new Date().toISOString(),
             files: {
@@ -3924,7 +4176,7 @@ describe("share", () => {
         const companyRoot = path.join(tmpDir, "companies", "acme");
         fs.mkdirSync(companyRoot, { recursive: true });
         const journalPath = path.join(stateDir, "sync-journal.acme.json");
-        fs.writeFileSync(journalPath, JSON.stringify({
+        seedJournalAt(journalPath, ({
             version: "1",
             lastSync: new Date().toISOString(),
             files: {
@@ -3954,14 +4206,14 @@ describe("share", () => {
             type: "delete-refused-stale-etag",
             reason: "legacy-no-etag",
         }));
-        const journal = JSON.parse(fs.readFileSync(journalPath, "utf-8"));
+        const journal = journalAt(journalPath);
         expect(journal.files["notes/legacy.md"]).toBeDefined();
     });
     it("owned-only still requires an intent — it is the documented rollback knob", async () => {
         const companyRoot = path.join(tmpDir, "companies", "acme");
         fs.mkdirSync(companyRoot, { recursive: true });
         const journalPath = path.join(stateDir, "sync-journal.acme.json");
-        fs.writeFileSync(journalPath, JSON.stringify({
+        seedJournalAt(journalPath, ({
             version: "1",
             lastSync: new Date().toISOString(),
             files: {
@@ -4148,7 +4400,7 @@ describe("share", () => {
         const companyRoot = path.join(tmpDir, "companies", "acme");
         fs.mkdirSync(companyRoot, { recursive: true });
         const journalPath = path.join(stateDir, "sync-journal.acme.json");
-        fs.writeFileSync(journalPath, JSON.stringify({
+        seedJournalAt(journalPath, ({
             version: "1",
             lastSync: new Date().toISOString(),
             files: {
@@ -4189,7 +4441,7 @@ describe("share", () => {
         expect(deleteRemoteFile).toHaveBeenCalledWith(expect.anything(), "regular.md");
         expect(deleteRemoteFile).toHaveBeenCalledWith(expect.anything(), "CLAUDE.md.conflict-2026-05-13T19-40-40Z-e5797a.md");
         // Both journal entries are removed by the delete loop's removeEntry call.
-        const journal = JSON.parse(fs.readFileSync(journalPath, "utf-8"));
+        const journal = journalAt(journalPath);
         expect(journal.files["CLAUDE.md.conflict-2026-05-13T19-40-40Z-e5797a.md"]).toBeUndefined();
         expect(journal.files["regular.md"]).toBeUndefined();
     });
@@ -4204,7 +4456,7 @@ describe("share", () => {
         process.env.HQ_STATE_DIR = stateDirPersonal;
         try {
             const journalPath = path.join(stateDirPersonal, "sync-journal.__hq_personal_vault__.json");
-            fs.writeFileSync(journalPath, JSON.stringify({
+            seedJournalAt(journalPath, ({
                 version: "1",
                 lastSync: new Date().toISOString(),
                 files: {
@@ -4230,7 +4482,7 @@ describe("share", () => {
             });
             expect(result.filesDeleted).toBe(1);
             expect(deleteRemoteFile).toHaveBeenCalledWith(expect.anything(), "personal/.obsidian/graph.json.drift-1779863862-42519");
-            const journal = JSON.parse(fs.readFileSync(journalPath, "utf-8"));
+            const journal = journalAt(journalPath);
             expect(journal.files["personal/.obsidian/graph.json.drift-1779863862-42519"]).toBeUndefined();
         }
         finally {
@@ -4253,7 +4505,7 @@ describe("share", () => {
                 hash: "h", size: 1, syncedAt: new Date().toISOString(),
                 direction: "up",
             });
-            fs.writeFileSync(journalPath, JSON.stringify({
+            seedJournalAt(journalPath, ({
                 version: "1",
                 lastSync: new Date().toISOString(),
                 files: {
@@ -4301,7 +4553,7 @@ describe("share", () => {
             expect(pruned[0].byReason["ignore-filtered"]).toBe(3);
             expect(pruned[0].byReason["excluded-top-level"]).toBe(1);
             // The persisted journal converged: excluded rows gone, legit row kept.
-            const journal = JSON.parse(fs.readFileSync(journalPath, "utf-8"));
+            const journal = journalAt(journalPath);
             expect(Object.keys(journal.files)).toContain("personal/keep.md");
             expect(journal.files[".claude/worktrees/wt/a.ts"]).toBeUndefined();
             expect(journal.files["personal/node_modules/pkg/index.js"]).toBeUndefined();
@@ -4333,7 +4585,7 @@ describe("share", () => {
         const key = "deleted-top-level.md";
         const journalSlug = "personal-scoped-delete";
         const journalPath = path.join(stateDir, `sync-journal.${journalSlug}.json`);
-        fs.writeFileSync(journalPath, JSON.stringify({
+        seedJournalAt(journalPath, ({
             version: "2",
             lastSync: new Date().toISOString(),
             pulls: [],
@@ -4365,7 +4617,7 @@ describe("share", () => {
         });
         expect(result.filesDeleted).toBe(1);
         expect(deleteRemoteFile).toHaveBeenCalledWith(expect.anything(), key);
-        expect(JSON.parse(fs.readFileSync(journalPath, "utf8")).files[key]).toBeUndefined();
+        expect(journalAt(journalPath).files[key]).toBeUndefined();
     });
     // ── Decommission prefixes ──────────────────────────────────────────────────
     //
@@ -4420,7 +4672,7 @@ describe("share", () => {
         // Local file remains on disk — decommission is a remote-only sweep.
         expect(fs.existsSync(path.join(tmpDir, "companies", "foo", "notes.md"))).toBe(true);
         // Journal entry pruned in lockstep with the remote delete.
-        const journalAfter = JSON.parse(fs.readFileSync(personalJournalPath, "utf-8"));
+        const journalAfter = journalAt(personalJournalPath);
         expect(journalAfter.files["companies/foo/notes.md"]).toBeUndefined();
         expect(journalAfter.files["knowledge/x.md"]).toBeDefined();
     });
@@ -4456,7 +4708,7 @@ describe("share", () => {
         expect(deleteRemoteFile).not.toHaveBeenCalled();
         // Journal entry preserved — the pulled-from-peer record stays so a
         // future pull can still reconcile it correctly.
-        const journalAfter = JSON.parse(fs.readFileSync(personalJournalPath, "utf-8"));
+        const journalAfter = journalAt(personalJournalPath);
         expect(journalAfter.files["companies/foo/from-peer.md"]).toBeDefined();
     });
     it("decommissionPrefixes: dedupes with propagateDeletes plan — a key in both still emits one DeleteObject", async () => {
@@ -4576,7 +4828,7 @@ describe("share", () => {
         expect(result.filesTombstoned).toBe(1);
         expect(result.filesDeleted).toBe(0);
         // Journal entry is gone.
-        const journalAfter = JSON.parse(fs.readFileSync(personalJournalPath, "utf-8"));
+        const journalAfter = journalAt(personalJournalPath);
         expect(journalAfter.files["companies/foo/gone.md"]).toBeUndefined();
     });
     describe("personalMode", () => {
@@ -4617,7 +4869,7 @@ describe("share", () => {
             const acmeJournalPath = path.join(stateDir, "sync-journal.acme.json");
             expect(fs.existsSync(personalJournalPath)).toBe(true);
             expect(fs.existsSync(acmeJournalPath)).toBe(false);
-            const journal = JSON.parse(fs.readFileSync(personalJournalPath, "utf-8"));
+            const journal = journalAt(personalJournalPath);
             expect(journal.files["knowledge/notes.md"]).toBeDefined();
         });
         it("personalMode=true accepts files outside companies/<slug>/ (companion to the company-folder rejection)", async () => {
@@ -4905,7 +5157,7 @@ describe("share", () => {
                 .createHash("sha256")
                 .update(target)
                 .digest("hex");
-            fs.writeFileSync(journalPath, JSON.stringify({
+            seedJournalAt(journalPath, ({
                 version: "1",
                 lastSync: new Date().toISOString(),
                 files: {
@@ -5308,7 +5560,7 @@ describe("share", () => {
             });
             expect(pushed.filesUploaded).toBe(1);
             const journalPath = path.join(stateDir, "sync-journal.acme.json");
-            const afterPush = JSON.parse(fs.readFileSync(journalPath, "utf-8"));
+            const afterPush = journalAt(journalPath);
             expect(Object.keys(afterPush.files)).toContain("knowledge/agents/brief.md");
             vi.mocked(deleteRemoteFile).mockClear();
             const walked = await share({
@@ -5322,7 +5574,7 @@ describe("share", () => {
             expect(walked.filesDeleted).toBe(0);
             const deletedKeys = vi.mocked(deleteRemoteFile).mock.calls.map((c) => c[1]);
             expect(deletedKeys).not.toContain("knowledge/agents/brief.md");
-            const afterWalk = JSON.parse(fs.readFileSync(journalPath, "utf-8"));
+            const afterWalk = journalAt(journalPath);
             expect(Object.keys(afterWalk.files)).toContain("knowledge/agents/brief.md");
         });
     });
@@ -5366,7 +5618,7 @@ describe("share", () => {
                 }
             }
             const journalPath = path.join(stateDir, "sync-journal.acme.json");
-            fs.writeFileSync(journalPath, JSON.stringify({
+            seedJournalAt(journalPath, ({
                 version: "1",
                 lastSync: new Date().toISOString(),
                 files,
@@ -5424,7 +5676,7 @@ describe("share", () => {
             expect(summary.samplePaths.length).toBeGreaterThan(0);
             expect(summary.samplePaths.length).toBeLessThanOrEqual(10);
             // Journal entries for the missing files SURVIVE — guard never mutates.
-            const journal = JSON.parse(fs.readFileSync(journalPath, "utf-8"));
+            const journal = journalAt(journalPath);
             expect(Object.keys(journal.files).length).toBe(100);
             // Per-key delete-refused-stale-etag events for each candidate.
             const perKeyRefusals = events.filter((e) => e.type === "delete-refused-stale-etag" && e.reason === "bulk-asymmetry");
@@ -5474,7 +5726,7 @@ describe("share", () => {
                 expect(headedKeys).not.toContain(`f-${i.toString().padStart(4, "0")}.md`);
             }
             // Journal untouched — the entries stay recoverable.
-            const journal = JSON.parse(fs.readFileSync(journalPath, "utf-8"));
+            const journal = journalAt(journalPath);
             expect(Object.keys(journal.files).length).toBe(100);
         });
         // The core of the #227 regression, isolated: pre-#227 a trip emptied
@@ -5505,7 +5757,7 @@ describe("share", () => {
             const perKeyRefusals = events.filter((e) => e.type === "delete-refused-stale-etag" &&
                 e.reason === "bulk-asymmetry");
             expect(perKeyRefusals.length).toBe(11);
-            const journal = JSON.parse(fs.readFileSync(journalPath, "utf-8"));
+            const journal = journalAt(journalPath);
             expect(Object.keys(journal.files).length).toBe(100);
         });
         it("vault litter still drains when the breaker trips", async () => {
@@ -5519,7 +5771,7 @@ describe("share", () => {
                 withIntents: false,
             });
             const litterKey = "CLAUDE.md.conflict-2026-05-13T19-40-40Z-e5797a.md";
-            const seeded = JSON.parse(fs.readFileSync(journalPath, "utf-8"));
+            const seeded = journalAt(journalPath);
             seeded.files[litterKey] = {
                 hash: "h",
                 size: 5,
@@ -5528,7 +5780,7 @@ describe("share", () => {
                 remoteEtag: "litter-etag",
                 kind: "file",
             };
-            fs.writeFileSync(journalPath, JSON.stringify(seeded));
+            seedJournalAt(journalPath, seeded);
             vi.mocked(headRemoteFile).mockImplementation(async (_ctx, key) => ({
                 etag: `etag-${parseInt(key.replace(/[^0-9]/g, ""), 10)}`,
                 lastModified: new Date(),
@@ -5668,7 +5920,7 @@ describe("share", () => {
             expect(summary).toBeDefined();
             expect(summary.ratio).toBeCloseTo(1.0, 5);
             // Journal untouched.
-            const journal = JSON.parse(fs.readFileSync(journalPath, "utf-8"));
+            const journal = journalAt(journalPath);
             expect(Object.keys(journal.files).length).toBe(50);
         });
         it("small absolute count (9/9 = 100% ratio but < MIN_ABS=10) does NOT trip: all 9 delete normally", async () => {
@@ -5712,7 +5964,7 @@ describe("share", () => {
             expect(deleteRemoteFile).not.toHaveBeenCalled();
             expect(events.find((e) => e.type === "delete-refused-bulk-asymmetry")).toBeDefined();
             // Journal entries survive.
-            const journal = JSON.parse(fs.readFileSync(journalPath, "utf-8"));
+            const journal = journalAt(journalPath);
             expect(Object.keys(journal.files).length).toBe(100);
         });
         it("direction:'down' entries don't count toward the bulk numerator (owned-only silently skips them)", async () => {
@@ -5740,7 +5992,7 @@ describe("share", () => {
                 localDeleteIntent: deleteIntent("up-etag", "h"),
             };
             const journalPath = path.join(stateDir, "sync-journal.acme.json");
-            fs.writeFileSync(journalPath, JSON.stringify({ version: "1", lastSync: now, files }));
+            seedJournalAt(journalPath, { version: "1", lastSync: now, files });
             const result = await share({
                 paths: [companyRoot],
                 company: "acme",
@@ -5863,7 +6115,7 @@ describe("currency-gated: journal version 2 fixtures", () => {
         fs.mkdirSync(companyRoot, { recursive: true });
         const journalPath = path.join(stateDir, "sync-journal.acme.json");
         // v2-shaped fixture — same field set the production journal uses.
-        fs.writeFileSync(journalPath, JSON.stringify({
+        seedJournalAt(journalPath, ({
             version: "2",
             lastSync: new Date().toISOString(),
             files: {
@@ -5909,7 +6161,7 @@ describe("currency-gated: journal version 2 fixtures", () => {
             const { hashFile } = await import("../journal.js");
             const baselineHash = hashFile(testFile);
             const journalPath = path.join(stateDir, "sync-journal.acme.json");
-            fs.writeFileSync(journalPath, JSON.stringify({
+            seedJournalAt(journalPath, ({
                 version: "2",
                 lastSync: new Date().toISOString(),
                 files: {
@@ -5950,7 +6202,7 @@ describe("currency-gated: journal version 2 fixtures", () => {
             const originalLstat = fs.lstatSync(testFile);
             // The recorded hash intentionally differs from the current bytes.
             const journalPath = path.join(stateDir, "sync-journal.acme.json");
-            fs.writeFileSync(journalPath, JSON.stringify({
+            seedJournalAt(journalPath, ({
                 version: "2",
                 lastSync: new Date().toISOString(),
                 files: {
@@ -5997,7 +6249,7 @@ describe("currency-gated: journal version 2 fixtures", () => {
             const { hashFile } = await import("../journal.js");
             const realHash = hashFile(testFile);
             const journalPath = path.join(stateDir, "sync-journal.acme.json");
-            fs.writeFileSync(journalPath, JSON.stringify({
+            seedJournalAt(journalPath, ({
                 version: "2",
                 lastSync: new Date().toISOString(),
                 files: {
@@ -6047,7 +6299,7 @@ describe("currency-gated: journal version 2 fixtures", () => {
             const { hashFile } = await import("../journal.js");
             const realHash = hashFile(testFile);
             const journalPath = path.join(stateDir, "sync-journal.acme.json");
-            fs.writeFileSync(journalPath, JSON.stringify({
+            seedJournalAt(journalPath, ({
                 version: "2",
                 lastSync: new Date().toISOString(),
                 files: {
@@ -6079,7 +6331,7 @@ describe("currency-gated: journal version 2 fixtures", () => {
             expect(uploadFile).not.toHaveBeenCalled();
             // Journal mtimeMs is now the bumped value, while content hashing remains
             // authoritative on the next sync.
-            const journalAfter = JSON.parse(fs.readFileSync(journalPath, "utf-8"));
+            const journalAfter = journalAt(journalPath);
             expect(journalAfter.files["touched-then-fast.md"].mtimeMs).toBe(bumpedLstat.mtimeMs);
             expect(journalAfter.files["touched-then-fast.md"].size).toBe(bumpedLstat.size);
             // Content hash untouched — the file genuinely didn't change.
@@ -6099,7 +6351,7 @@ describe("currency-gated: journal version 2 fixtures", () => {
             });
             expect(result.filesUploaded).toBe(1);
             const journalPath = path.join(stateDir, "sync-journal.acme.json");
-            const journal = JSON.parse(fs.readFileSync(journalPath, "utf-8"));
+            const journal = journalAt(journalPath);
             expect(journal.files["fresh.md"]).toBeDefined();
             expect(journal.files["fresh.md"].mtimeMs).toBe(lstat.mtimeMs);
             expect(journal.files["fresh.md"].size).toBe(lstat.size);
@@ -6116,7 +6368,7 @@ describe("currency-gated: journal version 2 fixtures", () => {
             const realSize = fs.statSync(testFile).size;
             // Real hash but NO mtimeMs. Hash matches → skip upload.
             const journalPath = path.join(stateDir, "sync-journal.acme.json");
-            fs.writeFileSync(journalPath, JSON.stringify({
+            seedJournalAt(journalPath, ({
                 version: "1",
                 lastSync: new Date().toISOString(),
                 files: {
@@ -6675,7 +6927,7 @@ describe("currency-gated: journal version 2 fixtures", () => {
             // AND lost their etag/content-hash/stat journal metadata.
             const journalPath = path.join(stateDir, "sync-journal.acme.json");
             expect(fs.existsSync(journalPath)).toBe(true);
-            const journal = JSON.parse(fs.readFileSync(journalPath, "utf-8"));
+            const journal = journalAt(journalPath);
             const stampedKeys = Object.keys(journal.files);
             expect(stampedKeys.length).toBe(FILE_COUNT - 1);
             // The failed file is NOT in the journal (no successful upload).
@@ -6823,7 +7075,7 @@ describe("scope-invalid key hardening on push (doubled companies/ tree — incid
         const companyRoot = path.join(tmpDir, "companies", "acme");
         fs.mkdirSync(companyRoot, { recursive: true });
         const journalPath = path.join(stateDir, "sync-journal.acme.json");
-        fs.writeFileSync(journalPath, JSON.stringify({
+        seedJournalAt(journalPath, ({
             version: "1",
             lastSync: new Date().toISOString(),
             files: {
@@ -6852,7 +7104,7 @@ describe("scope-invalid key hardening on push (doubled companies/ tree — incid
         expect(headRemoteFile).not.toHaveBeenCalled();
         expect(deleteRemoteFile).not.toHaveBeenCalled();
         expect(uploadFile).not.toHaveBeenCalled();
-        const journal = JSON.parse(fs.readFileSync(journalPath, "utf-8"));
+        const journal = journalAt(journalPath);
         expect(journal.files["companies/acme/knowledge/poison.md"]).toBeUndefined();
     });
     it("defers an unreadable scope-invalid symlink tombstone without a fatal error", async () => {
@@ -6864,7 +7116,7 @@ describe("scope-invalid key hardening on push (doubled companies/ tree — incid
         fs.mkdirSync(targetDir, { recursive: true });
         fs.symlinkSync(targetDir, linkPath, "dir");
         const journalPath = path.join(stateDir, "sync-journal.acme.json");
-        fs.writeFileSync(journalPath, JSON.stringify({
+        seedJournalAt(journalPath, ({
             version: "1",
             lastSync: new Date().toISOString(),
             files: {
@@ -6909,7 +7161,7 @@ describe("scope-invalid key hardening on push (doubled companies/ tree — incid
                 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]).toBeDefined();
         }
         finally {