@indigoai-us/hq-cloud 6.15.0 → 6.15.2

package/src/s3.ts

@@ -1,1532 +0,0 @@
-/**
- * S3 operations — upload, download, list, delete.
- *
- * VLT-5: All operations now accept an EntityContext (entity-aware bucket +
- * STS-scoped credentials) instead of reading static env config. The caller
- * is responsible for resolving the context via resolveEntityContext().
- */
-
-import * as fs from "fs";
-import * as path from "path";
-import * as crypto from "crypto";
-import { Readable, Transform } from "stream";
-import { pipeline } from "stream/promises";
-import type { EntityContext } from "./types.js";
-import {
-  resolveObjectIO,
-  type GetObjectStreamResult,
-  type ObjectIO,
-  type PutPrecondition,
-} from "./object-io.js";
-
-// Byte/metadata transport is resolved per-call via resolveObjectIO(ctx) — the
-// default is the AWS S3 SDK over STS-vended credentials (S3SdkObjectIO), but a
-// session may select the presigned-URL transport (PresignObjectIO) via
-// setObjectIOFactory. The symlink/mode/mtime/created-at semantics below are
-// transport-agnostic: they compose on top of the ObjectIO primitives.
-
-/**
- * Author identity stamped onto S3 user-defined metadata at upload time. The
- * vault UI's "CREATED BY" column reads `Metadata['created-by']` back via
- * HEAD; uploads without an author leave that column blank.
- */
-export interface UploadAuthor {
-  /** Cognito sub — stable join key for per-member rollups. */
-  userSub: string;
-  /** Email for human display. */
-  email: string;
-}
-
-/**
- * S3 user metadata is ASCII-only (lowercased on read, capped at 2 KB total).
- * Values that fail the printable-ASCII test or would push the keys over the
- * cap are elided rather than throwing — partial attribution beats none. The
- * shape mirrors `hq-console/src/lib/s3-vault.ts buildAuthorMetadata` so the
- * read path on the consumer side stays a single check against
- * `Metadata['created-by']`.
- */
-function buildAuthorMetadata(
-  author: UploadAuthor,
-  createdAt: string,
-): Record<string, string> {
-  const meta: Record<string, string> = {};
-  const sub = author.userSub.trim();
-  if (sub && /^[\x20-\x7E]+$/.test(sub)) {
-    meta["created-by-sub"] = sub;
-  }
-  const email = author.email.trim();
-  if (email && /^[\x20-\x7E]+$/.test(email)) {
-    meta["created-by"] = email;
-  }
-  if (createdAt && /^[\x20-\x7E]+$/.test(createdAt)) {
-    meta["created-at"] = createdAt;
-  }
-  return meta;
-}
-
-/**
- * S3 user-metadata header that marks an object as a symlink record.
- * The value is now an OPAQUE MARKER ('1') — the target lives in the
- * object body. Earlier drafts of this feature stored the target in
- * metadata (raw, then base64), but S3 user-metadata is HTTP-header-
- * bound: total ≤ 2 KiB across all user-defined keys + values. A
- * sufficiently long POSIX target (or one with author-metadata
- * adding to the total) would exceed the limit and PutObject would
- * reject the upload outright. Moving the target to the body — which
- * has no such limit — makes target length bounded only by S3's 5 GB
- * object size cap. The metadata header still serves as the read-
- * time discriminator (cheaper than peeking at body bytes via HEAD).
- *
- * Backward compat: downloadFile prefers the body (sliced after
- * SYMLINK_BODY_PREFIX) for the target string. If the body doesn't
- * carry the prefix (a legacy upload from earlier in this PR's
- * lifetime), it falls back to base64-decoding the metadata value —
- * the round-trip-validating decoder returns raw or decoded as
- * appropriate. Any prior in-flight upload still resolves correctly.
- */
-export const SYMLINK_TARGET_META_KEY = "hq-symlink-target";
-
-/**
- * Constant value written to SYMLINK_TARGET_META_KEY. Any non-empty
- * string would work as a discriminator — '1' is just compact and
- * conventional for boolean flags in HTTP headers.
- */
-export const SYMLINK_MARKER_META_VALUE = "1";
-
-/**
- * Encode a target for the S3 metadata header value. Retained as the
- * legacy encoder so a downloader can still receive it and round-trip
- * via decodeSymlinkMetadataValue, but new uploads use
- * SYMLINK_MARKER_META_VALUE — the target lives in the body now.
- */
-export function encodeSymlinkMetadataValue(target: string): string {
-  return Buffer.from(target, "utf-8").toString("base64");
-}
-
-/**
- * Decode a target from the S3 metadata header value. Used as a
- * legacy fallback when the body doesn't carry SYMLINK_BODY_PREFIX
- * (i.e. an in-flight upload from earlier in this PR before the
- * marker-only metadata convention). Round-trip-validates: if the
- * value isn't valid base64 of UTF-8, returns the raw string.
- */
-export function decodeSymlinkMetadataValue(value: string): string {
-  try {
-    const decoded = Buffer.from(value, "base64").toString("utf-8");
-    if (Buffer.from(decoded, "utf-8").toString("base64") === value) {
-      return decoded;
-    }
-  } catch {
-    // fall through
-  }
-  return value;
-}
-
-/**
- * Magic prefix prepended to symlink-record bodies on the wire. Two
- * properties this gives us:
- *
- *   1. ETag distinguishability. S3 ETag = MD5(body). Without a prefix,
- *      a symlink whose target string equals some regular file's exact
- *      contents would produce the same ETag, and the LIST-based pull
- *      planner (which can't see per-object metadata) would classify a
- *      symlink ↔ regular-file transition as "no change" and never
- *      replace the local representation. The prefix makes those two
- *      shapes ETag-distinguishable for the realistic case (collision
- *      now requires a regular file whose contents *start* with this
- *      prefix, which is implausible for any non-malicious source).
- *
- *   2. Fallback discriminator. If user-metadata is ever lost (S3
- *      cross-region replication of object data only, manual S3 console
- *      copy that drops Metadata), the body prefix lets a downloader
- *      recover the symlink record without needing the metadata header.
- *      We don't currently rely on this fallback — the metadata header
- *      is still the primary discriminator on the read path — but the
- *      prefix keeps the option open and avoids painting us into a
- *      "metadata is the only signal" corner.
- *
- * Format: `hq-symlink:` + target string (UTF-8 bytes). No trailing
- * newline. The colon separates the marker from the target so a future
- * extension can encode additional fields if needed.
- */
-export const SYMLINK_BODY_PREFIX = "hq-symlink:";
-const SYMLINK_BODY_PREFIX_BYTES = Buffer.from(SYMLINK_BODY_PREFIX, "utf-8");
-
-/**
- * S3 user-metadata key carrying the source-side file mode (permission bits
- * only — \`mode & 0o777\`) as an octal string ("755", "640", etc.). On
- * download, downloadFile parses this with \`parseInt(value, 8)\` and chmods
- * the file to the exact source mode after the byte write.
- *
- * Bug #5 in the 5.33.0 deep-test was originally reported as "exec bit lost
- * on sync" but the verification report broadened it: ALL modes (0600 / 0640
- * / 0700 / 0750 / 0755) collapsed to the receiver's umask default (0644)
- * because no mode signal crossed the wire at all. Stamping the mode in
- * metadata is the smallest schema change that preserves the full
- * permission bitfield without a per-host umask negotiation.
- *
- * Symlinks: skipped at upload time (symlink mode is OS-controlled
- * lrwxrwxrwx) and skipped on download (\`fs.chmodSync\` follows symlinks
- * and would mutate the target's mode instead).
- *
- * Back-compat: legacy uploads have no \`hq-mode\` header — the receiver
- * leaves the umask default in place, matching pre-fix behavior.
- */
-export const FILE_MODE_META_KEY = "hq-mode";
-
-/**
- * S3 user-metadata key carrying the source-side file modification time
- * (mtimeMs) as an integer-millisecond epoch string ("1700000000000"). On
- * download, downloadFile parses this with a strict-numeric regex BEFORE
- * parseInt, then applies it via `fs.utimesSync(localPath, mtimeDate,
- * mtimeDate)` after the byte write.
- *
- * 5.37.0 symmetric to the 5.34.0 Bug #5 mode preservation: a file's
- * modification time should follow it across machines instead of resetting
- * to "the time of sync." Without this metadata, every receiver's mtime is
- * wall-clock-now at write-time — making "newer than" comparisons,
- * mtime-keyed caches, and reproducible builds break across sync.
- *
- * Symlinks: skipped at upload time (symlink mtime is OS-controlled and
- * `lstat` on a symlink already returns the symlink's own times — but we
- * don't stamp them because the symlink record wire body is `hq-symlink:`
- * + target string, not real file content, so its mtime isn't user-
- * meaningful) and skipped on download (`fs.utimesSync` follows symlinks
- * and would mutate the target's mtime instead; `lutimesSync` is not in
- * stable Node).
- *
- * Composition with 5.36.0 lstat fast-path: the journal stamp is captured
- * AFTER utimesSync runs (the share/sync call sites lstat AFTER
- * downloadFile returns), so the journal's mtimeMs matches the post-utimes
- * lstat. The next sync's fast-path correctly skips re-hashing.
- *
- * Clock skew: a peer with a wrong clock pushes file with mtimeMs=<wrong>;
- * receivers apply <wrong>. This is the same trade git's "file from the
- * future" warning makes — silent in our case, deliberately. Clock skew
- * is the user's problem, not the sync engine's.
- *
- * Back-compat: legacy uploads (pre-5.37.0) have no `hq-mtime` header —
- * the receiver leaves the on-disk mtime at write-time, matching pre-
- * 5.37.0 behavior. Forward-compat: pre-5.37.0 pullers ignore `hq-mtime`
- * and keep their current "mtime = write-time" behavior. Both work; only
- * the receiver upgrade unlocks the feature.
- */
-export const FILE_MTIME_META_KEY = "hq-mtime";
-
-/**
- * S3 user-metadata key carrying the source-side file birthtime (birthtimeMs)
- * as an integer-millisecond epoch string. Stamped on upload ONLY when
- * `birthtimeMs > 0 && birthtimeMs !== mtimeMs` — many filesystems (Linux
- * ext4 historically, tmpfs, some FUSE mounts) return 0 (unsupported) or
- * the same value as mtime (no separate creation time tracking). The
- * filter keeps the metadata header free of noise on those platforms.
- *
- * Pull: NO-OP for now. Node has no API to set birthtime on POSIX as of
- * v24 (no `lbirthtime`, no `birthtimeSync`). The push side stamps it
- * anyway so a future receiver upgrade — once Node lands the API — can
- * apply it without a server-side data migration.
- *
- * Symlinks: skipped on both sides for the same reasons as `hq-mtime`.
- */
-export const FILE_BTIME_META_KEY = "hq-btime";
-
-/**
- * Encode/decode the symlink wire body. Kept as exported helpers so the
- * format is centrally defined and tests can probe both sides without
- * duplicating the prefix string.
- */
-export function encodeSymlinkBody(target: string): Buffer {
-  return Buffer.from(SYMLINK_BODY_PREFIX + target, "utf-8");
-}
-
-/**
- * Staged-download (`.hq-tmp-*`) and replacement-backup (`.hq-backup-*`)
- * sentinels are cleaned by try/finally in-process, but a hard kill
- * mid-transfer (agent job `timeout -k`, OOM, systemd stop) never reaches the
- * finally and nothing else removes them. On a fleet box that leaked 866M of
- * orphans in two days and filled /tmp (2026-07-20 incident). Sweep stale
- * sentinels in the destination dir before staging a new one there.
- *
- * The age threshold far exceeds any live transfer, so a concurrent download's
- * fresh sentinel is never touched. Only non-directories matching the sentinel
- * pattern are candidates. Per-dir memoization bounds the readdir cost to once
- * per directory per process run.
- */
-const STAGED_SENTINEL_PATTERN = /^\.hq-(tmp|backup)-/;
-const STAGED_SWEEP_MAX_AGE_MS = 60 * 60 * 1000;
-const sweptStagedDirs = new Set<string>();
-
-export function sweepStaleStagedFiles(
-  dir: string,
-  maxAgeMs: number = STAGED_SWEEP_MAX_AGE_MS,
-  nowMs: number = Date.now(),
-): string[] {
-  let entries: string[];
-  try {
-    entries = fs.readdirSync(dir);
-  } catch (err) {
-    // Destination dir may not exist yet (created later by downloadFile) —
-    // nothing to sweep. Anything else is unexpected but must not fail the
-    // download that triggered the sweep.
-    if ((err as NodeJS.ErrnoException).code !== "ENOENT") {
-      console.warn(`[hq-sync] staged-file sweep: cannot read ${dir}: ${err}`);
-    }
-    return [];
-  }
-  const removed: string[] = [];
-  for (const name of entries) {
-    if (!STAGED_SENTINEL_PATTERN.test(name)) continue;
-    const full = path.join(dir, name);
-    try {
-      const stat = fs.lstatSync(full);
-      if (stat.isDirectory()) continue;
-      if (nowMs - stat.mtimeMs < maxAgeMs) continue;
-      fs.unlinkSync(full);
-      removed.push(full);
-    } catch (err) {
-      // A concurrent process may have removed it first (ENOENT: fine), or the
-      // file is unremovable (EPERM/EROFS) — either way the download must
-      // proceed; surface non-ENOENT so the leak stays visible.
-      if ((err as NodeJS.ErrnoException).code !== "ENOENT") {
-        console.warn(`[hq-sync] staged-file sweep: cannot remove ${full}: ${err}`);
-      }
-    }
-  }
-  if (removed.length > 0) {
-    console.warn(
-      `[hq-sync] removed ${removed.length} stale staged file(s) in ${dir}`,
-    );
-  }
-  return removed;
-}
-
-function sweepStaleStagedFilesOnce(dir: string): void {
-  if (sweptStagedDirs.has(dir)) return;
-  sweptStagedDirs.add(dir);
-  sweepStaleStagedFiles(dir);
-}
-
-function downloadTempPath(localPath: string): string {
-  const dir = path.dirname(localPath);
-  sweepStaleStagedFilesOnce(dir);
-  const random = crypto.randomBytes(10).toString("hex");
-  return path.join(dir, `.hq-tmp-${random}`);
-}
-
-function removeTempPath(tempPath: string): void {
-  try {
-    fs.unlinkSync(tempPath);
-  } catch {
-    // A win32 directory-type symlink is a directory reparse point and
-    // refuses unlink (EPERM); rmdir is the correct removal call for it.
-    try {
-      fs.rmdirSync(tempPath);
-    } catch {
-      // Best-effort cleanup; do not mask the transfer/materialization error.
-    }
-  }
-}
-
-export interface CreateStagedSymlinkOps {
-  platform: NodeJS.Platform;
-  symlink(target: string, linkPath: string, type?: fs.symlink.Type): void;
-  statIsDirectory(absPath: string): boolean | undefined;
-}
-
-const DEFAULT_CREATE_STAGED_SYMLINK_OPS: CreateStagedSymlinkOps = {
-  platform: process.platform,
-  symlink: (target, linkPath, type) =>
-    fs.symlinkSync(target, linkPath, type),
-  statIsDirectory: (absPath) => {
-    try {
-      return fs.statSync(absPath).isDirectory();
-    } catch {
-      return undefined;
-    }
-  },
-};
-
-/**
- * Create a fully-staged symlink without requiring Windows Developer Mode.
- * NTFS symlinks fail with EPERM without SeCreateSymbolicLinkPrivilege, while
- * directory junctions need no privilege but require an absolute target. HQ
- * vault links are directory overlays, so missing targets default to junctions.
- * See Sentry HQ-DESKTOP-3M.
- */
-export function createStagedSymlink(
-  target: string,
-  linkPath: string,
-  ops: CreateStagedSymlinkOps = DEFAULT_CREATE_STAGED_SYMLINK_OPS,
-): void {
-  if (ops.platform !== "win32") {
-    ops.symlink(target, linkPath);
-    return;
-  }
-
-  const absTarget = path.isAbsolute(target)
-    ? target
-    : path.resolve(path.dirname(linkPath), target);
-  if (ops.statIsDirectory(absTarget) === false) {
-    ops.symlink(target, linkPath, "file");
-    return;
-  }
-
-  ops.symlink(absTarget, linkPath, "junction");
-}
-
-/**
- * downloadFile's `options.win32` seam is the authority for symlink-flavor
- * decisions (it is what makes Windows semantics testable on POSIX CI), so the
- * staged-link helper must see the SAME platform the idempotence fast path
- * reasoned about rather than the raw `process.platform`. createStagedSymlink
- * only ever asks "is this win32?", so "linux" is a faithful stand-in for
- * "not Windows" on the false branch.
- */
-function stagedSymlinkOpsFor(win32: boolean): CreateStagedSymlinkOps {
-  return {
-    ...DEFAULT_CREATE_STAGED_SYMLINK_OPS,
-    platform: win32 ? "win32" : "linux",
-  };
-}
-
-/**
- * Would createStagedSymlink() materialize `target` as a DIRECTORY-flavored
- * link (a junction) rather than a file symlink? Mirrors that helper's rule
- * exactly — only a target confirmed to be a non-directory earns a file
- * symlink; directories and unresolvable targets become junctions, which need
- * no Windows privilege. Keeping the two in lockstep is what lets the
- * idempotence fast path below decide whether an existing link is already the
- * link we would mint today.
- */
-function win32StagedLinkIsDirectoryFlavored(
-  target: string,
-  linkPath: string,
-  ops: CreateStagedSymlinkOps = DEFAULT_CREATE_STAGED_SYMLINK_OPS,
-): boolean {
-  const absTarget = path.isAbsolute(target)
-    ? target
-    : path.resolve(path.dirname(linkPath), target);
-  return ops.statIsDirectory(absTarget) !== false;
-}
-
-/**
- * Compare an on-disk readlink() result against an incoming wire target.
- *
- * POSIX compares exactly: we write the wire target verbatim, so readlink()
- * returns it byte-for-byte, and a backslash is an ordinary filename character
- * there. On win32 neither property holds — createStagedSymlink() materializes
- * directory overlays as JUNCTIONS, which require an ABSOLUTE substitute path,
- * and Node rewrites '/' → '\\' at symlink() time. A raw string compare would
- * therefore never match on Windows and the fast path would never fire for the
- * .claude/skills link farm (the exact perpetual-churn bug this guards). So
- * win32 equality resolves BOTH sides against the link's parent directory and
- * compares separator-insensitively, which normalizes the relative wire target
- * and the absolute junction target onto the same footing.
- */
-function symlinkTargetsEqual(
-  existing: string,
-  incoming: string,
-  linkPath: string,
-  win32: boolean,
-): boolean {
-  if (!win32) return existing === incoming;
-  const normalize = (value: string): string =>
-    path
-      .resolve(path.dirname(linkPath), value.replace(/\\/g, "/"))
-      .replace(/\\/g, "/");
-  return normalize(existing) === normalize(incoming);
-}
-
-export interface ReplaceStagedPathOps {
-  lstat(path: string): fs.Stats;
-  rename(from: string, to: string): void;
-  remove(path: string): void;
-}
-
-const DEFAULT_REPLACE_STAGED_PATH_OPS: ReplaceStagedPathOps = {
-  lstat: (p) => fs.lstatSync(p),
-  rename: (from, to) => fs.renameSync(from, to),
-  remove: (p) => {
-    try {
-      fs.unlinkSync(p);
-    } catch (err) {
-      // A win32 directory-type symlink or junction is a directory reparse
-      // point; some runtimes refuse unlink (EPERM/EISDIR) and need rmdir —
-      // same fallback as removeTempPath. Anything else stays loud so
-      // replaceStagedPath can roll back.
-      const code = (err as NodeJS.ErrnoException).code;
-      if (code !== "EPERM" && code !== "EISDIR") throw err;
-      fs.rmdirSync(p);
-    }
-  },
-};
-
-function replacementBackupPath(localPath: string): string {
-  const dir = path.dirname(localPath);
-  const random = crypto.randomBytes(10).toString("hex");
-  return path.join(dir, `.hq-backup-${random}`);
-}
-
-/**
- * Install a fully-staged download over its destination.
- *
- * A direct rename is atomic and remains the fast path for absent destinations
- * and ordinary files. Windows cannot rename over an existing directory link,
- * though, because MoveFileEx treats that link as an existing directory. For a
- * symlink/junction destination, move the old link to a sibling backup first,
- * install the staged entry, then remove the backup. Any failure after the
- * backup move restores the exact prior link before rethrowing.
- *
- * The tiny operations seam keeps the Windows failure/rollback contract
- * deterministic in ESM tests without spying on non-configurable fs exports.
- */
-export function replaceStagedPath(
-  stagedPath: string,
-  localPath: string,
-  ops: ReplaceStagedPathOps = DEFAULT_REPLACE_STAGED_PATH_OPS,
-): void {
-  let existing: fs.Stats;
-  try {
-    existing = ops.lstat(localPath);
-  } catch (err) {
-    if ((err as NodeJS.ErrnoException).code === "ENOENT") {
-      ops.rename(stagedPath, localPath);
-      return;
-    }
-    throw err;
-  }
-
-  if (!existing.isSymbolicLink()) {
-    ops.rename(stagedPath, localPath);
-    return;
-  }
-
-  const backupPath = replacementBackupPath(localPath);
-  ops.rename(localPath, backupPath);
-  let stagedInstalled = false;
-  try {
-    ops.rename(stagedPath, localPath);
-    stagedInstalled = true;
-    ops.remove(backupPath);
-  } catch (primaryError) {
-    const rollbackErrors: unknown[] = [];
-    if (stagedInstalled) {
-      try {
-        ops.rename(localPath, stagedPath);
-      } catch (rollbackError) {
-        rollbackErrors.push(rollbackError);
-      }
-    }
-    try {
-      ops.rename(backupPath, localPath);
-    } catch (rollbackError) {
-      rollbackErrors.push(rollbackError);
-    }
-    if (rollbackErrors.length > 0) {
-      throw new AggregateError(
-        [primaryError, ...rollbackErrors],
-        "Staged path replacement failed and the previous directory link could not be fully restored",
-      );
-    }
-    throw primaryError;
-  }
-}
-
-async function getObjectStream(
-  io: ObjectIO,
-  key: string,
-): Promise<GetObjectStreamResult> {
-  if (io.getObjectStream) return io.getObjectStream(key);
-  const res = await io.getObject(key);
-  return {
-    body: (async function* () {
-      yield res.body;
-    })(),
-    metadata: res.metadata,
-  };
-}
-
-function bufferFromChunk(chunk: Uint8Array): Buffer {
-  if (Buffer.isBuffer(chunk)) return chunk;
-  return Buffer.from(chunk.buffer, chunk.byteOffset, chunk.byteLength);
-}
-
-function leadingBytes(chunks: Buffer[], totalLength: number, length: number): Buffer {
-  const out = Buffer.alloc(Math.min(totalLength, length));
-  let offset = 0;
-  for (const chunk of chunks) {
-    if (offset >= out.length) break;
-    const take = Math.min(chunk.length, out.length - offset);
-    chunk.copy(out, offset, 0, take);
-    offset += take;
-  }
-  return out;
-}
-
-async function collectRemainingChunks(
-  initialChunks: Buffer[],
-  iterator: AsyncIterator<Uint8Array>,
-): Promise<Buffer> {
-  const chunks = [...initialChunks];
-  let totalLength = chunks.reduce((sum, chunk) => sum + chunk.length, 0);
-  while (true) {
-    const next = await iterator.next();
-    if (next.done) break;
-    const chunk = bufferFromChunk(next.value);
-    if (chunk.length === 0) continue;
-    chunks.push(chunk);
-    totalLength += chunk.length;
-  }
-  return Buffer.concat(chunks, totalLength);
-}
-
-async function* regularDownloadChunks(
-  initialChunks: Buffer[],
-  iterator: AsyncIterator<Uint8Array>,
-): AsyncIterable<Buffer> {
-  for (const chunk of initialChunks) {
-    if (chunk.length > 0) yield chunk;
-  }
-  while (true) {
-    const next = await iterator.next();
-    if (next.done) break;
-    const chunk = bufferFromChunk(next.value);
-    if (chunk.length > 0) yield chunk;
-  }
-}
-
-class HashingTransform extends Transform {
-  private readonly hash = crypto.createHash("sha256");
-  size = 0;
-
-  _transform(
-    chunk: Buffer,
-    _encoding: BufferEncoding,
-    callback: (error?: Error | null, data?: Buffer) => void,
-  ): void {
-    this.hash.update(chunk);
-    this.size += chunk.length;
-    callback(null, chunk);
-  }
-
-  digest(): string {
-    return this.hash.digest("hex");
-  }
-}
-
-async function streamRegularFileToTemp(
-  tempPath: string,
-  initialChunks: Buffer[],
-  iterator: AsyncIterator<Uint8Array>,
-): Promise<{ hash: string; size: number }> {
-  const hashing = new HashingTransform();
-  await pipeline(
-    Readable.from(regularDownloadChunks(initialChunks, iterator)),
-    hashing,
-    fs.createWriteStream(tempPath, { flags: "wx" }),
-  );
-  return { hash: hashing.digest(), size: hashing.size };
-}
-
-/**
- * Batch pre-mint transport URLs for `keys` under `op` so the subsequent
- * per-file transfer calls (downloadFile/headRemoteFile/…) reuse them instead
- * of presigning one key at a time. On the presigned-URL transport this turns
- * an N-file leg from N presign requests into ceil(N/100) — the difference
- * between completing a bulk pull and 429ing past the 100-req/hr limit. No-op
- * on the S3 SDK transport (which has no presign step) and harmless if called
- * with an empty list. Best-effort: a prime failure never propagates — the
- * per-file path falls back to a single presign.
- *
- * Call it once, right before a transfer loop, with the full key set the loop
- * will touch. The presigned transport memoizes one IO instance per company for
- * the run, so the warmed cache is the same one the loop drains.
- */
-export async function primeObjectTransport(
-  ctx: EntityContext,
-  op: "get" | "put" | "delete",
-  keys: string[],
-): Promise<void> {
-  if (keys.length === 0) return;
-  const io = resolveObjectIO(ctx);
-  if (!io.prime) return;
-  await io.prime(
-    op,
-    keys.map((key) => ({ key })),
-  );
-}
-
-/**
- * Source-side mode + mtime (+ btime when distinct) metadata for a regular
- * file, from a single lstat. Symlinks carry none (OS-controlled mode; a link's
- * mtime isn't user-meaningful — the wire body is the target string, not file
- * content). Shared by uploadFile and the primeUploads pre-pass so the PUT
- * metadata they produce is byte-identical. See the FILE_*_META_KEY docs for the
- * per-field rationale.
- */
-function buildModeTimeMetadata(lstat: fs.Stats): Record<string, string> {
-  const meta: Record<string, string> = {};
-  if (lstat.isSymbolicLink()) return meta;
-  meta[FILE_MODE_META_KEY] = (lstat.mode & 0o777).toString(8);
-  const mtimeFloor = Math.floor(lstat.mtimeMs);
-  if (Number.isFinite(lstat.mtimeMs)) meta[FILE_MTIME_META_KEY] = String(mtimeFloor);
-  const btimeFloor = Math.floor(lstat.birthtimeMs);
-  if (
-    Number.isFinite(lstat.birthtimeMs) &&
-    btimeFloor > 0 &&
-    btimeFloor !== mtimeFloor
-  ) {
-    meta[FILE_BTIME_META_KEY] = String(btimeFloor);
-  }
-  return meta;
-}
-
-/**
- * Resolve the created-at to stamp: the existing object's value (preserved
- * across re-uploads so the hq-console NEW-pill window doesn't reset) or now for
- * a first upload. HEAD failure / no author → now. Shared by upload* and
- * primeUploads so both agree on the value signed into the PUT.
- */
-async function resolveCreatedAt(
-  io: ObjectIO,
-  key: string,
-  author?: UploadAuthor,
-): Promise<string> {
-  let createdAt = new Date().toISOString();
-  if (author) {
-    try {
-      const head = await io.headObject(key);
-      const existing = head?.metadata?.["created-at"];
-      if (typeof existing === "string" && existing.length > 0) {
-        createdAt = existing;
-      }
-    } catch {
-      // Object doesn't exist yet, or HEAD failed — keep now (first upload).
-    }
-  }
-  return createdAt;
-}
-
-/**
- * One upload's identity for {@link primeUploads}: the vault key, the local
- * path (to lstat for mode/mtime), whether it's a symlink, and the author.
- */
-export interface UploadPrimeItem {
-  key: string;
-  localPath: string;
-  isSymlink: boolean;
-  author?: UploadAuthor;
-}
-
-/**
- * Batch pre-mint PUT URLs (+ the created-at HEADs they depend on) for a set of
- * uploads, signing the SAME metadata uploadFile/uploadSymlink would compute so
- * the transfer loop can replay the cached headers. Turns an N-file push from
- * ~N presign calls (1 per PUT, sometimes 2-3 with HEADs) into ceil(N/1000) GET
- * + ceil(N/1000) PUT — the difference between completing a bulk push and 429ing
- * past the 100/hr limit. No-op on the S3 SDK transport; best-effort.
- *
- * The per-item created-at HEADs run over the GET cache primed first, so they
- * cost S3 round-trips but NO extra presign calls (not counted against 100/hr).
- */
-export async function primeUploads(
-  ctx: EntityContext,
-  items: UploadPrimeItem[],
-): Promise<void> {
-  const io = resolveObjectIO(ctx);
-  if (!io.prime || items.length === 0) return;
-
-  // Prime GET first so each item's created-at HEAD reuses a cached URL.
-  // Canonicalize to POSIX here (one-canonical-form, matching the uploadFile /
-  // uploadSymlink boundary): a Windows-origin backslash key must cache under
-  // the SAME key uploadFile later looks up via hasPrimedPut(toPosixKey(...)),
-  // or the primed URL silently misses and the upload re-presigns. It also
-  // keeps the created-at HEAD pointed at the real (POSIX) object.
-  await io.prime(
-    "get",
-    items.map((i) => ({ key: toPosixKey(i.key) })),
-  );
-
-  // Build per-key PUT metadata with the SAME builders the upload path uses,
-  // bounded-concurrently (the HEADs are cheap cached-GET fetches).
-  const putKeys: Array<{
-    key: string;
-    contentType: string;
-    metadata: Record<string, string>;
-  }> = [];
-  const CONCURRENCY = 16;
-  let next = 0;
-  const worker = async (): Promise<void> => {
-    while (next < items.length) {
-      const it = items[next++];
-      // Same boundary guardrail as uploadFile/uploadSymlink: prime under the
-      // canonical POSIX key so the cached PUT URL is keyed identically to the
-      // hasPrimedPut/putObject lookup, and a backslash key can never be primed
-      // (let alone stored) as a non-POSIX vault key.
-      const key = toPosixKey(it.key);
-      const createdAt = await resolveCreatedAt(io, key, it.author);
-      if (it.isSymlink) {
-        putKeys.push({
-          key,
-          contentType: "application/octet-stream",
-          metadata: {
-            [SYMLINK_TARGET_META_KEY]: SYMLINK_MARKER_META_VALUE,
-            ...(it.author ? buildAuthorMetadata(it.author, createdAt) : {}),
-          },
-        });
-      } else {
-        let modeTime: Record<string, string> = {};
-        try {
-          modeTime = buildModeTimeMetadata(fs.lstatSync(it.localPath));
-        } catch {
-          // raced rm / EPERM — leave stamps off (receiver umask default).
-        }
-        putKeys.push({
-          key,
-          contentType: getMimeType(key),
-          metadata: {
-            ...(it.author ? buildAuthorMetadata(it.author, createdAt) : {}),
-            ...modeTime,
-          },
-        });
-      }
-    }
-  };
-  await Promise.all(
-    Array.from({ length: Math.min(CONCURRENCY, items.length) }, worker),
-  );
-
-  await io.prime("put", putKeys);
-}
-
-/**
- * Normalize an S3 object key to POSIX ("/") separators.
- *
- * S3 keys are always "/"-separated, and the vault listing reconstructs the
- * folder tree by splitting keys on "/". A non-POSIX (Windows) sync client
- * builds a key from `path.relative(...)`, whose separator is the native "\\";
- * stored verbatim, a nested key like `knowledge\books-eoi.md` contains no "/"
- * and the listing renders it flat at the vault root as one oddly-named file.
- * Converting every "\\" to "/" makes the stored key POSIX regardless of the
- * client OS.
- *
- * Mirrors the prefix guard in hq-pro files-acl (`FORBIDDEN_CHARS = /[?#\\[\]]/`,
- * which already rejects "\\" on browse/grant prefixes). Uploads go direct to
- * S3 via vended STS creds, so the server never re-validates the uploaded key —
- * the upload primitives (uploadFile / uploadSymlink) are the only shared choke
- * point, and they call this so a backslash key can never be stored again.
- */
-export function toPosixKey(key: string): string {
-  return key.split("\\").join("/");
-}
-
-/**
- * Client-side mirror of hq-pro's server validator
- * (`vault-service/handlers/files-acl.ts validateObjectKey`). The direct-S3
- * STS transport bypasses server key validation entirely — the upload
- * primitives (uploadFile / uploadSymlink) are the only shared choke point —
- * so we enforce the SAME rules here BEFORE the PUT. Incident 2026-07-11: a
- * client with a stale doubled local tree (companies/{slug}/companies/{slug}/…)
- * pushed literal `companies/…` keys into a company-scoped vault bucket via
- * direct S3; agent boxes could LIST them but the presign download API
- * rejected every one (INVALID_KEY_COMPANIES_SCOPED), erroring the whole
- * company sync fleet-wide. A poisoned key must fail loudly at the writer,
- * not at every reader.
- *
- * `scope` selects the companies/-prefix rule: company vault buckets are
- * already company-scoped so a `companies/…` key is always wrong there;
- * personal vaults legitimately carry `companies/{slug}/…` keys for local
- * (non-cloud) companies. Callers derive scope from the EntityContext uid
- * (`cmp_*` → "company", otherwise "personal").
- *
- * Errors carry the same `code` values the server throws so telemetry and
- * operator messaging line up across client and server. Pull planning also
- * uses the non-throwing classifier below to keep poison keys away from the
- * presign transport.
- */
-// Matching control chars is the whole point — block NUL/0x00–0x1F/0x7F in keys
-// (they can smuggle past path checks or corrupt HTTP headers on the signed URL).
-// eslint-disable-next-line no-control-regex
-const KEY_CONTROL_CHARS = /[\x00-\x1F\x7F]/;
-
-export type VaultKeyScope = "company" | "personal";
-
-export interface VaultKeyValidationIssue {
-  code: string;
-  message: string;
-}
-
-/**
- * Classify a vault key with the same rules as {@link validateVaultUploadKey}
- * without throwing. Callers that enumerate remote objects can use this before
- * presigning so permanently-invalid legacy keys remain benign skips.
- */
-export function classifyVaultKey(
-  key: string,
-  scope: VaultKeyScope,
-): VaultKeyValidationIssue | null {
-  if (key.length === 0) {
-    return {
-      code: "INVALID_KEY_EMPTY",
-      message: "Invalid key: must not be empty",
-    };
-  }
-  if (key.startsWith("/")) {
-    return {
-      code: "INVALID_KEY_LEADING_SLASH",
-      message: "Invalid key: leading '/' not allowed",
-    };
-  }
-  if (key.endsWith("/")) {
-    return {
-      code: "INVALID_KEY_TRAILING_SLASH",
-      message: "Invalid key: trailing '/' (folder marker, not an object)",
-    };
-  }
-  if (scope === "company" && key.startsWith("companies/")) {
-    return {
-      code: "INVALID_KEY_COMPANIES_SCOPED",
-      message:
-        "Invalid key: vault keys are bucket-relative and the vault is already " +
-        "company-scoped — do not prefix with 'companies/<slug>/'. This " +
-        "usually means a stale doubled local tree " +
-        "(companies/<slug>/companies/<slug>/…); remove the inner copy.",
-    };
-  }
-  if (KEY_CONTROL_CHARS.test(key)) {
-    return {
-      code: "INVALID_KEY_CONTROL_CHARS",
-      message: "Invalid key: contains control characters",
-    };
-  }
-  if (key.includes("\\")) {
-    return {
-      code: "INVALID_KEY_BACKSLASH",
-      message:
-        "Invalid key: backslash separators are not allowed — vault keys are POSIX ('/')",
-    };
-  }
-  if (key.includes("//")) {
-    return {
-      code: "INVALID_KEY_DOUBLE_SLASH",
-      message: "Invalid key: consecutive slashes not allowed",
-    };
-  }
-  for (const segment of key.split("/")) {
-    if (segment === "." || segment === "..") {
-      return {
-        code: "INVALID_KEY_DOT_COMPONENT",
-        message: "Invalid key: '.' and '..' path components are not allowed",
-      };
-    }
-  }
-  return null;
-}
-
-export function validateVaultUploadKey(
-  key: string,
-  scope: VaultKeyScope,
-): void {
-  const issue = classifyVaultKey(key, scope);
-  if (issue !== null) {
-    throw Object.assign(new Error(issue.message), { code: issue.code });
-  }
-}
-
-/** Scope for {@link validateVaultUploadKey}, derived from the entity uid. */
-function uploadScopeFor(ctx: EntityContext): VaultKeyScope {
-  return ctx.uid.startsWith("cmp_") ? "company" : "personal";
-}
-
-export async function uploadFile(
-  ctx: EntityContext,
-  localPath: string,
-  key: string,
-  author?: UploadAuthor,
-  precondition?: PutPrecondition,
-): Promise<{ etag: string }> {
-  // Boundary guardrail: never store a non-POSIX key (see toPosixKey), and
-  // never store a key the server-side validator would reject (see
-  // validateVaultUploadKey — the direct-S3 STS transport bypasses server
-  // validation, so this is the last line of defense against key poisoning).
-  key = toPosixKey(key);
-  validateVaultUploadKey(key, uploadScopeFor(ctx));
-  const io = resolveObjectIO(ctx);
-  const body = fs.readFileSync(localPath);
-
-  // Fast path: a primeUploads() pre-pass already signed this file's metadata
-  // into a cached PUT URL. Skip the lstat-metadata + created-at HEAD and just
-  // send the body — putObject replays the cached headers (computed by the SAME
-  // builders below, so identical). hasPrimedPut only reports true with >60s of
-  // URL lifetime left, so the cache can't expire before the putObject below.
-  // Fenced PUTs bypass the fast path: a primed URL was signed WITHOUT the
-  // conditional header, so replaying it would silently drop the fence.
-  if (!precondition && io.hasPrimedPut?.(key)) {
-    const primed = await io.putObject({
-      key,
-      body,
-      contentType: getMimeType(key),
-      metadata: {},
-    });
-    return { etag: primed.etag };
-  }
-
-  // Source-side mode/mtime/btime (Bug #5 + 5.37.0) and the preserved
-  // created-at (so the NEW-pill window doesn't reset on re-upload). Both via
-  // the shared builders that primeUploads uses, so a primed PUT carries the
-  // identical metadata — see buildModeTimeMetadata / resolveCreatedAt.
-  let modeTime: Record<string, string> = {};
-  try {
-    modeTime = buildModeTimeMetadata(fs.lstatSync(localPath));
-  } catch {
-    // raced rm / EPERM — leave stamps off; receiver keeps its umask default.
-  }
-  const createdAt = await resolveCreatedAt(io, key, author);
-  const Metadata: Record<string, string> = {
-    ...(author ? buildAuthorMetadata(author, createdAt) : {}),
-    ...modeTime,
-  };
-
-  const response = await io.putObject({
-    key,
-    body,
-    contentType: getMimeType(key),
-    metadata: Metadata,
-    ...(precondition ?? {}),
-  });
-
-  return { etag: response.etag };
-}
-
-/**
- * Upload a symlink as a zero-byte object whose user metadata carries the
- * link's target string. Mirrors uploadFile's signature so callers can pick
- * the right primitive once they've classified the entry as link vs file.
- *
- * The target string is stored verbatim — whatever fs.readlinkSync returned.
- * Relative targets transfer cleanly across machines; absolute targets are
- * preserved as-is and may be broken on a destination that doesn't share
- * the source's $HOME layout. Cross-machine portability of absolute targets
- * is out of scope for this primitive — the policy decision lives in the
- * caller (currently: upload anyway, never silently rewrite).
- */
-export async function uploadSymlink(
-  ctx: EntityContext,
-  target: string,
-  key: string,
-  author?: UploadAuthor,
-  precondition?: PutPrecondition,
-): Promise<{ etag: string }> {
-  // Boundary guardrail: never store a non-POSIX key (see toPosixKey), and
-  // never store a key the server-side validator would reject (see
-  // validateVaultUploadKey).
-  key = toPosixKey(key);
-  validateVaultUploadKey(key, uploadScopeFor(ctx));
-  const io = resolveObjectIO(ctx);
-  const symlinkBody = encodeSymlinkBody(target);
-
-  // Fast path: primeUploads() already signed this symlink's metadata into a
-  // cached PUT URL — send the body, replay the cached headers. Fenced PUTs
-  // bypass it — the primed URL carries no conditional header (see uploadFile).
-  if (!precondition && io.hasPrimedPut?.(key)) {
-    const primed = await io.putObject({
-      key,
-      body: symlinkBody,
-      contentType: "application/octet-stream",
-      metadata: {},
-    });
-    return { etag: primed.etag };
-  }
-
-  // Same created-at preservation as uploadFile (shared resolveCreatedAt) so the
-  // NEW-pill window doesn't reset on re-upload, and so a primed PUT matches.
-  const createdAt = await resolveCreatedAt(io, key, author);
-
-  const Metadata: Record<string, string> = {
-    // Marker-only: a constant flag value, not the target. The body
-    // is the source of truth for the target (no 2 KiB cap, no
-    // header-encoding considerations). See SYMLINK_TARGET_META_KEY
-    // doc for the full reasoning.
-    [SYMLINK_TARGET_META_KEY]: SYMLINK_MARKER_META_VALUE,
-    ...(author ? buildAuthorMetadata(author, createdAt) : {}),
-  };
-
-  const response = await io.putObject({
-    key,
-    // Body = SYMLINK_BODY_PREFIX + target (UTF-8). The prefix is what
-    // makes a symlink record's ETag distinguishable from a regular
-    // file whose contents happen to equal the target string — the
-    // LIST-based pull planner can't see per-object metadata, so ETag
-    // is its only drift signal across symlink ↔ regular-file
-    // transitions. See SYMLINK_BODY_PREFIX doc above.
-    body: symlinkBody,
-    contentType: "application/octet-stream",
-    metadata: Metadata,
-    ...(precondition ?? {}),
-  });
-
-  return { etag: response.etag };
-}
-
-/**
- * Download an object to localPath and return its S3 user-metadata.
- *
- * Materializes regular files and symlink records (the symlink branch
- * reconstructs the link from the body/marker). The GetObject response
- * already carries `response.Metadata` (S3 lowercases keys), so we
- * return it to callers — e.g. the pull loop reads `created-by` to
- * attribute downloaded files to their author with zero extra network.
- */
-export interface DownloadModeWarning {
-  /** The mode guardrail that could not be applied exactly. */
-  reason: "missing-hq-mode" | "invalid-hq-mode" | "chmod-failed";
-  /** Legacy objects can retain a local file's known-good permission bits. */
-  fallback?: "preserved-local-mode" | "receiver-default";
-}
-
-/**
- * A download whose parent directory exists as a DANGLING symlink.
- *
- * The vault stores directory symlinks as first-class objects (e.g.
- * `companies/<co>/.obsidian -> ../../.obsidian`) AND stores files beneath them.
- * When the link's target is absent on this machine, the child write fails —
- * and it fails as ENOENT rather than EEXIST, because `mkdir(2)` returns EEXIST
- * for the link and Node's `recursive: true` implementation then stats it, which
- * fails on a dangling link. Raw, that surfaced as a hard error that marked the
- * WHOLE company `errored`/`partial` on every sync cycle (2026-07-24 dogfood box:
- * `.obsidian/hotkeys.json: ENOENT ... mkdir '.../companies/indigo/.obsidian'`).
- *
- * It is a per-object condition, not a company-level failure, so it is typed and
- * the pull loop skips the object loudly instead of failing the run. We do NOT
- * materialize the link target: the target is by definition outside the
- * directory being synced, and creating it would write through a path the
- * caller's containment guard deliberately refuses.
- */
-export class DanglingSymlinkParentError extends Error {
-  readonly key: string;
-  readonly dir: string;
-  constructor(key: string, dir: string) {
-    super(
-      `download skipped: parent directory is a dangling symlink (${dir}) — ` +
-        `the vault stores it as a link whose target is absent locally`,
-    );
-    this.name = "DanglingSymlinkParentError";
-    this.key = key;
-    this.dir = dir;
-  }
-}
-
-/**
- * Create the parent directory for a download, distinguishing the
- * dangling-symlink case from a genuine mkdir failure.
- *
- * Callers must have already established that `dir` does not resolve
- * (`fs.existsSync(dir) === false`); `existsSync` FOLLOWS symlinks, so a
- * dangling link reports absent here while `lstat` still sees the link.
- */
-function ensureDownloadParentDir(dir: string, key: string): void {
-  let link: fs.Stats | null = null;
-  try {
-    link = fs.lstatSync(dir);
-  } catch {
-    // Genuinely absent — the ordinary first-write path.
-  }
-  if (link?.isSymbolicLink()) {
-    throw new DanglingSymlinkParentError(key, dir);
-  }
-  fs.mkdirSync(dir, { recursive: true });
-}
-
-export async function downloadFile(
-  ctx: EntityContext,
-  key: string,
-  localPath: string,
-  options: {
-    beforeReplace?: () => void;
-    /**
-     * Platform override so win32 symlink semantics are directly testable
-     * on any host (same convention as local-path-codec.ts).
-     */
-    win32?: boolean;
-  } = {},
-): Promise<{
-  metadata?: Record<string, string>;
-  contentHash?: string;
-  contentSize?: number;
-  /** Non-fatal mode guardrail warnings for caller telemetry. */
-  modeWarnings?: DownloadModeWarning[];
-}> {
-  const io = resolveObjectIO(ctx);
-
-  const { body, metadata } = await getObjectStream(io, key);
-  const iterator = body[Symbol.asyncIterator]();
-  const initialChunks: Buffer[] = [];
-  let initialLength = 0;
-  while (initialLength < SYMLINK_BODY_PREFIX_BYTES.length) {
-    const next = await iterator.next();
-    if (next.done) break;
-    const chunk = bufferFromChunk(next.value);
-    if (chunk.length === 0) continue;
-    initialChunks.push(chunk);
-    initialLength += chunk.length;
-  }
-
-  const dir = path.dirname(localPath);
-  if (!fs.existsSync(dir)) {
-    ensureDownloadParentDir(dir, key);
-  }
-
-  // Symlink path: presence of SYMLINK_TARGET_META_KEY (any non-empty
-  // value) is the discriminator. The TARGET is now sourced from the
-  // body — the marker-only metadata convention removes the 2 KiB
-  // header limit so long POSIX targets don't fail PutObject.
-  //
-  // S3 lowercases user-metadata keys on read (and sometimes on
-  // write), so the lookup uses the lowercased form. We don't
-  // normalize Metadata keys ourselves — the AWS SDK already does it.
-  const symlinkMarker = metadata?.[SYMLINK_TARGET_META_KEY];
-  // Discriminator: the metadata marker is the primary signal, but the body
-  // prefix is a header-loss fallback (S3 cross-region replication of data
-  // only, a console copy that drops Metadata, a metadata-stripping transport,
-  // or a poisoned regular-file re-upload of a sentinel). Honor BOTH — a
-  // marker-less object whose body starts with SYMLINK_BODY_PREFIX still
-  // rematerializes as a link instead of being written out as plain
-  // `hq-symlink:<target>` text, which would poison the key on the next push.
-  // The body is already buffered (tiny for symlink records); reading it here
-  // is behavior-preserving for regular files (whose body never starts with
-  // the prefix per the SYMLINK_BODY_PREFIX doc). See SYMLINK_BODY_PREFIX.
-  const leading = leadingBytes(
-    initialChunks,
-    initialLength,
-    SYMLINK_BODY_PREFIX_BYTES.length,
-  );
-  const bodyHasSymlinkPrefix =
-    leading.length >= SYMLINK_BODY_PREFIX_BYTES.length &&
-    leading.subarray(0, SYMLINK_BODY_PREFIX_BYTES.length).equals(
-      SYMLINK_BODY_PREFIX_BYTES,
-    );
-  const isSymlinkRecord =
-    (typeof symlinkMarker === "string" && symlinkMarker.length > 0) ||
-    bodyHasSymlinkPrefix;
-  if (isSymlinkRecord) {
-    const objectBody = await collectRemainingChunks(initialChunks, iterator);
-    // The target lives in the body (marker-only metadata convention).
-    // Symlink record bodies are bounded by target length (typically
-    // <300 bytes for relative paths, hard-capped by S3's 5 GB object
-    // size); only this branch buffers the body so regular files can stream.
-    let symlinkTarget: string;
-    if (bodyHasSymlinkPrefix) {
-      symlinkTarget = objectBody.toString(
-        "utf-8",
-        SYMLINK_BODY_PREFIX_BYTES.length,
-      );
-    } else {
-      // Backward-compat fallback: a legacy upload from earlier in
-      // this PR's lifetime stored the target in metadata (raw or
-      // base64) rather than the body. decodeSymlinkMetadataValue
-      // round-trip-validates so a raw value passes through and a
-      // base64 value decodes; either way we get the target. This branch
-      // is only reachable when the body lacks the prefix, which (given
-      // isSymlinkRecord) means the marker is present — the `?? ""` is a
-      // type guard for that invariant, and the length-0 check below
-      // catches the impossible empty case rather than passing it on.
-      symlinkTarget = decodeSymlinkMetadataValue(symlinkMarker ?? "");
-    }
-
-    if (symlinkTarget.length === 0) {
-      throw new Error(
-        `Symlink record for ${key} had no target (body: ${objectBody.length} bytes, marker: ${symlinkMarker})`,
-      );
-    }
-
-    // Idempotence fast path: the .claude/skills link farm makes symlink
-    // records the most re-pulled object class, and a pull that changes
-    // nothing must not touch disk at all (pre-fix, an already-correct
-    // Windows dir link still went through temp+rename, EPERM'd every
-    // pass, never journaled, and re-downloaded forever). On POSIX a
-    // target-string match is sufficient (lstat + readlink — never stat:
-    // dangling links are legitimate). On win32 a matching target string is
-    // NOT sufficient — links are flavored, and a file-type link at a
-    // directory target (minted by an older client, or while the target was
-    // absent) is broken despite the matching string. There the fast path
-    // additionally requires stat-follow to confirm the link FUNCTIONS as
-    // the type win32SymlinkType() would mint now; anything unconfirmable
-    // (including a dangling link, whose flavor cannot be probed) falls
-    // through to replacement, which is cheap and journals correctly.
-    const win32 = options.win32 ?? process.platform === "win32";
-    let existingLink: fs.Stats | null = null;
-    try {
-      existingLink = fs.lstatSync(localPath);
-    } catch {
-      // Absent (or unreadable) destination: no fast path; the normal
-      // materialization below surfaces real filesystem faults loudly.
-    }
-    if (existingLink?.isSymbolicLink()) {
-      let existingTarget: string | null = null;
-      try {
-        existingTarget = fs.readlinkSync(localPath);
-      } catch {
-        // Link raced away between lstat and readlink; replace it below.
-      }
-      if (
-        existingTarget !== null &&
-        symlinkTargetsEqual(existingTarget, symlinkTarget, localPath, win32)
-      ) {
-        if (!win32) return { metadata };
-        const desiredIsDirectory = win32StagedLinkIsDirectoryFlavored(
-          symlinkTarget,
-          localPath,
-        );
-        let followed: fs.Stats | null = null;
-        try {
-          followed = fs.statSync(localPath);
-        } catch {
-          // Unresolvable via this link (dangling, or a wrong-flavor link
-          // that Windows refuses to traverse): recreate below.
-        }
-        if (followed !== null && followed.isDirectory() === desiredIsDirectory) {
-          return { metadata };
-        }
-      }
-    }
-
-    const tempPath = downloadTempPath(localPath);
-    try {
-      // Creation goes through createStagedSymlink (#219): on win32 a directory
-      // overlay becomes an unprivileged JUNCTION rather than a 'dir' NTFS
-      // symlink, which is what stops the EPERM that pushed the one-shot runner
-      // to PARTIAL_SYNC_EXIT. The staged link lands beside `localPath`, so its
-      // flavor decision resolves the target identically to the fast path above.
-      createStagedSymlink(symlinkTarget, tempPath, stagedSymlinkOpsFor(win32));
-      options.beforeReplace?.();
-      replaceStagedPath(tempPath, localPath);
-    } catch (err) {
-      removeTempPath(tempPath);
-      throw err;
-    }
-    return { metadata };
-  }
-  const tempPath = downloadTempPath(localPath);
-  // A legacy object has no hq-mode. If it is replacing a regular local file,
-  // that local mode is the only trustworthy signal we have — retaining it is
-  // strictly safer than replacing (for example) a 0755 hook with the receiver
-  // umask's usual 0644. Never inspect a symlink or infer intent from content.
-  let existingLocalMode: number | undefined;
-  try {
-    const existing = fs.lstatSync(localPath);
-    if (existing.isFile()) existingLocalMode = existing.mode & 0o777;
-  } catch {
-    // Fresh destination / inaccessible prior path: no local fallback.
-  }
-  let tempReady = true;
-  let streamed: { hash: string; size: number };
-  const modeWarnings: DownloadModeWarning[] = [];
-  try {
-    streamed = await streamRegularFileToTemp(tempPath, initialChunks, iterator);
-
-    // Bug #5 — apply source-side mode after the byte write. See
-    // FILE_MODE_META_KEY for the metadata contract. The staged path is a
-    // regular file, then it is atomically renamed over the destination.
-    //
-    // Codex P2 (PR #24 round 3): strict octal-only regex BEFORE parseInt.
-    // parseInt(modeOctal, 8) accepts partial-prefix garbage — "755junk"
-    // parses to 0o755 instead of NaN — so tampered or malformed metadata
-    // could still change local permissions unexpectedly. The regex
-    // requires 1–4 pure octal digits (`[0-7]{1,4}$`), which matches what
-    // the upload side stamps (`(mode & 0o777).toString(8)` → at most
-    // three digits, all 0–7) and rejects everything else.
-    const modeOctal = metadata?.[FILE_MODE_META_KEY];
-    let modeToApply: number | undefined;
-    if (typeof modeOctal === "string" && /^[0-7]{1,4}$/.test(modeOctal)) {
-      const parsed = parseInt(modeOctal, 8);
-      if (Number.isFinite(parsed) && parsed >= 0 && parsed <= 0o777) {
-        modeToApply = parsed;
-      }
-    } else if (modeOctal === undefined) {
-      modeToApply = existingLocalMode;
-      modeWarnings.push({
-        reason: "missing-hq-mode",
-        fallback:
-          existingLocalMode === undefined
-            ? "receiver-default"
-            : "preserved-local-mode",
-      });
-    } else {
-      modeWarnings.push({ reason: "invalid-hq-mode", fallback: "receiver-default" });
-    }
-
-    if (modeToApply !== undefined) {
-      try {
-        fs.chmodSync(tempPath, modeToApply);
-      } catch {
-        // chmod failure (read-only FS, EPERM) is non-fatal — the file is
-        // materialized, but callers must receive a telemetry signal instead
-        // of silently believing the guardrail held.
-        modeWarnings.push({ reason: "chmod-failed" });
-      }
-    }
-
-    // 5.37.0 — apply source-side mtime after the byte write (and after the
-    // chmod above; ordering between chmod and utimes doesn't matter, but
-    // both must run AFTER writeFileSync because writeFileSync resets mtime
-    // to wall-clock-now). See FILE_MTIME_META_KEY for the metadata contract.
-    //
-    // Strict-numeric regex BEFORE parseInt — same Codex P2 lesson as hq-mode.
-    // `^-?[0-9]{1,16}$` rejects partial-prefix garbage ("175junk" → 175),
-    // empty, double-signed, decimals, whitespace, and oversized strings. A
-    // single optional leading `-` is allowed so pre-epoch / reproducible-build
-    // timestamps round-trip (Codex PR #27 P2 — `mtimeMs === 0` and negative
-    // epoch values are legitimate). 16 digits comfortably covers any plausible
-    // epoch-ms value (year ~5138 is 16 digits; we'll cross that bridge later).
-    //
-    // The staged file is regular; rename preserves these stamps at localPath.
-    //
-    // Composition with the 5.36.0 lstat fast-path: the journal stamp at the
-    // share/sync call sites runs AFTER downloadFile returns, so the lstat
-    // it captures sees the post-utimes mtime. Verified in cli/sync.ts
-    // (downloadFile → lstatSync → updateEntry) and cli/share.ts (pull path
-    // similarly lstats after downloadFile). If a future caller stamps the
-    // journal BEFORE downloadFile completes, the fast-path will stale and
-    // re-hash every sync forever — keep the call-site invariant intact.
-    const mtimeRaw = metadata?.[FILE_MTIME_META_KEY];
-    if (typeof mtimeRaw === "string" && /^-?[0-9]{1,16}$/.test(mtimeRaw)) {
-      const mtimeMs = parseInt(mtimeRaw, 10);
-      if (Number.isFinite(mtimeMs)) {
-        try {
-          // utimesSync accepts seconds OR Date; use Date(ms) for precision.
-          // atime = mtime is fine — many filesystems are mounted noatime
-          // and distinguishing "access" vs "modification" time doesn't
-          // matter for sync semantics. Setting both keeps the on-disk
-          // state deterministic across receivers.
-          const mtimeDate = new Date(mtimeMs);
-          fs.utimesSync(tempPath, mtimeDate, mtimeDate);
-        } catch {
-          // EPERM / read-only FS / file just unlinked → non-fatal. The
-          // file is materialized at write-time mtime; the source-of-truth
-          // can re-sync next pass.
-        }
-      }
-    }
-
-    options.beforeReplace?.();
-    replaceStagedPath(tempPath, localPath);
-    tempReady = false;
-  } finally {
-    if (tempReady) removeTempPath(tempPath);
-  }
-
-  // TODO: stamp hq-btime once Node lands lbirthtime (or birthtimeSync).
-  // The push side already emits hq-btime when the source FS tracks a
-  // distinct creation time, so a future receiver upgrade picks it up
-  // automatically without a server-side data migration.
-
-  if (modeWarnings.length > 0) {
-    for (const warning of modeWarnings) {
-      console.warn(
-        `[hq-sync] mode warning for ${key}: ${warning.reason}` +
-          (warning.fallback ? ` (${warning.fallback})` : ""),
-      );
-    }
-  }
-
-  return {
-    metadata,
-    contentHash: streamed.hash,
-    contentSize: streamed.size,
-    ...(modeWarnings.length > 0 ? { modeWarnings } : {}),
-  };
-}
-
-export interface RemoteFile {
-  key: string;
-  size: number;
-  lastModified: Date;
-  etag: string;
-}
-
-export async function listRemoteFiles(
-  ctx: EntityContext,
-  prefix?: string,
-): Promise<RemoteFile[]> {
-  const io = resolveObjectIO(ctx);
-  const files: RemoteFile[] = [];
-  let continuationToken: string | undefined;
-
-  do {
-    const page = await io.listObjects({ prefix, continuationToken });
-
-    for (const obj of page.objects) {
-      // Drop S3 directory-marker objects: the canonical shape is `0-byte
-      // key ending in '/'` (S3 console "Create folder", `aws s3 sync` of
-      // empty dirs, sync tools that mirror empty trees). Two downstream
-      // sites blow up on them — pull planner (sync.ts: `hashFile` calls
-      // `readFileSync` on an existing local dir → EISDIR "read") and the
-      // download path (s3.ts: `writeFileSync` on a trailing-slash path
-      // → EISDIR "open" after the parent mkdir creates the leaf as a
-      // directory). Filtering here eliminates both.
-      //
-      // Narrow on size===0 (not just trailing-slash) so a hypothetical
-      // non-empty object whose key happens to end in '/' is NOT silently
-      // hidden — it stays visible and downloadFile surfaces the same
-      // EISDIR "open" error pointing at the specific key, which is the
-      // signal an operator needs to reconcile the bucket. The vault
-      // service doesn't have a code path that produces such an object,
-      // but the listing returns whatever lives in the bucket; silent
-      // drop would be worse than loud failure for that case.
-      //
-      // Real 0-byte placeholders like `.gitkeep` never end in `/` and
-      // continue to flow through — the 5.13.0 `.gitkeep` regression
-      // remains fixed. (The `!key` guard now lives in the ObjectIO layer.)
-      if (obj.key.endsWith("/") && obj.size === 0) continue;
-
-      files.push({
-        key: obj.key,
-        size: obj.size,
-        lastModified: obj.lastModified,
-        etag: obj.etag,
-      });
-    }
-
-    continuationToken = page.nextContinuationToken;
-  } while (continuationToken);
-
-  return files;
-}
-
-export async function deleteRemoteFile(
-  ctx: EntityContext,
-  key: string,
-): Promise<void> {
-  await resolveObjectIO(ctx).deleteObject(key);
-}
-
-/**
- * Check if a remote key exists and return its metadata.
- */
-export async function headRemoteFile(
-  ctx: EntityContext,
-  key: string,
-): Promise<{ lastModified: Date; etag: string; size: number; metadata?: Record<string, string> } | null> {
-  return resolveObjectIO(ctx).headObject(key);
-}
-
-function getMimeType(filePath: string): string {
-  const ext = path.extname(filePath).toLowerCase();
-  const mimeTypes: Record<string, string> = {
-    ".md": "text/markdown",
-    ".json": "application/json",
-    ".yaml": "text/yaml",
-    ".yml": "text/yaml",
-    ".ts": "text/typescript",
-    ".js": "text/javascript",
-    ".txt": "text/plain",
-    ".html": "text/html",
-    ".css": "text/css",
-    ".png": "image/png",
-    ".jpg": "image/jpeg",
-    ".jpeg": "image/jpeg",
-    ".svg": "image/svg+xml",
-    ".pdf": "application/pdf",
-  };
-  return mimeTypes[ext] || "application/octet-stream";
-}