@indigoai-us/hq-cloud 5.23.0 → 5.24.0

package/src/cli/share.test.ts

@@ -23,7 +23,7 @@ vi.mock("../s3.js", () => ({
   headRemoteFile: vi.fn().mockResolvedValue(null),
 }));
 
-import { share } from "./share.js";
+import { share, _testing as shareTesting } from "./share.js";
 import { deleteRemoteFile, headRemoteFile, uploadFile, uploadSymlink } from "../s3.js";
 import type { EntityContext } from "../types.js";
 
@@ -915,6 +915,10 @@ describe("share", () => {
       hqRoot: tmpDir,
       skipUnchanged: true,
       propagateDeletes: true,
+      // Pin owned-only — this test predates the currency-gated default and
+      // asserts the direction-of-origin branch. A separate currency-gated
+      // test covers the new default semantics for the same scenario.
+      propagateDeletePolicy: "owned-only",
     });
 
     expect(result.filesDeleted).toBe(1);
@@ -965,6 +969,9 @@ describe("share", () => {
       hqRoot: tmpDir,
       skipUnchanged: true,
       propagateDeletes: true,
+      // Owned-only — predates currency-gated default; asserts the lstat
+      // guard which is independent of the policy branch.
+      propagateDeletePolicy: "owned-only",
     });
 
     expect(result.filesDeleted).toBe(0);
@@ -1013,6 +1020,8 @@ describe("share", () => {
       hqRoot: tmpDir,
       skipUnchanged: true,
       propagateDeletes: true,
+      // Owned-only — currency-gated semantics covered separately below.
+      propagateDeletePolicy: "owned-only",
     });
 
     expect(result.filesDeleted).toBe(1);
@@ -1054,6 +1063,9 @@ describe("share", () => {
       hqRoot: tmpDir,
       skipUnchanged: true,
       propagateDeletes: true,
+      // Owned-only — currency-gated emits a separate event variant; this test
+      // pins the legacy progress-with-deleted-flag shape.
+      propagateDeletePolicy: "owned-only",
       onEvent: (e) => events.push(e as { type: string }),
     });
 
@@ -1143,6 +1155,9 @@ describe("share", () => {
       hqRoot: tmpDir,
       skipUnchanged: true,
       propagateDeletes: true,
+      // Owned-only — this test asserts scope containment, independent of
+      // the policy branch. Currency-gated covered separately.
+      propagateDeletePolicy: "owned-only",
     });
 
     expect(result.filesDeleted).toBe(1);
@@ -1190,6 +1205,9 @@ describe("share", () => {
       hqRoot: tmpDir,
       skipUnchanged: true,
       propagateDeletes: true,
+      // Owned-only — pinning so the retry-survival assertion is independent
+      // of currency-gated's HEAD-driven bucketing.
+      propagateDeletePolicy: "owned-only",
       onEvent: (e) => events.push(e as { type: string }),
     });
 
