@vzn/vx 0.0.638 → 0.0.640

package/src/orchestrator/run-report.ts

@@ -1,189 +1,169 @@
-// Markdown run report (`vx run --report=markdown` / `--report-file=<path>`).
-// A table — one row per task plus a header line of totals —
-// rendered after a run so CI can put it in a step summary
-// (`vx run ci --report-file="$GITHUB_STEP_SUMMARY"`). Pure: the run's
-// finished outcomes in, a markdown string out. No ANSI, no live region —
-// keep it machine-clean and diffable.
-//
-// Machine-clean is a property of this STRING, not of stdout: the status
-// logger shares that stream, so redirecting it captures the whole run log
-// too. `--report-file` is the sink that carries the property end to end.
+// The report every plugin's teardown reads, and the run's own bytes kept
+// in a remote that takes its writes (owner 2026-10-15): a failed task's
+// log and the files its outputs left (`cache.upload.failures`), and the
+// log of a task that saved no entry. Each task's bytes leave when it ends,
+// off its path, like its entry's upload (owner 2026-10-16); the run only
+// waits for them where it waits for every upload.
 
-import { failedLabel, skippedLabel, type OutcomeView } from './events.js'
-import { neverStarted } from './summary.js'
+import {
+  packRunOutputs,
+  resolveOutputs,
+  resolveWorkspaceOutputs,
+  runEntryName,
+} from '../cache/index.js'
+import type { CiContext } from './run-context.js'
+import { isGroupTask, type TaskNode, type TaskOutcome } from '../graph/index.js'
+import { relPosix } from '../util/index.js'
+import { decodeOutputLog } from './output-log.js'
+import type { RunReport, RunReportTask } from './plugin.js'
 
