@vzn/vx 0.0.631 → 0.0.632

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/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'

package/src/util/secret-mask.ts

@@ -32,6 +32,12 @@ export function secretNamed(name: string): boolean {
   return secret
 }
 
+/**
+ * A URL's password (`postgres://app:<pw>@db/app`): a credential whatever
+ * the variable is named, so `DATABASE_URL` and `REDIS_URL` printed it.
+ */
+const URL_PASSWORD = /[a-z][a-z0-9+.-]*:\/\/[^\s:/@]*:([^\s/@]+)@/gi
+
 /**
  * Values shorter than this are not masked: `KEY=1` would mask every `1`
  * in every line, and a value that short is no secret worth the noise.
@@ -86,7 +92,13 @@ export function secretMask(
   }
   for (const source of sources) {
     if (source === undefined) continue
-    for (const name in source) if (secretNamed(name)) add(source[name])
+    for (const name in source) {
+      const value = source[name]
+      if (secretNamed(name)) add(value)
+      if (value?.includes('://') === true && value.includes('@')) {
+        for (const m of value.matchAll(URL_PASSWORD)) add(m[1])
+      }
+    }
     for (const name of named) add(source[name])
   }
   if (values.size === 0) return null

package/src/workspace/workspace.ts

@@ -165,6 +165,7 @@ export async function findWorkspaceRoot(
     `Could not find a workspace root in any parent of ${start} ` +
       `(looked for pnpm-workspace.yaml or package.json): run vx inside a project, ` +
       `or create a package.json (\`bun init\` or \`npm init -y\`) and run \`vx init\``,
+    'VX_E_NO_WORKSPACE',
   )
 }