@indigoai-us/hq-cloud 5.16.0 → 5.18.1

package/src/cli/sync.test.ts

@@ -740,4 +740,349 @@ describe("sync", () => {
       filesToSkip: 0,
     });
   });
+
+  it("stamps the journal with sha256(target) + size 0 when the downloaded entry is a symlink", async () => {
+    // Pre-fix, the post-download journal stamp called hashFile (which
+    // follows the link and reads the target file's bytes) and statSync
+    // (which follows the link and reports the target's size). The next
+    // push's skipUnchanged check would then compare its own
+    // sha256(target string) against the journal's "target file bytes"
+    // hash, never match, and re-upload every symlink on every tick. The
+    // fix: when localPath is a symlink after downloadFile, stamp the
+    // hash of readlink(localPath) and size 0 — exactly the values the
+    // push side would produce next.
+    const linkKey = "policies/personal-link.md";
+    const linkTarget = "../../personal/policies/real.md";
+
+    vi.mocked(s3Module.listRemoteFiles).mockResolvedValueOnce([
+      { key: linkKey, size: 0, lastModified: new Date(), etag: '"link-etag"' },
+    ]);
+    vi.mocked(s3Module.downloadFile).mockImplementationOnce(
+      async (_ctx: unknown, _key: string, localPath: string) => {
+        const dir = path.dirname(localPath);
+        if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+        // Mirror real downloadFile's symlink branch.
+        fs.symlinkSync(linkTarget, localPath);
+      },
+    );
+
+    const result = await sync({
+      company: "acme",
+      vaultConfig: mockConfig,
+      hqRoot: tmpDir,
+    });
+    expect(result.filesDownloaded).toBe(1);
+
+    // Recompute the expected hash from the target string — same helper
+    // the push side uses in computePushPlan for kind: "symlink", so
+    // skip-unchanged works on the next tick.
+    const journalMod = await import("../journal.js");
+    const expectedHash = journalMod.hashSymlinkTarget(linkTarget);
+
+    const journal = JSON.parse(fs.readFileSync(journalPath, "utf-8"));
+    expect(journal.files[linkKey]).toMatchObject({
+      hash: expectedHash,
+      size: 0,
+      direction: "down",
+    });
+  });
+
+  it("does not crash when local is a real directory at a remote-key path (EISDIR guard)", async () => {
+    // Codex round-9 P2 follow-up: pre-fix, the pull planner's
+    // post-lstat branch always called hashFile (readFileSync) on a
+    // localPath whose lstat succeeded but wasn't a symlink. For a
+    // local *directory* at a remote-key path (e.g. user has
+    // `companies/acme/knowledge/` as a real dir, cloud has a single
+    // object at the same key), readFileSync threw EISDIR and the
+    // entire sync run aborted during planning. The fix surfaces it
+    // as a non-fatal skip-local-only with a warning so the operator
+    // can manually reconcile rather than crash the whole pull.
+    const localDirKey = "knowledge";
+    const localDir = path.join(tmpDir, "companies", "acme", localDirKey);
+    fs.mkdirSync(localDir, { recursive: true });
+    fs.writeFileSync(path.join(localDir, "inside.md"), "local-only content");
+
+    vi.mocked(s3Module.listRemoteFiles).mockResolvedValueOnce([
+      {
+        key: localDirKey,
+        size: 100,
+        lastModified: new Date(),
+        etag: '"some-etag"',
+      },
+    ]);
+    const warnSpy = vi.spyOn(console, "error").mockImplementation(() => {});
+
+    let crashed = false;
+    let result;
+    try {
+      result = await sync({
+        company: "acme",
+        vaultConfig: mockConfig,
+        hqRoot: tmpDir,
+      });
+    } catch {
+      crashed = true;
+    }
+    warnSpy.mockRestore();
+
+    expect(crashed).toBe(false);
+    expect(result).toBeDefined();
+    // Skipped, not downloaded — destructive replacement of a local
+    // directory is a manual-reconciliation decision, not an automatic
+    // sync action.
+    expect(result!.filesDownloaded).toBe(0);
+    expect(result!.filesSkipped).toBe(1);
+    // Local directory still intact.
+    expect(fs.existsSync(path.join(localDir, "inside.md"))).toBe(true);
+  });
+
+  it("pulls a remote symlink record under an .hqinclude dir-only allowlist pattern", async () => {
+    // Codex round-7 P1 follow-up: pre-fix, computePullPlan called
+    // shouldSync(localPath) with the default isDir=false. LIST gives
+    // no file-vs-dir signal, so a remote symlink record at a path
+    // covered only by a dir-only .hqinclude pattern (e.g.
+    // `companies/*/knowledge/`) would be classified skip-ignored —
+    // the symlink record uploaded by the push-side fix would never
+    // propagate to peers. Symmetric to the walkDir/collectFiles
+    // dual-hint fix on the push side.
+    const linkKey = "knowledge";
+    const linkTarget = "../../repos/private/knowledge-acme";
+    // Allowlist with ONLY a dir-only pattern. The pre-fix bug was
+    // that the slashless probe didn't match this rule, so a bare
+    // `knowledge` alternative would mask the regression — keep the
+    // pattern strictly dir-only so the dual-hint probe is what
+    // actually has to make the test pass.
+    fs.writeFileSync(path.join(tmpDir, ".hqinclude"), "knowledge/\n");
+
+    vi.mocked(s3Module.listRemoteFiles).mockResolvedValueOnce([
+      { key: linkKey, size: 5, lastModified: new Date(), etag: '"link-etag-3"' },
+    ]);
+    let downloadCalls = 0;
+    vi.mocked(s3Module.downloadFile).mockImplementationOnce(
+      async (_ctx: unknown, _key: string, localPath: string) => {
+        downloadCalls++;
+        const dir = path.dirname(localPath);
+        if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+        fs.symlinkSync(linkTarget, localPath);
+      },
+    );
+
+    const result = await sync({
+      company: "acme",
+      vaultConfig: mockConfig,
+      hqRoot: tmpDir,
+    });
+
+    // Pre-fix: filesDownloaded=0, filesSkipped=1 (skip-ignored).
+    // Post-fix: filesDownloaded=1.
+    expect(downloadCalls).toBe(1);
+    expect(result.filesDownloaded).toBe(1);
+    expect(
+      fs
+        .lstatSync(path.join(tmpDir, "companies", "acme", linkKey))
+        .isSymbolicLink(),
+    ).toBe(true);
+  });
+
+  it("does not flag a pristine local symlink as locally-changed in the pull planner", async () => {
+    // Codex P2 follow-up: pre-fix, computePullPlan called hashFile on
+    // localPath (which follows symlinks → hashes the target file's
+    // bytes) and compared that against the journal's
+    // sha256(target string). The hashes never matched, so a pristine
+    // symlink was always classified localChanged. Combined with a
+    // remote-side change from another machine, that mis-classified as a
+    // conflict and aborted overwrites; without remote change, it was
+    // only logged as skip-local-only. Either way the planner thought
+    // the local link was "edited" when it wasn't.
+    const linkKey = "policies/personal-link.md";
+    const linkTarget = "../../personal/policies/real.md";
+    // listRemoteFiles surfaces the raw S3 etag with literal quotes;
+    // the journal stamps the normalized (unquoted) form. Match the
+    // journal convention here so hasRemoteChanged returns false.
+    const remoteEtagWire = '"link-etag-2"';
+    const remoteEtagNormalized = "link-etag-2";
+
+    // Pre-create the link locally so the planner sees an existing
+    // symlink, and pre-stamp the journal with the SAME hash the push
+    // side would have written (hashSymlinkTarget of the target string).
+    const companyRoot = path.join(tmpDir, "companies", "acme");
+    const linkDir = path.dirname(path.join(companyRoot, linkKey));
+    fs.mkdirSync(linkDir, { recursive: true });
+    fs.symlinkSync(linkTarget, path.join(companyRoot, linkKey));
+    const journalMod = await import("../journal.js");
+    const matchingHash = journalMod.hashSymlinkTarget(linkTarget);
+    fs.writeFileSync(
+      journalPath,
+      JSON.stringify({
+        version: "1",
+        lastSync: new Date().toISOString(),
+        files: {
+          [linkKey]: {
+            hash: matchingHash,
+            size: 0,
+            syncedAt: new Date().toISOString(),
+            direction: "down",
+            remoteEtag: remoteEtagNormalized,
+          },
+        },
+      }),
+    );
+
+    vi.mocked(s3Module.listRemoteFiles).mockResolvedValue([
+      { key: linkKey, size: 0, lastModified: new Date(), etag: remoteEtagWire },
+    ]);
+    // downloadFile must NOT be called: the planner should skip
+    // (unchanged on both sides). Use a sentinel that throws if invoked.
+    vi.mocked(s3Module.downloadFile).mockImplementation(async () => {
+      throw new Error("download must not be called for unchanged symlink");
+    });
+
+    const result = await sync({
+      company: "acme",
+      vaultConfig: mockConfig,
+      hqRoot: tmpDir,
+    });
+
+    expect(result.filesDownloaded).toBe(0);
+    expect(result.filesSkipped).toBe(1);
+    expect(result.conflicts).toBe(0);
+  });
+
+  it("classifies a dangling-symlink + remote-change as a conflict without crashing on statSync", async () => {
+    // Codex round-11 P2 follow-up: pre-fix, the conflict executor
+    // built the resolveConflict prompt with `fs.statSync(localPath).
+    // mtime`, which follows symlinks. For a dangling symlink (target
+    // missing locally) that ALSO had a target rewrite (localChanged)
+    // and a remote change (remoteChanged), the planner classified it
+    // as a conflict, then statSync threw ENOENT trying to follow the
+    // dangling link to read mtime — aborting the entire pull before
+    // resolveConflict could run. Fix: carry the planner's lstat
+    // mtime forward through PullPlanItem.conflict.localMtime so the
+    // executor never re-stats the path.
+    const linkKey = "dangling-link.md";
+    // Old target — what the journal-recorded hash will reflect.
+    const oldTarget = "old-target.md";
+    // New (current) target — points to a path that doesn't exist
+    // locally → the link is dangling. The hash differs from the
+    // journal so localChanged = true.
+    const newTarget = "missing-target.md";
+
+    const companyRoot = path.join(tmpDir, "companies", "acme");
+    fs.mkdirSync(companyRoot, { recursive: true });
+    fs.symlinkSync(newTarget, path.join(companyRoot, linkKey));
+
+    // Pre-stamp the journal with the OLD target's symlink hash, plus a
+    // remoteEtag that won't match the LIST etag we mock (forcing
+    // remoteChanged = true on top of localChanged = true).
+    const journalMod = await import("../journal.js");
+    const oldHash = journalMod.hashSymlinkTarget(oldTarget);
+    fs.writeFileSync(
+      journalPath,
+      JSON.stringify({
+        version: "1",
+        lastSync: new Date().toISOString(),
+        files: {
+          [linkKey]: {
+            hash: oldHash,
+            size: 0,
+            syncedAt: new Date().toISOString(),
+            direction: "down",
+            remoteEtag: "old-remote-etag",
+          },
+        },
+      }),
+    );
+
+    vi.mocked(s3Module.listRemoteFiles).mockResolvedValueOnce([
+      {
+        key: linkKey,
+        size: 30,
+        lastModified: new Date(),
+        etag: '"new-remote-etag"',
+      },
+    ]);
+
+    // Auto-resolve the conflict by aborting. What we're really testing
+    // is that the executor *reaches* resolveConflict at all — pre-fix
+    // it crashed at fs.statSync before getting there.
+    const result = await sync({
+      company: "acme",
+      vaultConfig: mockConfig,
+      hqRoot: tmpDir,
+      onConflict: "abort",
+    });
+
+    expect(result.aborted).toBe(true);
+    expect(result.conflicts).toBe(1);
+    expect(result.conflictPaths).toContain(linkKey);
+  });
+
+  it("conflict resolution 'keep' on a dangling symlink stamps the journal so it doesn't re-fire next sync", async () => {
+    // Codex round-12 P2 follow-up: pre-fix, the keep/skip branch of
+    // the conflict executor called `fs.statSync(localPath).size` to
+    // populate the journal stamp. For a dangling symlink, statSync
+    // followed the link and threw ENOENT, the catch swallowed it,
+    // and the journal was never updated — so the next sync saw the
+    // same localChanged && remoteChanged combination and prompted
+    // for the SAME conflict forever, ignoring the user's keep
+    // choice. Fix: carry localSize (symlink-aware: 0 for symlinks)
+    // through the conflict item so the executor never re-stats.
+    const linkKey = "dangling-keep.md";
+    const oldTarget = "old-target.md";
+    const newTarget = "missing-target.md";
+    const newRemoteEtagWire = '"new-remote-etag-keep"';
+    const newRemoteEtagNormalized = "new-remote-etag-keep";
+
+    const companyRoot = path.join(tmpDir, "companies", "acme");
+    fs.mkdirSync(companyRoot, { recursive: true });
+    fs.symlinkSync(newTarget, path.join(companyRoot, linkKey));
+
+    const journalMod = await import("../journal.js");
+    const oldHash = journalMod.hashSymlinkTarget(oldTarget);
+    const expectedNewHash = journalMod.hashSymlinkTarget(newTarget);
+    fs.writeFileSync(
+      journalPath,
+      JSON.stringify({
+        version: "1",
+        lastSync: new Date().toISOString(),
+        files: {
+          [linkKey]: {
+            hash: oldHash,
+            size: 0,
+            syncedAt: new Date().toISOString(),
+            direction: "down",
+            remoteEtag: "old-remote-etag-keep",
+          },
+        },
+      }),
+    );
+
+    vi.mocked(s3Module.listRemoteFiles).mockResolvedValueOnce([
+      {
+        key: linkKey,
+        size: 30,
+        lastModified: new Date(),
+        etag: newRemoteEtagWire,
+      },
+    ]);
+
+    const result = await sync({
+      company: "acme",
+      vaultConfig: mockConfig,
+      hqRoot: tmpDir,
+      onConflict: "keep",
+    });
+
+    expect(result.aborted).toBe(false);
+    expect(result.conflicts).toBe(1);
+
+    // The journal MUST be updated to reflect the user's keep
+    // decision. Pre-fix: catch swallowed the ENOENT, journal stayed
+    // at oldHash + old etag, every subsequent sync re-fired.
+    const journal = JSON.parse(fs.readFileSync(journalPath, "utf-8"));
+    const entry = journal.files[linkKey];
+    expect(entry.hash).toBe(expectedNewHash);
+    expect(entry.size).toBe(0);
+    expect(entry.remoteEtag).toBe(newRemoteEtagNormalized);
+  });
 });

