@vzn/vx 0.0.21 → 0.0.23

package/src/cache/inputs.ts

@@ -1,7 +1,8 @@
 // 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.
@@ -16,12 +17,18 @@
 // be a git work tree; non-git environments are not supported.
 
 import path from 'node:path'
-import { lstatSync } from 'node:fs'
+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'
-import { normalizeGlob } from '../util/index.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
@@ -35,6 +42,7 @@ export {
   gitPathspecs,
   parseCheckAttrOutput,
   autocrlfConverts,
+  attributeFilesOutsideTree,
   type GitEnumeration,
 } from './git-inputs.js'
 
@@ -45,6 +53,17 @@ export {
 // 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',
@@ -61,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]>
 }
@@ -109,6 +128,8 @@ export interface ResolveInputsArgs {
    * 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<
@@ -116,6 +137,25 @@ export type WorkspaceFilesCache = Map<
   { 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,
@@ -124,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
@@ -151,10 +192,17 @@ export async function resolveInputs(args: ResolveInputsArgs): Promise<ResolvedIn
           resolveRuntimeValues(
             runtimeDecl,
             args.projectDir,
+            projectBinDirs(args.projectDir, args.workspaceRoot),
             args.runtimeCache,
             `${args.projectDir}\0`,
           ),
-          resolveRuntimeValues(wsRuntimeDecl, args.workspaceRoot, args.workspaceRuntimeCache, ''),
+          resolveRuntimeValues(
+            wsRuntimeDecl,
+            args.workspaceRoot,
+            [path.join(args.workspaceRoot, 'node_modules', '.bin')],
+            args.workspaceRuntimeCache,
+            '',
+          ),
         ])
   return {
     files,
@@ -201,9 +249,12 @@ async function resolveWorkspaceFiles(args: {
   // 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
@@ -216,7 +267,14 @@ async function resolveWorkspaceFiles(args: {
     const hit = args.memo!.get(memoKey)
     if (hit !== undefined && hit.snapshot === gitFiles) return hit.result
   }
-  const result = resolveWorkspaceFilesOver(args, gitFiles, positive, positiveGlobs, excludeGlobs)
+  const result = resolveWorkspaceFilesOver(
+    args,
+    gitFiles,
+    positive,
+    positiveGlobs,
+    excludeGlobs,
+    undecodable,
+  )
   if (memoKey !== undefined) args.memo!.set(memoKey, { snapshot: gitFiles, result })
   return result
 }
@@ -227,13 +285,14 @@ async function resolveWorkspaceFilesOver(
   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.map(normalizeGlob).filter(isLiteralPath).map(stripTrailingSlash),
+    positive.map(normalizeGlob).filter(isLiteralPattern).map(stripTrailingSlash),
   )
   const candidates: string[] = []
   for (const rel of gitFiles) {
@@ -245,12 +304,23 @@ async function resolveWorkspaceFilesOver(
   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)
   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
+  }
+}
+
 /**
  * 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,
@@ -271,11 +341,18 @@ function isInputOnDisk(abs: string): boolean {
   }
 }
 
+/** 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]])
 }
 
 /**
@@ -287,17 +364,36 @@ function resolveEnvValues(
  * `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([
@@ -327,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]>> {
@@ -337,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]
@@ -345,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
@@ -352,10 +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(asTrees(args.outputs), excludeGlobs, args.projectDir, 'outputs')),
-  ]
+  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
@@ -440,13 +547,109 @@ export async function cleanOutputs(args: {
   // `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.
-  await Promise.all(files.map((f) => rm(f, { force: true })))
+  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
@@ -458,21 +661,30 @@ export async function cleanOutputs(args: {
  */
 async function pruneEmptiedDirs(root: string, removed: readonly string[]): Promise<void> {
   const rootResolved = path.resolve(root)
-  const tried = new Set<string>()
-  // Deepest first, so a parent is attempted after every child had its turn.
-  const dirs = [...new Set(removed.map((f) => path.dirname(f)))].sort(
-    (a, b) => b.split(path.sep).length - a.split(path.sep).length,
-  )
-  for (let dir of dirs) {
-    while (dir !== rootResolved && dir.startsWith(rootResolved + path.sep) && !tried.has(dir)) {
-      tried.add(dir)
-      const gone = await rmdir(dir).then(
-        () => true,
-        (err: NodeJS.ErrnoException) => err.code === 'ENOENT',
-      )
-      if (!gone) break
-      dir = path.dirname(dir)
-    }
+  // 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
   }
 }
 
@@ -488,7 +700,7 @@ export async function resolveWorkspaceOutputs(args: {
   outputs: string[]
 }): Promise<string[]> {
   if (args.outputs.length === 0) return []
-  const scanned = [...(await scanUnion(asTrees(args.outputs), [], args.workspaceRoot, 'outputs'))]
+  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`
@@ -509,43 +721,21 @@ 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('/'))
 }
 
-function isLiteralPath(glob: string): boolean {
-  return !/[*?[\]{}]/.test(glob)
-}
-
 function stripTrailingSlash(p: string): string {
   return p.replace(/\/+$/, '')
 }
 
-/**
- * A literal entry names a file OR a directory tree: `src/` and `src` both
- * mean everything under `src`, as they do in Turbo and every `.gitignore`.
- * A glob matcher sees only the literal path, so `['src/']` folded ZERO
- * files — a key that never moves with its source, and the most common
- * turbo.json shape (`"outputs": ["dist"]`) captured nothing. Every
- * literal therefore compiles to itself plus its subtree; a literal that
- * names a file still matches exactly that file, since `x/**` matches
- * nothing under a file.
- */
-export function asTrees(patterns: readonly string[]): string[] {
-  const out: string[] = []
-  for (const raw of patterns) {
-    const p = normalizeGlob(raw)
-    if (!isLiteralPath(p)) {
-      out.push(p)
-      continue
-    }
-    const lit = stripTrailingSlash(p)
-    if (lit.length === 0) continue
-    out.push(lit, `${lit}/**`)
-  }
-  return out
-}
+// 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'
 
 /** A literal is answered by the path itself or by anything under it. */
 function settleLiterals(unmatched: Set<string>, rel: string): void {
@@ -575,6 +765,13 @@ function settleLiterals(unmatched: Set<string>, rel: string): void {
  * 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>,
@@ -582,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 ` +
@@ -601,6 +798,45 @@ interface ResolveFilesArgs {
   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[]> {
@@ -635,16 +871,33 @@ async function resolveFiles(args: ResolveFilesArgs): Promise<string[]> {
   // same project per run is wasteful; we cache the result for the
   // duration of one orchestrator run.
   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
@@ -658,7 +911,7 @@ async function resolveFiles(args: ResolveFilesArgs): Promise<string[]> {
   // claims as an input. See the refusal below for why this is not simply
   // honoured instead.
   const unmatchedLiterals = new Set(
-    positive.map(normalizeGlob).filter(isLiteralPath).map(stripTrailingSlash),
+    positive.map(normalizeGlob).filter(isLiteralPattern).map(stripTrailingSlash),
   )
   // First pass: glob-filter to candidate absolute paths (no I/O).
   const candidates: string[] = []
@@ -678,6 +931,7 @@ async function resolveFiles(args: ResolveFilesArgs): Promise<string[]> {
   if (unmatchedLiterals.size > 0) {
     await assertNoInvisibleLiteralInputs(unmatchedLiterals, args.projectDir, 'files')
   }
+  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
@@ -685,54 +939,101 @@ async function resolveFiles(args: ResolveFilesArgs): Promise<string[]> {
   // `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)
-  return candidates.filter((abs) => oids?.has(abs) === true || isInputOnDisk(abs)).sort()
+  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]
+}
+
+/**
+ * `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.
+ */
+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.`,
+  )
 }
 
 /**
- * Union of files matching any positive pattern in `cwd`, minus files
- * matching any exclude glob (tested by Bun.Glob.match on the relative
+ * 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.
+ */
+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
+  }
+  let raw: Buffer[]
+  try {
+    raw = readdirSync(dir, { encoding: 'buffer' })
+  } catch {
+    return false
+  }
+  const lossy = new TextDecoder()
+  for (const name of raw) {
+    if (lossy.decode(name) !== next) continue
+    try {
+      FATAL_UTF8.decode(name)
+    } catch {
+      return true
+    }
+  }
+  return false
+}
+
+const FATAL_UTF8 = new TextDecoder('utf-8', { fatal: true })
+
+/**
+ * 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.
  *
- * `outputs` mode also 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 mode lists everything and sorts by `lstat`.
+ * 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[],
   excludeGlobs: readonly Bun.Glob[],
   cwd: string,
-  mode: 'files' | 'outputs' = 'files',
 ): Promise<Set<string>> {
   const matches = new Set<string>()
   for (const pattern of positive) {
     const glob = globFor(pattern)
-    if (mode === 'outputs') {
-      for (const rel of glob.scanSync({
-        cwd,
-        onlyFiles: false,
-        followSymlinks: false,
-        dot: true,
-      })) {
-        if (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)
-      }
-      continue
-    }
-    // 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).
-    for (const rel of glob.scanSync({ 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
@@ -744,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
 }