@vzn/vx 0.0.18 → 0.0.22

package/src/cache/inputs.ts

@@ -1,28 +1,50 @@
 // Resolve declared cache inputs into the concrete pieces that go into the
 // cache key:
 //   - files: absolute paths whose contents are hashed
-//   - envValues: [name, value] pairs from parent process.env
+//   - envValues: [name, value] pairs from parent process.env (value
+//     undefined for an unset name)
 //
 // `cache.inputs.env` is the cache-tracking axis for env vars; it's
 // independent of `exec.env`, which controls what reaches the child.
 //
-// File enumeration defers to git — same as Turbo and Nx. We ask git for
-// the file set via `git ls-files --cached --others --exclude-standard`,
-// which gives us:
-//   - all tracked files,
-//   - plus untracked-but-not-ignored files,
-//   - with nested .gitignore + .git/info/exclude + global excludes
-//     correctly applied (because git already does the cascade).
-// The user's `inputs.files` globs are then matched as a *filter* on
-// top of that file set. vx requires git to be installed and the
-// workspace to be a git work tree; non-git environments are not
-// supported.
+// File enumeration defers to git — same as Turbo and Nx. git-inputs.ts
+// asks for the tracked set with `git ls-files -s -v` (index OIDs and the
+// skip-worktree flag in the same spawn) and for the dirty and untracked
+// paths with `git status -uall`, with nested .gitignore, .git/info/exclude
+// and the global excludes applied because git already does the cascade.
+// The user's `inputs.files` globs are then matched as a *filter* on top
+// of that file set. vx requires git to be installed and the workspace to
+// be a git work tree; non-git environments are not supported.
 
 import path from 'node:path'
-import { existsSync } from 'node:fs'
-import { realpath, rm } from 'node:fs/promises'
+import { lstatSync, readdirSync } from 'node:fs'
+import { realpath, rm, rmdir } from 'node:fs/promises'
 import type { CacheInputs } from '../config.js'
-import { UserError } from '../util/index.js'
+import {
+  asTrees,
+  isExecutableMissing,
+  isLiteralPattern,
+  normalizeGlob,
+  taskGlob,
+  UserError,
+} from '../util/index.js'
+import { GitFilesCache, runGitLsFiles } from './git-inputs.js'
+
+// The git side lives in git-inputs.ts; its whole public surface is
+// re-exported here so a reader that reaches the resolver for it (the
+// tests do, by deep import) keeps working.
+export {
+  GitFilesCache,
+  populateGitFilesCache,
+  runGitLsFiles,
+  startGitEnumeration,
+  applyGitEnumeration,
+  gitPathspecs,
+  parseCheckAttrOutput,
+  autocrlfConverts,
+  attributeFilesOutsideTree,
+  type GitEnumeration,
+} from './git-inputs.js'
 
 // vx-lock.json is committed (so git enumerates it) but it's vx's own
 // frozen-config metadata — never a task input. Excluded globally so a
