@indigoai-us/hq-cloud 6.15.19 → 6.15.21

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: {
@@ -593,7 +625,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 +769,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 +821,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 +1001,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 +1117,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 +1190,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 +1272,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 +1332,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 +1367,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 +1409,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 +1455,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: {
@@ -1450,6 +1482,304 @@ describe("share", () => {
             // fence then retry — either is consent. Must not leave the file unuploaded.
             expect(uploadFile).toHaveBeenCalled();
         });
+        // ── publish-local: fenced promotion of a kept-local copy ────────────────
+        //
+        // `keep` leaves a file permanently unpublishable: push refuses it on the
+        // localDiverges flag, pull never clears the flag (remote is unchanged), and
+        // `keep` re-arms it every pass. The only existing escape — `overwrite` — is
+        // a blunt force-write that will PUT unfenced after a 412, clobbering a
+        // remote that genuinely advanced.
+        //
+        // `publish-local` is the missing middle: the operator explicitly elects
+        // their local copy as the new authority, and the engine accepts it ONLY
+        // while the remote still sits at the etag recorded when the keep happened.
+        // If the remote moved, consent was given against a version that no longer
+        // exists, so the write must fail closed instead of forcing.
+        it("localDiverges under publish-local: promotes local under an If-Match fence on the journal etag", async () => {
+            const companyRoot = path.join(tmpDir, "companies", "acme");
+            fs.mkdirSync(companyRoot, { recursive: true });
+            const testFile = path.join(companyRoot, "publish-divergent.md");
+            const localBytes = "my kept divergent local, now elected authority";
+            fs.writeFileSync(testFile, localBytes);
+            const localHash = hashFile(testFile);
+            const REMOTE = "peer-version-etag";
+            vi.mocked(headRemoteFile).mockResolvedValueOnce({
+                lastModified: new Date(),
+                etag: `"${REMOTE}"`,
+                size: 40,
+            });
+            vi.mocked(uploadFile).mockResolvedValueOnce({ etag: '"published-etag"' });
+            const journalPath = path.join(stateDir, "sync-journal.acme.json");
+            fs.writeFileSync(journalPath, JSON.stringify({
+                version: "1",
+                lastSync: new Date().toISOString(),
+                files: {
+                    "publish-divergent.md": {
+                        hash: localHash,
+                        size: localBytes.length,
+                        syncedAt: new Date().toISOString(),
+                        direction: "down",
+                        remoteEtag: REMOTE,
+                        localDiverges: true,
+                    },
+                },
+            }));
+            const result = await share({
+                paths: [testFile],
+                company: "acme",
+                vaultConfig: mockConfig,
+                hqRoot: tmpDir,
+                skipUnchanged: false,
+                onConflict: "publish-local",
+            });
+            expect(result.filesUploaded).toBe(1);
+            // Fenced on the etag the keep recorded — never unfenced, never live-HEAD.
+            expect(uploadFile).toHaveBeenCalledTimes(1);
+            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 = 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");
+            expect(fs.readFileSync(testFile, "utf-8")).toBe(localBytes);
+        });
+        it("localDiverges under publish-local: a 412 fails closed and never retries unfenced", async () => {
+            const companyRoot = path.join(tmpDir, "companies", "acme");
+            fs.mkdirSync(companyRoot, { recursive: true });
+            const testFile = path.join(companyRoot, "publish-raced.md");
+            const localBytes = "my local, but the remote moved under me";
+            fs.writeFileSync(testFile, localBytes);
+            const localHash = hashFile(testFile);
+            const REMOTE = "etag-at-keep-time";
+            vi.mocked(headRemoteFile).mockResolvedValueOnce({
+                lastModified: new Date(),
+                etag: `"${REMOTE}"`,
+                size: 40,
+            });
+            const precondition = Object.assign(new Error("At least one of the pre-conditions you specified did not hold"), {
+                name: "PreconditionFailed",
+            });
+            vi.mocked(uploadFile).mockRejectedValueOnce(precondition);
+            const journalPath = path.join(stateDir, "sync-journal.acme.json");
+            fs.writeFileSync(journalPath, JSON.stringify({
+                version: "1",
+                lastSync: new Date().toISOString(),
+                files: {
+                    "publish-raced.md": {
+                        hash: localHash,
+                        size: localBytes.length,
+                        syncedAt: new Date().toISOString(),
+                        direction: "down",
+                        remoteEtag: REMOTE,
+                        localDiverges: true,
+                    },
+                },
+            }));
+            const result = await share({
+                paths: [testFile],
+                company: "acme",
+                vaultConfig: mockConfig,
+                hqRoot: tmpDir,
+                skipUnchanged: false,
+                onConflict: "publish-local",
+            });
+            // Exactly one attempt: the fenced one. The `overwrite` escape hatch of
+            // re-PUTting with no precondition must NOT be reachable from here.
+            expect(uploadFile).toHaveBeenCalledTimes(1);
+            expect(result.filesUploaded).toBe(0);
+            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 = journalAt(journalPath);
+            expect(journal.files["publish-raced.md"].localDiverges).toBe(true);
+            expect(fs.readFileSync(testFile, "utf-8")).toBe(localBytes);
+        });
+        // Codex review (PR #356, P1). The sync runner's push leg always calls
+        // share() with `skipUnchanged: true`, and a pull-kept entry stores the
+        // CURRENT local hash — that is exactly what the journal-honesty stamp
+        // records. So `existing.hash === localHash` is true for every stuck file,
+        // classifyPushCandidates() returns `skip-unchanged`, and executeUploads()
+        // never runs: no HEAD, no conflict, no upload. Without this bypass the
+        // whole recovery is a no-op in the one mode that can reach personal-vault
+        // files, and the next pull leaves them stuck again. `hash === journal hash`
+        // means "local is unchanged since the stamp", NOT "local matches remote" —
+        // for a divergent entry those are different claims.
+        it("localDiverges bypasses the skip-unchanged fast path so the recovery can run at all", async () => {
+            const companyRoot = path.join(tmpDir, "companies", "acme");
+            fs.mkdirSync(companyRoot, { recursive: true });
+            const testFile = path.join(companyRoot, "stuck-under-skip-unchanged.md");
+            const localBytes = "the body a pull-keep stamped and then refused to publish";
+            fs.writeFileSync(testFile, localBytes);
+            const localHash = hashFile(testFile);
+            const REMOTE = "etag-at-keep-time";
+            vi.mocked(headRemoteFile).mockResolvedValueOnce({
+                lastModified: new Date(),
+                etag: `"${REMOTE}"`,
+                size: 40,
+            });
+            vi.mocked(uploadFile).mockResolvedValueOnce({ etag: '"published-etag"' });
+            const journalPath = path.join(stateDir, "sync-journal.acme.json");
+            fs.writeFileSync(journalPath, JSON.stringify({
+                version: "1",
+                lastSync: new Date().toISOString(),
+                files: {
+                    "stuck-under-skip-unchanged.md": {
+                        // Deliberately the CURRENT local hash: this is what a pull-keep
+                        // writes, and it is what makes the fast path swallow the file.
+                        hash: localHash,
+                        size: localBytes.length,
+                        syncedAt: new Date().toISOString(),
+                        direction: "down",
+                        remoteEtag: REMOTE,
+                        localDiverges: true,
+                    },
+                },
+            }));
+            const result = await share({
+                paths: [testFile],
+                company: "acme",
+                vaultConfig: mockConfig,
+                hqRoot: tmpDir,
+                skipUnchanged: true,
+                onConflict: "publish-local",
+            });
+            expect(result.filesUploaded).toBe(1);
+            expect(vi.mocked(uploadFile).mock.calls[0][4]).toEqual({ ifMatch: REMOTE });
+            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();
+        });
+        // Codex review (PR #356, P2). A genuine two-sided conflict is not the
+        // localDiverges recovery: the journal etag is stale BY DEFINITION here
+        // (that is what remoteChanged means), so fencing consent on it guarantees a
+        // 412 and the file can never publish. Consent given at this prompt is
+        // consent against the remote the operator was just shown, so the fence must
+        // be the freshly observed etag.
+        it("publish-local on a fresh two-sided conflict fences on the OBSERVED remote etag, not the stale journal one", async () => {
+            const companyRoot = path.join(tmpDir, "companies", "acme");
+            fs.mkdirSync(companyRoot, { recursive: true });
+            const testFile = path.join(companyRoot, "two-sided.md");
+            fs.writeFileSync(testFile, "my newer local body");
+            const STALE_JOURNAL_ETAG = "etag-from-last-sync";
+            const OBSERVED_REMOTE_ETAG = "etag-the-peer-just-wrote";
+            vi.mocked(headRemoteFile).mockResolvedValueOnce({
+                lastModified: new Date(),
+                etag: `"${OBSERVED_REMOTE_ETAG}"`,
+                size: 40,
+            });
+            vi.mocked(uploadFile).mockResolvedValueOnce({ etag: '"published-etag"' });
+            const journalPath = path.join(stateDir, "sync-journal.acme.json");
+            fs.writeFileSync(journalPath, JSON.stringify({
+                version: "1",
+                lastSync: new Date().toISOString(),
+                files: {
+                    "two-sided.md": {
+                        hash: "a-hash-that-is-neither-side",
+                        size: 10,
+                        syncedAt: new Date().toISOString(),
+                        direction: "up",
+                        remoteEtag: STALE_JOURNAL_ETAG,
+                    },
+                },
+            }));
+            const result = await share({
+                paths: [testFile],
+                company: "acme",
+                vaultConfig: mockConfig,
+                hqRoot: tmpDir,
+                skipUnchanged: false,
+                onConflict: "publish-local",
+            });
+            expect(result.filesUploaded).toBe(1);
+            expect(vi.mocked(uploadFile).mock.calls[0][4]).toEqual({
+                ifMatch: OBSERVED_REMOTE_ETAG,
+            });
+        });
+        // Codex review (PR #356, P2). HEAD returning null skips the whole conflict
+        // block, so the precondition becomes If-None-Match:* and the object is
+        // RECREATED. For a divergent entry that silently overrules a peer's
+        // deletion — the remote is emphatically no longer at the recorded etag, so
+        // the strategy's own fence says fail closed. `keep`'s recreate-once
+        // behaviour for non-divergent entries is unaffected.
+        it("publish-local does not resurrect a remote deleted after the keep", async () => {
+            const companyRoot = path.join(tmpDir, "companies", "acme");
+            fs.mkdirSync(companyRoot, { recursive: true });
+            const testFile = path.join(companyRoot, "peer-deleted.md");
+            const localBytes = "my divergent local body";
+            fs.writeFileSync(testFile, localBytes);
+            const localHash = hashFile(testFile);
+            vi.mocked(headRemoteFile).mockResolvedValueOnce(null);
+            const journalPath = path.join(stateDir, "sync-journal.acme.json");
+            fs.writeFileSync(journalPath, JSON.stringify({
+                version: "1",
+                lastSync: new Date().toISOString(),
+                files: {
+                    "peer-deleted.md": {
+                        hash: localHash,
+                        size: localBytes.length,
+                        syncedAt: new Date().toISOString(),
+                        direction: "down",
+                        remoteEtag: "etag-before-the-peer-deleted-it",
+                        localDiverges: true,
+                    },
+                },
+            }));
+            const result = await share({
+                paths: [testFile],
+                company: "acme",
+                vaultConfig: mockConfig,
+                hqRoot: tmpDir,
+                skipUnchanged: false,
+                onConflict: "publish-local",
+            });
+            expect(uploadFile).not.toHaveBeenCalled();
+            expect(result.filesUploaded).toBe(0);
+            expect(result.conflictPaths).toContain("peer-deleted.md");
+            const journal = journalAt(journalPath);
+            expect(journal.files["peer-deleted.md"].localDiverges).toBe(true);
+            expect(fs.readFileSync(testFile, "utf-8")).toBe(localBytes);
+        });
+        it("publish-local on a non-divergent file behaves like an ordinary fenced upload", async () => {
+            const companyRoot = path.join(tmpDir, "companies", "acme");
+            fs.mkdirSync(companyRoot, { recursive: true });
+            const testFile = path.join(companyRoot, "ordinary.md");
+            fs.writeFileSync(testFile, "locally edited since last sync");
+            const REMOTE = "unchanged-remote-etag";
+            vi.mocked(headRemoteFile).mockResolvedValueOnce({
+                lastModified: new Date(),
+                etag: `"${REMOTE}"`,
+                size: 10,
+            });
+            vi.mocked(uploadFile).mockResolvedValueOnce({ etag: '"next-etag"' });
+            const journalPath = path.join(stateDir, "sync-journal.acme.json");
+            fs.writeFileSync(journalPath, JSON.stringify({
+                version: "1",
+                lastSync: new Date().toISOString(),
+                files: {
+                    "ordinary.md": {
+                        hash: "stale-hash-from-a-previous-body",
+                        size: 10,
+                        syncedAt: new Date().toISOString(),
+                        direction: "up",
+                        remoteEtag: REMOTE,
+                    },
+                },
+            }));
+            const result = await share({
+                paths: [testFile],
+                company: "acme",
+                vaultConfig: mockConfig,
+                hqRoot: tmpDir,
+                skipUnchanged: false,
+                onConflict: "publish-local",
+            });
+            // No localDiverges flag means no special casing: the normal push fence
+            // applies and the file uploads without being routed through conflict.
+            expect(result.filesUploaded).toBe(1);
+            expect(result.conflictPaths ?? []).not.toContain("ordinary.md");
+            expect(vi.mocked(uploadFile).mock.calls[0][4]).toEqual({ ifMatch: REMOTE });
+        });
         // Journal still carries remoteEtag from a prior sync, but the remote key
         // is gone (HEAD null) — e.g. peer delete or operator purge. Recreation
         // must use If-None-Match:* (create-only), NOT If-Match on the stale
@@ -1467,7 +1797,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: {
@@ -1497,7 +1827,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",
@@ -1518,7 +1848,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: {
@@ -1550,7 +1880,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");
@@ -1874,7 +2204,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: {
@@ -1914,7 +2244,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: {
@@ -1950,7 +2280,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 () => {
@@ -1995,7 +2325,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: {
@@ -2215,7 +2545,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: {
@@ -2276,7 +2606,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: {
@@ -2313,7 +2643,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 () => {
@@ -2330,7 +2660,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: {
@@ -2360,7 +2690,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 " +
@@ -2425,7 +2755,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 {
@@ -2498,7 +2828,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: {
@@ -2523,7 +2853,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 " +
@@ -2614,7 +2944,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 {
@@ -2631,7 +2961,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: {
@@ -2667,7 +2997,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();
     });
@@ -2675,7 +3005,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: {
@@ -2717,7 +3047,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: {
@@ -2740,7 +3070,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 () => {
@@ -2748,7 +3078,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: {
@@ -2783,7 +3113,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.
@@ -2799,7 +3129,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: {
@@ -2834,7 +3164,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();
@@ -2851,7 +3181,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: {
@@ -2881,14 +3211,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: {
@@ -2921,7 +3251,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) ──────
@@ -2955,7 +3285,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: {
@@ -2992,7 +3322,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: {
@@ -3025,7 +3355,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: {
@@ -3084,7 +3414,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: {
@@ -3114,7 +3444,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 () => {
@@ -3125,7 +3455,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: {
@@ -3161,7 +3491,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 () => {
@@ -3170,7 +3500,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: {
@@ -3202,7 +3532,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
@@ -3224,7 +3554,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: {
@@ -3260,7 +3590,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",
@@ -3282,7 +3612,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: {
@@ -3317,7 +3647,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");
@@ -3334,7 +3664,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: {
@@ -3367,7 +3697,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
@@ -3388,7 +3718,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: {
@@ -3442,7 +3772,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: {
@@ -3494,7 +3824,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: {
@@ -3528,7 +3858,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: {
@@ -3578,7 +3908,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: {
@@ -3626,7 +3956,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: {
@@ -3656,14 +3986,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: {
@@ -3850,7 +4180,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: {
@@ -3891,7 +4221,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();
     });
@@ -3906,7 +4236,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: {
@@ -3932,7 +4262,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 {
@@ -3955,7 +4285,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: {
@@ -4003,7 +4333,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();
@@ -4035,7 +4365,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: [],
@@ -4067,7 +4397,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 ──────────────────────────────────────────────────
     //
@@ -4122,7 +4452,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();
     });
@@ -4158,7 +4488,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 () => {
@@ -4278,7 +4608,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", () => {
@@ -4319,7 +4649,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 () => {
@@ -4607,7 +4937,7 @@ describe("share", () => {
                 .createHash("sha256")
                 .update(target)
                 .digest("hex");
-            fs.writeFileSync(journalPath, JSON.stringify({
+            seedJournalAt(journalPath, ({
                 version: "1",
                 lastSync: new Date().toISOString(),
                 files: {
@@ -5010,7 +5340,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({
@@ -5024,7 +5354,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");
         });
     });
@@ -5068,7 +5398,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,
@@ -5126,7 +5456,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");
@@ -5176,7 +5506,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
@@ -5207,7 +5537,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 () => {
@@ -5221,7 +5551,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,
@@ -5230,7 +5560,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(),
@@ -5370,7 +5700,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 () => {
@@ -5414,7 +5744,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 () => {
@@ -5442,7 +5772,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",
@@ -5565,7 +5895,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: {
@@ -5611,7 +5941,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: {
@@ -5652,7 +5982,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: {
@@ -5699,7 +6029,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: {
@@ -5749,7 +6079,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: {
@@ -5781,7 +6111,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.
@@ -5801,7 +6131,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);
@@ -5818,7 +6148,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: {
@@ -6377,7 +6707,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).
@@ -6525,7 +6855,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: {
@@ -6554,7 +6884,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 () => {
@@ -6566,7 +6896,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: {
@@ -6611,7 +6941,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 {