@vzn/vx 0.0.18 → 0.0.22

package/src/orchestrator/shell-verdict.ts

@@ -0,0 +1,117 @@
+import { existsSync, readFileSync, statSync } from 'node:fs'
+import { constants as osConstants } from 'node:os'
+import path from 'node:path'
+import { execWord, exitSignal } from '../exec/index.js'
+
+/**
+ * The frame line for a shell verdict the task's own output leaves a mystery.
+ * `sh -c 'exec <word> …'` exits 127 ("not found") and 126 ("cannot
+ * execute"), and its one line names the word and nothing about why: a bare
+ * word is a PATH lookup, and the PATH is vx's (item 257); a word with a
+ * slash is a file, and the file itself says why — missing, a directory, no
+ * execute bit, a `#!` interpreter that is not there (dash and bash 5 say
+ * "not found" and blame the file; bash 3.2 names it itself and exits 1),
+ * or no `#!` line at all (item 258). An exit above 128 is the shell's
+ * report of a death by signal, and the number alone says nothing about
+ * what sent it — the OOM killer, a crash in native code, an abort, a
+ * closed pipe (item 259).
+ */
+export function shellVerdict(args: {
+  code: number
+  command: string
+  cwd: string
+  bins: string[]
+  /** The signal that killed the child when the runner saw one (`RunResult.signal`). */
+  signal?: string | undefined
+}): string | undefined {
+  if (args.code !== 127 && args.code !== 126) return signalVerdict(args.code, args.signal)
+  const word = execWord(args.command)
+  const what = word ?? 'a command in this task'
+  if (word !== undefined && word.includes('/')) {
+    const file = path.resolve(args.cwd, word)
+    return `[vx] exit ${args.code} is the shell's "${args.code === 127 ? 'not found' : 'cannot execute'}": ${word} ${fileVerdict(file)}`
+  }
+  if (args.code === 126) {
+    return `[vx] exit 126 is the shell's "found but cannot execute": ${what} is not executable or is a directory — chmod +x it`
+  }
+  return `[vx] exit 127 is the shell's "command not found": ${what} is not on this task's PATH — vx puts ${args.bins.join(' and ')} first and never a sibling project's bin; install it in this package or at the workspace root`
+}
+
+/** Why the shell could not run a file, read from the file. */
+function fileVerdict(file: string): string {
+  if (!existsSync(file)) {
+    return `does not exist — looked for ${file}, relative to the task's working directory`
+  }
+  let head: string
+  try {
+    const st = statSync(file)
+    if (st.isDirectory()) return 'is a directory'
+    if ((st.mode & 0o111) === 0) return 'is not executable — chmod +x it'
+    head = readFileSync(file, 'latin1').slice(0, 256)
+  } catch (err) {
+    return `could not be read (${(err as Error).message})`
+  }
+  if (!head.startsWith('#!')) {
+    return 'has no #! line, so it ran as a binary the loader refused — add a #! line or build it for this platform'
+  }
+  const nl = head.indexOf('\n')
+  const line = head.slice(2, nl === -1 ? head.length : nl)
+  if (line.endsWith('\r')) {
+    return `exists, and its #! line ends in CRLF, so the interpreter the shell looked for is "${line.trim()}\\r" — convert the file to LF line endings`
+  }
+  const interp = line.trim().split(/\s+/)[0] ?? ''
+  if (interp.startsWith('/') && !existsSync(interp)) {
+    return `exists, and its #! interpreter ${interp} does not — install it or fix the line`
+  }
+  return `exists and is executable, and the shell still could not run it — check its #! line (${line.trim()})`
+}
+
+/** The signal behind an exit above 128, from the runner's own report or the code alone. */
+function signalVerdict(code: number, signal: string | undefined): string | undefined {
+  const signals = osConstants.signals as Partial<Record<string, number>>
+  let name: string | undefined
+  let num: number | undefined
+  if (signal !== undefined) {
+    name = signal
+    num = signals[signal]
+  } else {
+    name = exitSignal(code)
+    num = code - 128
+  }
+  if (name === undefined || num === undefined) return undefined
+  // A SIGINT/SIGTERM the runner saw is a shutdown or an outside stop, and
+  // the orchestrator reverts the task to aborted — that path has its own line.
+  if (signal !== undefined && (signal === 'SIGINT' || signal === 'SIGTERM')) return undefined
+  const why = SIGNAL_WHY[name] ?? 'the process was killed by that signal'
+  const how =
+    signal !== undefined
+      ? `is how the shell reports a death by ${name} (${num})`
+      : `is 128 + ${num}, the shell's report of a death by ${name} in the last command (or that command exited ${code} itself)`
+  return `[vx] exit ${code} ${how}: ${why}`
+}
+
+const SIGNAL_WHY: Record<string, string> = {
+  SIGKILL:
+    "nothing catches it — on Linux the kernel's OOM killer (dmesg, or the memory limit of the container's cgroup) or an explicit kill; vx's own timeout reports itself as a timeout",
+  SIGSEGV:
+    'the program crashed in native code (a native module, or the runtime itself) — re-run the command by hand to reproduce',
+  SIGBUS:
+    'the program crashed in native code (a native module, or the runtime itself) — re-run the command by hand to reproduce',
+  SIGILL:
+    'the program crashed in native code (a native module, or the runtime itself) — re-run the command by hand to reproduce',
+  SIGFPE:
+    'the program crashed in native code (a native module, or the runtime itself) — re-run the command by hand to reproduce',
+  SIGTRAP:
+    "the program hit a breakpoint or a trap instruction — a debugger, or a runtime's fatal check",
+  SIGABRT:
+    "the program aborted itself — an assertion, or an allocator failure (a JS runtime's heap limit reports here)",
+  SIGTERM:
+    "something outside vx asked the process to stop (a runner's cancellation, a container stop, a kill)",
+  SIGINT: 'something outside vx interrupted the process (a Ctrl-C reaching it, a kill -INT)',
+  SIGHUP: 'the process lost its controlling terminal or session (a hangup, a closed SSH session)',
+  SIGPIPE: 'it wrote to a pipe whose reader had gone — a reader in the command left early',
+  SIGXCPU: "a CPU-time limit (ulimit -t, or a sandbox's) was hit",
+  SIGXFSZ: 'a file-size limit (ulimit -f) was hit',
+  SIGSYS: 'a system call was refused — a seccomp filter, or the sandbox',
+  SIGQUIT: 'the process was sent a quit (Ctrl-\\, or a kill -QUIT); a core dump may be beside it',
+}

