@remcp/runtime 0.2.107 → 0.2.109

package/src/tools/files.mjs

@@ -3,7 +3,7 @@ import os from 'node:os';
 import { spawnSync } from 'node:child_process';
 import { createHash, randomUUID } from 'node:crypto';
 import { constants, createReadStream } from 'node:fs';
-import { access, chmod, chown, copyFile, cp, lstat, mkdir, mkdtemp, open, readFile, readdir, rename, rm, stat, unlink, writeFile } from 'node:fs/promises';
+import { access, chmod, chown, copyFile, cp, lstat, mkdir, mkdtemp, open, readFile, readdir, rename, rm, stat, unlink } from 'node:fs/promises';
 import { pipeline } from 'node:stream/promises';
 import { liveConfig, runtimeConfig } from '../config.mjs';
 import { documentKind, readDocxText, readPdfText } from '../documents.mjs';
@@ -12,7 +12,7 @@ import { describeFilesystemFailure } from '../permissions.mjs';
 import { capturePortalScreenshot, isWaylandSession } from '../screenshot-portal.mjs';
 import { applyHunks, parseUnifiedDiff } from '../patch.mjs';
 import { countEvent, recordEvent } from '../telemetry.mjs';
-import { clampInteger, decodeText, displayPath, fail, globToRegExp, image, looksBinary, multi, pageLines, resolveSafePath, splitLines, text } from '../util.mjs';
+import { clampInteger, decodeText, displayPath, fail, globToRegExp, image, isInsideRoot, looksBinary, multi, pageLines, resolveSafePath, splitLines, text } from '../util.mjs';
 
 const MAX_INLINE_FILE_BYTES = 20 * 1024 * 1024;
 // An image travels base64-encoded, which costs a third more bytes. The agent's stdio transport holds
@@ -49,24 +49,326 @@ const WRITE_CREATE_NOFOLLOW = constants.O_WRONLY | constants.O_CREAT | constants
 const WRITE_TRUNCATE_NOFOLLOW = constants.O_WRONLY | constants.O_CREAT | constants.O_TRUNC | NOFOLLOW | NONBLOCK;
 const DIRECTORY_READ_NOFOLLOW = constants.O_RDONLY | (constants.O_DIRECTORY || 0) | NOFOLLOW | NONBLOCK;
 
