fix(engine): allow symlinks that resolve inside the project root

The ancestor-symlink check from #499 rejected any symlinked path component
below the project root, regardless of where it pointed. That over-rejects: a
link resolving back inside the project escapes nothing, and symlinked
directories inside a repository are an ordinary layout. Workspace monorepos
symlink node_modules/<pkg> to packages/<pkg> (pnpm, npm, yarn and bun all do
this), and projects symlink shared source directories — so archgate refused
to read files it is meant to govern, failing the rule with "access denied".

The gate is now where a symlink POINTS rather than that one exists: each
component below the root is resolved and rejected only when its target lands
outside the root. The escape #499 closed stays closed — an outside-pointing
link is still rejected at any component, including after an earlier hop that
legitimately stayed inside.

Comparison is realpath-against-realpath, never realpath-against-lexical:
realpath case-canonicalizes on Windows and macOS, so mixing the two would
reject case-mismatched-but-legitimate paths. Both sides are resolved so the
same canonicalization applies to each, and the root's own realpath is
memoized alongside the per-component memo.

The component memo is keyed by (root, component) rather than component
alone: the same component can sit under two roots with different verdicts,
since a link leaving root A may land inside an enclosing root B.

Note this also relaxes the pre-existing LEAF symlink check, which likewise
rejected in-project links. Leaving the leaf strict while allowing ancestors
would be arbitrary — a file reachable as packages/shared/index.ts should not
become unreadable because it is also linked as index.ts.

Signed-off-by: Rhuan Barreto <rhuan@barreto.work>

Author: rhuanbarreto

src/engine/safe-path.ts

@@ -1,6 +1,6 @@
 // SPDX-License-Identifier: Apache-2.0
 // Copyright 2026 Archgate
-import { lstatSync } from "node:fs";
+import { lstatSync, realpathSync } from "node:fs";
 import { resolve, isAbsolute, join, relative } from "node:path";
 
 import { UserError } from "../helpers/user-error";
@@ -31,23 +31,45 @@ export function isWithinRoot(resolvedRoot: string, absPath: string): boolean {
 }
 
 /**
- * Directories verified as real (non-symlink), memoized per process: safePath
- * runs once per glob result and siblings share every ancestor, so without this
- * the walk below re-lstats the same directories thousands of times per run.
+ * Components already verified safe, memoized per process: safePath runs once
+ * per glob result and siblings share every ancestor. Nested per root — the
+ * same component under two roots can differ, since a link leaving root A may
+ * land inside an enclosing root B.
  */
-const verifiedRealDirs = new Set<string>();
+const verifiedComponents = new Map<string, Set<string>>();
+
+/** Project roots resolved through `realpath`, memoized per process. */
+const realRoots = new Map<string, string>();
+
+/**
+ * The project root with symlinks in its own path resolved, so a link target
+ * compares against it like-for-like. Falls back to the lexical root.
+ */
+function realRootOf(resolvedRoot: string): string {
+  let hit = realRoots.get(resolvedRoot);
+  if (hit === undefined) {
+    try {
+      hit = realpathSync(resolvedRoot);
+    } catch {
+      hit = resolvedRoot;
+    }
+    realRoots.set(resolvedRoot, hit);
+  }
+  return hit;
+}
 
 /**
- * Reject a symlink anywhere in the path below the project root — the leaf OR
- * any ancestor, since a linked ancestor makes the leaf look like an ordinary
- * file to both `isWithinRoot` and a leaf `lstat`. Components at or above the
- * root are deliberately not inspected, and each test is a boolean `lstat`
- * rather than a `realpath` comparison.
+ * Reject a path whose real target lies outside the project root, testing every
+ * component below it — the leaf AND every ancestor, since a linked ancestor
+ * makes the leaf look ordinary to both `isWithinRoot` and a leaf `lstat`. The
+ * gate is where a link POINTS, not that one exists: links resolving back
+ * inside the project are a normal layout (workspace monorepos, shared dirs).
  *
- * @throws {UserError} When any component below the root is a symbolic link.
- * @see ARCH-022 — why the walk stops at the root and avoids `realpath`
+ * @throws {UserError} When a component resolves outside the project root.
+ * @see ARCH-022 — why the walk stops at the root
+ * @see .claude/agent-memory/archgate-developer/project_rules_engine_internals.md — why both sides are realpath'd
  */
