@indigoai-us/hq-cloud 6.15.31 → 6.15.33

package/dist/cli/share.test.js

@@ -53,9 +53,49 @@ vi.mock("readline", () => ({
 }));
 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 { deleteRemoteFile, downloadFile, headRemoteFile, primeObjectTransport, primeUploads, 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);
+}
+function sidecarIn(dir) {
+    const found = fs.readdirSync(dir).filter((name) => name.includes(".conflict-"));
+    expect(found).toHaveLength(1);
+    return path.join(dir, found[0]);
+}
+function conflictIndexAt(hqRoot) {
+    return JSON.parse(fs.readFileSync(path.join(hqRoot, ".hq-conflicts", "index.json"), "utf-8"));
+}
 const mockConfig = {
     apiUrl: "https://vault-api.test",
     authToken: "test-jwt-token",
@@ -369,6 +409,74 @@ describe("share", () => {
         // Remote key must be company-relative, not hqRoot-relative
         expect(uploadFile).toHaveBeenCalledWith(expect.anything(), testFile, "test.md", undefined, expect.anything());
     });
+    it("replans an upload from the bytes present when its action starts", async () => {
+        const companyRoot = path.join(tmpDir, "companies", "acme");
+        fs.mkdirSync(companyRoot, { recursive: true });
+        const testFile = path.join(companyRoot, "changing.md");
+        fs.writeFileSync(testFile, "body seen by the whole-run preview");
+        let uploadedBody = "";
+        vi.mocked(uploadFile).mockImplementationOnce(async (_ctx, localPath) => {
+            uploadedBody = fs.readFileSync(localPath, "utf-8");
+            return { etag: '"fresh-upload-etag"' };
+        });
+        let changedAfterPlan = false;
+        let executionHeartbeatCalls = 0;
+        const result = await share({
+            paths: [testFile],
+            company: "acme",
+            vaultConfig: mockConfig,
+            hqRoot: tmpDir,
+            onEvent: (event) => {
+                if (event.type === "plan" && !changedAfterPlan) {
+                    changedAfterPlan = true;
+                    fs.writeFileSync(testFile, "body present when upload executes");
+                }
+            },
+            onHeartbeat: () => {
+                if (changedAfterPlan)
+                    executionHeartbeatCalls++;
+            },
+        });
+        expect(changedAfterPlan).toBe(true);
+        expect(executionHeartbeatCalls).toBeGreaterThan(0);
+        expect(result.filesUploaded).toBe(1);
+        expect(uploadedBody).toBe("body present when upload executes");
+        expect(journalAt(path.join(stateDir, "sync-journal.acme.json")).files["changing.md"])
+            .toMatchObject({
+            hash: hashFile(testFile),
+            remoteEtag: "fresh-upload-etag",
+            direction: "up",
+        });
+    });
+    it("restarts the per-file decision when local bytes change during remote HEAD", async () => {
+        const companyRoot = path.join(tmpDir, "companies", "acme");
+        fs.mkdirSync(companyRoot, { recursive: true });
+        const testFile = path.join(companyRoot, "head-race.md");
+        fs.writeFileSync(testFile, "body before HEAD");
+        vi.mocked(headRemoteFile).mockImplementationOnce(async () => {
+            fs.writeFileSync(testFile, "body written while HEAD was in flight");
+            return null;
+        });
+        let uploadedBody = "";
+        vi.mocked(uploadFile).mockImplementationOnce(async (_ctx, localPath) => {
+            uploadedBody = fs.readFileSync(localPath, "utf-8");
+            return { etag: '"head-race-etag"' };
+        });
+        const result = await share({
+            paths: [testFile],
+            company: "acme",
+            vaultConfig: mockConfig,
+            hqRoot: tmpDir,
+        });
+        expect(result.filesUploaded).toBe(1);
+        expect(uploadedBody).toBe("body written while HEAD was in flight");
+        expect(journalAt(path.join(stateDir, "sync-journal.acme.json")).files["head-race.md"])
+            .toMatchObject({
+            hash: hashFile(testFile),
+            remoteEtag: "head-race-etag",
+            direction: "up",
+        });
+    });
     it("propagates a per-file vault 401 to the runner auth boundary", async () => {
         const companyRoot = path.join(tmpDir, "companies", "acme");
         fs.mkdirSync(companyRoot, { recursive: true });
@@ -382,6 +490,42 @@ describe("share", () => {
             hqRoot: tmpDir,
         })).rejects.toBeInstanceOf(VaultAuthError);
     });