@@ -31,6 +53,17 @@ import { UserError } from '../util/index.js'
 // cache is a leaf module and must not import from workspace.)
 const ALWAYS_IGNORE = [
   '**/node_modules/**',
+  // Defense in depth, and measured as exactly that (item 497): git never
+  // reports a path under `.git`, so dropping this line changes NOTHING on
+  // any route into the input set. Probed three ways with the pattern in
+  // and out — a tracked `**/*` glob, an UNTRACKED one, and a literal
+  // `inputs.files: ['.git/HEAD']` (refused by the git-reports-it check,
+  // not by this list) — all identical, while the control in the same
+  // fixture showed an untracked ORDINARY file does enter the set. So the
+  // enumeration is the live guard and this is the backstop; every other
+  // member of this list is load-bearing and has a row that fails without
+  // it. Kept: the day an enumeration stops going through git, this is
+  // what keeps a repository's object store out of a cache key.
   '**/.git/**',
   '**/.vx/**',
   '**/*.tsbuildinfo',
@@ -47,7 +80,7 @@ const DEFAULT_FILE_GLOBS: readonly string[] = ['**/*']
 
 export interface ResolvedInputs {
   files: string[]
-  envValues: Array<[name: string, value: string]>
+  envValues: Array<[name: string, value: string | undefined]>
   runtimeValues: Array<[command: string, output: string]>
   workspaceRuntimeValues: Array<[command: string, output: string]>
 }
@@ -75,7 +108,11 @@ export interface ResolveInputsArgs {
    * Run-scoped memo for `cache.inputs.runtime` command execution, keyed
    * 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 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
+   * `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.
    */
   runtimeCache?: Map<string, Promise<string>>
   /**
@@ -83,8 +120,42 @@ export interface ResolveInputsArgs {
    * only — global dedup so a root-level probe spawns once per run.
    */
   workspaceRuntimeCache?: Map<string, Promise<string>>
+  /**
+   * Run-scoped memo for `cache.inputs.workspaceFiles`, keyed by the
+   * declaration and valid for one enumeration snapshot. A Turbo-mapped
+   * workspace gives every task the same `globalDependencies`, and
+   * resolving one literal against medusa's 24k-file enumeration per task
+   * was 930 ms of a 3.0 s warm no-op (159 scans, 2026-09-11).
+   */
+  workspaceFilesCache?: WorkspaceFilesCache
+  /** Per-run memo for `inputs.files`; see `ProjectFilesCache`. */
+  projectFilesCache?: ProjectFilesCache
 }
 
+export type WorkspaceFilesCache = Map<
+  string,
+  { snapshot: readonly string[]; result: Promise<string[]> }
+>
+
+/**
+ * Per-run memo of `cache.inputs.files` resolution, keyed by the project and
+ * the DECLARATION — tasks of one project that declare the same inputs and
+ * the same outputs resolve to the same list, and this repo's own config is
+ * the shape that pays for it: twelve shard tasks, each declaring the same
+ * whole-tree glob over the same three thousand files (measured 1.2 ms of
+ * resolution per task, 2026-09-20).
+ *
+ * Reuse is gated on the git snapshot being the SAME ARRAY the entry was
+ * built from, not on equal contents: a mid-run re-enumeration replaces it
+ * (`GitFilesCache.set`), so a task whose inputs a previous task rewrote
+ * misses the memo and walks again. Same discipline as WorkspaceFilesCache
+ * above.
+ */
+export type ProjectFilesCache = Map<
+  string,
+  { snapshot: readonly string[]; result: readonly string[] }
+>
+
 export async function resolveInputs(args: ResolveInputsArgs): Promise<ResolvedInputs> {
   const projectFiles = await resolveFiles({
     projectDir: args.projectDir,
@@ -93,6 +164,7 @@ export async function resolveInputs(args: ResolveInputsArgs): Promise<ResolvedIn
     ownOutputs: args.ownOutputs,
     nestedProjectDirs: args.nestedProjectDirs,
     ...(args.gitFilesCache !== undefined ? { gitFilesCache: args.gitFilesCache } : {}),
+    ...(args.projectFilesCache !== undefined ? { projectFilesCache: args.projectFilesCache } : {}),
   })
   let files = projectFiles
   const wsDecl = args.inputs?.workspaceFiles
@@ -102,26 +174,36 @@ export async function resolveInputs(args: ResolveInputsArgs): Promise<ResolvedIn
       workspaceFiles: wsDecl,
       ownWorkspaceOutputs: args.ownWorkspaceOutputs ?? [],
       ...(args.gitFilesCache !== undefined ? { gitFilesCache: args.gitFilesCache } : {}),
+      ...(args.workspaceFilesCache !== undefined ? { memo: args.workspaceFilesCache } : {}),
     })
     // Dedupe: when the project dir IS the workspace root (or a glob
     // overlaps), the same absolute path can arrive via both lists —
     // it must contribute to the key exactly once.
     if (wsFiles.length > 0) files = [...new Set([...projectFiles, ...wsFiles])].sort()
   }
-  const [runtimeValues, workspaceRuntimeValues] = await Promise.all([
-    resolveRuntimeValues(
-      args.inputs?.runtime ?? [],
-      args.projectDir,
-      args.runtimeCache,
-      `${args.projectDir}\0`,
-    ),
-    resolveRuntimeValues(
-      args.inputs?.workspaceRuntime ?? [],
-      args.workspaceRoot,
-      args.workspaceRuntimeCache,
-      '',
-    ),
-  ])
+  // Two awaited empty resolutions per task were ~3 ms of a 1000-task warm
+  // run (profiled 2026-09-09); a task declaring neither skips the fan-out.
+  const runtimeDecl = args.inputs?.runtime ?? []
+  const wsRuntimeDecl = args.inputs?.workspaceRuntime ?? []
+  const [runtimeValues, workspaceRuntimeValues] =
+    runtimeDecl.length === 0 && wsRuntimeDecl.length === 0
+      ? [[], []]
+      : await Promise.all([
+          resolveRuntimeValues(
+            runtimeDecl,
+            args.projectDir,
+            projectBinDirs(args.projectDir, args.workspaceRoot),
+            args.runtimeCache,
+            `${args.projectDir}\0`,
+          ),
+          resolveRuntimeValues(
+            wsRuntimeDecl,
+            args.workspaceRoot,
+            [path.join(args.workspaceRoot, 'node_modules', '.bin')],
+            args.workspaceRuntimeCache,
+            '',
+          ),
+        ])
   return {
     files,
     envValues: resolveEnvValues(args.inputs?.env ?? [], args.envSource),
@@ -146,6 +228,7 @@ async function resolveWorkspaceFiles(args: {
   workspaceFiles: readonly string[]
   ownWorkspaceOutputs: readonly string[]
   gitFilesCache?: GitFilesCache
+  memo?: WorkspaceFilesCache
 }): Promise<string[]> {
   const positive: string[] = []
   const negative: string[] = []
@@ -155,25 +238,65 @@ async function resolveWorkspaceFiles(args: {
   }
   if (positive.length === 0) return []
 
-  const excludeGlobs = [...ALWAYS_IGNORE, ...args.ownWorkspaceOutputs, ...negative].map(globFor)
-  const positiveGlobs = positive.map(globFor)
+  const excludeGlobs = [
+    ...ALWAYS_IGNORE,
+    ...asTrees(args.ownWorkspaceOutputs),
+    ...asTrees(negative),
+  ].map(globFor)
+  const positiveGlobs = asTrees(positive).map(globFor)
   // Workspace-wide partition, keyed by the workspace root. Populated
   // up-front by `populateGitFilesCache(..., workspaceWide: true)` when
   // any loaded task declares workspaceFiles; a missing/invalidated
   // partition re-spawns git at the root on demand.
   let gitFiles = args.gitFilesCache?.snapshotFor(args.workspaceRoot, positiveGlobs)
+  let undecodable = args.gitFilesCache?.undecodableNames
   if (gitFiles === undefined) {
-    gitFiles = runGitLsFiles(args.workspaceRoot).files
+    const ls = runGitLsFiles(args.workspaceRoot)
+    gitFiles = ls.files
     args.gitFilesCache?.set(args.workspaceRoot, gitFiles)
+    undecodable = noteUndecodable(args.gitFilesCache, args.workspaceRoot, ls.undecodable)
   }
+  // The memo is valid for the snapshot it was computed over: a task that
+  // wrote workspace outputs mid-run replaces the partition, and the next
+  // caller sees a different array and scans again.
+  const memoKey =
+    args.memo === undefined
+      ? undefined
+      : JSON.stringify([positive, negative, args.ownWorkspaceOutputs])
+  if (memoKey !== undefined) {
+    const hit = args.memo!.get(memoKey)
+    if (hit !== undefined && hit.snapshot === gitFiles) return hit.result
+  }
+  const result = resolveWorkspaceFilesOver(
+    args,
+    gitFiles,
+    positive,
+    positiveGlobs,
+    excludeGlobs,
+    undecodable,
+  )
+  if (memoKey !== undefined) args.memo!.set(memoKey, { snapshot: gitFiles, result })
+  return result
+}
+
+async function resolveWorkspaceFilesOver(
+  args: { workspaceRoot: string; gitFilesCache?: GitFilesCache },
+  gitFiles: readonly string[],
+  positive: readonly string[],
+  positiveGlobs: readonly Bun.Glob[],
+  excludeGlobs: readonly Bun.Glob[],
+  undecodable: ReadonlySet<string> | undefined,
+): Promise<string[]> {
   // Second call site of the literal-input guard. `resolveWorkspaceFiles`
   // carries its own copy of the filter-over-git-set design, so the same
   // silently-folds-nothing hazard exists here — and a fix applied only to the
   // project half would pass that half's tests while leaving this one live.
-  const unmatchedLiterals = new Set(positive.filter(isLiteralPath))
+  const unmatchedLiterals = new Set(
+    positive.map(normalizeGlob).filter(isLiteralPattern).map(stripTrailingSlash),
+  )
   const candidates: string[] = []
   for (const rel of gitFiles) {
-    if (unmatchedLiterals.size > 0) unmatchedLiterals.delete(rel)
+    if (unmatchedLiterals.size > 0) settleLiterals(unmatchedLiterals, rel)
     if (!positiveGlobs.some((g) => g.match(rel))) continue
     if (excludeGlobs.some((g) => g.match(rel))) continue
     candidates.push(path.resolve(args.workspaceRoot, rel))
@@ -181,41 +304,96 @@ async function resolveWorkspaceFiles(args: {
   if (unmatchedLiterals.size > 0) {
     await assertNoInvisibleLiteralInputs(unmatchedLiterals, args.workspaceRoot, 'workspaceFiles')
   }
+  refuseUndecodable(candidates, undecodable, args.workspaceRoot, 'workspaceFiles')
   // 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 exists = await Promise.all(
-    candidates.map((abs) => oids?.has(abs) === true || Bun.file(abs).exists()),
-  )
-  const matches: string[] = []
-  for (let i = 0; i < candidates.length; i++) {
-    if (exists[i]) matches.push(candidates[i]!)
+  return candidates.filter((abs) => oids?.has(abs) === true || isInputOnDisk(abs)).sort()
+}
+
+/** Anything at the path — file, directory, symlink to anything or to nothing. */
+function existsOnDisk(abs: string): boolean {
+  try {
+    lstatSync(abs)
+    return true
+  } catch {
+    return false
   }
-  return matches.sort()
+}
+
+/**
+ * What an enumerated path must be to count as an input: a regular file, or
+ * a symlink (to anything, or to nothing — its target STRING is what folds,
+ * as in git). A directory is not one: git lists a gitlink (a submodule) at
+ * its path and the glob `**\/*` matches it, and the hasher has nothing to
+ * read there. `Bun.file(p).exists()` answered false for every symlink to a
+ * directory and every dangling link too, which silently dropped a tracked
+ * link from the key — retargeting it was a stale hit. lstat, synchronously:
+ * the paths that reach this probe are the ones without a trusted index OID
+ * (untracked and dirty files), a handful on a warm run.
+ */
+function isInputOnDisk(abs: string): boolean {
+  try {
+    const st = lstatSync(abs)
+    return st.isFile() || st.isSymbolicLink()
+  } catch {
+    return false
+  }
+}
+
+/** 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')
+  const root = path.join(workspaceRoot, 'node_modules', '.bin')
+  return own === root ? [own] : [own, root]
 }
 
 function resolveEnvValues(
   names: readonly string[],
   source: NodeJS.ProcessEnv,
-): Array<[string, string]> {
-  return [...names].sort().map((name) => [name, source[name] ?? ''] as [string, string])
+): Array<[string, string | undefined]> {
+  return [...names].sort().map((name) => [name, source[name]])
 }
 
 /**
  * Run one runtime-input command via `sh -c` (so pipelines / redirects
  * 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`.
+ *
+ * Its PATH does lead with the task's own `node_modules/.bin` directories
+ * (`binDirs`), as the task's does: `tsc --version` otherwise keyed the
+ * global tsc while the task ran the workspace's, and a changed local tool
+ * replayed the old output (item 996).
  */
-async function runRuntimeCommand(command: string, cwd: string): Promise<string> {
+async function runRuntimeCommand(
+  command: string,
+  cwd: string,
+  binDirs: readonly string[],
+): Promise<string> {
+  const ambient = process.env['PATH']
+  const prefix = binDirs.join(path.delimiter)
   let proc
   try {
     proc = Bun.spawn(['sh', '-c', command], {
       cwd,
+      env: { ...process.env, PATH: ambient ? `${prefix}${path.delimiter}${ambient}` : prefix },
       stdin: 'ignore',
       stdout: 'pipe',
       stderr: 'pipe',
     })
-  } catch {
+  } catch (err) {
+    // The probe runs through `sh -c` like a task: a box without sh names
+    // the shell, not the command (item 244).
+    if (isExecutableMissing(err)) {
+      throw new UserError(
+        `cache.inputs runtime command could not run: vx runs it with sh -c and 'sh' is not on PATH (command: ${command}, cwd: ${cwd}). Install a POSIX sh and re-run.`,
+      )
+    }
     throw new UserError(`cache.inputs runtime command failed to spawn: ${command} (cwd: ${cwd})`)
   }
   const [stdout, stderr, exitCode] = await Promise.all([
@@ -245,6 +423,7 @@ async function runRuntimeCommand(command: string, cwd: string): Promise<string>
 async function resolveRuntimeValues(
   commands: readonly string[],
   cwd: string,
+  binDirs: readonly string[],
   memo: Map<string, Promise<string>> | undefined,
   memoKeyPrefix: string,
 ): Promise<Array<[string, string]>> {
@@ -255,7 +434,7 @@ async function resolveRuntimeValues(
       const key = `${memoKeyPrefix}${cmd}`
       let p = memo?.get(key)
       if (p === undefined) {
-        p = runRuntimeCommand(cmd, cwd)
+        p = runRuntimeCommand(cmd, cwd, binDirs)
         memo?.set(key, p)
       }
       return [cmd, await p] as [string, string]
@@ -263,6 +442,15 @@ async function resolveRuntimeValues(
   )
 }
 
+/**
+ * What no output glob reaches. An output is otherwise taken as written —
+ * `node_modules/**` IS an install task's output, so `ALWAYS_IGNORE` does not
+ * apply here — but these two directories no task produces, and a root
+ * project declaring `**` would otherwise wipe its repository and the cache
+ * it is restoring from (2026-09-16).
+ */
+const OUTPUT_NEVER = ['**/.git/**', '**/.vx/**']
+
 /** Resolve declared output globs (project-relative) to actual produced files. */
 export async function resolveOutputs(args: {
   projectDir: string
@@ -270,8 +458,11 @@ export async function resolveOutputs(args: {
   nestedProjectDirs: string[]
 }): Promise<string[]> {
   if (args.outputs.length === 0) return []
-  const excludeGlobs = boundaryIgnorePatterns(args.projectDir, args.nestedProjectDirs).map(globFor)
-  const scanned = [...(await scanUnion(args.outputs, excludeGlobs, args.projectDir))]
+  const excludeGlobs = [
+    ...OUTPUT_NEVER,
+    ...boundaryIgnorePatterns(args.projectDir, args.nestedProjectDirs),
+  ].map(globFor)
+  const scanned = [...(await scanUnion(asTrees(args.outputs), excludeGlobs, args.projectDir))]
   // Containment, enforced HERE and not only at the loader. `cleanOutputs`
   // DELETES whatever this returns, and `Bun.Glob.scan` happily walks `..` out
   // of its cwd — so the loader's `..`/absolute rejection alone was a single
@@ -355,12 +546,148 @@ export async function cleanOutputs(args: {
   const files = await resolveOutputs(args)
   // `force: true` makes rm tolerate ENOENT (e.g. when two output
   // globs overlap and a sibling already deleted a path mid-iteration).
-  await Promise.all(files.map((f) => rm(f, { force: true })))
+  // A symlink is unlinked, never followed.
+  await removeAll(files, args.projectDir)
+  await pruneEmptiedDirs(args.projectDir, files)
   // Project-relative posix paths of what was removed — the caller
   // feeds these to GitFilesCache.markOutputsChanged after a restore.
   return files.map((f) => path.relative(args.projectDir, f).split(path.sep).join('/'))
 }
 
+/**
+ * Remove exactly these project-relative paths — the recorded rows of an
+ * ADDITIVE task's own artifact (item 588), never a glob: the glob would
+ * take the upstream's files the task adds beside. Emptied directories are
+ * pruned as `cleanOutputs` prunes them, and stop at one the upstream still
+ * fills.
+ */
+export async function cleanOutputPaths(args: {
+  projectDir: string
+  rels: readonly string[]
+}): Promise<void> {
+  const files = args.rels.map((r) => path.resolve(args.projectDir, r))
+  await removeAll(files, args.projectDir)
+  await pruneEmptiedDirs(args.projectDir, files)
+}
+
+/** A file's identity for the additive diff: what the hit path's fingerprint trusts too. */
+export interface OutputStamp {
+  size: number
+  mtimeMs: number
+}
+
+/**
+ * The stamps of every file the declared outputs currently select — taken
+ * BEFORE an additive task runs, so what it added or changed can be told
+ * from what it found (item 588).
+ */
+export async function stampOutputs(args: {
+  projectDir: string
+  outputs: string[]
+  nestedProjectDirs: string[]
+}): Promise<Map<string, OutputStamp>> {
+  const files = await resolveOutputs(args)
+  const out = new Map<string, OutputStamp>()
+  for (const f of files) {
+    try {
+      const st = lstatSync(f)
+      out.set(f, { size: st.size, mtimeMs: st.mtimeMs })
+    } catch {
+      // Gone between the walk and the stat: not a file the task found.
+    }
+  }
+  return out
+}
+
+/**
+ * The files an additive task's run ADDED or CHANGED under its declared
+ * outputs: every selected file that was not in `before`, or whose size or
+ * mtime moved. Size + mtime is the proof the hit path already trusts for
+ * a current tree, so no new trust is introduced. A file the run rewrote
+ * with identical bytes counts as its own (the mtime moved), which is the
+ * rewrite-in-place cost the design note records.
+ */
+export async function ownOutputsSince(
+  args: { projectDir: string; outputs: string[]; nestedProjectDirs: string[] },
+  before: ReadonlyMap<string, OutputStamp>,
+): Promise<string[]> {
+  const after = await resolveOutputs(args)
+  const own: string[] = []
+  for (const f of after) {
+    const was = before.get(f)
+    if (was === undefined) {
+      own.push(f)
+      continue
+    }
+    try {
+      const st = lstatSync(f)
+      if (st.size !== was.size || st.mtimeMs !== was.mtimeMs) own.push(f)
+    } catch {
+      // Vanished since the walk: not an output.
+    }
+  }
+  return own
+}
+
+/**
+ * A declared output the process cannot remove (a `dist/` another user
+ * wrote, a read-only checkout) is the environment's failure, not vx's:
+ * the scheduler prints any other error as an "internal error", which
+ * sends the reader to file a bug against a permission bit.
+ */
+async function removeAll(files: readonly string[], root: string): Promise<void> {
+  await Promise.all(
+    files.map((f) =>
+      rm(f, { force: true }).catch((err: NodeJS.ErrnoException) => {
+        const rel = path.relative(root, f).split(path.sep).join('/')
+        throw new UserError(
+          `cannot remove declared output ${rel}: ${err.code ?? err.message} — vx clears a task's ` +
+            `declared outputs before it runs and before a restore; make the path removable ` +
+            `by this user, or stop declaring it as an output`,
+        )
+      }),
+    ),
+  )
+}
+
+/**
+ * Remove the directories a clean emptied, 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
+ * holds something — a stray the globs do not cover — stays, and the restore
+ * says so if it is in the way.
+ */
+async function pruneEmptiedDirs(root: string, removed: readonly string[]): Promise<void> {
+  const rootResolved = path.resolve(root)
+  // LEVEL ORDER, not a walk-up per directory. A parent is attempted only
+  // once every one of its children has had its turn, which is what makes
+  // "the last child empties it" work — and it costs ONE rmdir per
+  // directory rather than one per directory PER CHILD.
+  //
+  // Measured (200 dirs x 20 files, min of 7, three interleaved passes):
+  // a walk-up with a `tried` memo is 46 ms but leaves an emptied parent
+  // 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)))
+  while (level.size > 0) {
+    const parents = new Set<string>()
+    await Promise.all(
+      [...level].map(async (dir) => {
+        if (dir === rootResolved || !dir.startsWith(rootResolved + path.sep)) return
+        const gone = await rmdir(dir).then(
+          () => true,
+          (err: NodeJS.ErrnoException) => err.code === 'ENOENT',
+        )
+        if (gone) parents.add(path.dirname(dir))
+      }),
+    )
+    level = parents
+  }
+}
+
 /**
  * Resolve declared `outputs.workspaceFiles` globs (workspace-root-
  * relative) to actual produced files. Live-FS glob like
@@ -373,7 +700,7 @@ export async function resolveWorkspaceOutputs(args: {
   outputs: string[]
 }): Promise<string[]> {
   if (args.outputs.length === 0) return []
-  const scanned = [...(await scanUnion(args.outputs, [], args.workspaceRoot))]
+  const scanned = [...(await scanUnion(asTrees(args.outputs), [], args.workspaceRoot))]
   // 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`
@@ -394,182 +721,27 @@ export async function cleanWorkspaceOutputs(args: {
   outputs: string[]
 }): Promise<string[]> {
   const files = await resolveWorkspaceOutputs(args)
-  await Promise.all(files.map((f) => rm(f, { force: true })))
+  await removeAll(files, args.workspaceRoot)
+  await pruneEmptiedDirs(args.workspaceRoot, files)
   return files.map((f) => path.relative(args.workspaceRoot, f).split(path.sep).join('/'))
 }
 
-/**
- * Per-run memo of each project's `git ls-files` output, plus the
- * staleness bookkeeping that lets the warm path avoid re-spawning git.
- *
- * After a cache-hit restore we know EXACTLY which paths changed on
- * disk: the declared outputs `cleanOutputs` wiped plus the artifact's
- * output files. `markOutputsChanged` records them; `snapshotFor`
- * hands back the existing snapshot when a resolving task's input
- * globs can't match any changed path — provably identical to what a
- * re-spawn would return, since glob matching ignores gitignore status
- * entirely when the path doesn't match. When globs DO overlap,
- * returning undefined forces the caller down the re-spawn path so
- * gitignore semantics stay byte-identical.
- *
- * The cache-miss save path still uses plain `delete` — an executed
- * task may write files outside its declared outputs, and only git can
- * see those.
- */
-export class GitFilesCache extends Map<string, readonly string[]> {
-  private changed = new Map<string, string[]>()
-  /**
-   * Per-project trusted index OIDs: absolute path → git blob OID, for
-   * tracked regular files whose working-tree state matched the index
-   * at populate time (per one `git status --porcelain` snapshot).
-   * These feed `Cache.key` via `CacheKeyInput.fileHashes` so a clean
-   * tree derives input hashes with zero reads / stats / SQLite.
-   *
-   * Dropped wholesale on `set` / `delete`: a mid-run re-enumeration
-   * proves the project's tree changed, and index OIDs can't be
-   * re-trusted without a fresh status — the per-file fallback
-   * (`Cache.hashFile`) computes the identical blob OID from disk, so
-   * dropping is a pure perf concession, never a correctness one.
-   */
-  private oids = new Map<string, Map<string, string>>()
-  /**
-   * Set when `populateGitFilesCache` stored a WORKSPACE-WIDE partition
-   * (any loaded task declares `inputs.workspaceFiles`). Null when the
-   * feature is unused — every workspace-partition hook below is then a
-   * no-op, so unused-feature behavior stays byte-identical.
-   */
-  private wsRoot: string | null = null
-  /**
-   * Whether the worktree had any uncommitted changes at populate time,
-   * derived from the SAME `git status --porcelain` spawn that prunes
-   * dirty paths from the trusted-OID set. Lets the Tier-3 invocation
-   * record report `dirty` without a SECOND status spawn. `null` until
-   * populate runs, or when the status spawn failed (non-repo).
-   */
-  private dirty: boolean | null = null
-
-  setWorkspaceRoot(root: string): void {
-    this.wsRoot = root
-  }
-
-  /** Aggregate worktree dirtiness from the populate-time status spawn. */
-  get worktreeDirty(): boolean | null {
-    return this.dirty
-  }
-
-  setWorktreeDirty(dirty: boolean | null): void {
-    this.dirty = dirty
-  }
-
-  markOutputsChanged(projectDir: string, relPaths: readonly string[]): void {
-    this.recordChanged(projectDir, relPaths)
-    // The workspace-wide partition sees the same files under
-    // root-relative names; forward so a downstream workspaceFiles
-    // task can't reuse a snapshot its globs could now contradict.
-    if (this.wsRoot !== null && this.wsRoot !== projectDir) {
-      this.recordChanged(
-        this.wsRoot,
-        relPaths.map((rel) =>
-          path.relative(this.wsRoot!, path.resolve(projectDir, rel)).split(path.sep).join('/'),
-        ),
-      )
-    }
-  }
-
-  /**
-   * Record root-anchored changed paths (cleaned/restored workspace
-   * outputs) against EVERY partition that can see them: the workspace
-   * partition under their root-relative names, and any project
-   * partition whose dir contains them (workspace outputs may land
-   * inside other projects' dirs — the no-boundary escape hatch).
-   */
-  markWorkspaceOutputsChanged(workspaceRoot: string, relPaths: readonly string[]): void {
-    if (relPaths.length === 0) return
-    for (const key of this.keys()) {
-      if (key === workspaceRoot) {
-        this.recordChanged(key, relPaths)
-        continue
-      }
-      const under: string[] = []
-      for (const rel of relPaths) {
-        const abs = path.resolve(workspaceRoot, rel)
-        if (abs.startsWith(key + path.sep)) {
-          under.push(path.relative(key, abs).split(path.sep).join('/'))
-        }
-      }
-      if (under.length > 0) this.recordChanged(key, under)
-    }
-  }
-
-  /**
-   * Drop the workspace-wide partition (if one exists). Called after a
-   * cache-miss save — an executed task may have written undeclared
-   * files anywhere in its project dir, and the workspace partition
-   * spans that subtree; only a fresh enumeration can see them. No-op
-   * when the feature is unused.
-   */
-  invalidateWorkspacePartition(): void {
-    if (this.wsRoot !== null) this.delete(this.wsRoot)
-  }
-
-  private recordChanged(partitionDir: string, relPaths: readonly string[]): void {
-    if (!this.has(partitionDir)) return
-    const cur = this.changed.get(partitionDir)
-    if (cur) cur.push(...relPaths)
-    else this.changed.set(partitionDir, [...relPaths])
-    // These paths just changed on disk; their index OIDs (if any) no
-    // longer describe the working-tree content.
-    const partitionOids = this.oids.get(partitionDir)
-    if (partitionOids) {
-      for (const rel of relPaths) partitionOids.delete(path.resolve(partitionDir, rel))
-    }
-  }
-
-  /** Trusted index OIDs for a project (abs path → oid), if any survive. */
-  oidsFor(projectDir: string): ReadonlyMap<string, string> | undefined {
-    return this.oids.get(projectDir)
-  }
-
-  setOids(projectDir: string, oids: Map<string, string>): void {
-    this.oids.set(projectDir, oids)
-  }
-
-  /** Snapshot if still valid for these input globs; undefined → re-spawn. */
-  snapshotFor(projectDir: string, inputGlobs: readonly Bun.Glob[]): readonly string[] | undefined {
-    const snap = this.get(projectDir)
-    if (snap === undefined) return undefined
-    const pending = this.changed.get(projectDir)
-    if (pending !== undefined && pending.some((p) => inputGlobs.some((g) => g.match(p)))) {
-      return undefined
-    }
-    return snap
-  }
-
-  override set(key: string, value: readonly string[]): this {
-    this.changed.delete(key)
-    this.oids.delete(key)
-    return super.set(key, value)
-  }
-
-  override delete(key: string): boolean {
-    this.changed.delete(key)
-    this.oids.delete(key)
-    return super.delete(key)
-  }
+function stripTrailingSlash(p: string): string {
+  return p.replace(/\/+$/, '')
 }
 
-interface ResolveFilesArgs {
-  projectDir: string
-  workspaceRoot: string
-  files: string[] | undefined
-  ownOutputs: string[]
-  nestedProjectDirs: string[]
-  gitFilesCache?: GitFilesCache
-}
+// The literal-is-a-tree rule moved to `util/paths.ts` (item 442): it
+// decides what a clean deletes as well as what a key folds, and the
+// graph's overlapping-output refusal — which may not import `cache` —
+// has to read the same one. Re-exported here so the cache contract is
+// unchanged.
+export { asTrees } from '../util/index.js'
 
-/** No glob metacharacter — the entry names one exact path. */
-function isLiteralPath(glob: string): boolean {
-  return !/[*?[\]{}]/.test(glob)
+/** A literal is answered by the path itself or by anything under it. */
+function settleLiterals(unmatched: Set<string>, rel: string): void {
+  for (const lit of unmatched) {
+    if (rel === lit || rel.startsWith(`${lit}/`)) unmatched.delete(lit)
+  }
 }
 
 /**
@@ -593,6 +765,13 @@ function isLiteralPath(glob: string): boolean {
  * An entry that does NOT exist on disk stays silent: that is an ordinary stale
  * declaration, and refusing it would break every config that lists an
  * optional file.
+ *
+ * "Exists" is lstat, not `Bun.file(p).exists()`: that answers false for a
+ * DIRECTORY, so a literal naming a gitignored `gen/` was never judged and
+ * folded nothing in silence — the stale hit this refusal exists to stop, one
+ * directory above where it looked (item 565, fixed in 576). A literal naming
+ * an EMPTY directory is refused by the same rule, and that is right: git
+ * lists no file under it, so it folds nothing whether tracked or not.
  */
 async function assertNoInvisibleLiteralInputs(
   literals: ReadonlySet<string>,
@@ -600,7 +779,7 @@ async function assertNoInvisibleLiteralInputs(
   field: 'files' | 'workspaceFiles' = 'files',
 ): Promise<void> {
   for (const rel of literals) {
-    if (!(await Bun.file(path.resolve(base, rel)).exists())) continue
+    if (!existsOnDisk(path.resolve(base, rel))) continue
     throw new UserError(
       `cache.inputs.${field}: "${rel}" exists in ${base} but git does not report it, ` +
         `so it contributes NOTHING to the cache key — input globs filter the files git ` +
@@ -612,6 +791,54 @@ async function assertNoInvisibleLiteralInputs(
   }
 }
 
+interface ResolveFilesArgs {
+  projectDir: string
+  workspaceRoot: string
+  files: string[] | undefined
+  ownOutputs: string[]
+  nestedProjectDirs: string[]
+  gitFilesCache?: GitFilesCache
+  projectFilesCache?: ProjectFilesCache
+}
+
+/**
+ * Record the names a fresh `git ls-files` could not decode, in the run's
+ * cache when there is one, and return the set to check against.
+ */
+function noteUndecodable(
+  cache: GitFilesCache | undefined,
+  dir: string,
+  rels: readonly string[],
+): ReadonlySet<string> {
+  const abs = rels.map((rel) => path.join(dir, rel))
+  if (cache === undefined) return new Set(abs)
+  cache.markUndecodable(abs)
+  return cache.undecodableNames
+}
+
+/**
+ * An input whose name is not UTF-8 is one vx cannot open (a string cannot
+ * spell it), so it could only drop out of the key, where an edit to it is a
+ * hit. Named instead, with the way out. One git still lists after it left
+ * the disk (a tracked file deleted) drops out as any deleted file does.
+ */
+function refuseUndecodable(
+  candidates: readonly string[],
+  undecodable: ReadonlySet<string> | undefined,
+  root: string,
+  field: 'files' | 'workspaceFiles',
+): void {
+  if (undecodable === undefined || undecodable.size === 0) return
+  const bad = candidates.filter((abs) => undecodable.has(abs) && undecodableOnDisk(abs))
+  if (bad.length === 0) return
+  const names = bad.map((abs) => JSON.stringify(path.relative(root, abs).split(path.sep).join('/')))
+  throw new UserError(
+    `cache.inputs.${field} matched ${names.join(', ')} in ${root}: the name is not valid UTF-8 ` +
+      `(shown with \ufffd), and vx cannot read a file by it. Rename it, or exclude it with a ` +
+      `negated glob.`,
+  )
+}
+
 async function resolveFiles(args: ResolveFilesArgs): Promise<string[]> {
   const positive: string[] = []
   const negative: string[] = []
@@ -628,9 +855,12 @@ async function resolveFiles(args: ResolveFilesArgs): Promise<string[]> {
   if (positive.length === 0) return []
 
   const boundaryIgnores = boundaryIgnorePatterns(args.projectDir, args.nestedProjectDirs)
-  const excludeGlobs = [...ALWAYS_IGNORE, ...boundaryIgnores, ...args.ownOutputs, ...negative].map(
-    globFor,
-  )
+  const excludeGlobs = [
+    ...ALWAYS_IGNORE,
+    ...boundaryIgnores,
+    ...asTrees(args.ownOutputs),
+    ...asTrees(negative),
+  ].map(globFor)
 
   // Defer to git for the file set (Turbo / Nx parity). Nested .gitignore
   // files, .git/info/exclude, and global excludes all participate
@@ -640,17 +870,34 @@ async function resolveFiles(args: ResolveFilesArgs): Promise<string[]> {
   // per task (build + test + lint + …). Spawning git N times for the
   // same project per run is wasteful; we cache the result for the
   // duration of one orchestrator run.
-  const positiveGlobs = positive.map(globFor)
+  const positiveGlobs = asTrees(positive).map(globFor)
+  // Everything below the snapshot that decides the result: the project, what
+  // it declares, what it excludes as its own outputs, and the boundaries.
+  const memoKey = `${args.projectDir}\0${positive.join('\u0001')}\0${negative.join('\u0001')}\0${args.ownOutputs.join('\u0001')}\0${boundaryIgnores.join('\u0001')}`
   let gitFiles = args.gitFilesCache?.snapshotFor(args.projectDir, positiveGlobs)
+  let undecodable = args.gitFilesCache?.undecodableNames
+  if (gitFiles !== undefined) {
+    const memo = args.projectFilesCache?.get(memoKey)
+    // Identity, not equality: a re-enumeration hands back a new array even
+    // when the file set is unchanged, and that is exactly when this task's
+    // inputs must be walked again.
+    if (memo !== undefined && memo.snapshot === gitFiles) return [...memo.result]
+  }
   if (gitFiles === undefined) {
-    // Mid-run re-enumeration. The OIDs this spawn could yield are NOT
+    // Mid-run re-enumeration — or a project the workspace-wide populate
+    // left without a partition because the workspace's git did not see its
+    // directory (a submodule, an embedded repository); spawned in the
+    // project dir, git answers from the nested repository.
+    // The OIDs this spawn could yield are NOT
     // trusted (no fresh `git status` to vouch for them — the project's
     // 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.
-    gitFiles = runGitLsFiles(args.projectDir).files
+    const ls = runGitLsFiles(args.projectDir)
+    gitFiles = ls.files
     // set() also clears the project's pending-changed bookkeeping.
     args.gitFilesCache?.set(args.projectDir, gitFiles)
+    undecodable = noteUndecodable(args.gitFilesCache, args.projectDir, ls.undecodable)
   }
   // A LITERAL entry — one with no glob metacharacter — names exactly one file,
   // so "this matched nothing" is unambiguous. For a glob it is not: matching
@@ -663,11 +910,13 @@ async function resolveFiles(args: ResolveFilesArgs): Promise<string[]> {
   // an artifact built from an older version of a file the config explicitly
   // claims as an input. See the refusal below for why this is not simply
   // honoured instead.
-  const unmatchedLiterals = new Set(positive.filter(isLiteralPath))
+  const unmatchedLiterals = new Set(
+    positive.map(normalizeGlob).filter(isLiteralPattern).map(stripTrailingSlash),
+  )
   // First pass: glob-filter to candidate absolute paths (no I/O).
   const candidates: string[] = []
   for (const rel of gitFiles) {
-    if (unmatchedLiterals.size > 0) unmatchedLiterals.delete(rel)
+    if (unmatchedLiterals.size > 0) settleLiterals(unmatchedLiterals, rel)
     let matched = false
     for (const g of positiveGlobs) {
       if (g.match(rel)) {
@@ -682,528 +931,94 @@ async function resolveFiles(args: ResolveFilesArgs): Promise<string[]> {
   if (unmatchedLiterals.size > 0) {
     await assertNoInvisibleLiteralInputs(unmatchedLiterals, args.projectDir, 'files')
   }
-  // Second pass: parallel existence check — but ONLY for paths
-  // without a trusted index OID. A clean-per-status tracked file
-  // necessarily exists on disk, so skipping its probe keeps the warm
-  // path free of 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.
+  refuseUndecodable(candidates, undecodable, args.projectDir, 'files')
+  // Second pass: existence check — but ONLY for paths without a
+  // trusted index OID. A clean-per-status tracked file necessarily
+  // exists on disk, so skipping its probe keeps the warm path free of
+  // 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 exists = await Promise.all(
-    candidates.map((abs) => oids?.has(abs) === true || Bun.file(abs).exists()),
-  )
-  const matches: string[] = []
-  for (let i = 0; i < candidates.length; i++) {
-    if (exists[i]) matches.push(candidates[i]!)
-  }
-  return matches.sort()
-}
-
-interface GitLsResult {
-  /** cwd-relative paths — same visibility set as `--cached --others`. */
-  files: string[]
-  /**
-   * cwd-relative path → index blob OID, for tracked REGULAR files
-   * (mode 100644 / 100755) at stage 0 only. Symlinks are excluded
-   * (their OID hashes the link-target string, not the dereferenced
-   * content our fallback hasher would read); merge-conflict stages
-   * and gitlinks are excluded too. NOT yet filtered by working-tree
-   * dirtiness — callers intersect with `git status` before trusting.
-   */
-  oids: Map<string, string>
-  /** Paths flagged skip-worktree / assume-unchanged (only when `-v` was passed). */
-  flagged: Set<string>
+  const resolved = candidates.filter((abs) => oids?.has(abs) === true || isInputOnDisk(abs)).sort()
+  // Stored only on the way out: a declaration whose literal named an
+  // invisible file threw above, and every task sharing it must throw too.
+  args.projectFilesCache?.set(memoKey, { snapshot: gitFiles, result: resolved })
+  return [...resolved]
 }
 
-// `<mode> <oid> <stage>\t<path>` — the staged-entry form of
-// `ls-files -s`. `--others` paths print bare; with `-z`,
-// core.quotePath quoting is off, so a bare path containing a literal
-// tab still can't match this fixed-form prefix.
-// `ls-files -s -v`: an optional cache-state flag (`H`, `S`, `h`, …) then the
-// stage record. Both answers come from ONE spawn.
-const LS_FILES_STAGE_RE = /^(?:([A-Za-z]) )?([0-7]{6}) ([0-9a-f]{40,64}) ([0-3])\t/
-
 /**
- * Run `git ls-files -s --others --exclude-standard -z .` in `cwd`.
- * One spawn yields BOTH the file list (identical visibility to the
- * pre-v20 `--cached --others` form, verified empirically: same set
- * including staged-but-deleted files and per-stage conflict
- * duplicates) AND each tracked file's index OID — the heart of the
- * Turbo-parity "hashes come from git's index" fast path. Throws a
- * `UserError` when git is unavailable or `cwd` isn't a git work
- * tree; vx requires git. `-z` survives filenames with newlines /
- * spaces.
- */
-function runGitLsFiles(cwd: string): GitLsResult {
-  let proc
-  try {
-    proc = Bun.spawnSync({
-      cmd: ['git', 'ls-files', '-s', '--others', '--exclude-standard', '-z', '.'],
-      cwd,
-      stdout: 'pipe',
-      stderr: 'pipe',
-    })
-  } catch {
-    throw new UserError(
-      `vx requires git: failed to spawn 'git' (working dir: ${cwd}). Install git and re-run.`,
-    )
-  }
-  if (proc.exitCode !== 0) {
-    // Exit 128 = not a git work tree; other non-zero = git failure.
-    // Either way we can't enumerate inputs reliably.
-    const stderr = new TextDecoder().decode(proc.stderr).trim()
-    throw new UserError(
-      `vx requires git: ${cwd} is not inside a git work tree. ` +
-        `Run 'git init' in your workspace root.${stderr ? ` (git: ${stderr})` : ''}`,
-    )
-  }
-  return parseLsFilesOutput(new TextDecoder().decode(proc.stdout))
-}
-
-function parseLsFilesOutput(out: string): GitLsResult {
-  const files: string[] = []
-  const oids = new Map<string, string>()
-  const flagged = new Set<string>()
-  if (out.length === 0) return { files, oids, flagged }
-  // NUL-separated; trailing NUL produces an empty segment we skip.
-  for (const record of out.split('\0')) {
-    if (record.length === 0) continue
-    const m = LS_FILES_STAGE_RE.exec(record)
-    if (m === null) {
-      files.push(record) // --others entry: bare path
-      continue
-    }
-    const filePath = record.slice(m[0].length)
-    files.push(filePath)
-    const mode = m[2]!
-    const stage = m[4]!
-    if ((mode === '100644' || mode === '100755') && stage === '0') {
-      oids.set(filePath, m[3]!)
-    }
-    // A LOWERCASE letter means skip-worktree or assume-unchanged (`S` is the
-    // older spelling of skip-worktree): git has been told to stop looking at
-    // the worktree file, so its index OID says nothing about the disk.
-    const flag = m[1]
-    if (flag !== undefined && (flag === 'S' || (flag >= 'a' && flag <= 'z'))) flagged.add(filePath)
-  }
-  return { files, oids, flagged }
-}
-
-/** One completed `git` invocation. */
-interface GitRun {
-  exitCode: number
-  stdout: string
-  stderr: string
-}
-
-/**
- * Parse `git check-attr -z text eol ident` output — a flat stream of
- * `<path>\0<attr>\0<value>\0` triples — into the set of paths where a clean
- * filter can rewrite bytes. `unspecified` means no rule matched and
- * `unset` (`-text`) explicitly disables conversion; both leave the index blob
- * byte-identical to the worktree file, so those OIDs stay trusted.
- */
-export function parseCheckAttrOutput(out: string): Set<string> {
-  const affected = new Set<string>()
-  const fields = out.split('\0')
-  for (let i = 0; i + 2 < fields.length; i += 3) {
-    const value = fields[i + 2]!
-    if (value !== 'unspecified' && value !== 'unset') affected.add(fields[i]!)
-  }
-  return affected
-}
-
-/**
- * Remove from `trusted` every path whose index blob may differ from its
- * worktree bytes because a clean filter applies.
- *
- * Gated in two steps so the common case pays NOTHING. The precise answer —
- * `git ls-files --eol`, comparing `i/` to `w/` — was measured at 240 ms on a
- * 15k-file tree because it must READ every worktree file: 13x the entire
- * enumeration, on a run whose warm total is ~130 ms, and in the common Linux
- * case it finds nothing. So instead:
- *
- *  1. If `core.autocrlf` is true/input, conversion applies to every
- *     auto-detected text file with no attribute needed — trust nothing.
- *  2. Else, if no attributes source exists anywhere (no in-tree
- *     `.gitattributes`, no `$GIT_DIR/info/attributes`, no
- *     `core.attributesFile`), no rule can name a filter — return untouched,
- *     zero extra work. This is the default `git init` repo.
- *  3. Otherwise ask `git check-attr` (measured 21 ms; it resolves attributes
- *     from the index WITHOUT reading worktree content) and drop only the
- *     paths that actually carry `text`/`eol`/`ident`.
- *
- * Never throws: a probe that fails leaves the map as-is, which is exactly the
- * behaviour before this gate existed.
+ * `Bun.Glob` decodes a name that is not UTF-8 lossily, so the path it
+ * yields names no file and the output dropped out of the artifact without
+ * a word: a hit then restored a tree without it (turborepo#9345's output
+ * half). A `\ufffd` that does not stat is that case or a file that left
+ * mid-scan; `undecodableOnDisk` tells them apart.
  */
-async function dropFilteredOids(
-  trusted: Map<string, string>,
-  args: {
-    workspaceRoot: string
-    gitDir: string
-    coreConfig: string
-    spawnGit: (a: string[], stdin?: string) => Promise<GitRun | null>
-  },
-): Promise<void> {
-  if (trusted.size === 0) return
-  if (autocrlfConverts(args.coreConfig)) {
-    trusted.clear()
-    return
-  }
-  // Cheap checks first, and nothing is materialized until one of them fires —
-  // on a 15k-file repo with no attributes this whole function is a size check,
-  // a substring scan of an empty string, one stat, and a key walk that exits
-  // on the first `.gitattributes` it does not find.
-  let attributesPossible =
-    args.coreConfig.toLowerCase().includes('core.attributesfile') ||
-    (args.gitDir !== '' &&
-      existsSync(path.resolve(args.workspaceRoot, args.gitDir, 'info', 'attributes')))
-  if (!attributesPossible) {
-    for (const rel of trusted.keys()) {
-      if (rel === '.gitattributes' || rel.endsWith('/.gitattributes')) {
-        attributesPossible = true
-        break
-      }
-    }
-  }
-  if (!attributesPossible) return
-
-  const res = await args.spawnGit(
-    ['check-attr', '--stdin', '-z', 'text', 'eol', 'ident'],
-    [...trusted.keys()].join('\0'),
+function refuseUndecodableOutput(abs: string): void {
+  if (!undecodableOnDisk(abs)) return
+  throw new UserError(
+    `cache.outputs matched ${JSON.stringify(abs)}: the name is not valid UTF-8 (shown with ` +
+      `\ufffd), and vx cannot save a file by it. Rename it, or keep it out of the outputs.`,
   )
-  if (res === null || res.exitCode !== 0) return
-  for (const rel of parseCheckAttrOutput(res.stdout)) trusted.delete(rel)
-}
-
-/** `true` when git may rewrite bytes for EVERY auto-detected text file. */
-export function autocrlfConverts(coreConfig: string): boolean {
-  for (const line of coreConfig.split('\n')) {
-    const [name, value] = [line.slice(0, line.indexOf(' ')), line.slice(line.indexOf(' ') + 1)]
-    if (name.toLowerCase() === 'core.autocrlf') {
-      const v = value.trim().toLowerCase()
-      return v === 'true' || v === 'input'
-    }
-  }
-  return false
 }
 
 /**
- * Paths `git ls-files -v -z` marks as not-watched: `S` is skip-worktree, and
- * ANY lowercase letter is assume-unchanged layered on that entry's state.
- * Either way git has been told to stop comparing the worktree file, so its
- * index OID says nothing about what is — or isn't — on disk. Each
- * NUL-terminated record is `<letter><space><path>`.
+ * Is `abs` (a lossy spelling) something on disk whose name, or a
+ * directory's above it, is not UTF-8? From the deepest ancestor a string
+ * can reach, read the raw names and look for one that decodes lossily to
+ * the next segment and fatally not at all. Only a path that failed to
+ * stat reaches here, so the reads are off every warm path.
  */
-export function parseFlaggedOutput(out: string): Set<string> {
-  const flagged = new Set<string>()
-  for (const record of out.split('\0')) {
-    if (record.length < 3 || record[1] !== ' ') continue
-    const letter = record[0]!
-    if (letter === 'S' || (letter >= 'a' && letter <= 'z')) flagged.add(record.slice(2))
+function undecodableOnDisk(abs: string): boolean {
+  let dir = path.dirname(abs)
+  let next = path.basename(abs)
+  while (!existsOnDisk(dir)) {
+    const parent = path.dirname(dir)
+    if (parent === dir) return false
+    next = path.basename(dir)
+    dir = parent
   }
-  return flagged
-}
-
-function parseStatusOutput(out: string): { dirty: Set<string>; untracked: string[] } {
-  const tokens = out.split('\0')
-  const dirty = new Set<string>()
-  const untracked: string[] = []
-  for (let i = 0; i < tokens.length; i++) {
-    const token = tokens[i]!
-    if (token.length < 4) continue
-    if (token[0] === '?') {
-      untracked.push(token.slice(3))
-      continue
-    }
-    dirty.add(token.slice(3))
-    // X = R or C → the next token is the rename/copy source path.
-    const x = token[0]
-    if ((x === 'R' || x === 'C') && i + 1 < tokens.length && tokens[i + 1]!.length > 0) {
-      i++
-      dirty.add(tokens[i]!)
-    }
+  let raw: Buffer[]
+  try {
+    raw = readdirSync(dir, { encoding: 'buffer' })
+  } catch {
+    return false
   }
-  return { dirty, untracked }
-}
-
-/**
- * Strip a repo→workspace `--show-prefix` (e.g. `code/`) from each path, keeping
- * only paths inside the workspace — so a repo-root-relative set (from `git
- * status`/`diff`) is re-keyed workspace-relative to match `git ls-files`. Empty
- * prefix → returns the set unchanged (workspace root IS the git root).
- */
-function stripPrefixFromSet(paths: Set<string>, prefix: string): Set<string> {
-  if (prefix === '') return paths
-  const out = new Set<string>()
-  for (const p of paths) if (p.startsWith(prefix)) out.add(p.slice(prefix.length))
-  return out
-}
-
-/**
- * Run `git ls-files` ONCE at the workspace root, then partition the
- * result by project. Populates `cache` for every project in
- * `projectDirs` with project-relative path lists matching what a
- * per-project spawn would have produced. Throws `UserError` if the
- * workspace isn't a git work tree (vx requires git).
- *
- * Why bulk: each spawn costs ~5-10ms (fork+exec). On a 200-project
- * workspace that's 1-2s of pure overhead reclaimed.
- *
- * Files in nested-project subtrees stay in their parent's list — the
- * boundary-ignore globs in `resolveFiles` filter them out the same way
- * they did before. Cheaper to filter once-per-task than to subtract
- * here.
- *
- * v20: the same `ls-files -s` spawn also yields each tracked file's
- * index OID. A second spawn (`git status --porcelain`) prunes paths
- * whose working tree diverges from the index; what survives is
- * stored per project via `cache.setOids` and feeds `Cache.key`
- * directly — clean-tree input hashing costs zero reads/stats/SQLite.
- *
- * `workspaceWide`: set when any loaded task declares
- * `cache.inputs.workspaceFiles`. Disables pathspec scoping (those
- * globs must see every file from the root) and additionally stores a
- * workspace-wide partition keyed by `workspaceRoot` (files + trusted
- * OIDs), which `resolveWorkspaceFiles` consumes. When false, the
- * enumeration behavior — pathspecs, spawn count, stored partitions —
- * is byte-identical to the pre-workspaceFiles code.
- */
-export async function populateGitFilesCache(
-  workspaceRoot: string,
-  projectDirs: readonly string[],
-  cache: GitFilesCache,
-  workspaceWide = false,
-): Promise<void> {
-  const enumeration = await startGitEnumeration(
-    workspaceRoot,
-    gitPathspecs(workspaceRoot, projectDirs, workspaceWide),
-  )
-  applyGitEnumeration(enumeration, workspaceRoot, projectDirs, cache, workspaceWide)
-}
-
-/** What one workspace-wide enumeration learned, before it is partitioned per project. */
-export interface GitEnumeration {
-  /** Every enumerated path, workspace-relative, tracked and untracked. */
-  all: string[]
-  /** Workspace-relative path → index OID, for files whose worktree state matched the index. */
-  trusted: Map<string, string>
-  /** Whether the worktree had uncommitted changes; null when `git status` failed. */
-  dirty: boolean | null
-}
-
-/**
- * Pathspec scoping: when the run only needs a handful of projects
- * (scoped config loading), let git scan just those dirs — 75 ms →
- * 11 ms on an 11k-file repo. Above 64 dirs (or when a project IS
- * the root) the whole-tree scan wins on arg/exec overhead anyway.
- */
-export function gitPathspecs(
-  workspaceRoot: string,
-  projectDirs: readonly string[],
-  workspaceWide: boolean,
-): string[] {
-  const rels = projectDirs.map((d) => path.relative(workspaceRoot, d).split(path.sep).join('/'))
-  const scoped =
-    !workspaceWide &&
-    rels.length > 0 &&
-    rels.length <= 64 &&
-    rels.every((r) => r !== '' && r !== '.')
-  return scoped ? rels : ['.']
-}
-
-/**
- * The spawn half of `populateGitFilesCache`, separated so an UNSCOPED run
- * can start it before the configs are evaluated — the enumeration needs
- * only the pathspecs, and `['.']` is right for every unscoped run — and
- * overlap ~60 ms of git with ~80 ms of config evaluation on a
- * 1000-project tree instead of paying them back to back.
- */
-export async function startGitEnumeration(
-  workspaceRoot: string,
-  pathspecs: readonly string[],
-): Promise<GitEnumeration> {
-  // The spawns are independent — run them concurrently so the
-  // bulk-populate costs max(ls-files, status) wall time, not the sum
-  // (status alone is ~74 ms on a 1000-project tree; serial spawning
-  // was a measurable warm-path regression vs the pre-OID code).
-  const spawnGit = async (args: string[], stdin?: string): Promise<GitRun | null> => {
+  const lossy = new TextDecoder()
+  for (const name of raw) {
+    if (lossy.decode(name) !== next) continue
     try {
-      const proc = Bun.spawn({
-        cmd: ['git', ...args],
-        cwd: workspaceRoot,
-        stdin: stdin === undefined ? 'ignore' : new TextEncoder().encode(stdin),
-        stdout: 'pipe',
-        stderr: 'pipe',
-      })
-      const [stdout, stderr, exitCode] = await Promise.all([
-        new Response(proc.stdout).text(),
-        new Response(proc.stderr).text(),
-        proc.exited,
-      ])
-      return { exitCode, stdout, stderr }
+      FATAL_UTF8.decode(name)
     } catch {
-      return null
+      return true
     }
   }
-  // Four spawns, one worktree walk. `ls-files -s -v` reads the INDEX only
-  // (~9 ms on a 1000-project tree) and answers two questions at once: every
-  // tracked path's OID and its cache-state flag. `status -uall` is the one
-  // command that walks the worktree, and it answers two as well: which
-  // tracked paths are dirty AND which files are untracked. Asking
-  // `ls-files --others` for the untracked set walked the same tree a second
-  // time (~50 ms of CPU, concurrent with status but contending with it).
-  const [ls, status, prefixRes, coreCfg] = await Promise.all([
-    spawnGit(['ls-files', '-s', '-v', '-z', '--', ...pathspecs]),
-    spawnGit(['status', '--porcelain', '-z', '-uall', '--', ...pathspecs]),
-    // Two answers from one spawn. `--show-prefix` is the repo→workspace path
-    // (empty when the workspace root IS the git root): `ls-files` prints
-    // cwd(workspace)-relative paths but `status` prints repo-root-relative
-    // ones, so when the workspace root is a SUBDIR of the git repo the two
-    // disagree; this lets us key both the same way below. `--git-dir` locates
-    // `info/attributes` for the filter gate (it is not always `.git/` — a
-    // linked worktree's `.git` is a FILE pointing elsewhere).
-    spawnGit(['rev-parse', '--show-prefix', '--git-dir']),
-    // Reads three config keys, no tree scan — the gate for whether a clean
-    // filter can rewrite bytes between the index and the worktree. Exits 1
-    // when none are set, which is the common case and means "no gate".
-    spawnGit(['config', '--get-regexp', '^core\\.(autocrlf|eol|attributesfile)$']),
-  ])
-  if (ls === null) {
-    throw new UserError(
-      `vx requires git: failed to spawn 'git' (working dir: ${workspaceRoot}). Install git and re-run.`,
-    )
-  }
-  if (ls.exitCode !== 0) {
-    const stderr = ls.stderr.trim()
-    throw new UserError(
-      `vx requires git: ${workspaceRoot} is not inside a git work tree. ` +
-        `Run 'git init' in your workspace root.${stderr ? ` (git: ${stderr})` : ''}`,
-    )
-  }
-  const { files: tracked, oids, flagged } = parseLsFilesOutput(ls.stdout)
-  // Normalize `status`'s repo-root-relative paths to workspace-relative (strip
-  // the `--show-prefix`) so the dirty set is keyed identically to the trusted
-  // OID map. Without this, when the workspace root is a git subdir, a modified
-  // tracked file is never pruned from `trusted` and keeps its committed OID —
-  // a STALE cache hit serving old outputs. Empty prefix (workspace == git root,
-  // the common case) is a zero-cost no-op. Paths above the workspace can't be
-  // inputs, so they drop out of the set.
-  // One spawn, two lines: `--show-prefix` then `--git-dir`.
-  const revLines =
-    prefixRes !== null && prefixRes.exitCode === 0 ? prefixRes.stdout.split('\n') : []
-  const gitPrefix = (revLines[0] ?? '').trim()
-  const gitDir = (revLines[1] ?? '').trim()
-  const parsedStatus =
-    status !== null && status.exitCode === 0 ? parseStatusOutput(status.stdout) : null
-  const dirty = parsedStatus === null ? null : stripPrefixFromSet(parsedStatus.dirty, gitPrefix)
-  // Untracked files are inputs too (a new file is the commonest edit there
-  // is). They come from the status walk, repo-root-relative like the dirty
-  // set. Without a status answer the enumeration is the index alone.
-  const untracked =
-    parsedStatus === null ? [] : [...stripPrefixFromSet(new Set(parsedStatus.untracked), gitPrefix)]
-  const all = untracked.length === 0 ? tracked : tracked.concat(untracked)
-  // Aggregate dirtiness for the Tier-3 invocation record — derived from
-  // this same status spawn so `run()` needs no second `git status`.
-  // null when the status spawn failed (non-repo / git error).
-  const worktreeDirty = dirty === null ? null : dirty.size > 0
-  const trusted = dirty === null ? new Map<string, string>() : oids
-  if (dirty !== null) {
-    for (const rel of dirty) trusted.delete(rel)
-  }
-  // A skip-worktree / assume-unchanged path sits at stage 0 and `git status`
-  // reports nothing for it, so it would otherwise keep a trusted OID — and
-  // resolveFiles SKIPS its existence probe for OID-carrying paths. A sparse
-  // checkout would then count a file that is not on disk as an input, so
-  // materializing it later changes no key and the old artifact is replayed.
-  // Dropping the OID sends these back through the probe, where they correctly
-  // fall out of the input set while unmaterialized.
-  for (const rel of flagged) trusted.delete(rel)
-  // An index OID is only the file's content hash when git stores the worktree
-  // bytes VERBATIM. Under a clean filter (`text`/`eol`/`ident`) the blob is a
-  // DIFFERENT sequence of bytes — the LF-normalized form — while the task
-  // reads the CRLF worktree file. `git status` compares AFTER filtering, so
-  // such a file reports clean and keeps its OID: the CRLF and LF states then
-  // fold the SAME key and a real content change is invisible.
-  //
-  // Dropping an OID is not over-invalidation. It routes the path to
-  // `hashFile`, which hashes the worktree bytes — the source that was correct
-  // all along. The only cost is the read, so the gate below is about paying it
-  // ONLY where a filter can actually apply.
-  await dropFilteredOids(trusted, {
-    workspaceRoot,
-    gitDir,
-    coreConfig: coreCfg !== null && coreCfg.exitCode === 0 ? coreCfg.stdout : '',
-    spawnGit,
-  })
-  return { all, trusted, dirty: worktreeDirty }
+  return false
 }
 
-/** The partition half of `populateGitFilesCache`: store per-project slices of one enumeration. */
-export function applyGitEnumeration(
-  enumeration: GitEnumeration,
-  workspaceRoot: string,
-  projectDirs: readonly string[],
-  cache: GitFilesCache,
-  workspaceWide = false,
-): void {
-  const { all, trusted } = enumeration
-  cache.setWorktreeDirty(enumeration.dirty)
-  // Sort once, then each project's files are a contiguous range found
-  // by binary search on its `dir/` prefix — O((F+P) log F) instead of
-  // the O(P·F) per-project startsWith scan (54 ms at 1090 projects ×
-  // ~9k files; ~5 ms this way). '/' sorts below most filename chars,
-  // so the range [prefix, prefix+'\xff…') is contiguous in the sorted
-  // array; lowerBound on `prefix` and on `prefix + '￿'` bracket it.
-  const sorted = [...all].sort()
-  const lowerBound = (key: string): number => {
-    let lo = 0
-    let hi = sorted.length
-    while (lo < hi) {
-      const mid = (lo + hi) >>> 1
-      if (sorted[mid]! < key) lo = mid + 1
-      else hi = mid
-    }
-    return lo
-  }
-  for (const projectDir of projectDirs) {
-    const relPrefix = path.relative(workspaceRoot, projectDir).split(path.sep).join('/')
-    if (relPrefix === '' || relPrefix === '.') {
-      cache.set(projectDir, all)
-      const rootOids = new Map<string, string>()
-      for (const [rel, oid] of trusted) rootOids.set(path.join(workspaceRoot, rel), oid)
-      cache.setOids(projectDir, rootOids)
-      continue
-    }
-    const prefix = `${relPrefix}/`
-    const start = lowerBound(prefix)
-    const end = lowerBound(`${prefix}￿`)
-    const matches: string[] = []
-    const projOids = new Map<string, string>()
-    for (let i = start; i < end; i++) {
-      const rel = sorted[i]!
-      matches.push(rel.slice(prefix.length))
-      const oid = trusted.get(rel)
-      if (oid !== undefined) projOids.set(path.join(workspaceRoot, rel), oid)
-    }
-    // setOids AFTER set — set() drops the project's OID slot.
-    cache.set(projectDir, matches)
-    cache.setOids(projectDir, projOids)
-  }
-  if (workspaceWide) {
-    const rootOids = new Map<string, string>()
-    for (const [rel, oid] of trusted) rootOids.set(path.join(workspaceRoot, rel), oid)
-    cache.set(workspaceRoot, all)
-    cache.setOids(workspaceRoot, rootOids)
-    cache.setWorkspaceRoot(workspaceRoot)
-  }
-}
+const FATAL_UTF8 = new TextDecoder('utf-8', { fatal: true })
 
 /**
- * Union of files matching any positive pattern in `cwd`, minus files
- * matching any exclude glob (tested by Bun.Glob.match on the relative
+ * Union of the OUTPUT files matching any positive pattern in `cwd`, minus
+ * files matching any exclude glob (tested by Bun.Glob.match on the relative
  * path). Bun.Glob takes a single pattern per instance, so we iterate.
+ *
+ * Yields SYMLINKS (never followed, never descended): a task that emits
+ * `dist/out -> ../src/x` has produced an output, so the save must capture it
+ * (as its target's bytes, `planArtifact`) and the clean must remove it — a
+ * link the clean leaves standing blocks the directory a later entry restores
+ * there. Bun's `onlyFiles` walk drops every symlink, so this lists everything
+ * and sorts by `lstat`.
+ *
+ * Sync scan. The async walk was chosen on 2026-09-02, when a warm HIT globbed
+ * its outputs and the thread pool overlapped a thousand of them; the directory
+ * short-circuit took the glob off the hit path, and what is left runs on the
+ * MISS path twice per task (clean, then resolve), where the walk is CPU-bound
+ * and each async chunk costs a main-thread round trip. Measured 2026-09-09 on
+ * a 1,000-task cold run (see STATUS).
+ *
+ * A second `mode: 'files'` branch lived here until item 566, defaulted to and
+ * reached by NOTHING — both call sites pass `'outputs'`. Its `dot: true` could
+ * be deleted with the whole suite green for the plainest reason there is.
  */
 async function scanUnion(
   positive: readonly string[],
@@ -1213,13 +1028,12 @@ async function scanUnion(
   const matches = new Set<string>()
   for (const pattern of positive) {
     const glob = globFor(pattern)
-    // Async scan, deliberately: the sync walk is faster in isolation (37 µs
-    // vs 56 µs on a one-file `dist/**`) but SERIALISES on the main thread,
-    // and this runs under the scheduler's concurrency — measured 2026-09-02,
-    // switching it to scanSync made a 1000-hit warm run 40 ms SLOWER.
-    for await (const rel of glob.scan({ cwd, onlyFiles: true, dot: true })) {
+    for (const rel of glob.scanSync({ cwd, onlyFiles: false, followSymlinks: false, dot: true })) {
       if (excludeGlobs.some((g) => g.match(rel))) continue
-      matches.add(path.resolve(cwd, rel))
+      const abs = path.resolve(cwd, rel)
+      const st = lstatSync(abs, { throwIfNoEntry: false })
+      if (st !== undefined && (st.isFile() || st.isSymbolicLink())) matches.add(abs)
+      else if (st === undefined && rel.includes('\ufffd')) refuseUndecodableOutput(abs)
     }
   }
   return matches
@@ -1231,7 +1045,7 @@ async function scanUnion(
 const globMemo = new Map<string, Bun.Glob>()
 function globFor(pattern: string): Bun.Glob {
   let g = globMemo.get(pattern)
-  if (g === undefined) globMemo.set(pattern, (g = new Bun.Glob(pattern)))
+  if (g === undefined) globMemo.set(pattern, (g = taskGlob(pattern)))
   return g
 }