@vzn/vx 0.0.21 → 0.0.23

package/src/orchestrator/upstream.ts

@@ -4,10 +4,22 @@ import {
   isTaskPattern,
   parseDependencySpec,
   type DependencySpec,
+  type TaskNode,
   type TaskOutcome,
 } from '../graph/index.js'
 import { UserError } from '../util/index.js'
 
+/**
+ * A task's upstream as its KEY reads it: the live outcomes of its scheduled
+ * dependencies, plus the keys of any `--exclude-dependencies` took out of
+ * the schedule (`excluded-keys.ts`). Every key site goes through this —
+ * the run, the plan, the up-front classify — so a selection cannot change
+ * a key at one of them and not the others.
+ */
+export function keyUpstream(node: TaskNode, upstream: TaskOutcome[]): TaskOutcome[] {
+  return node.excludedUpstream === undefined ? upstream : [...upstream, ...node.excludedUpstream]
+}
+
 /**
  * Pick which upstream task hashes participate in the current task's
  * cache key, filtered by `cache.inputs.tasks`. The folded value is the
@@ -18,6 +30,44 @@ import { UserError } from '../util/index.js'
  * output still re-runs its dependents (early cutoff was removed —
  * rare in practice, not worth the cascade complexity).
  *
+ * The selection itself is `selectFoldedDeps`, which the sandbox's keyed
+ * set (keyed-projects.ts) walks over the graph before any hash exists:
+ * one matcher, so what the key folds and what the sandbox believes it
+ * folds cannot drift.
+ *
+ * Returns `[upstreamTaskId, hash]` pairs. The hash is the only thing
+ * folded into the cache key (the fold sorts by hash, so ordering here
+ * doesn't affect derivation); the task id rides along so Tier-3's
+ * `entry_inputs` rows can NAME which upstream a hash came from. An
+ * upstream with no hash (a persistent task) folds nothing.
+ */
+export function filterUpstreamHashes(
+  upstream: TaskOutcome[],
+  filter: readonly string[] | undefined,
+  selfProjectName: string,
+  selfTaskId: string,
+): Array<[upstreamTaskId: string, hash: string]> {
+  const candidates: FoldCandidate[] = []
+  for (const u of upstream) if (u.hash) candidates.push({ node: u.node, unit: u.hash })
+  return selectFoldedDeps(candidates, filter, selfProjectName, selfTaskId).map((c) => [
+    c.node.id,
+    c.unit,
+  ])
+}
+
+/**
+ * One dependency as the key fold sees it: the task, and the value the
+ * fold dedups by — its hash on the hash path, a structural stand-in for
+ * the hash on the graph (`foldUnit` in keyed-projects.ts).
+ */
+export interface FoldCandidate {
+  node: TaskNode
+  unit: string
+}
+
+/**
+ * The dependencies a task's key folds, per its `cache.inputs.tasks`.
+ *
  * Patterns (Turbo/Nx micro-syntax + filter extensions):
  *   '*'         all same-project upstream
  *   '^*'        all dep-workspace upstream
@@ -36,28 +86,21 @@ import { UserError } from '../util/index.js'
  * `['*', '^*', '!^noisy']` reads as "all minus deps' noisy".
  *
  * Defaults:
- *   - `filter === undefined` → all upstream contribute.
- *   - `filter === []`        → none contribute (fully decoupled).
+ *   - `filter === undefined` → every candidate, as given.
+ *   - `filter === []`        → none (fully decoupled).
  *
- * Returns `[upstreamTaskId, hash]` pairs. The hash is the only thing
- * folded into the cache key (the fold sorts by hash, so ordering here
- * doesn't affect derivation); the task id rides along so Tier-3's
- * `entry_inputs` rows can NAME which upstream a hash came from. The
- * filter dedups by hash, as before — two upstream tasks with identical
- * hashes contribute one pair (first id wins; their key contribution is
- * identical anyway).
+ * Otherwise deduped by `unit`, first candidate kept. The unit is the
+ * fold's own identity, not the task's: two groups over the same members
+ * share one hash, so excluding either excludes both, and a selection by
+ * task id would keep the other while the key folded neither.
  */
