@indigoai-us/hq-cloud 6.14.37 → 6.14.39

package/dist/lib/readlink-safe.d.ts

@@ -0,0 +1,11 @@
+/**
+ * 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 declare function readlinkOrNull(linkPath: string, readlink?: (path: string) => string): string | null;
+//# sourceMappingURL=readlink-safe.d.ts.map

package/dist/lib/readlink-safe.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"readlink-safe.d.ts","sourceRoot":"","sources":["../../src/lib/readlink-safe.ts"],"names":[],"mappings":"AAEA;;;;;;;;GAQG;AACH,wBAAgB,cAAc,CAC5B,QAAQ,EAAE,MAAM,EAChB,QAAQ,GAAE,CAAC,IAAI,EAAE,MAAM,KAAK,MAAgD,GAC3E,MAAM,GAAG,IAAI,CAcf"}

package/dist/lib/readlink-safe.js

@@ -0,0 +1,27 @@
+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, readlink = (path) => fs.readlinkSync(path, "utf8")) {
+    try {
+        return readlink(linkPath);
+    }
+    catch (err) {
+        const code = err && typeof err === "object" && "code" in err
+            ? err.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;
+    }
+}
+//# sourceMappingURL=readlink-safe.js.map

package/dist/lib/readlink-safe.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"readlink-safe.js","sourceRoot":"","sources":["../../src/lib/readlink-safe.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,IAAI,CAAC;AAEzB;;;;;;;;GAQG;AACH,MAAM,UAAU,cAAc,CAC5B,QAAgB,EAChB,WAAqC,CAAC,IAAI,EAAE,EAAE,CAAC,EAAE,CAAC,YAAY,CAAC,IAAI,EAAE,MAAM,CAAC;IAE5E,IAAI,CAAC;QACH,OAAO,QAAQ,CAAC,QAAQ,CAAC,CAAC;IAC5B,CAAC;IAAC,OAAO,GAAY,EAAE,CAAC;QACtB,MAAM,IAAI,GACR,GAAG,IAAI,OAAO,GAAG,KAAK,QAAQ,IAAI,MAAM,IAAI,GAAG;YAC7C,CAAC,CAAE,GAA0B,CAAC,IAAI;YAClC,CAAC,CAAC,SAAS,CAAC;QAChB,oEAAoE;QACpE,wEAAwE;QACxE,8DAA8D;QAC9D,IAAI,OAAO,IAAI,KAAK,QAAQ,IAAI,cAAc,CAAC,IAAI,CAAC,IAAI,CAAC;YAAE,OAAO,IAAI,CAAC;QACvE,MAAM,GAAG,CAAC;IACZ,CAAC;AACH,CAAC"}

package/dist/lib/readlink-safe.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=readlink-safe.test.d.ts.map

package/dist/lib/readlink-safe.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"readlink-safe.test.d.ts","sourceRoot":"","sources":["../../src/lib/readlink-safe.test.ts"],"names":[],"mappings":""}

package/dist/lib/readlink-safe.test.js

@@ -0,0 +1,34 @@
+import { describe, expect, it } from "vitest";
+import { readlinkOrNull } from "./readlink-safe.js";
+function errnoError(code) {
+    const err = new Error(`${code}: scripted readlink failure`);
+    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");
+        defect.code = "ERR_INVALID_ARG_TYPE";
+        expect(() => readlinkOrNull("/test/link", () => {
+            throw defect;
+        })).toThrow(defect);
+    });
+});
+//# sourceMappingURL=readlink-safe.test.js.map

package/dist/lib/readlink-safe.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"readlink-safe.test.js","sourceRoot":"","sources":["../../src/lib/readlink-safe.test.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,QAAQ,CAAC;AAC9C,OAAO,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AAEpD,SAAS,UAAU,CAAC,IAAY;IAC9B,MAAM,GAAG,GAAG,IAAI,KAAK,CAAC,GAAG,IAAI,6BAA6B,CAA0B,CAAC;IACrF,GAAG,CAAC,IAAI,GAAG,IAAI,CAAC;IAChB,OAAO,GAAG,CAAC;AACb,CAAC;AAED,QAAQ,CAAC,gBAAgB,EAAE,GAAG,EAAE;IAC9B,EAAE,CAAC,uCAAuC,EAAE,GAAG,EAAE;QAC/C,MAAM,CAAC,cAAc,CAAC,0BAA0B,OAAO,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC,QAAQ,EAAE,CAAC;IAC7E,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,2DAA2D,EAAE,GAAG,EAAE;QACnE,MAAM,CAAC,cAAc,CAAC,YAAY,EAAE,GAAG,EAAE,CAAC,uBAAuB,CAAC,CAAC,CAAC,IAAI,CACtE,uBAAuB,CACxB,CAAC;IACJ,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,IAAI,CAAC,CAAC,QAAQ,EAAE,QAAQ,EAAE,OAAO,CAAC,CAAC,CAAC,qBAAqB,EAAE,CAAC,IAAI,EAAE,EAAE;QACrE,MAAM,CAAC,cAAc,CAAC,YAAY,EAAE,GAAG,EAAE;YACvC,MAAM,UAAU,CAAC,IAAI,CAAC,CAAC;QACzB,CAAC,CAAC,CAAC,CAAC,QAAQ,EAAE,CAAC;IACjB,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,kCAAkC,EAAE,GAAG,EAAE;QAC1C,MAAM,MAAM,GAAG,IAAI,KAAK,CAAC,wBAAwB,CAAC,CAAC;QAEnD,MAAM,CAAC,GAAG,EAAE,CAAC,cAAc,CAAC,YAAY,EAAE,GAAG,EAAE;YAC7C,MAAM,MAAM,CAAC;QACf,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;IACtB,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,0CAA0C,EAAE,GAAG,EAAE;QAClD,MAAM,MAAM,GAAG,IAAI,SAAS,CAAC,uBAAuB,CAAiC,CAAC;QACtF,MAAM,CAAC,IAAI,GAAG,sBAAsB,CAAC;QAErC,MAAM,CAAC,GAAG,EAAE,CAAC,cAAc,CAAC,YAAY,EAAE,GAAG,EAAE;YAC7C,MAAM,MAAM,CAAC;QACf,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;IACtB,CAAC,CAAC,CAAC;AACL,CAAC,CAAC,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@indigoai-us/hq-cloud",
-  "version": "6.14.37",
+  "version": "6.14.39",
   "description": "HQ by Indigo cloud sync engine — bidirectional S3 sync for mobile access",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/src/bin/sync-runner.test.ts

@@ -2027,6 +2027,58 @@ describe("per-company fanout", () => {
 // ---------------------------------------------------------------------------
 
 describe("all-complete aggregate", () => {
+  it("reports every unreadable-link fallback by path without turning the company leg into PARTIAL_SYNC_EXIT", async () => {
+    const unreadablePaths = [
+      "policies/scope-invalid-tombstone",
+      "docs/conflict-convergence-probe",
+      "skills/downloaded-link-hash",
+    ];
+    const deps = makeDeps({
+      createVaultClient: () =>
+        makeVaultStub({
+          memberships: [{ companyUid: "cmp_a" }],
+          entityGet: (uid: string) =>
+            Promise.resolve({
+              uid,
+              type: "company",
+              slug: "acme",
+              bucketName: "hq-vault-acme-test",
+              status: "active",
+            } as unknown as EntityInfo),
+        }),
+      share: vi.fn(async (options: ShareOptions) => {
+        for (const path of unreadablePaths) {
+          options.onEvent?.({
+            type: "not-shipped",
+            reason: "unreadable-link",
+            count: 1,
+            samplePaths: [path],
+          });
+        }
+        return defaultShareResult();
+      }),
+    });
+
+    const code = await runRunner(["--companies", "--direction", "push"], deps);
+
+    for (const path of unreadablePaths) {
+      expect(deps.stdout.events()).toContainEqual({
+        type: "not-shipped",
+        company: "acme",
+        reason: "unreadable-link",
+        count: 1,
+        samplePaths: [path],
+      });
+    }
+    const all = deps.stdout.events().find(
+      (event): event is Extract<RunnerEvent, { type: "all-complete" }> =>
+        event.type === "all-complete",
+    );
+    expect(all?.errors).toEqual([]);
+    expect(all?.partial).toBe(false);
+    expect(code).toBe(0);
+  });
+
   it("emits all-complete when telemetry never resolves", async () => {
     const deps = makeDeps({
       createVaultClient: () =>

package/src/cli/reindex.ts

@@ -22,6 +22,7 @@ import { spawnSync } from "child_process";
 import * as fs from "fs";
 import * as os from "os";
 import * as path from "path";
+import { readlinkOrNull } from "../lib/readlink-safe.js";
 import {
   acquireOperationLock,
   OperationLockedError,
@@ -126,15 +127,6 @@ function lstatOrNull(p: string): fs.Stats | null {
   }
 }
 
-/** readlink without throwing (null when not a symlink / missing). */
-function readlinkOrNull(p: string): string | null {
-  try {
-    return fs.readlinkSync(p);
-  } catch {
-    return null;
-  }
-}
-
 /**
  * Entries of `dir` matching a bash `dir/*` glob: dotfiles excluded (no
  * dotglob), sorted lexicographically (bash glob order). Missing dir → [].

package/src/cli/share.test.ts

@@ -46,6 +46,7 @@ vi.mock("readline", () => ({
 
 import * as readline from "readline";
 import { share, isForbiddenCompanyVaultKey, UnreachablePushPathsError, _testing as shareTesting } from "./share.js";
+import type { SyncProgressEvent } from "./sync.js";
 import { deleteRemoteFile, downloadFile, headRemoteFile, uploadFile, uploadSymlink } from "../s3.js";
 import type { EntityContext } from "../types.js";
 import { VaultAuthError } from "../vault-client.js";
@@ -56,6 +57,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;
+}
+
 /**
  * Build a pre-vended EntityContext as if a caller (e.g. AppBar) had already
  * called `/sts/vend-child` and is passing the result into share() via the
@@ -4364,6 +4371,113 @@ describe("share", () => {
       );
     });
 
+    it("skips and reports a top-level link whose win32 readlink raises EINVAL", () => {
+      const companyRoot = path.join(tmpDir, "companies", "acme");
+      const targetDir = path.join(tmpDir, "outside", "target");
+      fs.mkdirSync(targetDir, { recursive: true });
+      fs.writeFileSync(path.join(targetDir, "must-not-upload.md"), "private target bytes");
+      const unreadableLink = path.join(companyRoot, "knowledge");
+      fs.mkdirSync(companyRoot, { recursive: true });
+      fs.symlinkSync(targetDir, unreadableLink, "dir");
+
+      const realReadlinkSync = fs.readlinkSync;
+      const readlinkSpy = vi
+        .spyOn(fs, "readlinkSync")
+        .mockImplementation(((linkPath: fs.PathLike) => {
+          if (linkPath === unreadableLink) throw errnoError("EINVAL");
+          return realReadlinkSync(linkPath);
+        }) as typeof fs.readlinkSync);
+      const warnings = vi.spyOn(console, "error").mockImplementation(() => {});
+      const unreachable: Array<[string, string]> = [];
+
+      try {
+        const collected = shareTesting.collectFiles(
+          [unreadableLink],
+          tmpDir,
+          companyRoot,
+          () => true,
+          {
+            onUnreachablePath: (namedPath, reason) => unreachable.push([namedPath, reason]),
+          },
+        );
+
+        expect(collected).toEqual([]);
+        expect(unreachable).toEqual([[unreadableLink, "unreadable-link"]]);
+      } finally {
+        warnings.mockRestore();
+        readlinkSpy.mockRestore();
+      }
+    });
+
+    it("skips and names a nested unreadable link without descending into its target", async () => {
+      const companyRoot = path.join(tmpDir, "companies", "acme");
+      const policiesDir = path.join(companyRoot, "policies");
+      const targetDir = path.join(tmpDir, "outside", "target");
+      fs.mkdirSync(policiesDir, { recursive: true });
+      fs.mkdirSync(targetDir, { recursive: true });
+      fs.writeFileSync(path.join(policiesDir, "safe.md"), "safe bytes");
+      fs.writeFileSync(path.join(targetDir, "must-not-upload.md"), "private target bytes");
+      const unreadableLink = path.join(policiesDir, "unreadable-link");
+      fs.symlinkSync(targetDir, unreadableLink, "dir");
+
+      const realReadlinkSync = fs.readlinkSync;
+      const readlinkSpy = vi
+        .spyOn(fs, "readlinkSync")
+        .mockImplementation(((linkPath: fs.PathLike) => {
+          if (linkPath === unreadableLink) throw errnoError("EINVAL");
+          return realReadlinkSync(linkPath);
+        }) as typeof fs.readlinkSync);
+      const warnings = vi.spyOn(console, "error").mockImplementation(() => {});
+      const events: Array<{
+        type?: string;
+        reason?: string;
+        samplePaths?: string[];
+      }> = [];
+
+      try {
+        const result = await share({
+          paths: [companyRoot],
+          company: "acme",
+          vaultConfig: mockConfig,
+          hqRoot: tmpDir,
+          onEvent: (event) => events.push(event),
+        });
+
+        expect(result.filesUploaded).toBe(1);
+        expect(result.unreachablePaths).toEqual(["policies/unreadable-link"]);
+        expect(uploadFile).toHaveBeenCalledWith(
+          expect.anything(),
+          path.join(policiesDir, "safe.md"),
+          "policies/safe.md",
+          undefined,
+          expect.anything(),
+        );
+        expect(uploadFile).not.toHaveBeenCalledWith(
+          expect.anything(),
+          path.join(unreadableLink, "must-not-upload.md"),
+          "policies/unreadable-link/must-not-upload.md",
+          undefined,
+          expect.anything(),
+        );
+        expect(uploadSymlink).not.toHaveBeenCalledWith(
+          expect.anything(),
+          expect.anything(),
+          "policies/unreadable-link",
+          undefined,
+          expect.anything(),
+        );
+        expect(events).toContainEqual({
+          type: "not-shipped",
+          reason: "unreadable-link",
+          count: 1,
+          samplePaths: ["policies/unreadable-link"],
+        });
+      } finally {
+        warnings.mockRestore();
+        readlinkSpy.mockRestore();
+      }
+    });
+
     it("accepts a symlink inside the company folder even when its target lives outside", async () => {
       // Codex P2 follow-up: pre-fix, isWithin canonicalized the link
       // via realpathSync, so a directory symlink whose target lived
@@ -6528,6 +6642,72 @@ describe("scope-invalid key hardening on push (doubled companies/ tree — incid
     expect(journal.files["companies/acme/knowledge/poison.md"]).toBeUndefined();
   });
 
+  it("defers an unreadable scope-invalid symlink tombstone without a fatal error", async () => {
+    const companyRoot = path.join(tmpDir, "companies", "acme");
+    const linkKey = "companies/acme/knowledge/unreadable-link";
+    const linkPath = path.join(companyRoot, ...linkKey.split("/"));
+    const targetDir = path.join(tmpDir, "outside", "target");
+    fs.mkdirSync(path.dirname(linkPath), { recursive: true });
+    fs.mkdirSync(targetDir, { recursive: true });
+    fs.symlinkSync(targetDir, linkPath, "dir");
+    const journalPath = path.join(stateDir, "sync-journal.acme.json");
+    fs.writeFileSync(
+      journalPath,
+      JSON.stringify({
+        version: "1",
+        lastSync: new Date().toISOString(),
+        files: {
+          [linkKey]: {
+            hash: "recorded-link-hash",
+            size: 0,
+            syncedAt: new Date().toISOString(),
+            direction: "up",
+            remoteEtag: "poison-etag",
+          },
+        },
+      }),
+    );
+    const realReadlinkSync = fs.readlinkSync;
+    let linkReadCount = 0;
+    const readlinkSpy = vi
+      .spyOn(fs, "readlinkSync")
+      .mockImplementation(((candidate: fs.PathLike) => {
+        if (candidate === linkPath && ++linkReadCount === 2) {
+          throw errnoError("EINVAL");
+        }
+        return realReadlinkSync(candidate);
+      }) as typeof fs.readlinkSync);
+    const events: SyncProgressEvent[] = [];
+
+    try {
+      const result = await share({
+        paths: [companyRoot],
+        company: "acme",
+        vaultConfig: mockConfig,
+        hqRoot: tmpDir,
+        skipUnchanged: true,
+        propagateDeletes: true,
+        propagateDeletePolicy: "currency-gated",
+        onEvent: (event) => events.push(event),
+      });
+
+      expect(linkReadCount).toBe(2);
+      expect(result.filesTombstoned).toBe(0);
+      expect(fs.lstatSync(linkPath).isSymbolicLink()).toBe(true);
+      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]).toBeDefined();
+    } finally {
+      readlinkSpy.mockRestore();
+    }
+  });
+
   it("personal-mode push still uploads companies/{slug}/ keys (local non-cloud companies are legitimate)", async () => {
     const localCo = path.join(tmpDir, "companies", "localco");
     fs.mkdirSync(localCo, { recursive: true });

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;
     }