@vzn/vx 0.0.596 → 0.0.598

package/launcher.cjs

@@ -18,12 +18,16 @@
 // CommonJS, not ESM: Node's ESM loader cost every `vx` call ~8 ms of a
 // ~65 ms launch (min of 21, interleaved, Node 22, 2026-10-01).
 const { execFileSync, spawn, spawnSync } = require('node:child_process')
-const { existsSync, readFileSync } = require('node:fs')
+const { existsSync, readFileSync, realpathSync } = require('node:fs')
 const { constants: osConstants } = require('node:os')
 const { dirname, join } = require('node:path')
 
-const here = __dirname
-const pkg = require('./package.json')
+// The real directory, not `__dirname`: npm's `node_modules/.bin/vx` is a
+// symlink to this file, and under `--preserve-symlinks-main` (NODE_OPTIONS)
+// `__dirname` is `.bin`, where `./package.json` does not resolve and
+// the launcher died MODULE_NOT_FOUND before vx started.
+const here = dirname(realpathSync(__filename))
+const pkg = require(join(here, 'package.json'))
 
 // Derive the platform-package prefix + binary basename from this package's
 // name. `base` is the unscoped name — the command AND the binary filename

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vzn/vx",
-  "version": "0.0.596",
+  "version": "0.0.598",
   "description": "The fastest task runner and build cache for JavaScript monorepos.",
   "type": "module",
   "exports": {
@@ -21,10 +21,10 @@
     "node": ">=18"
   },
   "optionalDependencies": {
-    "@vzn/vx-linux-x64": "0.0.596",
-    "@vzn/vx-linux-arm64": "0.0.596",
-    "@vzn/vx-darwin-x64": "0.0.596",
-    "@vzn/vx-darwin-arm64": "0.0.596"
+    "@vzn/vx-linux-x64": "0.0.598",
+    "@vzn/vx-linux-arm64": "0.0.598",
+    "@vzn/vx-darwin-x64": "0.0.598",
+    "@vzn/vx-darwin-arm64": "0.0.598"
   },
   "dependencies": {
     "@anthropic-ai/sandbox-runtime": "^0.0.76"

package/src/bin.ts

@@ -30,8 +30,12 @@ async function main(): Promise<void> {
     // is set, and `exitOnceFlushed` exits after both streams have ended.
     process.exitCode = code
   } catch (err) {
-    const { fsRefusalHint, isFsRefusal, isOutOfFds, isUserError, OUT_OF_FDS_HINT } =
+    const { fsRefusalHint, isFsRefusal, isOutOfFds, isUserError, maskedLine, OUT_OF_FDS_HINT } =
       await import('./util/index.js')
+    // A plugin's failure quotes what it was told (a remote's reply, a
+    // header), and a config's own throw is its author's text: a secret in
+    // either reached stderr whole (L-11).
+    const say = (line: string): void => void process.stderr.write(maskedLine(line))
     // UserError (workspace not found, cycle, config invalid, ...) —
     // print the message only; the stack is noise the user can't act
     // on. Everything else gets the full stack so internal bugs are
@@ -41,16 +45,16 @@ async function main(): Promise<void> {
       // that wants its own name in the line) is printed as it is; prefixing
       // it produced `vx: vx why: …` (walkthrough, 2026-09-04).
       const m = err.message
-      process.stderr.write(m.startsWith('vx ') ? `${m}\n` : `vx: ${m}\n`)
+      say(m.startsWith('vx ') ? `${m}\n` : `vx: ${m}\n`)
     } else if (isOutOfFds(err)) {
-      process.stderr.write(`vx: ${err.message} — ${OUT_OF_FDS_HINT}\n`)
+      say(`vx: ${err.message} — ${OUT_OF_FDS_HINT}\n`)
     } else if (isFsRefusal(err)) {
       // The file system's refusal names the path; the stack would name
       // the verb's write, which the reader cannot act on either.
-      process.stderr.write(`vx: ${err.message} — ${fsRefusalHint(err)}\n`)
+      say(`vx: ${err.message} — ${fsRefusalHint(err)}\n`)
     } else {
       const message = err instanceof Error ? (err.stack ?? err.message) : String(err)
-      process.stderr.write(`vx: ${message}\n`)
+      say(`vx: ${message}\n`)
     }
     // Same reason as the success path above: a large stderr is truncated by
     // `process.exit` too, and an error message cut in half is the one a

package/src/cache/archive.ts

@@ -233,7 +233,7 @@ export async function planArtifact(args: PackArgs): Promise<ArtifactPlan> {
   const few = args.outputs.size <= ON_THREAD_STATS
   const lstatOf = few ? async (p: string) => lstatSync(p) : lstat
   const statOf = few ? async (p: string) => statSync(p) : stat
-  const realpathOf = few ? async (p: string) => realpathSync(p) : realpath
+  const realpathOf = (p: string) => realOf(p, few)
   let withinReal: Promise<string> | undefined
   // Where this artifact's own non-link outputs really are: a link to one of
   // them packs bytes the task wrote itself. A root-anchored output tree is
@@ -262,6 +262,16 @@ export async function planArtifact(args: PackArgs): Promise<ArtifactPlan> {
         : name.startsWith(WORKSPACE_OUTPUT_PREFIX)
           ? `workspaceFiles output ${name.slice(WORKSPACE_OUTPUT_PREFIX.length)}`
           : `output ${name}`
+      // The index stores a project row as its bare rel and reads one under
+      // `workspace-outputs/` as a workspace output, so every hit of this
+      // entry was "missing a recorded output", dropped and run again. The
+      // loader refuses a glob written under the name; one that reaches it
+      // otherwise (`**/*.js`, `w*/**`) is refused here, where names are known.
+      if (name.startsWith(`outputs/${WORKSPACE_OUTPUT_PREFIX}`)) {
+        throw new UserError(
+          `${shown} is under workspace-outputs/, a name vx's artifacts reserve for outputs.workspaceFiles — write the task's files to another directory, or take them back with a '!' entry`,
+        )
+      }
       const dangling = (err: NodeJS.ErrnoException): never => {
         if (err.code === 'ENOENT') {
           throw new UserError(
@@ -293,12 +303,12 @@ export async function planArtifact(args: PackArgs): Promise<ArtifactPlan> {
         )
       }
       const mode = st.mode & 0o777
-      meta.files[name] = [mode, Math.floor(st.mtimeMs)]
       return {
         name,
         abs: src,
         size: st.size,
         mode,
+        mtimeMs: Math.floor(st.mtimeMs),
         // ustar's octal field holds no sign: an mtime before 1970 made the
         // header unreadable and every save of it a "corrupt artifact". The
         // sidecar above carries the real value.
@@ -306,6 +316,8 @@ export async function planArtifact(args: PackArgs): Promise<ArtifactPlan> {
       }
     }),
   )
+  // In the outputs' order, not as each stat settled: one tree, one artifact.
+  for (const f of files) meta.files[f.name] = [f.mode, f.mtimeMs]
   const stdout = new TextEncoder().encode(args.stdout)
   const metaBytes = new TextEncoder().encode(JSON.stringify(meta))
   const inputs: TarInput[] = [
@@ -624,11 +636,11 @@ class Extractor {
       // deepest EXISTING ancestor and re-append the rest: the answer is the
       // same before and after the base is created, which is what makes the
       // memo safe.
-      r = await realpath(key).catch(async () => {
+      r = await realOf(key).catch(async () => {
         let probe = path.dirname(key)
         const tail: string[] = [path.basename(key)]
         while (probe !== path.dirname(probe)) {
-          const real = await realpath(probe).then(
+          const real = await realOf(probe).then(
             (v) => v,
             () => null,
           )
@@ -674,7 +686,7 @@ class Extractor {
     // resolve was a round trip spent on a comparison never made (item 627).
     let probe = path.dirname(targetResolved)
     while (probe.startsWith(baseResolved + path.sep)) {
-      const real = await realpath(probe).then(
+      const real = await realOf(probe).then(
         (r) => r,
         () => null,
       )
@@ -854,7 +866,7 @@ class Extractor {
       const top = path.resolve(s.created)
       // Created at a dangling link's resolved target (`mkdirThroughLink`),
       // so the chain is pruned from where the link leads.
-      if (!dir.startsWith(top)) dir = await realpath(dir).catch(() => dir)
+      if (!dir.startsWith(top)) dir = await realOf(dir).catch(() => dir)
       while (dir.startsWith(top)) {
         if (
           !(await rmdir(dir).then(
@@ -903,6 +915,23 @@ async function linkOutError(base: string, probe: string, realBase: string): Prom
   )
 }
 
+/**
+ * `realpath`, for a path holding a backslash too: Bun's answers ENOENT for
+ * any such path (1.4.2), so the containment walk took a link named
+ * `dist\x` for absent and wrote through it, and a save called a linked
+ * output under one dangling. Such a path's links are read one by one.
+ */
+async function realOf(p: string, sync = false): Promise<string> {
+  try {
+    return sync ? realpathSync(p) : await realpath(p)
+  } catch (err) {
+    if (!p.includes('\\')) throw err
+    const real = await resolveThrough(p)
+    await stat(real)
+    return real
+  }
+}
+
 /**
  * Where `p` leads, every link on the way followed, a dangling one included:
  * `realpath` for the part that exists, and past the first missing name the

package/src/cache/cache.ts

@@ -660,15 +660,6 @@ export class Cache implements CacheLayer {
   /** The shared store this index attached, or undefined when it holds its entries itself. */
   readonly storeDir: string | undefined
 
-  /**
-   * The store this open was asked for and could not use, with why: the
-   * entries went to a store inside `cacheDir` instead.
-   */
-  readonly storeFallback: string | null = null
-
-  /** Set when this open moved a workspace index's own entries out for a shared store. */
-  readonly storeMoved: { from: string; to: string } | null = null
-
   /**
    * Set when THIS open found an index written by another `SCHEMA_VERSION`
    * and dropped every table. The next open sees the current version and
@@ -849,24 +840,33 @@ export class Cache implements CacheLayer {
         this.schemaReset = this.db
           .transaction((): SchemaReset | null => {
             const found = readVersion()
-            if (found !== undefined && found !== SCHEMA_VERSION) refuseUnreadable(found)
-            if (found === undefined) {
-              this.db
-                .prepare("INSERT INTO schema_meta(key, value) VALUES ('version', ?)")
-                .run(SCHEMA_VERSION)
-              return null
-            }
             if (found === SCHEMA_VERSION) return null
+            if (found !== undefined) refuseUnreadable(found)
             // `main.` on every name: unqualified, a table the index lacks
             // resolves to an attached store's (none is attached yet; this
             // keeps it so).
-            this.db.exec(
-              'DROP TABLE IF EXISTS main.entries; DROP TABLE IF EXISTS main.runs; DROP TABLE IF EXISTS main.file_hashes; DROP TABLE IF EXISTS main.blob_sizes; DROP TABLE IF EXISTS main.blob_verdicts; DROP TABLE IF EXISTS main.output_files; DROP TABLE IF EXISTS main.output_stamps; DROP TABLE IF EXISTS main.invocations; DROP TABLE IF EXISTS main.run_task_inputs; DROP TABLE IF EXISTS main.entry_inputs; DROP TABLE IF EXISTS main.config_evals; DROP TABLE IF EXISTS main.config_closures; DROP TABLE IF EXISTS main.output_dirs; DROP TABLE IF EXISTS main.entry_stdout; DROP TABLE IF EXISTS main.store_meta;',
-            )
+            if (found !== undefined) {
+              this.db.exec(
+                'DROP TABLE IF EXISTS main.entries; DROP TABLE IF EXISTS main.runs; DROP TABLE IF EXISTS main.file_hashes; DROP TABLE IF EXISTS main.blob_sizes; DROP TABLE IF EXISTS main.blob_verdicts; DROP TABLE IF EXISTS main.output_files; DROP TABLE IF EXISTS main.output_stamps; DROP TABLE IF EXISTS main.invocations; DROP TABLE IF EXISTS main.run_task_inputs; DROP TABLE IF EXISTS main.entry_inputs; DROP TABLE IF EXISTS main.config_evals; DROP TABLE IF EXISTS main.config_closures; DROP TABLE IF EXISTS main.output_dirs; DROP TABLE IF EXISTS main.entry_stdout; DROP TABLE IF EXISTS main.store_meta;',
+              )
+            }
+            // The tables land under the same write lock as the stamp: made
+            // after it, another vx's reset could stamp its own schema in
+            // between and keep these tables under it. An index beside a
+            // store keeps no entry tables (they would shadow the store's).
+            createTables(this.db, 'main')
+            const recordedStore = this.db
+              .prepare("SELECT 1 FROM schema_meta WHERE key = 'store_dir'")
+              .get()
+            if (storeRoot === undefined ? recordedStore != null : storeRoot !== null) {
+              for (const t of STORE_TABLES) this.db.exec(`DROP TABLE main.${t}`)
+            }
             this.db
-              .prepare("UPDATE schema_meta SET value = ? WHERE key = 'version'")
+              .prepare(
+                "INSERT INTO schema_meta(key, value) VALUES ('version', ?) ON CONFLICT(key) DO UPDATE SET value = excluded.value",
+              )
               .run(SCHEMA_VERSION)
-            return { from: found, to: SCHEMA_VERSION }
+            return found === undefined ? null : { from: found, to: SCHEMA_VERSION }
           })
           .immediate()
       } catch (err) {
@@ -904,8 +904,6 @@ export class Cache implements CacheLayer {
         // the entries stay in this workspace rather than fail the run.
         const fallback = cacheDir
         if (fallback !== storeDir) {
-          // Said by the open that falls back; the ones after it find it recorded.
-          if (recorded !== fallback) this.storeFallback = `${storeDir} (${blocked})`
           storeDir = fallback
           openCacheDir(fallback)
         }
@@ -922,13 +920,11 @@ export class Cache implements CacheLayer {
             .get() != null,
       )
       if (holds) {
-        const had = this.db.prepare('SELECT 1 FROM main.entries LIMIT 1').get() != null
         this.db
           .transaction(() => {
             for (const t of STORE_TABLES) this.db.exec(`DROP TABLE IF EXISTS main.${t}`)
           })
           .immediate()
-        if (had) this.storeMoved = { from: cacheDir, to: storeDir }
       }
     }
     this.storeDir = storeDir
@@ -1040,13 +1036,25 @@ export class Cache implements CacheLayer {
    * Attach the shared store as `store`, with the pragmas the index takes:
    * WAL for both, so a workspace's run and another's share the store as
    * two runs on one `--cache-dir` share an index. A reading verb over a
-   * store with no file yet reads an empty one in memory.
+   * store with no file or no tables yet reads an empty one in memory.
    */
   private attachStore(storeDir: string, inspecting: boolean): void {
     const storeFile = path.join(storeDir, 'store.db')
-    const absent = inspecting && !existsSync(storeFile)
+    let absent = inspecting && !existsSync(storeFile)
     try {
       this.db.prepare('ATTACH DATABASE ? AS store').run(absent ? ':memory:' : storeFile)
+      // One with no tables yet is read empty in memory too: the journal
+      // switch and the table creation below are writes, under no write
+      // lock, racing an opener making that store.
+      if (
+        inspecting &&
+        !absent &&
+        this.db.prepare("SELECT 1 FROM store.sqlite_master WHERE name = 'entries'").get() == null
+      ) {
+        this.db.exec('DETACH DATABASE store')
+        this.db.prepare('ATTACH DATABASE ? AS store').run(':memory:')
+        absent = true
+      }
       this.db.exec('PRAGMA store.journal_mode = WAL')
       if (!absent) this.db.fileControl('store', SQLITE_FCNTL_PERSIST_WAL, 1)
       this.db.exec('PRAGMA store.journal_size_limit = 67108864')
@@ -1750,6 +1758,21 @@ export class Cache implements CacheLayer {
     return this.packArtifact(args)
   }
 
+  /**
+   * The artifact under a private second name, for a body read more than
+   * once (a digest pass then an upload, a retry). The live name is not
+   * stable: a re-save of the key renames other bytes over it, and a body
+   * opened by path read those mid-upload (a digest of one artifact over
+   * the bytes of another). A `Bun.file` over an fd is no answer — its
+   * second read starts where the first ended. Throws when the artifact is
+   * gone; `release` unlinks the name.
+   */
+  pinArtifact(hash: string): { body: Blob; release: () => Promise<void> } {
+    const pinned = this.tempPath(hash)
+    linkSync(this.tarPath(hash), pinned)
+    return { body: Bun.file(pinned), release: () => unlink(pinned).catch(() => undefined) }
+  }
+
   /**
    * The remote body goes to the temp by `Bun.write`, which streams a
    * `Response` and copies a file `Blob` without collecting either, so a
@@ -1769,6 +1792,9 @@ export class Cache implements CacheLayer {
         hash,
         `remote body runs past ${cap} bytes (the artifact ceiling's bound)`,
       )
+    // Every refusal releases the remote body: a held response pins its
+    // connection, and a layer that settles on the body's end never hears.
+    let counted: ReadableStream<Uint8Array> | undefined
     try {
       if (body instanceof Blob) {
         if (body.size > cap) throw past()
@@ -1777,7 +1803,7 @@ export class Cache implements CacheLayer {
         throw past()
       } else {
         let n = 0
-        const counted = body.body?.pipeThrough(
+        counted = body.body?.pipeThrough(
           new TransformStream<Uint8Array, Uint8Array>({
             transform(chunk, controller) {
               n += chunk.byteLength
@@ -1789,6 +1815,9 @@ export class Cache implements CacheLayer {
         await Bun.write(tmpPath, new Response(counted ?? null))
       }
     } catch (err) {
+      // A failed write leaves the pipe's end unlocked; cancelling it
+      // cancels the source. A body refused by its length is cancelled itself.
+      if (!(body instanceof Blob)) void (counted ?? body.body)?.cancel(err).catch(() => undefined)
       await unlink(tmpPath).catch(() => undefined)
       throw err
     }
@@ -2294,9 +2323,9 @@ export class Cache implements CacheLayer {
     // Delete DB rows in a single transaction (one fsync; ON DELETE
     // CASCADE clears `output_files`) and unlink artifacts in parallel.
     // Replaces N round-trips + serialized rm with one transaction + a
-    // Promise.all over the unlinks. The IN-list is chunked at 900 like
-    // flushAccessed so a huge eviction stays under any build's
-    // bound-parameter ceiling.
+    // Promise.all over the unlinks. The hash list binds as one `json_each`
+    // parameter, so a huge eviction stays under any build's bound-parameter
+    // ceiling.
     if (dryRun) {
       return { evicted: victims.size, bytesFreed, orphans: picked.files.length, orphanBytes }
     }

package/src/cache/git-inputs.ts

@@ -87,6 +87,29 @@ export function repoFacts(dir: string): RepoFacts | null {
   return facts
 }
 
+/**
+ * The refusal a run would meet at its enumeration, asked up front by a
+ * verb that waits on the user first (the picker); undefined when git
+ * tracks `dir`. Free when it does: `repoFacts` is the answer the run
+ * reuses.
+ */
+export function gitRefusal(dir: string): UserError | undefined {
+  if (repoFacts(dir) !== null) return undefined
+  let proc
+  try {
+    proc = Bun.spawnSync({
+      cmd: [executablePath('git'), 'rev-parse', '--is-inside-work-tree'],
+      cwd: dir,
+      stdout: 'ignore',
+      stderr: 'pipe',
+    })
+  } catch {
+    return gitSpawnRefusal(dir)
+  }
+  if (proc.exitCode === 0) return undefined
+  return notAWorkTree(dir, new TextDecoder().decode(proc.stderr).trim())
+}
+
 /** Variables that move where git finds the repository or its index: with any set, git is asked. */
 const GIT_LOCATION_ENV = [
   'GIT_INDEX_FILE',

package/src/cache/index.ts

@@ -36,6 +36,7 @@ export {
   cleanOutputs,
   cleanWorkspaceOutputs,
   declaresInput,
+  workspaceFilesReachInto,
   resolveInputs,
   resolveOutputs,
   resolveWorkspaceOutputs,
@@ -52,6 +53,7 @@ export {
 } from './inputs.js'
 export {
   GitFilesCache,
+  gitRefusal,
   applyGitEnumeration,
   gitPathspecs,
   MAX_SCOPED_PATHSPECS,

package/src/cache/inputs.ts

@@ -17,7 +17,7 @@
 // be a git work tree; non-git environments are not supported.
 
 import path from 'node:path'
-import { lstatSync, readdirSync, realpathSync, rmdirSync, rmSync } from 'node:fs'
+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 {
@@ -33,6 +33,7 @@ import {
   slashBraceExpansions,
   splitNegations,
   staticPrefix,
+  stripTrailingSlash,
   taskGlob,
   UserError,
 } from '../util/index.js'
@@ -643,7 +644,11 @@ function outputExcludes(outputs: readonly string[]): Bun.Glob[] {
   return (namesNodeModules ? OUTPUT_NEVER : [...OUTPUT_NEVER, '**/node_modules/**']).map(globFor)
 }
 
-/** Resolve declared output globs (project-relative) to actual produced files. */
+/**
+ * Resolve declared output globs (project-relative) to actual produced files.
+ * An output directory linked out of the project is refused by name (X-88):
+ * dropping its files silently saved an empty entry under a green run.
+ */
 export async function resolveOutputs(args: {
   projectDir: string
   outputs: readonly string[]
@@ -652,9 +657,11 @@ export async function resolveOutputs(args: {
   const { positive, negative } = splitNegations(args.outputs)
   if (positive.length === 0) return []
   const excludeGlobs = [...outputExcludes(positive), ...asTrees(negative).map(globFor)]
+  const trees = asTrees(positive)
+  refuseDirLinkedOut(args.projectDir, trees)
   const scanned = [
     ...(await scanUnion(
-      asTrees(positive),
+      trees,
       excludeGlobs,
       args.projectDir,
       inNestedProject(args.projectDir, args.nestedProjectDirs),
@@ -670,6 +677,53 @@ export async function resolveOutputs(args: {
   return containedIn(args.projectDir, scanned).sort()
 }
 
+/**
+ * The literal head of each output glob, walked: the scan follows a link
+ * there (`dist -> ../elsewhere` for `dist/**`) and only there. A link to a
+ * FILE is the archive's to judge (L-23); a dangling one the restore's.
+ */
+function refuseDirLinkedOut(projectDir: string, trees: readonly string[]): void {
+  let realRoot: string | undefined
+  for (const tree of trees) {
+    let at = projectDir
+    for (const part of staticPrefix(tree).split('/')) {
+      if (part === '' || part === '.') continue
+      at = path.join(at, part)
+      if (!isInside(projectDir, at)) break
+      let st
+      try {
+        st = lstatSync(at)
+      } catch {
+        break
+      }
+      if (!st.isSymbolicLink()) continue
+      let real: string
+      try {
+        real = realpathSync(at)
+        if (!statSync(real).isDirectory()) break
+      } catch {
+        break
+      }
+      realRoot ??= realOr(projectDir)
+      if (!isInside(realRoot, real)) {
+        throw new UserError(
+          `${at} is a symbolic link to ${real}, outside ${projectDir} — vx never cleans, saves ` +
+            'or restores declared outputs through a link that leaves the project. Remove the ' +
+            'link and re-run, or stop declaring outputs under it.',
+        )
+      }
+    }
+  }
+}
+
+function realOr(p: string): string {
+  try {
+    return realpathSync(p)
+  } catch {
+    return p
+  }
+}
+
 /**
  * Keep only the paths that are REALLY inside `root` — lexically, and after
  * resolving symlinks.
@@ -708,16 +762,9 @@ function containedIn(root: string, paths: readonly string[]): string[] {
   // Sync, as `hashFile`'s lstat: a realpath is microseconds, and the
   // promise round trip per call was most of this function's cost on every
   // miss (B, 2026-09-30).
-  const real = (p: string): string | null => {
-    try {
-      return realpathSync(p)
-    } catch {
-      return null
-    }
-  }
-  const realRoot = real(root) ?? root
+  const realRoot = realOrNull(root) ?? root
   const uniqueDirs = [...new Set(lexDirs)]
-  const resolved = uniqueDirs.map(real)
+  const resolved = uniqueDirs.map(realOrNull)
   const contained = new Set<string>()
   for (const [i, dir] of uniqueDirs.entries()) {
     const real = resolved[i]
@@ -899,7 +946,7 @@ const SYNC_CLEAN_MAX = 128
  * sends the reader to file a bug against a permission bit.
  */
 async function removeAll(all: readonly string[], root: string): Promise<string[]> {
-  const files = notThroughLink(all, root)
+  const files = insideRoot(all, root)
   const refused = (f: string, err: NodeJS.ErrnoException): UserError => {
     const rel = relPosix(root, f)
     return new UserError(
@@ -929,21 +976,14 @@ async function removeAll(all: readonly string[], root: string): Promise<string[]
 }
 
 /**
- * The paths whose directory is really where it sits, not reached through a
- * symlinked directory. A save follows `dist -> real-out` on purpose
- * (turborepo#13042), but a clean through a link deletes the target's
- * files: `public -> static` in the same project took the tracked
- * `static/logo.svg` before every run (X-5). The link is a declared
- * output's own entry; what it leads to is not.
+ * The paths whose directory resolves inside `root`. A link inside the
+ * project is followed, as the save follows it (turborepo#13042): a clean
+ * that skipped `dist -> real-out` left the last run's files for the next
+ * entry to save (X-88). One that leaves the project is never deleted
+ * through (X-5); `cleanOutputPaths` takes recorded rows, not the resolver's
+ * contained set, so the check is here too.
  */
-function notThroughLink(files: readonly string[], root: string): string[] {
-  const real = (p: string): string | null => {
-    try {
-      return realpathSync(p)
-    } catch {
-      return null
-    }
-  }
+function insideRoot(files: readonly string[], root: string): string[] {
   // Resolved only once a directory exists to compare: after a clean pruned
   // the outputs (the common restore) nothing does, and the call was most
   // of an empty clean.
@@ -955,9 +995,8 @@ function notThroughLink(files: readonly string[], root: string): string[] {
     if (ok === undefined) {
       // A directory already gone has nothing to delete through; its path
       // stays so the prune still reaches the parents it emptied.
-      const r = real(dir)
-      ok =
-        r === null || r === path.join((realRoot ??= real(root) ?? root), path.relative(root, dir))
+      const r = realOrNull(dir)
+      ok = r === null || isInside((realRoot ??= realOrNull(root) ?? root), r)
       own.set(dir, ok)
     }
     return ok
@@ -1101,8 +1140,12 @@ export async function cleanWorkspaceOutputs(args: {
   return files.map((f) => relPosix(args.workspaceRoot, f))
 }
 
-function stripTrailingSlash(p: string): string {
-  return p.replace(/\/+$/, '')
+function realOrNull(p: string): string | null {
+  try {
+    return realpathSync(p)
+  } catch {
+    return null
+  }
 }
 
 // The literal-is-a-tree rule moved to `util/paths.ts` (item 442): it
@@ -1356,6 +1399,18 @@ export function declaresInput(
   return matcher(workspaceRel)
 }
 
+/**
+ * Whether a cached 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
+  if (ws === undefined || ws.length === 0) return false
+  return reaches(reachOf(splitNegations(ws).positive).prefixes, dir)
+}
+
 function inPlan(plan: FilesPlan, rel: string): boolean {
   let input = plan.verdicts.get(rel)
   if (input === undefined) {

package/src/cache/key-fold.ts

@@ -103,7 +103,7 @@ import type { CacheKeyInput } from './layer.js'
 // bytes on disk, the filter since removed, holds the CRLF build (A-60).
 // v39: an entry saved while a gitlink without `.git` held files the key
 // never listed sits under the key of that directory empty (A-61).
-export const CACHE_VERSION = 'vx-cache-v40'
+export const CACHE_VERSION = 'vx-cache-v41'
 
 /**
  * The digest a key folds for an input gone between its enumeration and its

package/src/cache/layer.ts

@@ -332,7 +332,8 @@ export interface PruneResult {
  * discriminator — least-invasive row format, no schema change. A
  * project output dir literally named `workspace-outputs/` would
  * collide with the namespace; the name is reserved, and a project
- * output glob under it is refused at load (config-schema.ts).
+ * output glob under it is refused at load (config-schema.ts), a file
+ * another glob reaches there at save (`planArtifact`).
  */
 export const WORKSPACE_OUTPUT_PREFIX = 'workspace-outputs/'