@vzn/vx 0.0.631 → 0.0.633

package/src/cli/run.ts

@@ -3,7 +3,7 @@ import path from 'node:path'
 import { isatty } from 'node:tty'
 import { findWorkspaceRoot } from '../workspace/index.js'
 import { translateForeign } from './foreign-flags.js'
-import { flagHint, seeHelp } from './help.js'
+import { flagHint, formatValue, refuse, seeHelp } from './help.js'
 import {
   planRun,
   formatRunReportMarkdown,
@@ -69,6 +69,8 @@ export interface RunArgs {
   forwardArgs: string[]
   verbosity: number
   dry: 'text' | 'json' | undefined
+  /** `--format json`: the run's result document on stdout, every other line on stderr. */
+  format: 'pretty' | 'json'
   graph: string | undefined
   summarize: string | undefined
   profile: string | undefined
@@ -132,6 +134,7 @@ export function parseRunArgs(rawArgs: readonly string[], verb: 'run' | 'watch' =
     forwardArgs: [],
     verbosity: 0,
     dry: undefined,
+    format: 'pretty',
     graph: undefined,
     summarize: undefined,
     profile: undefined,
@@ -342,6 +345,10 @@ export function parseRunArgs(rawArgs: readonly string[], verb: 'run' | 'watch' =
         return { ...out, error: `--dry must be text or json (got ${fmt})` }
       }
       out.dry = fmt
+    } else if (a === '--format' || a?.startsWith('--format=')) {
+      const f = formatValue(a === '--format' ? before[++i] : a.slice('--format='.length), verb)
+      if (typeof f !== 'string') return { ...out, error: f.error }
+      out.format = f
     } else if (a === '--graph') {
       out.graph = ''
     } else if (a?.startsWith('--graph=')) {
@@ -429,6 +436,21 @@ export function parseRunArgs(rawArgs: readonly string[], verb: 'run' | 'watch' =
   if (out.graph !== undefined && needsRun) {
     return { ...out, error: `--graph skips execution; ${runOnly}` }
   }
+  if (out.format === 'json') {
+    // Each of these prints something else on stdout, which the document owns.
+    if (out.dry !== undefined)
+      return { ...out, error: '--format json runs the tasks; --dry=json prints the plan' }
+    if (out.graph === '')
+      return {
+        ...out,
+        error: '--format json and --graph both print on stdout; give --graph a file',
+      }
+    if (out.report === 'markdown')
+      return {
+        ...out,
+        error: '--format json and --report=markdown both print on stdout; use --report-file',
+      }
+  }
   return out
 }
 
@@ -614,6 +636,7 @@ export async function resolveRunOptions(
   if (parsed.cacheDir !== undefined) opts.cacheDir = parsed.cacheDir
   if (parsed.concurrency !== undefined) opts.concurrency = parsed.concurrency
   if (parsed.summarize !== undefined) opts.summarize = parsed.summarize
+  if (parsed.format === 'json') opts.json = true
   if (parsed.profile !== undefined) opts.profile = parsed.profile
   if (Object.keys(parsed.tags).length > 0) opts.tags = parsed.tags
 
@@ -626,8 +649,7 @@ const TASKS_SHOWN = 12
 export async function runCmd(args: readonly string[]): Promise<number> {
   const parsed = parseRunArgs(args)
   if (parsed.error) {
-    process.stderr.write(`vx run: ${parsed.error}${seeHelp('run')}\n`)
-    return 1
+    return refuse('run', args, `${parsed.error}${seeHelp('run')}`, 'VX_E_USAGE')
   }
 
   const cwd = process.cwd()
@@ -638,7 +660,10 @@ export async function runCmd(args: readonly string[]): Promise<number> {
   // anchored pkg#task; the rest of the pipeline treats it like any
   // explicit anchored positional.
   if (tasks.length === 0) {
-    if (!process.stdin.isTTY) {
+    // A JSON answer is for a program, which cannot pick from a menu: an
+    // agent on a pty waited at the picker forever.
+    const forProgram = parsed.format === 'json' || parsed.dry === 'json'
+    if (!process.stdin.isTTY || forProgram) {
       const names = await taskNamesHere(cwd)
       const shown = (names ?? []).slice(0, TASKS_SHOWN)
       const more = (names?.length ?? 0) - shown.length
@@ -646,10 +671,12 @@ export async function runCmd(args: readonly string[]): Promise<number> {
         shown.length === 0
           ? 'vx run <task>, e.g. vx run build'
           : `tasks here: ${shown.join(', ')}${more > 0 ? ` and ${more} more` : ''}`
-      process.stderr.write(
-        `vx run: missing task name (stdin is not a TTY, so no picker; ${tasksHere})${seeHelp('run')}\n`,
+      return refuse(
+        'run',
+        args,
+        `missing task name (${forProgram ? 'a JSON answer opens' : 'stdin is not a TTY, so'} no picker; ${tasksHere})${seeHelp('run')}`,
+        'VX_E_USAGE',
       )
-      return 1
     }
     // Every run needs git: refused here, not after the user has chosen.
     const refusal = gitRefusal(await findWorkspaceRoot(cwd))
@@ -664,17 +691,11 @@ export async function runCmd(args: readonly string[]): Promise<number> {
     // `--filter` / `--affected` scope the menu, as they scope a bare task:
     // the menu listed every project and the anchored pick ran outside it.
     const scope = await scopeFilters(parsed, cwd)
-    if ('error' in scope) {
-      process.stderr.write(`vx run: ${scope.error}\n`)
-      return 1
-    }
+    if ('error' in scope) return refuse('run', args, scope.error, 'VX_E_USAGE')
     let only: ReadonlySet<string> | undefined
     if (scope.filterStrings.length > 0) {
       const selected = await resolveFilters(cwd, scope.filterStrings, load, scope.affectedFilter)
-      if ('error' in selected) {
-        process.stderr.write(`vx run: ${selected.error}\n`)
-        return 1
-      }
+      if ('error' in selected) return refuse('run', args, selected.error, 'VX_E_USAGE')
       if ('empty' in selected) {
         process.stderr.write(`vx run: ${selected.empty}\n`)
         return 0
@@ -689,10 +710,7 @@ export async function runCmd(args: readonly string[]): Promise<number> {
   }
 
   const resolved = await resolveRunOptions(parsed, cwd, tasks)
-  if ('error' in resolved) {
-    process.stderr.write(`vx run: ${resolved.error}\n`)
-    return 1
-  }
+  if ('error' in resolved) return refuse('run', args, resolved.error, 'VX_E_USAGE')
   if ('nothingSelected' in resolved) {
     process.stderr.write(`vx run: ${resolved.nothingSelected}\n`)
     return 0
@@ -783,8 +801,8 @@ export async function runCmd(args: readonly string[]): Promise<number> {
   // is no whole-run delegation seam to consult.
   const summary = await runOrchestrator(opts)
   if (summary.refused !== undefined) {
-    process.stderr.write(`vx run: ${summary.refused}\n`)
-    return 1
+    const unknown = summary.refused.startsWith('no projects declare')
+    return refuse('run', args, summary.refused, unknown ? 'VX_E_UNKNOWN_TASK' : 'VX_E_REFUSED')
   }
   if (wantsReport) {
     const md =
@@ -816,5 +834,6 @@ export async function runCmd(args: readonly string[]): Promise<number> {
       }
     }
   }
+  if (summary.json !== undefined) process.stdout.write(`${JSON.stringify(summary.json, null, 2)}\n`)
   return summary.ok ? 0 : 1
 }

package/src/cli/show.ts

@@ -10,7 +10,7 @@ import path from 'node:path'
 import type { ProjectConfig, TaskConfig } from '../config.js'
 import { declaredTask } from '../graph/index.js'
 import { affectedTaskProjects, isDefaultBuild } from '../orchestrator/index.js'
-import { flagHint, formatValue, seeHelp } from './help.js'
+import { flagHint, formatValue, refuse, seeHelp } from './help.js'
 import { listed, nearMatches, relPosix, secretMask, UserError } from '../util/index.js'
 import { affectedFilterFor, resolveFilters } from './select.js'
 import {
@@ -82,10 +82,7 @@ export function parseShowArgs(args: readonly string[]): ShowArgs {
 
 export async function showCmd(args: readonly string[]): Promise<number> {
   const parsed = parseShowArgs(args)
-  if (parsed.error) {
-    process.stderr.write(`vx show: ${parsed.error}\n`)
-    return 1
-  }
+  if (parsed.error) return refuse('show', args, parsed.error, 'VX_E_USAGE')
   const reads: LoadReads = new Map()
   const root = await findWorkspaceRoot(process.cwd(), reads)
   const metas = await discoverCliProjects(await loadWorkspace(root, reads))
@@ -98,6 +95,7 @@ export async function showCmd(args: readonly string[]): Promise<number> {
     if (rootMeta === undefined) {
       throw new UserError(
         `vx show: "${parsed.target}" names the workspace root's project, and the root is no project here`,
+        'VX_E_USAGE',
       )
     }
     parsed.target = `${rootMeta.name}${parsed.target.slice(2)}`
@@ -114,12 +112,14 @@ export async function showCmd(args: readonly string[]): Promise<number> {
     const list = projectName === '' ? 'vx show' : `vx show ${projectName}`
     throw new UserError(
       `vx show: missing task name after '#' in "${parsed.target}" (${list} lists the tasks)`,
+      'VX_E_USAGE',
     )
   }
   if (projectName !== undefined && (taskName !== undefined || byName.has(projectName))) {
     if (!byName.has(projectName)) {
       throw new UserError(
         `vx show: unknown project: "${projectName}"${suggest(projectName, [...byName.keys()], '', 'projects')}`,
+        'VX_E_UNKNOWN_PROJECT',
       )
     }
   }
@@ -138,18 +138,19 @@ export async function showCmd(args: readonly string[]): Promise<number> {
     if (scope !== 'all') {
       throw new UserError(
         'vx show: --filter and --affected narrow a list: `vx show` or `vx show <task>`',
+        'VX_E_USAGE',
       )
     }
     const raw = [...parsed.filters]
     let affected: string | undefined
     if (parsed.affected !== undefined) {
       const f = await affectedFilterFor(process.cwd(), parsed.affected)
-      if (typeof f === 'object') throw new UserError(`vx show: ${f.error}`)
+      if (typeof f === 'object') throw new UserError(`vx show: ${f.error}`, 'VX_E_USAGE')
       affected = f
       raw.unshift(f)
     }
     const r = await resolveFilters(process.cwd(), raw, { noCreate: true }, affected)
-    if ('error' in r) throw new UserError(`vx show: ${r.error}`)
+    if ('error' in r) throw new UserError(`vx show: ${r.error}`, 'VX_E_USAGE')
     if ('empty' in r) process.stderr.write(`vx show: ${r.empty}\n`)
     selected = new Set('empty' in r ? [] : r.names)
     if ('names' in r && r.affected !== undefined)
@@ -181,6 +182,7 @@ export async function showCmd(args: readonly string[]): Promise<number> {
       const nx = projectName === 'projects' ? ' (`nx show projects` is `vx show` here)' : ''
       throw new UserError(
         `vx show: unknown project or task: "${projectName}"${nx}${suggest(projectName!, [...byName.keys(), ...names], '', 'projects and tasks')}`,
+        'VX_E_UNKNOWN_TASK',
       )
     }
     let shown = declaring.filter((p) => inSelection(p.name))
@@ -224,6 +226,7 @@ export async function showCmd(args: readonly string[]): Promise<number> {
   if (task === undefined) {
     throw new UserError(
       `vx show: unknown task: "${meta.name}#${taskName}"${suggest(taskName, Object.keys(config?.tasks ?? {}), `${meta.name}#`, 'its tasks')}`,
+      'VX_E_UNKNOWN_TASK',
     )
   }
   process.stdout.write(renderTask(meta.name, dir, taskName, task, parsed.format))

package/src/cli/upgrade.ts

@@ -13,7 +13,7 @@
 // deno upgrade — "update" is what package managers do to indexes.
 
 import { constants } from 'node:fs'
-import { access, chmod, chown, link, rename, rm, stat } from 'node:fs/promises'
+import { access, chmod, chown, link, mkdtemp, rename, rm, stat } from 'node:fs/promises'
 import path from 'node:path'
 import { flagHint, seeHelp } from './help.js'
 import { UserError } from '../util/index.js'
@@ -38,7 +38,7 @@ export function isBunfsPath(p: string): boolean {
  * upgrade` refused with "running from source". `Bun.main` stays the
  * bunfs path under every compile-flag combination.
  */
-function isCompiledBinary(): boolean {
+export function isCompiledBinary(): boolean {
   return (
     isBunfsPath(Bun.main) || isBunfsPath(process.argv[1] ?? '') || isBunfsPath(import.meta.path)
   )
@@ -247,8 +247,20 @@ export async function replaceBinary(
       `vx upgrade: the download did not match the release's SHA-256 (expected ${sha256}, got ${got}) — nothing replaced; try again, and if it repeats the asset is not the one the release published`,
     )
   }
-  const tmp = `${dest}.upgrade-${process.pid}`
-  const old = `${dest}.previous-${process.pid}`
+  // A fresh directory beside the binary, not a name built from the pid:
+  // anyone who can write the install directory could plant a link at a
+  // predictable name, and a `sudo vx upgrade` wrote through it as root.
+  let stage: string
+  try {
+    stage = await mkdtemp(path.join(dir, '.vx-upgrade-'))
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err)
+    throw new UserError(
+      `vx upgrade: could not stage the new binary in ${dir} (${msg}) — nothing replaced; check the permissions of ${dir}`,
+    )
+  }
+  const tmp = path.join(stage, 'new')
+  const old = path.join(stage, 'previous')
   let kept = false
   try {
     const was = await stat(dest).catch(() => null)
@@ -265,18 +277,18 @@ export async function replaceBinary(
     }
     await rename(tmp, dest)
   } catch (err) {
-    await rm(tmp, { force: true })
-    if (kept) await rm(old, { force: true })
+    await rm(stage, { recursive: true, force: true })
     const msg = err instanceof Error ? err.message : String(err)
     throw new UserError(
       `vx upgrade: could not replace ${dest} (${msg}) — nothing replaced; check the permissions of ${dest} and its directory`,
     )
   }
   if (starts === undefined || starts(dest)) {
-    if (kept) await rm(old, { force: true })
+    await rm(stage, { recursive: true, force: true })
     return
   }
   if (kept) await rename(old, dest)
+  await rm(stage, { recursive: true, force: true })
   throw new UserError(
     `vx upgrade: the new binary did not start on this machine (\`${dest} --version\` failed)${kept ? ' — the previous vx is back in place' : ''}. Nothing else changed; report it with this os/arch`,
   )

package/src/cli/watch.ts

@@ -78,8 +78,13 @@ export function watchRefusal(parsed: RunArgs): string | null {
   // 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
   // asks for the output watch already gives.
-  if (parsed.report !== undefined || parsed.reportFile !== undefined || parsed.verbosity > 0) {
-    return 'vx watch: --report / --report-file / --verbosity are not supported in watch mode (they report a single run)'
+  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)'
   }
   return null
 }

package/src/cli/why.ts

@@ -9,12 +9,11 @@ import path from 'node:path'
 import { Cache } from '../cache/index.js'
 import { flagHint, formatValue, seeHelp } from './help.js'
 import { splitTaskId } from '../graph/index.js'
-import type { Database } from 'bun:sqlite'
 import {
-  type CacheKeyDiff,
   cacheKeyDiff,
   explainCacheKeyQuery as explainCacheKey,
   latestRunId,
+  rootCauses,
   whyDidThisRerunQuery as whyDidThisRerun,
   resolveRunId,
 } from '../orchestrator/index.js'
@@ -151,7 +150,10 @@ async function resolveTarget(
   const ids = pairs.map((p) => `${p.project}#${p.task}`)
   const invoked = ids.length === 0 && db.query('SELECT 1 FROM invocations LIMIT 1').get() !== null
   if (target.includes('#')) {
-    throw new UserError(`vx why: no recorded runs for "${target}"${suggest(target, ids, invoked)}`)
+    throw new UserError(
+      `vx why: no recorded runs for "${target}"${suggest(target, ids, invoked)}`,
+      'VX_E_NO_HISTORY',
+    )
   }
   const matches = ids.filter((id) => id.endsWith(`#${target}`))
   if (matches.length === 1) return matches[0]!
@@ -161,10 +163,12 @@ async function resolveTarget(
     throw new UserError(
       `vx why: "${target}" ran in ${matches.length} projects — pick one:\n` +
         matches.map((m) => `  ${m}`).join('\n'),
+      'VX_E_AMBIGUOUS',
     )
   }
   throw new UserError(
     `vx why: no recorded runs for task "${target}"${suggest(target, ids, invoked)}`,
+    'VX_E_NO_HISTORY',
   )
 }
 
@@ -187,9 +191,12 @@ function restoredWord(r: { restored: boolean | null }): string {
 
 export async function whyCmd(args: readonly string[]): Promise<number> {
   const parsed = parseWhyArgs(args)
-  if (parsed.error !== undefined) throw new UserError(`vx why: ${parsed.error}`)
+  if (parsed.error !== undefined) throw new UserError(`vx why: ${parsed.error}`, 'VX_E_USAGE')
   if (parsed.target === undefined) {
-    throw new UserError('vx why: <task> required (e.g. vx why app#build, or vx why build)')
+    throw new UserError(
+      'vx why: <task> required (e.g. vx why app#build, or vx why build)',
+      'VX_E_USAGE',
+    )
   }
 
   const root = await findWorkspaceRoot(process.cwd())
@@ -206,6 +213,7 @@ export async function whyCmd(args: readonly string[]): Promise<number> {
       if (runId === null) {
         throw new UserError(
           `vx why: no recorded run ${parsed.runId} (vx last --list shows recent runs)`,
+          'VX_E_NO_HISTORY',
         )
       }
     } else runId = latestRunId(db, taskId)
@@ -231,6 +239,7 @@ export async function whyCmd(args: readonly string[]): Promise<number> {
     if (!why.found) {
       throw new UserError(
         `vx why: run ${runId} has no row for ${taskId}; \`vx last --list\` shows the recorded runs, \`vx last RUNID\` what one ran`,
+        'VX_E_NO_HISTORY',
       )
     }
     const diff = cacheKeyDiff(db, runId, taskId)
@@ -344,38 +353,3 @@ export async function whyCmd(args: readonly string[]): Promise<number> {
 }
 
 const ROOTS_SHOWN = 5
-
-interface RootCause {
-  /** From the asked task down to the one whose own inputs moved. */
-  chain: string[]
-  entries: CacheKeyDiff['entries']
-}
-
-/**
- * The tasks under `taskId`'s moved upstreams whose OWN key components
- * moved in the same run, each with the chain that carried it up. A task
- * visited once is not walked again (a diamond names its root once).
- */
-function rootCauses(
-  db: Database,
-  runId: string,
-  taskId: string,
-  entries: CacheKeyDiff['entries'],
-): RootCause[] {
-  const roots: RootCause[] = []
-  const seen = new Set([taskId])
-  const walk = (chain: string[], moved: CacheKeyDiff['entries']): void => {
-    for (const e of moved) {
-      if (e.kind !== 'upstream' || seen.has(e.name)) continue
-      seen.add(e.name)
-      const next = [...chain, e.name]
-      const d = cacheKeyDiff(db, runId, e.name)
-      if (!d.found) continue
-      const own = d.entries.filter((x) => x.kind !== 'upstream')
-      if (own.length > 0) roots.push({ chain: next, entries: own })
-      walk(next, d.entries)
-    }
-  }
-  walk([taskId], entries)
-  return roots
-}

package/src/exec/runner.ts

@@ -849,7 +849,7 @@ export function runPersistent(opts: PersistentOptions): PersistentSpawn {
       }
     }
     const reader = stream.getReader()
-    const decoder = new TextDecoder()
+    const decoder = new TextDecoder('utf-8', { ignoreBOM: true })
     try {
       while (true) {
         const { value, done } = await reader.read()
@@ -1097,12 +1097,17 @@ export const CAPTURE_HEAD_CHARS = 8 * 1024 * 1024
 export const CAPTURE_TAIL_CHARS = 8 * 1024 * 1024
 
 const mib = (n: number): string => `${(n / (1024 * 1024)).toFixed(1)} MiB`
+const size = (n: number): string => (n < 1024 * 1024 ? `${n / 1024} KiB` : mib(n))
 
 /** The line that stands where the dropped middle was. */
-export function droppedOutputLine(dropped: number): string {
+export function droppedOutputLine(
+  dropped: number,
+  headChars = CAPTURE_HEAD_CHARS,
+  tailChars = CAPTURE_TAIL_CHARS,
+): string {
   return (
-    `\n[vx] ${mib(dropped)} of output not kept — vx keeps the first ${mib(CAPTURE_HEAD_CHARS)} ` +
-    `and the last ${mib(CAPTURE_TAIL_CHARS)} of a task's output for its cache entry and replay\n`
+    `\n[vx] ${mib(dropped)} of output not kept — vx keeps the first ${size(headChars)} ` +
+    `and the last ${size(tailChars)} of a task's output\n`
   )
 }
 
@@ -1145,12 +1150,17 @@ export class BoundedCapture {
   private tailLen = 0
   private dropped = 0
 
+  constructor(
+    private readonly headChars = CAPTURE_HEAD_CHARS,
+    private readonly tailChars = CAPTURE_TAIL_CHARS,
+  ) {}
+
   push(text: string, err = false): void {
     // Once the tail has begun the head is closed, even a unit short of its
     // bound (the surrogate case below): a later short chunk fit there and
     // was retained ahead of the chunk before it.
-    if (this.tailLen === 0 && this.headLen < CAPTURE_HEAD_CHARS) {
-      let room = CAPTURE_HEAD_CHARS - this.headLen
+    if (this.tailLen === 0 && this.headLen < this.headChars) {
+      let room = this.headChars - this.headLen
       if (text.length <= room) {
         this.head.push({ text, err })
         this.headLen += text.length
@@ -1165,9 +1175,9 @@ export class BoundedCapture {
     }
     this.tail.push({ text, err })
     this.tailLen += text.length
-    while (this.tailLen > CAPTURE_TAIL_CHARS) {
+    while (this.tailLen > this.tailChars) {
       const first = this.tail[0]!
-      const excess = this.tailLen - CAPTURE_TAIL_CHARS
+      const excess = this.tailLen - this.tailChars
       if (first.text.length <= excess) {
         this.tail.shift()
         this.tailLen -= first.text.length
@@ -1185,7 +1195,14 @@ export class BoundedCapture {
   chunks(): CapturedChunk[] {
     return this.dropped === 0
       ? [...this.head, ...this.tail]
-      : [...this.head, { text: droppedOutputLine(this.dropped), err: false }, ...this.tail]
+      : [
+          ...this.head,
+          {
+            text: droppedOutputLine(this.dropped, this.headChars, this.tailChars),
+            err: false,
+          },
+          ...this.tail,
+        ]
   }
 
   text(): string {
@@ -1213,7 +1230,7 @@ export async function streamToString(
   if (!stream || typeof stream === 'number') return ''
   const full = new BoundedCapture()
   const reader = stream.getReader()
-  const decoder = new TextDecoder()
+  const decoder = new TextDecoder('utf-8', { ignoreBOM: true })
   // On abort, cancel the read so a pending `reader.read()` resolves
   // `done` and we return whatever we captured. Needed for the timeout
   // path: SIGTERMing `sh` doesn't close the pipe if an orphaned

package/src/graph/scheduler.ts

@@ -140,6 +140,12 @@ export interface TaskOutcome {
    * of reading it as a signal (item 268).
    */
   timedOut?: true
+  /**
+   * On a `failed` outcome of a command that ran: the final attempt's
+   * output, both streams, as `encodeOutputLog` stores it, secrets masked,
+   * bounded to its first 8 KiB and last 56 KiB. The run's history keeps it.
+   */
+  failedOutput?: string
   /**
    * On a failed persistent task: why it never became ready — the readiness
    * deadline fired, the child exited first (`exitCode` is then its own), or
@@ -255,6 +261,15 @@ export interface ScheduleOptions {
    * slot admits other work at once. Undefined: nothing owed.
    */
   settledOf?: (outcome: TaskOutcome) => Promise<Partial<TaskOutcome> | void> | undefined
+  /**
+   * The outcome of a task the caller settles in place, or undefined to
+   * dispatch it through `execute`. Asked of an exec-tier task the lane has
+   * room for, after the skip check; its outcome lands in the same tick, it
+   * holds no slot, and `onStart` / `onFinish` hear it as any other. An
+   * unkeyed group runs nothing, and the dispatch, the slot and the promise
+   * around it were ~10 µs of each of a warm run's 1,090 groups (X-192).
+   */
+  settleNow?: (node: TaskNode, upstream: TaskOutcome[]) => TaskOutcome | undefined
   /**
    * Optional priority override: callers pass their own per-node weight
    * (e.g. `computePredictedPriorities` from the orchestrator's history
@@ -749,6 +764,16 @@ export async function runGraph(options: ScheduleOptions): Promise<Map<string, Ta
       })
     }
 
+    // A throw falls back to the dispatch, whose `execute` reports it.
+    const settleInPlace = (node: TaskNode, upstream: TaskOutcome[]): TaskOutcome | undefined => {
+      if (options.settleNow === undefined) return undefined
+      try {
+        return options.settleNow(node, upstream)
+      } catch {
+        return undefined
+      }
+    }
+
     const tick = (): void => {
       if (resolved) return
       // Exec-tier tasks parked THIS tick on a refused admission. Within
@@ -844,6 +869,17 @@ export async function runGraph(options: ScheduleOptions): Promise<Map<string, Ta
 
         const queuedMs = Date.now() - (readyAt.get(id) ?? Date.now())
         readyAt.delete(id)
+        const now = inRestoreTier(id) ? undefined : settleInPlace(node, upstream)
+        if (now !== undefined) {
+          try {
+            onStart?.(node)
+          } catch (err) {
+            const m = err instanceof Error ? err.message : String(err)
+            process.stderr.write(`[vx] onStart observer threw for ${id}: ${m}\n`)
+          }
+          finishOne(id, queuedMs === 0 ? now : { ...now, queuedMs })
+          continue
+        }
         const leave = admit(id)
         // Listed as running on dispatch, so the policy's next ask in this
         // tick sees it; the completion callbacks unlist it.

package/src/graph/task-graph.ts

@@ -109,7 +109,7 @@ export function isGroupTask(node: TaskNode): boolean {
   return node.config.exec === undefined
 }
 
-/** The default `build` (orchestrator/projects.ts): a config cannot key a group, so it is the one keyed group. */
+/** A keyed group: the default `build` (orchestrator/projects.ts), or a config's group with `cache`. */
 function isKeyedGroup(task: TaskConfig): boolean {
   return task.exec === undefined && task.cache !== undefined
 }
@@ -1505,8 +1505,8 @@ interface Side {
  * `inputs.files` rebased to the root against another task's
  * `outputs.workspaceFiles`, which may land in any project (X-135). A task's own outputs are
  * already subtracted from its inputs, and an output the reader's `!` entries
- * take back whole is no overlap. A keyed group is exempt: the default
- * `build` reads `**` of a config-less dependency and runs nothing, and its
+ * take back whole is no overlap. A keyed group is exempt: it runs nothing
+ * (the default `build` reads `**` of a config-less dependency), and its
  * key waits as before.
  */
 function detectInputOverlaps(nodes: Map<string, TaskNode>, workspaceRoot?: string): void {
@@ -1670,7 +1670,7 @@ function detectCycle(nodes: Map<string, TaskNode>): void {
           for (let i = 0; i < stack.length; i += 2) path.push(idsArr[stack[i]!]!)
           const startInPath = path.indexOf(idsArr[depIdx]!)
           const cycle = [...path.slice(startInPath), idsArr[depIdx]!].join(' -> ')
-          throw new UserError(`Cycle detected in task graph: ${cycle}`)
+          throw new UserError(`Cycle detected in task graph: ${cycle}`, 'VX_E_CYCLE')
         }
         color[depIdx] = GRAY
         stack.push(depIdx, 0)

package/src/index.ts

@@ -239,8 +239,25 @@ export type {
 // The serializable run result and its per-task views (what `run()` returns).
 export type { RunResult, TaskView, OutcomeView } from './orchestrator/index.js'
 
-// The one run-history query a reader outside the CLI takes today: `vx why`'s
-// answer, which `@vzn/vx-mcp` serves. The event bus / wire form and the
-// other history readers (`listRuns`, `getRun`, …) left the façade 2026-09-10
-// with no consumer; the telemetry seam above is the canonical export path.
-export { latestRunId, resolveRunId, whyDidThisRerunQuery } from './orchestrator/index.js'
+// The run-history queries a reader outside the CLI takes today: `vx why`'s
+// answer, a run's failures and a task's log, which `@vzn/vx-mcp` serves. The event bus /
+// wire form and the other history readers (`listRuns`, `getRun`, …) left the
+// façade 2026-09-10 with no consumer; the telemetry seam above is the
+// canonical export path.
+export {
+  cacheKeyDiff,
+  latestRunId,
+  resolveRunId,
+  rootCauses,
+  runFailures,
+  taskLog,
+  whyDidThisRerunQuery,
+} from './orchestrator/index.js'
+export type {
+  CacheKeyDiff,
+  OutputLocation,
+  RootCause,
+  RunFailures,
+  TaskFailure,
+  TaskLog,
+} from './orchestrator/index.js'