-/**
- * One finished run, reduced to what a report needs. Used to live in
- * `protocol.ts` as the return type of the whole-run `backend` seam; that
- * seam is gone (a run always executes in-process — see
- * `docs/modules/executor.md`), so the shape lives with its only consumer.
- */
-export interface RunResult {
-  ok: boolean
-  outcomes: OutcomeView[]
+/** Stores one run entry; resolves whether a remote kept it. */
+export type KeepRunEntry = (name: string, bytes: Uint8Array) => Promise<boolean>
+
+export interface RunKeeperArgs {
+  readonly runId: string
+  readonly workspaceRoot: string
+  readonly nestedDirsByProject: ReadonlyMap<string, string[]>
+  readonly keep: KeepRunEntry
+  /** Whether a failed task's log and outputs are kept (`cache.upload.failures`). */
+  readonly failures: boolean
 }
-import { tallyViews, type Tally } from './tally.js'
 
-/**
- * The report header's numbers. The outcome BUCKETS come from the shared
- * `tallyViews` — the same rules the terminal summary and `--summarize` use,
- * so three surfaces describing one run cannot disagree. Only the two
- * durations are report-specific.
- *
- * This used to be a private copy of the partition, and it drifted: it had no
- * group filter (it could not have one — `OutcomeView` had no `isGroup`), so
- * every organizational node was counted as a successful task and rendered as
- * a row claiming `success | miss | 0ms`.
- */
-interface ReportTally extends Tally {
-  /** Wall-clock ms summed over tasks that ran a command, an aborted one's time so far included. */
-  executedMs: number
-  /** The aborted tasks the stop reached before they ran, as the terminal splits them. */
-  notRun: number
-  /**
-   * Ms of work the cache SKIPPED — the sum of the hits' STORED exec times.
-   * Deliberately not `durationMs`, which for a hit is the restore this run
-   * paid: summing that reported a 2.01 s task as "6ms saved".
-   */
-  savedMs: number
+/** Whether a run on CI or off it keeps failures, by `cache.upload.failures` (default `'ci'`). */
+export function keepsFailures(where: unknown, ci: boolean): boolean {
+  const at = where ?? 'ci'
+  return at === 'always' || (at === 'ci') === ci
 }
 
-function tally(outcomes: readonly OutcomeView[]): ReportTally {
-  const t: ReportTally = { ...tallyViews(outcomes), executedMs: 0, savedMs: 0, notRun: 0 }
-  for (const o of outcomes) {
-    if (o.isGroup === true) continue
-    switch (o.status) {
-      case 'success':
-      case 'failed':
-        t.executedMs += o.durationMs
-        break
-      case 'aborted':
-        if (neverStarted(o)) t.notRun++
-        else t.executedMs += o.durationMs
-        break
-      case 'cache-hit':
-      case 'cache-hit-remote':
-        // An outcome that doesn't know what it skipped contributes nothing:
-        // better to omit the claim than to substantiate it with the restore
-        // cost. (Only reachable across a version skew — every hit this
-        // binary produces carries the stored duration.)
-        t.savedMs += o.storedDurationMs ?? 0
-        break
-    }
-  }
-  return t
+/** Concurrent run-entry writes; more queue. */
+const KEEP_CONCURRENCY = 8
+
+/** The files `node`'s declared outputs match on disk now, workspace-relative and sorted. */
+async function outputsLeft(
+  node: TaskNode,
+  workspaceRoot: string,
+  nestedProjectDirs: string[],
+): Promise<string[]> {
+  const declared = node.config.cache?.outputs
+  if (declared === undefined) return []
+  const [own, ws] = await Promise.all([
+    resolveOutputs({ projectDir: node.projectDir, outputs: declared.files, nestedProjectDirs }),
+    resolveWorkspaceOutputs({ workspaceRoot, outputs: declared.workspaceFiles ?? [] }),
+  ])
+  return [...new Set([...own, ...ws].map((p) => relPosix(workspaceRoot, p)))].sort()
 }
 
-function statusWord(o: OutcomeView): string {
-  switch (o.status) {
-    case 'success':
-      return 'success'
-    case 'cache-hit':
-    case 'cache-hit-remote':
-      return 'success'
-    case 'failed':
-      return failedLabel(o.exitCode, o.timedOut, o.sandboxViolations, o.notReady, o.inputMoved)
-    case 'skipped':
-      return skippedLabel(o.blockedBy)
-    case 'aborted':
-      return neverStarted(o) ? 'not run' : 'aborted'
-    default:
-      return o.status
+/** Keeps each task's run bytes as it ends, and names them in the run's report. */
+export class RunKeeper {
+  private readonly kept = new Map<string, { log?: string; outputs?: string }>()
+  private readonly queue: (() => Promise<void>)[] = []
+  private readonly pending = new Set<Promise<void>>()
+  private active = 0
+  private stopped = false
+
+  constructor(private readonly args: RunKeeperArgs) {}
+
+  /** A task ended: queue what of it the run keeps. */
+  taskDone(o: TaskOutcome): void {
+    if (this.stopped || isGroupTask(o.node)) return
+    const { runId, workspaceRoot } = this.args
+    const id = o.node.id
+    const slot = (): { log?: string; outputs?: string } => {
+      let s = this.kept.get(id)
+      if (s === undefined) this.kept.set(id, (s = {}))
+      return s
+    }
+    const runLog = o.runLog
+    if (runLog !== undefined) {
+      const text = decodeOutputLog(runLog)
+        .map((c) => c.text)
+        .join('')
+      if (text.length > 0) {
+        const name = runEntryName(runId, id, 'log')
+        const bytes = new TextEncoder().encode(text)
+        this.enqueue(async () => {
+          if (await this.args.keep(name, bytes)) slot().log = name
+        })
+      }
+    }
+    if (this.args.failures && o.status === 'failed' && o.where === undefined) {
+      // Read now: a later task may write where this one's outputs lie.
+      const packed = outputsLeft(
+        o.node,
+        workspaceRoot,
+        this.args.nestedDirsByProject.get(o.node.projectName) ?? [],
+      ).then((paths) => packRunOutputs(workspaceRoot, paths))
+      const name = runEntryName(runId, id, 'outputs')
+      this.enqueue(async () => {
+        const bytes = await packed
+        if (bytes !== null && (await this.args.keep(name, bytes))) slot().outputs = name
+      })
+    }
   }
-}
 
-function cacheWord(o: OutcomeView): string {
-  switch (o.status) {
-    case 'cache-hit':
-      return o.restored === false ? 'up-to-date' : 'local'
-    case 'cache-hit-remote':
-      return o.restored === false ? 'up-to-date' : 'remote'
-    case 'success':
-    case 'failed':
-      return o.noCache === true ? 'no-cache' : 'miss'
-    default:
-      return '—'
+  /** Resolves once every queued write has settled, or the run was stopped. */
+  async settled(): Promise<void> {
+    while (!this.stopped && this.pending.size > 0) await Promise.all(this.pending)
   }
-}
 
-function fmtDuration(ms: number): string {
-  if (ms < 1000) return `${Math.round(ms)}ms`
-  return `${(ms / 1000).toFixed(2)}s`
-}
+  /** A stopped run starts no more writes and stops waiting on those in flight. */
+  stop(): void {
+    this.stopped = true
+    this.queue.length = 0
+  }
 
-/**
- * Make a value safe inside a GFM table cell. Task names are arbitrary TS
- * object keys and the loader accepts `|` and newlines, either of which
- * silently breaks the table on the consumer (`>> $GITHUB_STEP_SUMMARY`):
- * a bare pipe adds a column, a newline splits the row.
- *
- * Exported because this file is not the only markdown table describing a run:
- * the cloud plugin's GitHub job summary renders the same data from the same
- * unvalidated names and shipped WITHOUT this escape, so a `|` in a task name
- * or an output path shifted its columns. One definition, so the two
- * cannot disagree about what a cell may contain.
- *
- * A pipe splits the row unless an ODD run of backslashes precedes it (GFM
- * reads `\\` as one escaped backslash), so a pipe after an odd run is already
- * escaped and one more backslash would free it: `a\|b` became `a\\|b`, two
- * cells. A lone `\r` ends a line too.
- */
-export function escapeMarkdownCell(value: string): string {
-  return value
-    .replace(/(\\*)\|/g, (pipe, run: string) => (run.length % 2 === 0 ? `${run}\\|` : pipe))
-    .replace(/\r\n|\r|\n/g, ' ')
-}
+  /** What was kept of each task, by id, for `reportOf`. */
+  keptOf(id: string): { log?: string; outputs?: string } | undefined {
+    return this.kept.get(id)
+  }
 
-const cell = escapeMarkdownCell
+  private enqueue(job: () => Promise<void>): void {
+    let done!: () => void
+    const p = new Promise<void>((resolve) => (done = resolve))
+    this.pending.add(p)
+    this.queue.push(async () => {
+      try {
+        if (!this.stopped) await job()
+      } catch {
+        // a record, never the run's verdict
+      } finally {
+        this.pending.delete(p)
+        done()
+      }
+    })
+    this.pump()
+  }
 
-/**
- * Render the finished run as a markdown report. A header line of totals
- * followed by a per-task table. Self-contained — everything is derived
- * from the result's outcomes.
- */
-export function formatRunReportMarkdown(result: RunResult): string {
-  const t = tally(result.outcomes)
-  const cached = t.cachedLocal + t.cachedRemote
-  // The terminal summary's words and counts: every task in the run counts
-  // (M, 2026-10-14), and a task the stop reached before it ran was never
-  // aborted.
-  const aborted = t.aborted - t.notRun
-  const count = t.total + aborted + t.notRun
-  const parts = [
-    `**${count} task${count === 1 ? '' : 's'}**`,
-    `${t.successful} success`,
-    `${t.failed} failed`,
-    // What the hits did to the disk, as the run's summary splits them.
-    cached > 0
-      ? `${cached} cached (${t.upToDate} up-to-date, ${t.restoredLocal + t.restoredRemote} restored)`
-      : '0 cached',
-  ]
-  if (t.skipped > 0) parts.push(`${t.skipped} skipped`)
-  if (aborted > 0) parts.push(`${aborted} aborted`)
-  if (t.notRun > 0) parts.push(`${t.notRun} not run`)
-  parts.push(`${fmtDuration(t.executedMs)} total`)
-  if (t.savedMs > 0) parts.push(`${fmtDuration(t.savedMs)} saved`)
+  private pump(): void {
+    while (this.active < KEEP_CONCURRENCY && this.queue.length > 0) {
+      const job = this.queue.shift()!
+      this.active++
+      void job().finally(() => {
+        this.active--
+        this.pump()
+      })
+    }
+  }
+}
 
-  // Only a stop (a signal, `RunOptions.signal`) makes an `aborted` outcome,
-  // so one is how an interrupted run tells itself from a failed one.
-  const heading = t.aborted > 0 ? 'interrupted' : result.ok ? 'passed' : 'failed'
-  const lines: string[] = []
-  lines.push(`## vx run — ${heading}`)
-  lines.push('')
-  lines.push(parts.join(' · '))
-  lines.push('')
-  lines.push('| Task | Status | Cache | Duration |')
-  lines.push('| --- | --- | --- | --- |')
-  for (const o of result.outcomes) {
-    // A group node did no work: no command, no cache decision, 0ms. Rendering
-    // one as `success | miss | 0ms` invents a task the user never wrote a
-    // command for. Same exclusion the header's tally makes.
-    if (o.isGroup === true) continue
-    lines.push(
-      `| ${cell(o.taskId)} | ${cell(statusWord(o))} | ${cell(cacheWord(o))} | ${cell(
-        neverStarted(o) ? '—' : fmtDuration(o.durationMs),
-      )} |`,
-    )
+/** The report: every task, with the names of what `keeper` kept of it. */
+export function reportOf(
+  final: readonly TaskOutcome[],
+  run: { runId: string; commit: string | null; ciRun: CiContext; ok: boolean },
+  keeper: RunKeeper | undefined,
+): RunReport {
+  const tasks: RunReportTask[] = []
+  for (const o of final) {
+    if (isGroupTask(o.node)) continue
+    const kept = keeper?.keptOf(o.node.id)
+    tasks.push({
+      id: o.node.id,
+      status: o.status,
+      durationMs: Math.round(o.durationMs),
+      ...(o.hash !== undefined ? { key: o.hash } : {}),
+      ...(kept?.log !== undefined ? { log: kept.log } : {}),
+      ...(kept?.outputs !== undefined ? { outputs: kept.outputs } : {}),
+    })
   }
-  return lines.join('\n') + '\n'
+  return { runId: run.runId, commit: run.commit, ciRun: run.ciRun, ok: run.ok, tasks }
 }

package/src/orchestrator/run-settings.ts

@@ -5,7 +5,6 @@
 
 import type { WorkspaceConfig } from '../config.js'
 import { resolveSetting } from '../settings.js'
-import { setSettleBounds, type SettleBound } from '../util/index.js'
 import type { RunOptions } from './options.js'
 
 const FROM_OPTIONS = {
@@ -14,15 +13,12 @@ const FROM_OPTIONS = {
   timeout: 'run.timeout',
   retries: 'run.retries',
   continueMode: 'run.continue',
-  readyNotice: 'run.readyNotice',
   download: 'cache.download',
 } as const satisfies Partial<Record<keyof RunOptions, string>>
 
 /**
  * `options` with each run-level setting it leaves unset filled from the
- * environment, then the workspace. Arms the settle bounds (`util/settle`,
- * below settings) with the flag's or workspace's `run.killGrace` and
- * `run.teardownTimeout`: the variable sits between them, read per call.
+ * environment, then the workspace.
  */
 export function withRunSettings(
   options: RunOptions,
@@ -33,16 +29,5 @@ export function withRunSettings(
     const { value } = resolveSetting(path, workspace, options[field as keyof RunOptions])
     if (value !== undefined) out[field] = value
   }
-  const bound = (flag: number | undefined, path: string): SettleBound | undefined => {
-    if (flag !== undefined) return { ms: flag, from: 'flag' }
-    const { value } = resolveSetting(path, workspace, undefined, {})
-    return value === undefined ? undefined : { ms: value as number, from: 'workspace' }
-  }
-  const killGrace = bound(options.killGrace, 'run.killGrace')
-  const teardown = bound(options.teardownTimeout, 'run.teardownTimeout')
-  setSettleBounds({
-    ...(killGrace !== undefined ? { killGrace } : {}),
-    ...(teardown !== undefined ? { teardown } : {}),
-  })
   return out as unknown as RunOptions
 }

package/src/orchestrator/run-steps.ts

@@ -0,0 +1,57 @@
+// The steps a run did not wait on (`vx:prefetch`), for `vx last` (M,
+// 2026-10-16): they never show in a run's output. One file per run that
+// had one, `<cacheDir>/steps/<runId>.json`, the newest 50 kept, as
+// run-failures.ts keeps failed output: files, not cache.db, so the index
+// layout stays as it was. A run with none writes nothing.
+
+import { mkdirSync, readdirSync, readFileSync, renameSync, rmSync, writeFileSync } from 'node:fs'
+import path from 'node:path'
+import { isFsRefusal } from '../util/index.js'
+
+/** Runs whose background steps are kept; run ids are UUIDv7, so names sort by age. */
+const KEPT = 50
+
+/** One of vx's own steps that ran beside the tasks. */
+export interface RunStep {
+  id: string
+  durationMs: number
+  ok: boolean
+}
+
+const dirOf = (cacheDir: string): string => path.join(cacheDir, 'steps')
+
+/** Keep `steps` for `runId`; a refused write costs only them. */
+export function writeRunSteps(
+  cacheDir: string,
+  runId: string,
+  steps: readonly RunStep[],
+  warn: (message: string) => void,
+): void {
+  if (steps.length === 0) return
+  try {
+    const dir = dirOf(cacheDir)
+    mkdirSync(dir, { recursive: true })
+    const file = path.join(dir, `${runId}.json`)
+    const tmp = `${file}.${process.pid}.tmp`
+    writeFileSync(tmp, JSON.stringify(steps))
+    renameSync(tmp, file)
+    const names = readdirSync(dir)
+      .filter((n) => n.endsWith('.json'))
+      .sort()
+    for (const n of names.slice(0, -KEPT)) rmSync(path.join(dir, n), { force: true })
+  } catch (err) {
+    if (!isFsRefusal(err)) throw err
+    warn(`[vx] background steps not kept: ${err.message} — the verdict above stands`)
+  }
+}
+
+/** The background steps `runId` kept; none when it had none or they are gone. */
+export function runSteps(cacheDir: string, runId: string): RunStep[] {
+  try {
+    return JSON.parse(
+      readFileSync(path.join(dirOf(cacheDir), `${runId}.json`), 'utf8'),
+    ) as RunStep[]
+  } catch {
+    return []
+  }
+}

package/src/orchestrator/run-stop.ts

@@ -0,0 +1,153 @@
+// One stop for the run: an embedder's `RunOptions.signal` and a process
+// signal both abort it. The scheduler stops dispatching (it reads the
+// signal), the children are torn down, and run() returns through its own
+// end-of-run path. Owns the run-scoped registries of live subprocesses:
+//   - `liveChildren`: in-flight children. The runner adds/removes each
+//     child around its spawn (persistent children stay until they exit).
+//   - `persistentRegistry`: ready persistent tasks (dev servers,
+//     watchers). executeTask spawns them but does NOT await their exit;
+//     ownership moves here so the orchestrator can SIGTERM them once the
+//     rest of the graph finishes.
+// A SIGINT/SIGTERM mid-run forwards that signal to everything in both
+// (`signals.ts`); `detach` removes the handlers so repeated run() calls
+// (test suites) never stack listeners.
+
+import { killGraceMs, teardownTimeoutMs } from '../util/index.js'
+import { type Logger, warnOf } from '../report/index.js'
+import { hasEnded } from './persistent.js'
+import {
+  forwardedSignal,
+  forwardSignals,
+  SIGNAL_SHUTDOWN_GRACE_MS,
+  type StopSignal,
+  terminateChildren,
+} from './signals.js'
+
+type Child = ReturnType<typeof Bun.spawn>
+
+export interface RunStop {
+  readonly signal: AbortSignal
+  readonly liveChildren: Set<Child>
+  readonly persistentRegistry: Map<string, Child>
+  /**
+   * The process signal that stopped the run. A run a process signal
+   * stopped records no history: until item 849 the handler exited before
+   * any outcome landed, and a Ctrl-C'd run then read in `vx last` as
+   * FAILED with 0 tasks (item 854). An embedder's abort is its own call
+   * and keeps its record.
+   */
+  readonly stoppedBy: StopSignal | undefined
+  /**
+   * The stop's teardown of every child, awaited before run() leaves: a
+   * task's shell can die of the signal at once while a child it
+   * backgrounded ignores it and dies only to the SIGKILL after the grace,
+   * and a run that returned first left that child running past vx's exit
+   * (turborepo#14043's class).
+   */
+  readonly aborting: Promise<void> | undefined
+  /**
+   * The servers that had ended when the stop landed: those crashed. One
+   * that ends after it is the stop's own kill, and was named a crash
+   * (item 1061).
+   */
+  readonly endedBeforeStop: ReadonlySet<Child> | undefined
+  /** The graph finished: a server ending from here on is said by the end of the run. */
+  graphDone(): void
+  /** Removes the signal handlers and abort listeners. */
+  detach(): void
+  /** run() has left its `finally`: a process signal waits for this before it exits. */
+  left(): void
+}
+
+export function runStop(args: {
+  log: Logger
+  cache: { close(): void }
+  /** `RunOptions.signal`. */
+  external: AbortSignal | undefined
+  /** `RunOptions.handleSignals`. */
+  handleSignals: boolean
+  handsTerminal: boolean
+  /** How many plugins have a teardown: each gets its own bound before a signal exits. */
+  teardowns: number
+  /** Called first when the run is stopped. */
+  onStop: () => void
+}): RunStop {
+  const { log, external } = args
+  const liveChildren = new Set<Child>()
+  // A server that ends on its own while the graph still runs is said at
+  // once: its dependants were failing against it, and the end of the run
+  // was the first word of it (C-69). Not once the graph is done (the end
+  // of the run and the keep-alive wait say it) nor under a stop.
+  let graphDone = false
+  const persistentRegistry = new (class extends Map<string, Child> {
+    override set(id: string, child: Child): this {
+      super.set(id, child)
+      void child.exited.then((code) => {
+        if (code !== 0 && !graphDone && !controller.signal.aborted)
+          warnOf(log)(`vx: ${id} exited with code ${code} while the run went on`)
+      })
+      return this
+    }
+  })()
+  const controller = new AbortController()
+  const forwardAbort = (): void => controller.abort(external?.reason)
+  if (external?.aborted === true) forwardAbort()
+  else external?.addEventListener('abort', forwardAbort, { once: true })
+  let stoppedBy: StopSignal | undefined
+  let left = (): void => {}
+  const runLeft = new Promise<void>((resolve) => {
+    left = resolve
+  })
+  const signals = forwardSignals({
+    enabled: args.handleSignals,
+    log,
+    cache: args.cache,
+    liveChildren,
+    persistentRegistry,
+    stop: (signal) => {
+      stoppedBy = signal
+      controller.abort(signal)
+    },
+    done: runLeft,
+    handsTerminal: args.handsTerminal,
+    // The grace, then one flush and each teardown at their own bound, and
+    // slack for the summary and the cache close.
+    boundMs:
+      killGraceMs(SIGNAL_SHUTDOWN_GRACE_MS) + teardownTimeoutMs() * (1 + args.teardowns) + 2_000,
+  })
+  let aborting: Promise<void> | undefined
+  let endedBeforeStop: ReadonlySet<Child> | undefined
+  const onAbort = (): void => {
+    args.onStop()
+    endedBeforeStop = new Set([...persistentRegistry.values()].filter(hasEnded))
+    aborting = terminateChildren(
+      () => [...liveChildren, ...persistentRegistry.values()],
+      forwardedSignal(controller.signal.reason),
+    )
+  }
+  if (controller.signal.aborted) onAbort()
+  else controller.signal.addEventListener('abort', onAbort, { once: true })
+  return {
+    signal: controller.signal,
+    liveChildren,
+    persistentRegistry,
+    get stoppedBy() {
+      return stoppedBy
+    },
+    get aborting() {
+      return aborting
+    },
+    get endedBeforeStop() {
+      return endedBeforeStop
+    },
+    graphDone: () => {
+      graphDone = true
+    },
+    detach: () => {
+      signals.remove()
+      external?.removeEventListener('abort', forwardAbort)
+      controller.signal.removeEventListener('abort', onAbort)
+    },
+    left: () => left(),
+  }
+}