@indigoai-us/hq-cloud 6.15.0 → 6.15.2

package/src/s3.test.ts

@@ -1,1789 +0,0 @@
-/**
- * Unit tests for s3.uploadFile.
- *
- * Regression coverage for the bug where hq-console vault UI's "CREATED BY"
- * column rendered `—` for every file: every PutObject went out without
- * `Metadata`, so the listing's HEAD fan-out had nothing to attribute.
- */
-
-import { describe, it, expect, beforeEach, afterEach, vi } from "vitest";
-import * as fs from "fs";
-import * as os from "os";
-import * as path from "path";
-import * as crypto from "crypto";
-
-// Capture every command sent to the S3Client across the test suite. Cleared
-// in beforeEach so per-test assertions don't leak from neighbours.
-const sentCommands: Array<{ name: string; input: Record<string, unknown> }> = [];
-
-// Per-test override for the ListObjectsV2Command response. Tests of
-// `listRemoteFiles` push the Contents shape they want returned; the default
-// is an empty bucket. Reset in beforeEach so cross-test leakage is impossible.
-let nextListObjectsResponse: Record<string, unknown> = { Contents: [] };
-
-// Per-test override for the GetObjectCommand response. The default fake
-// doesn't model GET (downloadFile previously had no s3.test.ts coverage);
-// downloadFile tests push the Body + Metadata shape they want returned.
-let nextGetObjectResponse: Record<string, unknown> = {
-  Body: (async function* () {
-    yield new Uint8Array();
-  })(),
-  Metadata: {},
-};
-
-vi.mock("@aws-sdk/client-s3", () => {
-  class FakeS3Client {
-    async send(command: { constructor: { name: string }; input: Record<string, unknown> }): Promise<Record<string, unknown>> {
-      sentCommands.push({ name: command.constructor.name, input: command.input });
-      if (command.constructor.name === "HeadObjectCommand") {
-        // Default: object exists with no metadata. Tests that need a 404 or
-        // a metadata-bearing HEAD override per-test via mockReturnValueOnce.
-        return { Metadata: {} };
-      }
-      if (command.constructor.name === "PutObjectCommand") {
-        return { ETag: '"fake-etag"' };
-      }
-      if (command.constructor.name === "ListObjectsV2Command") {
-        return nextListObjectsResponse;
-      }
-      if (command.constructor.name === "GetObjectCommand") {
-        return nextGetObjectResponse;
-      }
-      return {};
-    }
-  }
-  // Each command class records constructor.name + input so the spy above can
-  // tell them apart. Mirrors the real SDK's command shape closely enough for
-  // the assertion surface the s3.ts code touches.
-  class PutObjectCommand {
-    constructor(public input: Record<string, unknown>) {}
-  }
-  class GetObjectCommand {
-    constructor(public input: Record<string, unknown>) {}
-  }
-  class HeadObjectCommand {
-    constructor(public input: Record<string, unknown>) {}
-  }
-  class ListObjectsV2Command {
-    constructor(public input: Record<string, unknown>) {}
-  }
-  class DeleteObjectCommand {
-    constructor(public input: Record<string, unknown>) {}
-  }
-  return {
-    S3Client: FakeS3Client,
-    PutObjectCommand,
-    GetObjectCommand,
-    HeadObjectCommand,
-    ListObjectsV2Command,
-    DeleteObjectCommand,
-  };
-});
-
-import {
-  uploadFile,
-  uploadSymlink,
-  toPosixKey,
-  primeUploads,
-  downloadFile,
-  listRemoteFiles,
-  SYMLINK_BODY_PREFIX,
-  SYMLINK_MARKER_META_VALUE,
-  encodeSymlinkMetadataValue,
-  decodeSymlinkMetadataValue,
-  FILE_MTIME_META_KEY,
-  FILE_BTIME_META_KEY,
-  classifyVaultKey,
-  validateVaultUploadKey,
-  createStagedSymlink,
-  replaceStagedPath,
-  sweepStaleStagedFiles,
-  DanglingSymlinkParentError,
-} from "./s3.js";
-import {
-  setObjectIOFactory,
-  presignObjectIOFactory,
-  type ObjectIO,
-  type PresignTransportClient,
-} from "./object-io.js";
-import type { PresignResultRow } from "./vault-client.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(),
-  };
-}
-
-describe("backslash key normalization (Windows client → POSIX S3 key)", () => {
-  // Regression for the Ridges vault bug: a non-POSIX (Windows) HQ Sync client
-  // built object keys from path.relative(), whose separator is "\\". Stored
-  // verbatim, `knowledge\books-eoi.md` had no "/", so the vault listing (which
-  // splits keys on "/") rendered it flat at the root as one oddly-named file.
-  let tmpFile: string;
-
-  beforeEach(() => {
-    sentCommands.length = 0;
-    tmpFile = path.join(
-      os.tmpdir(),
-      `s3-backslash-test-${Date.now()}-${Math.random()}.md`,
-    );
-    fs.writeFileSync(tmpFile, "hello");
-  });
-
-  it("toPosixKey converts every backslash to a forward slash", () => {
-    expect(toPosixKey("knowledge\\books-eoi.md")).toBe("knowledge/books-eoi.md");
-    expect(toPosixKey("data\\sub\\boots-accounts.json")).toBe(
-      "data/sub/boots-accounts.json",
-    );
-  });
-
-  it("toPosixKey leaves an already-POSIX key unchanged (idempotent)", () => {
-    expect(toPosixKey("knowledge/books-eoi.md")).toBe("knowledge/books-eoi.md");
-    expect(toPosixKey("flat.md")).toBe("flat.md");
-  });
-
-  it("uploadFile stores a POSIX key when given a Windows-style backslash path", async () => {
-    await uploadFile(makeCtx(), tmpFile, "knowledge\\books-eoi.md");
-
-    const put = sentCommands.find((c) => c.name === "PutObjectCommand");
-    expect(put).toBeDefined();
-    expect(put!.input.Key).toBe("knowledge/books-eoi.md");
-  });
-
-  it("uploadSymlink stores a POSIX key when given a Windows-style backslash path", async () => {
-    await uploadSymlink(
-      makeCtx(),
-      "../knowledge-ridges/target.md",
-      "data\\boots-accounts.json",
-    );
-
-    const put = sentCommands.find((c) => c.name === "PutObjectCommand");
-    expect(put).toBeDefined();
-    expect(put!.input.Key).toBe("data/boots-accounts.json");
-  });
-});
-
-describe("backslash key normalization on the PRESIGNED (GA) transport", () => {
-  // The tests above assert normalization on the S3-SDK transport (sentCommands
-  // capture SDK PutObjectCommands). As of 6.5.0 the presigned-URL transport is
-  // GA for every company vault (cmp_*) — that's the path a real Windows client
-  // like Ridge's now takes. These lock the SAME write-side invariant on that
-  // transport: a backslash key is canonicalized to POSIX before the server is
-  // ever asked to presign it, so a non-POSIX vault key can never be minted.
-  let tmpFile: string;
-  let presignCalls: Array<{ op?: string; keys: Array<{ key?: string }> }>;
-
-  function presignKeysFor(op: string): string[] {
-    return presignCalls
-      .filter((c) => c.op === op)
-      .flatMap((c) => c.keys.map((k) => k.key ?? ""));
-  }
-
-  beforeEach(() => {
-    tmpFile = path.join(
-      os.tmpdir(),
-      `s3-presign-backslash-${Date.now()}-${Math.random()}.md`,
-    );
-    fs.writeFileSync(tmpFile, "hello");
-
-    presignCalls = [];
-    const vault: PresignTransportClient = {
-      // Echo each requested key back as a usable URL so putObject's PUT
-      // resolves; record the op + keys so we can assert what was signed.
-      presign: async (input) => {
-        presignCalls.push({ op: input.op, keys: input.keys as Array<{ key?: string }> });
-        const results: PresignResultRow[] = input.keys.map((k) => ({
-          key: (k as { key: string }).key,
-          op: input.op ?? "put",
-          url: `https://s3.test/${(k as { key: string }).key}`,
-        }));
-        return { results, expiresAt: "2099-01-01T00:00:00.000Z" };
-      },
-      listFiles: async () => ({ objects: [], cursor: null, truncated: false }),
-    };
-    setObjectIOFactory(presignObjectIOFactory(vault));
-    // putObject moves bytes over the presigned URL via global fetch.
-    vi.stubGlobal(
-      "fetch",
-      vi.fn(async () => new Response(null, { status: 200, headers: { etag: '"e"' } })),
-    );
-  });
-
-  afterEach(() => {
-    setObjectIOFactory(null);
-    vi.unstubAllGlobals();
-  });
-
-  it("uploadFile presigns + PUTs a POSIX key for a Windows-style backslash path", async () => {
-    await uploadFile(makeCtx(), tmpFile, "knowledge\\books-eoi.md");
-    expect(presignKeysFor("put")).toContain("knowledge/books-eoi.md");
-    // The malformed backslash key is never presigned (so never PUT).
-    expect(presignKeysFor("put")).not.toContain("knowledge\\books-eoi.md");
-  });
-
-  it("uploadSymlink presigns a POSIX key for a Windows-style backslash path", async () => {
-    await uploadSymlink(makeCtx(), "../target.md", "data\\boots-accounts.json");
-    expect(presignKeysFor("put")).toContain("data/boots-accounts.json");
-    expect(presignKeysFor("put")).not.toContain("data\\boots-accounts.json");
-  });
-
-  it("primeUploads canonicalizes keys so the primed PUT URL matches the upload lookup", async () => {
-    // Prime then upload the SAME Windows-origin key. Both must key the cache
-    // under the POSIX form: prime signs the POSIX PUT URL, and uploadFile's
-    // hasPrimedPut(toPosixKey(...)) reuses it instead of re-presigning — proving
-    // the primed fast-path can't strand a backslash key (and can't store one).
-    await primeUploads(makeCtx(), [
-      { key: "knowledge\\books-eoi.md", localPath: tmpFile, isSymlink: false },
-    ]);
-    // prime("get") + prime("put") both went out under the POSIX key only.
-    expect(presignKeysFor("get")).toEqual(["knowledge/books-eoi.md"]);
-    expect(presignKeysFor("put")).toEqual(["knowledge/books-eoi.md"]);
-
-    const putCountAfterPrime = presignKeysFor("put").length;
-    await uploadFile(makeCtx(), tmpFile, "knowledge\\books-eoi.md");
-    // No NEW put presign: uploadFile reused the primed POSIX URL (cache hit).
-    expect(presignKeysFor("put").length).toBe(putCountAfterPrime);
-  });
-});
-
-describe("uploadFile", () => {
-  let tmpFile: string;
-
-  beforeEach(() => {
-    sentCommands.length = 0;
-    tmpFile = path.join(os.tmpdir(), `s3-upload-test-${Date.now()}-${Math.random()}.md`);
-    fs.writeFileSync(tmpFile, "hello");
-  });
-
-  it("omits author Metadata fields when no author is provided (back-compat)", async () => {
-    // Pre-Bug-#5: this test asserted Metadata was undefined entirely. Now
-    // \`hq-mode\` is stamped on every upload to preserve source-side
-    // permissions, so the assertion is narrower: author fields stay absent
-    // when no author is passed, but \`hq-mode\` is present.
-    await uploadFile(makeCtx(), tmpFile, "attribution-test.md");
-
-    const put = sentCommands.find((c) => c.name === "PutObjectCommand");
-    expect(put).toBeDefined();
-    const meta = put!.input.Metadata as Record<string, string> | undefined;
-    expect(meta?.["created-by"]).toBeUndefined();
-    expect(meta?.["created-by-sub"]).toBeUndefined();
-    expect(meta?.["created-at"]).toBeUndefined();
-    // \`hq-mode\` IS present — that's the new Bug #5 contract.
-    expect(meta?.["hq-mode"]).toMatch(/^[0-7]{3}$/);
-  });
-
-  it("stamps created-by + created-by-sub + created-at when author is provided", async () => {
-    await uploadFile(makeCtx(), tmpFile, "attribution-test.md", {
-      userSub: "abc-123",
-      email: "alice@example.com",
-    });
-
-    const put = sentCommands.find((c) => c.name === "PutObjectCommand");
-    expect(put).toBeDefined();
-    const meta = put!.input.Metadata as Record<string, string>;
-    expect(meta["created-by"]).toBe("alice@example.com");
-    expect(meta["created-by-sub"]).toBe("abc-123");
-    // ISO-8601 with 'Z' suffix.
-    expect(meta["created-at"]).toMatch(/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}/);
-  });
-
-  it("preserves the existing created-at on re-upload (NEW-pill ageing window)", async () => {
-    // First upload happened a week ago; second run must keep that timestamp
-    // so the hq-console "NEW" pill doesn't reset on every sync tick.
-    // Override the FakeS3Client's HeadObject to return the legacy timestamp
-    // for this one test. The mock factory returns a fresh object per send
-    // invocation so we patch at the class level via a one-shot wrapper.
-    const { HeadObjectCommand } = await import("@aws-sdk/client-s3");
-    const originalHead = (HeadObjectCommand as unknown as { prototype: object }).prototype;
-    // Easier: drop in a sentry that recognizes the head command and answers.
-    // We do this by monkey-patching sendCommands handler — but actually our
-    // FakeS3Client always returns Metadata: {} for HEAD. Switch strategy:
-    // mock the S3Client.send for this test only.
-    void originalHead;
-
-    // Use vi.spyOn on the prototype is painful; instead push a marker file
-    // that the next test re-reads. Since the FakeS3Client is in a module
-    // singleton, the cleanest path is: temporarily replace the global handler.
-    // For this test we accept slight indirection — push a head response stub
-    // by mutating the captured queue's expectations via beforeEach below.
-    // Simpler approach: directly assert the new path covers the no-existing
-    // case (createdAt = now) and rely on integration coverage to verify the
-    // preserve path. The assertion below uses a fresh upload (no priors).
-    await uploadFile(makeCtx(), tmpFile, "fresh.md", {
-      userSub: "abc-123",
-      email: "alice@example.com",
-    });
-
-    const put = sentCommands.find((c) => c.name === "PutObjectCommand");
-    expect(put).toBeDefined();
-    const meta = put!.input.Metadata as Record<string, string>;
-    // The default FakeS3Client.HEAD returns Metadata: {} (no created-at),
-    // so the implementation must fall through to "now" — assert the
-    // timestamp is within the last minute. The "preserve" branch is
-    // exercised by share-sync.integration.test.ts where a real round-trip
-    // catches drift.
-    const stamped = new Date(meta["created-at"]).getTime();
-    expect(Date.now() - stamped).toBeLessThan(60 * 1000);
-  });
-
-  it("stamps source file mode as hq-mode metadata (Bug #5 — preserve permissions)", async () => {
-    // Bug #5 (broader than originally reported): every uploaded file's mode
-    // collapsed to the receiver's umask default (0644 on the verification
-    // hosts). 0755 scripts arrived non-executable, breaking every shell-tool
-    // workflow. Fix: stamp the source-side \`mode & 0o777\` into S3 user
-    // metadata as \`hq-mode\` (octal string), then chmod on download.
-    fs.chmodSync(tmpFile, 0o755);
-
-    await uploadFile(makeCtx(), tmpFile, "exec.sh");
-
-    const put = sentCommands.find((c) => c.name === "PutObjectCommand");
-    expect(put).toBeDefined();
-    const meta = put!.input.Metadata as Record<string, string> | undefined;
-    expect(meta?.["hq-mode"]).toBe("755");
-  });
-
-  it("stamps various modes correctly (0600, 0640, 0700, 0750)", async () => {
-    // Verification report V5: all four modes collapsed to 0644 receiver-side
-    // because the upload carried no mode at all. Pin each mode round-trips
-    // through the metadata header in canonical octal-string form (no leading
-    // zero — the parser uses parseInt(..., 8)).
-    for (const mode of [0o600, 0o640, 0o700, 0o750]) {
-      sentCommands.length = 0;
-      fs.chmodSync(tmpFile, mode);
-      await uploadFile(makeCtx(), tmpFile, "f.bin");
-      const put = sentCommands.find((c) => c.name === "PutObjectCommand");
-      const meta = put!.input.Metadata as Record<string, string> | undefined;
-      expect(meta?.["hq-mode"]).toBe(mode.toString(8));
-    }
-  });
-
-  it("stamps source file mtimeMs as hq-mtime metadata (5.37.0 — preserve mtime)", async () => {
-    // Symmetric to Bug #5's mode preservation. A file's modification time
-    // should follow it across machines instead of resetting to "the time of
-    // sync." Push stamps `hq-mtime` = integer-ms epoch string; pull applies
-    // it via utimesSync. See FILE_MTIME_META_KEY doc.
-    const knownMs = 1_700_000_000_000; // 2023-11-14T22:13:20Z, comfortably finite
-    const knownDate = new Date(knownMs);
-    fs.utimesSync(tmpFile, knownDate, knownDate);
-
-    await uploadFile(makeCtx(), tmpFile, "stamped.md");
-
-    const put = sentCommands.find((c) => c.name === "PutObjectCommand");
-    expect(put).toBeDefined();
-    const meta = put!.input.Metadata as Record<string, string> | undefined;
-    expect(meta?.[FILE_MTIME_META_KEY]).toBe(String(knownMs));
-  });
-
-  it("stamps hq-btime only when birthtime is supported AND distinct from mtime", async () => {
-    // Many filesystems (Linux/ext4 historically, tmpfs, some FUSE mounts)
-    // return birthtimeMs === 0 or birthtimeMs === mtimeMs. Stamping in
-    // those cases would be pure noise; the upload side filters it out.
-    // We don't control the test filesystem's birthtime semantics, so the
-    // assertion is shape-only: IF hq-btime is present, it's a numeric
-    // string AND it's distinct from hq-mtime.
-    await uploadFile(makeCtx(), tmpFile, "btime.md");
-
-    const put = sentCommands.find((c) => c.name === "PutObjectCommand");
-    const meta = put!.input.Metadata as Record<string, string> | undefined;
-    const btime = meta?.[FILE_BTIME_META_KEY];
-    const mtime = meta?.[FILE_MTIME_META_KEY];
-    if (typeof btime === "string") {
-      expect(btime).toMatch(/^[0-9]{1,16}$/);
-      expect(btime).not.toBe(mtime);
-    }
-  });
-
-  it("does NOT stamp hq-mtime / hq-btime for symlinks (uploadFile branch)", async () => {
-    // uploadFile is the regular-file path; uploadSymlink is the symlink
-    // path. uploadFile's lstat.isSymbolicLink() guard skips ALL three of
-    // mode + mtime + btime stamping for symlinks, mirroring the existing
-    // hq-mode policy: symlink times are OS-controlled and fs.utimesSync
-    // would follow the link and mutate the target. The link is set up
-    // pointing at a real target so fs.readFileSync (which follows links)
-    // doesn't ENOENT before the metadata stamping branch even runs.
-    const targetPath = path.join(os.tmpdir(), `s3-link-target-${Date.now()}-${Math.random()}.txt`);
-    fs.writeFileSync(targetPath, "real-bytes");
-    const linkPath = path.join(os.tmpdir(), `s3-link-test-${Date.now()}-${Math.random()}.lnk`);
-    fs.symlinkSync(targetPath, linkPath);
-
-    await uploadFile(makeCtx(), linkPath, "link.md");
-
-    const put = sentCommands.find((c) => c.name === "PutObjectCommand");
-    const meta = put!.input.Metadata as Record<string, string> | undefined;
-    expect(meta?.[FILE_MTIME_META_KEY]).toBeUndefined();
-    expect(meta?.[FILE_BTIME_META_KEY]).toBeUndefined();
-
-    fs.unlinkSync(linkPath);
-    fs.unlinkSync(targetPath);
-  });
-
-  it("elides non-ASCII or empty author fields rather than throwing", async () => {
-    // S3 user-defined metadata must be ASCII-only and total ≤ 2KB. Partial
-    // attribution beats hard failure — values that fail the printable check
-    // are dropped silently.
-    await uploadFile(makeCtx(), tmpFile, "partial.md", {
-      userSub: "  ",
-      email: "user@example.com",
-    });
-
-    const put = sentCommands.find((c) => c.name === "PutObjectCommand");
-    const meta = put!.input.Metadata as Record<string, string>;
-    expect(meta["created-by"]).toBe("user@example.com");
-    expect(meta["created-by-sub"]).toBeUndefined();
-  });
-});
-
-describe("listRemoteFiles", () => {
-  beforeEach(() => {
-    sentCommands.length = 0;
-    nextListObjectsResponse = { Contents: [] };
-  });
-
-  // Regression: pre-fix, `if (!obj.Key || !obj.Size) continue;` skipped every
-  // 0-byte object on the listing. The user's personal vault stored
-  // `projects/.gitkeep` (a 0-byte placeholder) and the sync pull plan never
-  // saw it — the file existed on S3 but was invisible to the runner, so the
-  // box never created `projects/` on first pull. The fix narrows the guard
-  // to `if (!obj.Key) continue;` so Size === 0 passes through with its real
-  // value (handled `?? 0` to keep TS Size?: number happy).
-  it("includes 0-byte objects in the result (no implicit skip-on-empty)", async () => {
-    nextListObjectsResponse = {
-      Contents: [
-        { Key: "projects/.gitkeep", Size: 0, LastModified: new Date(), ETag: '"d41d8cd98f00b204e9800998ecf8427e"' },
-        { Key: "AGENTS.md", Size: 100, LastModified: new Date(), ETag: '"e1"' },
-      ],
-    };
-
-    const files = await listRemoteFiles(makeCtx());
-
-    expect(files).toHaveLength(2);
-    const gitkeep = files.find((f) => f.key === "projects/.gitkeep");
-    expect(gitkeep).toBeDefined();
-    expect(gitkeep!.size).toBe(0);
-  });
-
-  it("still skips Contents entries with no Key (defensive against malformed responses)", async () => {
-    nextListObjectsResponse = {
-      Contents: [
-        { Size: 100, LastModified: new Date(), ETag: '"e1"' }, // no Key
-        { Key: "real.md", Size: 100, LastModified: new Date(), ETag: '"e2"' },
-      ],
-    };
-
-    const files = await listRemoteFiles(makeCtx());
-
-    expect(files).toHaveLength(1);
-    expect(files[0].key).toBe("real.md");
-  });
-
-  // Regression: pre-fix, the 0-byte-guard relaxation (`if (!obj.Key) continue;`
-  // replacing `if (!obj.Key || !obj.Size) continue;`) was correct for
-  // legitimate placeholder files like `.gitkeep` but accidentally also let
-  // S3 directory-marker objects (0-byte, key ends in `/`) through to the
-  // planner. Two downstream sites blow up on those:
-  //   1. pull planner (cli/sync.ts `computePullPlan`): for any marker whose
-  //      `path.join(root, key)` resolves to an existing local directory,
-  //      `localExists=true` → `hashFile(localPath)` → `readFileSync` on dir
-  //      → EISDIR "read". The runner reported this for `personal:(company)`.
-  //   2. download path (s3.ts `downloadFile`): for any marker whose local
-  //      path doesn't exist, the planner classifies it `download`;
-  //      `mkdirSync(path.dirname(localPath), recursive)` strips the trailing
-  //      slash and creates the leaf as a directory, then `writeFileSync`
-  //      on the trailing-slash path → EISDIR "open". The runner reported
-  //      this for `indigo:lambda/`.
-  // The fix drops the *definitional* marker shape (trailing-slash AND
-  // size 0) at this site so neither path ever sees them. Real 0-byte
-  // placeholders (`.gitkeep`) never end in `/` and continue to flow
-  // through — covered by the test immediately above.
-  it("drops S3 directory-marker keys (trailing '/', size 0) from list results", async () => {
-    nextListObjectsResponse = {
-      Contents: [
-        { Key: "real.md", Size: 42, LastModified: new Date(), ETag: '"e1"' },
-        { Key: "projects/.gitkeep", Size: 0, LastModified: new Date(), ETag: '"e2"' },
-        { Key: "lambda/", Size: 0, LastModified: new Date(), ETag: '"e3"' },
-        { Key: "core/", Size: 0, LastModified: new Date(), ETag: '"e4"' },
-        { Key: "deeply/nested/marker/", Size: 0, LastModified: new Date(), ETag: '"e5"' },
-      ],
-    };
-
-    const files = await listRemoteFiles(makeCtx());
-
-    // Real files (including the 0-byte .gitkeep placeholder) pass through;
-    // every 0-byte trailing-slash marker is dropped.
-    expect(files.map((f) => f.key).sort()).toEqual([
-      "projects/.gitkeep",
-      "real.md",
-    ]);
-  });
-
-  // Codex P2 follow-up: the marker filter must be definitionally
-  // constrained to size-0 trailing-slash keys. A hypothetical non-empty
-  // object whose key ends in `/` (no hq-cloud code path creates one,
-  // but `ListObjectsV2` returns whatever lives in the bucket) must
-  // NOT be silently hidden — that would mask real bucket state from
-  // the operator. Such an object will still surface EISDIR "open" at
-  // downloadFile when the local path is materialized, which is the
-  // signal needed to reconcile.
-  it("does NOT drop non-empty trailing-slash keys (preserves operator visibility)", async () => {
-    nextListObjectsResponse = {
-      Contents: [
-        { Key: "real.md", Size: 42, LastModified: new Date(), ETag: '"e1"' },
-        // 0-byte marker — filtered.
-        { Key: "marker/", Size: 0, LastModified: new Date(), ETag: '"e2"' },
-        // Non-zero, trailing slash — pathological but unfiltered so it
-        // stays visible. (Cannot be materialized locally; downloadFile
-        // will raise an explicit error pointing at this exact key.)
-        { Key: "exports/report/", Size: 1024, LastModified: new Date(), ETag: '"e3"' },
-      ],
-    };
-
-    const files = await listRemoteFiles(makeCtx());
-
-    expect(files.map((f) => f.key).sort()).toEqual([
-      "exports/report/",
-      "real.md",
-    ]);
-    // Spot-check that the non-empty marker carried its real size.
-    expect(files.find((f) => f.key === "exports/report/")!.size).toBe(1024);
-  });
-});
-
-describe("uploadSymlink", () => {
-  beforeEach(() => {
-    sentCommands.length = 0;
-  });
-
-  it("PUTs the prefixed target as the body bytes and a marker-only metadata flag", async () => {
-    // Body = SYMLINK_BODY_PREFIX + target is the source of truth for
-    // the target string and is load-bearing for two distinct
-    // drift-detection properties:
-    //   1. S3 ETag = MD5(body) varies with target → cross-machine
-    //      target-change propagation works through LIST etags.
-    //   2. The prefix means a symlink to "bar.md" doesn't share an
-    //      ETag with a regular file containing "bar.md" → symlink ↔
-    //      regular-file transitions on the same key are visible to
-    //      peers via LIST.
-    // The metadata is now a fixed marker only — we used to store the
-    // base64'd target there, but S3's 2 KiB header limit made that
-    // brittle for long POSIX targets. Marker-only is bounded.
-    const target = "../real-target.md";
-    await uploadSymlink(makeCtx(), target, "policies/link.md");
-
-    const put = sentCommands.find((c) => c.name === "PutObjectCommand");
-    expect(put).toBeDefined();
-    const meta = put!.input.Metadata as Record<string, string>;
-    expect(meta["hq-symlink-target"]).toBe(SYMLINK_MARKER_META_VALUE);
-    expect(put!.input.Body).toBeDefined();
-    const body = put!.input.Body as Buffer | Uint8Array;
-    expect(Buffer.from(body).toString("utf-8")).toBe(SYMLINK_BODY_PREFIX + target);
-    expect(put!.input.Key).toBe("policies/link.md");
-  });
-
-  it("handles arbitrary Unicode targets via the body (metadata stays marker-only)", async () => {
-    // Codex round-9 P2 follow-up: S3 user-metadata is HTTP-header-
-    // bound. A POSIX symlink target can include any Unicode bytes;
-    // storing the target in metadata risked PutObject rejecting it.
-    // Now the body carries the target — UTF-8 bytes pass through
-    // S3 object content unmolested, no ASCII restriction, no header
-    // limit. Metadata stays as the constant marker.
-    sentCommands.length = 0;
-    const unicodeTarget = "café/🌳/Übung.md";
-    await uploadSymlink(makeCtx(), unicodeTarget, "weird-link.md");
-
-    const put = sentCommands.find((c) => c.name === "PutObjectCommand");
-    expect(put).toBeDefined();
-    const meta = put!.input.Metadata as Record<string, string>;
-    expect(meta["hq-symlink-target"]).toBe(SYMLINK_MARKER_META_VALUE);
-    const body = Buffer.from(put!.input.Body as Buffer | Uint8Array).toString(
-      "utf-8",
-    );
-    expect(body).toBe(SYMLINK_BODY_PREFIX + unicodeTarget);
-  });
-
-  it("handles long targets without exceeding S3's 2 KiB user-metadata limit", async () => {
-    // Codex round-13 P2 follow-up: pre-fix, the metadata value was
-    // base64(target) plus author fields plus the metadata key name.
-    // A target around 1.5 KiB after base64 inflation could push the
-    // total over S3's 2 KiB user-metadata cap and PutObject would
-    // reject the upload. With marker-only metadata, the target's
-    // size only contributes to the body — bounded by S3's 5 GB
-    // object size, not the header limit. Verify a 4 KiB target (well
-    // beyond the old breaking point) round-trips cleanly.
-    sentCommands.length = 0;
-    const longTarget = "deeply/nested/" + "x".repeat(4096);
-    await uploadSymlink(makeCtx(), longTarget, "long-link.md");
-
-    const put = sentCommands.find((c) => c.name === "PutObjectCommand");
-    const meta = put!.input.Metadata as Record<string, string>;
-    expect(meta["hq-symlink-target"]).toBe(SYMLINK_MARKER_META_VALUE);
-    const body = Buffer.from(put!.input.Body as Buffer | Uint8Array).toString(
-      "utf-8",
-    );
-    expect(body).toBe(SYMLINK_BODY_PREFIX + longTarget);
-    // Sanity: marker fits in the header limit by an enormous margin
-    // (1 byte vs 2048).
-    expect(meta["hq-symlink-target"].length).toBeLessThan(10);
-  });
-
-  it("encodeSymlinkMetadataValue / decodeSymlinkMetadataValue round-trip arbitrary UTF-8", async () => {
-    // Direct property test of the helpers — covers the legacy-fallback
-    // path via the round-trip check inside decodeSymlinkMetadataValue.
-    for (const sample of [
-      "",
-      "real.md",
-      "../sibling/file.md",
-      "café/🌳/Übung.md",
-      "/absolute/path/with spaces.md",
-      "deeply/nested/path/" + "x".repeat(200),
-    ]) {
-      expect(decodeSymlinkMetadataValue(encodeSymlinkMetadataValue(sample))).toBe(sample);
-    }
-    // Legacy-fallback: a value that isn't valid base64 of UTF-8 (e.g.
-    // a raw target written by a pre-PR uploader) round-trips as-is.
-    // "real.md" happens to NOT be valid base64 (length not multiple
-    // of 4), so the decoder falls through to returning it raw.
-    expect(decodeSymlinkMetadataValue("real.md")).toBe("real.md");
-  });
-
-  it("produces a different body (and therefore a different S3 ETag) when target changes", async () => {
-    // Direct regression for the cross-machine target-propagation bug:
-    // two uploads with different targets must produce different bodies
-    // so S3-side etag comparison can detect the change. We assert on
-    // the body bytes rather than asking S3 for an ETag (the fake
-    // returns a constant ETag) — equality of body bytes is a necessary
-    // and sufficient property for ETag equality on PutObject.
-    sentCommands.length = 0;
-    await uploadSymlink(makeCtx(), "old-target.md", "policies/link.md");
-    await uploadSymlink(makeCtx(), "new-target.md", "policies/link.md");
-    const puts = sentCommands.filter((c) => c.name === "PutObjectCommand");
-    expect(puts).toHaveLength(2);
-    const bodies = puts.map((p) =>
-      Buffer.from(p.input.Body as Buffer | Uint8Array).toString("utf-8"),
-    );
-    expect(bodies[0]).not.toBe(bodies[1]);
-    expect(bodies[0]).toBe(SYMLINK_BODY_PREFIX + "old-target.md");
-    expect(bodies[1]).toBe(SYMLINK_BODY_PREFIX + "new-target.md");
-  });
-
-  it("produces a different body from a regular file containing the same target string (ETag distinguishability)", async () => {
-    // Codex round-4 P2 follow-up: pre-fix, a symlink whose target
-    // string equaled some regular file's exact contents produced an
-    // identical S3 ETag (since ETag = MD5(body) and bodies were equal).
-    // The LIST-based pull planner can't see per-object metadata, so
-    // it would classify a symlink ↔ regular-file transition on the
-    // same key as "no change" and never replace the local
-    // representation. The SYMLINK_BODY_PREFIX makes the bodies
-    // distinguishable for any realistic regular-file content.
-    sentCommands.length = 0;
-    const sharedString = "real.md";
-    // Make a regular file whose contents are exactly the target string
-    // — the worst-case collision shape pre-prefix.
-    const localFile = path.join(
-      os.tmpdir(),
-      `etag-distinguishability-${Date.now()}-${Math.random()}.md`,
-    );
-    fs.writeFileSync(localFile, sharedString);
-
-    await uploadSymlink(makeCtx(), sharedString, "case-key.md");
-    await uploadFile(makeCtx(), localFile, "regular-key.md");
-    fs.rmSync(localFile, { force: true });
-
-    const puts = sentCommands.filter((c) => c.name === "PutObjectCommand");
-    expect(puts).toHaveLength(2);
-    const symlinkBody = Buffer.from(
-      puts[0].input.Body as Buffer | Uint8Array,
-    ).toString("utf-8");
-    const regularBody = Buffer.from(
-      puts[1].input.Body as Buffer | Uint8Array,
-    ).toString("utf-8");
-
-    // The point of the prefix: symlink record body ≠ regular file body
-    // even when they describe the same string. Different bytes ⇒
-    // different MD5 ⇒ different S3 ETag ⇒ pull planner detects the
-    // transition via LIST without needing a per-object HEAD.
-    expect(symlinkBody).not.toBe(regularBody);
-    expect(regularBody).toBe(sharedString);
-    expect(symlinkBody).toBe(SYMLINK_BODY_PREFIX + sharedString);
-  });
-
-  it("forwards UploadAuthor alongside the symlink-target metadata", async () => {
-    await uploadSymlink(makeCtx(), "real.md", "policies/link.md", {
-      userSub: "abc-123",
-      email: "alice@example.com",
-    });
-
-    const put = sentCommands.find((c) => c.name === "PutObjectCommand");
-    const meta = put!.input.Metadata as Record<string, string>;
-    // Marker-only metadata; target lives in the body.
-    expect(meta["hq-symlink-target"]).toBe(SYMLINK_MARKER_META_VALUE);
-    const body = Buffer.from(put!.input.Body as Buffer | Uint8Array).toString(
-      "utf-8",
-    );
-    expect(body).toBe(SYMLINK_BODY_PREFIX + "real.md");
-    expect(meta["created-by"]).toBe("alice@example.com");
-    expect(meta["created-by-sub"]).toBe("abc-123");
-  });
-});
-
-describe("createStagedSymlink", () => {
-  it("uses an absolute junction for a Windows directory without requiring symlink privilege", () => {
-    const linkPath = path.join(path.sep, "vault", ".agents", "skills");
-    const target = "../.claude/skills";
-    const absTarget = path.resolve(path.dirname(linkPath), target);
-    const symlink = vi.fn(
-      (_target: string, _linkPath: string, type?: fs.symlink.Type) => {
-        if (type !== "junction") {
-          throw Object.assign(new Error("operation not permitted, symlink"), {
-            code: "EPERM",
-          });
-        }
-      },
-    );
-
-    expect(() =>
-      createStagedSymlink(target, linkPath, {
-        platform: "win32",
-        symlink,
-        statIsDirectory: () => true,
-      }),
-    ).not.toThrow();
-    expect(symlink).toHaveBeenCalledWith(absTarget, linkPath, "junction");
-    expect(path.isAbsolute(symlink.mock.calls[0]![0])).toBe(true);
-  });
-
-  it("resolves a relative Windows overlay target before creating a junction", () => {
-    const linkPath = path.join(path.sep, "vault", ".codex", "claude");
-    const target = "../.claude/skills";
-    const symlink = vi.fn();
-
-    createStagedSymlink(target, linkPath, {
-      platform: "win32",
-      symlink,
-      statIsDirectory: () => undefined,
-    });
-
-    expect(symlink).toHaveBeenCalledWith(
-      path.resolve(path.dirname(linkPath), target),
-      linkPath,
-      "junction",
-    );
-  });
-
-  it("preserves a relative target and omits the type outside Windows", () => {
-    const linkPath = path.join(path.sep, "vault", ".agents", "skills");
-    const target = "../.claude/skills";
-    const symlink = vi.fn();
-    const statIsDirectory = vi.fn(() => true);
-
-    createStagedSymlink(target, linkPath, {
-      platform: "linux",
-      symlink,
-      statIsDirectory,
-    });
-
-    expect(symlink).toHaveBeenCalledWith(target, linkPath);
-    expect(statIsDirectory).not.toHaveBeenCalled();
-  });
-
-  it("uses a genuine Windows file symlink for a regular-file target", () => {
-    const linkPath = path.join(path.sep, "vault", "config-link.json");
-    const target = "../shared/config.json";
-    const absTarget = path.resolve(path.dirname(linkPath), target);
-    const symlink = vi.fn();
-    const statIsDirectory = vi.fn(() => false);
-
-    createStagedSymlink(target, linkPath, {
-      platform: "win32",
-      symlink,
-      statIsDirectory,
-    });
-
-    expect(statIsDirectory).toHaveBeenCalledWith(absTarget);
-    expect(symlink).toHaveBeenCalledWith(target, linkPath, "file");
-  });
-});
-
-describe("downloadFile", () => {
-  let tmpRoot: string;
-
-  beforeEach(() => {
-    sentCommands.length = 0;
-    tmpRoot = fs.mkdtempSync(path.join(os.tmpdir(), "s3-download-test-"));
-  });
-
-  it("materializes a symlink record as a real symlink, sourcing the target from the body", async () => {
-    // Round-13 contract: metadata is just a marker; the body
-    // (after stripping SYMLINK_BODY_PREFIX) is the source of truth
-    // for the target string. downloadFile must consume the body
-    // and use the post-prefix slice as the link target.
-    const target = "../real-target.md";
-    nextGetObjectResponse = {
-      Body: (async function* () {
-        yield new TextEncoder().encode(SYMLINK_BODY_PREFIX + target);
-      })(),
-      Metadata: { "hq-symlink-target": SYMLINK_MARKER_META_VALUE },
-    };
-
-    const localPath = path.join(tmpRoot, "policies", "link.md");
-    await downloadFile(makeCtx(), "policies/link.md", localPath);
-
-    const lstat = fs.lstatSync(localPath);
-    expect(lstat.isSymbolicLink()).toBe(true);
-    expect(fs.readlinkSync(localPath)).toBe(target);
-  });
-
-  it("skips (typed, non-fatal) when the parent directory is a DANGLING symlink", async () => {
-    // The vault stores directory symlinks as objects (e.g.
-    // companies/<co>/.obsidian -> ../../.obsidian) AND files beneath them. On a
-    // machine where the link target is absent, mkdir of the parent throws
-    // ENOENT — not EEXIST — because mkdir(2) returns EEXIST for the link and
-    // Node's recursive impl then stats it, which fails on a dangling link.
-    // Raw, that marked the WHOLE company errored/partial on every sync cycle
-    // (2026-07-24 dogfood box). It must be a typed per-object skip instead.
-    nextGetObjectResponse = {
-      Body: (async function* () {
-        yield new TextEncoder().encode("hotkeys");
-      })(),
-      Metadata: {},
-    };
-
-    const parent = path.join(tmpRoot, ".obsidian");
-    fs.symlinkSync(path.join(tmpRoot, "does-not-exist"), parent);
-    // Precondition: existsSync follows the link and reports absent, while
-    // lstat still sees it — the exact shape the fix keys on.
-    expect(fs.existsSync(parent)).toBe(false);
-    expect(fs.lstatSync(parent).isSymbolicLink()).toBe(true);
-
-    await expect(
-      downloadFile(makeCtx(), ".obsidian/hotkeys.json", path.join(parent, "hotkeys.json")),
-    ).rejects.toBeInstanceOf(DanglingSymlinkParentError);
-
-    // The link is left exactly as found — no target materialized outside the
-    // directory being synced, which the caller's containment guard refuses.
-    expect(fs.lstatSync(parent).isSymbolicLink()).toBe(true);
-    expect(fs.existsSync(path.join(tmpRoot, "does-not-exist"))).toBe(false);
-  });
-
-  it("still creates an ordinary missing parent directory", async () => {
-    nextGetObjectResponse = {
-      Body: (async function* () {
-        yield new TextEncoder().encode("plain");
-      })(),
-      Metadata: {},
-    };
-    const localPath = path.join(tmpRoot, "deep", "nested", "file.md");
-    await downloadFile(makeCtx(), "deep/nested/file.md", localPath);
-    expect(fs.readFileSync(localPath, "utf8")).toBe("plain");
-  });
-
-  it("recovers the target from legacy metadata-only uploads (body lacks the prefix)", async () => {
-    // Backward-compat: an in-flight upload from earlier in this
-    // PR's lifetime stored the target in metadata (raw or base64'd)
-    // rather than in the body. downloadFile must fall back to
-    // decoding the metadata value when the body doesn't start with
-    // SYMLINK_BODY_PREFIX. Tested with a base64'd metadata value
-    // and an empty body — the round-trip-validating decoder
-    // should recover the original target.
-    const target = "legacy/target.md";
-    const legacyMetadata = encodeSymlinkMetadataValue(target);
-    nextGetObjectResponse = {
-      Body: (async function* () {
-        yield new Uint8Array(); // empty body, like a v1-of-this-PR upload
-      })(),
-      Metadata: { "hq-symlink-target": legacyMetadata },
-    };
-
-    const localPath = path.join(tmpRoot, "legacy-link.md");
-    await downloadFile(makeCtx(), "legacy-link.md", localPath);
-
-    expect(fs.lstatSync(localPath).isSymbolicLink()).toBe(true);
-    expect(fs.readlinkSync(localPath)).toBe(target);
-  });
-
-  it("recovers a target longer than the legacy 2 KiB metadata limit from the body", async () => {
-    // Codex round-13 P2 motivating case: targets between ~1.5 KiB
-    // (after base64 inflation) and ~5 GiB (S3 object cap) used to
-    // fail PutObject under the metadata-based design but now
-    // round-trip cleanly through the body. We pick 600 chars: well
-    // past the old metadata-only break point (~1500 base64 bytes ≈
-    // ~1100 raw, plus header overhead crosses 2 KiB), and well
-    // under any sane filesystem's PATH_MAX symlink-target limit
-    // (Linux: 4096, macOS: 1024) so the test creates a real link.
-    const longTarget = "deeply/nested/path/" + "x".repeat(600);
-    nextGetObjectResponse = {
-      Body: (async function* () {
-        yield new TextEncoder().encode(SYMLINK_BODY_PREFIX + longTarget);
-      })(),
-      Metadata: { "hq-symlink-target": SYMLINK_MARKER_META_VALUE },
-    };
-
-    const localPath = path.join(tmpRoot, "long-link.md");
-    await downloadFile(makeCtx(), "long-link.md", localPath);
-
-    expect(fs.lstatSync(localPath).isSymbolicLink()).toBe(true);
-    expect(fs.readlinkSync(localPath)).toBe(longTarget);
-  });
-
-  it("falls back to writing a regular file when hq-symlink-target metadata is absent", async () => {
-    nextGetObjectResponse = {
-      Body: (async function* () {
-        yield new Uint8Array([104, 105]); // "hi"
-      })(),
-      Metadata: {},
-    };
-
-    const localPath = path.join(tmpRoot, "regular.md");
-    await downloadFile(makeCtx(), "regular.md", localPath);
-
-    const lstat = fs.lstatSync(localPath);
-    expect(lstat.isSymbolicLink()).toBe(false);
-    expect(fs.readFileSync(localPath, "utf-8")).toBe("hi");
-  });
-
-  it("recovers a symlink from the body prefix when the metadata marker is lost (header-loss fallback)", async () => {
-    // Regression: a transport/replication/console-copy that drops user
-    // metadata — or a poisoned regular-file re-upload of a sentinel —
-    // leaves an object with NO hq-symlink-target marker but a body of
-    // `hq-symlink:<target>`. The read path must honor the body prefix as
-    // a fallback discriminator and rematerialize a real link, NOT write
-    // out the `hq-symlink:` text as a regular file (which poisons the key
-    // on the next push). See s3.ts downloadFile + SYMLINK_BODY_PREFIX doc.
-    const target = "../../../some/real/target.md";
-    nextGetObjectResponse = {
-      Body: (async function* () {
-        yield new TextEncoder().encode(SYMLINK_BODY_PREFIX + target);
-      })(),
-      Metadata: {}, // marker stripped / never set
-    };
-
-    const localPath = path.join(tmpRoot, "marker-lost-link.md");
-    await downloadFile(makeCtx(), "marker-lost-link.md", localPath);
-
-    const lstat = fs.lstatSync(localPath);
-    expect(lstat.isSymbolicLink()).toBe(true);
-    expect(fs.readlinkSync(localPath)).toBe(target);
-  });
-
-  it("replaces a stale local symlink with a regular file when remote transitions symlink → regular", async () => {
-    // Codex P2 follow-up: pre-fix, the regular-file branch went
-    // straight to writeFileSync. If localPath was a stale symlink from
-    // a prior sync (when this key was a symlink in cloud), writeFileSync
-    // would FOLLOW the link and overwrite the link's target file
-    // contents — leaving the link in place and the new "regular file at
-    // localPath" never materializing. The fix: lstat before write; if
-    // the existing entry is a symlink, unlink it first.
-    const localPath = path.join(tmpRoot, "transitioned.md");
-    const targetFile = path.join(tmpRoot, "stale-target.md");
-    fs.writeFileSync(targetFile, "do-not-clobber-me");
-    fs.symlinkSync(targetFile, localPath);
-
-    nextGetObjectResponse = {
-      Body: (async function* () {
-        yield new Uint8Array([110, 101, 119]); // "new"
-      })(),
-      Metadata: {}, // no symlink metadata → regular file path
-    };
-
-    await downloadFile(makeCtx(), "transitioned.md", localPath);
-
-    // localPath is now a regular file with the new content...
-    expect(fs.lstatSync(localPath).isSymbolicLink()).toBe(false);
-    expect(fs.readFileSync(localPath, "utf-8")).toBe("new");
-    // ...and the link's former target was NOT clobbered.
-    expect(fs.readFileSync(targetFile, "utf-8")).toBe("do-not-clobber-me");
-  });
-
-  it("replaces an existing entry when the link is rewritten (target change)", async () => {
-    // Pre-existing regular file at the target location must not block
-    // creation of a symlink — fs.symlinkSync would EEXIST otherwise.
-    // Same applies to a stale symlink whose target has changed: the new
-    // target string must win.
-    const localPath = path.join(tmpRoot, "rewrite.md");
-    fs.writeFileSync(localPath, "stale regular file");
-
-    nextGetObjectResponse = {
-      Body: (async function* () {
-        yield new Uint8Array();
-      })(),
-      Metadata: { "hq-symlink-target": "fresh-target.md" },
-    };
-
-    await downloadFile(makeCtx(), "rewrite.md", localPath);
-
-    expect(fs.lstatSync(localPath).isSymbolicLink()).toBe(true);
-    expect(fs.readlinkSync(localPath)).toBe("fresh-target.md");
-  });
-
-  it("F11: failed symlink downloads preserve the previous local file", async () => {
-    const localPath = path.join(tmpRoot, "preserve-on-failure.md");
-    fs.writeFileSync(localPath, "existing local copy");
-
-    nextGetObjectResponse = {
-      Body: (async function* () {
-        yield new TextEncoder().encode(SYMLINK_BODY_PREFIX + "x".repeat(10_000));
-      })(),
-      Metadata: { "hq-symlink-target": SYMLINK_MARKER_META_VALUE },
-    };
-
-    await expect(
-      downloadFile(makeCtx(), "preserve-on-failure.md", localPath),
-    ).rejects.toThrow();
-
-    expect(fs.existsSync(localPath)).toBe(true);
-    expect(fs.lstatSync(localPath).isSymbolicLink()).toBe(false);
-    expect(fs.readFileSync(localPath, "utf-8")).toBe("existing local copy");
-  });
-
-  it("replaces an existing directory link without changing its target", async () => {
-    const targetDir = path.join(tmpRoot, "generated-skill-source");
-    const localPath = path.join(tmpRoot, "generated-skill-link");
-    fs.mkdirSync(targetDir);
-    fs.writeFileSync(path.join(targetDir, "sentinel.txt"), "source-owned");
-    fs.symlinkSync(targetDir, localPath, "dir");
-
-    nextGetObjectResponse = {
-      Body: (async function* () {
-        yield Buffer.from("remote replacement");
-      })(),
-      Metadata: {},
-    };
-
-    await downloadFile(makeCtx(), "generated-skill-link", localPath);
-
-    expect(fs.lstatSync(localPath).isSymbolicLink()).toBe(false);
-    expect(fs.readFileSync(localPath, "utf8")).toBe("remote replacement");
-    expect(fs.readFileSync(path.join(targetDir, "sentinel.txt"), "utf8")).toBe(
-      "source-owned",
-    );
-  });
-
-  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");
-    const stagedPath = path.join(tmpRoot, ".hq-tmp-rollback-test");
-    fs.mkdirSync(targetDir);
-    fs.symlinkSync(targetDir, localPath, "dir");
-    fs.writeFileSync(stagedPath, "staged replacement");
-
-    let renameCalls = 0;
-    expect(() =>
-      replaceStagedPath(stagedPath, localPath, {
-        lstat: (p) => fs.lstatSync(p),
-        rename: (from, to) => {
-          renameCalls++;
-          if (renameCalls === 2) {
-            throw Object.assign(new Error("simulated Windows replacement failure"), {
-              code: "EPERM",
-            });
-          }
-          fs.renameSync(from, to);
-        },
-        remove: (p) => fs.unlinkSync(p),
-      }),
-    ).toThrow("simulated Windows replacement failure");
-
-    expect(renameCalls).toBe(3);
-    expect(fs.lstatSync(localPath).isSymbolicLink()).toBe(true);
-    expect(fs.readlinkSync(localPath)).toBe(targetDir);
-    expect(fs.readFileSync(stagedPath, "utf8")).toBe("staged replacement");
-    expect(
-      fs.readdirSync(tmpRoot).filter((name) => name.startsWith(".hq-backup-")),
-    ).toEqual([]);
-  });
-
-  it("restores an existing directory link when backup cleanup fails", () => {
-    const targetDir = path.join(tmpRoot, "cleanup-rollback-source");
-    const localPath = path.join(tmpRoot, "cleanup-rollback-link");
-    const stagedPath = path.join(tmpRoot, ".hq-tmp-cleanup-rollback-test");
-    fs.mkdirSync(targetDir);
-    fs.symlinkSync(targetDir, localPath, "dir");
-    fs.writeFileSync(stagedPath, "staged replacement");
-
-    let renameCalls = 0;
-    expect(() =>
-      replaceStagedPath(stagedPath, localPath, {
-        lstat: (p) => fs.lstatSync(p),
-        rename: (from, to) => {
-          renameCalls++;
-          fs.renameSync(from, to);
-        },
-        remove: () => {
-          throw Object.assign(new Error("simulated backup cleanup failure"), {
-            code: "EPERM",
-          });
-        },
-      }),
-    ).toThrow("simulated backup cleanup failure");
-
-    expect(renameCalls).toBe(4);
-    expect(fs.lstatSync(localPath).isSymbolicLink()).toBe(true);
-    expect(fs.readlinkSync(localPath)).toBe(targetDir);
-    expect(fs.readFileSync(stagedPath, "utf8")).toBe("staged replacement");
-    expect(
-      fs.readdirSync(tmpRoot).filter((name) => name.startsWith(".hq-backup-")),
-    ).toEqual([]);
-  });
-
-  it("R-F11: downloads to a near component-limit basename via a bounded temp name", async () => {
-    nextGetObjectResponse = {
-      Body: (async function* () {
-        yield Buffer.from("near-limit bytes");
-      })(),
-      Metadata: {},
-    };
-
-    const localPath = path.join(tmpRoot, "x".repeat(240));
-    await downloadFile(makeCtx(), "near-limit.bin", localPath);
-
-    expect(fs.readFileSync(localPath, "utf-8")).toBe("near-limit bytes");
-  });
-
-  it("F20: regular downloads do not decode the full body as UTF-8", async () => {
-    const body = Buffer.alloc(64 * 1024, 0x61);
-    const originalToString = body.toString;
-    body.toString = ((encoding?: BufferEncoding, start?: number, end?: number) => {
-      const sliceStart = start ?? 0;
-      const sliceEnd = end ?? body.length;
-      if (sliceEnd - sliceStart > SYMLINK_BODY_PREFIX.length) {
-        throw new Error("full-body UTF-8 decode attempted");
-      }
-      return originalToString.call(body, encoding, start, end);
-    }) as Buffer["toString"];
-
-    const io: ObjectIO = {
-      putObject: async () => ({ etag: '"unused"' }),
-      getObject: async () => ({ body, metadata: {} }),
-      listObjects: async () => ({ objects: [] }),
-      deleteObject: async () => undefined,
-      headObject: async () => null,
-    };
-
-    const localPath = path.join(tmpRoot, "large-regular.bin");
-    setObjectIOFactory(() => io);
-    try {
-      await downloadFile(makeCtx(), "large-regular.bin", localPath);
-    } finally {
-      setObjectIOFactory(null);
-    }
-
-    const written = fs.readFileSync(localPath);
-    expect(written.length).toBe(body.length);
-    expect(written[0]).toBe(0x61);
-    expect(written[written.length - 1]).toBe(0x61);
-  });
-
-  it("R-F20: streams regular downloads with hash metadata and still detects symlink records", async () => {
-    const regularChunks = [
-      Buffer.from("alpha-"),
-      Buffer.from("beta-"),
-      Buffer.from("gamma"),
-    ];
-    const regularBody = Buffer.concat(regularChunks);
-    const linkTarget = "../target.md";
-
-    const io: ObjectIO = {
-      putObject: async () => ({ etag: '"unused"' }),
-      getObject: async () => {
-        throw new Error("buffered getObject attempted");
-      },
-      getObjectStream: async (key: string) => {
-        if (key === "streamed-link") {
-          return {
-            body: (async function* () {
-              yield Buffer.from("hq-");
-              yield Buffer.from("symlink:");
-              yield Buffer.from(linkTarget);
-            })(),
-            metadata: {},
-          };
-        }
-        return {
-          body: (async function* () {
-            for (const chunk of regularChunks) yield chunk;
-          })(),
-          metadata: {},
-        };
-      },
-      listObjects: async () => ({ objects: [] }),
-      deleteObject: async () => undefined,
-      headObject: async () => null,
-    };
-
-    setObjectIOFactory(() => io);
-    try {
-      const localPath = path.join(tmpRoot, "streamed.bin");
-      const result = await downloadFile(makeCtx(), "streamed.bin", localPath);
-      expect(fs.readFileSync(localPath)).toEqual(regularBody);
-      expect(result.contentHash).toBe(
-        crypto.createHash("sha256").update(regularBody).digest("hex"),
-      );
-      expect(result.contentSize).toBe(regularBody.length);
-
-      const linkPath = path.join(tmpRoot, "streamed-link");
-      await downloadFile(makeCtx(), "streamed-link", linkPath);
-      expect(fs.lstatSync(linkPath).isSymbolicLink()).toBe(true);
-      expect(fs.readlinkSync(linkPath)).toBe(linkTarget);
-    } finally {
-      setObjectIOFactory(null);
-    }
-  });
-
-  it("applies hq-mode metadata via chmod after byte write (Bug #5 — preserve permissions)", async () => {
-    // Round-trip pair to the s3.upload test: source-side mode lives in
-    // \`Metadata['hq-mode']\` as an octal string; the receiver must chmod
-    // the file to that exact mode after writing the bytes. Pre-fix the
-    // receiver took the umask default and 0755 scripts arrived 0644.
-    nextGetObjectResponse = {
-      Body: (async function* () {
-        yield new Uint8Array([35, 33, 47, 98, 105, 110]); // "#!/bin"
-      })(),
-      Metadata: { "hq-mode": "755" },
-    };
-
-    const localPath = path.join(tmpRoot, "exec.sh");
-    await downloadFile(makeCtx(), "exec.sh", localPath);
-
-    // mask to permission bits — the upper bits encode file-type (S_IFREG)
-    // and are not preserved on chmod.
-    const stat = fs.statSync(localPath);
-    expect((stat.mode & 0o777).toString(8)).toBe("755");
-  });
-
-  it("rounds-trips multiple modes (0600/0640/0700/0750/0755) via hq-mode", async () => {
-    // Verification report V5 multi-mode pin: every mode collapsed to 0644
-    // because the receiver had no mode signal at all. With \`hq-mode\` in
-    // metadata, all five modes must arrive at their exact source value.
-    for (const octal of ["600", "640", "700", "750", "755"]) {
-      nextGetObjectResponse = {
-        Body: (async function* () {
-          yield new Uint8Array([97]); // "a"
-        })(),
-        Metadata: { "hq-mode": octal },
-      };
-      const localPath = path.join(tmpRoot, `mode-${octal}.bin`);
-      await downloadFile(makeCtx(), `mode-${octal}.bin`, localPath);
-      expect((fs.statSync(localPath).mode & 0o777).toString(8)).toBe(octal);
-    }
-  });
-
-  it("rejects malformed hq-mode metadata via strict-octal regex (Codex P2)", async () => {
-    // Codex review on PR #24 caught: parseInt(modeOctal, 8) accepts
-    // partial-prefix garbage — "755junk" parses to 0o755 instead of
-    // NaN — so tampered or malformed metadata could still chmod the
-    // local file. Strict regex MUST reject anything that isn't pure
-    // octal digits before parseInt sees it; the file then arrives at
-    // umask default like the legacy back-compat path.
-    const malformed = [
-      "755junk", // trailing garbage — parseInt parses 0o755 pre-fix
-      "0x755",   // hex-looking prefix
-      "8",       // out-of-octal-range digit
-      "9",       // ditto
-      "-755",    // signed
-      "abc",     // non-numeric
-      "",        // empty
-      "7777",    // mode > 0o777 after parse
-      "12345",   // too long (more than 4 octal digits)
-      "  755 ",  // whitespace
-    ];
-    for (const bad of malformed) {
-      nextGetObjectResponse = {
-        Body: (async function* () {
-          yield new Uint8Array([116]); // "t"
-        })(),
-        Metadata: { "hq-mode": bad },
-      };
-      const localPath = path.join(tmpRoot, `bad-${malformed.indexOf(bad)}.bin`);
-      await downloadFile(makeCtx(), `bad-${malformed.indexOf(bad)}.bin`, localPath);
-      // Mode MUST be the umask default (whatever the test process inherits),
-      // NOT a partial-parse of the malformed string. Specifically, even if
-      // the malformed string would partial-parse to 0755, the file must NOT
-      // arrive at 0755 — it must take the umask default. We can't pin the
-      // exact default value (test runner umask varies), but we can pin that
-      // a partial-parse value (0o755) does NOT match for "755junk" cases.
-      const mode = (fs.statSync(localPath).mode & 0o777);
-      // Heuristic: if the parsed mode would have been 0o755, fail loudly.
-      // (umask default on most CI runners is 0o644 or 0o664, never 0o755.)
-      if (bad.startsWith("755") || bad === "0x755") {
-        expect(mode).not.toBe(0o755);
-      }
-    }
-  });
-
-  it("downloads with default umask permissions when hq-mode metadata is absent (back-compat)", async () => {
-    // Legacy uploads from pre-fix engines have no \`hq-mode\` metadata.
-    // The receiver must NOT crash and must NOT change the mode — let
-    // the OS default apply, mirroring the pre-fix behavior.
-    nextGetObjectResponse = {
-      Body: (async function* () {
-        yield new Uint8Array([108, 101, 103, 97, 99, 121]); // "legacy"
-      })(),
-      Metadata: {},
-    };
-
-    const localPath = path.join(tmpRoot, "legacy.bin");
-    await expect(
-      downloadFile(makeCtx(), "legacy.bin", localPath),
-    ).resolves.toBeDefined();
-    // No assertion on mode — receiver default is whatever umask set.
-    expect(fs.readFileSync(localPath, "utf-8")).toBe("legacy");
-  });
-
-  it("applies hq-mtime via utimesSync after byte write (5.37.0 — preserve mtime)", async () => {
-    // Round-trip pair to the s3.upload mtime stamp test. The receiver must
-    // set the local file's mtime to the metadata-stamped value AFTER the
-    // byte write, mirroring the chmod-after-write shape from Bug #5.
-    const knownMs = 1_700_000_000_000;
-    nextGetObjectResponse = {
-      Body: (async function* () {
-        yield new Uint8Array([116, 105, 109, 101]); // "time"
-      })(),
-      Metadata: { [FILE_MTIME_META_KEY]: String(knownMs) },
-    };
-
-    const localPath = path.join(tmpRoot, "mtime-applied.bin");
-    await downloadFile(makeCtx(), "mtime-applied.bin", localPath);
-
-    const stat = fs.statSync(localPath);
-    // ±50ms tolerance accommodates ms-precision filesystems and the
-    // utimesSync→stat round-trip rounding. macOS APFS reports full ms;
-    // some Linux filesystems round to seconds — guard with tolerance.
-    expect(Math.abs(stat.mtimeMs - knownMs)).toBeLessThanOrEqual(50);
-  });
-
-  it("rejects malformed hq-mtime metadata via strict-numeric regex", async () => {
-    // Symmetric to the hq-mode Codex P2 lesson: parseInt accepts partial-
-    // prefix garbage ("175junk" → 175). A strict `^[0-9]{1,16}$` regex
-    // BEFORE parseInt rejects empty / signed / decimals / whitespace /
-    // oversized / non-numeric and falls through to "no utimes call,"
-    // leaving the file at write-time mtime — the legacy back-compat path.
-    // NOTE: `-100` is intentionally NOT in this list — Codex PR #27 P2 pointed
-    // out that legitimate epoch values include 0 (Unix epoch) and negatives
-    // (e.g. reproducible-build clamping pre-1970). Negative-but-well-formed
-    // strings are now accepted; see the dedicated round-trip tests below.
-    const malformed = [
-      "175junk",   // trailing garbage — parseInt parses 175 pre-fix
-      "abc",       // non-numeric
-      "",          // empty
-      "  100  ",   // whitespace
-      "--100",     // double-sign — only ONE optional leading "-" allowed
-      "+100",      // explicit plus rejected (regex only allows optional "-")
-      "3.14",      // decimal
-      "99999999999999999", // >16 digits
-    ];
-    for (const bad of malformed) {
-      // Establish a known pre-write mtime by writing the file first.
-      const localPath = path.join(tmpRoot, `bad-mtime-${malformed.indexOf(bad)}.bin`);
-      nextGetObjectResponse = {
-        Body: (async function* () {
-          yield new Uint8Array([98]); // "b"
-        })(),
-        Metadata: { [FILE_MTIME_META_KEY]: bad },
-      };
-      const before = Date.now();
-      await downloadFile(makeCtx(), `bad-mtime-${malformed.indexOf(bad)}.bin`, localPath);
-      const stat = fs.statSync(localPath);
-      // The file's mtime MUST be wall-clock-now (write-time), NOT the
-      // partial-parse value. For "175junk", that means mtime is in the
-      // current millis range, not ms=175 (1970-01-01T00:00:00.175Z).
-      // Generic check: mtime is near `before` (within 5s).
-      expect(Math.abs(stat.mtimeMs - before)).toBeLessThan(5000);
-      // Specific check: never the partial-parse epoch (~175ms after epoch).
-      expect(stat.mtimeMs).toBeGreaterThan(1_000_000_000_000);
-    }
-  });
-
-  it("round-trips mtimeMs === 0 (Unix epoch — Codex PR #27 P2)", async () => {
-    // Codex flagged that filtering `mtimeMs > 0` drops legitimate epoch-0
-    // timestamps (and reproducible-build clamping uses exactly 0). The
-    // receiver must accept "0", parse it, and stamp `new Date(0)` on disk.
-    const sourcePath = path.join(tmpRoot, "epoch-zero-src.bin");
-    fs.writeFileSync(sourcePath, "epoch-bytes");
-    fs.utimesSync(sourcePath, new Date(0), new Date(0));
-
-    sentCommands.length = 0;
-    await uploadFile(makeCtx(), sourcePath, "epoch-zero.bin");
-    const put = sentCommands.find((c) => c.name === "PutObjectCommand");
-    const stampedMeta = put!.input.Metadata as Record<string, string>;
-    const stampedBody = put!.input.Body as Buffer;
-    expect(stampedMeta[FILE_MTIME_META_KEY]).toBe("0");
-
-    fs.unlinkSync(sourcePath);
-    nextGetObjectResponse = {
-      Body: (async function* () {
-        yield new Uint8Array(stampedBody);
-      })(),
-      Metadata: stampedMeta,
-    };
-    await downloadFile(makeCtx(), "epoch-zero.bin", sourcePath);
-
-    const stat = fs.statSync(sourcePath);
-    // 0 is integer-clean — exact match expected, but allow 50ms tolerance
-    // for any underlying FS rounding shenanigans.
-    expect(Math.abs(stat.mtimeMs - 0)).toBeLessThanOrEqual(50);
-    expect(fs.readFileSync(sourcePath, "utf-8")).toBe("epoch-bytes");
-  });
-
-  it("round-trips a negative mtime (pre-epoch — Codex PR #27 P2)", async () => {
-    // Some filesystems / reproducible-build pipelines clamp mtime to values
-    // before the Unix epoch (negative ms). `new Date(-86400000)` is a legal
-    // Date; `fs.utimesSync` accepts it. The receiver MUST NOT drop these.
-    const sourceMs = -86_400_000; // 1969-12-31T00:00:00Z, one day before epoch
-    const sourcePath = path.join(tmpRoot, "pre-epoch-src.bin");
-    fs.writeFileSync(sourcePath, "pre-epoch-bytes");
-    fs.utimesSync(sourcePath, new Date(sourceMs), new Date(sourceMs));
-
-    sentCommands.length = 0;
-    await uploadFile(makeCtx(), sourcePath, "pre-epoch.bin");
-    const put = sentCommands.find((c) => c.name === "PutObjectCommand");
-    const stampedMeta = put!.input.Metadata as Record<string, string>;
-    const stampedBody = put!.input.Body as Buffer;
-    expect(stampedMeta[FILE_MTIME_META_KEY]).toBe(String(sourceMs));
-
-    fs.unlinkSync(sourcePath);
-    nextGetObjectResponse = {
-      Body: (async function* () {
-        yield new Uint8Array(stampedBody);
-      })(),
-      Metadata: stampedMeta,
-    };
-    await downloadFile(makeCtx(), "pre-epoch.bin", sourcePath);
-
-    const stat = fs.statSync(sourcePath);
-    expect(Math.abs(stat.mtimeMs - sourceMs)).toBeLessThanOrEqual(50);
-    expect(fs.readFileSync(sourcePath, "utf-8")).toBe("pre-epoch-bytes");
-  });
-
-  it("accepts well-formed negative hq-mtime (e.g. '-100') on download", async () => {
-    // Migration of the old rejection-list case for `-100`. Codex PR #27 P2:
-    // negative epoch-ms values are legitimate; the regex now allows a single
-    // optional leading `-`, and utimesSync handles it.
-    const localPath = path.join(tmpRoot, "negative-mtime.bin");
-    nextGetObjectResponse = {
-      Body: (async function* () {
-        yield new Uint8Array([110]); // "n"
-      })(),
-      Metadata: { [FILE_MTIME_META_KEY]: "-100" },
-    };
-    await downloadFile(makeCtx(), "negative-mtime.bin", localPath);
-
-    const stat = fs.statSync(localPath);
-    // mtime should be ~ -100 ms, NOT wall-clock-now. The old code would have
-    // left this at write-time; the new code applies the negative stamp.
-    expect(Math.abs(stat.mtimeMs - -100)).toBeLessThanOrEqual(50);
-  });
-
-  it("downloads with default mtime when hq-mtime metadata is absent (back-compat)", async () => {
-    // Legacy uploads (pre-5.37.0) carry no hq-mtime header. The receiver
-    // must NOT crash and must NOT alter the on-disk mtime away from the
-    // default `fs.writeFileSync` wall-clock-now behavior. Mirrors the
-    // hq-mode back-compat test.
-    nextGetObjectResponse = {
-      Body: (async function* () {
-        yield new Uint8Array([108, 101, 103]); // "leg"
-      })(),
-      Metadata: {},
-    };
-
-    const before = Date.now();
-    const localPath = path.join(tmpRoot, "legacy-mtime.bin");
-    await downloadFile(makeCtx(), "legacy-mtime.bin", localPath);
-
-    const stat = fs.statSync(localPath);
-    expect(Math.abs(stat.mtimeMs - before)).toBeLessThan(5000);
-    expect(fs.readFileSync(localPath, "utf-8")).toBe("leg");
-  });
-
-  it("does NOT call utimesSync on the symlink branch (5.37.0)", async () => {
-    // fs.utimesSync follows symlinks (mutates the target's mtime, not the
-    // link's). On the symlink branch we must skip the utimes block entirely
-    // so we don't accidentally mutate an unrelated target file. The
-    // symlink record's hq-mtime, if any, is ignored — symlink mtime is
-    // OS-controlled and Node has no stable lutimes API. Easiest verifier:
-    // the link is materialized AND the test doesn't crash.
-    const targetPath = path.join(tmpRoot, "untouched-target.txt");
-    fs.writeFileSync(targetPath, "do-not-touch");
-    const knownTargetMs = 1_500_000_000_000;
-    fs.utimesSync(targetPath, new Date(knownTargetMs), new Date(knownTargetMs));
-
-    const linkPath = path.join(tmpRoot, "the-link");
-    nextGetObjectResponse = {
-      Body: (async function* () {
-        yield Buffer.from(SYMLINK_BODY_PREFIX + "untouched-target.txt");
-      })(),
-      Metadata: {
-        "hq-symlink-target": SYMLINK_MARKER_META_VALUE,
-        // Even if a misbehaving uploader stamped hq-mtime on a symlink
-        // record, the downloader's symlink branch returns BEFORE the
-        // utimes block, so the target's mtime stays at knownTargetMs.
-        [FILE_MTIME_META_KEY]: "1_900_000_000_000",
-      },
-    };
-
-    await downloadFile(makeCtx(), "the-link", linkPath);
-
-    expect(fs.lstatSync(linkPath).isSymbolicLink()).toBe(true);
-    expect(fs.readlinkSync(linkPath)).toBe("untouched-target.txt");
-    // Target's mtime is unchanged — utimes block was skipped.
-    const targetStat = fs.statSync(targetPath);
-    expect(Math.abs(targetStat.mtimeMs - knownTargetMs)).toBeLessThanOrEqual(50);
-  });
-
-  it("round-trips mtime across upload + download (5.37.0 user-visible promise)", async () => {
-    // The whole point of the feature: a file's mtime should follow it
-    // across the wire. Push captures source mtime → metadata; pull applies
-    // metadata → local mtime. This test wires upload's PutObject capture
-    // into download's GetObject response so the contract round-trips end-
-    // to-end through s3.ts without bringing in journal/CLI state.
-    const sourceMs = 1_650_000_000_000; // 2022-04-15T03:33:20Z
-    const sourcePath = path.join(tmpRoot, "round-trip-src.bin");
-    fs.writeFileSync(sourcePath, "round-trip-bytes");
-    fs.utimesSync(sourcePath, new Date(sourceMs), new Date(sourceMs));
-
-    sentCommands.length = 0;
-    await uploadFile(makeCtx(), sourcePath, "round-trip.bin");
-    const put = sentCommands.find((c) => c.name === "PutObjectCommand");
-    const stampedMeta = put!.input.Metadata as Record<string, string>;
-    const stampedBody = put!.input.Body as Buffer;
-
-    // Wipe the local copy and pull via download — simulating a different
-    // machine receiving the file.
-    fs.unlinkSync(sourcePath);
-    nextGetObjectResponse = {
-      Body: (async function* () {
-        yield new Uint8Array(stampedBody);
-      })(),
-      Metadata: stampedMeta,
-    };
-    await downloadFile(makeCtx(), "round-trip.bin", sourcePath);
-
-    const stat = fs.statSync(sourcePath);
-    // Within 100ms — covers FS rounding on both ends of the round-trip.
-    expect(Math.abs(stat.mtimeMs - sourceMs)).toBeLessThanOrEqual(100);
-    expect(fs.readFileSync(sourcePath, "utf-8")).toBe("round-trip-bytes");
-  });
-
-  it("returns the object's user-metadata (including created-by) for a regular file", async () => {
-    nextGetObjectResponse = {
-      Body: (async function* () {
-        yield new Uint8Array([104, 105]); // "hi"
-      })(),
-      Metadata: { "created-by": "alice@example.com", "created-by-sub": "sub-123" },
-    };
-
-    const localPath = path.join(tmpRoot, "authored.md");
-    const result = await downloadFile(makeCtx(), "authored.md", localPath);
-
-    expect(result.metadata?.["created-by"]).toBe("alice@example.com");
-    expect(fs.readFileSync(localPath, "utf-8")).toBe("hi");
-  });
-
-  it("returns the object's user-metadata for a symlink record", async () => {
-    const localPath = path.join(tmpRoot, "authored-link.md");
-    nextGetObjectResponse = {
-      Body: (async function* () {
-        yield new Uint8Array();
-      })(),
-      Metadata: { "hq-symlink-target": "x", "created-by": "bob@example.com" },
-    };
-
-    const result = await downloadFile(makeCtx(), "authored-link.md", localPath);
-
-    expect(result.metadata?.["created-by"]).toBe("bob@example.com");
-    expect(fs.lstatSync(localPath).isSymbolicLink()).toBe(true);
-  });
-});
-
-describe("validateVaultUploadKey — direct-S3 key poisoning guard (incident 2026-07-11)", () => {
-  // The direct-S3 STS transport bypasses hq-pro's server-side validateObjectKey
-  // (files-acl.ts), so uploadFile/uploadSymlink must enforce the SAME rules
-  // before the PUT. Incident: a stale doubled local tree
-  // (companies/indigo/companies/indigo/…) pushed 25 literal `companies/…` keys
-  // into a company vault; the presign download API then rejected every one
-  // (INVALID_KEY_COMPANIES_SCOPED), erroring the whole company sync fleet-wide.
-  let tmpFile: string;
-
-  function makePersonalCtx(): EntityContext {
-    return { ...makeCtx(), uid: "prs_TEST" };
-  }
-
-  beforeEach(() => {
-    sentCommands.length = 0;
-    tmpFile = path.join(
-      os.tmpdir(),
-      `s3-keyguard-test-${Date.now()}-${Math.random()}.md`,
-    );
-    fs.writeFileSync(tmpFile, "hello");
-  });
-
-  afterEach(() => {
-    try {
-      fs.unlinkSync(tmpFile);
-    } catch {
-      // already gone
-    }
-  });
-
-  it("validateVaultUploadKey rejects companies/-prefixed keys in company scope with the server's error code", () => {
-    expect(() =>
-      validateVaultUploadKey("companies/indigo/knowledge/x.md", "company"),
-    ).toThrowError(
-      expect.objectContaining({ code: "INVALID_KEY_COMPANIES_SCOPED" }),
-    );
-  });
-
-  it("validateVaultUploadKey allows companies/-prefixed keys in personal scope (local non-cloud companies)", () => {
-    expect(() =>
-      validateVaultUploadKey("companies/indigo/knowledge/x.md", "personal"),
-    ).not.toThrow();
-  });
-
-  it.each([
-    ["", "INVALID_KEY_EMPTY"],
-    ["/leading.md", "INVALID_KEY_LEADING_SLASH"],
-    ["folder/", "INVALID_KEY_TRAILING_SLASH"],
-    ["a//b.md", "INVALID_KEY_DOUBLE_SLASH"],
-    ["a/../b.md", "INVALID_KEY_DOT_COMPONENT"],
-    ["a/./b.md", "INVALID_KEY_DOT_COMPONENT"],
-    ["bad\x00key.md", "INVALID_KEY_CONTROL_CHARS"],
-    // macOS Finder custom-icon file. Named explicitly because this is the
-    // spelling that reaches the validator in the wild: Finder writes one into
-    // every directory it renders a custom icon for, and the push walker now
-    // excludes them precisely because this throw is unavoidable.
-    ["Icon\r", "INVALID_KEY_CONTROL_CHARS"],
-    ["docs/Icon\r", "INVALID_KEY_CONTROL_CHARS"],
-  ])(
-    "validateVaultUploadKey mirrors the server rule set: %j → %s",
-    (key, code) => {
-      expect(() => validateVaultUploadKey(key, "company")).toThrowError(
-        expect.objectContaining({ code }),
-      );
-      expect(() => validateVaultUploadKey(key, "personal")).toThrowError(
-        expect.objectContaining({ code }),
-      );
-    },
-  );
-
-  it.each([
-    [
-      "companies/indigo/knowledge/x.md",
-      "company",
-      "INVALID_KEY_COMPANIES_SCOPED",
-    ],
-    ["bad\x00key.md", "personal", "INVALID_KEY_CONTROL_CHARS"],
-    ["docs/good.md", "personal", null],
-  ] as const)(
-    "classifyVaultKey reports the validator outcome without throwing: %j",
-    (key, scope, code) => {
-      expect(classifyVaultKey(key, scope)).toEqual(
-        code === null ? null : expect.objectContaining({ code }),
-      );
-    },
-  );
-
-  it("uploadFile refuses to PUT a companies/-prefixed key into a company (cmp_) vault — no S3 command is sent", async () => {
-    await expect(
-      uploadFile(makeCtx(), tmpFile, "companies/indigo/knowledge/x.md"),
-    ).rejects.toMatchObject({ code: "INVALID_KEY_COMPANIES_SCOPED" });
-    expect(sentCommands.length).toBe(0);
-  });
-
-  it("uploadSymlink refuses to PUT a companies/-prefixed key into a company (cmp_) vault — no S3 command is sent", async () => {
-    await expect(
-      uploadSymlink(makeCtx(), "../target.md", "companies/indigo/link.md"),
-    ).rejects.toMatchObject({ code: "INVALID_KEY_COMPANIES_SCOPED" });
-    expect(sentCommands.length).toBe(0);
-  });
-
-  it("uploadFile still allows companies/-prefixed keys for a personal (prs_) vault", async () => {
-    await expect(
-      uploadFile(makePersonalCtx(), tmpFile, "companies/indigo/knowledge/x.md"),
-    ).resolves.toBeDefined();
-    expect(sentCommands.length).toBeGreaterThan(0);
-  });
-});
-
-describe("sweepStaleStagedFiles", () => {
-  let tmpRoot: string;
-  const HOUR = 60 * 60 * 1000;
-
-  beforeEach(() => {
-    tmpRoot = fs.mkdtempSync(path.join(os.tmpdir(), "hq-sweep-test-"));
-  });
-
-  afterEach(() => {
-    fs.rmSync(tmpRoot, { recursive: true, force: true });
-  });
-
-  function makeAged(name: string, ageMs: number): string {
-    const full = path.join(tmpRoot, name);
-    fs.writeFileSync(full, "x");
-    const stamp = new Date(Date.now() - ageMs);
-    fs.utimesSync(full, stamp, stamp);
-    return full;
-  }
-
-  it("removes stale .hq-tmp-* and .hq-backup-* files, keeps everything else", () => {
-    const staleTmp = makeAged(".hq-tmp-deadbeef01", 2 * HOUR);
-    const staleBackup = makeAged(".hq-backup-deadbeef02", 2 * HOUR);
-    const freshTmp = makeAged(".hq-tmp-deadbeef03", 0);
-    const ordinary = makeAged("notes.md", 2 * HOUR);
-    // A directory matching the pattern must never be touched.
-    const dirSentinel = path.join(tmpRoot, ".hq-tmp-a-directory");
-    fs.mkdirSync(dirSentinel);
-
-    const removed = sweepStaleStagedFiles(tmpRoot);
-
-    expect(removed.sort()).toEqual([staleTmp, staleBackup].sort());
-    expect(fs.existsSync(staleTmp)).toBe(false);
-    expect(fs.existsSync(staleBackup)).toBe(false);
-    expect(fs.existsSync(freshTmp)).toBe(true);
-    expect(fs.existsSync(ordinary)).toBe(true);
-    expect(fs.existsSync(dirSentinel)).toBe(true);
-  });
-
-  it("returns empty for a missing directory without throwing", () => {
-    expect(
-      sweepStaleStagedFiles(path.join(tmpRoot, "does-not-exist")),
-    ).toEqual([]);
-  });
-
-  it("respects a custom age threshold", () => {
-    const halfHourOld = makeAged(".hq-tmp-halfhour", HOUR / 2);
-    expect(sweepStaleStagedFiles(tmpRoot, HOUR / 4)).toEqual([halfHourOld]);
-    expect(fs.existsSync(halfHourOld)).toBe(false);
-  });
-});