@vzn/vx 0.0.631 → 0.0.633

package/src/orchestrator/run-failures.ts

@@ -0,0 +1,192 @@
+// A failed run's task output and the files it names, so an agent reads why
+// a task failed without the terminal (`vx last --format json`, vx-mcp's
+// getFailures). One file per failed run, `<cacheDir>/failures/<runId>.json`,
+// the newest 50 kept: files, not cache.db, so the index layout (and every
+// shared store under it) stays as it was.
+
+import type { Database } from 'bun:sqlite'
+import { mkdirSync, readdirSync, readFileSync, renameSync, rmSync, writeFileSync } from 'node:fs'
+import path from 'node:path'
+import { isGroupTask, type TaskOutcome } from '../graph/index.js'
+import { decodeOutputLog } from './output-log.js'
+import { splitTaskId } from '../util/index.js'
+import { fileLocations, fileMemo, type OutputLocation } from './path-links.js'
+
+/** Failed runs whose output is kept; run ids are UUIDv7, so names sort by age. */
+const KEPT = 50
+
+/** A failed task of a run and what it said. */
+export interface TaskFailure {
+  taskId: string
+  exitCode: number
+  timedOut?: true
+  /** Plain text, bounded, secrets masked; '' when the run kept none. */
+  output: string
+  locations: OutputLocation[]
+}
+
+export interface RunFailures {
+  runId: string
+  tasks: TaskFailure[]
+}
+
+interface StoredFailure extends TaskFailure {
+  project: string
+  task: string
+}
+
+const dirOf = (cacheDir: string): string => path.join(cacheDir, 'failures')
+
+/** Each failed outcome's output as plain text and the files it names. */
+function failuresOf(outcomes: readonly TaskOutcome[]): StoredFailure[] {
+  const isFile = fileMemo()
+  const out: StoredFailure[] = []
+  for (const o of outcomes) {
+    if (o.failedOutput === undefined || isGroupTask(o.node)) continue
+    const output = Bun.stripANSI(
+      decodeOutputLog(o.failedOutput)
+        .map((c) => c.text)
+        .join(''),
+    )
+    out.push({
+      taskId: o.node.id,
+      project: o.node.projectName,
+      task: o.node.taskName,
+      exitCode: o.exitCode,
+      ...(o.timedOut === true ? { timedOut: true as const } : {}),
+      output,
+      locations: fileLocations(output, o.node.projectDir, isFile),
+    })
+  }
+  return out
+}
+
+/**
+ * Write the run's failures, when any outcome carries output, and drop all
+ * but the newest `KEPT` files. Atomic: a reader sees the whole file or none.
+ */
+export function writeRunFailures(
+  cacheDir: string,
+  runId: string,
+  outcomes: readonly TaskOutcome[],
+): void {
+  const tasks = failuresOf(outcomes)
+  if (tasks.length === 0) return
+  const dir = dirOf(cacheDir)
+  mkdirSync(dir, { recursive: true })
+  const file = path.join(dir, `${runId}.json`)
+  const tmp = `${file}.${process.pid}.tmp`
+  writeFileSync(tmp, JSON.stringify({ runId, tasks }))
+  renameSync(tmp, file)
+  const names = readdirSync(dir)
+    .filter((n) => n.endsWith('.json'))
+    .sort()
+  for (const n of names.slice(0, -KEPT)) rmSync(path.join(dir, n), { force: true })
+}
+
+/**
+ * The failed tasks of `runId`, or of the latest failed run when omitted;
+ * null when there is no such run. A failed task the file lacks (an older
+ * run, a write the disk refused) reads `output: ''`, `locations: []`.
+ */
+export function runFailures(cacheDir: string, db: Database, runId?: string): RunFailures | null {
+  const id =
+    runId ??
+    (
+      db
+        .query('SELECT run_id FROM invocations WHERE exit_ok = 0 ORDER BY rowid DESC LIMIT 1')
+        .get() as { run_id: string } | null
+    )?.run_id
+  if (id === undefined) return null
+  const kept = new Map<string, StoredFailure>()
+  try {
+    const stored = JSON.parse(
+      readFileSync(path.join(dirOf(cacheDir), `${id}.json`), 'utf8'),
+    ) as RunFailures & { tasks: StoredFailure[] }
+    for (const t of stored.tasks) kept.set(t.taskId, t)
+  } catch (err) {
+    // No file: the run kept no output.
+    if ((err as NodeJS.ErrnoException).code !== 'ENOENT') throw err
+  }
+  const rows = db
+    .query(
+      `SELECT project, task, exit_code AS exitCode, timed_out AS timedOut FROM runs
+       WHERE run_id = ? AND status = 'failed' ORDER BY id`,
+    )
+    .all(id) as { project: string; task: string; exitCode: number; timedOut: number | null }[]
+  return {
+    runId: id,
+    tasks: rows.map((r) => {
+      const taskId = `${r.project}#${r.task}`
+      const k = kept.get(taskId)
+      return {
+        taskId,
+        exitCode: r.exitCode,
+        ...(r.timedOut === 1 ? { timedOut: true as const } : {}),
+        output: k?.output ?? '',
+        locations: k?.locations ?? [],
+      }
+    }),
+  }
+}
+
+/** One task's output in a recorded run, as `vx last --log` and getTaskLog read it. */
+export interface TaskLog {
+  runId: string
+  taskId: string
+  status: string
+  /**
+   * Where the output came from: the run's kept failure output, the cache
+   * entry the task saved or hit (masked as it was replayed), or null when
+   * vx kept none (an uncached task that passed, a skip).
+   */
+  source: 'failure' | 'cache' | null
+  /** Plain text; '' when `source` is null. The files it names: `runFailures`. */
+  output: string
+}
+
+/**
+ * `taskId`'s output in `runId`, or in the latest run that recorded the
+ * task when omitted; null when no such run recorded it.
+ */
+export function taskLog(
+  cacheDir: string,
+  db: Database,
+  taskId: string,
+  runId?: string,
+): TaskLog | null {
+  const [project, task] = splitTaskId(taskId)
+  if (project === '' || task === '') return null
+  const row = db
+    .query(
+      `SELECT run_id AS runId, hash, status FROM runs
+       WHERE project = ? AND task = ? AND run_id IS NOT NULL ${runId === undefined ? '' : 'AND run_id = ?'}
+       ORDER BY id DESC LIMIT 1`,
+    )
+    .get(...(runId === undefined ? [project, task] : [project, task, runId])) as {
+    runId: string
+    hash: string
+    status: string
+  } | null
+  if (row === null) return null
+  const base = { runId: row.runId, taskId, status: row.status }
+  if (row.status === 'failed') {
+    const kept = runFailures(cacheDir, db, row.runId)?.tasks.find((t) => t.taskId === taskId)
+    if (kept !== undefined && kept.output !== '') {
+      return { ...base, source: 'failure', output: kept.output }
+    }
+  } else if (row.hash !== '') {
+    const stored = db.query('SELECT stdout FROM entry_stdout WHERE hash = ?').get(row.hash) as {
+      stdout: string
+    } | null
+    if (stored !== null) {
+      const output = Bun.stripANSI(
+        decodeOutputLog(stored.stdout)
+          .map((c) => c.text)
+          .join(''),
+      )
+      return { ...base, source: 'cache', output }
+    }
+  }
+  return { ...base, source: null, output: '' }
+}

