@j0hanz/filesystem-mcp 2.8.0 → 2.9.0

package/dist/core/path.js

@@ -1,4 +1,4 @@
-import { lstat, readlink, realpath, stat } from 'node:fs/promises';
+import { lstat, readdir, readlink, realpath, stat } from 'node:fs/promises';
 import { homedir } from 'node:os';
 import { basename, dirname, isAbsolute, join, relative, resolve } from 'node:path';
 import { runExclusive, withAbort } from "./concurrency.js";
@@ -6,9 +6,15 @@ import { cli } from "./config.js";
 import { classifyCauseChain, ErrorCode, FsError, isFsError, isNotFoundErrno, isSkippableErrno, rethrowIfAborted, SKIPPABLE_FS_CODES, } from "./errors.js";
 import { Logger } from "./observability.js";
 import { findProjectRoot, isUnsafeCwdPath, resolveConfiguredDirs } from "./path-discovery.js";
-import { getReservedDeviceNameForPath, IS_WINDOWS, isPathInsideDirectory, isPathWithinDirectories, isSamePath, isWindowsDriveRelativePath, normalizeAllowedDirectory, normalizePath, parseTrueEnvFlag, toPosixPath, } from "./path-utils.js";
+import { escapeNonAscii, expandHome, getReservedDeviceNameForPath, IS_WINDOWS, isPathInsideDirectory, isPathWithinDirectories, isSamePath, isUnresolvableDrivePath, isWindowsDrivePath, isWindowsDriveRelativePath, mayHaveEquivalentSpelling, normalizeAllowedDirectory, normalizePath, toPosixRelative, unicodeMatchKey, } from "./path-utils.js";
 import { SensitiveMatcher } from "./sensitive.js";
-import { ROOTS_TIMEOUT_MS } from "./util.js";
+import { parseTrueEnvFlag, ROOTS_TIMEOUT_MS } from "./util.js";
+// Allowed-directory assembly and the PathGuard that enforces it. The
+// sensitive-file denylist lives in sensitive.ts, and the character-level
+// primitives (IS_WINDOWS, isAlpha, isSlash, toPosixPath) live in
+// path-utils.ts.
+/** Links followed, or respelling rounds run, before a path is refused (Linux ELOOP's 40). */
+const MAX_SYMLINK_HOPS = 40;
 /**
  * The real path of `normalizedPath`, or the one it would have if it does not
  * exist yet: realpath of its nearest existing ancestor plus the missing suffix.
@@ -53,10 +59,6 @@ async function partitionRootsWithin(roots, bounds, signal) {
     }
     return { kept, dropped };
 }
-/** `path.relative` with forward slashes, so displayed paths match across platforms. */
-export function toPosixRelative(from, to) {
-    return toPosixPath(relative(from, to));
-}
 // ---------------------------------------------------------------------------
 // Resolver pipeline
 // ---------------------------------------------------------------------------
@@ -80,24 +82,31 @@ async function resolveRealPath(normalized, signal) {
         throw error;
     }
 }