package/src/orchestrator/signals.ts

@@ -0,0 +1,167 @@
+// A SIGINT/SIGTERM mid-run stops the run the way `RunOptions.signal` does
+// — the scheduler dispatches nothing more, and the signal is forwarded to
+// everything live, SIGKILLed after a bounded grace — then waits, bounded,
+// for run() to leave its own end-of-run path (telemetry flush, each
+// plugin's teardown, the cache close), and exits 128+signo (130/143). A
+// second signal exits at once. Without the forward, a
+// programmatic signal to the vx process alone (CI cancellation,
+// `kill <pid>`) orphans every running child — terminal Ctrl-C only worked
+// via process-group propagation. Without the escalation (added
+// 2026-09-10) a child that traps TERM — a dev server mid-cleanup, a test
+// runner that ignores it — outlived the run that owned it: vx exited
+// 143 and left it running under init. Split from run.ts on 2026-09-10
+// (pure motion); the registries it reads stay with `run()`, which hands
+// them to the runner around every spawn.
+
+import { signalExitCode } from '../exec/index.js'
+import { killGraceMs, settleWithin } from '../util/index.js'
+import { holdGroups, killTree, untilGroupsGone } from '../exec/index.js'
+import type { Logger } from './logger.js'
+
+/**
+ * How long a SIGTERMed child gets before SIGKILL on the way out. The
+ * end-of-run persistent shutdown grants the same two seconds; both read
+ * `VX_KILL_GRACE_MS` (util/settle.ts) so the suites that prove the
+ * escalation do not wait the full grace.
+ */
+export const SIGNAL_SHUTDOWN_GRACE_MS = 2000
+
+type Child = ReturnType<typeof Bun.spawn>
+
+/**
+ * SIGHUP too: a task runs in its own session (kill-tree.ts), so the
+ * terminal closing no longer reaches it — only vx hears the hang-up,
+ * and vx must pass it on or the tree outlives the window.
+ */
+export type StopSignal = 'SIGINT' | 'SIGTERM' | 'SIGHUP'
+
+/** What a teardown sends a task's group before the SIGKILL. */
+export type ForwardedSignal = 'SIGINT' | 'SIGTERM'
+
+/**
+ * The signal a stop forwards to every task group: the one vx received.
+ * A task runs in its own session, so a terminal's Ctrl-C reaches vx
+ * alone; forwarding SIGTERM in its place skipped every SIGINT-only
+ * cleanup — a Node SIGINT listener, a shell's `trap … INT`
+ * (turborepo#444, #12652, #13097 and nx#23585 reproduced on vx,
+ * 2026-09-24). A hang-up forwards SIGTERM: to many servers SIGHUP means
+ * "reload", not "stop". Anything else — an embedder's abort reason that
+ * names no signal — is a SIGTERM.
+ */
+export function forwardedSignal(received: unknown): ForwardedSignal {
+  return received === 'SIGINT' ? 'SIGINT' : 'SIGTERM'
+}
+
+/**
+ * Send `signal` to every child `live()` returns, wait the grace for each one's
+ * process GROUP to go, then SIGKILL every group with a member left and
+ * whatever `live()` returns NOW — re-read, because the run loop may still
+ * be dispatching during the grace and a child spawned after the first
+ * sweep must not survive the second. The group, not the leader: a shell
+ * that dies at once on the SIGTERM ended the wait, and its backgrounded
+ * server was SIGKILLed mid-cleanup or, once the runner had dropped the
+ * shell, not at all. Resolves once the survivors are reaped. The one
+ * teardown behind the process-signal handler below, `RunOptions.signal`,
+ * and the foreground keep-alive.
+ */
+export async function terminateChildren(
+  live: () => Child[],
+  signal: ForwardedSignal = 'SIGTERM',
+  graceMs: number = killGraceMs(SIGNAL_SHUTDOWN_GRACE_MS),
+): Promise<void> {
+  const children = live()
+  // On the group guard's list until the sweep below is done: a shell that
+  // dies on the signal lets its group go while what it forked runs out
+  // the grace (kill-tree.ts, `holdGroups`).
+  const letGo = holdGroups(children)
+  try {
+    for (const child of children) killTree(child, signal)
+    const left = await untilGroupsGone(children, graceMs)
+    const survivors = [...new Set([...left, ...live()])]
+    for (const child of survivors) killTree(child, 'SIGKILL')
+    await Promise.allSettled(survivors.map((c) => c.exited))
+  } finally {
+    letGo()
+  }
+}
+
+export interface SignalForwarding {
+  /** Detach the handlers — in `run()`'s finally, so repeated runs never stack listeners. */
+  remove(): void
+}
+
+export function forwardSignals(args: {
+  /** `RunOptions.handleSignals` — an embedder that owns the process's signals opts out. */
+  enabled: boolean
+  log: Logger
+  cache: { close(): void }
+  /**
+   * Stop the run as `RunOptions.signal` would: the scheduler stops
+   * dispatching and run()'s abort listener tears the children down.
+   */
+  stop: (signal: StopSignal) => void
+  /**
+   * Settles when run() has left its `finally`. A signal waits for it
+   * before exiting: `process.exit` runs no `finally`, and plugin.md
+   * promises a plugin its teardown and a sink its flush at the end of
+   * every run — a Ctrl-C skipped both (item 849).
+   */
+  done: Promise<void>
+  /** How long a signal waits for `done` before it exits anyway. */
+  boundMs: number
+  /** In-flight children; the runner adds and removes each around its spawn. */
+  liveChildren: ReadonlySet<Child>
+  /** Ready persistent tasks the orchestrator owns until the graph finishes. */
+  persistentRegistry: ReadonlyMap<string, Child>
+}): SignalForwarding {
+  const everyChild = (): Child[] => [...args.liveChildren, ...args.persistentRegistry.values()]
+  const exit = (signal: StopSignal): never => {
+    for (const child of everyChild()) killTree(child, 'SIGKILL')
+    try {
+      args.cache.close()
+    } catch {
+      // double-close race with the normal path; we're exiting anyway
+    }
+    process.exit(signalExitCode(signal))
+  }
+  let stopping: StopSignal | undefined
+  const onSignal = (signal: StopSignal): void => {
+    // A second signal during the grace is the user saying "now": SIGKILL
+    // and go. The exit code stays the first signal's — that is the one
+    // that ended the run.
+    if (stopping !== undefined) exit(stopping)
+    stopping = signal
+    // Clear the live worker/status region BEFORE exiting so a TTY isn't
+    // left with a frozen region in the scrollback. runEnd is idempotent
+    // and a no-op for non-TTY loggers.
+    try {
+      args.log.runEnd?.()
+    } catch {
+      // teardown must not throw on the way out
+    }
+    args.stop(signal)
+    void settleWithin(args.done, args.boundMs)
+      // The run's output may still be in the pipe: `process.exit` drops
+      // what a reader has not taken (CLAUDE.md). An empty `write`'s
+      // callback fired early, and a CI-mode run lost 0.8 of 2 MiB (item
+      // 857); `end`'s waits for the pipe on Bun >= 1.4 (bin.ts). Bounded,
+      // for a reader that has gone and never takes it.
+      .then(() => settleWithin(new Promise<void>((r) => process.stdout.end(() => r())), 2_000))
+      .then(() => exit(signal))
+  }
+  const onSigint = (): void => onSignal('SIGINT')
+  const onSigterm = (): void => onSignal('SIGTERM')
+  const onSighup = (): void => onSignal('SIGHUP')
+  if (args.enabled) {
+    process.on('SIGINT', onSigint)
+    process.on('SIGTERM', onSigterm)
+    process.on('SIGHUP', onSighup)
+  }
+  return {
+    remove: () => {
+      process.off('SIGINT', onSigint)
+      process.off('SIGTERM', onSigterm)
+      process.off('SIGHUP', onSighup)
+    },
+  }
+}

