@vzn/vx 0.0.645 → 0.0.648

package/src/cache/inputs.ts

@@ -21,6 +21,7 @@ import { lstatSync, readdirSync, realpathSync, rmdirSync, rmSync, statSync } fro
 import { rm, rmdir } from 'node:fs/promises'
 import type { InputsConfig, TaskConfig } from '../config.js'
 import {
+  literalPath,
   anyTaskGlob,
   asTrees,
   isExecutableMissing,
@@ -31,16 +32,20 @@ import {
   outputNever,
   realpathOf,
   relPosix,
+  restorableOutput,
   shellArgv,
   slashBraceExpansions,
   braceAlternatives,
+  ESSENTIAL_ENV,
   splitNegations,
   staticPrefix,
   stripTrailingSlash,
   taskGlob,
   UserError,
+  writableUnder,
+  withoutWorkspaceBins,
 } from '../util/index.js'
-import { GitFilesCache, runGitLsFiles } from './git-inputs.js'
+import { GitFilesCache, listingEnv, runGitLsFiles } from './git-inputs.js'
 import { FILE_HASH_RACY_MS, racyWindowMs } from './layer.js'
 
 // The git side lives in git-inputs.ts; its whole public surface is
@@ -141,8 +146,8 @@ export interface ResolveInputsArgs {
    * by `projectDir + '\0' + command`. Shared across a run's tasks so a
    * project's command runs once even across build/test/lint and across
    * the hash + sandbox-baseline resolveInputs calls. The key is sound
-   * ONLY because the probe runs in vx's own ambient environment, never a
-   * task's `exec.env` (`runRuntimeCommand`): two tasks with different
+   * ONLY because every probe runs in one environment, vx's essentials,
+   * never a task's `exec.env` (`runRuntimeCommand`): two tasks with different
    * `define`s share one value. Threading the task env in would have to
    * widen this key too, or task A's probe becomes task B's key component.
    */
@@ -286,6 +291,7 @@ export async function resolveInputs(args: ResolveInputsArgs): Promise<ResolvedIn
             runtimeDecl,
             args.projectDir,
             projectBinDirs(args.projectDir, args.workspaceRoot),
+            args.workspaceRoot,
             args.runtimeCache,
             args.runtimeScope === undefined
               ? `${args.projectDir}\0`
@@ -295,6 +301,7 @@ export async function resolveInputs(args: ResolveInputsArgs): Promise<ResolvedIn
             wsRuntimeDecl,
             args.workspaceRoot,
             [path.join(args.workspaceRoot, 'node_modules', '.bin')],
+            args.workspaceRoot,
             args.workspaceRuntimeCache,
             args.runtimeScope === undefined ? '' : `\0${args.runtimeScope}\0`,
           ),
@@ -363,6 +370,7 @@ function resolveWorkspaceFiles(args: {
   // caller sees a different array and scans again.
   let isExcluded: ((rel: string) => boolean) | undefined
   let isPositive: ((rel: string) => boolean) | undefined
+  let mayHold: ((rel: string) => boolean) | undefined
   const excludedByDeclaration = (rel: string): boolean =>
     (isExcluded ??= anyTaskGlob([...WORKSPACE_ALWAYS_IGNORE, ...asTrees(negative)]))(rel)
   // A committed file stays an input whatever output reaches it (`committedFiles`).
@@ -374,11 +382,14 @@ function resolveWorkspaceFiles(args: {
     )
   const listing: InputListing = {
     root: args.workspaceRoot,
+    workspaceRoot: args.workspaceRoot,
     listed: gitFiles,
     isInput: (rel) =>
-      (isPositive ??= anyTaskGlob(asTrees(positive)))(rel) &&
+      (isPositive ??= throughLinks(positive, anyTaskGlob(asTrees(positive))))(rel) &&
       !excludedByDeclaration(rel) &&
       !own(rel),
+    linked: (rel) =>
+      (mayHold ??= mayHoldMatch(positive))(rel) && !excludedByDeclaration(rel) && !own(rel),
     nested: () => false,
     ...reachOf(positive),
   }
@@ -392,7 +403,7 @@ function resolveWorkspaceFiles(args: {
   const hit = args.memo?.get(declared)
   if (hit !== undefined && hit.snapshot === gitFiles) base = hit.result
   if (base === undefined) {
-    isPositive ??= anyTaskGlob(asTrees(positive))
+    isPositive ??= throughLinks(positive, anyTaskGlob(asTrees(positive)))
     base = resolveWorkspaceFilesOver(args, gitFiles, positive, isPositive, excludedByDeclaration)
     args.memo?.set(declared, { snapshot: gitFiles, result: base })
   }
@@ -409,12 +420,14 @@ function resolveWorkspaceFiles(args: {
     if (reach.length === 0) return kept
     // Outside the memo: an ignored file a task writes mid-run leaves the
     // snapshot as it was.
-    isPositive ??= anyTaskGlob(asTrees(positive))
+    isPositive ??= throughLinks(positive, anyTaskGlob(asTrees(positive)))
     const accept = isPositive
     const extra = ignoredInputs(
       args.workspaceRoot,
       reach,
       (rel) => accept(rel) && !excludedByDeclaration(rel) && !own(rel),
+      listing.linked,
+      args.gitFilesCache?.vxDirs,
     )
     return extra.length === 0 ? kept : mergeSorted(kept, extra)
   })
@@ -429,14 +442,18 @@ async function resolveWorkspaceFilesOver(
   excluded: (rel: string) => boolean,
 ): Promise<string[]> {
   const candidates: string[] = []
-  for (const rel of gitFiles) {
-    if (!isPositive(rel)) continue
-    if (excluded(rel)) continue
-    candidates.push(path.resolve(args.workspaceRoot, rel))
-  }
   // Same OID-trust shortcut as project files: a clean-per-status
   // tracked file necessarily exists on disk.
   const oids = args.gitFilesCache?.oidsFor(args.workspaceRoot)
+  const mayHold = mayHoldMatch(positive)
+  for (const rel of gitFiles) {
+    if (isPositive(rel)) {
+      if (!excluded(rel)) candidates.push(path.resolve(args.workspaceRoot, rel))
+    } else if (mayHold(rel) && !excluded(rel)) {
+      const abs = path.resolve(args.workspaceRoot, rel)
+      if (dirLinkInput(abs, oids)) candidates.push(abs)
+    }
+  }
   return candidates.filter((abs) => oids?.has(abs) === true || isInputOnDisk(abs)).sort()
 }
 
@@ -523,6 +540,16 @@ function isInputOnDisk(abs: string): boolean {
   }
 }
 
+/** vx's values of `ESSENTIAL_ENV`: the one environment every probe gets. */
+function probeEnv(): Record<string, string> {
+  const env: Record<string, string> = {}
+  for (const name of ESSENTIAL_ENV) {
+    const value = process.env[name]
+    if (value !== undefined) env[name] = value
+  }
+  return env
+}
+
 /** The task's `node_modules/.bin` directories, as `taskBinDirs` gives its PATH. */
 function projectBinDirs(projectDir: string, workspaceRoot: string): string[] {
   const own = path.join(projectDir, 'node_modules', '.bin')
@@ -530,6 +557,35 @@ function projectBinDirs(projectDir: string, workspaceRoot: string): string[] {
   return own === root ? [own] : [own, root]
 }
 
+/**
+ * One runtime probe answered on this machine as a key folds it: an
+ * `inputs.runtime` command run in `projectDir`, or with `workspace` a
+ * `workspaceRuntime` one run in `workspaceRoot`. For an executor that
+ * checks a task's probes where it runs it (`TaskExecutor.runtime`).
+ */
+export function answerRuntime(
+  command: string,
+  projectDir: string,
+  workspaceRoot: string,
+  workspace = false,
+): Promise<string> {
+  return workspace
+    ? runRuntimeCommand(
+        command,
+        workspaceRoot,
+        [path.join(workspaceRoot, 'node_modules', '.bin')],
+        workspaceRoot,
+        undefined,
+      )
+    : runRuntimeCommand(
+        command,
+        projectDir,
+        projectBinDirs(projectDir, workspaceRoot),
+        workspaceRoot,
+        undefined,
+      )
+}
+
 function resolveEnvValues(
   names: readonly string[],
   source: NodeJS.ProcessEnv,
@@ -542,10 +598,13 @@ function resolveEnvValues(
  * work — "shell is the API"). Returns trimmed stdout+stderr. A non-zero
  * exit is a hard UserError naming the command (fail-loud, like git).
  *
- * The probe inherits vx's AMBIENT environment on purpose — not the task's
- * `exec.env.define` / `passThrough`, which describe the command's
- * environment, not the machine's. That is what lets the run-scoped memo
- * key on (projectDir, command) alone; see `runtimeCache`.
+ * The probe sees the essential environment every task sees
+ * (`ESSENTIAL_ENV`), from vx's own — never the task's `exec.env`, which
+ * describes the command, not the machine, and never the rest of vx's: a
+ * child is dumpable after its exec, so an unsandboxed task read every
+ * secret vx holds from the probe's `/proc/<pid>/environ`. One env for
+ * every probe is what lets the run-scoped memo key on (projectDir,
+ * command) alone; see `runtimeCache`.
  *
  * Its PATH does lead with the task's own `node_modules/.bin` directories
  * (`binDirs`), as the task's does: `tsc --version` otherwise keyed the
@@ -556,9 +615,11 @@ async function runRuntimeCommand(
   command: string,
   cwd: string,
   binDirs: readonly string[],
+  workspaceRoot: string,
   owner: RuntimeMemo | undefined,
 ): Promise<string> {
-  const ambient = process.env['PATH']
+  // As a task's (exec/env.ts): no member's bin inherited from `npm run`.
+  const ambient = withoutWorkspaceBins(process.env['PATH'] ?? '', workspaceRoot)
   // As the task's PATH does (exec/env.ts): a dir holding the delimiter
   // splits into an entry relative to the probe's cwd.
   const PATH = [...binDirs.filter((dir) => !dir.includes(path.delimiter)), ambient]
@@ -571,7 +632,7 @@ async function runRuntimeCommand(
     // `node_modules/.bin`, so a dependency's `sh` bin ran every probe (J-69).
     proc = Bun.spawn(shellArgv(command), {
       cwd,
-      env: { ...process.env, PATH },
+      env: { ...probeEnv(), PATH },
       stdin: 'ignore',
       stdout: 'pipe',
       stderr: 'pipe',
@@ -707,6 +768,7 @@ async function resolveRuntimeValues(
   commands: readonly string[],
   cwd: string,
   binDirs: readonly string[],
+  workspaceRoot: string,
   memo: Map<string, Promise<string>> | undefined,
   memoKeyPrefix: string,
 ): Promise<Array<[string, string]>> {
@@ -717,7 +779,7 @@ async function resolveRuntimeValues(
       const key = `${memoKeyPrefix}${cmd}`
       let p = memo?.get(key)
       if (p === undefined) {
-        p = runRuntimeCommand(cmd, cwd, binDirs, memo)
+        p = runRuntimeCommand(cmd, cwd, binDirs, workspaceRoot, memo)
         memo?.set(key, p)
       }
       return [cmd, await p] as [string, string]
@@ -748,6 +810,21 @@ export async function resolveOutputs(args: {
   return (await scanOutputs(args)).files
 }
 
+/**
+ * Whether `resolveOutputs` takes the project-relative file `rel`, decided
+ * without the walk: a directory snapshot's file list is held to the
+ * entry's rows through it.
+ */
+export function outputWalkTakes(
+  projectDir: string,
+  outputs: readonly string[],
+  nestedProjectDirs: string[],
+): (rel: string) => boolean {
+  const restorable = restorableOutput(outputs)
+  const nested = inNestedProject(projectDir, nestedProjectDirs)
+  return (rel) => restorable(rel) && !nested(rel)
+}
+
 /**
  * `resolveOutputs`, plus the empty directories the globs match: a save
  * keeps them, so a hit leaves the tree a miss left (Turbo and Nx restore
@@ -771,7 +848,7 @@ async function scanOutputs(
   if (positive.length === 0) return { files: [] }
   const excludeGlobs = [...outputExcludes(positive, 'project'), ...asTrees(negative).map(globFor)]
   const trees = asTrees(positive)
-  refuseDirLinkedOut(args.projectDir, trees)
+  refuseDirLinkedOut(args.projectDir, trees, 'project')
   const scanned = [
     ...(await scanUnion(
       trees,
@@ -788,12 +865,13 @@ async function scanOutputs(
   // outside the project, so any future caller reaching it by another route (a
   // programmatic embedder, a config source that skips the loader) is contained
   // by construction.
-  return { files: containedIn(args.projectDir, scanned).sort() }
+  const contained = containedIn(args.projectDir, scanned)
+  return { files: outsideNested(args.nestedProjectDirs, contained).sort() }
 }
 
 /**
  * Whether git tracks a file under `dir`. No clean deletes a committed (or
- * `git add`ed) file an output glob reaches (owner, 2026-10-14: "never
+ * `git add`ed) file an output glob reaches (2026-10-14: "never
  * delete committed file"); the task may rewrite it and a restore writes the
  * bytes it left. It stays in the task's key, so those bytes follow from
  * the key. Turbo and Nx never clean an output at all.
@@ -808,16 +886,24 @@ export function committedFiles(
 /**
  * The literal head of each output glob, walked: the scan follows a link
  * there (`dist -> ../elsewhere` for `dist/**`) and only there. A link
- * below it is an output, kept as the link (`archive.ts`).
+ * below it is an output, kept as the link (`archive.ts`). One into `.git`
+ * or `.vx` is refused in either scope: for the root project and for
+ * workspace outputs those are inside, and the clean deleted the
+ * repository through `dist -> .git`. One out of a workspace output's root
+ * is left to `containedIn`.
  */
-function refuseDirLinkedOut(projectDir: string, trees: readonly string[]): void {
+function refuseDirLinkedOut(
+  root: string,
+  trees: readonly string[],
+  scope: 'project' | 'workspace',
+): void {
   let realRoot: string | undefined
   for (const tree of trees) {
-    let at = projectDir
+    let at = root
     for (const part of staticPrefix(tree).split('/')) {
       if (part === '' || part === '.') continue
       at = path.join(at, part)
-      if (!isInside(projectDir, at)) break
+      if (!isInside(root, at)) break
       let st
       try {
         st = lstatSync(at, { throwIfNoEntry: false })
@@ -833,18 +919,41 @@ function refuseDirLinkedOut(projectDir: string, trees: readonly string[]): void
       } catch {
         break
       }
-      realRoot ??= realOr(projectDir)
+      realRoot ??= realOr(root)
       if (!isInside(realRoot, real)) {
+        if (scope === 'workspace') break
         throw new UserError(
-          `${at} is a symbolic link to ${real}, outside ${projectDir} — vx never cleans, saves ` +
+          `${at} is a symbolic link to ${real}, outside ${root} — vx never cleans, saves ` +
             'or restores declared outputs through a link that leaves the project. Remove the ' +
             'link and re-run, or stop declaring outputs under it.',
         )
       }
+      if (inMetadata(real, realRoot)) {
+        throw new UserError(
+          `${at} is a symbolic link to ${real}, Git's or vx's metadata — vx never cleans, ` +
+            'saves or restores declared outputs through a link into .git or .vx. Remove the ' +
+            'link and re-run, or stop declaring outputs under it.',
+        )
+      }
     }
   }
 }
 
+/**
+ * Whether `real`, under `realRoot`, is in a `.git` there (`writableUnder`'s
+ * rule) or in its `.vx`. Asked only of where a link landed: a build's own
+ * `dist/.git/**` is an output (2026-10-17).
+ */
+function inMetadata(real: string, realRoot: string): boolean {
+  if (!writableUnder(real, realRoot)) return true
+  return (
+    real
+      .slice(realRoot.length + 1)
+      .split(path.sep, 1)[0]!
+      .toLowerCase() === '.vx'
+  )
+}
+
 function realOr(p: string): string {
   try {
     return realpathSync(p)
@@ -902,6 +1011,57 @@ function containedIn(root: string, paths: readonly string[]): string[] {
   return lexical.filter((_p, i) => contained.has(lexDirs[i]!))
 }
 
+/**
+ * `committed`, also asked by each path's real directory: the output walk
+ * follows a link at a glob's head that stays inside `root` (X-88), so
+ * `public/logo.txt` may be `static/logo.txt`, the only name git lists.
+ * Asked by the lexical name alone, an untracked `public -> static` link
+ * let the clean delete a committed file. One realpath per directory.
+ */
+function committedPastLinks(
+  root: string,
+  committed: (abs: string) => boolean,
+): (abs: string) => boolean {
+  let realRoot: string | undefined
+  const canonical = new Map<string, string | null>()
+  return (abs) => {
+    if (committed(abs)) return true
+    const dir = path.dirname(abs)
+    let canon = canonical.get(dir)
+    if (canon === undefined) {
+      const real = realOrNull(dir)
+      realRoot ??= realOrNull(root) ?? root
+      canon =
+        real === null || !isInside(realRoot, real)
+          ? null
+          : path.join(root, path.relative(realRoot, real))
+      canonical.set(dir, canon)
+    }
+    return canon !== null && canon !== dir && committed(path.join(canon, path.basename(abs)))
+  }
+}
+
+/**
+ * Drop the files whose real directory is in a nested project: a link at a
+ * glob's head that stays in the project is followed (X-88), and the
+ * lexical nested-project filter cannot see where it lands.
+ */
+function outsideNested(nestedDirs: readonly string[], files: string[]): string[] {
+  if (nestedDirs.length === 0 || files.length === 0) return files
+  const realNested = nestedDirs.map((d) => realOrNull(d) ?? d)
+  const verdict = new Map<string, boolean>()
+  return files.filter((f) => {
+    const dir = path.dirname(f)
+    let ok = verdict.get(dir)
+    if (ok === undefined) {
+      const real = realOrNull(dir) ?? dir
+      ok = !realNested.some((n) => isInside(n, real))
+      verdict.set(dir, ok)
+    }
+    return ok
+  })
+}
+
 /** Is `abs` the directory `dir` itself or something beneath it? */
 function isInside(dir: string, abs: string): boolean {
   if (abs === dir) return true
@@ -934,9 +1094,18 @@ export async function cleanOutputs(args: {
    */
   resolved?: readonly string[] | undefined
 }): Promise<string[]> {
-  const committed = args.committed ?? committedFiles(undefined, args.projectDir)
-  sweepRestoreTemps(args.projectDir, args.outputs)
-  const matched = args.resolved ?? (await resolveOutputs(args))
+  const committed = committedPastLinks(
+    args.projectDir,
+    args.committed ?? committedFiles(undefined, args.projectDir),
+  )
+  sweepRestoreTemps(args.projectDir, args.outputs, committed)
+  // An empty directory under the outputs is one too (a save keeps it): one
+  // an older build left would otherwise be saved by this run.
+  const tree =
+    args.resolved === undefined
+      ? await resolveOutputTree(args)
+      : { files: args.resolved, emptyDirs: [] }
+  const matched = tree.files
   // `force: true` makes rm tolerate ENOENT (e.g. when two output
   // globs overlap and a sibling already deleted a path mid-iteration).
   // A symlink is unlinked, never followed.
@@ -944,7 +1113,13 @@ export async function cleanOutputs(args: {
     matched.filter((f) => !committed(f)),
     args.projectDir,
   )
-  await pruneEmptiedDirs(args.projectDir, removed, pruneScope(args.projectDir, args.outputs))
+  await pruneEmptiedDirs(
+    args.projectDir,
+    removed,
+    pruneScope(args.projectDir, args.outputs),
+    undefined,
+    tree.emptyDirs,
+  )
   // Project-relative posix paths the outputs reach, for the caller's
   // GitFilesCache.markOutputsChanged: a committed one kept here is the
   // task's to rewrite or remove, so its index OID no longer vouches for it.
@@ -961,13 +1136,22 @@ export async function cleanOutputs(args: {
  * whose writer is alive, this process included, is left: it may be
  * mid-restore.
  */
-export function sweepRestoreTemps(base: string, outputs: readonly string[]): void {
+export function sweepRestoreTemps(
+  base: string,
+  outputs: readonly string[],
+  committed: (abs: string) => boolean = () => false,
+): void {
   const dirs = new Set<string>()
   for (const g of outputs) {
     if (g.startsWith('!') || !isLiteralPattern(g)) continue
     dirs.add(path.dirname(path.resolve(base, stripTrailingSlash(normalizeGlob(g)))))
   }
+  // A directory that resolves out of `base` is not the outputs': the link
+  // refusal runs after this sweep, and a delete never follows a link out.
+  let realBase: string | undefined
   for (const dir of dirs) {
+    const real = realOrNull(dir)
+    if (real === null || !isInside((realBase ??= realOrNull(base) ?? base), real)) continue
     let names: string[]
     try {
       names = readdirSync(dir)
@@ -979,6 +1163,8 @@ export function sweepRestoreTemps(base: string, outputs: readonly string[]): voi
       if (m === null) continue
       const pid = Number.parseInt(m[1]!, 36)
       if (pid === process.pid || writerAlive(pid)) continue
+      // vx never deletes a committed file, whatever its name.
+      if (committed(path.join(dir, name))) continue
       rmSync(path.join(dir, name), { force: true })
     }
   }
@@ -1029,6 +1215,8 @@ export async function cleanOutputPaths(args: {
   committed?: (abs: string) => boolean
   /** Directories the prune leaves standing even when emptied (absolute). */
   keep?: ReadonlySet<string>
+  /** Empty directories to remove too (project-relative). */
+  emptyDirs?: readonly string[]
 }): Promise<void> {
   const committed = args.committed ?? committedFiles(undefined, args.projectDir)
   const files = args.rels.map((r) => path.resolve(args.projectDir, r)).filter((f) => !committed(f))
@@ -1037,6 +1225,7 @@ export async function cleanOutputPaths(args: {
     await removeAll(files, args.projectDir),
     pruneScope(args.projectDir, args.outputs),
     args.keep,
+    args.emptyDirs?.map((r) => path.resolve(args.projectDir, r)),
   )
 }
 
@@ -1193,7 +1382,8 @@ async function removeAll(all: readonly string[], root: string): Promise<string[]
  * that skipped `dist -> real-out` left the last run's files for the next
  * entry to save (X-88). One that leaves the project is never deleted
  * through (X-5); `cleanOutputPaths` takes recorded rows, not the resolver's
- * contained set, so the check is here too.
+ * contained set, so the check is here too, and so is the one into
+ * `.git` or `.vx`.
  */
 function insideRoot(files: readonly string[], root: string): string[] {
   // Resolved only once a directory exists to compare: after a clean pruned
@@ -1208,7 +1398,14 @@ function insideRoot(files: readonly string[], root: string): string[] {
       // A directory already gone has nothing to delete through; its path
       // stays so the prune still reaches the parents it emptied.
       const r = realOrNull(dir)
-      ok = r === null || isInside((realRoot ??= realOrNull(root) ?? root), r)
+      if (r === null) ok = true
+      else {
+        realRoot ??= realOrNull(root) ?? root
+        // Where no link moved it, a `.git` is the build's own (inMetadata).
+        ok =
+          isInside(realRoot, r) &&
+          (path.relative(realRoot, r) === path.relative(root, dir) || !inMetadata(r, realRoot))
+      }
       own.set(dir, ok)
     }
     return ok
@@ -1216,11 +1413,11 @@ function insideRoot(files: readonly string[], root: string): string[] {
 }
 
 /**
- * Remove the directories a clean emptied, bottom-up, never `root` itself.
+ * Remove the directories a clean emptied, and the `emptyDirs` it found
+ * (an older build's, which a save would keep), bottom-up, never `root` itself.
  * A restore writes files where the cached entry has them; a directory left
  * standing where the entry holds a FILE of the same name (a task that once
- * wrote `dist/out/…` and now writes `dist/out`) blocks the rename, and an
- * empty directory is not an output anyone declared. A directory that still
+ * wrote `dist/out/…` and now writes `dist/out`) blocks the rename. A directory that still
  * holds something — a stray the globs do not cover — stays, and the restore
  * says so if it is in the way. With a `scope`, only a directory inside it
  * goes (`pruneScope`).
@@ -1230,6 +1427,7 @@ async function pruneEmptiedDirs(
   removed: readonly string[],
   scope?: PruneScope,
   keep?: ReadonlySet<string>,
+  emptyDirs: readonly string[] = [],
 ): Promise<void> {
   const rootResolved = path.resolve(root)
   // LEVEL ORDER, not a walk-up per directory. A parent is attempted only
@@ -1242,7 +1440,7 @@ async function pruneEmptiedDirs(
   // standing when a sibling's turn came first; the same walk-up without
   // the memo is correct and 60 ms, because every child re-attempts the
   // shared parent. This is correct at 44 ms.
-  let level = new Set(removed.map((f) => path.dirname(f)))
+  let level = new Set([...removed.map((f) => path.dirname(f)), ...emptyDirs])
   while (level.size > 0) {
     const parents = new Set<string>()
     const dirs = [...level].filter(
@@ -1294,8 +1492,10 @@ function pruneScope(base: string, outputs: readonly string[]): PruneScope {
   const scope: PruneScope = { below: [], atOrBelow: [] }
   for (const g of outputs) {
     if (g.startsWith('!')) continue
-    if (isLiteralPattern(g)) {
-      scope.atOrBelow.push(path.resolve(base, stripTrailingSlash(normalizeGlob(g))))
+    // `literalPath`, as `asTrees` reads it: an escaped `out/\[x\]` is one path.
+    const lit = literalPath(normalizeGlob(g))
+    if (lit !== null) {
+      scope.atOrBelow.push(path.resolve(base, stripTrailingSlash(lit)))
       continue
     }
     const prefix = staticPrefix(g)
@@ -1318,14 +1518,21 @@ function inScope(dir: string, scope: PruneScope): boolean {
  * with NO project-dir exclusion: workspace outputs are the documented
  * boundary escape hatch.
  */
-export async function resolveWorkspaceOutputs(args: {
-  workspaceRoot: string
-  outputs: readonly string[]
-}): Promise<string[]> {
+export async function resolveWorkspaceOutputs(
+  args: {
+    workspaceRoot: string
+    outputs: readonly string[]
+  },
+  emptyDirs?: Set<string>,
+): Promise<string[]> {
   const { positive, negative } = splitNegations(args.outputs)
   if (positive.length === 0) return []
   const excludeGlobs = [...outputExcludes(positive, 'workspace'), ...asTrees(negative).map(globFor)]
-  const scanned = [...(await scanUnion(asTrees(positive), excludeGlobs, args.workspaceRoot))]
+  const trees = asTrees(positive)
+  refuseDirLinkedOut(args.workspaceRoot, trees, 'workspace')
+  const scanned = [
+    ...(await scanUnion(trees, excludeGlobs, args.workspaceRoot, undefined, emptyDirs)),
+  ]
   // Same containment as the project twin, anchored one level out. These globs
   // deliberately ignore PROJECT boundaries — that is the escape hatch — but
   // escaping the WORKSPACE was never part of it, and `cleanWorkspaceOutputs`
@@ -1333,6 +1540,16 @@ export async function resolveWorkspaceOutputs(args: {
   return containedIn(args.workspaceRoot, scanned).sort()
 }
 
+/** `resolveOutputTree` for `outputs.workspaceFiles`: the files and the empty directories. */
+export async function resolveWorkspaceOutputTree(args: {
+  workspaceRoot: string
+  outputs: readonly string[]
+}): Promise<{ files: string[]; emptyDirs: string[] }> {
+  const emptyDirs = new Set<string>()
+  const files = await resolveWorkspaceOutputs(args, emptyDirs)
+  return { files, emptyDirs: containedIn(args.workspaceRoot, [...emptyDirs]).sort() }
+}
+
 /**
  * `cleanOutputs` for the workspace-output namespace: wipe every file
  * currently matching the declared root-relative globs. Same contract
@@ -1348,9 +1565,16 @@ export async function cleanWorkspaceOutputs(args: {
   /** `cleanOutputs`'s `resolved`, from `resolveWorkspaceOutputs`. */
   resolved?: readonly string[] | undefined
 }): Promise<string[]> {
-  const committed = args.committed ?? committedFiles(undefined, args.workspaceRoot)
-  sweepRestoreTemps(args.workspaceRoot, args.outputs)
-  const matched = args.resolved ?? (await resolveWorkspaceOutputs(args))
+  const committed = committedPastLinks(
+    args.workspaceRoot,
+    args.committed ?? committedFiles(undefined, args.workspaceRoot),
+  )
+  sweepRestoreTemps(args.workspaceRoot, args.outputs, committed)
+  const tree =
+    args.resolved === undefined
+      ? await resolveWorkspaceOutputTree(args)
+      : { files: args.resolved, emptyDirs: [] }
+  const matched = tree.files
   await pruneEmptiedDirs(
     args.workspaceRoot,
     await removeAll(
@@ -1358,6 +1582,8 @@ export async function cleanWorkspaceOutputs(args: {
       args.workspaceRoot,
     ),
     pruneScope(args.workspaceRoot, args.outputs),
+    undefined,
+    tree.emptyDirs,
   )
   return matched.map((f) => relPosix(args.workspaceRoot, f))
 }
@@ -1418,7 +1644,7 @@ function lowerBound(files: readonly string[], key: string): number {
  * The entries a declaration names outright that git answers nothing for: a
  * literal, or a glob's fixed prefix (`dist` of `dist/**`), with no listed
  * path at or under it. Such a path is gitignored or absent, and naming it
- * is asking for it (owner, 2026-10-16), so {@link ignoredInputs} reads it
+ * is asking for it (2026-10-16), so {@link ignoredInputs} reads it
  * from disk. A broad glob (`**`, or `src/**` over a listed `src`) reaches
  * no ignored file: `node_modules` is never walked.
  */
@@ -1472,20 +1698,28 @@ function outright(reach: { prefixes: readonly string[]; literals: readonly strin
  * The files on disk under the {@link ignoredReach} entries that `accept`
  * keeps, sorted and absolute. A file is hashed from disk like any untracked
  * one; nothing here is stored or restored. `node_modules` is no special
- * case (owner, 2026-10-16): an ignored path named outright is an input,
+ * case (2026-10-16): an ignored path named outright is an input,
  * a generated client (`node_modules/.prisma/client/**`) too; skipping
  * installs here folded such an entry to nothing, silently. lstat, not
  * `exists()`: that answers false for a directory. Never memoized: a
- * dependency writes these mid-run.
+ * dependency writes these mid-run. Nothing under `vxDirs` (the run's cache
+ * directory) is read: an ignored prefix over a `cache.dir` there walked the
+ * index each run writes, and the task never hit. The walk does not follow
+ * links, so a link to a directory a glob may reach below (`linked`) is an
+ * input itself, as a listed one is (`dirLinkInput`).
  */
 function ignoredInputs(
   root: string,
   reach: readonly string[],
   accept: (rel: string) => boolean,
+  linked: (rel: string) => boolean,
+  vxDirs: readonly string[] = [],
 ): string[] {
   const found = new Set<string>()
+  const vxOwn = (abs: string) => vxDirs.some((d) => abs === d || abs.startsWith(d + path.sep))
   for (const entry of reach) {
     const abs = path.resolve(root, entry)
+    if (vxOwn(abs)) continue
     const st = lstatSync(abs, { throwIfNoEntry: false })
     if (st === undefined) continue
     if (!st.isDirectory()) {
@@ -1499,9 +1733,11 @@ function ignoredInputs(
       dot: true,
     })) {
       const full = `${entry}/${rel.split(path.sep).join('/')}`
-      if (!accept(full)) continue
       const file = path.join(abs, rel)
-      if (isInputOnDisk(file)) found.add(file)
+      if (vxOwn(file)) continue
+      if (accept(full)) {
+        if (isInputOnDisk(file)) found.add(file)
+      } else if (linked(full) && dirLinkInput(file, undefined)) found.add(file)
     }
   }
   return [...found].sort()
@@ -1568,6 +1804,8 @@ interface FilesPlan {
   ownOutput: (rel: string) => boolean
   positiveGlobs: Bun.Glob[]
   isPositive: (rel: string) => boolean
+  /** Whether a positive glob may match a path under `rel` (`mayHoldMatch`). */
+  mayHold: (rel: string) => boolean
   /** The literal entries, each naming one path (see `unanswered`). */
   literals: string[]
   /** The directories a positive entry reaches; see `InputListing`. */
@@ -1580,9 +1818,9 @@ interface FilesPlan {
    */
   verdicts: Map<string, boolean>
   /**
-   * Whether a path is an input but for the task's own outputs: one git
-   * tracks stays an input (`committedFiles`), so the key sees an edit to a
-   * committed file an output glob reaches.
+   * Whether a path is under the task's own outputs, and no exclude takes it
+   * back: one git tracks is an input (`committedFiles`) whether or not a
+   * positive glob reaches it, since a hit writes the artifact's copy over it.
    */
   ownOnly: Map<string, boolean>
 }
@@ -1613,8 +1851,9 @@ function filesPlan(
       else positive.push(entry)
     }
   }
+  // Outputs alone still make a plan: a committed file under them is keyed.
   const plan =
-    positive.length === 0
+    positive.length === 0 && splitNegations(ownOutputs).positive.length === 0
       ? null
       : {
           positive,
@@ -1624,7 +1863,8 @@ function filesPlan(
           // stays an input: a tracked file under `dist` the build reads (A-44).
           ownOutput: outputMatcher(ownOutputs),
           positiveGlobs: asTrees(positive).map(globFor),
-          isPositive: anyTaskGlob(asTrees(positive)),
+          isPositive: throughLinks(positive, anyTaskGlob(asTrees(positive))),
+          mayHold: mayHoldMatch(positive),
           ...reachOf(positive),
           verdicts: new Map<string, boolean>(),
           ownOnly: new Map<string, boolean>(),
@@ -1633,17 +1873,88 @@ function filesPlan(
   return plan
 }
 
+/**
+ * `isPositive`, and each path a glob's static directory passes through:
+ * git lists a linked directory as one path, the link, so `lib/**` over
+ * `lib -> ../shared` matched nothing, and an edit behind it kept the key
+ * the task's last bytes were saved under (2026-10-25). The link is then
+ * an input, and its key includes every file behind it.
+ */
+function throughLinks(
+  positive: readonly string[],
+  isPositive: (rel: string) => boolean,
+): (rel: string) => boolean {
+  const through = new Set<string>()
+  // Each brace alternative by its own prefix: whole, `{lib,src}/**` has
+  // none, and a file behind `lib -> ../shared` was no input.
+  for (const g of positive.flatMap(braceAlternatives)) {
+    const prefix = staticPrefix(g)
+    if (prefix === '.' || prefix === '' || path.isAbsolute(prefix)) continue
+    const parts = prefix.split('/')
+    for (let i = 1; i <= parts.length; i++) through.add(parts.slice(0, i).join('/'))
+  }
+  return through.size === 0 ? isPositive : (rel) => isPositive(rel) || through.has(rel)
+}
+
+/**
+ * Whether a positive glob may match a path under `rel`, by each
+ * alternative's fixed prefix and depth (a `**` reaches any depth). A link
+ * below a glob's fixed prefix is listed as one path too: `src/**\/*.txt`
+ * over `src/v -> ../shared` matched the link's name, not what the task
+ * read through it, and an edit there was a hit (2026-10-28). Such a path
+ * that is a link to a directory is an input (`dirLinkInput`). Generous on
+ * purpose: a wrong yes costs one lookup, and folds a linked directory.
+ */
+function mayHoldMatch(positive: readonly string[]): (rel: string) => boolean {
+  const reach = asTrees(positive.flatMap(braceAlternatives)).map((g) => {
+    const prefix = staticPrefix(g)
+    return {
+      prefix: prefix === '.' ? '' : `${prefix}/`,
+      deep: g.includes('**'),
+      depth: g.split('/').length,
+    }
+  })
+  return (rel) => {
+    let depth: number | undefined
+    for (const r of reach) {
+      if (!rel.startsWith(r.prefix) || rel.length === r.prefix.length) continue
+      if (r.deep || (depth ??= rel.split('/').length) < r.depth) return true
+    }
+    return false
+  }
+}
+
+/**
+ * Whether `abs`, a path a glob may reach below, is a link to a directory.
+ * A trusted index OID answers for a tracked file with no syscall: only a
+ * link's (`120000:`) or an untracked path's is looked at.
+ */
+function dirLinkInput(abs: string, oids: ReadonlyMap<string, string> | undefined): boolean {
+  const oid = oids?.get(abs)
+  if (oid !== undefined && !oid.startsWith('120000:')) return false
+  try {
+    return lstatSync(abs).isSymbolicLink() && statSync(abs).isDirectory()
+  } catch {
+    return false
+  }
+}
+
 /**
  * Whether a changed path is one of a task's declared file inputs:
  * `projectRel` (the path relative to the project that owns it) against
  * `files`, `workspaceRel` (relative to the workspace root) against
  * `workspaceFiles`; null skips that half, by the globs and `!` exclusions (a path under
- * the task's own outputs counts: a committed one is keyed). `--affected` seeds a task with it (owner, 2026-10-04).
+ * the task's own outputs counts: a committed one is keyed). `--affected` seeds a task with it (2026-10-04).
  */
 export function declaresInput(
   task: TaskConfig,
   projectRel: string | null,
   workspaceRel: string | null,
+  /**
+   * The path is a link to a directory (or was one): a glob that may reach
+   * below it keys what is behind it, as `mayHoldMatch` says at key time.
+   */
+  dirLink = false,
 ): boolean {
   const inputs = task.inputs
   if (inputs === undefined) return false
@@ -1653,10 +1964,13 @@ export function declaresInput(
     // lists: either way it may be an input, so it counts.
     const plan = filesPlan(inputs.files, task.cache?.outputs.files ?? [])
     if (plan !== null && (inPlan(plan, projectRel) || ownOnly(plan, projectRel))) return true
+    if (plan !== null && dirLink && plan.mayHold(projectRel) && !plan.isExcluded(projectRel)) {
+      return true
+    }
   }
   const ws = inputs.workspaceFiles
   if (workspaceRel === null || ws === undefined || ws.length === 0) return false
-  return workspaceMatcher(ws)(workspaceRel)
+  return workspaceMatcher(ws)(workspaceRel, dirLink)
 }
 
 /**
@@ -1700,22 +2014,23 @@ function inPlan(plan: FilesPlan, rel: string): boolean {
 function ownOnly(plan: FilesPlan, rel: string): boolean {
   let own = plan.ownOnly.get(rel)
   if (own === undefined) {
-    own = plan.ownOutput(rel) && plan.isPositive(rel) && !plan.isExcluded(rel)
+    own = plan.ownOutput(rel) && !plan.isExcluded(rel)
     plan.ownOnly.set(rel, own)
   }
   return own
 }
 
-const workspaceMatchers = new Map<string, (rel: string) => boolean>()
+const workspaceMatchers = new Map<string, (rel: string, dirLink: boolean) => boolean>()
 
-function workspaceMatcher(decl: readonly string[]): (rel: string) => boolean {
+function workspaceMatcher(decl: readonly string[]): (rel: string, dirLink: boolean) => boolean {
   const key = JSON.stringify(decl)
   let m = workspaceMatchers.get(key)
   if (m !== undefined) return m
   const { positive, negative } = splitNegations(decl)
-  const isPositive = anyTaskGlob(asTrees(positive))
+  const isPositive = throughLinks(positive, anyTaskGlob(asTrees(positive)))
+  const mayHold = mayHoldMatch(positive)
   const isExcluded = anyTaskGlob([...WORKSPACE_ALWAYS_IGNORE, ...asTrees(negative)])
-  m = (rel) => isPositive(rel) && !isExcluded(rel)
+  m = (rel, dirLink) => (isPositive(rel) || (dirLink && mayHold(rel))) && !isExcluded(rel)
   workspaceMatchers.set(key, m)
   return m
 }
@@ -1764,6 +2079,7 @@ async function resolveFiles(
           plan,
           nested,
           ownWsOutput,
+          args.gitFilesCache,
         ),
         listing: listingFor(args, gitFiles, plan, nested, ownWsOutput),
       }
@@ -1779,7 +2095,7 @@ async function resolveFiles(
     // tree just changed); set() drops the project's OID slot and these
     // files fall back to Cache.hashFile, which computes the identical
     // blob OID from disk.
-    const ls = runGitLsFiles(args.projectDir)
+    const ls = runGitLsFiles(args.projectDir, listingEnv(args.projectDir, args.workspaceRoot))
     gitFiles = ls.files
     // set() also clears the project's pending-changed bookkeeping.
     args.gitFilesCache?.set(args.projectDir, gitFiles)
@@ -1811,14 +2127,21 @@ async function resolveFiles(
   const candidates: string[] = []
   const verdicts = plan.verdicts
   const committed = committedFiles(args.gitFilesCache, args.projectDir)
+  const oids = args.gitFilesCache?.oidsFor(args.projectDir)
   for (const rel of gitFiles) {
     let input = verdicts.get(rel)
     if (input === undefined) {
       input = isPositive(rel) && !isExcluded(rel) && !ownOutput(rel)
       verdicts.set(rel, input)
     }
-    if ((!input && !ownOnly(plan, rel)) || nested(rel) || ownWsOutput(rel)) continue
+    if (nested(rel) || ownWsOutput(rel)) continue
     const abs = base === undefined ? path.resolve(args.projectDir, rel) : base + rel
+    if (!input && !ownOnly(plan, rel)) {
+      if (plan.mayHold(rel) && !isExcluded(rel) && !ownOutput(rel) && dirLinkInput(abs, oids)) {
+        candidates.push(abs)
+      }
+      continue
+    }
     if (!input && !committed(abs)) continue
     candidates.push(abs)
   }
@@ -1830,7 +2153,6 @@ async function resolveFiles(
   // per-file syscalls. Paths without an OID keep the probe:
   // `git ls-files -s` can surface staged entries whose working-tree
   // file is gone; the hasher would otherwise throw ENOENT.
-  const oids = args.gitFilesCache?.oidsFor(args.projectDir)
   const resolved = candidates.filter((abs) => oids?.has(abs) === true || isInputOnDisk(abs))
   // Git's slice comes sorted and a common prefix keeps it so: one pass
   // proves it instead of a sort per task.
@@ -1842,7 +2164,15 @@ async function resolveFiles(
   }
   args.projectFilesCache?.set(memoKey, { snapshot: gitFiles, result: resolved })
   return {
-    files: withIgnored(args.projectDir, resolved, reach, plan, nested, ownWsOutput),
+    files: withIgnored(
+      args.projectDir,
+      resolved,
+      reach,
+      plan,
+      nested,
+      ownWsOutput,
+      args.gitFilesCache,
+    ),
     listing: listingFor(args, gitFiles, plan, nested, ownWsOutput),
   }
 }
@@ -1855,18 +2185,26 @@ function withIgnored(
   plan: FilesPlan,
   nested: (rel: string) => boolean,
   ownWsOutput: (rel: string) => boolean,
+  cache: GitFilesCache | undefined,
 ): string[] {
   if (reach.length === 0) return [...resolved]
   const extra = ignoredInputs(
     projectDir,
     reach,
     (rel) => inPlan(plan, rel) && !nested(rel) && !ownWsOutput(rel),
+    (rel) =>
+      plan.mayHold(rel) &&
+      !plan.isExcluded(rel) &&
+      !plan.ownOutput(rel) &&
+      !nested(rel) &&
+      !ownWsOutput(rel),
+    cache?.vxDirs,
   )
   return extra.length === 0 ? [...resolved] : mergeSorted(resolved, extra)
 }
 
 function listingFor(
-  args: { projectDir: string; gitFilesCache?: GitFilesCache | undefined },
+  args: { projectDir: string; workspaceRoot: string; gitFilesCache?: GitFilesCache | undefined },
   listed: readonly string[],
   plan: FilesPlan,
   nested: (rel: string) => boolean,
@@ -1876,12 +2214,15 @@ function listingFor(
   let committed: ((abs: string) => boolean) | undefined
   return {
     root,
+    workspaceRoot: args.workspaceRoot,
     listed,
     isInput: (rel) =>
       (inPlan(plan, rel) ||
         (ownOnly(plan, rel) &&
           (committed ??= committedFiles(args.gitFilesCache, root))(path.join(root, rel)))) &&
       !ownWsOutput(rel),
+    linked: (rel) =>
+      plan.mayHold(rel) && !plan.isExcluded(rel) && !plan.ownOutput(rel) && !ownWsOutput(rel),
     nested,
     prefixes: plan.prefixes,
     literals: plan.literals,
@@ -1943,9 +2284,16 @@ function undecodableOnDisk(abs: string): boolean {
  */
 export interface InputListing {
   root: string
+  /** Where git's location variables point; `root` in a repository below it is listed without them. */
+  workspaceRoot: string
   /** Root-relative paths, as git listed them. */
   listed: readonly string[]
   isInput: (rel: string) => boolean
+  /**
+   * Whether a link to a directory at `rel` is an input: a glob may match
+   * below it (`mayHoldMatch`), though its name fits none (`dirLinkInput`).
+   */
+  linked: (rel: string) => boolean
   nested: (rel: string) => boolean
   /** Root-relative directories a positive entry reaches, `''` for the root. */
   prefixes: readonly string[]
@@ -2051,7 +2399,10 @@ function addedTo(
         if (known.has(rel) || e.name === 'node_modules' || l.nested(`${rel}/`)) continue
         if (reaches(l.prefixes, rel)) candidates.push(rel)
       } else if (
-        l.isInput(rel) &&
+        (l.isInput(rel) ||
+          (e.isSymbolicLink() &&
+            l.linked(rel) &&
+            dirLinkInput(path.resolve(abs, e.name), undefined))) &&
         !l.nested(rel) &&
         !isInstalledPath(rel) &&
         !keyFiles.has(path.resolve(abs, e.name))
@@ -2061,10 +2412,11 @@ function addedTo(
     }
   }
   if (candidates.length === 0) return undefined
-  for (const rel of runGitLsFiles(l.root).files) {
+  for (const rel of runGitLsFiles(l.root, listingEnv(l.root, l.workspaceRoot)).files) {
     if (!candidates.some((c) => c === '' || rel === c || rel.startsWith(`${c}/`))) continue
-    if (isInstalledPath(rel) || l.nested(rel) || !l.isInput(rel)) continue
+    if (isInstalledPath(rel) || l.nested(rel)) continue
     const abs = path.resolve(l.root, rel)
+    if (!l.isInput(rel) && !(l.linked(rel) && dirLinkInput(abs, undefined))) continue
     if (!keyFiles.has(abs) && isInputOnDisk(abs)) return abs
   }
   return undefined
@@ -2103,25 +2455,103 @@ async function scanUnion(
   emptyDirs?: Set<string>,
 ): Promise<Set<string>> {
   const matches = new Set<string>()
+  const links: string[] = []
+  const take = (rel: string): void => {
+    if (nested(rel) || excludeGlobs.some((g) => g.match(rel))) return
+    const abs = path.resolve(cwd, rel)
+    const st = lstatSync(abs, { throwIfNoEntry: false })
+    if (st !== undefined && (st.isFile() || st.isSymbolicLink())) {
+      matches.add(abs)
+      if (st.isSymbolicLink()) links.push(abs)
+    } else if (emptyDirs !== undefined && st?.isDirectory() === true) {
+      if (readdirSync(abs).length === 0) emptyDirs.add(abs)
+    } else if (st === undefined && rel.includes('\ufffd')) refuseUndecodableOutput(abs)
+  }
+  const opts = { cwd, onlyFiles: false, followSymlinks: false, dot: true }
   // `Bun.Glob`'s scan finds nothing for a brace whose alternatives hold a
   // `/`: `{dist,lib/esm}/**` saved an empty artifact, and a hit restored
   // nothing over a cleaned tree (A-10). Expanded here, as discovery does.
-  for (const pattern of positive.flatMap(slashBraceExpansions)) {
+  const patterns = positive.flatMap(slashBraceExpansions)
+  // A leading `**` walks the whole project whatever else is listed, so the
+  // list is one walk: Turbo's `dist/**`, `**/dist/**`, `**/dist` was three,
+  // ~2 ms of a warm hit on solid.
+  // Not where a static head passes through a link: the one walk does not
+  // follow links, and the per-pattern scan enters them (X-88).
+  if (
+    patterns.length > 1 &&
+    patterns.some((p) => p.startsWith('**')) &&
+    !patterns.some((p) => headLinked(cwd, p))
+  ) {
+    const any = anyTaskGlob(patterns)
+    for (const rel of WHOLE_TREE.scanSync(opts)) if (any(rel)) take(rel)
+    return matches
+  }
+  for (const pattern of patterns) {
     if (absentPrefix(cwd, pattern)) continue
-    const glob = globFor(pattern)
-    for (const rel of glob.scanSync({ cwd, onlyFiles: false, followSymlinks: false, dot: true })) {
-      if (nested(rel) || excludeGlobs.some((g) => g.match(rel))) continue
-      const abs = path.resolve(cwd, rel)
-      const st = lstatSync(abs, { throwIfNoEntry: false })
-      if (st !== undefined && (st.isFile() || st.isSymbolicLink())) matches.add(abs)
-      else if (emptyDirs !== undefined && st?.isDirectory() === true) {
-        if (readdirSync(abs).length === 0) emptyDirs.add(abs)
-      } else if (st === undefined && rel.includes('\ufffd')) refuseUndecodableOutput(abs)
+    const from = scanRoot(cwd, pattern)
+    if (from === null) continue
+    if (from === undefined) for (const rel of globFor(pattern).scanSync(opts)) take(rel)
+    else
+      for (const rel of globFor(from.rest).scanSync({ ...opts, cwd: from.dir }))
+        take(`${from.prefix}/${rel}`)
+  }
+  // A literal names the path and its tree (`dist`, `dist/**`), and a tree
+  // whose head is a directory link is walked through it: the link and the
+  // files under it were one artifact holding `dist` as a file and a
+  // directory, refused, so the task never cached. The walk is the output.
+  if (links.length > 0) {
+    const sorted = [...matches].sort()
+    for (const link of links) {
+      const under = `${link}/`
+      const at = sorted.findIndex((m) => m >= under)
+      if (at !== -1 && sorted[at]!.startsWith(under)) matches.delete(link)
     }
   }
   return matches
 }
 
+/** `pattern`'s static directory passes through a symlink under `cwd`. */
+function headLinked(cwd: string, pattern: string): boolean {
+  const prefix = staticPrefix(pattern)
+  if (prefix === '.' || path.isAbsolute(prefix)) return false
+  let at = cwd
+  for (const part of prefix.split('/')) {
+    at = path.join(at, part)
+    const st = lstatSync(at, { throwIfNoEntry: false })
+    if (st === undefined || !st.isDirectory()) return st?.isSymbolicLink() === true
+  }
+  return false
+}
+
+/**
+ * Where `pattern`'s scan can start: its static directory, with the rest of
+ * the pattern to match there. `Bun.Glob` walks the whole of `cwd` whatever
+ * the prefix: `out/d1/**` beside 9000 sibling dirs cost 2.3 ms a scan, twice
+ * per miss (2026-10-25). Null when the prefix is a file, which nothing lies
+ * under (a literal's `<file>/**` tree). Undefined (scan from `cwd`) for no
+ * prefix, an escape, or a prefix that does not stat (a dangling link, a
+ * cycle), whose refusals the walk from `cwd` names. A prefix through a
+ * link is entered either way.
+ */
+function scanRoot(
+  cwd: string,
+  pattern: string,
+): { prefix: string; rest: string; dir: string } | null | undefined {
+  const prefix = staticPrefix(pattern)
+  if (prefix === '.' || prefix.includes('\\') || path.isAbsolute(prefix)) return undefined
+  if (!pattern.startsWith(`${prefix}/`) || prefix.split('/').includes('..')) return undefined
+  const dir = path.join(cwd, prefix)
+  let st
+  try {
+    st = statSync(dir, { throwIfNoEntry: false })
+  } catch {
+    return undefined
+  }
+  if (st === undefined) return undefined
+  if (!st.isDirectory()) return null
+  return { prefix, rest: pattern.slice(prefix.length + 1), dir }
+}
+
 /**
  * True when `pattern`'s static directory is not on disk, so nothing can
  * match under it. A restore into a tree without its outputs scans each
@@ -2139,6 +2569,8 @@ function absentPrefix(cwd: string, pattern: string): boolean {
   }
 }
 
+const WHOLE_TREE = new Bun.Glob('**')
+
 // Compiled once per pattern string for the life of the process: a `Bun.Glob`
 // is immutable, and the same handful of declared globs are compiled again
 // for every task otherwise (three sites, up to thousands of times per run).