@indigoai-us/hq-cloud 6.14.37 → 6.14.40

package/src/cli/share.ts

@@ -72,6 +72,7 @@ import { appendConflictEntry } from "../lib/conflict-index.js";
 import { isCloudAuthoritative } from "../lib/cloud-authoritative.js";
 import { VaultAuthError } from "../vault-client.js";
 import { describeError } from "../lib/describe-error.js";
+import { readlinkOrNull } from "../lib/readlink-safe.js";
 
 /**
  * Push-side fresh-collision convergence probe.
@@ -725,7 +726,7 @@ export interface ShareOptions {
 }
 
 /** Why an explicitly-named push path could not be shipped. */
-export type UnreachablePathReason = "missing" | "outside-company";
+export type UnreachablePathReason = "missing" | "outside-company" | "unreadable-link";
 
 /**
  * Thrown by `share()` when a caller-named path cannot be pushed and
@@ -743,9 +744,13 @@ export class UnreachablePushPathsError extends Error {
     const paths = [...unreachable.keys()];
     const lines = paths.map((p) => {
       const reason = unreachable.get(p);
-      return reason === "outside-company"
-        ? `  · ${p} — resolves outside the company folder (${syncRoot})`
-        : `  · ${p} — not found under the hq root, the company folder, or the current directory`;
+      if (reason === "outside-company") {
+        return `  · ${p} — resolves outside the company folder (${syncRoot})`;
+      }
+      if (reason === "unreadable-link") {
+        return `  · ${p} — symbolic link target could not be read; it was not dereferenced or uploaded`;
+      }
+      return `  · ${p} — not found under the hq root, the company folder, or the current directory`;
     });
     super(
       `${paths.length} named path${paths.length === 1 ? "" : "s"} could not be pushed; ` +
@@ -1826,7 +1831,17 @@ async function executeDeletes(
         }
         fs.unlinkSync(localPath);
       } else if (lstat.isSymbolicLink()) {
-        const localHash = hashSymlinkTarget(fs.readlinkSync(localPath));
+        const target = readlinkOrNull(localPath);
+        if (target === null) {
+          run.emit({
+            type: "not-shipped",
+            reason: "unreadable-link",
+            count: 1,
+            samplePaths: [relativePath],
+          });
+          continue;
+        }
+        const localHash = hashSymlinkTarget(target);
         if (entry?.hash && entry.hash !== localHash) {
           run.emit({
             type: "error",
@@ -1992,12 +2007,27 @@ function collectFatalUnreachablePaths(
  */
 function emitUnreachablePathEvent(run: PushRunContext): void {
   if (run.unreachablePaths.size === 0) return;
-  run.emit({
-    type: "not-shipped",
-    reason: "unreachable-path",
-    count: run.unreachablePaths.size,
-    samplePaths: sampleSet(run.unreachablePaths.keys()),
-  });
+  const unreadableLinks: string[] = [];
+  const unreachablePaths: string[] = [];
+  for (const [namedPath, reason] of run.unreachablePaths) {
+    (reason === "unreadable-link" ? unreadableLinks : unreachablePaths).push(namedPath);
+  }
+  if (unreachablePaths.length > 0) {
+    run.emit({
+      type: "not-shipped",
+      reason: "unreachable-path",
+      count: unreachablePaths.length,
+      samplePaths: unreachablePaths.slice(0, 10),
+    });
+  }
+  if (unreadableLinks.length > 0) {
+    run.emit({
+      type: "not-shipped",
+      reason: "unreadable-link",
+      count: unreadableLinks.length,
+      samplePaths: unreadableLinks.slice(0, 10),
+    });
+  }
 }
 
 /** First up-to-`limit` members of an iterable, for bounded event payloads. */