package/src/orchestrator/stable-keys.ts

@@ -13,7 +13,10 @@
 
 import { isGroupTask, type TaskNode, type TaskOutcome } from '../graph/index.js'
 import type { CacheLayer, GitFilesCache } from '../cache/index.js'
+import { isLiteralPattern, normalizeGlob, relPosix } from '../util/index.js'
+import { commandWriteReach, mayWriteFingerprint, undeclaredWriteReach } from './sandbox-request.js'
 import { computeGroupHash, computeTaskHash, type HashCache } from './task-hash.js'
+import { filterUpstreamHashes, keyUpstream } from './upstream.js'
 
 export interface DeriveStableKeysArgs {
   nodes: Map<string, TaskNode>
@@ -54,12 +57,57 @@ export async function deriveStableKeys(args: DeriveStableKeysArgs): Promise<Stab
   // dep's accumulated producers fold forward.
   //   - outputProjects: the project names of every upstream task declaring
   //     cache.outputs.files (project-relative outputs land in the producer's
-  //     own dir).
+  //     own dir), and of every upstream with no cache block that may write
+  //     in its own project (`undeclaredWriteReach`, item 743). A bitset over
+  //     project indexes: a union per dep was a string Set copied tasks ×
+  //     deps × projects times, 101 ms of a 513 ms warm run at 476 packages
+  //     (item 744).
   //   - wsOutputUpstream: any upstream declares cache.outputs.workspaceFiles
-  //     (root-anchored, boundary-ignoring outputs).
-  const outputProjectsById = new Map<string, ReadonlySet<string>>()
+  //     (root-anchored, boundary-ignoring outputs), or has no cache block
+  //     and a sandbox write grant elsewhere in the workspace, or may rewrite
+  //     a file the workspace fingerprint folds (a root `pnpm install`): every
+  //     key folds that digest, taken once per run.
+  //   - rewritersById / unfoldedById: the projects of every upstream CACHED
+  //     task that may rewrite its own inputs in place (a formatter declaring
+  //     no outputs; `commandWriteReach`), and the subset this task's key does
+  //     not fold. A key that folds the rewriter's covers what it writes — its
+  //     writes are its inputs', which its key names — so only a reader
+  //     folding no path to it (`tasks: []`) is preliminary. A rewriter an
+  //     unfolded dependency covered is still uncovered here: its key is not
+  //     in this one.
+  //   - wsRewriters: the same for a cached rewriter whose reach is every
+  //     project (a write grant elsewhere in the workspace, or a fingerprinted
+  //     file, `mayWriteFingerprint`); one this key does not fold makes it
+  //     preliminary. A dependency this key folds needs no pass-through here:
+  //     a keyed task with such a rewriter unfolded is unstable itself, and
+  //     instability is inherited below.
+  const projects = new ProjectIndex(args.nodes)
+  const outputProjectsById = new Map<string, ProjectSet>()
+  const rewritersById = new Map<string, ProjectSet>()
+  const unfoldedById = new Map<string, ProjectSet>()
+  const wsRewriters = new Set<string>()
+  // A cached rewriter matters only to a key that leaves a dependency's key
+  // out: a `cache.inputs.tasks` filter, or a persistent dependency, which
+  // has no key. With neither in the graph every edge folds and the sets
+  // above stay empty, so they are not built (about 2 ms, median, of a 27 ms
+  // memoised walk over the 3,000-task bench; item 750).
+  let anyUnfolded = false
+  for (const n of args.nodes.values()) {
+    if (n.config.cache?.inputs?.tasks !== undefined || n.config.exec?.persistent !== undefined) {
+      anyUnfolded = true
+      break
+    }
+  }
   const wsOutputUpstreamById = new Map<string, boolean>()
   const stableKeys: StableKey[] = []
+  // Workspace-relative project dirs, for the reach test of a
+  // `workspaceFiles` reader against its upstream producers.
+  const dirByProject = new Map<string, string>()
+  for (const node of args.nodes.values()) {
+    if (!dirByProject.has(node.projectName)) {
+      dirByProject.set(node.projectName, relPosix(args.workspaceRoot, node.projectDir))
+    }
+  }
 
   for (const id of order) {
     const node = args.nodes.get(id)!
@@ -67,19 +115,68 @@ export async function deriveStableKeys(args: DeriveStableKeysArgs): Promise<Stab
 
     // Fold every dep's accumulated producers + the dep's own declared
     // outputs into this node's transitive-upstream producer sets.
-    const outputProjects = new Set<string>()
+    const outputProjects = projects.empty()
+    let rewriters: ProjectSet | undefined
+    let unfolded: ProjectSet | undefined
+    let folds: ((dep: string) => boolean) | undefined
+    let wsRewriter = false
+    let wsUnfoldedHere = false
     let wsOutputUpstream = false
     for (const dep of node.deps) {
       const depNode = args.nodes.get(dep)
       if (!depNode) continue
-      for (const p of outputProjectsById.get(dep) ?? []) outputProjects.add(p)
+      const upstreamOfDep = outputProjectsById.get(dep)
+      if (upstreamOfDep !== undefined) outputProjects.addAll(upstreamOfDep)
       if (wsOutputUpstreamById.get(dep) === true) wsOutputUpstream = true
       const depOut = depNode.config.cache?.outputs
       if ((depOut?.files?.length ?? 0) > 0) outputProjects.add(depNode.projectName)
       if ((depOut?.workspaceFiles?.length ?? 0) > 0) wsOutputUpstream = true
+      // An uncached producer declares no outputs, yet a same-project reader
+      // after it (`tasks: []` decouples the key, not the order) read the
+      // bytes it wrote: its key taken up front was the pre-producer one, and
+      // the fourth run of seeds A,B,B,A replayed B over A (turborepo#13788).
+      const reach = undeclaredWriteReach(depNode, args.workspaceRoot)
+      if (reach === 'project') outputProjects.add(depNode.projectName)
+      else if (reach === 'workspace') wsOutputUpstream = true
+      const cached = depNode.config.cache !== undefined
+      if (!cached && mayWriteFingerprint(depNode, args.workspaceRoot)) wsOutputUpstream = true
+      if (!anyUnfolded) continue
+      // The cached twin: a formatter rewriting its own input ahead of a
+      // reader that folds no key of it replayed seed B's build under seed A
+      // on the fourth run, the same way (item 750).
+      const rewrites = cached ? commandWriteReach(depNode, args.workspaceRoot) : 'none'
+      const rewritesWs =
+        cached && (rewrites === 'workspace' || mayWriteFingerprint(depNode, args.workspaceRoot))
+      const rewritersOfDep = rewritersById.get(dep)
+      const wsRewriterOfDep = wsRewriters.has(dep)
+      if (
+        rewritersOfDep === undefined &&
+        rewrites !== 'project' &&
+        !wsRewriterOfDep &&
+        !rewritesWs
+      ) {
+        continue
+      }
+      rewriters ??= projects.empty()
+      if (rewritersOfDep !== undefined) rewriters.addAll(rewritersOfDep)
+      if (rewrites === 'project') rewriters.add(depNode.projectName)
+      if (wsRewriterOfDep || rewritesWs) wsRewriter = true
+      folds ??= foldedBy(node, upstream, keyById)
+      if (folds(dep)) {
+        const unfoldedOfDep = unfoldedById.get(dep)
+        if (unfoldedOfDep !== undefined) (unfolded ??= projects.empty()).addAll(unfoldedOfDep)
+        continue
+      }
+      unfolded ??= projects.empty()
+      if (rewritersOfDep !== undefined) unfolded.addAll(rewritersOfDep)
+      if (rewrites === 'project') unfolded.add(depNode.projectName)
+      if (wsRewriterOfDep || rewritesWs) wsUnfoldedHere = true
     }
     outputProjectsById.set(id, outputProjects)
     wsOutputUpstreamById.set(id, wsOutputUpstream)
+    if (rewriters !== undefined) rewritersById.set(id, rewriters)
+    if (unfolded !== undefined) unfoldedById.set(id, unfolded)
+    if (wsRewriter) wsRewriters.add(id)
 
     if (isGroupTask(node)) {
       // Groups have no exec/cache; they only fold upstream keys so
@@ -91,6 +188,12 @@ export async function deriveStableKeys(args: DeriveStableKeysArgs): Promise<Stab
       continue
     }
 
+    // A persistent task has no key on the live path (its outcome carries no
+    // hash, so a dependent folds nothing of it); recording one here gave
+    // its dependents a second key, which a `--force` or remote run never
+    // saved under.
+    if (node.config.exec?.persistent !== undefined) continue
+
     const hash = await computeTaskHash({
       node,
       upstream,
@@ -106,7 +209,12 @@ export async function deriveStableKeys(args: DeriveStableKeysArgs): Promise<Stab
 
     const unstable =
       node.deps.some((d) => unstableById.has(d)) ||
-      dependsOnSiblingOutputs(node, outputProjects, wsOutputUpstream)
+      dependsOnSiblingOutputs(
+        node,
+        unfolded === undefined ? outputProjects : unfolded.or(outputProjects),
+        wsOutputUpstream || wsUnfoldedHere,
+        dirByProject,
+      )
     if (unstable) unstableById.add(id)
 
     const cacheEnabled = node.config.cache !== undefined
@@ -115,6 +223,28 @@ export async function deriveStableKeys(args: DeriveStableKeysArgs): Promise<Stab
   return stableKeys
 }
 
+/**
+ * Does this task's key fold the dependency's? What `computeTaskHash` folds
+ * (`filterUpstreamHashes` over the same synthetic outcomes); a group folds
+ * every keyed member. A dependency with no key (persistent) is folded by
+ * none.
+ */
+function foldedBy(
+  node: TaskNode,
+  upstream: TaskOutcome[],
+  keyById: Map<string, string>,
+): (dep: string) => boolean {
+  const filter = node.config.cache?.inputs?.tasks
+  if (isGroupTask(node) || filter === undefined) return (dep) => keyById.has(dep)
+  const hashes = new Set(
+    filterUpstreamHashes(upstream, filter, node.projectName, node.id).map(([, h]) => h),
+  )
+  return (dep) => {
+    const h = keyById.get(dep)
+    return h !== undefined && hashes.has(h)
+  }
+}
+
 /**
  * Synthetic upstream outcomes for key derivation. Only `node` + `hash`
  * are read by filterUpstreamHashes / computeGroupHash; the rest of
@@ -137,7 +267,7 @@ function synthUpstream(
       hash: keyById.get(dep),
     } as TaskOutcome)
   }
-  return out
+  return keyUpstream(node, out)
 }
 
 /**
@@ -167,8 +297,9 @@ function synthUpstream(
  */
 export function dependsOnSiblingOutputs(
   node: TaskNode,
-  upstreamOutputProjects: ReadonlySet<string>,
+  upstreamOutputProjects: ProjectNames,
   hasWsOutputUpstream: boolean,
+  dirByProject?: ReadonlyMap<string, string>,
 ): boolean {
   const cache = node.config.cache
   // A cache-disabled task has no key to prefetch anyway; treat as
@@ -184,11 +315,129 @@ export function dependsOnSiblingOutputs(
   // `app` read `gen/**` project-relative), so the mere presence of a
   // workspace-output producer upstream makes the key preliminary.
   if (hasWsOutputUpstream) return true
-  const readsWorkspaceFiles = (cache.inputs?.workspaceFiles?.length ?? 0) > 0
-  if (readsWorkspaceFiles && upstreamOutputProjects.size > 0) return true
+  const wsInputs = cache.inputs?.workspaceFiles ?? []
+  if (wsInputs.length > 0 && upstreamOutputProjects.size > 0) {
+    // Without the dirs the old answer stands: a workspace reader over any
+    // producer is preliminary. With them, only a reader whose globs can
+    // reach a producer's directory is. A Turbo-mapped workspace gives every
+    // task its `globalDependencies` as root literals (`turbo.json`), which
+    // reach no package — classing those as unstable hashed medusa's 83
+    // tasks twice and probed 76 of them lazily (2026-09-11).
+    if (dirByProject === undefined) return true
+    const dirs: string[] = []
+    for (const p of upstreamOutputProjects) {
+      const d = dirByProject.get(p)
+      if (d === undefined) return true
+      dirs.push(d)
+    }
+    return workspaceInputsReach(wsInputs, dirs)
+  }
+  return false
+}
+
+/**
+ * Can any positive `workspaceFiles` entry match a path inside one of
+ * `dirs` (workspace-relative project dirs)? An entry's reach is its
+ * literal prefix — the segments before the first one holding a glob
+ * metacharacter — and it reaches a dir when either is the other's
+ * ancestor or equal. An entry with no literal prefix (`**\/*`) reaches
+ * everything. Conservative on every unknown spelling.
+ */
+export function workspaceInputsReach(
+  workspaceFiles: readonly string[],
+  dirs: readonly string[],
+): boolean {
+  for (const raw of workspaceFiles) {
+    if (raw.startsWith('!')) continue
+    const entry = normalizeGlob(raw)
+    const segments = entry.split('/')
+    const literal: string[] = []
+    for (const seg of segments) {
+      if (!isLiteralPattern(seg)) break
+      literal.push(seg)
+    }
+    if (literal.length === 0) return true
+    const prefix = literal.join('/')
+    for (const dir of dirs) {
+      if (dir === '' || dir === '.') return true
+      if (prefix === dir || prefix.startsWith(`${dir}/`) || dir.startsWith(`${prefix}/`))
+        return true
+    }
+  }
   return false
 }
 
+/** What the stability gate reads of a set of project names. */
+interface ProjectNames extends Iterable<string> {
+  has(name: string): boolean
+  readonly size: number
+}
+
+/** Every project of the graph, numbered, so a set of them is a bitset. */
+class ProjectIndex {
+  readonly names: string[] = []
+  readonly indexOf = new Map<string, number>()
+  readonly words: number
+
+  constructor(nodes: Map<string, TaskNode>) {
+    for (const node of nodes.values()) {
+      if (this.indexOf.has(node.projectName)) continue
+      this.indexOf.set(node.projectName, this.names.length)
+      this.names.push(node.projectName)
+    }
+    this.words = (this.names.length + 31) >>> 5
+  }
+
+  empty(): ProjectSet {
+    return new ProjectSet(this, new Uint32Array(this.words))
+  }
+}
+
+class ProjectSet implements ProjectNames {
+  constructor(
+    private readonly index: ProjectIndex,
+    private readonly bits: Uint32Array,
+  ) {}
+
+  add(name: string): void {
+    const i = this.index.indexOf.get(name)!
+    this.bits[i >>> 5]! |= 1 << (i & 31)
+  }
+
+  addAll(other: ProjectSet): void {
+    for (let w = 0; w < this.bits.length; w++) this.bits[w]! |= other.bits[w]!
+  }
+
+  or(other: ProjectSet): ProjectSet {
+    const bits = this.bits.slice()
+    for (let w = 0; w < bits.length; w++) bits[w]! |= other.bits[w]!
+    return new ProjectSet(this.index, bits)
+  }
+
+  has(name: string): boolean {
+    const i = this.index.indexOf.get(name)
+    return i !== undefined && (this.bits[i >>> 5]! & (1 << (i & 31))) !== 0
+  }
+
+  get size(): number {
+    let n = 0
+    for (const word of this.bits) {
+      let v = word
+      while (v !== 0) {
+        v &= v - 1
+        n++
+      }
+    }
+    return n
+  }
+
+  *[Symbol.iterator](): Iterator<string> {
+    for (let i = 0; i < this.index.names.length; i++) {
+      if ((this.bits[i >>> 5]! & (1 << (i & 31))) !== 0) yield this.index.names[i]!
+    }
+  }
+}
+
 function topoOrder(nodes: Map<string, TaskNode>): string[] {
   const indegree = new Map<string, number>()
   const dependents = new Map<string, string[]>()