From c2f5fc661291216174c5dfb7357f201344290d18 Mon Sep 17 00:00:00 2001
From: N0zoM1z0 <161784452+N0zoM1z0@users.noreply.github.com>
Date: Tue, 6 Oct 2026 19:00:55 +0800
Subject: [PATCH] docs(hopper): clarify realpath fallback scope

---
 src/hopper/HopperTargetLease.ts | 12 ++++++------
 1 file changed, 6 insertions(+), 6 deletions(-)

diff --git a/src/hopper/HopperTargetLease.ts b/src/hopper/HopperTargetLease.ts
index bd9459621..2744a4fca 100644
--- a/src/hopper/HopperTargetLease.ts
+++ b/src/hopper/HopperTargetLease.ts
@@ -35,12 +35,12 @@ export const acquireHopperTargetLease = async (input: {
 }): Promise<HopperTargetLeaseAcquisition> => {
   const directory = input.directory ?? leaseDirectory;
   await ensureLeaseDirectory(directory);
-  // The canonical path only derives the lease key; it never authorizes access.
-  // `realpath` is expected to fail when the target or a path component is
-  // missing (ENOENT, ENOTDIR), unreadable (EACCES), or a symlink loop (ELOOP).
-  // The lexical `resolve` fallback still yields a deterministic key, so the
-  // only cost is that symlinked spellings of such a path may take separate
-  // leases.
+  // The normal Hopper path supplies a readable canonical target from
+  // `parseBinaryTarget`. This extra `realpath` also canonicalizes direct
+  // callers and may fail if the filesystem changes before lease acquisition.
+  // Any failure falls back to a lexical absolute path because this value only
+  // keys coordination and never authorizes access. The fallback discards the
+  // filesystem error and can let aliases of the same target take separate leases.
   const targetPath = await realpath(input.targetPath).catch(() =>
     resolve(input.targetPath),
   );