@@ -1227,7 +1245,7 @@ describe("share", () => {
   //   (i)  `direction === "up"` requirement under the default policy.
   //   (ii) `shouldSync` must accept the key — same filter the pull uses.
 
-  it("propagateDeletes: under owned-only (default), skips direction:'down' entries", async () => {
+  it("propagateDeletes: under owned-only (legacy pre-5.24 default), skips direction:'down' entries", async () => {
     const companyRoot = path.join(tmpDir, "companies", "acme");
     fs.mkdirSync(companyRoot, { recursive: true });
     // No local files. One journal entry pulled from elsewhere (direction:'down')
@@ -1259,7 +1277,8 @@ describe("share", () => {
       hqRoot: tmpDir,
       skipUnchanged: true,
       propagateDeletes: true,
-      // propagateDeletePolicy omitted ⇒ defaults to "owned-only".
+      // Explicit opt-in — `currency-gated` is the new (5.24+) default.
+      propagateDeletePolicy: "owned-only",
     });
 
     // Only the 'up' entry is deleted; the 'down' entry is left alone so a
@@ -1338,6 +1357,10 @@ describe("share", () => {
       hqRoot: tmpDir,
       skipUnchanged: true,
       propagateDeletes: true,
+      // Owned-only — filter symmetry is policy-independent; pinning so the
+      // legacy direction-of-origin gate (not currency-gated's HEAD path)
+      // resolves the "delete vs skip" decision for active/current.md.
+      propagateDeletePolicy: "owned-only",
     });
 
     // legacy/old-layout.md is filter-skipped; only active/current.md is
@@ -1347,6 +1370,420 @@ describe("share", () => {
     expect(deleteRemoteFile).not.toHaveBeenCalledWith(expect.anything(), "legacy/old-layout.md");
   });
 
+  // ── Delete propagation: currency-gated policy (5.24+ default) ──────────────
+  //
+  // The pre-5.24 `owned-only` default refused to delete-propagate any journal
+  // entry whose `direction !== "up"`. That made sense as a safety net against
+  // a behind machine's first push erasing peer uploads — but it had a worse
+  // failure mode in practice: every `/update-hq` writes `core/`, `.claude/`,
+  // `.codex/` with `direction: "down"` (they came from upstream), so any
+  // subsequent local delete during a cleanup or upgrade was silently dropped.
+  // Net effect: remote vault accumulated permanent litter the user could not
+  // clean up without manually invoking `policy: "all"` (which has its own
+  // safety problems).
+  //
+  // `currency-gated` solves this by gating on per-file proof of currency: HEAD
+  // the remote, compare ETag, only propagate when this device has the
+  // latest version. Direction-of-origin becomes irrelevant — a file the
+  // upstream `/update-hq` wrote can be cleanly deleted by the device that
+  // wrote it, as long as no other device modified it in the meantime.
+
+  it("currency-gated: propagates delete when remote ETag matches journal", async () => {
+    const companyRoot = path.join(tmpDir, "companies", "acme");
+    fs.mkdirSync(companyRoot, { recursive: true });
+    // direction:"down" file (e.g. arrived via /update-hq), locally deleted.
+    // 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({
+        version: "1",
+        lastSync: new Date().toISOString(),
+        files: {
+          "core/policies/old.md": {
+            hash: "h", size: 100, syncedAt: new Date().toISOString(),
+            direction: "down",
+            remoteEtag: "abc123",
+          },
+        },
+      }),
+    );
+
+    // HEAD returns the same etag — this device is current for the file.
+    vi.mocked(headRemoteFile).mockResolvedValueOnce({
+      lastModified: new Date(),
+      etag: '"abc123"',
+      size: 100,
+    });
+
+    const result = await share({
+      paths: [companyRoot],
+      company: "acme",
+      vaultConfig: mockConfig,
+      hqRoot: tmpDir,
+      skipUnchanged: true,
+      propagateDeletes: true,
+      propagateDeletePolicy: "currency-gated",
+    });
+
+    expect(result.filesDeleted).toBe(1);
+    expect(deleteRemoteFile).toHaveBeenCalledWith(
+      expect.anything(),
+      "core/policies/old.md",
+    );
+    const journal = JSON.parse(fs.readFileSync(journalPath, "utf-8"));
+    expect(journal.files["core/policies/old.md"]).toBeUndefined();
+  });
+
+  it("currency-gated: refuses delete + emits stale-etag event when remote moved since last sync", async () => {
+    const companyRoot = path.join(tmpDir, "companies", "acme");
+    fs.mkdirSync(companyRoot, { recursive: true });
+    // 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({
+        version: "1",
+        lastSync: new Date().toISOString(),
+        files: {
+          "shared.md": {
+            hash: "h", size: 50, syncedAt: new Date().toISOString(),
+            direction: "down",
+            remoteEtag: "stale-etag",
+          },
+        },
+      }),
+    );
+
+    vi.mocked(headRemoteFile).mockResolvedValueOnce({
+      lastModified: new Date(),
+      etag: '"fresh-etag"',
+      size: 51,
+    });
+
+    const events: Array<{ type: string; path?: string; journalEtag?: string; remoteEtag?: string }> = [];
+    const result = await share({
+      paths: [companyRoot],
+      company: "acme",
+      vaultConfig: mockConfig,
+      hqRoot: tmpDir,
+      skipUnchanged: true,
+      propagateDeletes: true,
+      propagateDeletePolicy: "currency-gated",
+      onEvent: (e) => events.push(e as { type: string }),
+    });
+
+    // 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"));
+    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
+    // consumers don't have to string-compare placeholder etag values.
+    const refusedEvent = events.find((e) => e.type === "delete-refused-stale-etag");
+    expect(refusedEvent).toMatchObject({
+      type: "delete-refused-stale-etag",
+      path: "shared.md",
+      journalEtag: "stale-etag",
+      remoteEtag: "fresh-etag",
+      reason: "stale-etag",
+    });
+    // Counter exposed on ShareResult so callers don't need to re-count events.
+    expect(result.filesRefusedStale).toBe(1);
+    expect(result.filesTombstoned).toBe(0);
+  });
+
+  it("currency-gated: tombstones journal entry when remote returns 404 (out-of-band cleanup)", async () => {
+    const companyRoot = path.join(tmpDir, "companies", "acme");
+    fs.mkdirSync(companyRoot, { recursive: true });
+    // Remote file was deleted out-of-band (e.g. someone removed it via the
+    // 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({
+        version: "1",
+        lastSync: new Date().toISOString(),
+        files: {
+          "removed-out-of-band.md": {
+            hash: "h", size: 25, syncedAt: new Date().toISOString(),
+            direction: "down",
+            remoteEtag: "doesnt-matter",
+          },
+        },
+      }),
+    );
+
+    vi.mocked(headRemoteFile).mockResolvedValueOnce(null);
+
+    const events: Array<{ type: string; path?: string; deleted?: boolean; message?: string; bytes?: number }> = [];
+    const result = await share({
+      paths: [companyRoot],
+      company: "acme",
+      vaultConfig: mockConfig,
+      hqRoot: tmpDir,
+      skipUnchanged: true,
+      propagateDeletes: true,
+      propagateDeletePolicy: "currency-gated",
+      onEvent: (e) => events.push(e as { type: string }),
+    });
+
+    // No DeleteObject (remote was already gone), but journal converges.
+    expect(deleteRemoteFile).not.toHaveBeenCalled();
+    // filesDeleted counts actual S3 deletes; tombstones aren't counted here.
+    expect(result.filesDeleted).toBe(0);
+    // Tombstones have their own counter so callers can distinguish them
+    // 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"));
+    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
+    // can't tell from logs alone that no S3 call was issued.
+    const tombstoneEvent = events.find(
+      (e) => e.type === "progress" && e.deleted === true && e.message?.includes("tombstone"),
+    );
+    expect(tombstoneEvent).toMatchObject({
+      type: "progress",
+      path: "removed-out-of-band.md",
+      bytes: 0,
+      deleted: true,
+      message: expect.stringContaining("tombstone"),
+    });
+  });
+
+  it("currency-gated: refuses delete for legacy journal entry with no recorded remoteEtag", async () => {
+    const companyRoot = path.join(tmpDir, "companies", "acme");
+    fs.mkdirSync(companyRoot, { recursive: true });
+    // Journal entry from before remoteEtag tracking — no etag to compare
+    // 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({
+        version: "1",
+        lastSync: new Date().toISOString(),
+        files: {
+          "legacy-no-etag.md": {
+            hash: "h", size: 5, syncedAt: new Date().toISOString(),
+            direction: "down",
+            // No remoteEtag.
+          },
+        },
+      }),
+    );
+
+    const events: Array<{ type: string; journalEtag?: string }> = [];
+    const result = await share({
+      paths: [companyRoot],
+      company: "acme",
+      vaultConfig: mockConfig,
+      hqRoot: tmpDir,
+      skipUnchanged: true,
+      propagateDeletes: true,
+      propagateDeletePolicy: "currency-gated",
+      onEvent: (e) => events.push(e as { type: string }),
+    });
+
+    expect(result.filesDeleted).toBe(0);
+    expect(deleteRemoteFile).not.toHaveBeenCalled();
+    // HEAD must NOT be called — we short-circuit on the missing journal etag.
+    expect(headRemoteFile).not.toHaveBeenCalled();
+    const refused = events.find((e) => e.type === "delete-refused-stale-etag");
+    expect(refused).toMatchObject({
+      journalEtag: "<legacy-no-etag>",
+      reason: "legacy-no-etag",
+    });
+    expect(result.filesRefusedStale).toBe(1);
+  });
+
+  it("currency-gated: real-world /update-hq scenario — direction:'down' delete propagates when current", async () => {
+    // Regression for the exact bug that motivated the 5.24 default flip:
+    // every `/update-hq` writes core/.claude/.codex from upstream and
+    // journals them as direction:"down". When the user later moves or
+    // deletes one locally (e.g. during cleanup, dir-restructure, or the
+    // next upgrade), pre-5.24 `owned-only` silently kept it on remote
+    // forever. Currency-gated propagates the delete cleanly as long as
+    // this device is current for the file.
+    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({
+        version: "1",
+        lastSync: new Date().toISOString(),
+        files: {
+          ".claude/commands/retired-command.md": {
+            hash: "h", size: 200, syncedAt: new Date().toISOString(),
+            direction: "down",
+            remoteEtag: "upstream-etag",
+          },
+        },
+      }),
+    );
+
+    vi.mocked(headRemoteFile).mockResolvedValueOnce({
+      lastModified: new Date(),
+      etag: '"upstream-etag"',
+      size: 200,
+    });
+
+    const result = await share({
+      paths: [companyRoot],
+      company: "acme",
+      vaultConfig: mockConfig,
+      hqRoot: tmpDir,
+      skipUnchanged: true,
+      propagateDeletes: true,
+      // Explicit opt-in. 5.24 ships the currency-gated CODE PATH but keeps
+      // `owned-only` as the default while it soaks; the default flips to
+      // `currency-gated` in 5.25. This test pins the user-facing semantics
+      // (the /update-hq delete-propagation bug) under the new policy
+      // regardless of which default the surrounding release ships.
+      propagateDeletePolicy: "currency-gated",
+    });
+
+    expect(result.filesDeleted).toBe(1);
+    expect(deleteRemoteFile).toHaveBeenCalledWith(
+      expect.anything(),
+      ".claude/commands/retired-command.md",
+    );
+  });
+
+  // ── Conflict-mirror exclusion (ephemeral pattern) ──────────────────────────
+  //
+  // Conflict mirrors (`*.conflict-<ISO>-<machineHash>.<ext>`) are local-only
+  // safety backups written by the pull leg whenever a 3-way merge keeps
+  // local and wants to preserve the remote version for inspection. They
+  // MUST never round-trip to S3. Pre-fix, the push walker uploaded them,
+  // the journal tracked them, and the owned-only delete policy then refused
+  // to clean them up — permanent ratchet of remote litter.
+
+  it("conflict-mirror exclusion: push walker skips local conflict-mirror files", async () => {
+    const companyRoot = path.join(tmpDir, "companies", "acme");
+    fs.mkdirSync(path.join(companyRoot, "skills"), { recursive: true });
+    // Two files: a normal one and a conflict mirror. Only the normal one
+    // should reach S3; the mirror is local-only state.
+    fs.writeFileSync(
+      path.join(companyRoot, "skills", "real.md"),
+      "real content",
+    );
+    fs.writeFileSync(
+      path.join(companyRoot, "skills", "real.md.conflict-2026-05-13T19-40-40Z-e5797a.md"),
+      "conflict mirror content",
+    );
+
+    await share({
+      paths: [companyRoot],
+      company: "acme",
+      vaultConfig: mockConfig,
+      hqRoot: tmpDir,
+      skipUnchanged: true,
+    });
+
+    expect(uploadFile).toHaveBeenCalledTimes(1);
+    expect(uploadFile).toHaveBeenCalledWith(
+      expect.anything(),
+      expect.stringContaining("real.md"),
+      "skills/real.md",
+    );
+    // Spy was called once total — the conflict mirror never reaches uploadFile.
+    // (Asserted by count above; the explicit non-call below is defensive.)
+    const calls = vi.mocked(uploadFile).mock.calls;
+    expect(calls.every((c) => !String(c[1] ?? "").includes("conflict-"))).toBe(true);
+  });
+
+  it("conflict-mirror exclusion: explicit user-supplied conflict-mirror path is also refused", async () => {
+    const companyRoot = path.join(tmpDir, "companies", "acme");
+    fs.mkdirSync(companyRoot, { recursive: true });
+    const mirrorPath = path.join(
+      companyRoot,
+      "CLAUDE.md.conflict-2026-05-13T19-40-40Z-e5797a.md",
+    );
+    fs.writeFileSync(mirrorPath, "mirror content");
+
+    await share({
+      paths: [mirrorPath],
+      company: "acme",
+      vaultConfig: mockConfig,
+      hqRoot: tmpDir,
+      skipUnchanged: true,
+    });
+
+    // Explicit caller path matching the ephemeral pattern is filtered the
+    // same as a walker-discovered one. Belt-and-suspenders against any
+    // tooling that hands a conflict mirror to share() directly.
+    expect(uploadFile).not.toHaveBeenCalled();
+  });
+
+  it("conflict-mirror exclusion: journaled mirror with local-missing is NOT swept by delete plan", async () => {
+    const companyRoot = path.join(tmpDir, "companies", "acme");
+    fs.mkdirSync(companyRoot, { recursive: true });
+    // Simulate the existing-litter state: a conflict mirror that leaked
+    // into the journal in a prior buggy version. Locally missing (user
+    // already deleted it). The regular delete plan must NOT issue a
+    // DeleteObject — that's the dedicated reconcile command's job, and
+    // a sync should not accidentally race a user reviewing the mirror.
+    const journalPath = path.join(stateDir, "sync-journal.acme.json");
+    fs.writeFileSync(
+      journalPath,
+      JSON.stringify({
+        version: "1",
+        lastSync: new Date().toISOString(),
+        files: {
+          "CLAUDE.md.conflict-2026-05-13T19-40-40Z-e5797a.md": {
+            hash: "h", size: 10, syncedAt: new Date().toISOString(),
+            direction: "up",
+            remoteEtag: "mirror-etag",
+          },
+          "regular.md": {
+            hash: "h", size: 5, syncedAt: new Date().toISOString(),
+            direction: "up",
+            remoteEtag: "regular-etag",
+          },
+        },
+      }),
+    );
+
+    // HEAD needed for the non-mirror entry under currency-gated.
+    vi.mocked(headRemoteFile).mockResolvedValue({
+      lastModified: new Date(),
+      etag: '"regular-etag"',
+      size: 5,
+    });
+
+    const result = await share({
+      paths: [companyRoot],
+      company: "acme",
+      vaultConfig: mockConfig,
+      hqRoot: tmpDir,
+      skipUnchanged: true,
+      propagateDeletes: true,
+    });
+
+    expect(result.filesDeleted).toBe(1);
+    expect(deleteRemoteFile).toHaveBeenCalledTimes(1);
+    expect(deleteRemoteFile).toHaveBeenCalledWith(expect.anything(), "regular.md");
+    expect(deleteRemoteFile).not.toHaveBeenCalledWith(
+      expect.anything(),
+      expect.stringContaining("conflict-"),
+    );
+    // Mirror's journal entry survives — reconcile command (separate skill)
+    // sweeps it once the user explicitly opts in.
+    const journal = JSON.parse(fs.readFileSync(journalPath, "utf-8"));
+    expect(
+      journal.files["CLAUDE.md.conflict-2026-05-13T19-40-40Z-e5797a.md"],
+    ).toBeDefined();
+  });
+
   // ── personalMode ───────────────────────────────────────────────────────────
   //
   // The personal vault (slug "personal" in the runner's fanout plan) shares
