@vzn/vx 0.0.631 → 0.0.633

package/src/orchestrator/admission.ts

@@ -32,11 +32,21 @@ export interface TaintTracker {
    * bytes nothing vouches for. Its order-only deps count too.
    */
   judge: (node: TaskNode, upstream: TaskOutcome[]) => boolean
+  /**
+   * For a task `judge` called tainted: the task at the root of it, a
+   * failed one or a dependency `--exclude-dependencies` dropped. Its run
+   * row names it (`blocked_by`), so no reader counts the row on its key.
+   */
+  cause: (node: TaskNode, upstream: TaskOutcome[]) => string
   /** Every settled outcome, the scheduler's `onFinish`. */
   settled: (outcome: TaskOutcome) => void
 }
 
-const UNTAINTED: TaintTracker = { judge: () => false, settled: () => {} }
+const UNTAINTED: TaintTracker = {
+  judge: () => false,
+  cause: (node) => node.id,
+  settled: () => {},
+}
 
 /**
  * Records which tasks ran behind a failure, or on the key of a dependency
@@ -61,6 +71,7 @@ export function taintTracker(
   if (!continueAlways && seeds.size === 0) return UNTAINTED
   const outcomes = new Map<string, TaskOutcome>()
   const memo = new Map<string, boolean>()
+  const causes = new Map<string, string>()
   const failed = (u: TaskOutcome): boolean =>
     continueAlways && (u.status === 'failed' || u.status === 'aborted' || u.status === 'skipped')
   const through = (u: TaskOutcome | undefined): boolean =>
@@ -113,6 +124,23 @@ export function taintTracker(
       seeds.has(node.id) ||
       upstream.some(through) ||
       node.orderOnly?.some((d) => through(outcomes.get(d))) === true,
+    cause: (node, upstream) => {
+      // A restore-tier task's upstream holds holes (see `judge`).
+      const deps = upstream.filter((u) => u !== undefined)
+      for (const d of node.orderOnly ?? []) {
+        const u = outcomes.get(d)
+        if (u !== undefined) deps.push(u)
+      }
+      const root =
+        deps.find(failed) ?? deps.find((u) => taintOf(u.node.id)) ?? node.excludedUpstream?.[0]
+      let c: string
+      if (root === undefined) c = node.id
+      else if (failed(root))
+        c = root.status === 'skipped' ? (root.blockedBy ?? root.node.id) : root.node.id
+      else c = causes.get(root.node.id) ?? root.node.id
+      causes.set(node.id, c)
+      return c
+    },
     settled: (outcome) => {
       outcomes.set(outcome.node.id, outcome)
     },

package/src/orchestrator/affected-tasks.ts

@@ -4,6 +4,7 @@
 // behind `^build` runs when `ui#build` (or what it depends on) is reached,
 // and a spec edit `ui#build`'s inputs leave out stops at `ui`'s own tasks.
 
+import path from 'node:path'
 import type { WorkspaceRules } from '../config.js'
 import { declaresInput, workspaceFilesReachInto } from '../cache/index.js'
 import {
@@ -54,6 +55,30 @@ function wholeProjects(
   return whole
 }
 
+/**
+ * Why `--affected` kept a requested task (`vx run --affected --dry`):
+ * `input`, a changed `file` is one of its declared inputs; `project`, its
+ * project changed and the task reads it whole (an uncached task, a path no
+ * cached task declares, or no single `file`: a lockfile claim, a manifest
+ * edge, a config import); `package`, a `^` edge passes through `project`, a
+ * changed package with no such task; `named`, asked as `pkg#task`;
+ * `selected`, another filter selected its project outright. `via` is the
+ * `dependsOn` chain, nearest first, to the task the change seeded.
+ */
+export interface AffectedReason {
+  kind: 'input' | 'project' | 'package' | 'named' | 'selected'
+  /** Workspace-relative. */
+  file?: string
+  project?: string
+  via?: string[]
+}
+
+/** Collects each kept task's `AffectedReason` when given; a run without one pays nothing. */
+export interface AffectedExplain {
+  workspaceRoot: string
+  reasons: Map<string, AffectedReason>
+}
+
 /**
  * The task ids of `ids` whose closure the change reaches, in their order.
  * A group seeds nothing (it runs nothing) unless it is keyed, as the default
@@ -69,8 +94,16 @@ export function affectedRoots(
   changes: AffectedChanges,
   projects: ReadonlyMap<string, ProjectEntry>,
   packageGraph: PackageGraph,
+  explain?: AffectedExplain,
 ): string[] {
   const whole = wholeProjects(changes, projects)
+  const seeds = explain === undefined ? null : new Map<string, AffectedReason>()
+  const through = explain === undefined ? null : new Map<string, string>()
+  const inProject = (name: string, rel: string | undefined): AffectedReason => {
+    if (rel === undefined) return { kind: 'project' }
+    const dir = path.relative(explain!.workspaceRoot, projects.get(name)!.dir)
+    return { kind: 'project', file: dir === '' ? rel : path.posix.join(dir, rel) }
+  }
   // The builder's `^name` walk (task-graph.ts), keeping only the packages
   // it passes through: a holder's own node is already in `deps`.
   const passesChanged = (n: TaskNode): boolean => {
@@ -89,7 +122,10 @@ export function affectedRoots(
         if (visited.has(target)) continue
         visited.add(target)
         if (holds(target)) continue
-        if (changes.projects.has(target)) return true
+        if (changes.projects.has(target)) {
+          seeds?.set(n.id, { kind: 'package', project: target })
+          return true
+        }
         frontier.push(...packageGraph.directDeps(target))
       }
     }
@@ -99,22 +135,35 @@ export function affectedRoots(
     const cache = n.config.cache
     // Asked of every node, not only the changed projects' (the
     // `workspaceFiles` owners): a `graph` hook may have given the glob.
-    if (
-      cache !== undefined &&
-      (changes.changed.some((rel) => declaresInput(cache, null, rel)) ||
-        (changes.nested ?? []).some((dir) => workspaceFilesReachInto(cache, dir)))
-    ) {
-      return true
+    if (cache !== undefined) {
+      const file = changes.changed.find((rel) => declaresInput(cache, null, rel))
+      const dir =
+        file === undefined
+          ? (changes.nested ?? []).find((d) => workspaceFilesReachInto(cache, d))
+          : undefined
+      if (file !== undefined || dir !== undefined) {
+        seeds?.set(n.id, { kind: 'input', file: (file ?? dir)! })
+        return true
+      }
     }
     if (!changes.projects.has(n.projectName)) return false
+    const rels = changes.paths.get(n.projectName) ?? []
     // A group runs nothing; only the default `build` (projects.ts) is keyed.
     // An uncached task reads its project: a root file another task of it
     // declares (`workspaceFiles`) is no change there.
     if (cache === undefined) {
-      return !isGroupTask(n) && (whole.has(n.projectName) || changes.paths.has(n.projectName))
+      const hit = !isGroupTask(n) && (whole.has(n.projectName) || changes.paths.has(n.projectName))
+      if (hit) seeds?.set(n.id, inProject(n.projectName, rels[0]))
+      return hit
+    }
+    if (whole.has(n.projectName)) {
+      seeds?.set(n.id, inProject(n.projectName, undefined))
+      return true
     }
-    if (whole.has(n.projectName)) return true
-    return (changes.paths.get(n.projectName) ?? []).some((rel) => declaresInput(cache, rel, null))
+    const rel = rels.find((r) => declaresInput(cache, r, null))
+    if (rel === undefined) return false
+    if (seeds !== null) seeds.set(n.id, { ...inProject(n.projectName, rel), kind: 'input' })
+    return true
   }
   const reached = new Map<string, boolean>()
   // Post-order on an explicit stack: a closure is as deep as the graph, and
@@ -145,6 +194,7 @@ export function affectedRoots(
       frame[1] = i
       if (i === deps.length || reached.get(deps[i]!) === true) {
         reached.set(id, i < deps.length)
+        if (i < deps.length) through?.set(id, deps[i]!)
         stack.pop()
         continue
       }
@@ -152,7 +202,20 @@ export function affectedRoots(
     }
     return reached.get(root)!
   }
-  return ids.filter(reaches)
+  const kept = ids.filter(reaches)
+  if (explain !== undefined) {
+    for (const root of kept) {
+      const via: string[] = []
+      let id = root
+      for (let next = through!.get(id); next !== undefined; next = through!.get(id)) {
+        via.push(next)
+        id = next
+      }
+      const seed = seeds!.get(id)!
+      explain.reasons.set(root, via.length > 0 ? { ...seed, via } : seed)
+    }
+  }
+  return kept
 }
 
 /**
@@ -167,15 +230,21 @@ export function keptByAffected<R extends { project: string; task: string }>(
   projects: ReadonlyMap<string, ProjectEntry>,
   packageGraph: PackageGraph,
   keep: { named?: ReadonlySet<string>; outright?: ReadonlySet<string> } = {},
+  explain?: AffectedExplain,
 ): R[] {
   const ids = requested.map((r) => `${r.project}#${r.task}`)
-  const reached = new Set(affectedRoots(nodes, ids, changes, projects, packageGraph))
-  return requested.filter(
-    (r, i) =>
-      keep.named?.has(ids[i]!) === true ||
-      keep.outright?.has(r.project) === true ||
-      reached.has(ids[i]!),
-  )
+  const reached = new Set(affectedRoots(nodes, ids, changes, projects, packageGraph, explain))
+  return requested.filter((r, i) => {
+    const id = ids[i]!
+    const why: AffectedReason['kind'] | null =
+      keep.named?.has(id) === true
+        ? 'named'
+        : keep.outright?.has(r.project) === true
+          ? 'selected'
+          : null
+    if (why !== null) explain?.reasons.set(id, { kind: why })
+    return why !== null || reached.has(id)
+  })
 }
 
 /**

package/src/orchestrator/doctor.ts

@@ -8,7 +8,7 @@
 import os from 'node:os'
 import path from 'node:path'
 import { Cache, CACHE_VERSION, SCHEMA_VERSION } from '../cache/index.js'
-import { PLUGIN_HOOKS } from '../config.js'
+import { PLUGIN_HOOKS, type WorkspaceConfig } from '../config.js'
 import {
   cgroupCpuQuota,
   cgroupMemoryLimitBytes,
@@ -17,6 +17,7 @@ import {
   machineMemoryBytes,
   machineParallelism,
   maskedLine,
+  parseSize,
   relPosix,
 } from '../util/index.js'
 import { VERSION } from '../version.js'
@@ -93,6 +94,8 @@ export interface InfoFacts {
   schemaVersion: string
   cacheEntries: number
   cacheBytes: number
+  /** The workspace's `cacheRetention`, with `maxSize` in bytes; null when none is declared. */
+  cacheRetention: { olderThan?: string; maxSize?: string; maxBytes?: number } | null
   orphans: { artifacts: number; bytes: number }
   runs24h: number
   hits24h: number