@@ -2133,6 +2163,10 @@ function defaultConsoleLogger(event: SyncProgressEvent): void {
       console.warn(
         `  ! ${event.count} named path${event.count === 1 ? "" : "s"} could NOT be pushed — the file exists but is not reachable under the company folder (nothing was uploaded for ${event.count === 1 ? "it" : "them"}):`,
       );
+    } else if (event.reason === "unreadable-link") {
+      console.warn(
+        `  ! ${event.count} symbolic link${event.count === 1 ? "" : "s"} could NOT be read and was skipped without dereferencing its target:`,
+      );
     } else {
       console.warn(
         `  ! ${event.count} linked subtree${event.count === 1 ? "" : "s"} recorded but NOT uploaded — contents sync via their own repo, not the vault:`,
@@ -2166,22 +2200,21 @@ type CollectedEntry =
  * They turn two previously-SILENT outcomes into surfaced signals — without
  * changing WHAT gets uploaded (feedback_258e4a86 / feedback_a51cb63d):
  *
- *   - `onUnreachablePath`: a path the caller EXPLICITLY named (never an internal
- *     walk root — those are always the reachable company folder) that exists on
- *     disk but the resolver could not place under the company folder
- *     (`"outside-company"`), or could not resolve to an existing file under any
- *     base (`"missing"`). Pre-fix this was a bare `console.error` warn-skip that
- *     still let the push report "Pushed 0 file(s)" — a false success. The caller
- *     can now turn a non-empty set into a real error / nonzero exit.
+ *   - `onUnreachablePath`: a path that cannot be shipped. It is normally the
+ *     caller's explicit spelling (`"outside-company"` or `"missing"`), and is
+ *     the company-relative key for an unreadable link discovered during a
+ *     directory walk (`"unreadable-link"`). Pre-fix this was a bare
+ *     `console.error` warn-skip that still let the push report "Pushed 0 file(s)"
+ *     — a false success. The caller can now turn a non-empty set into a real
+ *     error / nonzero exit.
  *
- *     SPELLING CONTRACT: `namedPath` is ALWAYS the caller's ORIGINAL token,
+ *     SPELLING CONTRACT: resolver outcomes use the caller's ORIGINAL token,
  *     verbatim — never the resolved absolute path, and never normalized. A
  *     relative `knowledge/agents/x.md` is reported as `knowledge/agents/x.md`;
  *     an absolute path is reported absolute because that is what was passed.
- *     Echoing the caller's own spelling is what makes the error actionable
- *     ("the thing you typed did not ship"), and it keeps `unreachablePaths`
- *     comparable to the input array without a resolution step. Both call sites
- *     below pass the loop variable `p` for exactly this reason.
+ *     An unreadable link discovered during a recursive walk instead uses its
+ *     company-relative vault key, because it has no separate caller token.
+ *     This keeps UI output actionable without exposing host-specific paths.
  *   - `onLinkedSubtree`: a directory symlink recorded as a link but NOT
  *     descended because its target resolves OUTSIDE the company folder (e.g.
  *     `companies/{co}/knowledge` → `repos/private/knowledge-{co}/`). The link's
@@ -2189,7 +2222,7 @@ type CollectedEntry =
  *     created under such a link from vanishing from every push bucket silently.
  */
 interface CollectHooks {
-  onUnreachablePath?: (namedPath: string, reason: "missing" | "outside-company") => void;
+  onUnreachablePath?: (namedPath: string, reason: UnreachablePathReason) => void;
   onLinkedSubtree?: (rel: string) => void;
 }
 
@@ -2517,6 +2550,12 @@ function collectFiles(
       // whole branch). The filter is pure path lookup with no I/O,
       // so two calls are free.
       if (!filter(absolutePath, false) && !filter(absolutePath, true)) continue;
+      const target = readlinkOrNull(absolutePath);
+      if (target === null) {
+        console.error(`  Warning: ${p} is an unreadable symbolic link, skipping.`);
+        hooks.onUnreachablePath?.(p, "unreadable-link");
+        continue;
+      }
       // A directory symlink whose target lives outside the company folder is
       // recorded here but never descended — its contents ship via their own
       // repo, not the vault. Surface it so files created under such a link
@@ -2526,7 +2565,7 @@ function collectFiles(
         kind: "symlink",
         absolutePath,
         relativePath,
-        target: fs.readlinkSync(absolutePath),
+        target,
       });
       continue;
     }
@@ -2602,11 +2641,17 @@ function walkDir(
       // private/knowledge-{co}/), causing per-company knowledge repos
       // to be uploaded into every vault that links them. Recording
       // and not following preserves the link topology while avoiding
-      // that duplication. readlinkSync on a Dirent-known link cannot
-      // fail under normal conditions; let the throw propagate if it
-      // somehow does (race with rm, EPERM) — the operator needs to
-      // see it rather than us silently dropping the link again.
       const linkRelative = vaultKeyForLocalPath(syncRoot, absolutePath);
+      // On win32, a Dirent-known link is not sufficient proof that readlink
+      // will succeed (notably for some reparse points). Never fall through to
+      // normal file/directory handling here: doing so would dereference the
+      // link and duplicate its target under this vault key.
+      const target = readlinkOrNull(absolutePath);
+      if (target === null) {
+        console.error(`  Warning: ${linkRelative} is an unreadable symbolic link, skipping.`);
+        hooks.onUnreachablePath?.(linkRelative, "unreadable-link");
+        continue;
+      }
       // The link is recorded but its (external) target is not descended, so
       // any files under it are NOT uploaded. Report the subtree so a full
       // `sync now` no longer drops it from every bucket without a trace.
@@ -2615,7 +2660,7 @@ function walkDir(
         kind: "symlink",
         absolutePath,
         relativePath: linkRelative,
-        target: fs.readlinkSync(absolutePath),
+        target,
       });
       continue;
     }