-async function openRegularFile(absolute, flags = READ_NOFOLLOW) {
+async function openDirectoryFromFilesystemRoot(absolute) {
+  const root = path.parse(absolute).root;
+  const parts = absolute.slice(root.length).split(path.sep).filter(Boolean);
+  const directories = [];
+  let current = root;
+  const closeDirectories = async () => {
+    for (const handle of directories.reverse()) await handle.close().catch(() => {});
+  };
+  try {
+    const rootHandle = await open(root, DIRECTORY_READ_NOFOLLOW);
+    directories.push(rootHandle);
+    current = `/proc/self/fd/${rootHandle.fd}`;
+    for (const part of parts) {
+      const candidate = path.join(current, part);
+      const next = await open(candidate, DIRECTORY_READ_NOFOLLOW);
+      try {
+        const info = await next.stat();
+        if (!info.isDirectory()) fail('Filesystem path component is not a directory');
+        directories.push(next);
+        current = `/proc/self/fd/${next.fd}`;
+      } catch (error) {
+        await next.close().catch(() => {});
+        throw error;
+      }
+    }
+    const handle = directories.pop();
+    return {
+      handle,
+      anchor: current,
+      close: async () => {
+        try { await handle.close(); }
+        finally { await closeDirectories(); }
+      },
+    };
+  } catch (error) {
+    await closeDirectories();
+    throw error;
+  }
+}
+
+const secureRootPromises = new Map();
+
+async function secureAllowedRoot(root) {
+  if (!secureRootPromises.has(root)) {
+    secureRootPromises.set(root, openDirectoryFromFilesystemRoot(root));
+  }
+  try {
+    return await secureRootPromises.get(root);
+  } catch (error) {
+    secureRootPromises.delete(root);
+    throw error;
+  }
+}
+
+async function cloneDirectory(directory) {
+  const handle = await open(`${directory.anchor}/.`, DIRECTORY_READ_NOFOLLOW);
+  return {
+    handle,
+    anchor: `/proc/self/fd/${handle.fd}`,
+    close: () => handle.close(),
+  };
+}
+
+async function openConfinedDirectoryPath(absolute, create) {
+  if (!runtimeConfig.allowedRoots.length || absolute.startsWith('/proc/')) return null;
+  const root = runtimeConfig.allowedRoots.find(candidate => isInsideRoot(absolute, candidate));
+  if (!root) return null;
+  const relative = path.relative(root, absolute);
+  if (relative.startsWith('..') || path.isAbsolute(relative)) return null;
+  const rootDirectory = await secureAllowedRoot(root);
+  const directories = [];
+  let current = rootDirectory.anchor;
+  const closeDirectories = async () => {
+    for (const handle of directories.reverse()) await handle.close().catch(() => {});
+  };
+  try {
+    for (const part of relative.split(path.sep).filter(Boolean)) {
+      const candidate = path.join(current, part);
+      if (create) {
+        await mkdir(candidate, { mode:0o700 }).catch(error => {
+          if (error?.code !== 'EEXIST') throw error;
+        });
+      }
+      const handle = await open(candidate, DIRECTORY_READ_NOFOLLOW);
+      const info = await handle.stat();
+      if (!info.isDirectory()) {
+        await handle.close().catch(() => {});
+        fail('Filesystem path component is not a directory');
+      }
+      directories.push(handle);
+      current = `/proc/self/fd/${handle.fd}`;
+    }
+    if (!directories.length) return cloneDirectory(rootDirectory);
+    const handle = directories.pop();
+    return {
+      handle,
+      anchor: current,
+      close: async () => {
+        try { await handle.close(); }
+        finally { await closeDirectories(); }
+      },
+    };
+  } catch (error) {
+    await closeDirectories();
+    throw error;
+  }
+}
+
+async function openDescriptorDirectoryPath(absolute, create) {
+  const match = absolute.match(/^(\/proc\/(?:self|\d+)\/fd\/\d+)(?:\/(.*))?$/);
+  if (!match) return null;
+  // The proc-fd entry itself is a symlink. Make it an intermediate component so
+  // O_NOFOLLOW protects the referenced directory entry rather than rejecting procfs.
+  const base = await open(`${match[1]}/.`, DIRECTORY_READ_NOFOLLOW);
+  const directories = [base];
+  let current = `/proc/self/fd/${base.fd}`;
+  const closeDirectories = async () => {
+    for (const handle of directories.reverse()) await handle.close().catch(() => {});
+  };
+  try {
+    for (const part of (match[2] || '').split(path.sep).filter(Boolean)) {
+      const candidate = path.join(current, part);
+      if (create) {
+        await mkdir(candidate, { mode:0o700 }).catch(error => {
+          if (error?.code !== 'EEXIST') throw error;
+        });
+      }
+      const handle = await open(candidate, DIRECTORY_READ_NOFOLLOW);
+      const info = await handle.stat();
+      if (!info.isDirectory()) {
+        await handle.close().catch(() => {});
+        fail('Filesystem path component is not a directory');
+      }
+      directories.push(handle);
+      current = `/proc/self/fd/${handle.fd}`;
+    }
+    const handle = directories.pop();
+    return {
+      handle,
+      anchor: current,
+      close: async () => {
+        try { await handle.close(); }
+        finally { await closeDirectories(); }
+      },
+    };
+  } catch (error) {
+    await closeDirectories();
+    throw error;
+  }
+}
+
+export async function openDirectoryPath(absolute, { create = false, allowOutside = false } = {}) {
+  const descriptorBound = process.platform === 'linux' && Boolean(constants.O_NOFOLLOW) && Boolean(constants.O_DIRECTORY);
+  if (!descriptorBound) {
+    if (create) await mkdir(absolute, { recursive:true, mode:0o700 });
+    const info = await lstat(absolute);
+    if (info.isSymbolicLink() || !info.isDirectory()) fail('Filesystem path component is not a safe directory');
+    const handle = {
+      stat: () => stat(absolute),
+      chmod: mode => chmod(absolute, mode),
+      close: async () => {},
+    };
+    return { handle, anchor:absolute, descriptorBound:false, close: handle.close };
+  }
+  const confinedPath = await openConfinedDirectoryPath(absolute, create);
+  if (confinedPath) return confinedPath;
+  const descriptorPath = await openDescriptorDirectoryPath(absolute, create);
+  if (descriptorPath) return descriptorPath;
+  if (runtimeConfig.allowedRoots.length && !allowOutside) fail('Path is outside the directories this device allows');
+  const root = path.parse(absolute).root;
+  const parts = absolute.slice(root.length).split(path.sep).filter(Boolean);
+  if (!parts.length) {
+    const handle = await open(root, DIRECTORY_READ_NOFOLLOW);
+    return { handle, anchor: `/proc/self/fd/${handle.fd}`, close: () => handle.close() };
+  }
+  const directories = [];
+  let current = root;
+  const closeDirectories = async () => {
+    for (const handle of directories.reverse()) await handle.close().catch(() => {});
+  };
+  try {
+    for (const part of parts) {
+      const candidate = path.join(current, part);
+      if (create) {
+        await mkdir(candidate, { mode:0o700 }).catch(error => {
+          if (error?.code !== 'EEXIST') throw error;
+        });
+      }
+      const handle = await open(candidate, DIRECTORY_READ_NOFOLLOW);
+      const info = await handle.stat();
+      if (!info.isDirectory()) {
+        await handle.close().catch(() => {});
+        fail('Filesystem path component is not a directory');
+      }
+      directories.push(handle);
+      current = `/proc/self/fd/${handle.fd}`;
+    }
+    const handle = directories.pop();
+    return {
+      handle,
+      anchor: current,
+      close: async () => {
+        try { await handle.close(); }
+        finally { await closeDirectories(); }
+      },
+    };
+  } catch (error) {
+    await closeDirectories();
+    throw error;
+  }
+}
+
+async function openEntryAtPath(absolute, flags) {
+  const descriptorFile = /^\/proc\/(?:self|\d+)\/fd\/\d+$/.test(absolute);
+  if (process.platform === 'linux' && constants.O_NOFOLLOW && constants.O_DIRECTORY && !descriptorFile) {
+    const parent = await openDirectoryPath(path.dirname(absolute));
+    try {
+      const handle = await open(path.join(parent.anchor, path.basename(absolute)), flags);
+      return {
+        handle,
+        close: async () => {
+          try { await handle.close(); }
+          finally { await parent.close().catch(() => {}); }
+        },
+      };
+    } catch (error) {
+      await parent.close().catch(() => {});
+      throw error;
+    }
+  }
   const handle = await open(absolute, flags);
+  return { handle, close: () => handle.close() };
+}
+
+async function openRegularFileAtPath(absolute, flags, label = absolute) {
+  const opened = await openEntryAtPath(absolute, flags);
   try {
-    const info = assertRegularFile(await handle.stat(), absolute);
-    return { handle, info };
+    const info = assertRegularFile(await opened.handle.stat(), label);
+    return { handle: opened.handle, info, close: opened.close };
   } catch (error) {
-    await handle.close().catch(() => {});
+    await opened.close().catch(() => {});
     throw error;
   }
 }
 
+export async function openRegularFile(absolute, flags = READ_NOFOLLOW) {
+  return openRegularFileAtPath(absolute, flags, absolute);
+}
+
+async function openWritableParent(absolute, options = {}) {
+  if (process.platform === 'linux' && constants.O_NOFOLLOW && constants.O_DIRECTORY) {
+    return openDirectoryPath(absolute, { create:true, ...options });
+  }
+  await mkdir(absolute, { recursive:true });
+  const info = await lstat(absolute);
+  if (info.isSymbolicLink() || !info.isDirectory()) fail('Filesystem path component is not a directory');
+  return { anchor:absolute, close:async() => {} };
+}
+
+async function writeResolvedFile(absolute, content, { append = false } = {}) {
+  const parent = await openWritableParent(path.dirname(absolute));
+  let handle;
+  try {
+    const flags = append
+      ? constants.O_WRONLY | constants.O_CREAT | (constants.O_APPEND || 0) | NOFOLLOW | NONBLOCK
+      : WRITE_TRUNCATE_NOFOLLOW;
+    handle = await open(path.join(parent.anchor, path.basename(absolute)), flags, 0o600);
+    await handle.writeFile(content);
+  } finally {
+    if (handle) await handle.close().catch(() => {});
+    await parent.close().catch(() => {});
+  }
+}
+
+async function withWritableParent(absolute, callback) {
+  const parent = await openWritableParent(path.dirname(absolute));
+  try {
+    return await callback(path.join(parent.anchor, path.basename(absolute)));
+  } finally {
+    await parent.close().catch(() => {});
+  }
+}
+
+async function openExistingParent(absolute) {
+  if (process.platform === 'linux' && constants.O_NOFOLLOW && constants.O_DIRECTORY) {
+    return openDirectoryPath(absolute);
+  }
+  const info = await lstat(absolute);
+  if (info.isSymbolicLink() || !info.isDirectory()) fail('Filesystem path component is not a directory');
+  return { anchor:absolute, close:async() => {} };
+}
+
+async function withExistingParent(absolute, callback) {
+  const parent = await openExistingParent(path.dirname(absolute));
+  try {
+    return await callback(path.join(parent.anchor, path.basename(absolute)));
+  } finally {
+    await parent.close().catch(() => {});
+  }
+}
+
+async function ensureDirectoryPath(absolute, options = {}) {
+  if (process.platform === 'linux' && constants.O_NOFOLLOW && constants.O_DIRECTORY) {
+    const directory = await openDirectoryPath(absolute, { create:true, ...options });
+    await directory.close();
+    return;
+  }
+  await mkdir(absolute, { recursive:true });
+  const info = await lstat(absolute);
+  if (info.isSymbolicLink() || !info.isDirectory()) fail('Filesystem path component is not a directory');
+}
+
 async function readRegularBuffer(absolute, maxBytes = Infinity) {
-  const { handle, info } = await openRegularFile(absolute);
+  const opened = await openRegularFile(absolute);
+  const { handle, info } = opened;
   try {
     if (info.size > maxBytes) fail(`File is too large to read inline (${info.size} bytes)`);
     return { info, buffer: await handle.readFile() };
   } finally {
-    await handle.close();
+    await opened.close();
   }
 }
 
@@ -90,29 +392,65 @@ async function collectTree(root, { maxFiles = 500, skip = [] } = {}) {
   const found = [];
   const denied = [];
   const skipName = name => skip.some(entry => (entry.endsWith('*') ? name.startsWith(entry.slice(0, -1)) : name === entry));
-  async function visit(target) {
-    if (found.length >= maxFiles) return;
-    const info = await lstat(target).catch(() => null);
-    // A symlink is skipped on purpose (it can point outside the allowed roots); that is not a denial
-    // and must not be reported as one.
-    if (!info || info.isSymbolicLink()) return;
-    if (info.isFile()) { found.push(target); return; }
-    if (!info.isDirectory()) return;
+  const visitDirectory = async (directory, logicalBase) => {
     let entries;
     try {
-      entries = await readdir(target, { withFileTypes: true });
+      entries = await readdir(directory.anchor, { withFileTypes: true });
     } catch {
-      // Reporting the skip matters: silently dropping a directory made a partial walk look complete.
-      denied.push(target);
+      denied.push(logicalBase);
       return;
     }
     for (const entry of entries) {
       if (found.length >= maxFiles) return;
       if (entry.isSymbolicLink() || skipName(entry.name)) continue;
-      await visit(path.join(target, entry.name));
+      const childLogical = path.join(logicalBase, entry.name);
+      const childAnchor = path.join(directory.anchor, entry.name);
+      if (entry.isDirectory()) {
+        let child;
+        try {
+          child = await openDirectoryPath(childAnchor);
+          const info = await child.handle.stat();
+          if (!info.isDirectory()) fail('Filesystem path component is not a directory');
+          await visitDirectory(child, childLogical);
+        } catch {
+          denied.push(childLogical);
+        } finally {
+          if (child) await child.close().catch(() => {});
+        }
+      } else if (entry.isFile()) {
+        let opened;
+        try {
+          opened = await openEntryAtPath(childAnchor, READ_NOFOLLOW_NONBLOCK);
+          const info = await opened.handle.stat();
+          if (info.isFile()) found.push(childLogical);
+        } catch {
+          denied.push(childLogical);
+        } finally {
+          if (opened) await opened.close().catch(() => {});
+        }
+      }
+      if (found.length >= maxFiles) return;
     }
+  };
+  let directory;
+  try {
+    directory = await openDirectoryPath(root);
+    await visitDirectory(directory, root);
+  } catch {
+    let opened;
+    try {
+      opened = await openEntryAtPath(root, READ_NOFOLLOW_NONBLOCK);
+      const info = await opened.handle.stat();
+      if (info.isFile()) found.push(root);
+      else denied.push(root);
+    } catch {
+      denied.push(root);
+    } finally {
+      if (opened) await opened.close().catch(() => {});
+    }
+  } finally {
+    if (directory) await directory.close().catch(() => {});
   }
-  await visit(root);
   return { files: found, denied };
 }
 
@@ -229,37 +567,64 @@ export async function hashFileTool(args) {
   }
   const { handle, info } = opened;
   const algorithm = String(args.algorithm || 'sha256').toLowerCase();
-  if (!['sha256', 'sha1', 'md5'].includes(algorithm)) { await handle.close(); fail('algorithm must be sha256, sha1, or md5'); }
+  if (!['sha256', 'sha1', 'md5'].includes(algorithm)) { await opened.close(); fail('algorithm must be sha256, sha1, or md5'); }
   const hash = createHash(algorithm);
   try {
     await pipeline(createReadStream(absolute, { fd: handle.fd, autoClose: false }), hash);
     return text(`${algorithm} ${hash.digest('hex')}  ${displayPath(absolute)} (${info.size} bytes)`);
   } finally {
-    await handle.close();
+    await opened.close();
   }
 }
 
-async function listEntry(base, depth, maxDepth, prefix, pattern) {
+async function openListEntry(base, name) {
+  const opened = await openEntryAtPath(path.join(base, name), READ_NOFOLLOW_NONBLOCK);
+  try {
+    return { handle: opened.handle, info: await opened.handle.stat(), close: opened.close };
+  } catch (error) {
+    await opened.close().catch(() => {});
+    throw error;
+  }
+}
+
+async function listEntry(directory, depth, maxDepth, prefix, pattern, displayBase) {
   let entries;
   try {
-    entries = await readdir(base, { withFileTypes: true });
+    entries = await readdir(directory.anchor, { withFileTypes: true });
   } catch (error) {
-    // One unreadable subdirectory must not abort the whole listing.
-    return [`${prefix}[DENIED] ${path.basename(base)} (${error instanceof Error ? error.code || error.message : 'unreadable'})`];
+    return [`${prefix}[DENIED] ${path.basename(displayBase)} (${error instanceof Error ? error.code || error.message : 'unreadable'})`];
   }
   entries.sort((a, b) => Number(b.isDirectory()) - Number(a.isDirectory()) || a.name.localeCompare(b.name));
   const rows = [];
   for (const entry of entries) {
-    const child = path.join(base, entry.name);
+    const childDisplay = path.join(displayBase, entry.name);
     if (entry.isDirectory()) {
       rows.push(`${prefix}[DIR] ${entry.name}`);
-      if (depth < maxDepth) rows.push(...await listEntry(child, depth + 1, maxDepth, `${prefix}  `.replace(/ {2}$/, '') + '  ', pattern));
+      if (depth >= maxDepth) continue;
+      let child;
+      try {
+        child = await openDirectoryPath(path.join(directory.anchor, entry.name));
+        const childInfo = await child.handle.stat();
+        if (!childInfo.isDirectory()) fail('Filesystem path component is not a directory');
+        rows.push(...await listEntry(child, depth + 1, maxDepth, `${prefix}  `.replace(/ {2}$/, '') + '  ', pattern, childDisplay));
+      } catch (error) {
+        rows.push(`${prefix}  [DENIED] ${entry.name} (${error instanceof Error ? error.code || error.message : 'unreadable'})`);
+      } finally {
+        if (child) await child.close().catch(() => {});
+      }
     } else if (entry.isSymbolicLink()) {
       rows.push(`${prefix}[LINK] ${entry.name}`);
     } else {
       if (pattern && !pattern.test(entry.name)) continue;
-      const info = await stat(child).catch(() => null);
-      rows.push(`${prefix}[FILE] ${entry.name}${info ? ` (${info.size} bytes)` : ''}`);
+      let opened;
+      try {
+        opened = await openListEntry(directory.anchor, entry.name);
+        rows.push(`${prefix}[${opened.info.isFile() ? 'FILE' : 'SPECIAL'}] ${entry.name}${opened.info.isFile() ? ` (${opened.info.size} bytes)` : ''}`);
+      } catch (error) {
+        rows.push(`${prefix}[DENIED] ${entry.name} (${error instanceof Error ? error.code || error.message : 'unreadable'})`);
+      } finally {
+        if (opened) await opened.close().catch(() => {});
+      }
     }
   }
   return rows;
@@ -267,39 +632,85 @@ async function listEntry(base, depth, maxDepth, prefix, pattern) {
 
 export async function listDirectoryTool(args) {
   const absolute = await resolveSafePath(args.path);
-  const info = await stat(absolute).catch(() => fail(`Path not found: ${displayPath(absolute)}`));
-  if (!info.isDirectory()) fail(`${displayPath(absolute)} is not a directory`);
   const depth = clampInteger(args.depth, 1, 1, 5);
   const pattern = typeof args.pattern === 'string' && args.pattern.trim() ? globToRegExp(args.pattern.trim()) : null;
-  const rows = await listEntry(absolute, 1, depth, '', pattern);
-  return text(`${displayPath(absolute)}${pattern ? ` · matching ${args.pattern}` : ''}\n${rows.join('\n') || '(empty)'}`);
+  let directory;
+  try {
+    directory = await openDirectoryPath(absolute);
+    const info = await directory.handle.stat();
+    if (!info.isDirectory()) fail(`${displayPath(absolute)} is not a directory`);
+    const rows = await listEntry(directory, 1, depth, '', pattern, absolute);
+    return text(`${displayPath(absolute)}${pattern ? ` · matching ${args.pattern}` : ''}\n${rows.join('\n') || '(empty)'}`);
+  } catch (error) {
+    if (error?.code === 'ENOENT' || error?.code === 'ENOTDIR') fail(`Path not found: ${displayPath(absolute)}`);
+    throw error;
+  } finally {
+    if (directory) await directory.close().catch(() => {});
+  }
+}
+
+async function openPathForInfo(absolute) {
+  let directory;
+  try {
+    directory = await openDirectoryPath(absolute);
+    return { info: await directory.handle.stat(), close: directory.close };
+  } catch (directoryError) {
+    const canTryFile = directoryError?.code === 'ENOTDIR'
+      || directoryError?.code === 'EISDIR'
+      || (!directoryError?.code && /not a directory/i.test(directoryError?.message || ''));
+    if (!canTryFile) throw directoryError;
+  }
+  const opened = await openEntryAtPath(absolute, READ_NOFOLLOW_NONBLOCK);
+  try {
+    return { info: await opened.handle.stat(), close: opened.close };
+  } catch (error) {
+    await opened.close().catch(() => {});
+    throw error;
+  }
+}
+
+async function getPathInfo(absolute) {
+  const opened = await openPathForInfo(absolute);
+  try { return opened.info; }
+  finally { await opened.close().catch(() => {}); }
 }
 
 export async function getFileInfoTool(args) {
   const absolute = await resolveSafePath(args.path);
-  const info = await stat(absolute).catch(() => fail(`Path not found: ${displayPath(absolute)}`));
-  const payload = {
-    path: displayPath(absolute),
-    type: info.isDirectory() ? 'directory' : info.isSymbolicLink() ? 'symlink' : 'file',
-    size: info.size,
-    createdAt: info.birthtime.toISOString(),
-    modifiedAt: info.mtime.toISOString(),
-    permissions: `0${(info.mode & 0o777).toString(8)}`,
-  };
-  if (info.isFile() && info.size <= MAX_INLINE_FILE_BYTES) {
-    const opened = await readRegularBuffer(absolute, MAX_INLINE_FILE_BYTES).catch(() => null);
-    if (opened) {
-      const decoded = decodeText(opened.buffer);
-      if (decoded.encoding !== 'utf8') payload.encoding = decoded.encoding;
-      if (decoded.encoding !== 'utf8' || !looksBinary(opened.buffer)) {
-        const lines = splitLines(decoded.text);
-        payload.lineCount = lines.length;
-        payload.lastLine = Math.max(0, lines.length - 1);
-        payload.eol = detectEol(decoded.text) === '\r\n' ? 'CRLF' : 'LF';
+  let opened;
+  try {
+    opened = await openPathForInfo(absolute);
+  } catch (error) {
+    if (error?.code === 'ENOENT' || error?.code === 'ENOTDIR') fail(`Path not found: ${displayPath(absolute)}`);
+    throw error;
+  }
+  const { info } = opened;
+  try {
+    const payload = {
+      path: displayPath(absolute),
+      type: info.isDirectory() ? 'directory' : info.isSymbolicLink() ? 'symlink' : info.isFile() ? 'file' : 'special',
+      size: info.size,
+      createdAt: info.birthtime.toISOString(),
+      modifiedAt: info.mtime.toISOString(),
+      permissions: `0${(info.mode & 0o777).toString(8)}`,
+    };
+    if (info.isFile() && info.size <= MAX_INLINE_FILE_BYTES) {
+      const regular = await readRegularBuffer(absolute, MAX_INLINE_FILE_BYTES).catch(() => null);
+      if (regular) {
+        const decoded = decodeText(regular.buffer);
+        if (decoded.encoding !== 'utf8') payload.encoding = decoded.encoding;
+        if (decoded.encoding !== 'utf8' || !looksBinary(regular.buffer)) {
+          const lines = splitLines(decoded.text);
+          payload.lineCount = lines.length;
+          payload.lastLine = Math.max(0, lines.length - 1);
+          payload.eol = detectEol(decoded.text) === '\r\n' ? 'CRLF' : 'LF';
+        }
       }
     }
+    return text(JSON.stringify(payload, null, 2));
+  } finally {
+    await opened.close().catch(() => {});
   }
-  return text(JSON.stringify(payload, null, 2));
 }
 
 function assertWritableSize(content) {
@@ -331,8 +742,7 @@ export async function writeFileTool(args) {
       fail(`Appending ${bytes} bytes would grow ${displayPath(absolute)} to ${existingSize + bytes} bytes, above the ${runtimeConfig.maxWriteBytes}-byte write limit for this device`);
     }
   }
-  await mkdir(path.dirname(absolute), { recursive: true });
-  await writeFile(absolute, content, mode === 'append' ? { encoding: 'utf8', flag: 'a' } : 'utf8');
+  await writeResolvedFile(absolute, content, { append: mode === 'append' });
   countEvent('bytesWritten', bytes);
   return text(`${mode === 'append' ? 'Appended' : 'Wrote'} ${bytes} bytes to ${displayPath(absolute)}.`);
 }
@@ -367,7 +777,7 @@ export async function readBinaryTool(args) {
     });
     return text(payload);
   } finally {
-    await handle.close();
+    await opened.close();
   }
 }
 
@@ -387,8 +797,7 @@ export async function writeBinaryTool(args) {
     recordEvent('write_denied', { reason: 'size_limit' });
     fail(`Decoded content is ${buffer.length} bytes, above the ${runtimeConfig.maxWriteBytes}-byte write limit for this device`);
   }
-  await mkdir(path.dirname(absolute), { recursive: true });
-  await writeFile(absolute, buffer, mode === 'append' ? { flag: 'a' } : undefined);
+  await writeResolvedFile(absolute, buffer, { append: mode === 'append' });
   countEvent('bytesWritten', buffer.length);
   return text(`${mode === 'append' ? 'Appended' : 'Wrote'} ${buffer.length} bytes to ${displayPath(absolute)}.`);
 }
@@ -435,7 +844,7 @@ export async function editBlockTool(args) {
   if (occurrences === expected) {
     const updated = content.split(oldString).join(newString);
     assertWritableSize(updated);
-    if (!dryRun) await writeFile(absolute, updated, 'utf8');
+    if (!dryRun) await writeResolvedFile(absolute, updated);
     return text(present(updated, `Replaced ${occurrences} occurrence(s)`));
   }
   if (occurrences > 0) {
@@ -457,7 +866,7 @@ export async function editBlockTool(args) {
   // file to LF and turned a one-line change into a whole-file diff on Windows.
   const updated = `${lines.join(eol)}${endsWithNewline && lines.length ? eol : ''}`;
   assertWritableSize(updated);
-  if (!dryRun) await writeFile(absolute, updated, 'utf8');
+  if (!dryRun) await writeResolvedFile(absolute, updated);
   return text(present(updated, `Replaced ${starts.length} occurrence(s) using whitespace-tolerant matching (line endings kept as ${eol === '\r\n' ? 'CRLF' : 'LF'})`));
 }
 
@@ -482,7 +891,7 @@ export async function replaceLinesTool(args) {
   if (dryRun) {
     return text(`${summary}\n(dry run: nothing was written)\n${unifiedDiff(original, updatedText, { oldLabel: displayPath(absolute), newLabel: 'after' })}`);
   }
-  await writeFile(absolute, updatedText, 'utf8');
+  await writeResolvedFile(absolute, updatedText);
   return text(`${summary}.`);
 }
 
@@ -502,7 +911,7 @@ export async function replaceInFilesTool(args) {
       fail(`pattern is not a valid regular expression (${error instanceof Error ? error.message : String(error)})`);
     }
   }
-  const info = await stat(root).catch(() => fail(`Path not found: ${displayPath(root)}`));
+  const info = await getPathInfo(root).catch(() => fail(`Path not found: ${displayPath(root)}`));
   const walk = info.isFile() ? { files: [root], denied: [] } : await collectTree(root, { maxFiles, skip: ['.git', 'node_modules', '.remcp-trash*'] });
   const files = await confineAll(walk.files);
   const glob = filePattern ? globToRegExp(filePattern) : null;
@@ -532,7 +941,7 @@ export async function replaceInFilesTool(args) {
       const stats = diffStats(original, updated);
       changed.push({ file: displayPath(file), replacements: count, added: stats.added, removed: stats.removed });
     } finally {
-      await handle.close();
+      await opened.close();
     }
   }
   if (!changed.length) return text(`No matches for ${JSON.stringify(pattern)} in ${displayPath(root)} (${scanned} text files scanned).`);
@@ -562,7 +971,6 @@ function trashDirectoryFor() {
 
 export async function moveToTrashTool(args) {
   const source = await resolveSafePath(args.source, 'source');
-  const info = await stat(source).catch(() => fail(`Path not found: ${displayPath(source)}`));
   const trash = trashDirectoryFor();
   let destination = null;
   if (trash) {
@@ -577,7 +985,7 @@ export async function moveToTrashTool(args) {
   const existingDestination = await lstat(destination).catch(() => null);
   if (existingDestination?.isSymbolicLink()) fail('Refusing to use a symlink as the trash directory');
   if (existingDestination && !existingDestination.isDirectory()) fail('Trash destination is not a directory');
-  await mkdir(destination, { recursive: true, mode: 0o700 });
+  await ensureDirectoryPath(destination);
   destination = await resolveSafePath(destination, 'trash');
   const destinationInfo = await lstat(destination);
   if (!destinationInfo.isDirectory() || destinationInfo.isSymbolicLink()) fail('Refusing to use a symlink as the trash directory');
@@ -588,11 +996,17 @@ export async function moveToTrashTool(args) {
     target = path.join(destination, `${stamp}-${counter}-${path.basename(source)}`);
     counter += 1;
   }
-  await rename(source, target).catch(async error => {
-    if (error?.code !== 'EXDEV') throw error;
-    if (info.isDirectory()) fail('Moving a directory to the trash across filesystems is not supported');
-    await copyFile(source, target);
-    await unlink(source);
+  await withExistingParent(source, async anchoredSource => {
+    const sourceInfo = await lstat(anchoredSource).catch(() => fail(`Path not found: ${displayPath(source)}`));
+    if (sourceInfo.isSymbolicLink()) fail('source cannot be a symbolic link');
+    await withWritableParent(target, async anchoredTarget => {
+      await rename(anchoredSource, anchoredTarget).catch(async error => {
+        if (error?.code !== 'EXDEV') throw error;
+        if (sourceInfo.isDirectory()) fail('Moving a directory to the trash across filesystems is not supported');
+        await copyTreeContents(anchoredSource, anchoredTarget, { entries:0, bytes:0, maxBytes:Number.MAX_SAFE_INTEGER });
+        await rm(anchoredSource, { force:true });
+      });
+    });
   });
   return text(`Moved ${displayPath(source)} to ${displayPath(target)}. Restore it with move_file if this was a mistake.`);
 }
@@ -606,7 +1020,7 @@ export async function readFilesTool(args) {
   const maxLinesPerFile = clampInteger(args.max_lines_per_file, liveConfig('maxReadLines'), 1, 20000);
   const includeIgnored = args.include_ignored === true;
   const matcher = globToRegExp(pattern);
-  const rootInfo = await stat(root).catch(() => null);
+  const rootInfo = await getPathInfo(root).catch(() => null);
   // A file path is matched directly; a directory is walked without following links.
   const walk = rootInfo?.isFile()
     ? { files: [root], denied: [] }
@@ -661,8 +1075,7 @@ export async function writeFilesTool(args) {
       const bytes = assertWritableSize(content);
       totalBytes += bytes;
       if (totalBytes > runtimeConfig.maxWriteBytes * 4) fail(`This call would write ${totalBytes} bytes, above the ${runtimeConfig.maxWriteBytes * 4}-byte batch limit`);
-      await mkdir(path.dirname(absolute), { recursive: true });
-      await writeFile(absolute, content, entry.mode === 'append' ? { encoding: 'utf8', flag: 'a' } : 'utf8');
+      await writeResolvedFile(absolute, content, { append: entry.mode === 'append' });
       results.push(`${entry.mode === 'append' ? 'appended' : 'wrote'} ${displayPath(absolute)} (${bytes} bytes)`);
     } catch (error) {
       results.push(`failed ${target}: ${describeFilesystemFailure(error, { path: error?.path })}`);
@@ -675,15 +1088,19 @@ export async function writeFilesTool(args) {
 
 export async function deletePathTool(args) {
   const absolute = await resolveSafePath(args.path);
-  const info = await stat(absolute).catch(() => fail(`Path not found: ${displayPath(absolute)}`));
   if (path.dirname(absolute) === absolute) fail(`Refusing to delete the filesystem root ${displayPath(absolute)}`);
   const recursive = args.recursive !== false;
-  if (info.isDirectory() && !recursive) {
-    const entries = await readdir(absolute).catch(() => []);
-    if (entries.length) fail(`Directory is not empty: ${displayPath(absolute)}. Pass recursive: true to delete it with its contents.`);
-  }
-  const entries = info.isDirectory() ? await readdir(absolute).catch(() => []) : [];
-  await rm(absolute, { recursive: true, force: false });
+  let info;
+  let entries = [];
+  await withExistingParent(absolute, async target => {
+    info = await lstat(target).catch(() => fail(`Path not found: ${displayPath(absolute)}`));
+    if (info.isDirectory() && !recursive) {
+      entries = await readdir(target).catch(() => []);
+      if (entries.length) fail(`Directory is not empty: ${displayPath(absolute)}. Pass recursive: true to delete it with its contents.`);
+    }
+    if (info.isDirectory()) entries = await readdir(target).catch(() => []);
+    await rm(target, { recursive:true, force:false });
+  });
   return text(`Deleted ${info.isDirectory() ? 'directory' : 'file'} ${displayPath(absolute)}${info.isDirectory() ? ` and its ${entries.length} top-level entr${entries.length === 1 ? 'y' : 'ies'}` : ''}.`);
 }
 
@@ -698,13 +1115,15 @@ export async function deletePathsTool(args) {
     try {
       const absolute = await resolveSafePath(entry, 'paths[]');
       if (path.dirname(absolute) === absolute) throw new Error('refusing to delete the filesystem root');
-      const info = await stat(absolute).catch(() => null);
-      if (!info) throw new Error('not found');
-      if (info.isDirectory() && !recursive) {
-        const children = await readdir(absolute).catch(() => []);
-        if (children.length) throw new Error('directory is not empty (pass recursive: true)');
-      }
-      await rm(absolute, { recursive: true, force: false });
+      await withExistingParent(absolute, async target => {
+        const info = await lstat(target).catch(() => null);
+        if (!info) throw new Error('not found');
+        if (info.isDirectory() && !recursive) {
+          const children = await readdir(target).catch(() => []);
+          if (children.length) throw new Error('directory is not empty (pass recursive: true)');
+        }
+        await rm(target, { recursive:true, force:false });
+      });
       deleted += 1;
       results.push(`deleted ${displayPath(absolute)}`);
     } catch (error) {
@@ -728,12 +1147,11 @@ export async function copyPathsTool(args) {
       const source = await resolveSafePath(entry?.source, 'paths[].source');
       const destination = await resolveSafePath(entry?.destination, 'paths[].destination');
       if (source === destination) throw new Error('source and destination are the same path');
-      const info = await stat(source).catch(() => null);
-      if (!info) throw new Error('source not found');
-      const existing = await stat(destination).catch(() => null);
-      if (existing && !overwrite) throw new Error('destination already exists (pass overwrite: true)');
-      await mkdir(path.dirname(destination), { recursive: true });
-      await cp(source, destination, { recursive: true, force: overwrite, errorOnExist: !overwrite });
+      await withWritableParent(destination, async anchoredDestination => {
+        const existing = await lstat(anchoredDestination).catch(() => null);
+        if (existing && !overwrite) throw new Error('destination already exists (pass overwrite: true)');
+        await copyTreeContents(source, anchoredDestination, { entries:0, bytes:0, maxBytes:Number.MAX_SAFE_INTEGER });
+      });
       copied += 1;
       results.push(`copied ${displayPath(source)} → ${displayPath(destination)}`);
     } catch (error) {
@@ -755,18 +1173,22 @@ export async function movePathsTool(args) {
       const source = await resolveSafePath(entry?.source, 'paths[].source');
       const destination = await resolveSafePath(entry?.destination, 'paths[].destination');
       if (source === destination) throw new Error('source and destination are the same path');
-      const info = await stat(source).catch(() => null);
-      if (!info) throw new Error('source not found');
-      const existing = await stat(destination).catch(() => null);
-      if (existing && !overwrite) throw new Error('destination already exists (pass overwrite: true)');
-      await mkdir(path.dirname(destination), { recursive: true });
-      try {
-        await rename(source, destination);
-      } catch (error) {
-        if (error?.code !== 'EXDEV') throw error;
-        await cp(source, destination, { recursive: true, force: overwrite, errorOnExist: !overwrite });
-        await rm(source, { recursive: true, force: true });
-      }
+      await withExistingParent(source, async anchoredSource => {
+        const sourceInfo = await lstat(anchoredSource).catch(() => null);
+        if (!sourceInfo) throw new Error('source not found');
+        if (sourceInfo.isSymbolicLink()) throw new Error('source cannot be a symbolic link');
+        await withWritableParent(destination, async anchoredDestination => {
+          const existing = await lstat(anchoredDestination).catch(() => null);
+          if (existing && !overwrite) throw new Error('destination already exists (pass overwrite: true)');
+          try {
+            await rename(anchoredSource, anchoredDestination);
+          } catch (error) {
+            if (error?.code !== 'EXDEV') throw error;
+            await copyTreeContents(anchoredSource, anchoredDestination, { entries:0, bytes:0, maxBytes:Number.MAX_SAFE_INTEGER });
+            await rm(anchoredSource, { recursive:true, force:true });
+          }
+        });
+      });
       moved += 1;
       results.push(`moved ${displayPath(source)} → ${displayPath(destination)}`);
     } catch (error) {
@@ -801,8 +1223,7 @@ export async function applyPatchTool(args) {
       const stats = diffStats(original, updated);
       if (!dryRun) {
         assertWritableSize(updated);
-        await mkdir(path.dirname(absolute), { recursive: true });
-        await writeFile(absolute, updated, 'utf8');
+        await writeResolvedFile(absolute, updated);
       }
       changed += 1;
       const fuzzy = applied.filter(entry => entry.fuzz > 0).length;
@@ -816,41 +1237,81 @@ export async function applyPatchTool(args) {
   return text([`${changed}/${files.length} file(s) ${dryRun ? 'would be patched' : 'patched'}`, ...results].join('\n'), failedCount > 0);
 }
 
+async function setLinuxPermissions(target, mode, uid, gid, recursive, displayTarget, failures) {
+  let directory = null;
+  let file = null;
+  try {
+    const info = await lstat(target);
+    if (info.isSymbolicLink()) {
+      failures.push(`${displayTarget}: symbolic links are not changed`);
+      return 0;
+    }
+    if (info.isDirectory()) {
+      directory = await openDirectoryPath(target);
+      let changed = 0;
+      if (recursive) {
+        for (const entry of await readdir(directory.anchor, { withFileTypes:true })) {
+          if (entry.isSymbolicLink()) continue;
+          changed += await setLinuxPermissions(path.join(directory.anchor, entry.name), mode, uid, gid, true, path.join(displayTarget, entry.name), failures);
+        }
+      }
+      await directory.handle.chmod(mode);
+      if (uid !== null || gid !== null) await directory.handle.chown(uid ?? -1, gid ?? -1);
+      return changed + 1;
+    }
+    if (!info.isFile()) {
+      failures.push(`${displayTarget}: special files are not changed`);
+      return 0;
+    }
+    file = await openRegularFile(target, READ_NOFOLLOW);
+    await file.handle.chmod(mode);
+    if (uid !== null || gid !== null) await file.handle.chown(uid ?? -1, gid ?? -1);
+    return 1;
+  } catch (error) {
+    failures.push(`${displayTarget}: ${describeFilesystemFailure(error, { path:error?.path })}`);
+    return 0;
+  } finally {
+    if (file) await file.close().catch(() => {});
+    if (directory) await directory.close().catch(() => {});
+  }
+}
+
 export async function setPermissionsTool(args) {
   const absolute = await resolveSafePath(args.path);
-  const info = await stat(absolute).catch(() => fail(`Path not found: ${displayPath(absolute)}`));
   const raw = typeof args.mode === 'string' ? args.mode.trim() : String(args.mode ?? '');
   if (!/^[0-7]{3,4}$/.test(raw)) fail('mode must be an octal string such as "755" or "0644"');
   const mode = Number.parseInt(raw, 8);
   const recursive = args.recursive === true;
   const uid = Number.isInteger(Number(args.uid)) ? Number(args.uid) : null;
   const gid = Number.isInteger(Number(args.gid)) ? Number(args.gid) : null;
-  const targets = [absolute];
-  if (recursive) {
-    // Directories are included, links are not: chmod follows a link and would change a target
-    // outside the allowed roots.
-    const walk = async target => {
-      const entries = await readdir(target, { withFileTypes: true }).catch(() => []);
-      for (const entry of entries) {
-        if (entry.isSymbolicLink()) continue;
-        const child = path.join(target, entry.name);
-        targets.push(child);
-        if (entry.isDirectory()) await walk(child);
-      }
-    };
-    await walk(absolute);
-  }
-  const confined = await confineAll(targets);
-  let changed = 0;
   const failures = [];
-  for (const target of confined) {
-    try {
-      await chmod(target, mode);
-      if (uid !== null || gid !== null) await chown(target, uid ?? -1, gid ?? -1);
-      changed += 1;
-    } catch (error) {
-      // One protected file must not abort a recursive change; the caller gets the full picture.
-      failures.push(`${displayPath(target)}: ${describeFilesystemFailure(error, { path: error?.path })}`);
+  let changed = 0;
+  if (process.platform === 'linux' && constants.O_NOFOLLOW && constants.O_DIRECTORY) {
+    changed = await setLinuxPermissions(absolute, mode, uid, gid, recursive, displayPath(absolute), failures);
+  } else {
+    const info = await stat(absolute).catch(() => fail(`Path not found: ${displayPath(absolute)}`));
+    const targets = [absolute];
+    if (recursive && info.isDirectory()) {
+      const walk = async target => {
+        const entries = await readdir(target, { withFileTypes:true }).catch(() => []);
+        for (const entry of entries) {
+          if (entry.isSymbolicLink()) continue;
+          const child = path.join(target, entry.name);
+          targets.push(child);
+          if (entry.isDirectory()) await walk(child);
+        }
+      };
+      await walk(absolute);
+    }
+    const confined = await confineAll(targets);
+    for (const target of confined) {
+      try {
+        await chmod(target, mode);
+        if (uid !== null || gid !== null) await chown(target, uid ?? -1, gid ?? -1);
+        changed += 1;
+      } catch (error) {
+        failures.push(`${displayPath(target)}: ${describeFilesystemFailure(error, { path:error?.path })}`);
+      }
     }
   }
   const summary = `Set mode ${raw}${uid !== null || gid !== null ? ` (uid ${uid ?? '-'} gid ${gid ?? '-'})` : ''} on ${changed} path(s) starting at ${displayPath(absolute)}.`;
@@ -867,7 +1328,7 @@ export async function createDirectoryTool(args) {
   for (const entry of list) {
     try {
       const absolute = await resolveSafePath(entry);
-      await mkdir(absolute, { recursive: true });
+      await ensureDirectoryPath(absolute);
       created.push(displayPath(absolute));
     } catch (error) {
       failed.push(`${entry}: ${describeFilesystemFailure(error, { path: error?.path })}`);
@@ -885,24 +1346,28 @@ export async function moveFileTool(args) {
   const source = await resolveSafePath(args.source, 'source');
   const destination = await resolveSafePath(args.destination, 'destination');
   if (source === destination) fail('source and destination are the same path');
-  await stat(source).catch(() => fail(`Source not found: ${displayPath(source)}`));
   const overwrite = args.overwrite !== false;
-  const existing = await stat(destination).catch(() => null);
-  if (existing && !overwrite) fail(`Destination already exists: ${displayPath(destination)}. Pass overwrite: true to replace it.`);
-  if (existing?.isDirectory()) {
-    const entries = await readdir(destination).catch(() => []);
-    if (entries.length) fail(`Destination is a non-empty directory: ${displayPath(destination)}. Move it aside or pick another name.`);
-  }
-  await mkdir(path.dirname(destination), { recursive: true });
-  try {
-    await rename(source, destination);
-  } catch (error) {
-    if (error?.code !== 'EXDEV') throw error;
-    const info = await stat(source);
-    if (info.isDirectory()) fail('Moving a directory across filesystems is not supported; copy it manually or move within one volume');
-    await copyFile(source, destination);
-    await unlink(source);
-  }
+  await withExistingParent(source, async anchoredSource => {
+    const sourceInfo = await lstat(anchoredSource).catch(() => fail(`Source not found: ${displayPath(source)}`));
+    if (sourceInfo.isSymbolicLink()) fail('source cannot be a symbolic link');
+    await withWritableParent(destination, async anchoredDestination => {
+      const existing = await lstat(anchoredDestination).catch(() => null);
+      if (existing?.isSymbolicLink()) fail('destination cannot be a symbolic link');
+      if (existing && !overwrite) fail(`Destination already exists: ${displayPath(destination)}. Pass overwrite: true to replace it.`);
+      if (existing?.isDirectory()) {
+        const entries = await readdir(anchoredDestination).catch(() => []);
+        if (entries.length) fail(`Destination is a non-empty directory: ${displayPath(destination)}. Move it aside or pick another name.`);
+      }
+      try {
+        await rename(anchoredSource, anchoredDestination);
+      } catch (error) {
+        if (error?.code !== 'EXDEV') throw error;
+        if (sourceInfo.isDirectory()) fail('Moving a directory across filesystems is not supported; copy it manually or move within one volume');
+        await copyTreeContents(anchoredSource, anchoredDestination, { entries:0, bytes:0, maxBytes:Number.MAX_SAFE_INTEGER });
+        await rm(anchoredSource, { force:true });
+      }
+    });
+  });
   return text(`Moved ${displayPath(source)} to ${displayPath(destination)}.`);
 }
 
@@ -910,31 +1375,24 @@ export async function copyFileTool(args) {
   const source = await resolveSafePath(args.source, 'source');
   const destination = await resolveSafePath(args.destination, 'destination');
   if (source === destination) fail('source and destination are the same path');
-  const info = await stat(source).catch(() => fail(`Source not found: ${displayPath(source)}`));
-  if (info.isDirectory()) fail('copy_file copies single files only; create the directory and copy its files individually');
   const overwrite = args.overwrite !== false;
-  if (!overwrite && await pathExists(destination)) fail(`Destination already exists: ${displayPath(destination)}. Pass overwrite: true to replace it.`);
-  await mkdir(path.dirname(destination), { recursive: true });
-  await copyFile(source, destination, overwrite ? 0 : constants.COPYFILE_EXCL);
+  let info;
+  await withExistingParent(source, async anchoredSource => {
+    const sourceInfo = await lstat(anchoredSource).catch(() => fail(`Source not found: ${displayPath(source)}`));
+    if (sourceInfo.isSymbolicLink()) fail('source cannot be a symbolic link');
+    if (sourceInfo.isDirectory()) fail('copy_file copies single files only; create the directory and copy its files individually');
+    info = sourceInfo;
+    await withWritableParent(destination, async anchoredDestination => {
+      const existing = await lstat(anchoredDestination).catch(() => null);
+      if (existing?.isSymbolicLink()) fail('destination cannot be a symbolic link');
+      if (existing && !overwrite) fail(`Destination already exists: ${displayPath(destination)}. Pass overwrite: true to replace it.`);
+      await copyTreeContents(anchoredSource, anchoredDestination, { entries:0, bytes:0, maxBytes:Number.MAX_SAFE_INTEGER });
+    });
+  });
   return text(`Copied ${displayPath(source)} to ${displayPath(destination)} (${info.size} bytes).`);
 }
 
 // --- archives -------------------------------------------------------------------------
-async function assertNoSymlinkTree(root, state = { entries: 0 }) {
-  const info = await lstat(root);
-  if (info.isSymbolicLink()) fail(`Archive sources cannot contain symbolic links: ${displayPath(root)}`);
-  if (!info.isDirectory() && !info.isFile()) fail(`Archive sources cannot contain special files: ${displayPath(root)}`);
-  state.entries += 1;
-  if (state.entries > 100_000) fail('Archive source contains too many entries');
-  if (state.maxBytes !== undefined && info.isFile()) {
-    state.bytes = (state.bytes || 0) + info.size;
-    if (state.bytes > state.maxBytes) fail('Archive source exceeds the safety limit');
-  }
-  if (!info.isDirectory()) return;
-  const entries = await readdir(root, { withFileTypes: true });
-  for (const entry of entries) await assertNoSymlinkTree(path.join(root, entry.name), state);
-}
-
 const MAX_ARCHIVE_EXPANDED_BYTES = Math.min(
   4 * 1024 * 1024 * 1024,
   Math.max(64 * 1024 * 1024, Number(process.env.REMCP_MAX_ARCHIVE_EXPANDED_BYTES) || 512 * 1024 * 1024),
@@ -1007,43 +1465,7 @@ async function assertExtractedTree(root, state = { entries: 0, bytes: 0 }) {
 }
 
 async function openArchiveSource(absolute) {
-  if (process.platform !== 'linux') {
-    const opened = await openRegularFile(absolute, READ_NOFOLLOW_NONBLOCK);
-    return { ...opened, close: () => opened.handle.close() };
-  }
-  const root = path.parse(absolute).root;
-  const parts = absolute.slice(root.length).split(path.sep).filter(Boolean);
-  if (!parts.length) return openRegularFile(absolute, READ_NOFOLLOW_NONBLOCK);
-  const directories = [];
-  let current = root;
-  const closeDirectories = async () => {
-    for (const handle of directories.reverse()) await handle.close().catch(() => {});
-  };
-  try {
-    for (const part of parts.slice(0, -1)) {
-      const handle = await open(path.join(current, part), DIRECTORY_READ_NOFOLLOW);
-      try {
-        const info = await handle.stat();
-        if (!info.isDirectory()) fail('Archive source is not a safe regular file');
-      } catch (error) {
-        await handle.close().catch(() => {});
-        throw error;
-      }
-      directories.push(handle);
-      current = `/proc/self/fd/${handle.fd}`;
-    }
-    const opened = await openRegularFile(path.join(current, parts.at(-1)), READ_NOFOLLOW_NONBLOCK);
-    return {
-      ...opened,
-      close: async () => {
-        try { await opened.handle.close(); }
-        finally { await closeDirectories(); }
-      },
-    };
-  } catch (error) {
-    await closeDirectories();
-    throw error;
-  }
+  return openRegularFile(absolute, READ_NOFOLLOW_NONBLOCK);
 }
 
 async function snapshotRegularFile(source, destination, maxBytes) {
@@ -1127,47 +1549,48 @@ async function copyOpenRegularFile(sourceHandle, sourceInfo, destinationPath, st
 
 async function copyTreeContents(source, destination, state = { entries: 0, bytes: 0, maxBytes: MAX_ARCHIVE_EXPANDED_BYTES }) {
   const initial = await lstat(source);
-  if (initial.isSymbolicLink() || (!initial.isDirectory() && !initial.isFile())) fail('Archive contains a link or special file; archive destination is unsafe');
+  if (initial.isSymbolicLink() || (!initial.isDirectory() && !initial.isFile())) fail('Archive contains symbolic links or special files; archive destination is unsafe');
   state.entries += 1;
   if (state.entries > 100_000) fail('Archive contains too many entries');
   if (initial.isFile()) {
-    const opened = await openRegularFile(source, READ_NOFOLLOW_NONBLOCK);
+    const opened = source.startsWith('/proc/self/fd/')
+      ? await openRegularFile(source, READ_NOFOLLOW_NONBLOCK)
+      : await openArchiveSource(source);
     try { await copyOpenRegularFile(opened.handle, opened.info, destination, state); }
-    finally { await opened.handle.close(); }
+    finally { if (opened.close) await opened.close(); else await opened.handle.close(); }
     return;
   }
   let directoryHandle = null;
   let sourcePath = source;
   let info = initial;
   try {
-    if (process.platform === 'linux') {
-      try {
-        directoryHandle = await open(source, DIRECTORY_READ_NOFOLLOW);
-        info = await directoryHandle.stat();
-        if (!info.isDirectory()) fail('Archive contains a link or special file; archive destination is unsafe');
-        sourcePath = `/proc/self/fd/${directoryHandle.fd}`;
-      } catch (error) {
-        if (['ELOOP', 'ENOTDIR'].includes(error?.code)) fail('Archive contains a link or special file; archive destination is unsafe');
-        throw error;
-      }
+    try {
+      directoryHandle = await openDirectoryPath(source, { allowOutside:state.allowOutsideSource === true });
+      info = await directoryHandle.handle.stat();
+      if (!info.isDirectory()) fail('Archive contains a link or special file; archive destination is unsafe');
+      sourcePath = directoryHandle.anchor;
+    } catch (error) {
+      if (['ELOOP', 'ENOTDIR'].includes(error?.code)) fail('Archive contains a link or special file; archive destination is unsafe');
+      throw error;
     }
     const mode = info.mode & 0o777;
     const existing = await lstat(destination).catch(() => null);
     if (existing && (!existing.isDirectory() || existing.isSymbolicLink())) fail('Archive contains a link or special file; archive destination is unsafe');
-    try { await mkdir(destination, { mode: mode | 0o700 }); }
+    try { await ensureDirectoryPath(destination, { allowOutside:true }); }
     catch (error) { if (error?.code !== 'EEXIST') throw error; }
     const destinationInfo = await lstat(destination);
     if (!destinationInfo.isDirectory() || destinationInfo.isSymbolicLink()) fail('Archive contains a link or special file; archive destination is unsafe');
     let destinationHandle;
     try {
-      destinationHandle = await open(destination, DIRECTORY_READ_NOFOLLOW);
-      const openedDestination = await destinationHandle.stat();
+      destinationHandle = await openDirectoryPath(destination, { allowOutside:true });
+      const openedDestination = await destinationHandle.handle.stat();
       if (!openedDestination.isDirectory()) fail('Archive contains a link or special file; archive destination is unsafe');
-      await destinationHandle.chmod(mode | 0o700);
+      await destinationHandle.handle.chmod(mode | 0o700);
+      const destinationAnchor = destinationHandle.anchor;
       for (const name of await readdir(sourcePath)) {
-        await copyTreeContents(path.join(sourcePath, name), path.join(destination, name), state);
+        await copyTreeContents(path.join(sourcePath, name), path.join(destinationAnchor, name), state);
       }
-      await destinationHandle.chmod(mode);
+      await destinationHandle.handle.chmod(mode);
     } finally {
       if (destinationHandle) await destinationHandle.close().catch(() => {});
     }
@@ -1184,32 +1607,39 @@ async function removeExtractionArtifact(target) {
 }
 
 async function recoverExtractionArtifacts(parent, destination, prefix) {
-  const entries = await readdir(parent, { withFileTypes: true });
-  const staleBefore = Date.now() - 60 * 60 * 1000;
-  for (const entry of entries) {
-    if (!entry.name.startsWith('.remcp-extract-txn-')) continue;
-    const candidate = path.join(parent, entry.name);
-    const info = await lstat(candidate).catch(() => null);
-    if (info && info.mtimeMs < staleBefore) await removeExtractionArtifact(candidate);
-  }
-  const backups = entries.filter(entry => entry.name.startsWith(prefix)).map(entry => path.join(parent, entry.name));
-  for (const backup of backups) {
-    const destinationInfo = await lstat(destination).catch(() => null);
-    if (destinationInfo) {
-      await removeExtractionArtifact(backup);
-      continue;
-    }
-    const backupInfo = await lstat(backup).catch(() => null);
-    if (!backupInfo) continue;
-    if (backupInfo.isSymbolicLink() || !backupInfo.isDirectory()) {
-      await removeExtractionArtifact(backup);
-      continue;
+  const parentDirectory = await openDirectoryPath(parent, { create:true });
+  const anchor = parentDirectory.anchor;
+  const destinationPath = path.join(anchor, path.basename(destination));
+  try {
+    const entries = await readdir(anchor, { withFileTypes: true });
+    const staleBefore = Date.now() - 60 * 60 * 1000;
+    for (const entry of entries) {
+      if (!entry.name.startsWith('.remcp-extract-txn-')) continue;
+      const candidate = path.join(anchor, entry.name);
+      const info = await lstat(candidate).catch(() => null);
+      if (info && info.mtimeMs < staleBefore) await removeExtractionArtifact(candidate);
     }
-    try {
-      await rename(backup, destination);
-    } catch {
-      continue;
+    const backups = entries.filter(entry => entry.name.startsWith(prefix)).map(entry => path.join(anchor, entry.name));
+    for (const backup of backups) {
+      const destinationInfo = await lstat(destinationPath).catch(() => null);
+      if (destinationInfo) {
+        await removeExtractionArtifact(backup);
+        continue;
+      }
+      const backupInfo = await lstat(backup).catch(() => null);
+      if (!backupInfo) continue;
+      if (backupInfo.isSymbolicLink() || !backupInfo.isDirectory()) {
+        await removeExtractionArtifact(backup);
+        continue;
+      }
+      try {
+        await rename(backup, destinationPath);
+      } catch {
+        continue;
+      }
     }
+  } finally {
+    await parentDirectory.close().catch(() => {});
   }
 }
 
@@ -1232,20 +1662,23 @@ async function restoreExtractionBackup(backup, destination) {
 async function installExtractedTree(source, destination) {
   const parent = path.dirname(destination);
   if (destination === path.parse(destination).root) fail('Archive destination cannot be a filesystem root');
-  await mkdir(parent, { recursive: true, mode: 0o700 });
   const backupPrefix = `.remcp-extract-backup-${createHash('sha256').update(destination).digest('hex').slice(0, 16)}-`;
   await recoverExtractionArtifacts(parent, destination, backupPrefix);
-  const existing = await lstat(destination).catch(() => null);
+  const parentDirectory = await openDirectoryPath(parent, { create:true });
+  const parentAnchor = parentDirectory.anchor;
+  const destinationPath = path.join(parentAnchor, path.basename(destination));
+  const existing = await lstat(destinationPath).catch(() => null);
   const destinationMode = existing?.isDirectory() ? existing.mode & 0o777 : 0o700;
-  const transaction = await mkdtemp(path.join(parent, '.remcp-extract-txn-'));
+  let transaction = '';
   let backup = '';
   let backupOwned = false;
   let preserveBackup = false;
   try {
+    transaction = await mkdtemp(path.join(parentAnchor, '.remcp-extract-txn-'));
     if (existing) {
-      backup = path.join(parent, `${backupPrefix}${randomUUID()}`);
+      backup = path.join(parentAnchor, `${backupPrefix}${randomUUID()}`);
       try {
-        await rename(destination, backup);
+        await rename(destinationPath, backup);
         backupOwned = true;
       } catch (error) {
         if (error?.code !== 'ENOENT') throw error;
@@ -1255,11 +1688,11 @@ async function installExtractedTree(source, destination) {
     if (backupOwned) {
       const backupInfo = await lstat(backup);
       if (backupInfo.isSymbolicLink() || !backupInfo.isDirectory()) fail('Archive destination is not a safe directory');
-      await copyTreeContents(backup, transaction);
+      await copyTreeContents(backup, transaction, { entries:0, bytes:0, maxBytes:MAX_ARCHIVE_EXPANDED_BYTES, allowOutsideSource:true });
     }
-    await copyTreeContents(source, transaction);
+    await copyTreeContents(source, transaction, { entries:0, bytes:0, maxBytes:MAX_ARCHIVE_EXPANDED_BYTES, allowOutsideSource:true });
     await chmod(transaction, destinationMode);
-    await rename(transaction, destination);
+    await rename(transaction, destinationPath);
     if (backupOwned) {
       await removeExtractionArtifact(backup);
       backupOwned = false;
@@ -1267,7 +1700,7 @@ async function installExtractedTree(source, destination) {
   } catch (error) {
     if (backupOwned) {
       try {
-        await restoreExtractionBackup(backup, destination);
+        await restoreExtractionBackup(backup, destinationPath);
         if (!await lstat(backup).catch(() => null)) backupOwned = false;
         else preserveBackup = true;
       } catch (restoreError) {
@@ -1277,24 +1710,32 @@ async function installExtractedTree(source, destination) {
     }
     throw error;
   } finally {
-    await rm(transaction, { recursive: true, force: true });
+    if (transaction) await rm(transaction, { recursive: true, force: true });
     if (backupOwned && !preserveBackup) await removeExtractionArtifact(backup);
+    await parentDirectory.close().catch(() => {});
   }
 }
 
 async function moveArchiveFile(source, destination) {
+  const parent = path.dirname(destination);
+  const parentDirectory = await openDirectoryPath(parent, { create:true });
+  const destinationPath = path.join(parentDirectory.anchor, path.basename(destination));
   try {
-    await rename(source, destination);
-  } catch (error) {
-    if (!['EXDEV', 'EPERM'].includes(error?.code)) throw error;
-    const temporary = path.join(path.dirname(destination), `.${path.basename(destination)}.remcp-${randomUUID()}.tmp`);
     try {
-      await copyFile(source, temporary, constants.COPYFILE_EXCL);
-      await rename(temporary, destination);
-    } finally {
-      await unlink(temporary).catch(() => {});
+      await rename(source, destinationPath);
+    } catch (error) {
+      if (!['EXDEV', 'EPERM'].includes(error?.code)) throw error;
+      const temporary = path.join(parentDirectory.anchor, `.${path.basename(destination)}.remcp-${randomUUID()}.tmp`);
+      try {
+        await copyFile(source, temporary, constants.COPYFILE_EXCL);
+        await rename(temporary, destinationPath);
+      } finally {
+        await unlink(temporary).catch(() => {});
+      }
+      await unlink(source);
     }
-    await unlink(source);
+  } finally {
+    await parentDirectory.close().catch(() => {});
   }
 }
 
@@ -1314,13 +1755,10 @@ export async function createArchiveTool(args) {
   if (!sources.length) fail('paths must list at least one file or directory');
   const resolved = [];
   for (const entry of sources) resolved.push(await resolveSafePath(entry, 'paths[]'));
-  const sourceState = { entries: 0, bytes: 0, maxBytes: MAX_ARCHIVE_EXPANDED_BYTES };
-  for (const entry of resolved) await assertNoSymlinkTree(entry, sourceState);
   const destination = await resolveSafePath(args.destination, 'destination');
   const existingDestination = await lstat(destination).catch(() => null);
   if (existingDestination?.isSymbolicLink()) fail('Archive destination cannot be a symbolic link');
   const format = String(args.format || (destination.endsWith('.zip') ? 'zip' : 'tar.gz')).toLowerCase();
-  await mkdir(path.dirname(destination), { recursive: true });
   const baseDir = path.dirname(resolved[0]);
   const names = resolved.map(entry => path.relative(baseDir, entry));
   if (names.some(name => !name || name.startsWith('..') || path.isAbsolute(name))) fail('Archive sources must share one parent directory');
@@ -1334,11 +1772,13 @@ export async function createArchiveTool(args) {
    const staging = path.join(stagingDirectory, `payload${suffix}`);
    const snapshotRoot = path.join(stagingDirectory, 'source');
    try {
-     await mkdir(snapshotRoot, { mode: 0o700 });
+      await ensureDirectoryPath(snapshotRoot, { allowOutside:true });
+
      const snapshotState = { entries: 0, bytes: 0, maxBytes: MAX_ARCHIVE_EXPANDED_BYTES };
      for (let index = 0; index < resolved.length; index += 1) {
        const snapshotPath = path.join(snapshotRoot, names[index]);
-       await mkdir(path.dirname(snapshotPath), { recursive: true, mode: 0o700 });
+        await ensureDirectoryPath(path.dirname(snapshotPath), { allowOutside:true });
+
        await copyTreeContents(resolved[index], snapshotPath, snapshotState);
      }
      if (format === 'zip') {
@@ -1353,11 +1793,11 @@ export async function createArchiveTool(args) {
      } else {
        fail('format must be tar, tar.gz, or zip');
      }
-     const stagedInfo = await stat(staging);
-     assertArchiveExpandedSize(stagedInfo.size, 'archive output');
-     await mkdir(path.dirname(destination), { recursive: true });
+      const stagedInfo = await stat(staging);
+      assertArchiveExpandedSize(stagedInfo.size, 'archive output');
+
+      await moveArchiveFile(staging, destination);
 
-     await moveArchiveFile(staging, destination);
      const info = await stat(destination).catch(() => null);
      const note = ' (built outside the tree in temporary staging and committed atomically)';
 
@@ -1397,7 +1837,6 @@ export async function extractArchiveTool(args) {
   try {
     await mkdir(staging, { mode: 0o700 });
     await snapshotRegularFile(archive, archiveSnapshot, MAX_ARCHIVE_EXPANDED_BYTES);
-    await mkdir(parent, { recursive: true, mode: 0o700 });
     await recoverExtractionArtifacts(parent, destination, backupPrefix);
     const existingDestination = await lstat(destination).catch(() => null);
     if (existingDestination?.isSymbolicLink() || (existingDestination && !existingDestination.isDirectory())) fail('Archive destination is not a safe directory');
@@ -1493,8 +1932,17 @@ export async function takeScreenshotTool(args) {
   const requestedDirectory = args.directory ? await resolveSafePath(args.directory, 'directory') : '';
   const temporaryDirectory = requestedDirectory ? '' : await mkdtemp(path.join(os.tmpdir(), 'remcp-screenshot-'));
   const directory = requestedDirectory || temporaryDirectory;
-  if (requestedDirectory) await mkdir(directory, { recursive: true });
-  const file = path.join(directory, `capture-${randomUUID()}.png`);
+  let outputDirectory = null;
+  if (requestedDirectory) {
+    await ensureDirectoryPath(directory);
+    outputDirectory = await openWritableParent(directory);
+  }
+  const outputAnchor = outputDirectory
+    ? outputDirectory.anchor.replace('/proc/self/fd/', `/proc/${process.pid}/fd/`)
+    : directory;
+  const fileName = `capture-${randomUUID()}.png`;
+  const file = path.join(outputAnchor, fileName);
+  const displayFile = path.join(directory, fileName);
   const attempts = [];
   let preserveCapture = false;
   try {
@@ -1524,26 +1972,28 @@ export async function takeScreenshotTool(args) {
     }
     if (!await pathExists(file)) fail(screenshotAdvice(attempts));
 
-    const { handle, info } = await openRegularFile(file);
+    const opened = await openRegularFile(file);
+    const { handle, info } = opened;
     try {
       if (info.size <= MAX_IMAGE_BYTES) {
         const buffer = await handle.readFile();
         preserveCapture = args.keep === true;
         return multi([
-          { type: 'text', text: `Screenshot of ${os.hostname()} (${info.size} bytes)${preserveCapture ? (' saved at ' + displayPath(file)) : ''}` },
+          { type: 'text', text: `Screenshot of ${os.hostname()} (${info.size} bytes)${preserveCapture ? (' saved at ' + displayPath(displayFile)) : ''}` },
           image(buffer.toString('base64'), 'image/png'),
         ]);
       }
       preserveCapture = true;
-      return text(`Screenshot of ${os.hostname()} captured: ${info.size} bytes, above the ${MAX_IMAGE_BYTES}-byte inline limit, so it is saved at ${displayPath(file)} instead of being returned as an image. Fetch it with read_binary using chunks of up to ${MAX_BINARY_CHUNK_BYTES} bytes (offset_bytes and length_bytes), or ask for a smaller region.`);
+      return text(`Screenshot of ${os.hostname()} captured: ${info.size} bytes, above the ${MAX_IMAGE_BYTES}-byte inline limit, so it is saved at ${displayPath(displayFile)} instead of being returned as an image. Fetch it with read_binary using chunks of up to ${MAX_BINARY_CHUNK_BYTES} bytes (offset_bytes and length_bytes), or ask for a smaller region.`);
     } finally {
-      await handle.close();
+      await opened.close();
     }
   } finally {
     if (!preserveCapture) {
       if (temporaryDirectory) await rm(temporaryDirectory, { recursive: true, force: true }).catch(() => {});
       else await rm(file, { force: true }).catch(() => {});
     }
+    if (outputDirectory) await outputDirectory.close().catch(() => {});
   }
 }
 export const fileToolHandlers = {