@@ -1748,3 +2185,140 @@ describe("share", () => {
     });
   });
 });
+
+// ── Pure-function unit coverage: isEphemeralPath ─────────────────────────────
+//
+// EPHEMERAL_PATH_PATTERN is the single source of truth for "this is a conflict
+// mirror and must never round-trip to S3." Integration tests already cover the
+// behavior end-to-end (uploadFile is or isn't called), but a direct regex
+// contract test makes intent unambiguous and catches future drift in the
+// pattern — much cheaper than reproducing each case through share().
+
+describe("isEphemeralPath (conflict-mirror pattern contract)", () => {
+  const { isEphemeralPath } = shareTesting;
+
+  it.each([
+    // Canonical: basename and relativeKey both match (the two callsites).
+    [".claude/CLAUDE.md.conflict-2026-05-13T19-40-40Z-e5797a.md", true],
+    ["CLAUDE.md.conflict-2026-05-13T19-40-40Z-e5797a.md", true],
+    [".claude/commands/adr.md.conflict-2026-05-13T19-40-41Z-e5797a.md", true],
+    // Longer machine hash (no upper bound on `[a-f0-9]+`).
+    ["foo.conflict-2026-05-19T17-05-56Z-deadbeef.md", true],
+    // Non-markdown extensions also valid (sh scripts, ts files, etc.).
+    ["foo.sh.conflict-2026-05-19T17-05-56Z-abc123.sh", true],
+  ])("matches conflict mirror: %s", (p, expected) => {
+    expect(isEphemeralPath(p)).toBe(expected);
+  });
+
+  it.each([
+    // Normal files: regular markdown, scripts, etc.
+    ["README.md", false],
+    [".claude/CLAUDE.md", false],
+    ["companies/acme/knowledge/note.md", false],
+    // Strings containing the word "conflict" but not the timestamp+hash token.
+    ["conflict-resolution.md", false],
+    ["my-conflict.md", false],
+    ["foo.conflict-handler.md", false],
+    // Date-shaped but missing the trailing dot + extension (real conflicts
+    // always carry a file extension; the trailing `\.` in the pattern is the
+    // safety against bare-substring false positives).
+    ["foo.conflict-2026-05-13T19-40-40Z-abc", false],
+    // Wrong-case or non-hex machine hash.
+    ["foo.conflict-2026-05-13T19-40-40Z-ZZZZZZ.md", false],
+    // Wrong timestamp format (real conflicts use UTC ISO with Z suffix).
+    ["foo.conflict-2026-05-13-abc123.md", false],
+    // Missing leading dot before "conflict" (this protects against legitimate
+    // files that happen to contain the word "conflict" mid-name).
+    ["fooconflict-2026-05-13T19-40-40Z-abc.md", false],
+  ])("rejects non-mirror: %s", (p, expected) => {
+    expect(isEphemeralPath(p)).toBe(expected);
+  });
+});
+
+// ── Currency-gated coverage against journal version "2" fixtures ─────────────
+//
+// Production journals on disk are at `version: "2"` (verified via jq on the
+// real-world ~/.hq/sync-journal.personal.json). The currency-gated tests above
+// use v1 fixtures by historical convention — this block pins the behavior at
+// v2 explicitly so a future schema change can't silently strand the new policy
+// on a stale fixture format. The bucket logic ignores `version` (only reads
+// `journal.files[*]`), so this should pass identically — but we want the
+// regression test on record.
+
+describe("currency-gated: journal version 2 fixtures", () => {
+  let tmpDir: string;
+  let stateDir: string;
+  let origDataHome: string | undefined;
+
+  beforeEach(() => {
+    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "hq-share-test-v2-"));
+    stateDir = path.join(tmpDir, ".hq");
+    fs.mkdirSync(stateDir, { recursive: true });
+    origDataHome = process.env.XDG_DATA_HOME;
+    process.env.XDG_DATA_HOME = stateDir;
+    process.env.HQ_STATE_DIR = stateDir;
+    clearContextCache();
+    setupFetchMock();
+    vi.mocked(uploadFile).mockClear();
+    vi.mocked(uploadSymlink).mockClear();
+    vi.mocked(deleteRemoteFile).mockClear();
+    vi.mocked(headRemoteFile).mockReset();
+    vi.mocked(headRemoteFile).mockResolvedValue(null);
+  });
+
+  afterEach(() => {
+    if (origDataHome === undefined) {
+      delete process.env.XDG_DATA_HOME;
+    } else {
+      process.env.XDG_DATA_HOME = origDataHome;
+    }
+    delete process.env.HQ_STATE_DIR;
+    fs.rmSync(tmpDir, { recursive: true, force: true });
+  });
+
+  it("propagates delete on etag match against a v2-shaped journal", async () => {
+    const companyRoot = path.join(tmpDir, "companies", "acme");
+    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({
+        version: "2",
+        lastSync: new Date().toISOString(),
+        files: {
+          "core/policies/old.md": {
+            hash: "h",
+            size: 100,
+            syncedAt: new Date().toISOString(),
+            direction: "down",
+            remoteEtag: "v2-etag",
+          },
+        },
+        pulls: [],
+      }),
+    );
+
+    vi.mocked(headRemoteFile).mockResolvedValueOnce({
+      lastModified: new Date(),
+      etag: '"v2-etag"',
+      size: 100,
+    });
+
+    const result = await share({
+      paths: [companyRoot],
+      company: "acme",
+      vaultConfig: mockConfig,
+      hqRoot: tmpDir,
+      skipUnchanged: true,
+      propagateDeletes: true,
+      propagateDeletePolicy: "currency-gated",
+    });
+
+    expect(result.filesDeleted).toBe(1);
+    expect(deleteRemoteFile).toHaveBeenCalledWith(
+      expect.anything(),
+      "core/policies/old.md",
+    );
+  });
+});