-function assertNoSymlinkInPath(
+function assertNoEscapingSymlink(
   resolvedRoot: string,
   absPath: string,
   userPath: string
@@ -57,10 +79,16 @@ function assertNoSymlinkInPath(
   if (!rel || rel.startsWith("..")) return;
 
   const segments = rel.split(/[/\\]/u);
+  let verified = verifiedComponents.get(resolvedRoot);
+  if (!verified) {
+    verified = new Set();
+    verifiedComponents.set(resolvedRoot, verified);
+  }
+
   let current = resolvedRoot;
-  for (const [index, segment] of segments.entries()) {
+  for (const segment of segments) {
     current = join(current, segment);
-    if (verifiedRealDirs.has(current)) continue;
+    if (verified.has(current)) continue;
     let stat;
     try {
       stat = lstatSync(current);
@@ -70,20 +98,28 @@ function assertNoSymlinkInPath(
       return;
     }
     if (stat.isSymbolicLink()) {
-      throw new UserError(
-        index === segments.length - 1
-          ? `Path "${userPath}" is a symbolic link — access denied`
-          : `Path "${userPath}" traverses symbolic link "${segment}" — access denied`
-      );
+      let target: string;
+      try {
+        target = realpathSync(current);
+      } catch {
+        return; // Broken link — resolves to nothing, so it reaches nothing.
+      }
+      if (!isWithinRoot(realRootOf(resolvedRoot), target)) {
+        throw new UserError(
+          `Path "${userPath}" resolves outside the project through symbolic link "${segment}" — access denied`
+        );
+      }
     }
-    if (stat.isDirectory()) verifiedRealDirs.add(current);
+    verified.add(current);
   }
 }
 
 /**
- * Resolve a user-supplied path and ensure it stays within projectRoot.
- * Throws if the resolved path escapes the project boundary, is a symlink, or
- * reaches its target through a symlinked ancestor directory.
+ * Resolve a user-supplied path and ensure it stays within projectRoot, either
+ * lexically or after resolving symlinks at any component. Links resolving back
+ * inside the project are allowed.
+ *
+ * @throws {UserError} When the path escapes the project root.
  */
 export function safePath(resolvedRoot: string, userPath: string): string {
   const absPath = resolveUserPath(resolvedRoot, userPath);
@@ -92,6 +128,6 @@ export function safePath(resolvedRoot: string, userPath: string): string {
       `Path "${userPath}" escapes project root — access denied`
     );
   }
-  assertNoSymlinkInPath(resolvedRoot, absPath, userPath);
+  assertNoEscapingSymlink(resolvedRoot, absPath, userPath);
   return absPath;
 }

tests/engine/safe-path.test.ts

@@ -79,7 +79,7 @@ describe("safe-path", () => {
       );
     });
 
-    test("throws when an ANCESTOR directory is a symlink", () => {
+    test("throws when an ANCESTOR directory links OUTSIDE the project", () => {
       // The leaf is an ordinary file — only the parent is a link, which a
       // leaf-only lstat cannot see.
       const outsideDir = mkdtempSync(join(tmpdir(), "archgate-outside-"));
@@ -93,12 +93,34 @@ describe("safe-path", () => {
         return;
       }
       expect(() => safePath(tempDir, "linkdir/secret.txt")).toThrow(
-        /traverses symbolic link "linkdir" — access denied/u
+        /resolves outside the project through symbolic link "linkdir" — access denied/u
       );
       rmSync(outsideDir, { recursive: true, force: true });
     });
 
-    test("throws when the LEAF itself is a symlink", () => {
+    test("ALLOWS an ancestor directory symlink that stays inside the project", () => {
+      // The workspace-monorepo layout: apps/web/shared -> packages/shared.
+      // This escapes nothing, so refusing it would refuse to govern ordinary
+      // repositories (pnpm/npm/yarn/bun all symlink workspace packages).
+      mkdirSync(join(tempDir, "packages", "shared"), { recursive: true });
+      writeFileSync(
+        join(tempDir, "packages", "shared", "index.ts"),
+        "export {};"
+      );
+      mkdirSync(join(tempDir, "apps", "web"), { recursive: true });
+      try {
+        symlinkSync(
+          join(tempDir, "packages", "shared"),
+          join(tempDir, "apps", "web", "shared"),
+          "junction"
+        );
+      } catch {
+        return;
+      }
+      expect(() => safePath(tempDir, "apps/web/shared/index.ts")).not.toThrow();
+    });
+
+    test("throws when the LEAF links OUTSIDE the project", () => {
       const outsideDir = mkdtempSync(join(tmpdir(), "archgate-outside-"));
       writeFileSync(join(outsideDir, "secret.txt"), "sensitive");
       try {
@@ -109,7 +131,40 @@ describe("safe-path", () => {
         return;
       }
       expect(() => safePath(tempDir, "link.txt")).toThrow(
-        /is a symbolic link — access denied/u
+        /resolves outside the project through symbolic link "link.txt" — access denied/u
+      );
+      rmSync(outsideDir, { recursive: true, force: true });
+    });
+
+    test("ALLOWS a leaf symlink that stays inside the project", () => {
+      mkdirSync(join(tempDir, "real"), { recursive: true });
+      writeFileSync(join(tempDir, "real", "config.ts"), "export {};");
+      try {
+        symlinkSync(
+          join(tempDir, "real", "config.ts"),
+          join(tempDir, "config.ts")
+        );
+      } catch {
+        return;
+      }
+      expect(() => safePath(tempDir, "config.ts")).not.toThrow();
+    });
+
+    test("throws when a chain hops inside the project and then out", () => {
+      // inside-link -> real dir; real dir contains escape -> outside.
+      // Allowing the first hop must not stop the walk checking later ones.
+      const outsideDir = mkdtempSync(join(tmpdir(), "archgate-outside-"));
+      writeFileSync(join(outsideDir, "secret.txt"), "sensitive");
+      mkdirSync(join(tempDir, "real"), { recursive: true });
+      try {
+        symlinkSync(join(tempDir, "real"), join(tempDir, "hop"), "junction");
+        symlinkSync(outsideDir, join(tempDir, "real", "escape"), "junction");
+      } catch {
+        rmSync(outsideDir, { recursive: true, force: true });
+        return;
+      }
+      expect(() => safePath(tempDir, "hop/escape/secret.txt")).toThrow(
+        /resolves outside the project.*access denied/u
       );
       rmSync(outsideDir, { recursive: true, force: true });
     });