+    it("surfaces a safe nested upload-worker cause without replacing the first error", async () => {
+        const companyRoot = path.join(tmpDir, "companies", "acme");
+        fs.mkdirSync(companyRoot, { recursive: true });
+        const firstFile = path.join(companyRoot, "first.md");
+        const secondFile = path.join(companyRoot, "second.md");
+        fs.writeFileSync(firstFile, "first");
+        fs.writeFileSync(secondFile, "second");
+        const networkCause = Object.assign(new Error("connect ECONNREFUSED sync.example.test Authorization: Bearer upload-secret"), { code: "ECONNREFUSED", syscall: "connect", hostname: "sync.example.test" });
+        const first = new VaultAuthError("UnknownError");
+        first.name = "UnknownError";
+        first.cause = networkCause;
+        const second = new VaultAuthError("second worker failed");
+        vi.mocked(uploadFile)
+            .mockRejectedValueOnce(first)
+            .mockRejectedValueOnce(second);
+        let thrown;
+        try {
+            await share({
+                paths: [firstFile, secondFile],
+                company: "acme",
+                vaultConfig: mockConfig,
+                hqRoot: tmpDir,
+            });
+        }
+        catch (err) {
+            thrown = err;
+        }
+        expect(thrown).toBe(first);
+        expect(first.cause).toBe(networkCause);
+        expect(first.message).toContain("cause=ECONNREFUSED");
+        expect(first.message).toContain("syscall=connect");
+        expect(first.message).toContain("host=sync.example.test");
+        expect(first.message).toContain("(and 1 more upload-worker errors)");
+        expect(first.message).not.toContain("upload-secret");
+        expect(first.message.length).toBeLessThanOrEqual(1_024);
+    });
     it("respects ignore rules", async () => {
         const companyRoot = path.join(tmpDir, "companies", "acme");
         fs.mkdirSync(path.join(companyRoot, ".git"), { recursive: true });
@@ -528,7 +672,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 +703,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 +725,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-held 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("replans and stamps the new body when the file changes during remote HEAD", async () => {
+            // The pass-level preview hashes CONTENT_A, then the asynchronous remote
+            // probe changes the file to CONTENT_B. The per-file execution seam must
+            // restart from CONTENT_B, upload it now, and journal that exact body — no
+            // stale hash and no redundant upload on the next pass.
+            const abs = writeFile("edited-mid-flight.md", CONTENT_A);
+            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"];
+            const currentStat = fs.lstatSync(abs);
+            expect(entry.hash).toBe(hashFile(abs));
+            expect(entry.mtimeMs).toBe(currentStat.mtimeMs);
+            expect(entry.ctimeMs).toBe(currentStat.ctimeMs);
+            // The current bytes were already shipped and journaled in this pass.
+            vi.mocked(uploadFile).mockClear();
+            const second = await push(abs);
+            expect(second.filesUploaded).toBe(0);
+            expect(uploadFile).not.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 +957,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: {
@@ -630,6 +994,8 @@ describe("share", () => {
             });
             // The resurrection is blocked at the source: no upload for the tombstoned key.
             expect(uploadFile).not.toHaveBeenCalled();
+            expect(primeUploads).toHaveBeenCalledWith(expect.anything(), []);
+            expect(primeObjectTransport).toHaveBeenCalledWith(expect.anything(), "get", []);
             expect(result.filesUploaded).toBe(0);
             expect(result.filesSuppressedByTombstone).toBe(1);
             expect(events.some((e) => e.type === "upload-suppressed-tombstone" && e.path === "docs/shared.md")).toBe(true);
@@ -736,8 +1102,12 @@ describe("share", () => {
             etag: '"remote-new-etag"',
             size: 99,
         });
+        vi.mocked(downloadFile).mockImplementationOnce(async (_ctx, _key, dest) => {
+            fs.writeFileSync(dest, "remote edit");
+            return undefined;
+        });
         const journalPath = path.join(stateDir, "sync-journal.acme.json");
-        fs.writeFileSync(journalPath, JSON.stringify({
+        seedJournalAt(journalPath, ({
             version: "1",
             lastSync: new Date().toISOString(),
             files: {
@@ -768,6 +1138,24 @@ describe("share", () => {
             direction: "push",
             resolution: "keep",
         });
+        // `keep` is cloud-wins on the push leg too: remote takes the working
+        // name, while the displaced local body remains recoverable beside it.
+        expect(fs.readFileSync(testFile, "utf-8")).toBe("remote edit");
+        expect(fs.readFileSync(sidecarIn(companyRoot), "utf-8")).toBe("local edit");
+        const journal = journalAt(journalPath);
+        expect(journal.files["drifted.md"]).toMatchObject({
+            hash: hashFile(testFile),
+            remoteEtag: "remote-new-etag",
+            direction: "down",
+        });
+        const index = conflictIndexAt(tmpDir);
+        expect(index.conflicts).toHaveLength(1);
+        expect(index.conflicts[0]).toMatchObject({
+            originalPath: "companies/acme/drifted.md",
+            preserved: "local",
+        });
+        expect(fs.readFileSync(path.join(tmpDir, index.conflicts[0].conflictPath), "utf-8"))
+            .toBe("local edit");
     });
     it("cloud-authoritative: never pushes a stale local ontology/.last-run over the server value (one-sided-change clobber guard)", async () => {
         // Regression for the gardener watermark clobber. A second HQ root sharing this
@@ -789,7 +1177,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: {
@@ -835,9 +1223,9 @@ describe("share", () => {
         //
         // Fix: even on first-time upload, if HEAD shows remote exists and
         // its content (etag) differs from what we'd put, emit a conflict.
-        // Under keep, the existing pull-side mirror routine downloads the
-        // remote bytes to \`<orig>.conflict-<ts>-<short>\` so both versions
-        // survive on disk; under abort, the company aborts before PUT.
+        // Under keep, cloud takes the original name and local moves to
+        // \`<orig>.conflict-<ts>-<short>\` so both versions survive on disk;
+        // under abort, the company aborts before PUT.
         const companyRoot = path.join(tmpDir, "companies", "acme");
         fs.mkdirSync(companyRoot, { recursive: true });
         const testFile = path.join(companyRoot, "v7b-fresh.txt");
@@ -849,6 +1237,10 @@ describe("share", () => {
             etag: '"remote-version-etag"',
             size: 40,
         });
+        vi.mocked(downloadFile).mockImplementation(async (_ctx, _key, dest) => {
+            fs.writeFileSync(dest, "peer remote content");
+            return undefined;
+        });
         // No journal file written — first-time upload contract.
         const events = [];
         const result = await share({
@@ -860,14 +1252,19 @@ describe("share", () => {
             onEvent: (e) => events.push(e),
         });
         expect(result.conflictPaths).toEqual(["v7b-fresh.txt"]);
-        // Under keep, local stays as-is (no upload) and the mirror records
-        // the remote bytes so neither version is lost.
+        // Under keep, no upload occurs: the remote bytes take the working name
+        // and the local body is preserved beside them.
         expect(result.filesUploaded).toBe(0);
         const conflicts = events.filter((e) => typeof e === "object" && e !== null && e.type === "conflict");
         expect(conflicts).toHaveLength(1);
         expect(conflicts[0].path).toBe("v7b-fresh.txt");
-        // Local file unmodified — it must still contain the local content.
-        expect(fs.readFileSync(testFile, "utf-8")).toBe("macos-fresh-collision-content");
+        expect(fs.readFileSync(testFile, "utf-8")).toBe("peer remote content");
+        expect(fs.readFileSync(sidecarIn(companyRoot), "utf-8")).toBe("macos-fresh-collision-content");
+        const index = conflictIndexAt(tmpDir);
+        expect(index.conflicts[0]).toMatchObject({
+            originalPath: "companies/acme/v7b-fresh.txt",
+            preserved: "local",
+        });
     });
     it("first-time-upload-with-cloud-collision: aborts company under --on-conflict abort (Bug #7)", async () => {
         // Symmetric to the keep case: when --on-conflict abort is passed, a
@@ -895,11 +1292,11 @@ describe("share", () => {
         expect(result.filesUploaded).toBe(0);
     });
     it("HQ-DESKTOP-54: a privilege refusal while writing the push conflict mirror is a skip, not an error", async () => {
-        // The keep-mirror also materializes the remote object (to a .conflict-*
-        // file). On an unprivileged Windows host that throws the typed privilege
+        // Push keep also materializes the remote object (at the original name).
+        // On an unprivileged Windows host that throws the typed privilege
         // error; it must be downgraded to the deliberate skip so the push stays
         // complete and the runner exits 0 — never type:error. The conflict itself
-        // is still recorded and the local file is untouched.
+        // is still surfaced and the local rename is rolled back.
         const companyRoot = path.join(tmpDir, "companies", "acme");
         fs.mkdirSync(companyRoot, { recursive: true });
         const testFile = path.join(companyRoot, "v7b-priv.txt");
@@ -910,7 +1307,7 @@ describe("share", () => {
             size: 40,
         });
         // On a real unprivileged host BOTH the fresh-collision reconciled probe and
-        // the keep-mirror materialize the remote symlink, so both downloadFile calls
+        // the keep adoption materialize the remote symlink, so both downloadFile calls
         // refuse. The probe's catch returns "differs" (conflict) without erroring;
         // the mirror must downgrade the refusal to the deliberate skip.
         vi.mocked(downloadFile)
@@ -931,7 +1328,7 @@ describe("share", () => {
             target: "../target.md",
         }));
         expect(events.some((e) => e.type === "error")).toBe(false);
-        // The conflict is still recorded; the local file is preserved.
+        // The conflict is still surfaced; the failed adoption restores local.
         expect(result.conflictPaths).toEqual(["v7b-priv.txt"]);
         expect(fs.readFileSync(testFile, "utf-8")).toBe("local-collision-content");
     });
@@ -969,7 +1366,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",
@@ -1043,7 +1440,7 @@ describe("share", () => {
             etag: '"0123456789abcdef0123456789abcdef-3"',
             size: 32,
         });
-        // The probe (and the subsequent keep-mirror download) return DIFFERENT
+        // The probe (and the subsequent keep adoption download) return DIFFERENT
         // remote bytes.
         vi.mocked(downloadFile).mockImplementation(async (_ctx, _key, dest) => {
             fs.writeFileSync(dest, "a-peers-different-version");
@@ -1062,8 +1459,8 @@ describe("share", () => {
         expect(result.filesUploaded).toBe(0);
         const conflicts = events.filter((e) => typeof e === "object" && e !== null && e.type === "conflict");
         expect(conflicts).toHaveLength(1);
-        // Local file untouched under keep.
-        expect(fs.readFileSync(testFile, "utf-8")).toBe("my-local-version");
+        expect(fs.readFileSync(testFile, "utf-8")).toBe("a-peers-different-version");
+        expect(fs.readFileSync(sidecarIn(companyRoot), "utf-8")).toBe("my-local-version");
     });
     describe("conditional-write fence (If-Match / If-None-Match / 412)", () => {
         const fence412 = () => Object.assign(new Error("Precondition failed"), {
@@ -1085,7 +1482,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: {
@@ -1123,12 +1520,18 @@ describe("share", () => {
             });
             expect(uploadFile).toHaveBeenCalledWith(expect.anything(), testFile, "brand-new.md", undefined, { ifNoneMatch: "*" });
         });
-        it("412 under keep: conflict event + remote mirrored + ledger entry + NO journal stamp", async () => {
+        it("412 under keep: adopts the racing remote, preserves local, and converges the journal", async () => {
             const companyRoot = path.join(tmpDir, "companies", "acme");
             fs.mkdirSync(companyRoot, { recursive: true });
             const testFile = path.join(companyRoot, "raced.md");
             fs.writeFileSync(testFile, "my local bytes");
-            vi.mocked(headRemoteFile).mockResolvedValueOnce(null);
+            vi.mocked(headRemoteFile)
+                .mockResolvedValueOnce(null)
+                .mockResolvedValueOnce({
+                lastModified: new Date(),
+                etag: '"racing-peer-etag"',
+                size: 23,
+            });
             vi.mocked(uploadFile).mockRejectedValueOnce(fence412());
             vi.mocked(downloadFile).mockImplementationOnce(async (_ctx, _key, dest) => {
                 fs.writeFileSync(dest, "the racing peer version");
@@ -1148,19 +1551,22 @@ describe("share", () => {
             expect(result.filesUploaded).toBe(0);
             expect(result.aborted).toBe(false);
             expect(events.some((e) => e.type === "conflict" && e.path === "raced.md")).toBe(true);
-            // The racing remote bytes were preserved next to the local copy.
-            const mirrors = fs
-                .readdirSync(companyRoot)
-                .filter((f) => f.includes(".conflict-"));
-            expect(mirrors).toHaveLength(1);
-            // Local copy untouched.
-            expect(fs.readFileSync(testFile, "utf-8")).toBe("my local bytes");
-            // No journal stamp for the failed PUT — next pass re-evaluates fresh.
+            // The racing remote wins the working name; local remains recoverable.
+            expect(fs.readFileSync(testFile, "utf-8")).toBe("the racing peer version");
+            expect(fs.readFileSync(sidecarIn(companyRoot), "utf-8")).toBe("my local bytes");
+            // The pull-shaped result is journalled as the remote body, so the next
+            // pass does not revive the same resolved conflict.
             const journalPath = path.join(stateDir, "sync-journal.acme.json");
-            if (fs.existsSync(journalPath)) {
-                const journal = JSON.parse(fs.readFileSync(journalPath, "utf-8"));
-                expect(journal.files?.["raced.md"]).toBeUndefined();
-            }
+            const journal = journalAt(journalPath);
+            expect(journal.files["raced.md"]).toMatchObject({
+                hash: hashFile(testFile),
+                remoteEtag: "racing-peer-etag",
+                direction: "down",
+            });
+            expect(conflictIndexAt(tmpDir).conflicts[0]).toMatchObject({
+                originalPath: "companies/acme/raced.md",
+                preserved: "local",
+            });
         });
         it("412 under overwrite: retries exactly once WITHOUT the fence (explicit consent)", async () => {
             const companyRoot = path.join(tmpDir, "companies", "acme");
@@ -1239,8 +1645,12 @@ describe("share", () => {
                 }
                 return { etag: '"should-not-land"' };
             });
+            vi.mocked(downloadFile).mockImplementationOnce(async (_ctx, _key, dest) => {
+                fs.writeFileSync(dest, "reviewed peer body");
+                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: {
@@ -1283,8 +1693,9 @@ describe("share", () => {
             }
             // No unfenced retry under keep.
             expect(vi.mocked(uploadFile).mock.calls.some((c) => c[4] === undefined)).toBe(false);
-            // Local stale bytes preserved on disk (keep does not pull).
-            expect(fs.readFileSync(testFile, "utf-8")).toBe(staleBytes);
+            // Keep adopts the peer body but retains the stale local body beside it.
+            expect(fs.readFileSync(testFile, "utf-8")).toBe("reviewed peer body");
+            expect(fs.readFileSync(sidecarIn(path.dirname(testFile)), "utf-8")).toBe(staleBytes);
         });
         it("legitimate local-ahead still uploads when remote remains at journal baseline", async () => {
             const companyRoot = path.join(tmpDir, "companies", "acme");
@@ -1300,7 +1711,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: {
@@ -1334,8 +1745,12 @@ describe("share", () => {
                 etag: '"remote-concurrent"',
                 size: 20,
             });
+            vi.mocked(downloadFile).mockImplementationOnce(async (_ctx, _key, dest) => {
+                fs.writeFileSync(dest, "remote concurrent");
+                return undefined;
+            });
             const journalPath = path.join(stateDir, "sync-journal.acme.json");
-            fs.writeFileSync(journalPath, JSON.stringify({
+            seedJournalAt(journalPath, ({
                 version: "1",
                 lastSync: new Date().toISOString(),
                 files: {
@@ -1358,12 +1773,14 @@ describe("share", () => {
             expect(result.conflictPaths).toEqual(["both-changed.md"]);
             expect(result.filesUploaded).toBe(0);
             expect(uploadFile).not.toHaveBeenCalled();
-        });
-        it("localDiverges under keep: pull-kept divergent local cannot silently become write authority", async () => {
-            // After pull --on-conflict keep, journal stamps remoteEtag of the peer
-            // version AND localDiverges=true (local never matched that etag). A later
-            // push must not treat "remote still at stamped etag" as license to PUT
-            // the divergent local body (journal-baseline If-Match would succeed).
+            expect(fs.readFileSync(testFile, "utf-8")).toBe("remote concurrent");
+            expect(fs.readFileSync(sidecarIn(companyRoot), "utf-8")).toBe("local concurrent");
+        });
+        it("localDiverges under keep: a pull-held divergent local yields to cloud without becoming write authority", async () => {
+            // After a pull-side hold (`skip` or pull-leg `publish-local`), the journal
+            // stamps the peer remoteEtag and localDiverges=true because local never
+            // matched that etag. A later push must not treat "remote still at stamped
+            // etag" as license to PUT the divergent local body.
             const companyRoot = path.join(tmpDir, "companies", "acme");
             fs.mkdirSync(companyRoot, { recursive: true });
             const testFile = path.join(companyRoot, "kept-divergent.md");
@@ -1376,8 +1793,12 @@ describe("share", () => {
                 etag: `"${REMOTE}"`,
                 size: 40,
             });
+            vi.mocked(downloadFile).mockImplementationOnce(async (_ctx, _key, dest) => {
+                fs.writeFileSync(dest, "peer remote body");
+                return undefined;
+            });
             const journalPath = path.join(stateDir, "sync-journal.acme.json");
-            fs.writeFileSync(journalPath, JSON.stringify({
+            seedJournalAt(journalPath, ({
                 version: "1",
                 lastSync: new Date().toISOString(),
                 files: {
@@ -1407,7 +1828,10 @@ describe("share", () => {
             expect(events.some((e) => e.type === "conflict" &&
                 e.path === "kept-divergent.md" &&
                 e.resolution === "keep")).toBe(true);
-            expect(fs.readFileSync(testFile, "utf-8")).toBe(localBytes);
+            expect(fs.readFileSync(testFile, "utf-8")).toBe("peer remote body");
+            expect(fs.readFileSync(sidecarIn(companyRoot), "utf-8")).toBe(localBytes);
+            expect(journalAt(journalPath).files["kept-divergent.md"]?.localDiverges)
+                .toBeFalsy();
         });
         it("localDiverges under overwrite: explicit intent may force-write", async () => {
             const companyRoot = path.join(tmpDir, "companies", "acme");
@@ -1423,7 +1847,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 +1874,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-held 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 hold 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 hold
+                        // 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 +2189,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,28 +2219,34 @@ 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",
                 direction: "up",
             });
         });
-        it("deleted journaled remote + concurrent create 412 under keep: existing conflict semantics", async () => {
+        it("deleted journaled remote + concurrent create 412 under keep: adopts the winner and preserves local", async () => {
             // Same setup as recreation, but a peer creates the key between HEAD and
-            // PUT → If-None-Match:* 412s → keep surfaces conflict, no journal stamp.
+            // PUT → If-None-Match:* 412s → keep adopts the peer's winning create.
             const companyRoot = path.join(tmpDir, "companies", "acme");
             fs.mkdirSync(companyRoot, { recursive: true });
             const testFile = path.join(companyRoot, "race-recreate.md");
             fs.writeFileSync(testFile, "my recreated local");
-            vi.mocked(headRemoteFile).mockResolvedValueOnce(null);
+            vi.mocked(headRemoteFile)
+                .mockResolvedValueOnce(null)
+                .mockResolvedValueOnce({
+                lastModified: new Date(),
+                etag: '"peer-created-etag"',
+                size: 18,
+            });
             vi.mocked(uploadFile).mockRejectedValueOnce(fence412());
             vi.mocked(downloadFile).mockImplementationOnce(async (_ctx, _key, dest) => {
                 fs.writeFileSync(dest, "peer created first");
                 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: {
@@ -1548,12 +2276,15 @@ describe("share", () => {
             // First (only) attempt must be create-fenced; no unfenced retry under keep.
             expect(uploadFile).toHaveBeenCalledTimes(1);
             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"));
-            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");
+            // Journal now describes the peer body at the original name.
+            const journal = journalAt(journalPath);
+            expect(journal.files["race-recreate.md"]).toMatchObject({
+                remoteEtag: "peer-created-etag",
+                hash: hashFile(testFile),
+                direction: "down",
+            });
+            expect(fs.readFileSync(testFile, "utf-8")).toBe("peer created first");
+            expect(fs.readFileSync(sidecarIn(companyRoot), "utf-8")).toBe("my recreated local");
         });
     });
     it("scoped push (plan-exceeds-grant): syncs the in-scope subset, skips out-of-scope paths, never aborts (feedback_ded09d56)", async () => {
@@ -1874,7 +2605,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 +2645,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 +2681,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 +2726,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 +2946,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 +3007,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 +3044,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 +3061,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 +3091,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 +3156,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 +3229,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 +3254,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 +3345,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 +3362,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 +3398,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 +3406,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 +3448,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 +3471,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 +3479,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 +3514,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 +3530,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 +3565,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 +3582,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 +3612,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 +3652,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 +3686,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 +3723,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 +3756,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 +3815,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 +3845,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 +3856,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 +3892,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 +3901,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 +3933,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 +3955,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 +3991,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 +4013,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 +4048,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 +4065,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 +4098,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 +4119,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 +4173,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 +4225,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 +4259,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 +4309,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 +4357,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 +4387,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 +4581,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 +4622,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 +4637,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 +4663,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 +4686,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 +4734,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 +4766,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 +4798,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 +4853,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 +4889,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 +5009,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 +5050,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 +5338,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 +5741,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 +5755,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 +5799,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 +5857,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 +5907,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 +5938,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 +5952,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 +5961,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 +6101,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 +6145,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 +6173,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 +6296,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 +6342,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 +6383,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 +6430,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 +6480,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 +6512,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 +6532,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 +6549,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 +7108,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 +7256,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 +7285,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 +7297,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 +7342,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 {