@vzn/vx 0.0.639 → 0.0.641

package/src/cache/inputs.ts

@@ -4,7 +4,7 @@
 //   - 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
+// `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. git-inputs.ts
@@ -19,7 +19,7 @@
 import path from 'node:path'
 import { lstatSync, readdirSync, realpathSync, rmdirSync, rmSync, statSync } from 'node:fs'
 import { rm, rmdir } from 'node:fs/promises'
-import type { CacheConfig, CacheInputs } from '../config.js'
+import type { InputsConfig, TaskConfig } from '../config.js'
 import {
   anyTaskGlob,
   asTrees,
@@ -27,6 +27,8 @@ import {
   isInstalledPath,
   isLiteralPattern,
   normalizeGlob,
+  namesNodeModules,
+  OUTPUT_NEVER,
   outputMatcher,
   realpathOf,
   relPosix,
@@ -89,21 +91,8 @@ const ALWAYS_IGNORE = [
   // must not select every `**` reader under --affected.
   '**/.vx/.gitattributes',
   '**/.vx/.gitignore',
-  // `bun build --compile` writes a transient `.<hash>-<n>.bun-build` intermediate
-  // in the cwd. It never rests on disk, so it can't be a real input — but a
-  // broad `inputs.files: ['**/*']` on a compile task would try to hash the temp
-  // file that a CONCURRENT compile is mid-write, racing to EACCES/ENOENT. Always
-  // exclude it (vx is Bun-native; compiling standalone binaries is a common task).
-  '**/*.bun-build',
-  // …and, cross-compiling for a target its cache lacks, the directory it
-  // extracts the downloaded runtime into, `<cwd>/.<16 hex>-<8 hex>.tmp/`,
-  // 60 MB mid-write under the same race (2026-09-29).
-  '**/.????????????????-????????.tmp/**',
-  // vx's own restore temp (archive.ts), live only while an artifact lands
-  // beside its target. A key taken meanwhile listed it, the rename removed
-  // it, and every task reading that directory was withheld its save
-  // (withastro/astro: 25 of 33 builds re-ran on a restore, X-209).
-  '**/.vx-tmp-*',
+  // Where restores stage (archive.ts): vx's own, never an input.
+  '**/.vx/tmp/**',
 ]
 
 const DEFAULT_FILE_GLOBS: readonly string[] = ['**/*']
@@ -121,7 +110,7 @@ export interface ResolveInputsArgs {
   projectDir: string
   workspaceRoot: string
   envSource: NodeJS.ProcessEnv
-  inputs: CacheInputs | undefined
+  inputs: InputsConfig | undefined
   /** Project-relative output globs to exclude from inputs. */
   ownOutputs: readonly string[]
   /** Root-relative `outputs.workspaceFiles` globs to exclude from
@@ -137,7 +126,7 @@ export interface ResolveInputsArgs {
    */
   gitFilesCache?: GitFilesCache
   /**
-   * Run-scoped memo for `cache.inputs.runtime` command execution, keyed
+   * Run-scoped memo for `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 key is sound
@@ -148,7 +137,7 @@ export interface ResolveInputsArgs {
    */
   runtimeCache?: Map<string, Promise<string>>
   /**
-   * Run-scoped memo for `cache.inputs.workspaceRuntime`, keyed by command
+   * Run-scoped memo for `inputs.workspaceRuntime`, keyed by command
    * only — global dedup so a root-level probe spawns once per run.
    */
   workspaceRuntimeCache?: Map<string, Promise<string>>
@@ -160,7 +149,7 @@ export interface ResolveInputsArgs {
    */
   runtimeScope?: string
   /**
-   * Run-scoped memo for `cache.inputs.workspaceFiles`, keyed by the
+   * Run-scoped memo for `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
@@ -177,7 +166,7 @@ export type WorkspaceFilesCache = Map<
 >
 
 /**
- * Per-run memo of `cache.inputs.files` resolution, keyed by the project and
+ * Per-run memo of `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
@@ -263,7 +252,7 @@ export async function resolveInputs(args: ResolveInputsArgs): Promise<ResolvedIn
 }
 
 /**
- * Resolve `cache.inputs.workspaceFiles` — workspace-root-relative
+ * Resolve `inputs.workspaceFiles` — workspace-root-relative
  * globs matched against the workspace-wide git file set (tracked +
  * untracked-not-ignored, same visibility as project inputs).
  *
@@ -354,10 +343,21 @@ function resolveWorkspaceFiles(args: {
   const ownsAny =
     splitNegations(args.ownWorkspaceOutputs).positive.length > 0 ||
     splitNegations(args.ownOutputs).positive.length > 0
+  const reach = ignoredReach(reachOf(positive), gitFiles)
   const files = base.then((all) => {
     const kept = ownsAny ? all.filter((abs) => !own(relPosix(args.workspaceRoot, abs))) : all
     refuseUndecodable(kept, undecodable, args.workspaceRoot, 'workspaceFiles')
-    return kept
+    if (reach.length === 0) return kept
+    // Outside the memo: an ignored file a task writes mid-run leaves the
+    // snapshot as it was.
+    isPositive ??= anyTaskGlob(asTrees(positive))
+    const accept = isPositive
+    const extra = ignoredInputs(
+      args.workspaceRoot,
+      reach,
+      (rel) => accept(rel) && !excludedByDeclaration(rel) && !own(rel),
+    )
+    return extra.length === 0 ? kept : mergeSorted(kept, extra)
   })
   return { files, listing }
 }
@@ -369,23 +369,12 @@ async function resolveWorkspaceFilesOver(
   isPositive: (rel: string) => boolean,
   excluded: (rel: string) => boolean,
 ): 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 = unanswered(
-    positive.map(normalizeGlob).filter(isLiteralPattern).map(stripTrailingSlash),
-    gitFiles,
-  )
   const candidates: string[] = []
   for (const rel of gitFiles) {
     if (!isPositive(rel)) continue
     if (excluded(rel)) continue
     candidates.push(path.resolve(args.workspaceRoot, rel))
   }
-  if (unmatchedLiterals.size > 0) {
-    await assertNoInvisibleLiteralInputs(unmatchedLiterals, 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)
@@ -536,10 +525,10 @@ async function runRuntimeCommand(
     // 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.`,
+        `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})`)
+    throw new UserError(`inputs runtime command failed to spawn: ${command} (cwd: ${cwd})`)
   }
   liveProbes.add(proc)
   let mine: Set<ReturnType<typeof Bun.spawn>> | undefined
@@ -564,7 +553,7 @@ async function runRuntimeCommand(
     const lossy = new TextDecoder()
     const shown = `${lossy.decode(stdout)}${lossy.decode(stderr)}`.trim()
     throw new UserError(
-      `cache.inputs runtime command exited ${exitCode}: ${command} (cwd: ${cwd})` +
+      `inputs runtime command exited ${exitCode}: ${command} (cwd: ${cwd})` +
         (shown ? `\n${shown}` : ''),
     )
   }
@@ -577,7 +566,7 @@ async function runRuntimeCommand(
     // A lossy decode keys every invalid byte as U+FFFD: Latin-1 é and è
     // folded the same output and replayed each other's build.
     throw new UserError(
-      `cache.inputs runtime command printed bytes that are not UTF-8: ${command} (cwd: ${cwd}). ` +
+      `inputs runtime command printed bytes that are not UTF-8: ${command} (cwd: ${cwd}). ` +
         `Pipe it through a hash or od.`,
     )
   }
@@ -677,17 +666,6 @@ 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 no task produces these, and a root project declaring
- * `**` would otherwise wipe its repository and the cache it is restoring
- * from (2026-09-16). `.vx` whole and each `vx.lock.json` are vx's own: as
- * outputs, the clean deleted an uncommitted workspace config and a hit
- * restored a lock or ignore file the key does not see over the current one.
- */
-const OUTPUT_NEVER = ['**/.git/**', '**/.vx/**', '**/vx.lock.json']
-
 /**
  * What a set of output globs may not reach: `OUTPUT_NEVER`, and every
  * `node_modules` unless a glob names one. `**\/*.js` meant the build's
@@ -697,8 +675,9 @@ const OUTPUT_NEVER = ['**/.git/**', '**/.vx/**', '**/vx.lock.json']
  * even `.git`.
  */
 function outputExcludes(outputs: readonly string[]): Bun.Glob[] {
-  const namesNodeModules = outputs.some((o) => normalizeGlob(o).split('/').includes('node_modules'))
-  return (namesNodeModules ? OUTPUT_NEVER : [...OUTPUT_NEVER, '**/node_modules/**']).map(globFor)
+  return (namesNodeModules(outputs) ? OUTPUT_NEVER : [...OUTPUT_NEVER, '**/node_modules/**']).map(
+    globFor,
+  )
 }
 
 /**
@@ -877,6 +856,7 @@ export async function cleanOutputs(args: {
   resolved?: readonly string[] | undefined
 }): Promise<string[]> {
   const committed = args.committed ?? committedFiles(undefined, args.projectDir)
+  sweepRestoreTemps(args.projectDir, args.outputs)
   const matched = args.resolved ?? (await resolveOutputs(args))
   // `force: true` makes rm tolerate ENOENT (e.g. when two output
   // globs overlap and a sibling already deleted a path mid-iteration).
@@ -892,6 +872,70 @@ export async function cleanOutputs(args: {
   return matched.map((f) => relPosix(args.projectDir, f))
 }
 
+/**
+ * Remove the restore temps (`.vx-tmp-<pid>-<n>`, archive.ts) a killed run
+ * left beside an exact-file output. A restore stages in `.vx/tmp/` and
+ * writes one beside its target only where the target is on another
+ * filesystem (EXDEV); a glob over the directory takes it with the outputs,
+ * but `out/a.txt` reaches no sibling, and a partial temp stayed in `out/`
+ * through every later run (Growth's SIGKILL probe, 2026-10-16). A temp
+ * whose writer is alive, this process included, is left: it may be
+ * mid-restore.
+ */
+export function sweepRestoreTemps(base: string, outputs: readonly string[]): void {
+  const dirs = new Set<string>()
+  for (const g of outputs) {
+    if (g.startsWith('!') || !isLiteralPattern(g)) continue
+    dirs.add(path.dirname(path.resolve(base, stripTrailingSlash(normalizeGlob(g)))))
+  }
+  for (const dir of dirs) {
+    let names: string[]
+    try {
+      names = readdirSync(dir)
+    } catch {
+      continue
+    }
+    for (const name of names) {
+      const m = /^\.vx-tmp-([0-9a-z]+)-[0-9a-z]+$/.exec(name)
+      if (m === null) continue
+      const pid = Number.parseInt(m[1]!, 36)
+      if (pid === process.pid || writerAlive(pid)) continue
+      rmSync(path.join(dir, name), { force: true })
+    }
+  }
+}
+
+/**
+ * Empty `.vx/tmp/` (archive.ts `STAGING`) of the staging directories
+ * (`<pid>-<n>`) a killed run left, once per run. One whose writer is alive,
+ * another run's or this one's, is left: it may be mid-restore.
+ */
+export function sweepStaging(workspaceRoot: string): void {
+  const top = path.join(workspaceRoot, '.vx', 'tmp')
+  let names: string[]
+  try {
+    names = readdirSync(top)
+  } catch {
+    return
+  }
+  for (const name of names) {
+    const m = /^([0-9a-z]+)-[0-9a-z]+$/.exec(name)
+    if (m === null) continue
+    const pid = Number.parseInt(m[1]!, 36)
+    if (pid === process.pid || writerAlive(pid)) continue
+    rmSync(path.join(top, name), { recursive: true, force: true })
+  }
+}
+
+function writerAlive(pid: number): boolean {
+  try {
+    process.kill(pid, 0)
+    return true
+  } catch (err) {
+    return (err as NodeJS.ErrnoException).code === 'EPERM'
+  }
+}
+
 /**
  * Remove exactly these project-relative paths — the recorded rows of an
  * ADDITIVE task's own artifact (item 588), never a glob: the glob would
@@ -1221,6 +1265,7 @@ export async function cleanWorkspaceOutputs(args: {
   resolved?: readonly string[] | undefined
 }): Promise<string[]> {
   const committed = args.committed ?? committedFiles(undefined, args.workspaceRoot)
+  sweepRestoreTemps(args.workspaceRoot, args.outputs)
   const matched = args.resolved ?? (await resolveWorkspaceOutputs(args))
   await pruneEmptiedDirs(
     args.workspaceRoot,
@@ -1282,52 +1327,86 @@ function lowerBound(files: readonly string[], key: string): number {
 }
 
 /**
- * Refuse a literal `cache.inputs.files` entry that EXISTS ON DISK but is
- * invisible to git — gitignored, or otherwise absent from
- * `git ls-files --cached --others --exclude-standard`.
- *
- * Such an entry contributes nothing to the cache key, so the task stops
- * tracking a file its own config names as an input. That is a stale hit, and a
- * quiet one: the run replays cached stdout, so it even LOOKS like it executed.
- *
- * Turbo honours the declaration instead (an explicit `inputs` entry overrides
- * gitignore). vx cannot afford to, and the reason is not cost: honouring it
- * would make the cache key depend on a change that `git diff` and
- * `git ls-files --others` CANNOT SEE, so editing that input would re-key the
- * task while `--affected` selected nothing. `docs/cli.md` states the invariant
- * those two surfaces owe each other as a principle — "input hashing sees it, so
- * `--affected` must too" — and it was closed for lockfiles only recently.
- * Honouring a gitignored input would reopen it from the other side.
- *
- * 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.
+ * The entries a declaration names outright that git answers nothing for: a
+ * literal, or a glob's fixed prefix (`dist` of `dist/**`), with no listed
+ * path at or under it. Such a path is gitignored or absent, and naming it
+ * is asking for it (owner, 2026-10-16), so {@link ignoredInputs} reads it
+ * from disk. A broad glob (`**`, or `src/**` over a listed `src`) reaches
+ * no ignored file: `node_modules` is never walked.
  */
-async function assertNoInvisibleLiteralInputs(
-  literals: ReadonlySet<string>,
-  base: string,
-  field: 'files' | 'workspaceFiles' = 'files',
-): Promise<void> {
-  for (const rel of literals) {
-    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 ` +
-        `lists, and a filter cannot add one back. The task would keep reporting ` +
-        `up-to-date after that file changed. If it is generated, depend on the task ` +
-        `that produces it via cache.inputs.tasks; if it should be tracked, remove it ` +
-        `from .gitignore.`,
-    )
+function ignoredReach(
+  reach: { prefixes: readonly string[]; literals: readonly string[] },
+  listed: readonly string[],
+): readonly string[] {
+  const named = outright(reach)
+  if (named.length === 0) return []
+  // Per listing and entries: thousands of tasks share a few declarations.
+  let memo = reachMemo.get(listed)
+  if (memo === undefined) reachMemo.set(listed, (memo = new Map()))
+  const key = named.join('\0')
+  let left = memo.get(key)
+  if (left === undefined) memo.set(key, (left = [...unanswered(named, listed)]))
+  return left
+}
+
+const reachMemo = new WeakMap<readonly string[], Map<string, readonly string[]>>()
+
+/**
+ * A declaration's literals and globs' fixed prefixes, each once: none for a
+ * glob that starts with a wildcard, and none that leaves the directory the
+ * entries are relative to (a project's boundary is hard).
+ */
+function outright(reach: { prefixes: readonly string[]; literals: readonly string[] }): string[] {
+  return [
+    ...new Set(
+      [...reach.literals, ...reach.prefixes].filter(
+        (p) => p !== '' && p !== '.' && p !== '..' && !p.startsWith('../') && !path.isAbsolute(p),
+      ),
+    ),
+  ]
+}
+
+/**
+ * The files on disk under the {@link ignoredReach} entries that `accept`
+ * keeps, sorted and absolute. A file is hashed from disk like any untracked
+ * one; nothing here is stored or restored. `node_modules` is no special
+ * case (owner, 2026-10-16): an ignored path named outright is an input,
+ * a generated client (`node_modules/.prisma/client/**`) too; skipping
+ * installs here folded such an entry to nothing, silently. lstat, not
+ * `exists()`: that answers false for a directory. Never memoized: a
+ * dependency writes these mid-run.
+ */
+function ignoredInputs(
+  root: string,
+  reach: readonly string[],
+  accept: (rel: string) => boolean,
+): string[] {
+  const found = new Set<string>()
+  for (const entry of reach) {
+    const abs = path.resolve(root, entry)
+    const st = lstatSync(abs, { throwIfNoEntry: false })
+    if (st === undefined) continue
+    if (!st.isDirectory()) {
+      if ((st.isFile() || st.isSymbolicLink()) && accept(entry)) found.add(abs)
+      continue
+    }
+    for (const rel of WALK.scanSync({
+      cwd: abs,
+      onlyFiles: false,
+      followSymlinks: false,
+      dot: true,
+    })) {
+      const full = `${entry}/${rel.split(path.sep).join('/')}`
+      if (!accept(full)) continue
+      const file = path.join(abs, rel)
+      if (isInputOnDisk(file)) found.add(file)
+    }
   }
+  return [...found].sort()
 }
 
+const WALK = new Bun.Glob('**')
+
 interface ResolveFilesArgs {
   projectDir: string
   workspaceRoot: string
@@ -1373,7 +1452,7 @@ function refuseUndecodable(
   if (bad.length === 0) return
   const names = bad.map((abs) => JSON.stringify(relPosix(root, abs)))
   throw new UserError(
-    `cache.inputs.${field} matched ${names.join(', ')} in ${root}: the name is not valid UTF-8 ` +
+    `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.`,
   )
@@ -1396,7 +1475,7 @@ function refuseOneAlternativeBrace(
     if (m === null) continue
     const inner = m[0].slice(1, -1)
     throw new UserError(
-      `cache.inputs.${field}: "${entry}" holds a brace with one alternative, which matches ` +
+      `inputs.${field}: "${entry}" holds a brace with one alternative, which matches ` +
         `"${inner}" and never a name holding "${m[0]}". Write "${entry.replace(m[0], inner)}", ` +
         `or "${entry.replace(m[0], `\\{${inner}\\}`)}" for the braces themselves.`,
     )
@@ -1478,41 +1557,59 @@ function filesPlan(
 }
 
 /**
- * Whether a changed path is one of a cached task's declared file inputs:
+ * Whether a changed path is one of a task's declared file inputs:
  * `projectRel` (the path relative to the project that owns it) against
  * `files`, `workspaceRel` (relative to the workspace root) against
  * `workspaceFiles`; null skips that half, by the globs and `!` exclusions (a path under
  * the task's own outputs counts: a committed one is keyed). `--affected` seeds a task with it (owner, 2026-10-04).
  */
 export function declaresInput(
-  cache: CacheConfig,
+  task: TaskConfig,
   projectRel: string | null,
   workspaceRel: string | null,
 ): boolean {
+  const inputs = task.inputs
+  if (inputs === undefined) return false
   if (projectRel !== null) {
     // A changed path under the task's own outputs is a committed file
     // (`git diff` lists only what git tracks) or a stray `git status`
     // lists: either way it may be an input, so it counts.
-    const plan = filesPlan(cache.inputs.files, cache.outputs.files)
+    const plan = filesPlan(inputs.files, task.cache?.outputs.files ?? [])
     if (plan !== null && (inPlan(plan, projectRel) || ownOnly(plan, projectRel))) return true
   }
-  const ws = cache.inputs.workspaceFiles
+  const ws = inputs.workspaceFiles
   if (workspaceRel === null || ws === undefined || ws.length === 0) return false
   return workspaceMatcher(ws)(workspaceRel)
 }
 
 /**
- * Whether a cached task's `workspaceFiles` may name a file under `dir`
+ * Whether a task's `workspaceFiles` may name a file under `dir`
  * (workspace-relative): a nested repository git reports as that one path,
  * whose files the key folds and a match against the path alone misses.
  * By the entries' static prefixes, so a glob that may descend counts.
  */
-export function workspaceFilesReachInto(cache: CacheConfig, dir: string): boolean {
-  const ws = cache.inputs.workspaceFiles
+export function workspaceFilesReachInto(task: TaskConfig, dir: string): boolean {
+  const ws = task.inputs?.workspaceFiles
   if (ws === undefined || ws.length === 0) return false
   return reaches(reachOf(splitNegations(ws).positive).prefixes, dir)
 }
 
+/**
+ * The paths a task names outright (literals, and globs' fixed prefixes),
+ * `files` relative to its project and `workspaceFiles` to the root: where a
+ * gitignored input can be (`ignoredReach`).
+ */
+export function namedOutright(task: TaskConfig): { files: string[]; workspaceFiles: string[] } {
+  const inputs = task.inputs
+  const plan =
+    inputs === undefined ? null : filesPlan(inputs.files, task.cache?.outputs.files ?? [])
+  const ws = inputs?.workspaceFiles ?? []
+  return {
+    files: plan === null ? [] : outright(plan),
+    workspaceFiles: ws.length === 0 ? [] : outright(reachOf(splitNegations(ws).positive)),
+  }
+}
+
 function inPlan(plan: FilesPlan, rel: string): boolean {
   let input = plan.verdicts.get(rel)
   if (input === undefined) {
@@ -1577,7 +1674,14 @@ async function resolveFiles(
     // inputs must be walked again.
     if (memo !== undefined && memo.snapshot === gitFiles) {
       return {
-        files: [...memo.result],
+        files: withIgnored(
+          args.projectDir,
+          memo.result,
+          ignoredReach(plan, gitFiles),
+          plan,
+          nested,
+          ownWsOutput,
+        ),
         listing: listingFor(args, gitFiles, plan, nested, ownWsOutput),
       }
     }
@@ -1635,10 +1739,7 @@ async function resolveFiles(
     if (!input && !committed(abs)) continue
     candidates.push(abs)
   }
-  const unmatchedLiterals = unanswered(plan.literals, gitFiles)
-  if (unmatchedLiterals.size > 0) {
-    await assertNoInvisibleLiteralInputs(unmatchedLiterals, args.projectDir, 'files')
-  }
+  const reach = ignoredReach(plan, gitFiles)
   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
@@ -1656,15 +1757,31 @@ async function resolveFiles(
       break
     }
   }
-  // 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 {
-    files: [...resolved],
+    files: withIgnored(args.projectDir, resolved, reach, plan, nested, ownWsOutput),
     listing: listingFor(args, gitFiles, plan, nested, ownWsOutput),
   }
 }
 
+/** The resolved files, plus the gitignored ones the declaration names outright. */
+function withIgnored(
+  projectDir: string,
+  resolved: readonly string[],
+  reach: readonly string[],
+  plan: FilesPlan,
+  nested: (rel: string) => boolean,
+  ownWsOutput: (rel: string) => boolean,
+): string[] {
+  if (reach.length === 0) return [...resolved]
+  const extra = ignoredInputs(
+    projectDir,
+    reach,
+    (rel) => inPlan(plan, rel) && !nested(rel) && !ownWsOutput(rel),
+  )
+  return extra.length === 0 ? [...resolved] : mergeSorted(resolved, extra)
+}
+
 function listingFor(
   args: { projectDir: string; gitFilesCache?: GitFilesCache | undefined },
   listed: readonly string[],

package/src/cache/key-fold.ts

@@ -28,7 +28,7 @@ import type { CacheKeyInput } from './layer.js'
 // in any cache key. SCHEMA v21 drops the now-unused outputs_hash
 // column. Early cutoff removed (an upstream that re-emits identical
 // output still re-runs dependents) — rare, not worth the cascade.
-// v23: fold cache.inputs.runtime / workspaceRuntime command output into
+// v23: fold inputs.runtime / workspaceRuntime command output into
 // the key (two namespaced sections after env-values). Command strings
 // live in the resolved config (frozen by `vx lock`); the OUTPUT is
 // resolved live every run, so it stays correct under the lock. No
@@ -144,6 +144,12 @@ export async function foldKey(
    * prints nothing.
    */
   digestValue: (value: string) => string = xxh3hex,
+  /**
+   * The content behind an input that is a symlink (linked-inputs.ts), folded
+   * after the link's own target string. Absent, a link folds its target
+   * string alone: a caller that keys no worktree.
+   */
+  behind?: (link: string) => Promise<string>,
 ): Promise<string> {
   // Seed-chained xxHash3: each step folds one field into the
   // running digest via `xxh3(part, prevDigest)`. Equivalent to the
@@ -168,7 +174,7 @@ export async function foldKey(
   // NOTE on `cap` (entry_inputs capture): the `hash` field stores a
   // DIGEST of each component, never the raw value. For value-bearing kinds
   // (env, runtime, ws-runtime, forward) the payload is a secret or
-  // sensitive string (API keys via cache.inputs.env, runtime-command
+  // sensitive string (API keys via inputs.env, runtime-command
   // output, args after `--`), so we push `digestValue(v)` — the diff
   // consumer only needs to know whether a component CHANGED, which a
   // digest preserves losslessly. cache.db must never hold plaintext
@@ -268,13 +274,27 @@ export async function foldKey(
   fileHashes ??= await Promise.all(
     sortedInputs.map((f) => provided?.get(f) ?? hashFile(f).catch(absentOr)),
   )
+  // Links are rare, so a list without one awaits nothing more.
+  let behindLinks: Map<number, string> | undefined
+  if (behind !== undefined) {
+    const links: number[] = []
+    for (let i = 0; i < fileHashes.length; i++)
+      if (fileHashes[i]!.startsWith('120000:')) links.push(i)
+    if (links.length > 0) {
+      const digests = await Promise.all(links.map((i) => behind(sortedInputs[i]!)))
+      behindLinks = new Map(links.map((i, n) => [i, digests[n]!]))
+    }
+  }
   for (let i = 0; i < sortedInputs.length; i++) {
     const file = sortedInputs[i]!
     const rel = relOf(file)
     const oid = fileHashes[i]!
-    h = xxh3(`${rel}\0${oid}`, h)
+    const linked = behindLinks?.get(i)
+    // A link folds what it points to in its own step, so a key without one is unchanged.
+    h = xxh3(linked === undefined ? `${rel}\0${oid}` : `${rel}\0${oid}\0${linked}`, h)
     // The OID is already awaited — file capture is zero extra I/O.
     if (cap) cap.push({ kind: 'file', name: rel, hash: oid })
+    if (linked !== undefined && cap) cap.push({ kind: 'linked', name: rel, hash: xxh3hex(linked) })
   }
 
   return h.toString(16).padStart(16, '0')