@indigoai-us/hq-cloud 6.15.18 → 6.15.20

package/dist/cli/share.test.js

@@ -1450,6 +1450,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 = JSON.parse(fs.readFileSync(journalPath, "utf-8"));
+            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 = JSON.parse(fs.readFileSync(journalPath, "utf-8"));
+            expect(journal.files["publish-raced.md"].localDiverges).toBe(true);
+            expect(fs.readFileSync(testFile, "utf-8")).toBe(localBytes);
+        });
+        // Codex review (PR #356, P1). The sync runner's push leg always calls
+        // share() with `skipUnchanged: true`, and a pull-kept entry stores the
+        // CURRENT local hash — that is exactly what the journal-honesty stamp
+        // records. So `existing.hash === localHash` is true for every stuck file,
+        // classifyPushCandidates() returns `skip-unchanged`, and executeUploads()
+        // never runs: no HEAD, no conflict, no upload. Without this bypass the
+        // whole recovery is a no-op in the one mode that can reach personal-vault
+        // files, and the next pull leaves them stuck again. `hash === journal hash`
+        // means "local is unchanged since the stamp", NOT "local matches remote" —
+        // for a divergent entry those are different claims.
+        it("localDiverges bypasses the skip-unchanged fast path so the recovery can run at all", async () => {
+            const companyRoot = path.join(tmpDir, "companies", "acme");
+            fs.mkdirSync(companyRoot, { recursive: true });
+            const testFile = path.join(companyRoot, "stuck-under-skip-unchanged.md");
+            const localBytes = "the body a pull-keep stamped and then refused to publish";
+            fs.writeFileSync(testFile, localBytes);
+            const localHash = hashFile(testFile);
+            const REMOTE = "etag-at-keep-time";
+            vi.mocked(headRemoteFile).mockResolvedValueOnce({
+                lastModified: new Date(),
+                etag: `"${REMOTE}"`,
+                size: 40,
+            });
+            vi.mocked(uploadFile).mockResolvedValueOnce({ etag: '"published-etag"' });
+            const journalPath = path.join(stateDir, "sync-journal.acme.json");
+            fs.writeFileSync(journalPath, JSON.stringify({
+                version: "1",
+                lastSync: new Date().toISOString(),
+                files: {
+                    "stuck-under-skip-unchanged.md": {
+                        // Deliberately the CURRENT local hash: this is what a pull-keep
+                        // writes, and it is what makes the fast path swallow the file.
+                        hash: localHash,
+                        size: localBytes.length,
+                        syncedAt: new Date().toISOString(),
+                        direction: "down",
+                        remoteEtag: REMOTE,
+                        localDiverges: true,
+                    },
+                },
+            }));
+            const result = await share({
+                paths: [testFile],
+                company: "acme",
+                vaultConfig: mockConfig,
+                hqRoot: tmpDir,
+                skipUnchanged: true,
+                onConflict: "publish-local",
+            });
+            expect(result.filesUploaded).toBe(1);
+            expect(vi.mocked(uploadFile).mock.calls[0][4]).toEqual({ ifMatch: REMOTE });
+            const journal = JSON.parse(fs.readFileSync(journalPath, "utf-8"));
+            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 = JSON.parse(fs.readFileSync(journalPath, "utf-8"));
+            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
@@ -5598,45 +5896,41 @@ describe("currency-gated: journal version 2 fixtures", () => {
         expect(result.filesDeleted).toBe(1);
         expect(deleteRemoteFile).toHaveBeenCalledWith(expect.anything(), "core/policies/old.md");
     });
-    // ── Fix #1 (5.36.0): lstat fast-path ─────────────────────────────────────
-    //
-    // When skipUnchanged is on AND the journal carries an mtimeMs for the
-    // file AND (lstat.size, lstat.mtimeMs) match the recorded values, the
-    // push planner classifies the file `unchanged` WITHOUT reading its
-    // bytes. Same trade-off rsync/gitignore use; turns no-op syncs from
-    // O(file bytes) into O(file count).
-    //
-    // We prove "the SHA256 path didn't run" by seeding the journal with an
-    // intentionally WRONG hash but matching mtimeMs+size. If the fast-path
-    // fires → file is classified `unchanged` purely on lstat (no hash
-    // compare). If the fast-path is skipped → hashFile runs, hashes the
-    // real file, fails the !== journal-hash check, and uploads. The
-    // upload-vs-skip outcome is the diagnostic signal.
-    describe("lstat fast-path (5.36.0)", () => {
-        it("skips upload when mtimeMs + size match journal (even with wrong stored hash)", async () => {
+    // ── Regular-file content identity ─────────────────────────────────────────
+    describe("regular-file content identity", () => {
+        it("uploads a same-size edit whose mtime matches the journal", async () => {
             const companyRoot = path.join(tmpDir, "companies", "acme");
             fs.mkdirSync(companyRoot, { recursive: true });
             const testFile = path.join(companyRoot, "stable.md");
             fs.writeFileSync(testFile, "stable bytes");
-            const lstat = fs.lstatSync(testFile);
-            // Intentionally-wrong hash; matching mtimeMs+size. If the fast-path
-            // doesn't fire, hashFile runs, the real hash != "sentinel-wrong-hash",
-            // and the file gets uploaded — which would fail this test.
+            const preservedMtime = new Date("2026-01-02T03:04:05.000Z");
+            fs.utimesSync(testFile, preservedMtime, preservedMtime);
+            const baselineLstat = fs.lstatSync(testFile);
+            const { hashFile } = await import("../journal.js");
+            const baselineHash = hashFile(testFile);
             const journalPath = path.join(stateDir, "sync-journal.acme.json");
             fs.writeFileSync(journalPath, JSON.stringify({
                 version: "2",
                 lastSync: new Date().toISOString(),
                 files: {
                     "stable.md": {
-                        hash: "sentinel-wrong-hash-fast-path-should-skip-without-checking",
-                        size: lstat.size,
-                        mtimeMs: lstat.mtimeMs,
+                        hash: baselineHash,
+                        size: baselineLstat.size,
+                        mtimeMs: baselineLstat.mtimeMs,
                         syncedAt: new Date().toISOString(),
                         direction: "up",
                     },
                 },
                 pulls: [],
             }));
+            // Rewrite the bytes without changing either cheap stat signal. A planner
+            // that treats (size, mtimeMs) as content identity will skip this forever.
+            fs.writeFileSync(testFile, "edited bytes");
+            fs.utimesSync(testFile, preservedMtime, preservedMtime);
+            const editedLstat = fs.lstatSync(testFile);
+            expect(editedLstat.size).toBe(baselineLstat.size);
+            expect(editedLstat.mtimeMs).toBe(baselineLstat.mtimeMs);
+            expect(hashFile(testFile)).not.toBe(baselineHash);
             const result = await share({
                 paths: [testFile],
                 company: "acme",
@@ -5644,21 +5938,17 @@ describe("currency-gated: journal version 2 fixtures", () => {
                 hqRoot: tmpDir,
                 skipUnchanged: true,
             });
-            // Fast-path fired → no hash read → no upload despite wrong stored hash.
-            expect(result.filesUploaded).toBe(0);
-            expect(result.filesSkipped).toBe(1);
-            expect(uploadFile).not.toHaveBeenCalled();
+            expect(result.filesUploaded).toBe(1);
+            expect(result.filesSkipped).toBe(0);
+            expect(uploadFile).toHaveBeenCalled();
         });
-        it("uploads when mtime changes (fast-path misses → hash runs → mismatch)", async () => {
+        it("uploads when the content hash differs after an mtime change", async () => {
             const companyRoot = path.join(tmpDir, "companies", "acme");
             fs.mkdirSync(companyRoot, { recursive: true });
             const testFile = path.join(companyRoot, "touched.md");
             fs.writeFileSync(testFile, "original bytes!");
             const originalLstat = fs.lstatSync(testFile);
-            // Wrong hash + matching mtimeMs+size — would skip via fast-path if
-            // mtime stayed the same. We're about to bump mtime, so fast-path
-            // MUST miss, hashFile MUST run, hash MUST mismatch the wrong stored
-            // value, and the file MUST upload.
+            // The recorded hash intentionally differs from the current bytes.
             const journalPath = path.join(stateDir, "sync-journal.acme.json");
             fs.writeFileSync(journalPath, JSON.stringify({
                 version: "2",
@@ -5674,7 +5964,7 @@ describe("currency-gated: journal version 2 fixtures", () => {
                 },
                 pulls: [],
             }));
-            // Bump mtime forward — fast-path comparison mtime fails.
+            // Bump mtime forward; content hashing remains the source of truth.
             const futureTime = new Date(Date.now() + 60_000);
             fs.utimesSync(testFile, futureTime, futureTime);
             const result = await share({
@@ -5684,8 +5974,6 @@ describe("currency-gated: journal version 2 fixtures", () => {
                 hqRoot: tmpDir,
                 skipUnchanged: true,
             });
-            // Fast-path missed → second-stage hash compare ran → wrong stored hash
-            // forced the upload.
             expect(result.filesUploaded).toBe(1);
             expect(uploadFile).toHaveBeenCalled();
         });
@@ -5693,13 +5981,11 @@ describe("currency-gated: journal version 2 fixtures", () => {
         // create a conflict/drift file." This is the push-side complement of the
         // pull-side reconcile test (sync.test.ts "byte-identical ... no litter").
         //
-        // A pure `touch` (bytes identical, mtime bumped) MUST miss the lstat
-        // fast-path (mtime != stored mtimeMs), fall through to hashFile, hit the
-        // second-stage hash compare (real hash === CORRECT stored hash), and
+        // A pure `touch` (bytes identical, mtime bumped) MUST hash the bytes,
+        // compare the real hash with the correct stored hash, and
         // classify the file `unchanged`. No upload, no conflict event, and no
         // `.conflict-*`/`.drift-*` mirror on disk — mtime alone never manufactures
-        // divergence. (3722 above proves the fast-path MISSES on an mtime bump;
-        // this proves a CORRECT stored hash then reconciles instead of uploading.)
+        // divergence.
         it("mtime bumped but bytes identical → re-hash reconciles → no upload, no conflict, no mirror", async () => {
             const companyRoot = path.join(tmpDir, "companies", "acme");
             fs.mkdirSync(companyRoot, { recursive: true });
@@ -5707,8 +5993,7 @@ describe("currency-gated: journal version 2 fixtures", () => {
             fs.writeFileSync(testFile, "identical bytes, only mtime moves");
             const originalLstat = fs.lstatSync(testFile);
             // CORRECT stored hash (unlike 3722's sentinel) + matching size. Once the
-            // mtime bump forces hashFile to run, the real hash MUST equal this value
-            // and the second-stage compare MUST classify the file unchanged.
+            // The real hash MUST equal this value and classify the file unchanged.
             const { hashFile } = await import("../journal.js");
             const realHash = hashFile(testFile);
             const journalPath = path.join(stateDir, "sync-journal.acme.json");
@@ -5726,7 +6011,7 @@ describe("currency-gated: journal version 2 fixtures", () => {
                 },
                 pulls: [],
             }));
-            // Bump mtime forward only — bytes untouched. Fast-path mtime compare fails.
+            // Bump mtime forward only — bytes untouched.
             const futureTime = new Date(Date.now() + 60_000);
             fs.utimesSync(testFile, futureTime, futureTime);
             const events = [];
@@ -5738,7 +6023,7 @@ describe("currency-gated: journal version 2 fixtures", () => {
                 skipUnchanged: true,
                 onEvent: (e) => events.push(e),
             });
-            // Fast-path missed (mtime moved), hash ran, hash matched → reconciled.
+            // Hash matched → reconciled.
             expect(result.filesUploaded).toBe(0);
             expect(result.filesSkipped).toBe(1);
             expect(uploadFile).not.toHaveBeenCalled();
@@ -5751,12 +6036,9 @@ describe("currency-gated: journal version 2 fixtures", () => {
                 .filter((f) => f.includes(".conflict-") || f.includes(".drift-"));
             expect(litter).toEqual([]);
         });
-        // Efficiency follow-up to the directive lock above: a touched-but-identical
-        // file currently re-hashes on EVERY sync because the no-op skip never
-        // refreshes the journal's (mtimeMs, size). Re-stamp them on the skip so the
-        // NEXT sync short-circuits on lstat alone. Pure performance — still no
-        // upload, no conflict, no mirror.
-        it("re-stamps journal mtimeMs after a no-op skip so the next sync hits the fast-path", async () => {
+        // Keep stat metadata current after a touched-but-identical no-op. Content
+        // identity still comes exclusively from the hash.
+        it("re-stamps journal mtimeMs after a no-op hash match", async () => {
             const companyRoot = path.join(tmpDir, "companies", "acme");
             fs.mkdirSync(companyRoot, { recursive: true });
             const testFile = path.join(companyRoot, "touched-then-fast.md");
@@ -5779,7 +6061,7 @@ describe("currency-gated: journal version 2 fixtures", () => {
                 },
                 pulls: [],
             }));
-            // Bump mtime — fast-path misses, hash runs, hash matches → no-op skip.
+            // Bump mtime — hash still matches, so this is a no-op skip.
             const futureTime = new Date(Date.now() + 120_000);
             fs.utimesSync(testFile, futureTime, futureTime);
             const bumpedLstat = fs.lstatSync(testFile);
@@ -5795,8 +6077,8 @@ describe("currency-gated: journal version 2 fixtures", () => {
             expect(result.filesUploaded).toBe(0);
             expect(result.filesSkipped).toBe(1);
             expect(uploadFile).not.toHaveBeenCalled();
-            // Journal mtimeMs is now the BUMPED value (not the stale original), so the
-            // next sync's lstat fast-path matches and skips without re-hashing.
+            // 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"));
             expect(journalAfter.files["touched-then-fast.md"].mtimeMs).toBe(bumpedLstat.mtimeMs);
             expect(journalAfter.files["touched-then-fast.md"].size).toBe(bumpedLstat.size);
@@ -5822,11 +6104,9 @@ describe("currency-gated: journal version 2 fixtures", () => {
             expect(journal.files["fresh.md"].mtimeMs).toBe(lstat.mtimeMs);
             expect(journal.files["fresh.md"].size).toBe(lstat.size);
         });
-        it("falls through to hashFile when journal has no mtimeMs (pre-5.36 entry)", async () => {
-            // Back-compat: pre-5.36 journals don't carry mtimeMs. The first sync
-            // after upgrade must fall through to the hash path so legacy entries
-            // still work; the post-upload stamp adds the field so subsequent
-            // syncs use the fast-path.
+        it("hashes content when the journal has no mtimeMs (pre-5.36 entry)", async () => {
+            // Back-compat: pre-5.36 journals don't carry mtimeMs, but the content
+            // hash still decides whether the file is unchanged.
             const companyRoot = path.join(tmpDir, "companies", "acme");
             fs.mkdirSync(companyRoot, { recursive: true });
             const testFile = path.join(companyRoot, "legacy.md");
@@ -5834,8 +6114,7 @@ describe("currency-gated: journal version 2 fixtures", () => {
             const { hashFile: realHashFile } = await import("../journal.js");
             const realHash = realHashFile(testFile);
             const realSize = fs.statSync(testFile).size;
-            // Real hash but NO mtimeMs — must take hash path. Hash matches →
-            // second-stage compare skips upload.
+            // Real hash but NO mtimeMs. Hash matches → skip upload.
             const journalPath = path.join(stateDir, "sync-journal.acme.json");
             fs.writeFileSync(journalPath, JSON.stringify({
                 version: "1",
@@ -5857,13 +6136,11 @@ describe("currency-gated: journal version 2 fixtures", () => {
                 hqRoot: tmpDir,
                 skipUnchanged: true,
             });
-            // Pre-5.36 entry → fast-path skipped → hash path ran → real hash
-            // matched → upload skipped at second stage. Same outcome as 5.35.0.
+            // Real hash matched → upload skipped.
             expect(result.filesSkipped).toBe(1);
             expect(uploadFile).not.toHaveBeenCalled();
-            // And the upgrade path: a follow-up upload (forced by changing the
-            // file) must stamp mtimeMs so the NEXT sync gets the fast-path.
-            // Verified separately by the "stamps mtimeMs" test above.
+            // A follow-up upload still stamps mtimeMs for journal compatibility,
+            // verified separately by the "stamps mtimeMs" test above.
         });
     });
     // ── Fix #2 (5.36.0): bounded-parallel transfer pool ──────────────────────
@@ -6395,7 +6672,7 @@ describe("currency-gated: journal version 2 fixtures", () => {
             // entries for the 9 successful uploads. Pre-fix the journal was
             // never written (the throw escaped before writeJournal()), so
             // the next sync re-uploaded all 9 successful files unnecessarily
-            // AND lost the etag/mtime stamps needed by the lstat fast-path.
+            // 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"));