+async function resolveRootSpellings(dirs, signal) {
+    const roots = normalizeAllowedDirectories(dirs);
+    const reals = await Promise.all(roots.map((dir) => resolveRealPath(dir, signal)));
+    return roots.map((root, i) => {
+        const real = reals[i];
+        return { root, spellings: real && !isSamePath(real, root) ? [root, real] : [root] };
+    });
+}
 export async function resolveAllowedDirectoriesState(dirs, signal) {
-    const primary = normalizeAllowedDirectories(dirs);
-    const reals = await Promise.all(primary.map((dir) => resolveRealPath(dir, signal)));
-    return [
-        ...new Set(primary.flatMap((dir, i) => {
-            const real = reals[i];
-            return real && !isSamePath(real, dir) ? [dir, real] : [dir];
-        })),
-    ];
+    const entries = await resolveRootSpellings(dirs, signal);
+    return [...new Set(entries.flatMap((entry) => entry.spellings))];
 }
 /**
  * TOCTOU note: validation returns a plain string and the fs operation is a
  * later syscall, so a symlink swapped in between could redirect it. Reads and
- * appends in core/fs.ts and core/read.ts open with O_NOFOLLOW (final component)
- * and re-check the fd's real path on Linux (ancestor swap). Residual: write
- * paths that resolve a parent by name (`rename`, `mkdir`, `rm`, `cp`) would
- * need openat()-relative-to-dirfd, which Node lacks; non-Linux skips the fd
- * re-check.
+ * appends in core/fs.ts open with O_NOFOLLOW (final component) and re-check the
+ * fd's real path on Linux (ancestor swap). stat's directory count opens and
+ * re-checks the directory, and reads entries through that descriptor, only on
+ * Linux with procfs; elsewhere it reads the directory by path, so the swap
+ * window stays there, like the read path's non-Linux residual. Residuals: the
+ * directory walker behind list and the search tools (core/glob.ts) still
+ * resolves each entry by path, as the count does for a symlinked entry;
+ * write paths that resolve a parent by name
+ * (`rename`, `mkdir`, `rm`, `cp`) would need openat()-relative-to-dirfd, which
+ * Node lacks; non-Linux skips the fd re-check.
  */
 export class PathGuard {
     allowedDirectoriesState;
@@ -119,6 +128,18 @@ export class PathGuard {
      * field — so the recompute can rebuild from it without re-filtering.
      */
     grantedDirectories = [];
+    /**
+     * The grants a user approved for a path a tool asked about, as opposed to
+     * the workspace roots a client declared. Relative paths never resolve
+     * against these: one approval must not change what a relative path names,
+     * neither in a later round of the same call nor in a later call.
+     */
+    accessGrants = [];
+    /**
+     * Where relative paths resolve: the roots minus `accessGrants`, each with
+     * its spellings, plus every spelling flattened for containment.
+     */
+    relativeBases;
     rootBoundaries = [];
     options;
     constructor(options) {
@@ -127,10 +148,23 @@ export class PathGuard {
     /**
      * `expanded` is the containment set (each root plus its realpath alias);
      * `roots` is what a caller choosing "the root" sees, one entry per root.
+     * `relativeBases` lists the roots relative paths resolve against, with
+     * their spellings; without it, every root, each spelled only as given.
      */
-    initialize(expanded, roots = expanded) {
+    initialize(expanded, roots = expanded, relativeBases) {
         this.allowedDirectoriesState = normalizeAllowedDirectories(expanded);
         this.rootsState = normalizeAllowedDirectories(roots);
+        const entries = (relativeBases ?? this.rootsState.map((root) => ({ root, spellings: [root] }))).map((entry) => ({
+            root: normalizeAllowedDirectory(entry.root),
+            spellings: normalizeAllowedDirectories(entry.spellings),
+        }));
+        this.relativeBases = {
+            entries,
+            roots: entries.map((entry) => entry.root),
+            expanded: relativeBases
+                ? normalizeAllowedDirectories(entries.flatMap((entry) => entry.spellings))
+                : this.allowedDirectoriesState,
+        };
     }
     isInitialized() {
         return this.allowedDirectoriesState !== undefined;
@@ -170,24 +204,18 @@ export class PathGuard {
         return this.sensitive.isSensitive(filePath);
     }
     /**
-     * True when `entryPath` is both within the guard's allowed directories and
-     * not sensitive, checking the requested AND resolved paths. EVERY entry is
-     * realpath-resolved via validateExistingPathDetailed: a symlinked ancestor
-     * directory pointing outside the sandbox would otherwise pass the lexical
-     * containment check (fs.glob follows symlinks and yields external entries as
-     * non-symlink dirents). validateExistingPathDetailed re-checks containment on
-     * the real path against this.allowedDirectoriesState (the guard's full
-     * allowed set — a superset of the single-root `bounds` callers pass) and
-     * re-checks sensitivity on the resolved target, throwing ACCESS_DENIED for
-     * escapes/sensitive, which the catch below turns into a filter. Skippable
-     * errno/fs errors return false (the entry is filtered, not fatal). The
-     * accepted TOCTOU window is documented at the class docstring above.
+     * True when a walked entry is inside the allowed directories and not sensitive,
+     * on both its requested and resolved paths. Every entry is realpath-resolved: a
+     * symlinked ancestor pointing outside the sandbox would otherwise pass the
+     * lexical check (fs.glob follows symlinks and yields external entries as
+     * non-symlink dirents). Escapes and sensitive targets throw ACCESS_DENIED and
+     * skippable errors filter the entry; anything else is fatal. The accepted
+     * TOCTOU window is documented on this class.
      */
     async isEntryAccessible(entryPath) {
-        const isSensitive = (requestedPath, resolvedPath) => this.isSensitive(requestedPath) || this.isSensitive(resolvedPath);
         try {
-            const validated = await this.validateExistingPathDetailed(entryPath);
-            return !isSensitive(validated.requestedPath, validated.resolvedPath);
+            const { requestedPath, resolvedPath } = await this.validateExistingPathDetailed(entryPath);
+            return !this.isSensitive(requestedPath) && !this.isSensitive(resolvedPath);
         }
         catch (error) {
             if (isFsError(error)) {
@@ -265,7 +293,16 @@ export class PathGuard {
             if (!requested) {
                 continue;
             }
+            // Validation refuses it for its shape whatever is granted, so asking the
+            // user to grant the working directory it resolves under is pointless.
+            if (isUnresolvableDrivePath(requested) ||
+                (IS_WINDOWS && getReservedDeviceNameForPath(requested) !== undefined)) {
+                continue;
+            }
             const normalized = normalizePath(requested);
+            if (this.isSensitive(requested) || this.isSensitive(normalized)) {
+                continue;
+            }
             if (isPathWithinDirectories(normalized, allowedDirs)) {
                 continue;
             }
@@ -277,7 +314,7 @@ export class PathGuard {
             if (await this.isUnsafeGrantTarget(targetDir)) {
                 continue;
             }
-            if (grantDirs.includes(targetDir)) {
+            if (grantDirs.some((dir) => isSamePath(dir, targetDir))) {
                 continue;
             }
             if (!(await this.isWithinBoundary(targetDir))) {
@@ -297,8 +334,12 @@ export class PathGuard {
      * pre-checks passed. The caller leaves a refused path to fail with
      * ACCESS_DENIED during the operation. Idempotent: re-granting an already
      * allowed directory is a no-op via the dedup in `initialize`.
+     *
+     * `kind` says where the grant came from: `access` for a path the user
+     * approved when a tool asked, `workspace` for a root the client declared.
+     * Only a workspace root becomes a place relative paths resolve.
      */
-    async applyGrant(targetDir) {
+    async applyGrant(targetDir, kind = 'access') {
         // Defense-in-depth: even a tampered/accepted grant cannot extend roots into
         // an unsafe path. The precheckAccess guard already refuses to offer these;
         // this catches a grant that arrived by another route — the legacy stdio
@@ -314,22 +355,32 @@ export class PathGuard {
         // nothing in this body may take the lock again.
         return runExclusive(this, async () => {
             const previous = this.grantedDirectories;
-            this.grantedDirectories = [...previous, normalizePath(targetDir)];
+            const previousAccess = this.accessGrants;
+            const dir = normalizePath(targetDir);
+            this.grantedDirectories = [...previous, dir];
+            this.accessGrants =
+                kind === 'access'
+                    ? [...previousAccess, dir]
+                    : previousAccess.filter((grant) => !isSamePath(grant, dir));
+            const rollBack = () => {
+                this.grantedDirectories = previous;
+                this.accessGrants = previousAccess;
+            };
             try {
                 await this.recomputeAllowedDirectories();
             }
             catch (error) {
                 // A failed recompute leaves the guard with its previous, consistent view.
-                this.grantedDirectories = previous;
+                rollBack();
                 throw error;
             }
             // Verify rather than assume: a boundary that no longer covers this
             // directory would drop it in the recompute above, and reporting success
             // for a grant that did not land is exactly the failure this replaces.
-            if (isPathWithinDirectories(normalizePath(targetDir), this.getAllowedDirectories())) {
+            if (isPathWithinDirectories(dir, this.getAllowedDirectories())) {
                 return true;
             }
-            this.grantedDirectories = previous;
+            rollBack();
             await this.recomputeAllowedDirectories();
             return false;
         });
@@ -349,6 +400,10 @@ export class PathGuard {
         if (!this.allowedDirectoriesState) {
             throw new FsError(ErrorCode.UNKNOWN, 'PathGuard not initialized. Call initialize() first.', requestedPath);
         }
+        // Before the drive-relative check, whose advice (`use C:\path`) is wrong here.
+        if (!IS_WINDOWS && isWindowsDrivePath(requestedPath)) {
+            throw new FsError(ErrorCode.INVALID_INPUT, `Windows-style path received on a POSIX host (${process.platform}). Use a POSIX path, such as one under an allowed root.`, requestedPath, undefined, 'Run list_roots to see the allowed directories.');
+        }
         if (isWindowsDriveRelativePath(requestedPath)) {
             throw new FsError(ErrorCode.INVALID_INPUT, 'Drive-relative paths are not allowed. Use C:\\path or C:/path instead of C:path.', requestedPath);
         }
@@ -405,12 +460,29 @@ export class PathGuard {
     }
     async validateExistingPathDetailed(requestedPath) {
         const { normalizedRequested, allowedDirs, accessDeniedHint } = this.validateAccess(requestedPath);
+        let spelled = normalizedRequested;
         let realPath;
         try {
-            realPath = await realpath(normalizedRequested);
+            realPath = await realpath(spelled);
         }
         catch (error) {
-            realPath = await this.handleRealpathError(error, normalizedRequested, allowedDirs, accessDeniedHint, requestedPath);
+            // Not on disk as typed; it may be under another Unicode spelling (#101).
+            const respelled = isNotFoundErrno(error)
+                ? await this.respellMissing(spelled, allowedDirs, accessDeniedHint, requestedPath)
+                : undefined;
+            if (respelled === undefined) {
+                realPath = await this.handleRealpathError(error, spelled, allowedDirs, accessDeniedHint, requestedPath);
+            }
+            else {
+                this.assertNotSensitiveFile(respelled, requestedPath);
+                spelled = respelled;
+                try {
+                    realPath = await realpath(spelled);
+                }
+                catch (retryError) {
+                    realPath = await this.handleRealpathError(retryError, spelled, allowedDirs, accessDeniedHint, requestedPath);
+                }
+            }
         }
         const normalizedReal = normalizePath(realPath);
         if (!isPathWithinDirectories(normalizedReal, allowedDirs)) {
@@ -421,9 +493,9 @@ export class PathGuard {
         // sees the requested/normalized path, not the symlink target.
         this.assertNotSensitiveFile(normalizedReal, requestedPath);
         return {
-            requestedPath: normalizedRequested,
+            requestedPath: spelled,
             resolvedPath: normalizedReal,
-            isSymlink: !isSamePath(normalizedRequested, normalizedReal),
+            isSymlink: !isSamePath(spelled, normalizedReal),
         };
     }
     async validateExistingDirectory(requestedPath) {
@@ -457,6 +529,134 @@ export class PathGuard {
         }
         return root;
     }
+    /**
+     * Where the relative paths a caller sent should point, keyed by the spelling
+     * sent; a path that keeps its meaning is absent. A relative path resolves
+     * against the working directory, as it always has, while that lands inside
+     * a root. When it does not — a desktop host starts the server outside the
+     * project, and an HTTP client never shares its working directory — it
+     * resolves against the roots: the one root, or with several, the one it
+     * exists under. Searches print paths relative to the root (`resultPaths`),
+     * so this is what lets one tool's output feed the next.
+     *
+     * "Roots" here are the configured ones and those a client declared, never an
+     * access grant (see `accessGrants`). Absolute, `~` and drive paths keep their
+     * meaning, as does every path when there is no such root; validation judges
+     * them as before. A Windows drive path on POSIX is left for validation to
+     * refuse: joined to a root, `C:\x` would be an absolute path that passes. A
+     * relative path that exists under several roots, or under none of several,
+     * is refused rather than guessed.
+     */
+    async resolveRelativePaths(paths) {
+        const resolved = new Map();
+        const bases = this.relativeBases;
+        if (!bases || bases.roots.length === 0)
+            return resolved;
+        for (const requested of new Set(paths)) {
+            if (requested.trim().length === 0 ||
+                isUnresolvableDrivePath(requested) ||
+                isAbsolute(expandHome(requested)) ||
+                isPathWithinDirectories(normalizePath(requested), bases.expanded)) {
+                continue;
+            }
+            resolved.set(requested, await this.resolveAgainstRoots(requested, bases.roots));
+        }
+        return resolved;
+    }
+    async resolveAgainstRoots(requested, roots) {
+        const candidates = roots.map((root) => join(root, requested));
+        const [first] = candidates;
+        if (first === undefined || candidates.length === 1)
+            return first ?? requested;
+        // Each candidate is probed through validation itself, so the probe learns
+        // nothing validation would not tell the caller: a denylisted name is
+        // refused before the filesystem is touched, and a path through a symlink
+        // out of the roots is refused whether or not its target exists.
+        const existing = [];
+        let refused;
+        for (const candidate of candidates) {
+            try {
+                await this.validateExistingPath(candidate);
+                existing.push(candidate);
+            }
+            catch (error) {
+                if (isFsError(error) && error.code === ErrorCode.NOT_FOUND)
+                    continue;
+                refused ??= candidate;
+            }
+        }
+        const [only] = existing;
+        if (only !== undefined && existing.length === 1)
+            return only;
+        // Validation then refuses it again, with its own reason.
+        if (existing.length === 0 && refused !== undefined)
+            return refused;
+        throw new FsError(ErrorCode.INVALID_INPUT, existing.length === 0
+            ? `Relative path exists under none of the ${String(roots.length)} roots, so it names no one file. Pass an absolute path under one of: ${roots.join(', ')}.`
+            : `Relative path exists under more than one root: ${existing.join(', ')}. Pass the absolute path you mean.`, requested);
+    }
+    /**
+     * How a tool prints the paths a walk of `walkedDir` found, so the caller can
+     * pass each one straight back: relative to the root holding `walkedDir`
+     * when `resolveRelativePaths` maps that spelling back to the same path,
+     * absolute otherwise. A scoped search of `src` prints `src/a.ts`, not
+     * `a.ts`, which would name `<root>/a.ts`. `root` is the root as configured,
+     * as `list_roots` shows it, even when the walk went through its realpath.
+     *
+     * The absolute fallback covers a working directory in a subfolder of a root
+     * (relative paths resolve there), a directory under an access grant only
+     * (relative paths never resolve there), several roots with the working
+     * directory outside them (a name two roots share would read back as
+     * ambiguous, and which names are shared can change between the print and
+     * the read), and a name that would not read back as given: `~`, blank, or a
+     * POSIX name holding a backslash or starting with a drive (`C:`).
+     */
+    resultPaths(walkedDir) {
+        const walked = normalizePath(walkedDir);
+        const bases = this.relativeBases;
+        let found;
+        for (const entry of bases?.entries ?? []) {
+            for (const spelling of entry.spellings) {
+                if (isPathInsideDirectory(spelling, walked) &&
+                    (found === undefined || spelling.length > found.spelling.length)) {
+                    found = { root: entry.root, spelling };
+                }
+            }
+        }
+        if (found === undefined || bases === undefined) {
+            return { root: walked, atRoot: false, show: (absolutePath) => absolutePath };
+        }
+        const { root, spelling } = found;
+        const allowed = bases.expanded;
+        const severalRoots = bases.roots.length > 1;
+        return {
+            root,
+            atRoot: isSamePath(spelling, walked),
+            show: (absolutePath) => {
+                // Windows separators become `/`, which every tool accepts there; on
+                // POSIX a backslash is part of a name and must stay one.
+                const rel = IS_WINDOWS
+                    ? toPosixRelative(spelling, absolutePath)
+                    : relative(spelling, absolutePath);
+                if (rel.trim().length === 0 ||
+                    rel === '..' ||
+                    rel.startsWith('../') ||
+                    isAbsolute(rel) ||
+                    isUnresolvableDrivePath(rel) ||
+                    expandHome(rel) !== rel ||
+                    !isSamePath(resolve(spelling, rel), absolutePath)) {
+                    return absolutePath;
+                }
+                // Mirrors resolveRelativePaths: a spelling that lands inside a root
+                // from the working directory resolves there, so it must land here.
+                const fromCwd = normalizePath(rel);
+                if (isPathWithinDirectories(fromCwd, allowed)) {
+                    return isSamePath(fromCwd, absolutePath) ? rel : absolutePath;
+                }
+                return severalRoots ? absolutePath : rel;
+            },
+        };
+    }
     isAllowedRoot(normalizedPath) {
         // isSamePath case-folds on case-insensitive filesystems (win + darwin),
         // matching the containment checks used everywhere else in the guard. The
@@ -478,6 +678,7 @@ export class PathGuard {
     async resolveNearestExistingAncestor(requestedPath, currentPath) {
         const missingSegments = [];
         let current = currentPath;
+        let hops = 0;
         for (;;) {
             try {
                 const realAncestor = normalizePath(await realpath(current));
@@ -490,17 +691,30 @@ export class PathGuard {
                 try {
                     const stats = await lstat(current);
                     if (stats.isSymbolicLink()) {
+                        if (++hops > MAX_SYMLINK_HOPS) {
+                            throw new FsError(ErrorCode.SYMLINK_NOT_ALLOWED, 'Too many symbolic links encountered', requestedPath);
+                        }
+                        const allowedDirs = this.getAllowedDirectories();
+                        const linkParent = normalizePath(await realpath(dirname(current)));
+                        if (!isPathWithinDirectories(linkParent, allowedDirs)) {
+                            this.throwAccessDenied(requestedPath);
+                        }
                         const target = await readlink(current);
-                        const resolvedTarget = isAbsolute(target) ? target : resolve(dirname(current), target);
+                        const resolvedTarget = isAbsolute(target) ? target : resolve(linkParent, target);
                         const normalizedTarget = normalizePath(resolvedTarget);
-                        const allowedDirs = this.getAllowedDirectories();
                         if (!isPathWithinDirectories(normalizedTarget, allowedDirs)) {
                             this.throwAccessDenied(requestedPath);
                         }
+                        current =
+                            missingSegments.length === 0
+                                ? normalizedTarget
+                                : normalizePath(join(normalizedTarget, ...missingSegments.reverse()));
+                        missingSegments.length = 0;
+                        continue;
                     }
                 }
                 catch (lstatErr) {
-                    if (isFsError(lstatErr) && lstatErr.code === ErrorCode.ACCESS_DENIED) {
+                    if (isFsError(lstatErr)) {
                         throw lstatErr;
                     }
                     // ENOENT is expected during ancestor walk — the entry simply doesn't exist.
@@ -518,12 +732,126 @@ export class PathGuard {
             }
         }
     }
+    /**
+     * `normalized` re-spelled with the on-disk names of the components that are
+     * missing as typed but present under another Unicode spelling (#101), or
+     * `undefined` when no component changed. Only names below a root are
+     * matched, never the root's own. Each directory is scanned only after its
+     * real path is checked to be inside the roots, and each matched entry is
+     * realpathed and checked again, so a link found this way cannot lead out
+     * (`resolveLast: false` leaves the last one unresolved, for delete). The
+     * first component with no match ends the walk; it and the rest stay as
+     * typed, so a write still creates them. The result is a spelling only:
+     * the caller runs its own containment and denylist checks on it.
+     */
+    async respellMissing(normalized, allowedDirs, accessDeniedHint, requestedPath, resolveLast = true) {
+        const root = this.allowedRootContaining(normalized);
+        if (root === undefined || !mayHaveEquivalentSpelling(normalized.slice(root.length))) {
+            return undefined;
+        }
+        const missing = [];
+        let ancestor = normalized;
+        let real;
+        for (;;) {
+            try {
+                real = normalizePath(await realpath(ancestor));
+                break;
+            }
+            catch (error) {
+                if (!isNotFoundErrno(error) || isSamePath(ancestor, root))
+                    return undefined;
+                missing.unshift(basename(ancestor));
+                ancestor = dirname(ancestor);
+            }
+        }
+        // An ancestor that resolves out of the roots is the caller's to refuse.
+        if (!isPathWithinDirectories(real, allowedDirs))
+            return undefined;
+        const spelled = [];
+        for (const [index, name] of missing.entries()) {
+            let onDisk = name;
+            if (mayHaveEquivalentSpelling(name)) {
+                // The scan must not reveal what the denylist hides: a name it covers
+                // under the resolved parent is refused as the exact spelling is, and
+                // a directory `list` would refuse is never read.
+                this.assertNotSensitiveFile(join(real, ...missing.slice(index)), requestedPath);
+                if (this.isSensitive(real))
+                    break;
+                onDisk = await this.findEquivalentEntry(real, name, requestedPath);
+            }
+            if (onDisk === undefined)
+                break;
+            spelled.push(onDisk);
+            if (!resolveLast && index === missing.length - 1)
+                break;
+            try {
+                real = normalizePath(await realpath(join(ancestor, ...spelled)));
+            }
+            catch {
+                // Missing as typed, or a dangling link: the caller's checks judge it.
+                break;
+            }
+            if (!isPathWithinDirectories(real, allowedDirs)) {
+                this.throwAccessDenied(requestedPath, accessDeniedHint);
+            }
+        }
+        if (spelled.every((name, index) => name === missing[index]))
+            return undefined;
+        return join(ancestor, ...spelled, ...missing.slice(spelled.length));
+    }
+    /**
+     * The entry of `realDir` that `name` names: `name` itself when it is
+     * there, else the one entry with the same `unicodeMatchKey`. Two or more
+     * such entries are refused, never chosen between. `undefined` when none
+     * matches or the directory cannot be read.
+     */
+    async findEquivalentEntry(realDir, name, requestedPath) {
+        let entries;
+        try {
+            entries = await readdir(realDir);
+        }
+        catch {
+            return undefined;
+        }
+        if (entries.includes(name))
+            return name;
+        const key = unicodeMatchKey(name);
+        const matches = entries.filter((entry) => unicodeMatchKey(entry) === key);
+        // A match the denylist covers is refused here, as a lone one would be by
+        // the caller, so the ambiguity error below never lists a hidden name.
+        for (const match of matches)
+            this.assertNotSensitiveFile(join(realDir, match), requestedPath);
+        if (matches.length > 1) {
+            throw new FsError(ErrorCode.INVALID_INPUT, `Ambiguous Unicode path component "${name}": ${String(matches.length)} entries in ${realDir} match it (${matches.map(escapeNonAscii).join(', ')}). Pass the exact name, using \\u escapes for the characters shown that way.`, requestedPath);
+        }
+        return matches[0];
+    }
     async validatePathForWrite(requestedPath) {
         const { normalizedRequested, allowedDirs, accessDeniedHint } = this.validateAccess(requestedPath);
-        const { realAncestor, resolvedTarget } = await this.resolveNearestExistingAncestor(requestedPath, normalizedRequested);
-        if (!isPathWithinDirectories(realAncestor, allowedDirs) ||
-            !isPathWithinDirectories(resolvedTarget, allowedDirs)) {
-            this.throwAccessDenied(requestedPath, accessDeniedHint);
+        let { realAncestor, resolvedTarget } = await this.resolveNearestExistingAncestor(requestedPath, normalizedRequested);
+        const assertInside = () => {
+            if (!isPathWithinDirectories(realAncestor, allowedDirs) ||
+                !isPathWithinDirectories(resolvedTarget, allowedDirs)) {
+                this.throwAccessDenied(requestedPath, accessDeniedHint);
+            }
+        };
+        assertInside();
+        // Part of it is not on disk as typed; it may be under another Unicode
+        // spelling (#101). A followed link may also name a missing target spelled
+        // differently on disk, and respelling a parent can expose such a link, so
+        // repeat until the resolution settles, re-running the checks each round.
+        let candidate = normalizedRequested;
+        for (let round = 0; realAncestor !== resolvedTarget && round < MAX_SYMLINK_HOPS; round++) {
+            const respelled = (await this.respellMissing(candidate, allowedDirs, accessDeniedHint, requestedPath)) ??
+                (isSamePath(resolvedTarget, candidate)
+                    ? undefined
+                    : await this.respellMissing(resolvedTarget, allowedDirs, accessDeniedHint, requestedPath));
+            if (respelled === undefined)
+                break;
+            this.assertNotSensitiveFile(respelled, requestedPath);
+            ({ realAncestor, resolvedTarget } = await this.resolveNearestExistingAncestor(requestedPath, respelled));
+            assertInside();
+            candidate = respelled;
         }
         // Re-check the resolved target: a symlink inside an allowed root may point
         // at a sensitive file. Writing through such a link must be blocked too.
@@ -541,7 +869,25 @@ export class PathGuard {
         if (this.isAllowedRoot(normalizedRequested)) {
             throw new FsError(ErrorCode.ACCESS_DENIED, 'Deleting a workspace root directory is not allowed', requestedPath);
         }
-        const parent = dirname(normalizedRequested);
+        // Probe the final component before the parent, so a target that is not on
+        // disk as typed can be re-spelled (#101) before either is checked.
+        let target = normalizedRequested;
+        let stats;
+        try {
+            stats = await lstat(target);
+        }
+        catch (error) {
+            // The link itself is deleted, so the last component stays unresolved.
+            const respelled = isNotFoundErrno(error)
+                ? await this.respellMissing(target, allowedDirs, accessDeniedHint, requestedPath, false)
+                : undefined;
+            if (respelled !== undefined) {
+                this.assertNotSensitiveFile(respelled, requestedPath);
+                target = respelled;
+                stats = await lstat(target).catch(() => undefined);
+            }
+        }
+        const parent = dirname(target);
         let realParent;
         try {
             realParent = await realpath(parent);
@@ -553,36 +899,38 @@ export class PathGuard {
         if (!isPathWithinDirectories(normalizedRealParent, allowedDirs)) {
             this.throwAccessDenied(requestedPath, accessDeniedHint);
         }
-        // Resolve the final component when it exists. For deletion, we ONLY
-        // block if the real target is outside the sandbox IF the target is
-        // NOT a symlink. Deleting a symlink is safe even if it points outside.
+        // A target that does not exist needs only the parent check above.
+        if (stats === undefined)
+            return target;
+        // For deletion, we ONLY block if the real target is outside the sandbox
+        // IF the target is NOT a symlink. Deleting a symlink is safe even if it
+        // points outside.
+        if (stats.isSymbolicLink()) {
+            // Symlink: check link sensitivity but don't resolve target.
+            // The parent check above ensures the link itself is in an allowed root.
+            // Spelled through the validated real parent, so every path to one link
+            // (an aliased parent, another Unicode spelling) names it the same way.
+            const link = join(normalizedRealParent, basename(target));
+            this.assertNotSensitiveFile(target, requestedPath);
+            this.assertNotSensitiveFile(link, requestedPath);
+            return link;
+        }
+        // Not a symlink: resolve to catch path escapes (e.g. /allowed/dir/../../etc)
+        // and block sensitive files. A probe failure (ENOENT and friends) falls
+        // back to the parent check, which is sufficient for a path that does not
+        // exist.
+        let realTarget;
         try {
-            const stats = await lstat(normalizedRequested);
-            if (stats.isSymbolicLink()) {
-                // Symlink: check link sensitivity but don't resolve target.
-                // The parent check above ensures the link itself is in an allowed root.
-                this.assertNotSensitiveFile(normalizedRequested, requestedPath);
-                return normalizedRequested;
-            }
-            // Not a symlink: resolve to catch path escapes (e.g. /allowed/dir/../../etc)
-            // and block sensitive files.
-            const realTarget = normalizePath(await realpath(normalizedRequested));
-            if (!isPathWithinDirectories(realTarget, allowedDirs)) {
-                this.throwAccessDenied(requestedPath, accessDeniedHint);
-            }
-            this.assertNotSensitiveFile(realTarget, requestedPath);
-            return realTarget;
+            realTarget = normalizePath(await realpath(target));
         }
-        catch (error) {
-            // A denial raised inside this block (out-of-root real target, or a
-            // sensitive file reached through a symlinked parent) must propagate.
-            // Only a probe failure — ENOENT and friends — falls through to the
-            // parent check, which is sufficient for a path that does not exist.
-            if (isFsError(error)) {
-                throw error;
-            }
+        catch {
+            return target;
+        }
+        if (!isPathWithinDirectories(realTarget, allowedDirs)) {
+            this.throwAccessDenied(requestedPath, accessDeniedHint);
         }
-        return normalizedRequested;
+        this.assertNotSensitiveFile(realTarget, requestedPath);
+        return realTarget;
     }
     async recomputeAllowedDirectories() {
         const cliAllowedDirs = normalizeAllowedDirectories(this.options?.cliAllowedDirs ?? []);
@@ -625,12 +973,17 @@ export class PathGuard {
                 .kept;
         }
         const combined = [...baseline, ...grantsToInclude];
-        const nextState = await resolveAllowedDirectoriesState(combined, signal);
+        const spellings = await resolveRootSpellings(combined, signal);
+        const nextState = [...new Set(spellings.flatMap((entry) => entry.spellings))];
+        // A configured root stays a base even when it was also granted.
+        const accessGrants = this.accessGrants;
+        const bases = spellings.filter((entry) => baseline.some((dir) => isSamePath(dir, entry.root)) ||
+            !accessGrants.some((grant) => isSamePath(grant, entry.root)));
         // Commit boundaries and the allowed set together, after every await has
         // resolved, so a rejecting recompute leaves the guard's previous,
         // consistent view intact.
         this.rootBoundaries = boundaries;
-        this.initialize(nextState, combined);
+        this.initialize(nextState, combined, bases);
     }
 }
 //# sourceMappingURL=path.js.map