-export function filterUpstreamHashes(
-  upstream: TaskOutcome[],
+export function selectFoldedDeps(
+  deps: readonly FoldCandidate[],
   filter: readonly string[] | undefined,
   selfProjectName: string,
   selfTaskId: string,
-): Array<[upstreamTaskId: string, hash: string]> {
-  if (filter === undefined) {
-    const out: Array<[string, string]> = []
-    for (const u of upstream) if (u.hash) out.push([u.node.id, u.hash])
-    return out
-  }
+): FoldCandidate[] {
+  if (filter === undefined) return [...deps]
 
   const specs: DependencySpec[] = filter.map((raw) => {
     try {
@@ -73,21 +116,18 @@ export function filterUpstreamHashes(
   // Per-spec predicate, compiled once (exact compares + patterns).
   const matchers = specs.map((spec) => specMatcher(spec))
 
-  // Dedup by hash (the key fold's unit), but remember the first task id
-  // seen for each hash so the diff row can name the upstream.
-  const selected = new Map<string, string>()
+  const selected = new Map<string, FoldCandidate>()
   for (let i = 0; i < specs.length; i++) {
     const spec = specs[i]!
     const matches = matchers[i]!
-    for (const u of upstream) {
-      if (!u.hash) continue
-      const isSelf = u.node.projectName === selfProjectName
-      if (!matches(u, isSelf)) continue
-      if (spec.negated) selected.delete(u.hash)
-      else if (!selected.has(u.hash)) selected.set(u.hash, u.node.id)
+    for (const d of deps) {
+      const isSelf = d.node.projectName === selfProjectName
+      if (!matches(d.node, isSelf)) continue
+      if (spec.negated) selected.delete(d.unit)
+      else if (!selected.has(d.unit)) selected.set(d.unit, d)
     }
   }
-  return [...selected].map(([hash, id]) => [id, hash])
+  return [...selected.values()]
 }
 
 /**
@@ -102,25 +142,31 @@ export function filterUpstreamHashes(
  * IS the input root: `dependsOn: ['install']` shipped a worker an action with
  * none of what `install` chains.
  *
- * Groups may nest, so the walk recurses. Only what the FILTER already
- * selected is passed in, so a group excluded from a task's
+ * Groups may nest, as deep as the graph (the builder takes a 50,000-deep
+ * chain, item 737), so the walk keeps its own stack; and a group reached
+ * along two paths (a group `build` whose `^build` meets a package diamond)
+ * is expanded once, or the walk doubles per layer. Only what the FILTER
+ * already selected is passed in, so a group excluded from a task's
  * `cache.inputs.tasks` brings no members with it.
  */
 export function expandGroupUpstream(upstream: readonly TaskOutcome[]): TaskOutcome[] {
   const out: TaskOutcome[] = []
   const seen = new Set<string>()
-  const walk = (list: readonly TaskOutcome[]): void => {
-    for (const u of list) {
-      if (u.groupUpstream !== undefined) {
-        walk(u.groupUpstream)
-        continue
-      }
-      if (seen.has(u.node.id)) continue
-      seen.add(u.node.id)
-      out.push(u)
+  const expanded = new Set<TaskOutcome>()
+  const stack = upstream.toReversed()
+  while (stack.length > 0) {
+    const u = stack.pop()!
+    if (expanded.has(u)) continue
+    const members = u.groupUpstream
+    if (members !== undefined) {
+      expanded.add(u)
+      for (let i = members.length - 1; i >= 0; i--) stack.push(members[i]!)
+      continue
     }
+    if (seen.has(u.node.id)) continue
+    seen.add(u.node.id)
+    out.push(u)
   }
-  walk(upstream)
   return out
 }
 
@@ -139,24 +185,24 @@ function nameMatcher(name: string): (candidate: string) => boolean {
  * so a package pattern is unambiguous here — unlike dependsOn, which must
  * materialize concrete edges and therefore rejects it.
  */
-function specMatcher(spec: DependencySpec): (u: TaskOutcome, isSelf: boolean) => boolean {
+function specMatcher(spec: DependencySpec): (n: TaskNode, isSelf: boolean) => boolean {
   switch (spec.kind) {
     case 'wildcardSelf':
-      return (_u, isSelf) => isSelf
+      return (_n, isSelf) => isSelf
     case 'wildcardDeps':
-      return (_u, isSelf) => !isSelf
+      return (_n, isSelf) => !isSelf
     case 'self': {
       const task = nameMatcher(spec.task)
-      return (u, isSelf) => isSelf && task(u.node.taskName)
+      return (n, isSelf) => isSelf && task(n.taskName)
     }
     case 'deps': {
       const task = nameMatcher(spec.task)
-      return (u, isSelf) => !isSelf && task(u.node.taskName)
+      return (n, isSelf) => !isSelf && task(n.taskName)
     }
     case 'cross': {
       const project = nameMatcher(spec.project)
       const task = nameMatcher(spec.task)
-      return (u) => project(u.node.projectName) && task(u.node.taskName)
+      return (n) => project(n.projectName) && task(n.taskName)
     }
   }
 }

package/src/util/bun-version.ts

@@ -0,0 +1,43 @@
+/**
+ * The runtime floor. `package.json`'s `engines` states it, but `engines` is
+ * advice an install may print and a run never reads: `bun src/bin.ts` on an
+ * older Bun starts fine and then answers WRONGLY, which is the failure class
+ * this repo treats as the worst one.
+ *
+ * Measured on Bun 1.3.11 (2026-09-19, STATUS item 366): a 2 MiB `--format
+ * json` answer reached a pipe as 219 KB — `bin.ts` ends stdout in a callback
+ * precisely to prevent that, and the fix does not hold below the floor; the
+ * runner read no `peakRssBytes` at all, so `vx last` and `vx why` reported
+ * nothing a task used; and a config syntax error arrived as a `BuildMessage`
+ * the loader's classifier does not know, surfacing as an internal error
+ * instead of the UserError naming file, line and column. Ten of that
+ * container's twenty-three failures were this, and every one of them is a
+ * green exit over a wrong answer.
+ *
+ * `@vzn/vx-reapi` REFUSES an old Bun at its wire, because its failure mode is
+ * a hang and a hang leaves the user nothing to read. Core warns instead: most
+ * of it works below the floor (23 of ~2,000 tests failed on 1.3.11), so
+ * refusing would be heavier than the measurement supports. What the
+ * measurement supports is that a green exit can hide a truncated answer, and
+ * that is what the warning says.
+ */
+export const MIN_BUN = [1, 4, 0] as const
+
+/** True when `version` is older than {@link MIN_BUN}. */
+export function isUnsupportedBun(version: string): boolean {
+  const [maj = 0, min = 0, patch = 0] = version.split('.').map((p) => Number.parseInt(p, 10) || 0)
+  const [reqMaj, reqMin, reqPatch] = MIN_BUN
+  if (maj !== reqMaj) return maj < reqMaj
+  if (min !== reqMin) return min < reqMin
+  return patch < reqPatch
+}
+
+/** The warning a CLI entry prints once, before the verb runs. */
+export function unsupportedBunMessage(version: string): string {
+  return (
+    `vx needs Bun >= ${MIN_BUN.join('.')} (running ${version}). ` +
+    `An older Bun does not fail — it answers wrongly: a large \`--format json\` ` +
+    `answer is truncated mid-write, no task reports what it used, and a config ` +
+    `syntax error surfaces as an internal error. Upgrade with \`bun upgrade\`.`
+  )
+}

package/src/util/errors.ts

@@ -3,6 +3,9 @@
 //
 // `bin.ts` and the scheduler consult `isUserError` to decide what to print.
 
+import { realpathSync } from 'node:fs'
+import os from 'node:os'
+
 export class UserError extends Error {
   constructor(message: string) {
     super(message)
@@ -23,3 +26,86 @@ export class UserError extends Error {
 export function isUserError(err: unknown): err is UserError {
   return err instanceof UserError || (err instanceof Error && err.name === 'UserError')
 }
+
+/**
+ * An `EACCES`, `EPERM` or `EROFS` from the file system: a path vx must
+ * write is not this user's to write (a root-owned `.vx`, a read-only
+ * checkout). The environment's failure, reported like a UserError — one
+ * line naming the path — never as an internal error with a stack.
+ */
+export function isPermissionError(err: unknown): err is NodeJS.ErrnoException {
+  if (!(err instanceof Error)) return false
+  const code = (err as NodeJS.ErrnoException).code
+  return code === 'EACCES' || code === 'EPERM' || code === 'EROFS'
+}
+
+/** What follows the path in a permission error's one line. */
+export const PERMISSION_HINT = 'a path vx must write is not writable by this user'
+
+/** `ENOSPC` or `EDQUOT`: the disk a path is on is full. */
+export function isDiskFull(err: unknown): err is NodeJS.ErrnoException {
+  if (!(err instanceof Error)) return false
+  const code = (err as NodeJS.ErrnoException).code
+  return code === 'ENOSPC' || code === 'EDQUOT'
+}
+
+/** A file system refusing a write for a reason no code path caused: permission or space. */
+export function isFsRefusal(err: unknown): err is NodeJS.ErrnoException {
+  return isPermissionError(err) || isDiskFull(err)
+}
+
+export const DISK_FULL_HINT = 'the disk that path is on is full'
+
+/** The one-line hint after a refusal's path. */
+export function fsRefusalHint(err: NodeJS.ErrnoException): string {
+  return isDiskFull(err) ? DISK_FULL_HINT : PERMISSION_HINT
+}
+
+/**
+ * A spawn that could not run at all — Bun throws `ENOENT` ("Executable not
+ * found in $PATH") synchronously from `Bun.spawn` and `Bun.spawnSync` alike.
+ * Every git call site tells it from a git that ran and failed, because the
+ * remedy differs: install git, not "git init".
+ */
+export function isExecutableMissing(err: unknown): boolean {
+  return (err as NodeJS.ErrnoException)?.code === 'ENOENT'
+}
+
+/**
+ * The one refusal for a git that is not on PATH, wherever vx needed it — a
+ * `--affected` base, the input enumeration, a watch judgement. A minimal
+ * image without git met a stack from `defaultAffectedBase` before
+ * (2026-09-16); the enumeration had this line and the others did not.
+ */
+export function gitSpawnRefusal(cwd: string): UserError {
+  return new UserError(
+    `vx requires git: failed to spawn 'git' (working dir: ${cwd}). Install git and re-run.`,
+  )
+}
+
+export const TMPDIR_HINT = 'point TMPDIR at a writable directory'
+
+/**
+ * A temp-directory refusal: the path is under `os.tmpdir()` and the error
+ * says it is missing, a file, or not writable. The knob is TMPDIR, and a
+ * line that names the path should name the knob — a minimal image's
+ * sandboxed task said "EACCES … mkdtemp '/tmp/…/srt-obs-…'" and nothing
+ * else (2026-09-16). Only for a site whose path IS the temp directory by
+ * construction: a workspace under /tmp would pass the path test too.
+ */
+export function isTmpdirRefusal(err: unknown): err is NodeJS.ErrnoException {
+  if (!(err instanceof Error)) return false
+  const code = (err as NodeJS.ErrnoException).code
+  if (code !== 'ENOENT' && code !== 'ENOTDIR' && !isPermissionError(err)) return false
+  const p = (err as NodeJS.ErrnoException).path
+  const named = typeof p === 'string' ? p : err.message
+  const tmp = os.tmpdir()
+  // The error may name the resolved directory (macOS: /tmp is /private/tmp);
+  // a temp directory that does not exist has no real path, so the name as
+  // given is the only one it can carry.
+  let real = tmp
+  try {
+    real = realpathSync(tmp)
+  } catch {}
+  return named.includes(tmp) || named.includes(real)
+}

package/src/util/hash.ts

@@ -13,10 +13,19 @@
 // folds `part` into the running digest. Equivalent to the old
 // `CryptoHasher.update(...).update(...).digest()` pattern, without
 // allocating an intermediate buffer.
+//
+// Bun reads only the LOW 32 bits of that seed (measured, item 682), so a
+// bare `xxHash3(part, prev)` carries 32 bits of state from step to step:
+// two input sets whose running digests share their low halves merge at
+// the next step, and a birthday search found such a pair in 0.08 s — a
+// stale hit at ~2^-32 per step, not 2^-64. The seed is XORed back in
+// (feed-forward): states that share their low half keep their exact
+// high-half difference through every later step, so they never merge,
+// and a seed of 0 changes nothing, so single-shot digests are unchanged.
 
 /** xxHash3 bigint output. Use as the seed for the next chain step. */
 export function xxh3(input: string | Uint8Array, seed: bigint = 0n): bigint {
-  return Bun.hash.xxHash3(input, seed)
+  return Bun.hash.xxHash3(input, seed) ^ seed
 }
 
 /** xxHash3 hex-encoded, fixed 16 chars (zero-padded). */

package/src/util/index.ts

@@ -1,13 +1,38 @@
 // Module contract. Cross-module imports must come through here; see
 // docs/design/module-isolation-2026-06.md and tests/module-boundaries.test.ts.
 
-export { isUserError, UserError } from './errors.js'
+export {
+  DISK_FULL_HINT,
+  fsRefusalHint,
+  isDiskFull,
+  isFsRefusal,
+  isTmpdirRefusal,
+  TMPDIR_HINT,
+  isPermissionError,
+  isUserError,
+  PERMISSION_HINT,
+  UserError,
+  gitSpawnRefusal,
+  isExecutableMissing,
+} from './errors.js'
 export { xxh3, xxh3hex } from './hash.js'
 export { mark, printTimings, span } from './timing.js'
 export { clampInt, MAX_TIMEOUT_MS, parseDecimalInt } from './num.js'
-export { normalizeGlob, relPosix, staticPrefix, wholeSubtreePrefixes } from './paths.js'
+export {
+  asTrees,
+  BUN_GLOB_WILDCARDS,
+  grantPrefix,
+  isLiteralPattern,
+  GLOB_WILDCARDS,
+  normalizeBunGlob,
+  normalizeGlob,
+  relPosix,
+  staticPrefix,
+  taskGlob,
+  wholeSubtreePrefixes,
+} from './paths.js'
 export { killGraceMs, settleWithin, teardownTimeoutMs } from './settle.js'
-export { parseSize } from './size.js'
+export { formatBytes, parseDuration, parseSize } from './size.js'
 export {
   cgroupCpuQuota,
   cgroupMemoryLimitBytes,
@@ -17,5 +42,9 @@ export {
 } from './cgroup.js'
 export { appendTail, createTail, resetTail, tailText, type Tail } from './tail.js'
 export { ulid } from './ulid.js'
+export { splitTaskId } from './task-id.js'
 export { editDistance, nearMatches, nearest } from './edit-distance.js'
 export { CORE_VERBS, DISPATCHED_VERBS, MOVED_VERBS } from './verbs.js'
+export { isUnsupportedBun, MIN_BUN, unsupportedBunMessage } from './bun-version.js'
+export { executablePath } from './which.js'
+export { procfsIsOwn } from './procfs.js'

package/src/util/paths.ts

@@ -24,13 +24,43 @@ export function relPosix(from: string, to: string): string {
  * baseline joins it onto a dir to get a write prefix, and the deferral
  * eligibility gate compares two of them for overlap. A second copy is
  * how the two would disagree about what a prefix is.
+ *
+ * The spelling is normalized FIRST, here rather than at each call site,
+ * because sharing the function was not enough to make the two callers
+ * agree: the sandbox joins the prefix onto a directory and `path.join`
+ * folds `./`, `//` and `/./` on the way, while the deferral gate compares
+ * the raw strings and does not. So `./out/**` and `out/**` named the same
+ * tree to the resolver, the sandbox and the watcher, and two DIFFERENT
+ * prefixes to the gate — which then deferred a producer a same-project
+ * reader's key could see, moving that key with a transfer flag (item 441,
+ * measured through a real run: `./out/**` keyed the consumer two ways).
+ * Every glob reaching here is user-written, so every one takes the rule.
+ */
+export function staticPrefix(rawGlob: string): string {
+  return prefixOf(normalizeGlob(rawGlob), GLOB_WILDCARDS)
+}
+
+/**
+ * {@link staticPrefix} under `Bun.Glob`'s own alphabet, for a sandbox GRANT:
+ * the grant is expanded by a `Bun.Glob` scan that reads `[ab]` as a class, so
+ * its prefix must stop there too, or `write: ['g/[ab].txt']` would create a
+ * DIRECTORY named `g/[ab].txt`.
  */
-export function staticPrefix(glob: string): string {
+export function grantPrefix(rawGlob: string): string {
+  return prefixOf(normalizeBunGlob(rawGlob), BUN_GLOB_WILDCARDS)
+}
+
+function prefixOf(glob: string, wildcards: RegExp): string {
   // A brace set is a wildcard too: `{dist,build}/**` reaches either dir,
   // and reading it as the literal directory `{dist,build}` gave the
   // sandbox baseline a prefix that exists nowhere (2026-09-10).
-  const wildcardIdx = glob.search(/[*?[\]{}]/)
-  if (wildcardIdx === -1) return glob
+  const wildcardIdx = glob.search(wildcards)
+  // A LITERAL keeps its trailing slash through `normalizeGlob` on purpose
+  // (`asTrees` is what turns `out/` into the tree `out` + `out/**`), but a
+  // prefix with a slash on the end compares as a different string: `out/`
+  // against `out/sub` found no overlap where `out` does. The prefix is a
+  // directory either way. `/` is the root, not a trailing slash.
+  if (wildcardIdx === -1) return glob === '/' ? '/' : glob.replace(/\/+$/, '')
   const head = glob.slice(0, wildcardIdx)
   const lastSep = head.lastIndexOf('/')
   if (lastSep === -1) return '.'
@@ -51,7 +81,7 @@ export function wholeSubtreePrefixes(globs: readonly string[]): string[] | null
   if (globs.length === 0) return null
   const out: string[] = []
   for (const g of globs.map(normalizeGlob)) {
-    const m = /^([^*?[\]{}!]+?)\/\*\*$/.exec(g)
+    const m = /^([^*?{}!]+?)\/\*\*$/.exec(g)
     if (m === null) return null
     const dir = m[1]!.replace(/\/+$/, '')
     if (dir === '' || dir === '.' || dir.startsWith('/') || dir.split('/').includes('..'))
@@ -71,10 +101,122 @@ export function wholeSubtreePrefixes(globs: readonly string[]): string[] | null
  * after an optional `!`; a bare `.` is the empty entry the schema refuses.
  */
 export function normalizeGlob(glob: string): string {
+  return normalizeWith(glob, GLOB_WILDCARDS)
+}
+
+/**
+ * {@link normalizeGlob} for a glob in `Bun.Glob`'s own alphabet (a workspace
+ * member glob, a sandbox grant): the same spellings, but `\[` stays escaped,
+ * since there it is what keeps a bracket from opening a class.
+ */
+export function normalizeBunGlob(glob: string): string {
+  return normalizeWith(glob, BUN_GLOB_WILDCARDS)
+}
+
+function normalizeWith(glob: string, wildcards: RegExp): string {
   const neg = glob.startsWith('!')
   let g = neg ? glob.slice(1) : glob
   g = g.replace(/\/{2,}/g, '/').replace(/(^|\/)(\.\/)+/g, '$1')
   if (g === '.') g = ''
-  if (/[*?[\]{}]/.test(g) && g.endsWith('/')) g = `${g.replace(/\/+$/, '')}/**`
+  // Where a bracket is literal, Turbo's escaped spelling `\[id\]` names the
+  // same path as `[id]`; one spelling is what lets every literal fast path
+  // (string compare, `settleLiterals`, `asTrees`) see it as a literal.
+  if (wildcards === GLOB_WILDCARDS && g.includes('\\')) g = g.replace(/\\([[\]])/g, '$1')
+  if (wildcards.test(g) && g.endsWith('/')) g = `${g.replace(/\/+$/, '')}/**`
   return neg ? `!${g}` : g
 }
+
+/**
+ * True when a pattern carries no wildcard — it names exactly one path.
+ *
+ * The character SET is the whole content: in a task glob `*`, `?` and a
+ * brace alternation are wildcards, so a pattern holding any of them must
+ * be MATCHED, never compared as a string. It lives here, exported, because
+ * four places asked the same question and one of them asked it with a
+ * smaller set: `graph/task-graph.ts` omitted `{}`, so `dist/{a,b}.txt`
+ * counted as a literal and the overlapping-output refusal compared it to
+ * `dist/a.txt` as two unequal strings — the two tasks were accepted and
+ * then deleted each other's outputs, green, every run (item 495). That is
+ * the same divergence `asTrees` was moved here to end in item 442, and the
+ * same one that removed `@vzn/vx-migrate`'s copy of `outputsOverlap` in
+ * item 445.
+ */
+export function isLiteralPattern(glob: string): boolean {
+  return !GLOB_WILDCARDS.test(glob)
+}
+
+/**
+ * The alphabet of a TASK glob (`cache.inputs.files`, `cache.outputs.files`,
+ * `workspaceFiles`), behind {@link isLiteralPattern}, for the callers that
+ * need the POSITION of the first wildcard rather than a verdict. Every site
+ * that asks "must this declaration be matched?" reads this one regex: item
+ * 495 found the fourth copy with a smaller set, and item 577 found the
+ * class written out nine times — a spelling that drifts is how two guards
+ * come to answer differently for one pattern.
+ *
+ * `[` and `]` are NOT in it: a bracket is a literal character in a task
+ * glob, and there are no character classes (item 667). Route directories
+ * are named `[id]` across Next.js, SvelteKit and Astro, and read as a class
+ * `app/[id]/**` matched `app/i/…` and `app/d/…` and never the route: the
+ * file never entered the key (a stale hit) and the output clean deleted an
+ * unrelated `app/i/page.js`. {@link taskGlob} is how such a glob reaches
+ * `Bun.Glob`, whose own alphabet still reads the class.
+ */
+export const GLOB_WILDCARDS = /[*?{}]/
+
+/**
+ * `Bun.Glob`'s own alphabet, the class included, for the globs vx does not
+ * own: package-manager workspace members and `--filter` path globs follow
+ * npm/pnpm semantics, and a sandbox grant's prefix must stop where the scan
+ * that expands the grant (`Bun.Glob`, `MOUNT_WILDCARDS`) sees a wildcard.
+ */
+export const BUN_GLOB_WILDCARDS = /[*?[\]{}]/
+
+/**
+ * Compile a task glob for `Bun.Glob`, with every bare bracket escaped so it
+ * matches itself (item 667). Every task glob is compiled here and nowhere
+ * else: one site that forgot is a route directory that keys nothing.
+ */
+export function taskGlob(pattern: string): Bun.Glob {
+  // A `]` with no `[` before it is already literal to `Bun.Glob`.
+  if (!pattern.includes('[')) return new Bun.Glob(pattern)
+  return new Bun.Glob(pattern.replace(/(?<!\\)[[\]]/g, '\\$&'))
+}
+
+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.
+ *
+ * It lives in `util` rather than beside the resolver because it is not
+ * only the resolver's rule. It decides what a clean DELETES, so the
+ * graph's overlapping-output refusal has to read the same one: while it
+ * did not, `dist` and `dist/app.js` compared as two unequal literals and
+ * the run that wiped `dist/app.js` reported success (item 442). `graph`
+ * may not import `cache`, and a second copy is how the two would
+ * disagree — which is exactly what item 441 measured about
+ * `staticPrefix`.
+ */
+export function asTrees(patterns: readonly string[]): string[] {
+  const out: string[] = []
+  for (const raw of patterns) {
+    const p = normalizeGlob(raw)
+    if (!isLiteralPattern(p)) {
+      out.push(p)
+      continue
+    }
+    const lit = stripTrailingSlash(p)
+    if (lit.length === 0) continue
+    out.push(lit, `${lit}/**`)
+  }
+  return out
+}

package/src/util/procfs.ts

@@ -0,0 +1,20 @@
+// Is `/proc` this process's view of the pid namespace? A procfs mounted
+// for another namespace is a table of strangers: under the sandbox's
+// nested pid namespace vx is pid 2 while `/proc/self` names 7, and
+// `/proc/<our child's pid>` is some other process or none (2026-09-24).
+// Asked once per process: the mount does not change under a run.
+
+import { readlinkSync } from 'node:fs'
+
+let own: boolean | undefined
+
+export function procfsIsOwn(): boolean {
+  if (own === undefined) {
+    try {
+      own = process.platform === 'linux' && readlinkSync('/proc/self') === String(process.pid)
+    } catch {
+      own = false
+    }
+  }
+  return own
+}

package/src/util/settle.ts

@@ -47,9 +47,11 @@ export function killGraceMs(defaultMs: number): number {
 }
 
 /**
- * Await `p`, giving up after `ms`. Returns true when `p` settled first,
+ * Await `p`, giving up after `ms`. Returns true when `p` fulfilled first,
  * false when the deadline won — the caller decides whether a lost result
- * is worth reporting.
+ * is worth reporting. A rejection before the deadline is not a timeout: it
+ * propagates, so the caller reports the failure rather than a hang
+ * (`tests/util-settle.test.ts`).
  */
 export async function settleWithin(p: Promise<unknown>, ms: number): Promise<boolean> {
   let timer: ReturnType<typeof setTimeout> | undefined