@vzn/vx 0.0.630 → 0.0.632

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('')
 }

package/src/orchestrator/index.ts

@@ -4,6 +4,7 @@
 export { run, planRun, nxProjectTarget, projectNamed } from './run.js'
 export { prepareRun, type PreparedRun } from './prepare.js'
 export { affectedTaskProjects } from './affected-tasks.js'
+export type { AffectedReason } from './affected-tasks.js'
 export {
   discoverProjects,
   gitOfDiscovery,
@@ -156,12 +157,22 @@ export {
   latestRunId,
   listInvocations,
   listRuns,
+  rootCauses,
   whyDidThisRerun as whyDidThisRerunQuery,
 } from './metrics.js'
+export {
+  runFailures,
+  type RunFailures,
+  type TaskFailure,
+  type TaskLog,
+  taskLog,
+} from './run-failures.js'
+export type { OutputLocation } from './path-links.js'
 export { resolveRunId, shortRunId } from './run-id.js'
 export type {
   CacheEntryRow,
   CacheKeyDiff,
+  RootCause,
   CacheKeyExplanation,
   InputDiffEntry,
   InvocationDetail,

package/src/orchestrator/logger.ts

@@ -37,6 +37,7 @@ import {
   notifyEscape,
   PROGRESS_CLEAR,
   progressEscape,
+  terminalLinks,
   terminalSignals,
 } from './terminal-signals.js'
 
@@ -298,6 +299,7 @@ export function defaultLogger(
   const signals = writer.enabled
     ? terminalSignals(opts.env ?? process.env)
     : { progress: false, notify: false }
+  const links = writer.enabled && terminalLinks(opts.env ?? process.env)
   let progressShown = -1
   let progressRed = false
 
@@ -753,7 +755,15 @@ export function defaultLogger(
         }
         if (framed && output.some((c) => c.text.length > 0)) {
           emitBlock(
-            formatTaskBlock(node, outcome, { output, ...dropped }, colors, true, forwardArgs),
+            formatTaskBlock(
+              node,
+              outcome,
+              { output, ...dropped },
+              colors,
+              true,
+              forwardArgs,
+              links,
+            ),
           )
           return
         }
@@ -846,7 +856,15 @@ export function defaultLogger(
           if (outcome.status !== 'failed') return
           emitLine(failureRow(node, outcome))
           deferredFailures.push(
-            formatTaskBlock(node, outcome, { output, ...dropped }, colors, false, forwardArgs),
+            formatTaskBlock(
+              node,
+              outcome,
+              { output, ...dropped },
+              colors,
+              false,
+              forwardArgs,
+              links,
+            ),
           )
           return
         case 'broad':
@@ -858,7 +876,15 @@ export function defaultLogger(
             // ◼ row now; the full frame replays at runEnd.
             emitLine(failureRow(node, outcome))
             deferredFailures.push(
-              formatTaskBlock(node, outcome, { output, ...dropped }, colors, false, forwardArgs),
+              formatTaskBlock(
+                node,
+                outcome,
+                { output, ...dropped },
+                colors,
+                false,
+                forwardArgs,
+                links,
+              ),
             )
           } else if (outcome.status === 'success') {
             emitLine(formatTaskExecutedLine(node, outcome, colors))
@@ -895,14 +921,30 @@ export function defaultLogger(
             if (outcome.status === 'failed') {
               emitLine(failureRow(node, outcome))
               deferredFailures.push(
-                formatTaskBlock(node, outcome, { output, ...dropped }, colors, false, forwardArgs),
+                formatTaskBlock(
+                  node,
+                  outcome,
+                  { output, ...dropped },
+                  colors,
+                  false,
+                  forwardArgs,
+                  links,
+                ),
               )
               return
             }
             // forceCommand: a requested task's frame shows `$ cmd`
             // whether it ran or was cached — same frame every run.
             emitBlock(
-              formatTaskBlock(node, outcome, { output, ...dropped }, colors, true, forwardArgs),
+              formatTaskBlock(
+                node,
+                outcome,
+                { output, ...dropped },
+                colors,
+                true,
+                forwardArgs,
+                links,
+              ),
             )
             return
           }
@@ -913,7 +955,15 @@ export function defaultLogger(
           } else if (outcome.status === 'failed') {
             emitLine(failureRow(node, outcome))
             deferredFailures.push(
-              formatTaskBlock(node, outcome, { output, ...dropped }, colors, false, forwardArgs),
+              formatTaskBlock(
+                node,
+                outcome,
+                { output, ...dropped },
+                colors,
+                false,
+                forwardArgs,
+                links,
+              ),
             )
           }
           return
@@ -939,6 +989,7 @@ export function defaultLogger(
             colors,
             false,
             forwardArgs,
+            links,
           )
           if (block.length === 0) return
           if (view.gha) {

package/src/orchestrator/metrics.ts

@@ -757,6 +757,36 @@ export function cacheKeyDiff(db: Database, runId: string, taskId: string): Cache
   const cur = loadEntryInputs(db, this_.hash)
   const old = loadEntryInputs(db, prev.hash)
 
+  // A failed previous run kept no fingerprints; the last run that saved an
+  // entry still names what moved since then (the edit an agent made to fix
+  // the failure, or the one that broke it).
+  if (cur.length > 0 && old.length === 0 && !isPassStatus(prev.status)) {
+    const saved = db
+      .query(
+        `SELECT run_id AS runId, hash FROM runs
+         WHERE project = ? AND task = ? AND id < ? AND ${KEYED_RUNS_SQL}
+           AND hash IN (SELECT entry_hash FROM entry_inputs)
+         ORDER BY id DESC LIMIT 1`,
+      )
+      .get(project, task, this_.id) as { runId: string | null; hash: string } | undefined
+    if (saved) {
+      const { entries, unchangedCount } = diffKeyComponents(loadEntryInputs(db, saved.hash), cur)
+      const since = `run ${saved.runId}, the last that saved an entry (the previous run ended ${prev.status})`
+      return {
+        runId,
+        taskId,
+        found: true,
+        previousRunId: saved.runId,
+        entries,
+        unchangedCount,
+        note:
+          entries.length > 0
+            ? `${entries.length} cache-key component(s) changed since ${since}`
+            : `cache key matches ${since}`,
+      }
+    }
+  }
+
   // Input fingerprints are pruned with their entry (ON DELETE CASCADE); if
   // either side's rows are gone, we can name the hash change but not the
   // component-level diff.
@@ -803,6 +833,41 @@ export function cacheKeyDiff(db: Database, runId: string, taskId: string): Cache
   }
 }
 
+export 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).
+ */
+export 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
+}
+
 // ---------------------------------------------------------------------------
 // Run comparison — diff a run against the immediately-previous invocation
 // ---------------------------------------------------------------------------

package/src/orchestrator/options.ts

@@ -5,9 +5,11 @@
 import type { CachePolicy, RemoteCacheLayer } from '../cache/index.js'
 import type { ContinueMode } from '../graph/index.js'
 import type { TaskOutcome } from '../graph/index.js'
+import type { AffectedReason } from './affected-tasks.js'
 import type { EventBus } from './events.js'
 import type { TelemetrySink } from './telemetry.js'
 import type { Logger } from './logger.js'
+import type { RunSummaryJson } from './run-artifacts.js'
 import type { AffectedChanges, ProjectEntry, ProjectMeta } from '../workspace/index.js'
 
 export interface RunOptions {
@@ -41,6 +43,8 @@ export interface RunOptions {
    * whether or not `affected` reaches them (X-10).
    */
   selectedOutright?: readonly string[]
+  /** Filled with why `--affected` kept each requested task; `planRun` (`--dry`) passes it. */
+  affectedReasons?: Map<string, AffectedReason>
   /**
    * Configs a selection pass in this same process already loaded and
    * staged with the same `cacheDir` and `frozen` (the CLI walks every
@@ -171,6 +175,12 @@ export interface RunOptions {
    * else is treated as the literal file path (cwd-relative).
    */
   summarize?: string
+  /**
+   * `vx run --format json`: the terminal renderer writes stderr, and the
+   * run hands back `RunSummary.json`, the `--summarize` document, for the
+   * caller to print on stdout.
+   */
+  json?: boolean
   /**
    * Text printed just above the run's footer, given the outcomes the
    * footer counts, after the `summaryTable`: nothing prints below the
@@ -312,6 +322,8 @@ export interface RunSummary {
    * caller prints it; `vx run` writes it to stderr.
    */
   refused?: string
+  /** The `--summarize` document, when `RunOptions.json` asked for it. */
+  json?: RunSummaryJson
 }
 
 export interface HeldPersistent {

package/src/orchestrator/output-log.ts

@@ -4,7 +4,7 @@
 // RS (U+001E) + `e` / `o` where the stream switches to stderr / stdout, and
 // a literal RS doubled. Output that never touched stderr is its own text.
 
-import type { CapturedChunk } from '../exec/index.js'
+import { BoundedCapture, type CapturedChunk } from '../exec/index.js'
 
 const RS = '\x1e'
 
@@ -51,3 +51,16 @@ export function decodeOutputLog(log: string): CapturedChunk[] {
   flush()
   return chunks
 }
+
+// What a failed task reports of its output (`vx last`, an agent): the
+// error is usually at the end, and a run's history keeps one per failure.
+export const FAILED_OUTPUT_HEAD_CHARS = 8 * 1024
+export const FAILED_OUTPUT_TAIL_CHARS = 56 * 1024
+
+/** A failed attempt's capture, re-bounded to the failure's limits when it is the entry's. */
+export function failedOutputLog(capture: BoundedCapture, entrySized: boolean): string {
+  if (!entrySized) return encodeOutputLog(capture.chunks())
+  const small = new BoundedCapture(FAILED_OUTPUT_HEAD_CHARS, FAILED_OUTPUT_TAIL_CHARS)
+  for (const c of capture.chunks()) small.push(c.text, c.err)
+  return encodeOutputLog(small.chunks())
+}