package/src/orchestrator/run-records.ts

@@ -14,8 +14,11 @@ import { isCacheHit, taskTelemetryOf, type TaskTelemetry } from './telemetry.js'
 
 export interface RunRecordsInput {
   outcomes: readonly TaskOutcome[]
-  /** Tasks that ran behind a failed dependency (`--continue=always`). */
-  tainted?: ReadonlySet<string>
+  /**
+   * Tasks that ran behind a failed dependency (`--continue=always`) or one
+   * `--exclude-dependencies` dropped, each with the task at the root of it.
+   */
+  tainted?: ReadonlyMap<string, string>
   runId: string
   /** Wall-clock ms at run start; every per-task ns offset is anchored to it. */
   startedAtMs: number
@@ -67,12 +70,9 @@ export function assembleRunRecords(input: RunRecordsInput): RunRecords {
     // aborted (killed by a shutdown signal) isn't a real run.
     if (o.status === 'aborted') continue
     if (input.withTelemetry) telemetryTasks.push(taskTelemetryOf(o))
+    const blockedBy = o.blockedBy ?? input.tainted?.get(o.node.id)
     runs.push({
-      // A failure behind a failed dependency is recorded keyless (`''`, which
-      // the key readers skip): the flaky list asks a key whether it failed.
-      ...(o.hash !== undefined && !(o.status === 'failed' && input.tainted?.has(o.node.id) === true)
-        ? { hash: o.hash }
-        : {}),
+      ...(o.hash !== undefined ? { hash: o.hash } : {}),
       project: o.node.projectName,
       task: o.node.taskName,
       status: o.status,
@@ -107,7 +107,9 @@ export function assembleRunRecords(input: RunRecordsInput): RunRecords {
       ...(isCacheHit(o.status) ? { restored: o.restored === true } : {}),
       ...(o.attempts !== undefined ? { attempts: o.attempts } : {}),
       cached: o.node.config.cache !== undefined,
-      ...(o.blockedBy !== undefined ? { blockedBy: o.blockedBy } : {}),
+      // A task that ran behind a failure names it too, so the flakiness
+      // projection counts its outcome on no key (failure-mode.ts).
+      ...(blockedBy !== undefined ? { blockedBy } : {}),
       ...(o.timedOut === true ? { timedOut: true as const } : {}),
       ...(o.sandboxViolations !== undefined ? { sandboxViolations: o.sandboxViolations } : {}),
       ...(o.notReady !== undefined ? { notReady: o.notReady } : {}),

package/src/orchestrator/run.ts

@@ -48,13 +48,14 @@ import {
   machineParallelism,
   teardownTimeoutMs,
   secretMask,
+  isFsRefusal,
 } from '../util/index.js'
 import { keyedProjects } from './keyed-projects.js'
 import { isDefaultBuild } from './projects.js'
 import { prepareSandbox } from './sandbox-request.js'
 import type { OutputDirSnapshot, SaveFacts } from './miss-save.js'
 import { admitTasks, taintTracker } from './admission.js'
-import type { ExecuteArgs } from './execute-task.js'
+import { unkeyedGroupOutcome, type ExecuteArgs } from './execute-task.js'
 import { excludedTaint } from './excluded-keys.js'
 import { keyUpstream } from './upstream.js'
 import { busLogger, createEventBus, terminalSubscriber, type EventBus } from './events.js'
@@ -70,6 +71,7 @@ import { formatPersistentList } from './framed-output.js'
 import { createForecast } from './forecast.js'
 import { LocalHistoryProvider } from './history.js'
 import { plan, type RunPlan } from './plan.js'
+import type { AffectedReason } from './affected-tasks.js'
 import { prepareRun, type PreparedRun } from './prepare.js'
 import { acquireRunLock } from './run-lock.js'
 import {
@@ -103,6 +105,7 @@ import {
 } from './local-shortcircuit.js'
 import { deriveStableKeys, probesAfterWrites } from './stable-keys.js'
 
+import { writeRunFailures } from './run-failures.js'
 import { assembleRunRecords } from './run-records.js'
 import {
   hasEnded,
@@ -111,7 +114,12 @@ import {
   shutdownPersistent,
   takeHeldServers,
 } from './persistent.js'
-import { writeRunProfile, writeRunSummary } from './run-artifacts.js'
+import {
+  runSummaryJson,
+  writeRunProfile,
+  writeRunSummary,
+  type RunSummaryJson,
+} from './run-artifacts.js'
 import { createSaveLane } from './save-lane.js'
 import { formatOutcomeTable, formatRunSummary } from './summary.js'
 import { detectFlaky, type FlakyCandidate, type FlakyFinding } from './failure-mode.js'
@@ -316,11 +324,16 @@ export async function run(options: RunOptions): Promise<RunSummary> {
   // See docs/design/event-stream-2026-06.md.
   const terminal =
     options.log === undefined
-      ? defaultLogger(colors, resolveOutputView(options), process.stdout, {
-          coalesce: true,
-          ...(options.tty === true ? { tty: true } : {}),
-          ...(options.forwardArgs !== undefined ? { forwardArgs: options.forwardArgs } : {}),
-        })
+      ? defaultLogger(
+          colors,
+          resolveOutputView(options),
+          options.json === true ? process.stderr : process.stdout,
+          {
+            coalesce: true,
+            ...(options.tty === true ? { tty: true } : {}),
+            ...(options.forwardArgs !== undefined ? { forwardArgs: options.forwardArgs } : {}),
+          },
+        )
       : null
   const sink = options.log ?? terminal!
   // An injected bus already has surfaces subscribed; we add the terminal
@@ -970,7 +983,8 @@ async function runOnBus(
     // dispatch, and the tracker carries it to what is built on it.
     const taintSeeds = new Set(excluded.seeds)
     const taint = taintTracker(options.continueMode === 'always', taintSeeds, nodes)
-    const taintedRan = new Set<string>()
+    // Each task that ran tainted, and the task at the root of it.
+    const taintedRan = new Map<string, string>()
     const dependedOn = new Set<string>()
     for (const n of nodes.values()) for (const d of n.deps) dependedOn.add(d)
 
@@ -995,13 +1009,16 @@ async function runOnBus(
       const probe = reuseProbe ? shortCircuit.preProbed.get(node.id) : undefined
       const upfrontKey = shortCircuit.uncachedKeys.get(node.id)
       const upfrontGroupKey = shortCircuit.groupKeys.get(node.id)
-      if (
-        options.continueMode === 'always' &&
-        node.deps.some((d) => deadServerBehind(nodes, serverDied, d) !== undefined)
-      )
-        taintSeeds.add(node.id)
+      let deadServer: string | undefined
+      if (options.continueMode === 'always') {
+        for (const d of node.deps) {
+          deadServer = deadServerBehind(nodes, serverDied, d)
+          if (deadServer !== undefined) break
+        }
+        if (deadServer !== undefined) taintSeeds.add(node.id)
+      }
       const tainted = taint.judge(node, upstream)
-      if (tainted) taintedRan.add(node.id)
+      if (tainted) taintedRan.set(node.id, deadServer ?? taint.cause(node, upstream))
       const a: ExecuteArgs = {
         node,
         upstream,
@@ -1130,6 +1147,21 @@ async function runOnBus(
           ? Promise.resolve(kept)
           : executeWithDedup(node, keyUpstream(node, upstream))
       },
+      // An unkeyed group runs nothing: settled in place, unless a taint
+      // may ride it, which `buildExecuteArgs` records on dispatch.
+      ...(options.continueMode !== 'always' && taintSeeds.size === 0
+        ? {
+            settleNow: (node: TaskNode, upstream: TaskOutcome[]) =>
+              isGroupTask(node) && node.config.cache === undefined
+                ? unkeyedGroupOutcome(
+                    node,
+                    keyUpstream(node, upstream),
+                    shortCircuit.groupKeys.get(node.id),
+                    runStartHrTimeNs,
+                  )
+                : undefined,
+          }
+        : {}),
       // A `schedule` plugin's weights; the scheduler keeps its structural
       // baseline as the tie-break. Empty map → baseline only.
       ...(prepared.priorities.size > 0 ? { priorities: prepared.priorities } : {}),
@@ -1232,7 +1264,20 @@ async function runOnBus(
     // change the run's exit code — the run already happened.
     // Written again after the keep-alive wait: a kept server's crash or a
     // Ctrl-C there is the process's exit, and the first write said ok.
+    let json: RunSummaryJson | undefined
     const summarize = async (runOk: boolean, final = list): Promise<void> => {
+      if (options.json === true) {
+        json = runSummaryJson({
+          runId,
+          startedAtMs: endedAtMsAtStart,
+          endedAtMs,
+          totalMs,
+          ok: runOk,
+          ...(stoppedBy !== undefined && { exitCode: signalExitCode(stoppedBy) }),
+          outcomes: final,
+          flaky,
+        })
+      }
       if (options.summarize === undefined) return
       // The rewrite after the keep-alive wait says nothing: the footer is
       // the run's last word.
@@ -1319,8 +1364,21 @@ async function runOnBus(
     // cache closes: its history is written once the wait has decided, or it
     // read `ok` over the exit 1 and fed the flaky list a pass (X-23).
     const historyAfterWait = keepAlive.children.length > 0 && !hold && stoppedBy === undefined
-    if (stoppedBy === undefined && !historyAfterWait)
+    // A failed task's output, for `vx last` and an agent: files beside the
+    // index, so a refused write (a full disk, a read-only cache dir) costs
+    // only that output.
+    const recordFailures = (final: readonly TaskOutcome[]): void => {
+      try {
+        writeRunFailures(prepared.cacheDir, runId, final)
+      } catch (err) {
+        if (!isFsRefusal(err)) throw err
+        log.status(`[vx] failed tasks' output not kept: ${err.message} — the verdict above stands`)
+      }
+    }
+    if (stoppedBy === undefined && !historyAfterWait) {
       recordHistory(() => cache.recordRunBundle(records))
+      recordFailures(list)
+    }
     mark('record history')
     // Drain any still-in-flight background prefetches before closing the
     // cache handle — a prefetch ingesting into a closed SQLite DB would
@@ -1533,11 +1591,12 @@ async function runOnBus(
             local.close()
           }
         })
+        recordFailures(final)
       }
-      return { ok: ok && first.code === 0, outcomes: final }
+      return { ok: ok && first.code === 0, outcomes: final, ...(json && { json }) }
     }
 
-    return { ok, outcomes: list }
+    return { ok, outcomes: list, ...(json && { json }) }
   } finally {
     // Idempotent. The status-line ticker starts in runStart, and every
     // call between it and the success path's runEnd is crash-isolated
@@ -1627,7 +1686,8 @@ export async function planRun(options: RunOptions): Promise<RunPlan> {
   // The plan is the product and goes to stdout (`--dry=json` is parsed):
   // what a stage says on the way goes to stderr (C-6).
   const log = options.log ?? defaultLogger(undefined, undefined, process.stderr)
-  const prepared = await prepareRun(options, log)
+  const reasons = new Map<string, AffectedReason>()
+  const prepared = await prepareRun({ ...options, affectedReasons: reasons }, log)
   try {
     if (prepared.unresolvedTasks.length > 0) {
       return {
@@ -1675,6 +1735,10 @@ export async function planRun(options: RunOptions): Promise<RunPlan> {
       ...(await planRestorable(prepared, policy, options.forwardArgs)),
     })
     mark('plan')
+    for (const t of planned.tasks) {
+      const why = reasons.get(t.node.id)
+      if (why !== undefined) t.affected = why
+    }
     return planned
   } finally {
     // The plan called the cache and executor factories; teardown releases
@@ -1861,7 +1925,7 @@ export function projectNamed(
 /** The executed, keyed outcomes of a run — what flakiness is judged on. */
 function flakyCandidates(
   outcomes: readonly TaskOutcome[],
-  tainted: ReadonlySet<string>,
+  tainted: ReadonlyMap<string, string>,
 ): FlakyCandidate[] {
   const out: FlakyCandidate[] = []
   for (const o of outcomes) {
@@ -1871,9 +1935,10 @@ function flakyCandidates(
     // and runs every time, so one bad network day would read as a flake for
     // thirty days. Groups do no work.
     if (o.hash === undefined || o.node.config.cache === undefined || isGroupTask(o.node)) continue
-    // Behind a failed dependency the failure is the dependency's: the key it
-    // had passed on read as a flake for thirty days.
-    if (o.status === 'failed' && tainted.has(o.node.id)) continue
+    // Behind a failed dependency the outcome is not the key's: a failure is
+    // the dependency's, and a pass built on bytes the key never named, so a
+    // later failure relapsed from it and read as a flake for thirty days.
+    if (tainted.has(o.node.id)) continue
     out.push({
       project: o.node.projectName,
       task: o.node.taskName,

package/src/orchestrator/task-hash.ts

@@ -411,8 +411,8 @@ function hashTaskConfig(cfg: TaskConfig, hashCache?: HashCache): string {
  * in place. Its one behavioural case is a config with NO `exec`, where
  * the spread would add `exec: {}` — and nothing reaches here that way,
  * proven by throwing on a no-exec config and running the whole suite:
- * a group takes `computeGroupKey`, and the one keyed group (the default
- * `build`) declares no `remote`. `timeout`/`retries` stay folded — their keys are
+ * a group takes `computeGroupKey`, and a keyed group has no `exec`, so no
+ * `remote`. `timeout`/`retries` stay folded — their keys are
  * distinct by design (see the decision log); stripping them retroactively
  * would bump CACHE_VERSION.
  */
@@ -423,8 +423,8 @@ function hashableConfig(cfg: TaskConfig): unknown {
 }
 
 /**
- * A group's key: its upstream, and for a keyed group — the default
- * `build` (projects.ts), the one group with `cache` — its own inputs too,
+ * A group's key: its upstream, and for a keyed group — one with `cache`,
+ * the default `build` (projects.ts) or a config's — its own inputs too,
  * the way a task's key folds them.
  */
 export async function computeGroupKey(args: ComputeHashArgs): Promise<string> {

package/src/orchestrator/terminal-signals.ts

@@ -43,3 +43,19 @@ export function notifyEscape(text: string): string {
   // eslint-disable-next-line no-control-regex -- the control range is the point
   return `\x1b]9;${text.replace(/[\x00-\x1f\x7f]/g, ' ')}\x07`
 }
+
+/**
+ * Whether the terminal `env` names opens OSC 8 links. A terminal that does
+ * not know the sequence may print it, so only ones known to read it get it;
+ * tmux and screen pass it through only when configured to.
+ */
+export function terminalLinks(env: Readonly<Record<string, string | undefined>>): boolean {
+  if (env['TMUX'] !== undefined || env['STY'] !== undefined) return false
+  const program = env['TERM_PROGRAM']
+  if (program === 'tmux' || program === 'screen') return false
+  if (program === 'ghostty' || program === 'WezTerm' || program === 'vscode') return true
+  if (program === 'iTerm.app') return atLeast(env['TERM_PROGRAM_VERSION'], 3, 1)
+  if (env['WT_SESSION'] !== undefined || env['KITTY_WINDOW_ID'] !== undefined) return true
+  if (env['KONSOLE_VERSION'] !== undefined) return true
+  return Number(env['VTE_VERSION'] ?? 0) >= 5000
+}

package/src/orchestrator/upstream.ts

@@ -1,6 +1,7 @@
 import {
   DependencySpecError,
   compileTaskPattern,
+  isGroupTask,
   isTaskPattern,
   parseDependencySpec,
   type DependencySpec,
@@ -76,6 +77,69 @@ export function filterUpstreamHashes(
   ])
 }
 
+/**
+ * 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.cache?.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}: cache.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}: cache.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
@@ -123,16 +187,7 @@ export function selectFoldedDeps(
 ): FoldCandidate[] {
   if (filter === undefined) return [...deps]
 
-  const specs: DependencySpec[] = filter.map((raw) => {
-    try {
-      return parseDependencySpec(raw)
-    } catch (err) {
-      if (err instanceof DependencySpecError) {
-        throw new UserError(`${selfTaskId}: cache.inputs.tasks: ${err.message}`)
-      }
-      throw err
-    }
-  })
+  const specs: DependencySpec[] = filter.map((raw) => parseSpec(raw, selfTaskId))
 
   // Per-spec predicate, compiled once (exact compares + patterns).
   const matchers = specs.map((spec) => specMatcher(spec))

package/src/util/errors.ts

@@ -7,12 +7,66 @@ import { realpathSync } from 'node:fs'
 import os from 'node:os'
 
 export class UserError extends Error {
-  constructor(message: string) {
+  /**
+   * What an agent branches on: `VX_E_…`, printed by a verb that answers
+   * JSON (`errorDocument`). The message is prose and may change; a code
+   * does not. `VX_E_REFUSED` is any refusal without a code of its own.
+   */
+  readonly code: string
+  // Two signatures, not an optional parameter: the package-api record
+  // keeps the one-argument form every plugin already calls.
+  constructor(message: string)
+  constructor(message: string, code: string)
+  constructor(message: string, code = 'VX_E_REFUSED') {
     super(message)
     this.name = 'UserError'
+    this.code = code
   }
 }
 
+// A refusal that opens with the config that caused it: the schema's
+// `<file>: tasks.<name> …` and the loader's `<file> has unknown field …`.
+const CONFIG_REFUSAL = /^\/\S*\/vx\.(?:config|workspace)\.[cm]?[jt]s\b/
+
+/**
+ * The stable code of anything `bin.ts` catches. A UserError's own, but
+ * `VX_E_CONFIG` for a codeless one that names its config file; then the
+ * environment's refusals; anything else is a defect, `VX_E_INTERNAL`. A
+ * UserError from another copy of core has no `code` when that copy
+ * predates it.
+ */
+export function errorCode(err: unknown): string {
+  if (isUserError(err)) {
+    const code = (err as { code?: unknown }).code
+    if (typeof code === 'string' && code !== 'VX_E_REFUSED') return code
+    return CONFIG_REFUSAL.test(err.message) ? 'VX_E_CONFIG' : 'VX_E_REFUSED'
+  }
+  if (isOutOfFds(err)) return 'VX_E_FDS'
+  if (isFsRefusal(err)) return 'VX_E_FS'
+  return 'VX_E_INTERNAL'
+}
+
+/**
+ * Does this argv ask for JSON (`--format json`, `--format=json`,
+ * `--dry=json`)? Then a refusal is a JSON document on stdout too, so a
+ * reader of stdout gets an answer, not nothing. Args after `--` are the
+ * task's, not vx's.
+ */
+export function wantsJson(argv: readonly string[]): boolean {
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i]!
+    if (a === '--') return false
+    if (a === '--format=json' || a === '--dry=json') return true
+    if (a === '--format' && argv[i + 1] === 'json') return true
+  }
+  return false
+}
+
+/** The JSON a verb that answers JSON prints for a refusal: one line. */
+export function errorDocument(code: string, message: string): string {
+  return `${JSON.stringify({ ok: false, error: { code, message } })}\n`
+}
+
 /**
  * `instanceof UserError`, plus the same class arriving from ANOTHER COPY of
  * core. A compiled `vx` binary carries core inside it while a plugin in the

package/src/util/index.ts

@@ -3,6 +3,8 @@
 
 export {
   DISK_FULL_HINT,
+  errorCode,
+  errorDocument,
   fsRefusalHint,
   isDiskFull,
   isFsRefusal,
@@ -17,6 +19,7 @@ export {
   isOutOfFds,
   notAWorkTree,
   OUT_OF_FDS_HINT,
+  wantsJson,
 } from './errors.js'
 export { configErrorFrame } from './config-frame.js'
 export { xxh3, xxh3hex } from './hash.js'