package/src/cli/sync.ts

@@ -11,7 +11,15 @@ import type { VaultServiceConfig, SyncJournal } from "../types.js";
 import { resolveEntityContext, isExpiringSoon, refreshEntityContext } from "../context.js";
 import { downloadFile, listRemoteFiles, headRemoteFile } from "../s3.js";
 import type { RemoteFile } from "../s3.js";
-import { readJournal, writeJournal, hashFile, updateEntry, getEntry, normalizeEtag } from "../journal.js";
+import {
+  readJournal,
+  writeJournal,
+  hashFile,
+  hashSymlinkTarget,
+  updateEntry,
+  getEntry,
+  normalizeEtag,
+} from "../journal.js";
 import { createIgnoreFilter } from "../ignore.js";
 import { resolveConflict } from "./conflict.js";
 import type { ConflictStrategy, ConflictResolution } from "./conflict.js";
@@ -235,7 +243,10 @@ export async function sync(options: SyncOptions): Promise<SyncResult> {
           path: remoteFile.key,
           localHash: item.localHash,
           remoteModified: remoteFile.lastModified,
-          localModified: fs.statSync(localPath).mtime,
+          // Use the lstat-mtime captured by the planner — statSync
+          // here would follow a dangling symlink and throw ENOENT,
+          // aborting the pull before resolveConflict could prompt.
+          localModified: item.localMtime,
           direction: "pull",
         },
         onConflict,
