@vzn/vx 0.0.638 → 0.0.640

package/src/cli/watch.ts

@@ -7,7 +7,7 @@
 //
 // The cache does the heavy lifting: re-runs are typically cache hits
 // (input hash matches), so spurious events from edits outside any
-// task's `cache.inputs.files` cost ~tens of ms of orchestrator
+// task's `inputs.files` cost ~tens of ms of orchestrator
 // overhead. We deliberately don't try to filter events through the
 // per-task input globs — the cache key is the source of truth, and
 // filtering would mean re-doing the glob/boundary work on every event.
@@ -61,22 +61,17 @@ const DEBOUNCE_MAX_MS = 1_000
  * the help line and the completions, and a test holds the two together.
  */
 export function watchRefusal(parsed: RunArgs): string | null {
-  if (parsed.dry !== undefined || parsed.graph !== undefined) {
-    return 'vx watch: --dry / --graph are not supported in watch mode'
+  if (parsed.dry !== undefined) {
+    return 'vx watch: --dry is not supported in watch mode'
   }
-  if (parsed.summarize !== undefined || parsed.profile !== undefined) {
-    return 'vx watch: --summarize / --profile are not supported in watch mode (would overwrite per cycle)'
+  if (parsed.profile !== undefined) {
+    return 'vx watch: --profile is not supported in watch mode (would overwrite per cycle)'
   }
-  // All three format ONE run's result and are consumed by `runCmd` alone, so
-  // a watch loop silently ignored them. `--verbosity 0` is not rejected: it
+  // It formats ONE run's result and is consumed by `runCmd` alone, so a
+  // watch loop silently ignored it. `--verbosity 0` is not rejected: it
   // asks for the output watch already gives.
-  if (
-    parsed.report !== undefined ||
-    parsed.reportFile !== undefined ||
-    parsed.verbosity > 0 ||
-    parsed.format !== 'pretty'
-  ) {
-    return 'vx watch: --report / --report-file / --verbosity / --format are not supported in watch mode (they report a single run)'
+  if (parsed.verbosity > 0) {
+    return 'vx watch: --verbosity is not supported in watch mode (it reports a single run)'
   }
   return null
 }
@@ -284,6 +279,7 @@ export async function watchCmd(args: readonly string[]): Promise<number> {
       outputs: swept.outputs,
       inputs: swept.inputs,
       uncached: swept.uncached,
+      namedIgnored: swept.namedIgnored,
       configImports: swept.configImports,
       workspaceConfigImports: swept.workspaceConfigImports,
       fenceDirs: fenceDirs(allProjects),
@@ -306,6 +302,7 @@ export async function watchCmd(args: readonly string[]): Promise<number> {
           outputs: sweep.outputs,
           inputs: sweep.inputs,
           uncached: sweep.uncached,
+          namedIgnored: sweep.namedIgnored,
           configImports: sweep.configImports,
           workspaceConfigImports: sweep.workspaceConfigImports,
           fenceDirs: fenceDirs(all),
@@ -356,6 +353,8 @@ interface WatchLoopArgs {
   inputs: ReadonlyMap<string, ReadonlyArray<readonly string[]>>
   /** Projects whose uncached task may read a git-ignored file: such a path there is still an edit. */
   uncached: ReadonlySet<string>
+  /** Paths a task's inputs name outright: a git-ignored one there is still an edit. */
+  namedIgnored: readonly string[]
   /** Files the configs import: an edit to one outside the watched projects is a cycle that re-reads them. */
   configImports: readonly string[]
   /** Files the workspace config imports: loaded once per process, so an edit is named, not run. */
@@ -384,6 +383,7 @@ interface Rediscovered {
   outputs: ReadonlyMap<string, readonly string[]>
   inputs: ReadonlyMap<string, ReadonlyArray<readonly string[]>>
   uncached: ReadonlySet<string>
+  namedIgnored: readonly string[]
   configImports: readonly string[]
   workspaceConfigImports: readonly string[]
   fenceDirs: readonly string[]
@@ -399,6 +399,7 @@ async function runWatchLoop(args: WatchLoopArgs): Promise<void> {
   let outputs = args.outputs
   let inputs = args.inputs
   let uncached = args.uncached
+  let namedIgnored = args.namedIgnored
   let claimedRootFiles = args.claimedRootFiles
   let configImportFiles = args.configImports
   let wsConfigImportFiles = args.workspaceConfigImports
@@ -572,6 +573,7 @@ async function runWatchLoop(args: WatchLoopArgs): Promise<void> {
     armedAt,
     held: () => held !== undefined,
     uncached: () => uncached,
+    namedIgnored: () => namedIgnored,
     fenced: (ownDir, abs) => fenced(ownDir, abs),
     ...(atArm !== undefined ? { existedAtArm: atArm.listed, trackedAtArm: atArm.tracked } : {}),
   })
@@ -626,6 +628,19 @@ async function runWatchLoop(args: WatchLoopArgs): Promise<void> {
     }
   }
   const stale = (dir: string): boolean => armedAs.get(dir) !== inodeOf(dir)
+  /** The projects the workspace-wide arm names an event by. */
+  let wide: readonly ProjectMeta[] = []
+  // The deepest, as a nested project's file is its own.
+  const ownerOf = (abs: string): ProjectMeta | undefined => {
+    let best: ProjectMeta | undefined
+    for (const proj of wide)
+      if (
+        abs.startsWith(proj.dir + path.sep) &&
+        (best === undefined || proj.dir.length > best.dir.length)
+      )
+        best = proj
+    return best
+  }
   /** The root arm: recursive when workspace-wide or the one stream, else the root's own files only. */
   let rootArm: WatchHandle = CLOSED
   let dotVxArm: WatchHandle = CLOSED
@@ -634,7 +649,8 @@ async function runWatchLoop(args: WatchLoopArgs): Promise<void> {
     if (isIgnoredPath(proj.dir, filename) || fenced(proj.dir, abs)) return
     // A module the config imports from inside the project is the config
     // too: its edit can add an output or a `workspaceFiles` input.
-    if (shapesWatchedSet(filename) || configImportFiles.includes(abs)) reread = true
+    if (shapesWatchedSet(filename) || configImportFiles.includes(abs) || linkChanged(abs))
+      reread = true
     trigger(`${proj.name} ${filename}`, abs)
   }
   const armProject = (proj: ProjectMeta): void => {
@@ -700,7 +716,13 @@ async function runWatchLoop(args: WatchLoopArgs): Promise<void> {
               configImportFiles.includes(abs)
             )
               reread = true
-            trigger(`root ${filename}`, abs)
+            const owner = ownerOf(abs)
+            trigger(
+              owner === undefined
+                ? `root ${filename}`
+                : `${owner.name} ${path.relative(owner.dir, abs)}`,
+              abs,
+            )
           })
         : oneStream
           ? arm(workspaceRoot, true, streamEvent)
@@ -725,6 +747,7 @@ async function runWatchLoop(args: WatchLoopArgs): Promise<void> {
   // (it would cover every project + node_modules + caches). On macOS one
   // recursive stream at the root stands for all of them (`oneStream`).
   const armMode = (watched: readonly ProjectMeta[]): void => {
+    wide = workspaceWide ? watched : []
     if (!workspaceWide) {
       streamed = oneStream ? toStream(watched) : []
       const inStream = new Set(streamed.map((s) => s.proj))
@@ -801,6 +824,65 @@ async function runWatchLoop(args: WatchLoopArgs): Promise<void> {
     armAncestors()
   }
 
+  /**
+   * What each symlink under a watched project points to: the key reads it,
+   * wherever it lies (cache/linked-inputs.ts), and the project's arm hears
+   * only the link. A file target's directory, non-recursive, or a directory
+   * target, recursive; each event names the link. Links are read again when
+   * one comes or goes (`projectEvent`).
+   */
+  const linkArms = new Map<string, { target: string; handle: WatchHandle }>()
+  let links = atArm?.links ?? new Set<string>()
+  let watched = projects
+  /** A link came, went or moved: the set `armLinks` reads is stale. */
+  const linkChanged = (abs: string): boolean => {
+    if (links.has(abs)) return true
+    try {
+      return fs.lstatSync(abs).isSymbolicLink()
+    } catch {
+      return false
+    }
+  }
+  const armLinks = (): void => {
+    const want = new Map<string, { proj: ProjectMeta; real: string; dir: boolean }>()
+    for (const link of links) {
+      let proj: ProjectMeta | undefined
+      for (const p of watched)
+        if (
+          link.startsWith(p.dir + path.sep) &&
+          (proj === undefined || p.dir.length > proj.dir.length)
+        )
+          proj = p
+      if (proj === undefined) continue
+      try {
+        const real = fs.realpathSync(link)
+        want.set(link, { proj, real, dir: fs.statSync(real).isDirectory() })
+      } catch {
+        // Dangling: its target string is all the key reads, and the link's own arm hears that.
+      }
+    }
+    for (const [link, armed] of linkArms) {
+      if (want.get(link)?.real === armed.target) continue
+      armed.handle.close()
+      linkArms.delete(link)
+    }
+    for (const [link, { proj, real, dir }] of want) {
+      if (linkArms.has(link)) continue
+      const name = path.basename(real)
+      const label = `${proj.name} ${path.relative(proj.dir, link)}`
+      try {
+        const handle = arm(dir ? real : path.dirname(real), dir, (filename) => {
+          if (!dir && filename !== name) return
+          trigger(label, link)
+        })
+        linkArms.set(link, { target: real, handle })
+        changes.seed(link)
+      } catch (err) {
+        sayCannot(`cannot watch ${real}`, err)
+      }
+    }
+  }
+
   // Said once, when the loop first arms: a re-arm repeated it after every
   // cycle that re-read the watched set, between task rows. `debug.watch`
   // says each arm on stderr, for whoever needs to see the set change.
@@ -828,6 +910,7 @@ async function runWatchLoop(args: WatchLoopArgs): Promise<void> {
     outputs = next.outputs
     inputs = next.inputs
     uncached = next.uncached
+    namedIgnored = next.namedIgnored
     claimedRootFiles = next.claimedRootFiles
     configImportFiles = next.configImports
     wsConfigImportFiles = next.workspaceConfigImports
@@ -861,6 +944,9 @@ async function runWatchLoop(args: WatchLoopArgs): Promise<void> {
       for (const proj of own) if (!perProject.has(proj.dir)) armProject(proj)
     }
     armImports()
+    watched = next.projects
+    links = gitFiles(workspaceRoot)?.links ?? links
+    armLinks()
     // A new arm proves delivery like the first ones: an edit in the new
     // project right after this cycle is seen, not lost in the gap.
     await pool.proved()
@@ -943,6 +1029,7 @@ async function runWatchLoop(args: WatchLoopArgs): Promise<void> {
   }
   armAncestors()
   armImports()
+  armLinks()
 
   // The orchestrator's own writes never kick the loop: `makeWatchIgnore`
   // closes over the RESOLVED cache dir (relocated or not) and the tasks'

package/src/cli/why.ts

@@ -9,13 +9,13 @@ import { flagHint, formatValue, seeHelp } from './help.js'
 import { splitTaskId } from '../graph/index.js'
 import {
   cacheKeyDiff,
-  explainCacheKeyQuery as explainCacheKey,
+  explainCacheKey,
   inputWriters,
   latestRunId,
   rootCauses,
-  whyDidThisRerunQuery as whyDidThisRerun,
-  resolveRunId,
-} from '../orchestrator/index.js'
+  whyDidThisRerun,
+} from '../history/index.js'
+import { resolveRunId } from '../orchestrator/index.js'
 import { MASKED, nearMatches, printable, refusal, UserError } from '../util/index.js'
 import { findWorkspaceRoot } from '../workspace/index.js'
 import { findCwdProject } from './select.js'
@@ -36,8 +36,10 @@ interface WhyArgs {
  * `tests/why.test.ts`.
  */
 export const WHAT_TO_DO: Readonly<Record<string, string>> = {
-  file: 'an edit re-runs by design; a file the task does not read belongs out of cache.inputs.files',
-  env: "the variable's value moved; one the task does not read belongs out of cache.inputs.env",
+  file: 'an edit re-runs by design; a file the task does not read belongs out of inputs.files',
+  linked:
+    'what the symlink points to changed (the file, or a file under the directory); an edit there re-runs by design',
+  env: "the variable's value moved; one the task does not read belongs out of inputs.env",
   runtime: 'the command printed something else; drop timestamps and paths from its output',
   'ws-runtime':
     'the workspace command printed something else; drop timestamps and paths from its output',
@@ -372,4 +374,4 @@ export async function whyCmd(args: readonly string[]): Promise<number> {
 const ROOTS_SHOWN = 5
 
 const WRITTEN_TODO =
-  'a task that writes a file a key reads re-keys it every run; give that write its own task with the file as an output, or keep the file out of cache.inputs.files'
+  'a task that writes a file a key reads re-keys it every run; give that write its own task with the file as an output, or keep the file out of inputs.files'

package/src/config.ts

@@ -62,12 +62,6 @@ export interface RunSettings {
    * default) skips its dependents, `always` runs them too.
    */
   continue?: 'never' | 'deps-ok' | 'always'
-  /** How long a task that ignores SIGTERM gets before SIGKILL. Omitted → `'2s'`. */
-  killGrace?: Duration
-  /** The bound on each plugin's end-of-run flush and teardown. Omitted → `'3s'`. */
-  teardownTimeout?: Duration
-  /** How long a persistent task may take to match `readyWhen` before vx says it waits. Omitted → `'10s'`. */
-  readyNotice?: Duration
   /**
    * Graph rules checked by `vx lock` and `vx lock --check`, never by a
    * run. Each is on
@@ -116,6 +110,12 @@ export interface CacheSettings {
   inputStability?: InputStability
   /** The `cache.outputs.clean` of every task that does not set its own. */
   outputs?: { clean?: boolean }
+  /**
+   * Which runs keep a failed task's log and the files its outputs left in
+   * the remote: CI runs (`'ci'`, the default), runs off CI (`'local'`), or
+   * both (`'always'`). Only a run whose policy writes a remote keeps any.
+   */
+  upload?: { failures?: 'ci' | 'local' | 'always' }
 }
 
 /** `WorkspaceConfig.lock`. */
@@ -143,12 +143,6 @@ export interface WorkspaceRules {
    * overlapping tasks with no edge are refused either way.
    */
   exclusiveOutputs?: boolean
-  /**
-   * Refuse a task whose input globs can match another task's declared
-   * outputs, so every key is derived before any task runs. Off, such a key
-   * waits for its producer (`caching.md` § Local restore tier).
-   */
-  upfrontKeys?: boolean
   /**
    * Which workspace projects a project may depend on, checked by `vx lock`
    * over each project's direct dependencies (its manifest's and its tasks'
@@ -304,12 +298,18 @@ export interface TaskConfig {
    *   - `'pkg#name'`   — specific package's `name` task; not key-checked.
    */
   dependsOn?: readonly string[]
+  /**
+   * What the task's key folds, whether or not it caches: its dependents
+   * fold that key. A task with `exec` and no `inputs` has no key, so every
+   * task that folds it runs and saves nothing. A group with `inputs` is a
+   * keyed group: its inputs are a key its dependents fold, with no process.
+   */
+  inputs?: InputsConfig
   /**
    * Caching configuration. **Caching is opt-in.** If this field is omitted,
    * the task always runs and nothing is read from or written to the cache.
-   * Provide a `cache` block (with at least `outputs`) to enable caching.
-   * Requires `exec` — a group task can't cache anything because nothing
-   * runs.
+   * Requires `exec` and `inputs`: the key is the task's inputs, and a group
+   * runs nothing to cache.
    */
   cache?: CacheConfig
 }
@@ -330,7 +330,7 @@ export interface TaskConfig {
  * `node_modules`, and through it the real path of every workspace
  * package linked there.
  *
- * `cache` grants no access in either direction: `cache.inputs` says what
+ * `cache` grants no access in either direction: `inputs` says what
  * INVALIDATES a task, `allow` says what it may TOUCH, and deriving one
  * from the other coupled them both ways — a declaration added for
  * caching silently widened the sandbox, and a path the task needed had
@@ -404,7 +404,7 @@ export interface SandboxIgnore {
 export interface SandboxGrants {
   /**
    * Readable paths or globs, added to the baseline — which is
-   * `node_modules`, NOT `cache.inputs.files`. A task that reads its own
+   * `node_modules`, NOT `inputs.files`. A task that reads its own
    * source in the sandbox says so here.
    */
   read?: readonly string[]
@@ -579,8 +579,6 @@ export interface ExecEnv {
 }
 
 export interface CacheConfig {
-  /** What participates in the cache key. */
-  inputs: CacheInputs
   /** What this task produces. Captured for restore on a cache hit. */
   outputs: CacheOutputs
   /**
@@ -640,7 +638,7 @@ export interface CacheOutputs {
   clean?: boolean
 }
 
-export interface CacheInputs {
+export interface InputsConfig {
   /**
    * Project-relative globs. Each entry is a positive glob, or a negation
    * prefixed with `!`. Required: pass a recursive glob to mean "all
@@ -779,8 +777,8 @@ export function defineProject<const T extends ProjectConfig>(
         [K in keyof NonNullable<T['tasks']>]?: Known<NonNullable<T['tasks']>[K], TaskConfig> & {
           dependsOn?: readonly DependsOnEntry<Extract<keyof NonNullable<T['tasks']>, string>>[]
           exec?: Known<At<NonNullable<T['tasks']>[K], 'exec'>, ExecConfig>
+          inputs?: Known<At<NonNullable<T['tasks']>[K], 'inputs'>, InputsConfig>
           cache?: Known<At<NonNullable<T['tasks']>[K], 'cache'>, CacheConfig> & {
-            inputs?: Known<At<At<NonNullable<T['tasks']>[K], 'cache'>, 'inputs'>, CacheInputs>
             outputs?: Known<At<At<NonNullable<T['tasks']>[K], 'cache'>, 'outputs'>, CacheOutputs>
           }
         }

package/src/exec/executor.ts

@@ -53,13 +53,13 @@ export interface InputFile {
  * secrets (cache.db stores only their digests).
  */
 export interface TaskInputs {
-  /** Declared `cache.inputs.files` + `workspaceFiles` (own outputs excluded), sorted by path. */
+  /** Declared `inputs.files` + `workspaceFiles` (own outputs excluded), sorted by path. */
   readonly files: readonly InputFile[]
-  /** Declared `cache.inputs.env` names with their resolved values; `undefined` when unset. */
+  /** Declared `inputs.env` names with their resolved values; `undefined` when unset. */
   readonly env: ReadonlyArray<{ readonly name: string; readonly value: string | undefined }>
-  /** `cache.inputs.runtime` commands and the output that was folded — a toolchain expectation. */
+  /** `inputs.runtime` commands and the output that was folded — a toolchain expectation. */
   readonly runtime: ReadonlyArray<{ readonly command: string; readonly output: string }>
-  /** `cache.inputs.workspaceRuntime`, same shape. */
+  /** `inputs.workspaceRuntime`, same shape. */
   readonly workspaceRuntime: ReadonlyArray<{ readonly command: string; readonly output: string }>
   /**
    * Dependencies whose cache keys are folded. `outputs` lists each one's
@@ -142,7 +142,7 @@ export interface ExecuteRequest {
    * work and returns: a child an executor spawned is not one core can
    * reach (H-10, H-12). One already aborted is work not to start (B-55).
    * Any exit after the timeout's abort, a 0 included, is a timeout. Core
-   * waits the kill grace (`VX_RUN_KILL_GRACE`, 2 s) after the abort, then
+   * waits the kill grace (2 s) after the abort, then
    * settles the attempt without `execute` and abandons it (H-14).
    */
   readonly signal?: AbortSignal

package/src/exec/sandbox-runtime.ts

@@ -2332,7 +2332,7 @@ function outsideWritesHint(
     ? `${refused} The task has its own temp directory, empty at its start: write under ` +
       `$TMPDIR (os.tmpdir() in Node and Bun) instead of a fixed path.`
     : `${refused} If the task needs one, grant its directory, e.g. ` +
-      `\`allow: { write: [${jsString(`${spelled}/`)}] }\`.`
+      `\`allow: { write: [${jsString(spelled.endsWith('/') ? spelled : `${spelled}/`)}] }\`.`
   return { timestamp: new Date(), hint: true, line }
 }
 

package/src/exec/sandbox-violations.ts

@@ -578,7 +578,9 @@ export function refusedWritesOutside(
     if (v.path === undefined || !path.isAbsolute(v.path) || !write || reported(v)) continue
     if (!skip.some((s) => atOrUnder(v.path!, s))) paths.add(v.path)
   }
-  return [...paths]
+  // `mkdir -p ~/.cache/tool` is refused at each directory on its way;
+  // the one it wanted is the deepest.
+  return [...paths].filter((p) => ![...paths].some((q) => q !== p && atOrUnder(q, p)))
 }
 
 /**

package/src/graph/dependency-spec.ts

@@ -1,5 +1,5 @@
 // Parser for the Turbo/Nx-style task-edge micro-syntax used in
-// `dependsOn` and `cache.inputs.tasks`. Returns a small discriminated
+// `dependsOn` and `inputs.tasks`. Returns a small discriminated
 // union the graph builder + cache filter both consume.
 
 export type DependencySpec =
@@ -32,7 +32,7 @@ export function compileTaskPattern(pattern: string): RegExp {
 }
 
 /**
- * Parse one `dependsOn` / `cache.inputs.tasks` entry.
+ * Parse one `dependsOn` / `inputs.tasks` entry.
  *
  *   `name`       → self.name
  *   `^name`      → every dep workspace's `name` task

package/src/graph/folds.ts

@@ -0,0 +1,236 @@
+// Which dependencies a task's key folds (`inputs.tasks`), on the graph
+// alone: the hash path, the sandbox's keyed set and `vx lock`'s
+// input-overlap rule read this one selection, so they cannot drift.
+
+import { UserError } from '../util/index.js'
+import {
+  DependencySpecError,
+  compileTaskPattern,
+  isTaskPattern,
+  parseDependencySpec,
+  type DependencySpec,
+} from './dependency-spec.js'
+import type { TaskNode } from './task-graph.js'
+
+/**
+ * A task is a "group" if it has no `exec` — it exists only to chain
+ * `dependsOn` (an umbrella for `vx run ci`). Group tasks:
+ *   - never spawn a process,
+ *   - never read/write the cache (it's a config error to declare one),
+ *   - never appear in the run summary or `runs` analytics table,
+ *   - render no framed block in the live output.
+ * Six call sites used to repeat `node.config.exec === undefined`;
+ * centralising the predicate prevents that check from drifting.
+ */
+export function isGroupTask(node: TaskNode): boolean {
+  return node.config.exec === undefined
+}
+
+/** `node.deps` less its ordering-only edges: the dependencies a key may fold. */
+export function keyedDeps(node: TaskNode): readonly string[] {
+  const order = node.orderOnly
+  return order === undefined ? node.deps : node.deps.filter((d) => !order.includes(d))
+}
+
+/**
+ * A filter selects among the task's own dependencies, never through a
+ * group: `dependsOn: ['build']` over a group `build` of `build.a` and
+ * `build.b` offers the filter `build`, not its members. A pattern that
+ * matches only a member (`build.*`) therefore selected nothing, and the key stopped moving
+ * with that member's inputs: a stale hit under a green run. Such a spec
+ * is refused, once, over the graph every key site reads. One that matches
+ * nothing anywhere stays legal (a preset's pattern needn't match in every
+ * project). An exact name is refused earlier, at load, unless `dependsOn`
+ * names it (`assertFilterNamesDeclaredDeps`).
+ */
+export function refuseFiltersThroughGroups(nodes: ReadonlyMap<string, TaskNode>): void {
+  for (const node of nodes.values()) {
+    const filter = node.config.inputs?.tasks
+    if (filter === undefined || filter.length === 0) continue
+    const deps = keyedDeps(node).flatMap((id) => nodes.get(id) ?? [])
+    const groups = deps.filter(isGroupTask)
+    if (groups.length === 0) continue
+    for (const raw of filter) {
+      const spec = parseSpec(raw, node.id)
+      if (spec.negated) continue
+      const matches = specMatcher(spec)
+      const hit = (n: TaskNode): boolean => matches(n, n.projectName === node.projectName)
+      if (deps.some(hit)) continue
+      for (const group of groups) {
+        const member = groupMembers(group, nodes).find(hit)
+        if (member === undefined) continue
+        throw new UserError(
+          `${node.id}: inputs.tasks: '${raw}' matches ${member.id} only through the group ${group.id}, so it selects nothing; name '${group.taskName}' or depend on ${member.id} directly`,
+        )
+      }
+    }
+  }
+}
+
+function parseSpec(raw: string, selfTaskId: string): DependencySpec {
+  try {
+    return parseDependencySpec(raw)
+  } catch (err) {
+    if (err instanceof DependencySpecError) {
+      throw new UserError(`${selfTaskId}: inputs.tasks: ${err.message}`)
+    }
+    throw err
+  }
+}
+
+/** Every task a group stands for, through nested groups, each once. */
+function groupMembers(group: TaskNode, nodes: ReadonlyMap<string, TaskNode>): TaskNode[] {
+  const out: TaskNode[] = []
+  const seen = new Set<string>([group.id])
+  const stack = group.deps.toReversed()
+  while (stack.length > 0) {
+    const id = stack.pop()!
+    if (seen.has(id)) continue
+    seen.add(id)
+    const n = nodes.get(id)
+    if (n === undefined) continue
+    out.push(n)
+    if (isGroupTask(n)) stack.push(...n.deps.toReversed())
+  }
+  return out
+}
+
+/**
+ * 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 `inputs.tasks`.
+ *
+ * Patterns (Turbo/Nx micro-syntax + filter extensions):
+ *   '*'         all same-project upstream
+ *   '^*'        all dep-workspace upstream
+ *   'name'      same-project task `name`
+ *   '^name'     `name` task in every dep workspace
+ *   'pkg#name'  specific package's `name` task
+ *   'name.*'    patterns — EITHER half of any form above may contain `*`
+ *               (same glob as dependsOn patterns), including the project
+ *               half of `pkg#name`. A filter that matched literally here
+ *               would silently select ZERO upstream hashes and decouple the
+ *               task from its dependencies — a stale-hit trap, so every
+ *               name is matched through the shared glob.
+ *   '!<form>'   exclude — any of the above with a leading `!`
+ *
+ * Patterns are applied in order; last write wins, so
+ * `['*', '^*', '!^noisy']` reads as "all minus deps' noisy".
+ *
+ * Defaults:
+ *   - `filter === undefined` → every candidate, as given.
+ *   - `filter === []`        → none (fully decoupled).
+ *
+ * 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 selectFoldedDeps(
+  deps: readonly FoldCandidate[],
+  filter: readonly string[] | undefined,
+  selfProjectName: string,
+  selfTaskId: string,
+): FoldCandidate[] {
+  if (filter === undefined) return [...deps]
+
+  const specs: DependencySpec[] = filter.map((raw) => parseSpec(raw, selfTaskId))
+
+  // Per-spec predicate, compiled once (exact compares + patterns).
+  const matchers = specs.map((spec) => specMatcher(spec))
+
+  const selected = new Map<string, FoldCandidate>()
+  for (let i = 0; i < specs.length; i++) {
+    const spec = specs[i]!
+    const matches = matchers[i]!
+    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.values()]
+}
+
+/** Exact-name compare, or the shared `*`-glob when the name is a pattern. */
+function nameMatcher(name: string): (candidate: string) => boolean {
+  if (isTaskPattern(name)) {
+    const re = compileTaskPattern(name)
+    return (candidate) => re.test(candidate)
+  }
+  return (candidate) => candidate === name
+}
+
+/**
+ * Compile one spec into an upstream predicate. BOTH halves of a `pkg#task`
+ * form glob: a filter only ever selects from upstreams that already exist,
+ * so a package pattern is unambiguous here — unlike dependsOn, which must
+ * materialize concrete edges and therefore rejects it.
+ */
+function specMatcher(spec: DependencySpec): (n: TaskNode, isSelf: boolean) => boolean {
+  switch (spec.kind) {
+    case 'wildcardSelf':
+      return (_n, isSelf) => isSelf
+    case 'wildcardDeps':
+      return (_n, isSelf) => !isSelf
+    case 'self': {
+      const task = nameMatcher(spec.task)
+      return (n, isSelf) => isSelf && task(n.taskName)
+    }
+    case 'deps': {
+      const task = nameMatcher(spec.task)
+      return (n, isSelf) => !isSelf && task(n.taskName)
+    }
+    case 'cross': {
+      const project = nameMatcher(spec.project)
+      const task = nameMatcher(spec.task)
+      return (n) => project(n.projectName) && task(n.taskName)
+    }
+  }
+}
+
+/**
+ * The dependencies `node`'s key folds, per the hash path's rules above, as
+ * `keyUpstream` hands them to the key: the scheduled ones less the edges
+ * `--exclude-dependencies` left for order alone, plus the dropped ones it
+ * keys all the same (`excludedUpstream`), whose own dependencies the walk
+ * reads from the run's `keyOnly` map. `node.deps` held the order-only
+ * edges and lacked the dropped ones: the sandbox granted a sibling the key
+ * does not answer for.
+ */
+export function foldedDeps(node: TaskNode, nodeOf: (id: string) => TaskNode): FoldCandidate[] {
+  const candidates: FoldCandidate[] = []
+  for (const id of keyedDeps(node)) {
+    const dep = nodeOf(id)
+    candidates.push({ node: dep, unit: foldUnit(dep) })
+  }
+  for (const { node: dep } of node.excludedUpstream ?? []) {
+    candidates.push({ node: dep, unit: foldUnit(dep) })
+  }
+  if (isGroupTask(node) && node.config.inputs === undefined) return candidates
+  return selectFoldedDeps(candidates, node.config.inputs?.tasks, node.projectName, node.id)
+}
+
+/**
+ * What stands in for a dependency's hash in the dedup: equal exactly when
+ * the hashes are. An exec task's key folds its own id (`task:<id>`), so its
+ * id is enough; a group's hash is a roll-up of its members' ids and hashes
+ * with no id of its own, so two groups over the same members hash alike.
+ * The members are `keyUpstream`'s, which `computeGroupHash` is handed: under
+ * `--exclude-dependencies` `node.deps` holds order-only edges and lacks the
+ * dropped ones, and two groups the key told apart shared a unit.
+ */
+function foldUnit(node: TaskNode): string {
+  if (!isGroupTask(node) || node.config.inputs !== undefined) return `task|${node.id}`
+  const members = [...keyedDeps(node), ...(node.excludedUpstream ?? []).map((u) => u.node.id)]
+  return `group|${members.sort().join('|')}`
+}