From 6847bc947316e43ff0e0af99ab75752cfabe40dd Mon Sep 17 00:00:00 2001
From: Vinay Prasad <100485512+vinay121314@users.noreply.github.com>
Date: Tue, 6 Oct 2026 15:08:54 +0530
Subject: [PATCH] docs(hopper): document HopperTargetLease realpath fallback

Closes #642
---
 src/hopper/HopperTargetLease.ts | 6 ++++++
 1 file changed, 6 insertions(+)

diff --git a/src/hopper/HopperTargetLease.ts b/src/hopper/HopperTargetLease.ts
index 9203c7c77..bd9459621 100644
--- a/src/hopper/HopperTargetLease.ts
+++ b/src/hopper/HopperTargetLease.ts
@@ -35,6 +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.
   const targetPath = await realpath(input.targetPath).catch(() =>
     resolve(input.targetPath),
   );