@indigoai-us/hq-cloud 6.14.22 → 6.14.24

package/src/s3.symlink-materialize.test.ts

@@ -0,0 +1,492 @@
+/**
+ * Regression tests for US-001 (hq-sync-windows-skill-symlink-collision):
+ * Windows-safe, idempotent symlink materialization in downloadFile.
+ *
+ * Background: the .claude/skills/<ns>:<skill> link farm is materialized from
+ * `hq-symlink:<target>` records. Pre-fix, downloadFile always did
+ * symlinkSync(temp) + renameSync(temp, dest). On Windows that is doubly
+ * broken: (1) rename() can never replace an existing directory — and a
+ * directory symlink counts as one — so every pull over the farm EPERM'd,
+ * never journaled, and re-downloaded forever; (2) a bare symlinkSync mints a
+ * FILE-type link, which is broken for directory targets on Windows.
+ *
+ * Windows semantics are exercised via the injectable `win32` option (the
+ * local-path-codec.ts convention) plus scripted fs fakes, so these tests are
+ * deterministic on POSIX CI and on a real Windows host alike.
+ */
+
+import { describe, it, expect, beforeEach, afterEach, vi } from "vitest";
+import * as fs from "fs";
+import * as os from "os";
+import * as path from "path";
+
+// Re-export node:fs as a plain mutable object so vi.spyOn can instrument
+// individual functions (the frozen ESM namespace of a builtin cannot be
+// spied on directly). Every copied function still delegates to the real
+// implementation until a test overrides it.
+vi.mock("fs", async (importOriginal) => {
+  const actual = await importOriginal<typeof import("fs")>();
+  return { ...actual };
+});
+
+import { downloadFile, SYMLINK_BODY_PREFIX, SYMLINK_MARKER_META_VALUE } from "./s3.js";
+import { localPathForVaultKey } from "./local-path-codec.js";
+import { setObjectIOFactory, type ObjectIO } from "./object-io.js";
+import type { EntityContext } from "./types.js";
+
+function makeCtx(): EntityContext {
+  return {
+    uid: "cmp_TEST",
+    slug: "acme",
+    bucketName: "hq-vault-acme-123",
+    region: "us-east-1",
+    credentials: {
+      accessKeyId: "ASIA_TEST",
+      secretAccessKey: "secret",
+      sessionToken: "session",
+    },
+    expiresAt: new Date(Date.now() + 15 * 60 * 1000).toISOString(),
+  };
+}
+
+/** ObjectIO stub serving a single symlink record (marker + prefixed body). */
+function symlinkRecordIO(target: string): ObjectIO {
+  return {
+    putObject: async () => ({ etag: '"unused"' }),
+    getObject: async () => ({
+      body: Buffer.from(SYMLINK_BODY_PREFIX + target, "utf-8"),
+      metadata: { "hq-symlink-target": SYMLINK_MARKER_META_VALUE },
+    }),
+    listObjects: async () => ({ objects: [] }),
+    deleteObject: async () => undefined,
+    headObject: async () => null,
+  };
+}
+
+function errnoError(code: string): NodeJS.ErrnoException {
+  const err = new Error(`${code}: scripted test failure`) as NodeJS.ErrnoException;
+  err.code = code;
+  return err;
+}
+
+/** Minimal fs.Stats fake — only the predicates downloadFile consults. */
+function fakeStats(shape: {
+  symlink?: boolean;
+  dir?: boolean;
+  file?: boolean;
+}): fs.Stats {
+  return {
+    isSymbolicLink: () => shape.symlink ?? false,
+    isDirectory: () => shape.dir ?? false,
+    isFile: () => shape.file ?? false,
+  } as unknown as fs.Stats;
+}
+
+describe("downloadFile symlink materialization (US-001)", () => {
+  let tmpRoot: string;
+
+  beforeEach(() => {
+    tmpRoot = fs.mkdtempSync(path.join(os.tmpdir(), "s3-symlink-mat-test-"));
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+    setObjectIOFactory(null);
+    fs.rmSync(tmpRoot, { recursive: true, force: true });
+  });
+
+  it("fast path: an unchanged symlink is a success WITHOUT touching disk", async () => {
+    // The perpetual-churn half of the bug: an already-correct link went
+    // through temp+rename anyway, EPERM'd on Windows, never journaled, and
+    // re-downloaded every pass. A pull whose incoming target matches the
+    // existing link must return success (so the caller journals it) with
+    // zero writes — no temp link, no rename, no beforeReplace.
+    const target = "../real-target.md";
+    const localPath = path.join(tmpRoot, "skills", "link.md");
+    fs.mkdirSync(path.dirname(localPath), { recursive: true });
+    // Real target on disk: the win32 fast path stat-follows the link to
+    // confirm it functions as the desired type (a dangling link would
+    // deliberately fall through to replacement).
+    fs.writeFileSync(path.join(tmpRoot, "real-target.md"), "target body");
+    fs.symlinkSync(target, localPath);
+    setObjectIOFactory(() => symlinkRecordIO(target));
+
+    const symlinkSpy = vi.spyOn(fs, "symlinkSync");
+    const renameSpy = vi.spyOn(fs, "renameSync");
+    const beforeReplace = vi.fn();
+
+    const res = await downloadFile(makeCtx(), "skills/link.md", localPath, {
+      beforeReplace,
+    });
+
+    // Success shape matches a materializing pull, so the caller journals it.
+    expect(res.metadata?.["hq-symlink-target"]).toBe(SYMLINK_MARKER_META_VALUE);
+    expect(symlinkSpy).not.toHaveBeenCalled();
+    expect(renameSpy).not.toHaveBeenCalled();
+    expect(beforeReplace).not.toHaveBeenCalled();
+    expect(fs.lstatSync(localPath).isSymbolicLink()).toBe(true);
+  });
+
+  it("fast path compares readlink() separator-insensitively on win32", async () => {
+    // Windows stores the substitute path with backslashes (Node converts
+    // '/' at symlink() time), so readlink() of a link created from the
+    // POSIX-slashed wire target returns '..\\dir\\target'. The comparison
+    // must treat that as equal to the incoming '../dir/target' or the fast
+    // path would never fire for any multi-segment target on Windows.
+    const wireTarget = "../companies/indigo/skills/call-prep-brief";
+    const localPath = path.join(tmpRoot, "farm", "indigo%3Acall-prep-brief");
+    fs.mkdirSync(path.dirname(localPath), { recursive: true });
+    // Real directory at the resolved target: the link farm's normal shape,
+    // and what makes the desired flavor directory-ish (a junction, post-#219).
+    fs.mkdirSync(path.resolve(path.dirname(localPath), wireTarget), {
+      recursive: true,
+    });
+    setObjectIOFactory(() => symlinkRecordIO(wireTarget));
+
+    vi.spyOn(fs, "lstatSync").mockImplementation(() =>
+      fakeStats({ symlink: true }),
+    );
+    // A RELATIVE substitute path — the spelling an older client's 'dir'
+    // symlink left behind. It still resolves to the same target, so the
+    // fast path must accept it rather than churn the link.
+    vi.spyOn(fs, "readlinkSync").mockImplementation(
+      () => "..\\companies\\indigo\\skills\\call-prep-brief",
+    );
+    const realStatSync = fs.statSync.bind(fs) as (p: fs.PathLike) => fs.Stats;
+    // The follow-probe on the link itself reports a traversable directory,
+    // matching the flavor createStagedSymlink would mint — fast path holds.
+    vi.spyOn(fs, "statSync").mockImplementation(((p: fs.PathLike) =>
+      p === localPath
+        ? fakeStats({ dir: true })
+        : realStatSync(p)) as typeof fs.statSync);
+    const symlinkSpy = vi.spyOn(fs, "symlinkSync");
+    const renameSpy = vi.spyOn(fs, "renameSync");
+
+    const res = await downloadFile(
+      makeCtx(),
+      ".claude/skills/indigo:call-prep-brief",
+      localPath,
+      { win32: true },
+    );
+
+    expect(res.metadata).toBeDefined();
+    expect(symlinkSpy).not.toHaveBeenCalled();
+    expect(renameSpy).not.toHaveBeenCalled();
+  });
+
+  it("fast path accepts a JUNCTION's absolute substitute path against a relative wire target", async () => {
+    // Post-#219, win32 directory overlays are materialized as junctions, and
+    // a junction can only store an ABSOLUTE substitute path. readlink() of a
+    // link this client itself created therefore returns
+    // 'C:\\...\\companies\\indigo\\skills\\call-prep-brief' while the wire
+    // target stays '../companies/...'. If equality were a raw string compare
+    // the fast path could never fire for the link farm on Windows — every
+    // pull would re-stage the whole farm, which is precisely the perpetual
+    // churn US-001 exists to kill. Both sides must be resolved before compare.
+    const wireTarget = "../companies/indigo/skills/call-prep-brief";
+    const localPath = path.join(tmpRoot, "farm", "indigo%3Acall-prep-brief");
+    fs.mkdirSync(path.dirname(localPath), { recursive: true });
+    const absTarget = path.resolve(path.dirname(localPath), wireTarget);
+    fs.mkdirSync(absTarget, { recursive: true });
+    setObjectIOFactory(() => symlinkRecordIO(wireTarget));
+
+    vi.spyOn(fs, "lstatSync").mockImplementation(() =>
+      fakeStats({ symlink: true }),
+    );
+    vi.spyOn(fs, "readlinkSync").mockImplementation(() =>
+      absTarget.split("/").join("\\"),
+    );
+    const realStatSync = fs.statSync.bind(fs) as (p: fs.PathLike) => fs.Stats;
+    vi.spyOn(fs, "statSync").mockImplementation(((p: fs.PathLike) =>
+      p === localPath
+        ? fakeStats({ dir: true })
+        : realStatSync(p)) as typeof fs.statSync);
+    const symlinkSpy = vi.spyOn(fs, "symlinkSync");
+    const renameSpy = vi.spyOn(fs, "renameSync");
+
+    const res = await downloadFile(
+      makeCtx(),
+      ".claude/skills/indigo:call-prep-brief",
+      localPath,
+      { win32: true },
+    );
+
+    expect(res.metadata).toBeDefined();
+    expect(symlinkSpy).not.toHaveBeenCalled();
+    expect(renameSpy).not.toHaveBeenCalled();
+  });
+
+  it("win32: a FILE-flavor link at a DIRECTORY target is broken despite a matching target string — recreated as a junction, never fast-pathed", async () => {
+    // Round-3 review P1: flavors matter on Windows. An older client (or a
+    // pull that ran while the target dir was absent) can leave a file-type
+    // link whose target string matches the incoming record exactly; it
+    // still cannot be traversed. The fast path must fall through and the
+    // materializer must mint the correct directory flavor — post-#219 that
+    // is a junction (unprivileged) rather than a 'dir' NTFS symlink.
+    const wireTarget = "../companies/indigo/skills/call-prep-brief";
+    const localPath = path.join(tmpRoot, "farm", "indigo%3Acall-prep-brief");
+    fs.mkdirSync(path.dirname(localPath), { recursive: true });
+    const resolvedTarget = path.resolve(path.dirname(localPath), wireTarget);
+    fs.mkdirSync(resolvedTarget, { recursive: true });
+    setObjectIOFactory(() => symlinkRecordIO(wireTarget));
+
+    const realStatSync = fs.statSync.bind(fs) as (p: fs.PathLike) => fs.Stats;
+    vi.spyOn(fs, "lstatSync").mockImplementation(((p: fs.PathLike) =>
+      p === localPath
+        ? fakeStats({ symlink: true })
+        : fakeStats({})) as typeof fs.lstatSync);
+    vi.spyOn(fs, "readlinkSync").mockImplementation(
+      (() => "..\\companies\\indigo\\skills\\call-prep-brief") as unknown as typeof fs.readlinkSync,
+    );
+    // Windows refuses to traverse the wrong-flavor link: stat on the link
+    // throws, while the resolved target itself stats as a real directory.
+    vi.spyOn(fs, "statSync").mockImplementation(((p: fs.PathLike) => {
+      if (p === localPath) throw errnoError("EINVAL");
+      return realStatSync(p);
+    }) as typeof fs.statSync);
+    const symlinkSpy = vi
+      .spyOn(fs, "symlinkSync")
+      .mockImplementation(() => undefined);
+    vi.spyOn(fs, "unlinkSync").mockImplementation(() => undefined);
+    vi.spyOn(fs, "renameSync").mockImplementation(() => undefined);
+
+    await downloadFile(makeCtx(), ".claude/skills/indigo:call-prep-brief", localPath, {
+      win32: true,
+    });
+
+    // Fell through the fast path and minted the correct flavor: a junction,
+    // which requires an absolute substitute path.
+    expect(symlinkSpy).toHaveBeenCalledTimes(1);
+    expect(symlinkSpy.mock.calls[0]![2]).toBe("junction");
+    expect(symlinkSpy.mock.calls[0]![0]).toBe(resolvedTarget);
+  });
+
+  it("win32: replaces a directory symlink via backup-swap, minting a junction temp link", async () => {
+    // Failure signature 1 from the incident: EPERM on rename over
+    // '...\\indigo%3Acall-prep-brief\\scripts' — the destination was a
+    // directory symlink, which Windows rename() can never replace.
+    // replaceStagedPath (upstream #193) swaps a symlink destination out to
+    // a sibling backup, installs the staged link, then removes the backup.
+    const wireTarget = "../companies/indigo/skills/call-prep-brief";
+    const localPath = path.join(tmpRoot, "farm", "indigo%3Acall-prep-brief");
+    fs.mkdirSync(path.dirname(localPath), { recursive: true });
+    // Real directory at the resolved target so the type probe picks 'dir'.
+    fs.mkdirSync(path.resolve(path.dirname(localPath), wireTarget), {
+      recursive: true,
+    });
+    setObjectIOFactory(() => symlinkRecordIO(wireTarget));
+
+    const realLstatSync = fs.lstatSync.bind(fs) as (p: fs.PathLike) => fs.Stats;
+    const realStatSync = fs.statSync.bind(fs) as (p: fs.PathLike) => fs.Stats;
+    // Destination is scripted as a live directory symlink to a STALE target.
+    vi.spyOn(fs, "lstatSync").mockImplementation(((p: fs.PathLike) =>
+      p === localPath
+        ? fakeStats({ symlink: true })
+        : realLstatSync(p)) as typeof fs.lstatSync);
+    vi.spyOn(fs, "readlinkSync").mockImplementation(
+      (() => "..\\stale\\old-skill") as unknown as typeof fs.readlinkSync,
+    );
+    vi.spyOn(fs, "statSync").mockImplementation(((p: fs.PathLike) =>
+      p === localPath
+        ? fakeStats({ dir: true })
+        : realStatSync(p)) as typeof fs.statSync);
+    const symlinkSpy = vi
+      .spyOn(fs, "symlinkSync")
+      .mockImplementation(() => undefined);
+    const unlinkSpy = vi
+      .spyOn(fs, "unlinkSync")
+      .mockImplementation(() => undefined);
+    const renameSpy = vi
+      .spyOn(fs, "renameSync")
+      .mockImplementation(() => undefined);
+
+    await downloadFile(makeCtx(), ".claude/skills/indigo:call-prep-brief", localPath, {
+      win32: true,
+    });
+
+    // Typed temp link: directory target ⇒ junction with an ABSOLUTE
+    // substitute path (#219 — a bare symlinkSync mints a broken file-type
+    // link, and a 'dir' NTFS symlink EPERMs without Developer Mode).
+    expect(symlinkSpy).toHaveBeenCalledTimes(1);
+    expect(symlinkSpy.mock.calls[0]![0]).toBe(
+      path.resolve(path.dirname(localPath), wireTarget),
+    );
+    expect(String(symlinkSpy.mock.calls[0]![1])).toContain(".hq-tmp-");
+    expect(symlinkSpy.mock.calls[0]![2]).toBe("junction");
+    // Backup-swap: old link → .hq-backup-*, staged link → destination,
+    // backup removed. The destination itself is never rm'd in place.
+    expect(renameSpy).toHaveBeenCalledTimes(2);
+    expect(renameSpy.mock.calls[0]![0]).toBe(localPath);
+    expect(String(renameSpy.mock.calls[0]![1])).toContain(".hq-backup-");
+    expect(String(renameSpy.mock.calls[1]![0])).toContain(".hq-tmp-");
+    expect(renameSpy.mock.calls[1]![1]).toBe(localPath);
+    expect(unlinkSpy).not.toHaveBeenCalledWith(localPath);
+    expect(
+      unlinkSpy.mock.calls.some((c) => String(c[0]).includes(".hq-backup-")),
+    ).toBe(true);
+  });
+
+  it("win32: replaces a file symlink via backup-swap, minting a 'file'-type temp link", async () => {
+    const wireTarget = "../personal/skills/dm/SKILL.md";
+    const localPath = path.join(tmpRoot, "farm", "personal%3Adm");
+    fs.mkdirSync(path.dirname(localPath), { recursive: true });
+    // A GENUINE regular file at the resolved target — the only shape that
+    // still earns a real 'file' symlink post-#219. An unresolvable target is
+    // deliberately materialized as a junction instead (vault overlays are
+    // directories, and a junction needs no Windows symlink privilege).
+    const resolvedTarget = path.resolve(path.dirname(localPath), wireTarget);
+    fs.mkdirSync(path.dirname(resolvedTarget), { recursive: true });
+    fs.writeFileSync(resolvedTarget, "# dm skill");
+    setObjectIOFactory(() => symlinkRecordIO(wireTarget));
+
+    const realLstatSync = fs.lstatSync.bind(fs) as (p: fs.PathLike) => fs.Stats;
+    vi.spyOn(fs, "lstatSync").mockImplementation(((p: fs.PathLike) =>
+      p === localPath
+        ? fakeStats({ symlink: true })
+        : realLstatSync(p)) as typeof fs.lstatSync);
+    vi.spyOn(fs, "readlinkSync").mockImplementation(
+      (() => "..\\stale\\dm.md") as unknown as typeof fs.readlinkSync,
+    );
+    const symlinkSpy = vi
+      .spyOn(fs, "symlinkSync")
+      .mockImplementation(() => undefined);
+    const rmdirSpy = vi.spyOn(fs, "rmdirSync");
+    const unlinkSpy = vi
+      .spyOn(fs, "unlinkSync")
+      .mockImplementation(() => undefined);
+    const renameSpy = vi
+      .spyOn(fs, "renameSync")
+      .mockImplementation(() => undefined);
+
+    await downloadFile(makeCtx(), ".claude/skills/personal:dm", localPath, {
+      win32: true,
+    });
+
+    expect(symlinkSpy.mock.calls[0]![2]).toBe("file");
+    // Backup-swap: two renames (old→backup, staged→destination) and the
+    // backup removed; the destination is never unlinked in place.
+    expect(renameSpy).toHaveBeenCalledTimes(2);
+    expect(unlinkSpy).not.toHaveBeenCalledWith(localPath);
+    expect(
+      unlinkSpy.mock.calls.some((c) => String(c[0]).includes(".hq-backup-")),
+    ).toBe(true);
+    expect(rmdirSpy).not.toHaveBeenCalledWith(localPath);
+  });
+
+  it("win32: NEVER deletes a real (non-symlink) directory — the rename failure surfaces", async () => {
+    // The engine-level guarantee behind the caller's "manual reconciliation
+    // required" warning: a real directory at the destination is the user's
+    // data. The replace path may only remove SYMLINK destinations; a real
+    // dir is left in place and the (scripted, Windows-faithful) EPERM from
+    // rename-over-dir propagates.
+    const wireTarget = "../companies/indigo/skills/capture";
+    const localPath = path.join(tmpRoot, "farm", "indigo%3Acapture");
+    fs.mkdirSync(localPath, { recursive: true }); // REAL directory
+    fs.mkdirSync(path.resolve(path.dirname(localPath), wireTarget), {
+      recursive: true,
+    });
+    setObjectIOFactory(() => symlinkRecordIO(wireTarget));
+
+    vi.spyOn(fs, "symlinkSync").mockImplementation(() => undefined);
+    const rmdirSpy = vi.spyOn(fs, "rmdirSync");
+    const unlinkSpy = vi.spyOn(fs, "unlinkSync");
+    const renameSpy = vi.spyOn(fs, "renameSync").mockImplementation(() => {
+      throw errnoError("EPERM");
+    });
+
+    await expect(
+      downloadFile(makeCtx(), ".claude/skills/indigo:capture", localPath, {
+        win32: true,
+      }),
+    ).rejects.toThrow(/EPERM/);
+
+    // Surfaced on the first failure — never silently swallowed, and a
+    // non-symlink destination gets no backup-swap (nothing to roll back).
+    expect(renameSpy).toHaveBeenCalledTimes(1);
+    // The real directory was never removed (temp cleanup may touch the
+    // .hq-tmp- path, but the destination itself is untouchable).
+    expect(rmdirSpy).not.toHaveBeenCalledWith(localPath);
+    expect(unlinkSpy).not.toHaveBeenCalledWith(localPath);
+    expect(fs.statSync(localPath).isDirectory()).toBe(true);
+  });
+
+  it("POSIX: symlink destination is replaced cleanly — fresh target installed, no temp/backup litter", async () => {
+    // replaceStagedPath backup-swaps symlink destinations on every
+    // platform; the observable contract is a clean replacement with no
+    // .hq-tmp-/.hq-backup- litter and a bare (no type hint) staged link.
+    const localPath = path.join(tmpRoot, "posix-link.md");
+    fs.symlinkSync("stale-target.md", localPath);
+    setObjectIOFactory(() => symlinkRecordIO("fresh-target.md"));
+
+    const symlinkSpy = vi.spyOn(fs, "symlinkSync");
+
+    await downloadFile(makeCtx(), "posix-link.md", localPath, {
+      win32: false,
+    });
+
+    expect(symlinkSpy).toHaveBeenCalledTimes(1);
+    expect(symlinkSpy.mock.calls[0]![2]).toBeUndefined();
+    expect(fs.readlinkSync(localPath)).toBe("fresh-target.md");
+    const litter = fs
+      .readdirSync(tmpRoot)
+      .filter((n) => n.startsWith(".hq-tmp-") || n.startsWith(".hq-backup-"));
+    expect(litter).toEqual([]);
+  });
+
+  it("2026-07-16 ENOENT mode (US-002): parents are created at the ENCODED local path, never the raw-colon path", async () => {
+    // Failure signature 2 from the incident:
+    //   ENOENT mkdir 'C:\...\skills\indigo:team-agent-telemetry-report'
+    // — the pre-codec caller handed downloadFile a RAW-key local path, and
+    // Windows cannot mkdir a colon segment. The pull pipeline now derives
+    // localPath through the codec (sync.ts resolveContainedVaultPath →
+    // localPathForVaultKey); this pins the contract end-to-end: pulling the
+    // incident's exact key with a codec-derived localPath materializes the
+    // parent chain at `indigo%3Ateam-agent-telemetry-report`, and no
+    // raw-colon sibling ever appears.
+    const key = ".claude/skills/indigo:team-agent-telemetry-report/agents";
+    const wireTarget =
+      "../../../companies/indigo/skills/team-agent-telemetry-report/agents";
+    const localPath = localPathForVaultKey(tmpRoot, key, true);
+    setObjectIOFactory(() => symlinkRecordIO(wireTarget));
+    // Leaf materialization is exercised by the suites above; this test is
+    // about the parent chain, so the link+rename pair is inert.
+    vi.spyOn(fs, "symlinkSync").mockImplementation(() => undefined);
+    vi.spyOn(fs, "renameSync").mockImplementation(() => undefined);
+
+    await downloadFile(makeCtx(), key, localPath, { win32: true });
+
+    const encodedParent = path.join(
+      tmpRoot,
+      ".claude",
+      "skills",
+      "indigo%3Ateam-agent-telemetry-report",
+    );
+    expect(fs.existsSync(encodedParent)).toBe(true);
+    expect(fs.statSync(encodedParent).isDirectory()).toBe(true);
+    // The raw-colon spelling must not exist anywhere in the farm.
+    expect(
+      fs.readdirSync(path.join(tmpRoot, ".claude", "skills")),
+    ).toEqual(["indigo%3Ateam-agent-telemetry-report"]);
+  });
+
+  it("POSIX: fast path also fires with exact string equality", async () => {
+    // Separator normalization is win32-only; POSIX equality is exact (a
+    // backslash is an ordinary filename character there). A separator-free
+    // target makes this deterministic on any host platform.
+    const target = "plain-target.md";
+    const localPath = path.join(tmpRoot, "posix-noop.md");
+    fs.symlinkSync(target, localPath);
+    setObjectIOFactory(() => symlinkRecordIO(target));
+
+    const symlinkSpy = vi.spyOn(fs, "symlinkSync");
+    const renameSpy = vi.spyOn(fs, "renameSync");
+
+    const res = await downloadFile(makeCtx(), "posix-noop.md", localPath, {
+      win32: false,
+    });
+
+    expect(res.metadata).toBeDefined();
+    expect(symlinkSpy).not.toHaveBeenCalled();
+    expect(renameSpy).not.toHaveBeenCalled();
+  });
+});