@@ -250,6 +253,7 @@ async function collectWorkspaceInfo(
     schemaVersion: SCHEMA_VERSION,
     cacheEntries: stats.entryCount,
     cacheBytes: stats.totalBytes,
+    cacheRetention: retentionFact(workspaceConfig?.cacheRetention),
     // A row-less artifact is indexed again only when its task asks for its
     // key; the rest only `vx cache prune` reclaims (after an upgrade's
     // schema reset, most often).
@@ -407,3 +411,12 @@ async function countLoadableTasks(
   errors.sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0))
   return { tasks, sandboxed, errors }
 }
+
+function retentionFact(r: WorkspaceConfig['cacheRetention']): InfoFacts['cacheRetention'] {
+  if (r === undefined) return null
+  return {
+    ...(r.olderThan !== undefined ? { olderThan: r.olderThan } : {}),
+    // Validated at load, so it parses.
+    ...(r.maxSize !== undefined ? { maxSize: r.maxSize, maxBytes: parseSize(r.maxSize)! } : {}),
+  }
+}

package/src/orchestrator/execute-task.ts

@@ -41,7 +41,12 @@ import {
   maskCaptured,
   BoundedCapture,
 } from '../exec/index.js'
-import { encodeOutputLog } from './output-log.js'
+import {
+  encodeOutputLog,
+  FAILED_OUTPUT_HEAD_CHARS,
+  FAILED_OUTPUT_TAIL_CHARS,
+  failedOutputLog,
+} from './output-log.js'
 import { isGroupTask, RestoreDemoted, type TaskNode, type TaskOutcome } from '../graph/index.js'
 import {
   killGraceMs,
@@ -260,9 +265,87 @@ export interface ExecuteArgs {
 export async function executeTask(args: ExecuteArgs): Promise<TaskOutcome> {
   if (isGroupTask(args.node)) return executeGroupTask(args)
   if (args.node.config.exec?.persistent !== undefined) return executePersistentTask(args)
+  // A probed hit needs none of the run path's set-up: the upstream folding,
+  // timers and closures `executeCachedTask` builds on entry were ~15 µs of
+  // each of a warm run's hits (X-193). The same branch there handles it
+  // when this one does not apply.
+  const probed = args.preProbed
+  if (probed?.hit != null && readsCache(args) && args.remoteOnlyNoop !== true) {
+    return restoreProbed(
+      args,
+      probed.hash,
+      probed.hit,
+      process.hrtime.bigint() - args.runStartHrTimeNs,
+    )
+  }
   return executeCachedTask(args)
 }
 
+/** Whether this task reads the cache: a cached, not remote-only task with a read axis on. */
+function readsCache(args: ExecuteArgs): boolean {
+  const policy = args.cachePolicy ?? FULL_CACHE_POLICY
+  return (
+    args.remoteOnly !== true &&
+    args.node.config.cache !== undefined &&
+    (policy.localRead || policy.remoteRead)
+  )
+}
+
+/**
+ * Restore the up-front probe's hit, or demote it. A key taken before a task
+ * rewrote the lockfile names an install the tree no longer holds, and the
+ * lazy path never probes one (X-124): demoted like a vanished hit, it runs
+ * dep-gated. The hit may be restoring AHEAD of this task's deps, and a
+ * command run now would build from outputs they have not written yet and
+ * save that under the good key: the scheduler runs it again once they are
+ * done (admission drops the probe).
+ */
+async function restoreProbed(
+  args: ExecuteArgs,
+  hash: string,
+  hit: CacheEntry,
+  taskStartNs: bigint,
+): Promise<TaskOutcome> {
+  const cacheOpStart = performance.now()
+  const restored = fingerprintMoved(args)
+    ? null
+    : await restoreOrMiss(args, hash, hit, cacheOpStart, taskStartNs)
+  if (restored !== null) return restored
+  throw new RestoreDemoted(args.node.id)
+}
+
+/**
+ * A hit restored, or null when its artifact was removed after the probe (a
+ * prune, another workspace's retention on a shared cache directory): a
+ * miss. The restore has wiped the declared outputs by then; the run path
+ * cleans them again and the task writes them.
+ */
+async function restoreOrMiss(
+  args: ExecuteArgs,
+  hash: string,
+  hit: CacheEntry,
+  cacheOpStart: number,
+  taskStartNs: bigint,
+): Promise<TaskOutcome | null> {
+  try {
+    return await restoreHit({ args, hash, hit, cacheOpStart, taskStartNs })
+  } catch (err) {
+    if (!(err instanceof ArtifactVanishedError)) throw err
+    args.log.status(`[vx] ${args.node.id}: ${err.message} — running it`)
+    return null
+  }
+}
+
+/**
+ * The workspace fingerprint every key here folded has moved (a task
+ * rewrote the lockfile), said once per run.
+ */
+function fingerprintMoved(args: ExecuteArgs): boolean {
+  if (args.fingerprintWatch?.moved() === undefined) return false
+  args.fingerprintWatch.say(args.log)
+  return true
+}
+
 /**
  * Group task: no `exec`. The scheduler has already ensured every
  * dependency completed; we just return success with a hash rolled up
@@ -270,35 +353,65 @@ export async function executeTask(args: ExecuteArgs): Promise<TaskOutcome> {
  * through us.
  */
 async function executeGroupTask(args: ExecuteArgs): Promise<TaskOutcome> {
+  if (args.node.config.cache === undefined) {
+    return unkeyedGroupOutcome(
+      args.node,
+      args.upstream,
+      args.upfrontGroupKey,
+      args.runStartHrTimeNs,
+    )
+  }
   const wallclockNs = process.hrtime.bigint() - args.runStartHrTimeNs
-  // `computeGroupKey`: an unkeyed group's key is its upstream's alone, so
-  // the up-front one stands when that upstream is unchanged.
-  const upfront = args.upfrontGroupKey
+  const hash = await computeTaskHash({
+    node: args.node,
+    upstream: args.upstream,
+    workspaceRoot: args.workspaceRoot,
+    workspaceFingerprint: args.workspaceFingerprint,
+    cache: args.cache,
+    forwardArgs: args.forwardArgs,
+    nestedProjectDirs: args.nestedProjectDirs,
+    ...(args.gitFilesCache !== undefined ? { gitFilesCache: args.gitFilesCache } : {}),
+    ...(args.hashCache !== undefined ? { hashCache: args.hashCache } : {}),
+  })
+  return groupOutcome(args.node, args.upstream, hash, wallclockNs)
+}
+
+/**
+ * An unkeyed group's outcome (no `cache`, no key of its own): its key is
+ * its upstream's alone (`computeGroupKey`), so the up-front one stands when
+ * that upstream is unchanged. Synchronous: the scheduler settles such a
+ * group in place (`ScheduleOptions.settleNow`), and `upstream` is the key's
+ * (`keyUpstream`).
+ */
+export function unkeyedGroupOutcome(
+  node: TaskNode,
+  upstream: TaskOutcome[],
+  upfront: UpfrontGroupKey | undefined,
+  runStartHrTimeNs: bigint,
+): TaskOutcome {
+  const wallclockNs = process.hrtime.bigint() - runStartHrTimeNs
   const hash =
-    args.node.config.cache === undefined
-      ? upfront !== undefined && sameUpstream(args.upstream, upfront.upstream)
-        ? upfront.key
-        : computeGroupHash(args.upstream)
-      : await computeTaskHash({
-          node: args.node,
-          upstream: args.upstream,
-          workspaceRoot: args.workspaceRoot,
-          workspaceFingerprint: args.workspaceFingerprint,
-          cache: args.cache,
-          forwardArgs: args.forwardArgs,
-          nestedProjectDirs: args.nestedProjectDirs,
-          ...(args.gitFilesCache !== undefined ? { gitFilesCache: args.gitFilesCache } : {}),
-          ...(args.hashCache !== undefined ? { hashCache: args.hashCache } : {}),
-        })
+    upfront !== undefined && sameUpstream(upstream, upfront.upstream)
+      ? upfront.key
+      : computeGroupHash(upstream)
+  return groupOutcome(node, upstream, hash, wallclockNs)
+}
+
+function groupOutcome(
+  node: TaskNode,
+  upstream: TaskOutcome[],
+  hash: string,
+  wallclockNs: bigint,
+): TaskOutcome {
   return {
-    node: args.node,
+    node,
     status: 'success',
     exitCode: 0,
     durationMs: 0,
     hash,
     // What this group stands for. A dependent expands it to describe the
     // real tasks in its input closure — see `TaskOutcome.groupUpstream`.
-    groupUpstream: args.upstream,
+    groupUpstream: upstream,
     wallclockStartNs: wallclockNs,
     wallclockEndNs: wallclockNs,
   }
@@ -823,40 +936,16 @@ async function executeCachedTask(args: ExecuteArgs): Promise<TaskOutcome> {
   // the probe already ran — restore its hit, or (null hit) fall straight
   // to the run path as a known stable miss. No second cache.get.
   if (willRead) {
-    const cacheOpStart = performance.now()
-    // A hit whose artifact was removed after the probe (a prune, another
-    // workspace's retention on a shared cache directory) is a miss. The
-    // restore has wiped the declared outputs by then; the run path cleans
-    // them again and the task writes them.
-    const restoreOrMiss = async (hit: CacheEntry): Promise<TaskOutcome | null> => {
-      try {
-        return await restoreHit({ args, hash, hit, cacheOpStart, taskStartNs })
-      } catch (err) {
-        if (!(err instanceof ArtifactVanishedError)) throw err
-        log.status(`[vx] ${node.id}: ${err.message} — running it`)
-        return null
-      }
-    }
     if (preProbed !== undefined) {
-      if (preProbed.hit !== null) {
-        // A key taken before a task rewrote the lockfile names an install
-        // the tree no longer holds, and the lazy path below never probes
-        // one (X-124): demoted like a vanished hit, it runs dep-gated.
-        const restored = fingerprintMoved() ? null : await restoreOrMiss(preProbed.hit)
-        if (restored !== null) return restored
-        // The up-front probe's hit may be restoring AHEAD of this task's
-        // deps, and a command run now would build from outputs they have
-        // not written yet and save that under the good key. The scheduler
-        // runs it again once they are done (admission drops the probe).
-        throw new RestoreDemoted(node.id)
-      }
+      if (preProbed.hit !== null) return restoreProbed(args, hash, preProbed.hit, taskStartNs)
       // Confirmed stable miss — skip the probe, fall through to run.
-    } else if (!fingerprintMoved()) {
+    } else if (!fingerprintMoved(args)) {
+      const cacheOpStart = performance.now()
       const endProbe = span('cache.get')
       const hit = await cache.get(hash, getContext(node, step.command))
       endProbe()
       if (hit) {
-        const restored = await restoreOrMiss(hit)
+        const restored = await restoreOrMiss(args, hash, hit, cacheOpStart, taskStartNs)
         if (restored !== null) return restored
       }
     }
@@ -1198,7 +1287,8 @@ async function executeCachedTask(args: ExecuteArgs): Promise<TaskOutcome> {
   // and what the cache keeps of it (L-11); null when there are none.
   const secrets = secretMask([process.env, env, step.env?.define], step.env?.secret)
   let flushMasked = (): void => {}
-  // The attempt's output as the logger got it (masked), for the entry.
+  // The attempt's output as the logger got it (masked): the entry's when
+  // the task saves, else only what a failure reports (`failedOutput`).
   let output: BoundedCapture | undefined
   const storedOutput = (): string => encodeOutputLog(output?.chunks() ?? [])
   const failedAttempts: { endedAt: number; exitCode: number; timedOut?: true }[] = []
@@ -1290,14 +1380,16 @@ async function executeCachedTask(args: ExecuteArgs): Promise<TaskOutcome> {
   }
 
   async function buildRequest(local: boolean): Promise<ExecuteRequest> {
-    const kept = willSave ? new BoundedCapture() : undefined
+    const kept = willSave
+      ? new BoundedCapture()
+      : new BoundedCapture(FAILED_OUTPUT_HEAD_CHARS, FAILED_OUTPUT_TAIL_CHARS)
     output = kept
     const toOut = (t: string): void => {
-      kept?.push(t)
+      kept.push(t)
       log.taskStdout(node, t)
     }
     const toErr = (t: string): void => {
-      kept?.push(t, true)
+      kept.push(t, true)
       log.taskStderr(node, t)
     }
     const out = secrets && maskedEmitter(secrets, toOut)
@@ -1436,16 +1528,6 @@ async function executeCachedTask(args: ExecuteArgs): Promise<TaskOutcome> {
     }
   }
 
-  /**
-   * The workspace fingerprint every key here folded has moved (a task
-   * rewrote the lockfile), said once per run.
-   */
-  function fingerprintMoved(): boolean {
-    if (args.fingerprintWatch?.moved() === undefined) return false
-    args.fingerprintWatch.say(log)
-    return true
-  }
-
   /**
    * What an additive run saves as its own, or undefined when it removed a
    * file it found: no entry replays a removal (`ownOutputsSince`), so the
@@ -1491,7 +1573,7 @@ async function executeCachedTask(args: ExecuteArgs): Promise<TaskOutcome> {
    * withholds it too: the key folded the old one.
    */
   async function keyStillTrue(): Promise<boolean> {
-    if (fingerprintMoved()) {
+    if (fingerprintMoved(args)) {
       unkeyed = true
       return false
     }
@@ -1540,6 +1622,9 @@ async function executeCachedTask(args: ExecuteArgs): Promise<TaskOutcome> {
       : {}),
     ...(inputChanges !== undefined ? { inputChanges } : {}),
     ...(unkeyed ? { unkeyed: true as const } : {}),
+    ...(effectiveExitCode !== 0 && output !== undefined
+      ? { failedOutput: failedOutputLog(output, willSave) }
+      : {}),
     ...(result.timedOut === true && effectiveExitCode !== 0 ? { timedOut: true as const } : {}),
     ...(result.cpuMs !== undefined ? { cpuMs: result.cpuMs } : {}),
     ...(result.peakRssBytes !== undefined ? { peakRssBytes: result.peakRssBytes } : {}),

package/src/orchestrator/failure-mode.ts

@@ -27,7 +27,9 @@ export type FailureMode = 'stable' | 'flaky-recoverable' | 'flaky-fatal'
  * and how often it failed AFTER its first pass (`relapses`). A task with
  * no cache block keys on its config alone and runs every time, so its key
  * says nothing about its inputs: no reader counts it, as no run's row
- * calls it flaky. Every flakiness reader is a filter over this one
+ * calls it flaky. Nor is a row that names a `blocked_by`: it ran behind a
+ * failure (`--continue=always`), on bytes its key never named, so its
+ * pass or failure is not the key's. Every flakiness reader is a filter over this one
  * projection.
  */
 function keyOutcomesSql(source: string, where = ''): string {
@@ -42,7 +44,7 @@ function keyOutcomesSql(source: string, where = ''): string {
              CASE WHEN status = 'success' OR status IN ${HIT_STATUSES} OR cache_hit = 1
                THEN 1 ELSE 0 END AS passed
            FROM ${source}
-           WHERE ${KEYED_RUNS_SQL} AND cached IS NOT 0${where}))
+           WHERE ${KEYED_RUNS_SQL} AND cached IS NOT 0 AND blocked_by IS NULL${where}))
        GROUP BY project, task, hash`
 }
 
@@ -148,7 +150,7 @@ export function detectFlaky(db: Database, candidates: readonly FlakyCandidate[])
     const rows = db
       .query(
         `SELECT DISTINCT project, task, hash FROM runs
-         WHERE status = 'failed' AND hash IN (${chunk.map(() => '?').join(', ')})`,
+         WHERE status = 'failed' AND blocked_by IS NULL AND hash IN (${chunk.map(() => '?').join(', ')})`,
       )
       .all(...chunk.map((c) => c.hash)) as { project: string; task: string; hash: string }[]
     for (const r of rows) everFailed.add(keyOf(r))

package/src/orchestrator/framed-output.ts

@@ -31,6 +31,7 @@ import { formatElapsed, maskedCommand } from '../util/index.js'
 import { paint, type ColorSupport } from './colors.js'
 import { neverStarted } from './summary.js'
 import { outcomeLabel, ranNoCache, skippedReason } from './events.js'
+import { fileMemo, linkPaths } from './path-links.js'
 
 const NO_COLOR: ColorSupport = { enabled: false }
 
@@ -88,6 +89,8 @@ export function formatTaskBlock(
   // ran or was cached — you asked for it, you see what it would run.
   forceCommand = false,
   forwardArgs: readonly string[] = [],
+  // The terminal opens OSC 8 links: a failed task's paths become links.
+  links = false,
 ): string {
   // Group tasks (no `exec`) do no work and have no body — they're
   // organizational nodes the user wrote so a `vx run ci` invocation
@@ -113,7 +116,16 @@ export function formatTaskBlock(
     lines.push('', corner(`$ ${shownCommand(node, forwardArgs)}`), '')
   }
 
-  pushOutputSection(lines, output, (body.droppedStdout ?? 0) + (body.droppedStderr ?? 0), colors)
+  const isFile = links && outcome.status === 'failed' ? fileMemo() : undefined
+  const link =
+    isFile === undefined ? undefined : (t: string) => linkPaths(t, node.projectDir, isFile)
+  pushOutputSection(
+    lines,
+    output,
+    (body.droppedStdout ?? 0) + (body.droppedStderr ?? 0),
+    colors,
+    link,
+  )
 
   lines.push(...violationSection(outcome, colors))
 
@@ -156,6 +168,7 @@ function pushOutputSection(
   output: readonly OutputChunk[],
   lost: number,
   colors: ColorSupport,
+  link?: (line: string) => string,
 ): void {
   if (output.every((c) => c.text.trim().length === 0)) return
   lines.push(sectionLine('OUTPUT', '', colors), '')
@@ -179,8 +192,9 @@ function pushOutputSection(
   }
   if (open !== null) body.push({ text: open.parts.join(''), err: open.err })
   for (const l of body) {
-    if (!l.err || !colors.enabled) lines.push(l.text)
-    else lines.push(l.text.includes('\x1b') ? l.text : paint(ERROR, l.text, colors))
+    const text = link === undefined ? l.text : link(l.text)
+    if (!l.err || !colors.enabled) lines.push(text)
+    else lines.push(l.text.includes('\x1b') ? text : paint(ERROR, text, colors))
   }
   lines.push('')
 }