@@ -311,19 +322,20 @@ export async function sync(options: SyncOptions): Promise<SyncResult> {
         // the next sync "no change on either side" until something new
         // diverges. Without this, both `localChanged` and `remoteChanged`
         // stay true forever and the conflict is sticky.
-        try {
-          const stat = fs.statSync(localPath);
-          updateEntry(
-            journal,
-            remoteFile.key,
-            item.localHash,
-            stat.size,
-            "down",
-            remoteFile.etag,
-          );
-        } catch {
-          // best-effort — sync continues even if stat fails
-        }
+        // Stamp from planner-captured size (symlink-aware), NOT
+        // statSync — which would follow a dangling symlink and
+        // throw ENOENT, get swallowed, and leave the journal
+        // stale so this conflict would re-fire on every sync
+        // forever. localSize is sourced from the same lstat that
+        // computed localMtime + localHash above.
+        updateEntry(
+          journal,
+          remoteFile.key,
+          item.localHash,
+          item.localSize,
+          "down",
+          remoteFile.etag,
+        );
         continue;
       }
       // "overwrite" falls through to download
@@ -333,11 +345,24 @@ export async function sync(options: SyncOptions): Promise<SyncResult> {
     try {
       await downloadFile(ctx, remoteFile.key, localPath);
 
-      const hash = hashFile(localPath);
-      const stat = fs.statSync(localPath);
+      // Symlink records materialize as real symlinks on disk. lstat
+      // (does not follow) lets us detect that case so the journal stamp
+      // mirrors what the push side would emit on the next tick:
+      //   hash = sha256(readlink target string)
+      //   size = 0
+      // Without this check, hashFile would follow the link and stamp the
+      // target file's contents — a value the next push would never
+      // produce — which makes skipUnchanged perpetually re-upload every
+      // symlink, defeating the point of the gate.
+      const localLstat = fs.lstatSync(localPath);
+      const isLocalSymlink = localLstat.isSymbolicLink();
+      const hash = isLocalSymlink
+        ? hashSymlinkTarget(fs.readlinkSync(localPath))
+        : hashFile(localPath);
+      const size = isLocalSymlink ? 0 : fs.statSync(localPath).size;
       // Capture the listing's ETag so subsequent syncs can detect remote
       // drift independently of mtime drift.
-      updateEntry(journal, remoteFile.key, hash, stat.size, "down", remoteFile.etag);
+      updateEntry(journal, remoteFile.key, hash, size, "down", remoteFile.etag);
 
       // Attach message from the prior journal entry if present (set by a
       // previous `share` operation that included a --message).
@@ -346,12 +371,12 @@ export async function sync(options: SyncOptions): Promise<SyncResult> {
       emit({
         type: "progress",
         path: remoteFile.key,
-        bytes: stat.size,
+        bytes: size,
         ...(remoteJournalMessage ? { message: remoteJournalMessage } : {}),
       });
 
       filesDownloaded++;
-      bytesDownloaded += stat.size;
+      bytesDownloaded += size;
     } catch (err) {
       // STS session policy may deny access to some paths — this is expected
       // for guest members with allowedPrefixes
@@ -471,6 +496,22 @@ type PullPlanItem =
       remoteFile: RemoteFile;
       localPath: string;
       localHash: string;
+      // Captured from the planner's lstat (does NOT follow symlinks),
+      // so a dangling symlink doesn't make the conflict executor
+      // statSync-then-ENOENT and abort the whole pull. See the
+      // executor: prior to this field, the prompt builder called
+      // fs.statSync(localPath).mtime to populate the conflict UI's
+      // "local modified at X" line, which crashed for dangling links.
+      localMtime: Date;
+      // Symlink-aware size for the post-resolution journal stamp.
+      // For a symlink, journal convention is 0 (the wire body is
+      // empty + target metadata; matches what the push side stamps).
+      // For a regular file, mirrors the on-disk byte length. The
+      // executor's keep/skip branch reads this instead of calling
+      // fs.statSync(localPath), which would follow a dangling link
+      // and silently fail to stamp the journal — leaving the
+      // conflict to re-fire forever.
+      localSize: number;
     };
 
 interface PullPlan {
@@ -499,7 +540,7 @@ function computePullPlan(
   remoteFiles: RemoteFile[],
   journal: SyncJournal,
   companyRoot: string,
-  shouldSync: (filePath: string) => boolean,
+  shouldSync: (filePath: string, isDir?: boolean) => boolean,
   personalMode: boolean,
 ): PullPlan {
   const items: PullPlanItem[] = [];
@@ -512,16 +553,72 @@ function computePullPlan(
       continue;
     }
 
-    if (!shouldSync(localPath)) {
+    // LIST gives us no kind signal for the remote object — we don't
+    // know whether this key is a regular file or a symlink record
+    // until we either HEAD it (expensive — N extra calls per pull) or
+    // download it. So probe the ignore filter with BOTH isDir hints
+    // and include the entry if either probe passes. Without this,
+    // a symlink record at a dir-only-allowlisted path (e.g. an
+    // .hqinclude of `companies/*/knowledge/`) would be classified
+    // skip-ignored and the symlinks freshly uploaded by the
+    // push-side fix would never propagate. Mirrors the dual-hint
+    // probe in walkDir/collectFiles. Pure path lookup, no I/O.
+    if (!shouldSync(localPath, false) && !shouldSync(localPath, true)) {
       items.push({ action: "skip-ignored", remoteFile, localPath });
       continue;
     }
 
     const journalEntry = getEntry(journal, remoteFile.key);
-    const localExists = fs.existsSync(localPath);
+    // lstat (not existsSync/statSync) handles three cases the legacy
+    // checks got wrong for symlinks:
+    //   1. A valid symlink at localPath: existsSync returns true and the
+    //      planner falls through to hashFile, which follows the link and
+    //      hashes the target file's bytes — never matching the journal's
+    //      sha256(target string), so every pull would mis-classify a
+    //      pristine symlink as locally changed.
+    //   2. A dangling symlink: existsSync returns false (existsSync
+    //      follows links) so the planner treats the entry as missing and
+    //      re-downloads, silently clobbering the user's intentional
+    //      dangling link on every run.
+    //   3. A regular file: indistinguishable from current behaviour.
+    let localLstat: fs.Stats | null = null;
+    try {
+      localLstat = fs.lstatSync(localPath);
+    } catch (err: unknown) {
+      // ENOENT means truly absent; other errors propagate.
+      if (
+        err &&
+        typeof err === "object" &&
+        "code" in err &&
+        (err as { code?: string }).code !== "ENOENT"
+      ) {
+        throw err;
+      }
+    }
+    const localExists = localLstat !== null;
 
     if (localExists) {
-      const localHash = hashFile(localPath);
+      const isLocalSymlink = localLstat!.isSymbolicLink();
+      // Kind-mismatch guard: a remote LIST entry is always a single
+      // S3 object (regular file or symlink record), but the local
+      // path may be a real directory if the user previously had a
+      // dir at this key. Hashing a directory throws EISDIR and
+      // aborts the whole pull. We don't auto-replace because that
+      // would `rm -rf` the user's directory; surface as a non-fatal
+      // skip and warn so the operator can reconcile manually
+      // (delete the local dir, or restructure the remote).
+      if (localLstat!.isDirectory() && !isLocalSymlink) {
+        console.error(
+          `  Warning: ${remoteFile.key} exists locally as a directory; ` +
+            `cloud has a single object at this key. Skipping; manual ` +
+            `reconciliation required (rm -rf the local directory to pull).`,
+        );
+        items.push({ action: "skip-local-only", remoteFile, localPath });
+        continue;
+      }
+      const localHash = isLocalSymlink
+        ? hashSymlinkTarget(fs.readlinkSync(localPath))
+        : hashFile(localPath);
       const localChanged = !!journalEntry && journalEntry.hash !== localHash;
       const remoteChanged =
         !!journalEntry && hasRemoteChanged(remoteFile, journalEntry);
@@ -535,6 +632,18 @@ function computePullPlan(
           remoteFile,
           localPath,
           localHash,
+          // localLstat is non-null inside this `if (localExists)`
+          // branch — the planner already lstat'd the path. Carry
+          // its mtime forward so the executor doesn't have to
+          // re-stat (which would follow links and crash on a
+          // dangling symlink). Same goes for size: the conflict
+          // executor's keep/skip branch needs to stamp the
+          // journal with a size, and statSync on a dangling
+          // symlink throws ENOENT (silently swallowed pre-fix),
+          // leaving the journal stale and re-firing the conflict
+          // every sync.
+          localMtime: localLstat!.mtime,
+          localSize: isLocalSymlink ? 0 : localLstat!.size,
         });
         continue;
       }

package/src/journal.ts

@@ -74,6 +74,39 @@ export function hashFile(filePath: string): string {
   return crypto.createHash("sha256").update(content).digest("hex");
 }
 
+/**
+ * Marker prepended to a symlink's target string before hashing for the
+ * journal. Mirrors the wire-side `SYMLINK_BODY_PREFIX` constant in
+ * `s3.ts` — same purpose, different namespace.
+ *
+ * Without this marker, a symlink to `real.md` and a regular file whose
+ * contents are exactly the bytes `real.md` produce identical journal
+ * hashes (both `sha256("real.md")`). When `skipUnchanged` is enabled,
+ * the planner would treat a regular-file → symlink replacement as
+ * "no change" and never upload the new symlink, leaving the remote
+ * representation stale forever — the pull side would then also see no
+ * drift via ETag and never repair.
+ *
+ * Hashing `sha256(prefix + target)` makes the two representations
+ * structurally inequal in journal-hash space, so skip-unchanged can
+ * never confuse them. The hash always varies with the target string,
+ * so target rewrites still re-fire uploads as expected.
+ */
+export const SYMLINK_HASH_PREFIX = "hq-symlink:";
+
+/**
+ * Compute the journal hash for a symlink. Always use this helper
+ * (never inline `crypto.createHash` with the raw target) so the
+ * push side, the pull-planner, and the post-download stamp stay in
+ * lockstep on the prefixed-hash convention.
+ */
+export function hashSymlinkTarget(target: string): string {
+  return crypto
+    .createHash("sha256")
+    .update(SYMLINK_HASH_PREFIX + target)
+    .digest("hex");
+}
+
 export function updateEntry(
   journal: SyncJournal,
   relativePath: string,