package/src/s3.test.ts

@@ -1067,6 +1067,30 @@ describe("downloadFile", () => {
     );
   });
 
+  it("default ops replace a directory symlink destination end-to-end (dir-reparse-safe cleanup)", () => {
+    // No ops seam: exercises DEFAULT_REPLACE_STAGED_PATH_OPS on the real
+    // filesystem. The backup of the old DIR-type link must be removable on
+    // every platform (unlink with rmdir fallback for directory reparse
+    // points), or the replacement rolls back and the Windows churn returns.
+    const oldTarget = path.join(tmpRoot, "default-ops-old");
+    const newTarget = path.join(tmpRoot, "default-ops-new");
+    const localPath = path.join(tmpRoot, "default-ops-link");
+    const stagedPath = path.join(tmpRoot, ".hq-tmp-default-ops-test");
+    fs.mkdirSync(oldTarget);
+    fs.mkdirSync(newTarget);
+    fs.symlinkSync(oldTarget, localPath, "dir");
+    fs.symlinkSync(newTarget, stagedPath, "dir");
+
+    replaceStagedPath(stagedPath, localPath);
+
+    expect(fs.lstatSync(localPath).isSymbolicLink()).toBe(true);
+    expect(fs.readlinkSync(localPath)).toBe(newTarget);
+    expect(
+      fs.readdirSync(tmpRoot).filter((n) => n.startsWith(".hq-backup-")),
+    ).toEqual([]);
+    expect(fs.existsSync(stagedPath)).toBe(false);
+  });
+
   it("restores an existing directory link when staged replacement fails", () => {
     const targetDir = path.join(tmpRoot, "rollback-source");
     const localPath = path.join(tmpRoot, "rollback-link");