package/src/cli/sync.test.ts

@@ -10,6 +10,13 @@ import { clearContextCache } from "../context.js";
 import type { VaultServiceConfig } from "../types.js";
 import { lockPathFor } from "../operation-lock.js";
 
+// Re-export node:fs as a mutable module so unreadable-link regressions can
+// inject a win32 EINVAL without needing a real Windows reparse point.
+vi.mock("fs", async (importOriginal) => {
+  const actual = await importOriginal<typeof import("fs")>();
+  return { ...actual };
+});
+
 // Mock s3 module at the top level
 vi.mock("../s3.js", async (importOriginal) => {
   const actual = await importOriginal<typeof import("../s3.js")>();
@@ -67,6 +74,12 @@ const mockConfig: VaultServiceConfig = {
   region: "us-east-1",
 };
 
+function errnoError(code: string): NodeJS.ErrnoException {
+  const err = new Error(`${code}: invalid argument, readlink`) as NodeJS.ErrnoException;
+  err.code = code;
+  return err;
+}
+
 const mockEntity = {
   uid: "cmp_01ABCDEF",
   slug: "acme",
@@ -383,6 +396,52 @@ describe("sync", () => {
     expect(journal.files["docs/handoff.md"]?.localDiverges).toBeFalsy();
   });
 
+  it("leaves a downloaded unreadable link unjournaled without emitting a fatal error", async () => {
+    const linkKey = "policies/downloaded-unreadable-link";
+    const linkPath = path.join(tmpDir, "companies", "acme", linkKey);
+    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) => {
+        fs.mkdirSync(path.dirname(localPath), { recursive: true });
+        fs.symlinkSync("missing-target.md", localPath);
+        return { metadata: {} };
+      },
+    );
+    const realReadlinkSync = fs.readlinkSync;
+    const readlinkSpy = vi
+      .spyOn(fs, "readlinkSync")
+      .mockImplementation(((candidate: fs.PathLike) => {
+        if (candidate === linkPath) throw errnoError("EINVAL");
+        return realReadlinkSync(candidate);
+      }) as typeof fs.readlinkSync);
+    const events: SyncProgressEvent[] = [];
+
+    try {
+      const result = await sync({
+        company: "acme",
+        vaultConfig: mockConfig,
+        hqRoot: tmpDir,
+        onEvent: (event) => events.push(event),
+      });
+
+      expect(result.filesDownloaded).toBe(0);
+      expect(result.filesSkipped).toBe(1);
+      expect(events).toContainEqual({
+        type: "not-shipped",
+        reason: "unreadable-link",
+        count: 1,
+        samplePaths: [linkKey],
+      });
+      expect(events.some((event) => event.type === "error")).toBe(false);
+      const journal = JSON.parse(fs.readFileSync(journalPath, "utf-8"));
+      expect(journal.files[linkKey]).toBeUndefined();
+    } finally {
+      readlinkSpy.mockRestore();
+    }
+  });
+
   it("emits a conflict event with path + resolution on hash mismatch", async () => {
     const companyDocs = path.join(tmpDir, "companies", "acme", "docs");
     fs.mkdirSync(companyDocs, { recursive: true });
@@ -505,6 +564,73 @@ describe("sync", () => {
     expect(journalAfter.files["docs/handoff.md"].remoteEtag).toBeTruthy();
   });
 
+  it("defers a conflict whose downloaded link target cannot be read", async () => {
+    const linkKey = "docs/handoff.md";
+    const localPath = path.join(tmpDir, "companies", "acme", linkKey);
+    fs.mkdirSync(path.dirname(localPath), { recursive: true });
+    fs.writeFileSync(localPath, "local version");
+    vi.mocked(s3Module.listRemoteFiles).mockResolvedValueOnce([
+      { key: linkKey, size: 0, lastModified: new Date(), etag: '"remote-link"' },
+    ]);
+    let mirrorPath = "";
+    vi.mocked(s3Module.downloadFile).mockImplementationOnce(
+      async (_ctx: unknown, _key: string, destination: string) => {
+        mirrorPath = destination;
+        fs.mkdirSync(path.dirname(destination), { recursive: true });
+        fs.symlinkSync("missing-target.md", destination);
+        return { metadata: {} };
+      },
+    );
+    fs.writeFileSync(
+      journalPath,
+      JSON.stringify({
+        version: "1",
+        lastSync: new Date().toISOString(),
+        files: {
+          [linkKey]: {
+            hash: "stale-hash",
+            size: 20,
+            syncedAt: new Date(Date.now() - 3600000).toISOString(),
+            direction: "down",
+          },
+        },
+      }),
+    );
+    const realReadlinkSync = fs.readlinkSync;
+    const readlinkSpy = vi
+      .spyOn(fs, "readlinkSync")
+      .mockImplementation(((candidate: fs.PathLike) => {
+        if (candidate === mirrorPath) throw errnoError("EINVAL");
+        return realReadlinkSync(candidate);
+      }) as typeof fs.readlinkSync);
+    const events: SyncProgressEvent[] = [];
+
+    try {
+      const result = await sync({
+        company: "acme",
+        onConflict: "keep",
+        vaultConfig: mockConfig,
+        hqRoot: tmpDir,
+        onEvent: (event) => events.push(event),
+      });
+
+      expect(result.conflicts).toBe(0);
+      expect(result.filesSkipped).toBeGreaterThanOrEqual(1);
+      expect(events).toContainEqual({
+        type: "not-shipped",
+        reason: "unreadable-link",
+        count: 1,
+        samplePaths: [linkKey],
+      });
+      expect(events.some((event) => event.type === "error")).toBe(false);
+      expect(fs.readFileSync(localPath, "utf-8")).toBe("local version");
+      const journal = JSON.parse(fs.readFileSync(journalPath, "utf-8"));
+      expect(journal.files[linkKey].hash).toBe("stale-hash");
+    } finally {
+      readlinkSpy.mockRestore();
+    }
+  });
+
   it("still writes a `.conflict-*` mirror when remote genuinely diverges from local", async () => {
     // Guard the other side of the convergence branch: when the probe bytes
     // differ from local, it remains a real conflict — counted, kept, and the
@@ -4131,6 +4257,47 @@ describe("sync", () => {
     expect(result.conflicts).toBe(0);
   });
 
+  it("defers an unreadable local symlink instead of aborting the pull plan", async () => {
+    const linkKey = "policies/unreadable-link";
+    const companyRoot = path.join(tmpDir, "companies", "acme");
+    const linkPath = path.join(companyRoot, linkKey);
+    fs.mkdirSync(path.dirname(linkPath), { recursive: true });
+    fs.symlinkSync("target.md", linkPath);
+    vi.mocked(s3Module.listRemoteFiles).mockResolvedValueOnce([
+      { key: linkKey, size: 0, lastModified: new Date(), etag: '"link-etag"' },
+    ]);
+
+    const realReadlinkSync = fs.readlinkSync;
+    const readlinkSpy = vi
+      .spyOn(fs, "readlinkSync")
+      .mockImplementation(((candidate: fs.PathLike) => {
+        if (candidate === linkPath) throw errnoError("EINVAL");
+        return realReadlinkSync(candidate);
+      }) as typeof fs.readlinkSync);
+
+    try {
+      const events: SyncProgressEvent[] = [];
+      const result = await sync({
+        company: "acme",
+        vaultConfig: mockConfig,
+        hqRoot: tmpDir,
+        onEvent: (event) => events.push(event),
+      });
+
+      expect(result.filesDownloaded).toBe(0);
+      expect(result.filesSkipped).toBe(1);
+      expect(s3Module.downloadFile).not.toHaveBeenCalled();
+      expect(events).toContainEqual({
+        type: "not-shipped",
+        reason: "unreadable-link",
+        count: 1,
+        samplePaths: [linkKey],
+      });
+    } finally {
+      readlinkSpy.mockRestore();
+    }
+  });
+
   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).

package/src/cli/sync.ts

@@ -13,6 +13,7 @@ import type {
   SyncJournal,
 } from "../types.js";
 import { VaultAuthError, VaultClient, type SyncMode } from "../vault-client.js";
+import { readlinkOrNull } from "../lib/readlink-safe.js";
 import {
   emitCloudTelemetry,
   type TelemetryClaims,
@@ -436,11 +437,11 @@ export type SyncProgressEvent =
     }
   | {
       /**
-       * Emitted at most ONCE per `reason` per `share()` push leg when local
-       * content the walk saw was deliberately NOT uploaded and would otherwise
-       * vanish from every push bucket without a trace (feedback_258e4a86 /
+       * Emitted when local content is deliberately not transferred and would
+       * otherwise vanish from sync output without a trace (feedback_258e4a86 /
        * feedback_a51cb63d — an hour lost because a "Pushed 0 file(s)" success
-       * named nothing that was skipped). `reason` distinguishes the cause:
+       * named nothing that was skipped). Push batches by reason; pull emits an
+       * unreadable link by its remote key. `reason` distinguishes the cause:
        *
        *   - `"unreachable-path"`: a path the caller EXPLICITLY named exists on
        *     disk but the resolver could not place it under the company folder,
@@ -450,12 +451,15 @@ export type SyncProgressEvent =
        *     the company folder was recorded as a link but its contents were not
        *     descended/uploaded. They sync via their own repo, not the vault;
        *     this is informational, not an error.
+       *   - `"unreadable-link"`: the OS identified a local symbolic link but
+       *     did not expose a readable target. The link is skipped rather than
+       *     dereferenced, and the company leg remains complete.
        *
        * `count` is the number of distinct paths for that reason; `samplePaths`
        * carries up to 10 for display. Not emitted when `count === 0`.
        */
       type: "not-shipped";
-      reason: "unreachable-path" | "linked-subtree";
+      reason: "unreachable-path" | "unreadable-link" | "linked-subtree";
       count: number;
       samplePaths: string[];
     };
@@ -1261,6 +1265,19 @@ async function executeConflictExecutor(
       counters.filesSkipped++;
       continue;
     }
+    if (item.action === "skip-unreadable-link") {
+      // An unreadable local link must stay non-fatal: the runner treats a
+      // generic error event as a failed company leg. Surface the exact remote
+      // key through the recoverable not-shipped channel instead.
+      counters.filesSkipped++;
+      run.emit({
+        type: "not-shipped",
+        reason: "unreadable-link",
+        count: 1,
+        samplePaths: [item.remoteFile.key],
+      });
+      continue;
+    }
     if (item.action === "skip-excluded-policy") {
       continue;
     }
@@ -1408,10 +1425,23 @@ async function executeConflictItem(
   try {
     const downloaded = await downloadFile(run.ctx, remoteFile.key, conflictAbs);
     remoteFetched = true;
-    const remoteHash = fs.lstatSync(conflictAbs).isSymbolicLink()
-      ? hashSymlinkTarget(fs.readlinkSync(conflictAbs))
-      : (downloaded.contentHash ?? hashFile(conflictAbs));
-    converged = remoteHash === item.localHash;
+    if (fs.lstatSync(conflictAbs).isSymbolicLink()) {
+      const target = readlinkOrNull(conflictAbs);
+      if (target === null) {
+        counters.filesSkipped++;
+        run.emit({
+          type: "not-shipped",
+          reason: "unreadable-link",
+          count: 1,
+          samplePaths: [remoteFile.key],
+        });
+        return null;
+      } else {
+        converged = hashSymlinkTarget(target) === item.localHash;
+      }
+    } else {
+      converged = (downloaded.contentHash ?? hashFile(conflictAbs)) === item.localHash;
+    }
   } catch (probeErr) {
     if (probeErr instanceof VaultAuthError) throw probeErr;
     run.emit({
@@ -1635,9 +1665,23 @@ async function downloadOne(
 
     const localLstat = fs.lstatSync(localPath);
     const isLocalSymlink = localLstat.isSymbolicLink();
-    const hash = isLocalSymlink
-      ? hashSymlinkTarget(fs.readlinkSync(localPath))
-      : (contentHash ?? hashFile(localPath));
+    let hash: string;
+    if (isLocalSymlink) {
+      const target = readlinkOrNull(localPath);
+      if (target === null) {
+        counters.filesSkipped++;
+        run.emit({
+          type: "not-shipped",
+          reason: "unreadable-link",
+          count: 1,
+          samplePaths: [remoteFile.key],
+        });
+        return;
+      }
+      hash = hashSymlinkTarget(target);
+    } else {
+      hash = contentHash ?? hashFile(localPath);
+    }
     const size = isLocalSymlink ? 0 : (contentSize ?? fs.statSync(localPath).size);
 
     updateEntry(
@@ -2166,6 +2210,11 @@ type PullPlanItem =
   | { action: "skip-personal-mode"; remoteFile: RemoteFile; localPath: string }
   | { action: "skip-unchanged"; remoteFile: RemoteFile; localPath: string }
   | { action: "skip-local-only"; remoteFile: RemoteFile; localPath: string }
+  // A local symlink was classified as a link but Windows (or a filesystem
+  // race) would not expose its target. This stays distinct from generic
+  // skip-local-only so the executor can report the exact path without making
+  // the whole company leg fail.
+  | { action: "skip-unreadable-link"; remoteFile: RemoteFile; localPath: string }
   // A stale personal-overlay symlink marker in the vault sitting at a key that
   // is ALSO a real, release-shipped core directory (e.g. an old
   // `core/knowledge/public/agent-browser` overlay marker after a release
@@ -2800,9 +2849,19 @@ function computePullPlan(
       ) {
         localHash = journalEntry.hash;
       } else {
-        localHash = isLocalSymlink
-          ? hashSymlinkTarget(fs.readlinkSync(localPath))
-          : hashFile(localPath);
+        if (isLocalSymlink) {
+          const target = readlinkOrNull(localPath);
+          if (target === null) {
+            // We cannot prove whether the local link diverged, so never
+            // overwrite or tombstone it from this plan. A later pass can retry
+            // once the OS exposes a readable target.
+            items.push({ action: "skip-unreadable-link", remoteFile, localPath });
+            continue;
+          }
+          localHash = hashSymlinkTarget(target);
+        } else {
+          localHash = hashFile(localPath);
+        }
       }
       const localChanged = !!journalEntry && journalEntry.hash !== localHash;
       plannedLocalSnapshot = {
@@ -3329,6 +3388,10 @@ function defaultConsoleLogger(event: SyncProgressEvent): void {
       console.warn(
         `  ! ${event.count} named path${event.count === 1 ? "" : "s"} could NOT be pushed — the file exists but is not reachable under the company folder (nothing was uploaded for ${event.count === 1 ? "it" : "them"}):`,
       );
+    } else if (event.reason === "unreadable-link") {
+      console.warn(
+        `  ! ${event.count} symbolic link${event.count === 1 ? "" : "s"} could NOT be read and was skipped without dereferencing its target:`,
+      );
     } else {
       console.warn(
         `  ! ${event.count} linked subtree${event.count === 1 ? "" : "s"} recorded but NOT uploaded — contents sync via their own repo, not the vault:`,

package/src/lib/readlink-safe.test.ts

@@ -0,0 +1,43 @@
+import { describe, expect, it } from "vitest";
+import { readlinkOrNull } from "./readlink-safe.js";
+
+function errnoError(code: string): NodeJS.ErrnoException {
+  const err = new Error(`${code}: scripted readlink failure`) as NodeJS.ErrnoException;
+  err.code = code;
+  return err;
+}
+
+describe("readlinkOrNull", () => {
+  it("uses the filesystem reader by default", () => {
+    expect(readlinkOrNull(`/hq-cloud-missing-link-${process.pid}`)).toBeNull();
+  });
+
+  it("returns the target string verbatim when readlink succeeds", () => {
+    expect(readlinkOrNull("/test/link", () => "../target with spaces")).toBe(
+      "../target with spaces",
+    );
+  });
+
+  it.each(["EINVAL", "ENOENT", "EPERM"])("returns null for %s", (code) => {
+    expect(readlinkOrNull("/test/link", () => {
+      throw errnoError(code);
+    })).toBeNull();
+  });
+
+  it("rethrows non-filesystem failures", () => {
+    const defect = new Error("unexpected test defect");
+
+    expect(() => readlinkOrNull("/test/link", () => {
+      throw defect;
+    })).toThrow(defect);
+  });
+
+  it("rethrows code-bearing programming errors", () => {
+    const defect = new TypeError("path must be a string") as TypeError & { code: string };
+    defect.code = "ERR_INVALID_ARG_TYPE";
+
+    expect(() => readlinkOrNull("/test/link", () => {
+      throw defect;
+    })).toThrow(defect);
+  });
+});

package/src/lib/readlink-safe.ts

@@ -0,0 +1,29 @@
+import * as fs from "fs";
+
+/**
+ * Read a link target without turning an expected filesystem race or an
+ * unsupported link shape into a caller-wide failure.
+ *
+ * A `null` result is deliberately distinct from an empty target string: it
+ * means the caller must preserve the link boundary and choose its conservative
+ * skip/defer path. Non-filesystem exceptions still propagate so programming
+ * errors cannot be mistaken for an unreadable link.
+ */
+export function readlinkOrNull(
+  linkPath: string,
+  readlink: (path: string) => string = (path) => fs.readlinkSync(path, "utf8"),
+): string | null {
+  try {
+    return readlink(linkPath);
+  } catch (err: unknown) {
+    const code =
+      err && typeof err === "object" && "code" in err
+        ? (err as { code?: unknown }).code
+        : undefined;
+    // Node system errors use POSIX-style errno names such as EINVAL and
+    // ENOENT. Runtime/programming errors use ERR_* codes; those must remain
+    // loud rather than being misclassified as an unreadable link.
+    if (typeof code === "string" && /^E[A-Z0-9]+$/.test(code)) return null;
+    throw err;
+  }
+}