@vzn/vx 0.0.0 → 0.0.12

package/src/orchestrator/telemetry.ts

@@ -0,0 +1,350 @@
+// The telemetry contract — THE canonical, versioned data-export shape.
+//
+// This is the one neutral boundary the observability/integration design
+// (docs/design/observability-architecture-2026-06.md) is built around.
+// Core projects its live `RunEvent` stream into these records ONCE, in
+// one place (`createTelemetrySource`), and hands them to every registered
+// `TelemetrySink`. Exporters (OTel, a manual HTTP POST, any third-party sink) all read
+// the SAME records — with the analytics fields + git/CI context already
+// folded in — instead of each re-deriving an ad-hoc shape from the raw,
+// rendering-oriented `WireEvent` stream.
+//
+// A sink is observe-only BY CONSTRUCTION: its only input is an immutable
+// record; its `TelemetryContext` carries read-only metadata and NO mutable
+// run handle (no bus, no Cache, no RunRequest). There is no API path from a
+// sink back into scheduling/caching/exec — telemetry provably cannot change
+// what or how tasks run. Contrast `backend`/`cache`, which return objects
+// core calls INTO; those are the behavior capabilities, kept separate.
+
+import type { TaskStatus, VerifyVerdict } from '../graph/index.js'
+import type { RunEvent, RunEventSubscriber } from './events.js'
+
+/** Bumped when the record shape changes. Readers MUST check `v`. */
+export const TELEMETRY_SCHEMA_VERSION = 2
+
+/** Where a task's result came from, derived ONCE in core from the status. */
+export type CacheSource = 'miss' | 'local' | 'remote' | 'none'
+
+/**
+ * Map a task outcome status to its cache source. `success`/`failed` ran
+ * (a miss as far as the cache read is concerned); the two cache-hit
+ * statuses restored from local/remote; `skipped`/`aborted` never engaged
+ * the cache. Pure function — the single place this mapping is decided, so
+ * no consumer re-implements `status LIKE 'cache-hit%'`.
+ */
+export function deriveCacheSource(status: TaskStatus): CacheSource {
+  switch (status) {
+    case 'cache-hit':
+      return 'local'
+    case 'cache-hit-remote':
+      return 'remote'
+    case 'success':
+    case 'failed':
+      return 'miss'
+    case 'skipped':
+    case 'aborted':
+      return 'none'
+  }
+}
+
+/** Identifies which run a record belongs to + its captured context. Maps
+ *  cleanly onto OTel CI/CD + VCS resource attributes. */
+export interface RunContextRecord {
+  /** ULID, shared by every record in one `vx run`. */
+  runId: string
+  vxVersion: string
+  /** The invocation command line (process.argv-derived). */
+  command: string
+  requestedTasks: readonly string[]
+  /** Compact cache-policy flags, e.g. `'lR,lW,rR,rW'`. */
+  cachePolicy: string
+  concurrency: number
+  flow: 'focused' | 'broad' | null
+  /**
+   * Stable workspace identity (v2) — the multi-workspace server key.
+   * Derived from the normalized git remote (any checkout of the same
+   * repo → same id); see run-context.ts captureWorkspaceIdentity. A v1
+   * consumer synthesizes 'default' for pushes that predate it.
+   */
+  workspaceId: string
+  workspaceName: string
+  // git / CI / host — straight from run-context.ts.
+  commitSha: string | null
+  branch: string | null
+  dirty: boolean | null
+  ci: boolean
+  ciProvider: string | null
+  host: string | null
+  os: string
+  arch: string
+  /** `--tag k=v` pairs. */
+  tags: Readonly<Record<string, string>>
+}
+
+/** Denormalized per-task analytics — shared by the streaming `task.end`
+ *  record and the per-run summary's `tasks[]`. */
+export interface TaskTelemetry {
+  taskId: string
+  project: string
+  task: string
+  status: TaskStatus
+  cacheSource: CacheSource
+  exitCode: number
+  durationMs: number
+  hash?: string
+  cpuMs?: number
+  peakRssBytes?: number
+  /** Total attempts when the task RETRIED (>1) — set only when `exec.retries`
+   *  / `--retry` produced more than one attempt. A retried-then-passed task is
+   *  flaky by definition; this is the telemetry-side flaky signal. */
+  attempts?: number
+  /** Cache-correctness verdict — set ONLY on a `--verify` run (absent
+   *  otherwise). A `nondeterministic` verdict means the task's cache entry is
+   *  unsound (its outputs aren't a pure function of its declared inputs); this
+   *  is the telemetry-side hermeticity signal a dashboard surfaces. */
+  verify?: VerifyVerdict
+  /** bigint hrtime ns relative to run t=0, encoded as a decimal string. */
+  wallclockStartNs?: string
+  wallclockEndNs?: string
+}
+
+/**
+ * A streaming telemetry record — one per lifecycle event. A superset of the
+ * rendering-oriented `WireEvent`: it carries the run context + the per-task
+ * analytics fields a consumer needs WITHOUT re-deriving from the stream.
+ * `task.log` records are large and OPT-IN (see `TelemetrySink.wants`).
+ */
+export type TelemetryRecord =
+  | { v: number; kind: 'run.start'; run: RunContextRecord; total: number; ts: number }
+  | {
+      v: number
+      kind: 'task.start'
+      runId: string
+      taskId: string
+      project: string
+      task: string
+      command?: string
+      ts: number
+    }
+  | {
+      v: number
+      kind: 'task.log'
+      runId: string
+      taskId: string
+      stream: 'stdout' | 'stderr'
+      chunk: string
+      ts: number
+    }
+  | ({ v: number; kind: 'task.end'; runId: string; ts: number } & TaskTelemetry)
+  | { v: number; kind: 'run.end'; runId: string; ts: number }
+
+/**
+ * A per-run SUMMARY record — the denormalized invocation header plus the
+ * per-task outcome list, emitted once at run:end. An ingesting store can
+ * persist a whole run in one write without replaying the stream. The
+ * manual-API exporter + a service's ingest endpoint primarily speak this shape.
+ */
+export interface RunSummaryRecord {
+  v: number
+  run: RunContextRecord
+  startedAt: number
+  endedAt: number
+  totalDurationMs: number
+  taskCount: number
+  failedCount: number
+  hitCount: number
+  hitLocalCount: number
+  hitRemoteCount: number
+  exitOk: boolean
+  tasks: readonly TaskTelemetry[]
+}
+
+/** A telemetry consumer. Observe-only: receives records, holds no run handle. */
+export interface TelemetrySink {
+  readonly name?: string
+  /**
+   * Which streaming record kinds to receive. Default (undefined): all
+   * EXCEPT `task.log` (large; most sinks don't want build-log chunks).
+   * The source checks this before projecting/cloning, so a sink pays
+   * nothing for kinds it declines.
+   */
+  readonly wants?: ReadonlyArray<TelemetryRecord['kind']>
+  /** A streaming record. MUST return promptly — buffer; do NOT await I/O. */
+  onRecord?(record: TelemetryRecord): void
+  /** The per-run summary, at run:end. MUST return promptly. */
+  onRunSummary?(summary: RunSummaryRecord): void
+  /** Drain buffered data. Awaited (time-bounded by the sink) at run:end. */
+  flush?(): Promise<void>
+}
+
+/** Read-only context a sink is created with. No mutable run handle — the
+ *  isolation guarantee is structural. */
+export interface TelemetryContext {
+  readonly workspaceRoot: string
+  /** A STRING, not a Cache handle — a sink cannot reach the cache. */
+  readonly cacheDir: string
+  warn(message: string): void
+}
+
+/** A live telemetry source: a bus subscriber + the run-summary emit + flush. */
+export interface TelemetrySource {
+  /** Subscribe this to the run event bus to stream records to the sinks. */
+  readonly subscriber: RunEventSubscriber
+  /** Fan the per-run summary to every sink's `onRunSummary` (crash-isolated). */
+  emitSummary(summary: RunSummaryRecord): void
+  /** Await every sink's `flush()` (each crash-isolated). */
+  flush(): Promise<void>
+}
+
+const DEFAULT_KINDS: ReadonlyArray<TelemetryRecord['kind']> = [
+  'run.start',
+  'task.start',
+  'task.end',
+  'run.end',
+]
+
+/**
+ * Build a telemetry source over a fixed set of sinks. The returned
+ * `subscriber` projects each `RunEvent` into a `TelemetryRecord` and fans
+ * it to the sinks that want its kind, under crash isolation (a throwing
+ * sink is disabled for the rest of the run, never propagating into the
+ * orchestrator). `task.log` is projected ONLY if some sink opted in — so
+ * the large-payload path costs nothing by default.
+ *
+ * The `run` context (captured once by run.ts) is stamped onto `run.start`
+ * and supplies the `runId` every other record carries.
+ */
+export function createTelemetrySource(args: {
+  sinks: readonly TelemetrySink[]
+  run: RunContextRecord
+}): TelemetrySource {
+  const { sinks, run } = args
+  const runId = run.runId
+  // A sink is disabled the first time it throws — its name (or index) goes
+  // here and it's skipped for the rest of the run.
+  const disabled = new Set<TelemetrySink>()
+  // Precompute which sinks want each kind, so per-event fan-out is a plain
+  // array walk with no per-record `wants` scanning.
+  const wantsLog = sinks.some((s) => (s.wants ?? DEFAULT_KINDS).includes('task.log'))
+
+  function deliver(record: TelemetryRecord): void {
+    for (const sink of sinks) {
+      if (disabled.has(sink) || sink.onRecord === undefined) continue
+      const kinds = sink.wants ?? DEFAULT_KINDS
+      if (!kinds.includes(record.kind)) continue
+      try {
+        sink.onRecord(record)
+      } catch {
+        disabled.add(sink)
+      }
+    }
+  }
+
+  let endEmitted = false
+  const subscriber: RunEventSubscriber = (event: RunEvent) => {
+    const ts = Date.now()
+    switch (event.kind) {
+      case 'run:start':
+        deliver({
+          v: TELEMETRY_SCHEMA_VERSION,
+          kind: 'run.start',
+          run,
+          total: event.info.total,
+          ts,
+        })
+        return
+      case 'task:start': {
+        const node = event.node
+        if (node.config.exec === undefined) return // group task — no command, skip
+        const rec: TelemetryRecord = {
+          v: TELEMETRY_SCHEMA_VERSION,
+          kind: 'task.start',
+          runId,
+          taskId: node.id,
+          project: node.projectName,
+          task: node.taskName,
+          ts,
+        }
+        if (node.config.exec.command !== undefined) rec.command = node.config.exec.command
+        deliver(rec)
+        return
+      }
+      case 'task:stdout':
+      case 'task:stderr': {
+        if (!wantsLog) return // nobody wants logs — pay nothing
+        deliver({
+          v: TELEMETRY_SCHEMA_VERSION,
+          kind: 'task.log',
+          runId,
+          taskId: event.node.id,
+          stream: event.kind === 'task:stdout' ? 'stdout' : 'stderr',
+          chunk: event.chunk,
+          ts,
+        })
+        return
+      }
+      case 'task:complete': {
+        const { node, outcome } = event
+        if (node.config.exec === undefined) return // group task
+        const rec: TelemetryRecord = {
+          v: TELEMETRY_SCHEMA_VERSION,
+          kind: 'task.end',
+          runId,
+          ts,
+          taskId: node.id,
+          project: node.projectName,
+          task: node.taskName,
+          status: outcome.status,
+          cacheSource: deriveCacheSource(outcome.status),
+          exitCode: outcome.exitCode,
+          durationMs: outcome.durationMs,
+        }
+        if (outcome.hash !== undefined) rec.hash = outcome.hash
+        if (outcome.cpuMs !== undefined) rec.cpuMs = outcome.cpuMs
+        if (outcome.peakRssBytes !== undefined) rec.peakRssBytes = outcome.peakRssBytes
+        if (outcome.attempts !== undefined) rec.attempts = outcome.attempts
+        if (outcome.verify !== undefined) rec.verify = outcome.verify
+        if (outcome.wallclockStartNs !== undefined)
+          rec.wallclockStartNs = outcome.wallclockStartNs.toString()
+        if (outcome.wallclockEndNs !== undefined)
+          rec.wallclockEndNs = outcome.wallclockEndNs.toString()
+        deliver(rec)
+        return
+      }
+      case 'run:status':
+        return // status lines are terminal-rendering noise, not telemetry
+      case 'run:end':
+        // run() emits run:end twice (normal + finally); emit one record.
+        if (endEmitted) return
+        endEmitted = true
+        deliver({ v: TELEMETRY_SCHEMA_VERSION, kind: 'run.end', runId, ts })
+        return
+    }
+  }
+
+  return {
+    subscriber,
+    emitSummary(summary: RunSummaryRecord): void {
+      for (const sink of sinks) {
+        if (disabled.has(sink) || sink.onRunSummary === undefined) continue
+        try {
+          sink.onRunSummary(summary)
+        } catch {
+          disabled.add(sink)
+        }
+      }
+    },
+    async flush(): Promise<void> {
+      await Promise.all(
+        sinks.map(async (sink) => {
+          if (sink.flush === undefined) return
+          try {
+            await sink.flush()
+          } catch {
+            // a sink's flush failure can never break the run
+          }
+        }),
+      )
+    },
+  }
+}

package/src/orchestrator/upstream.ts

@@ -0,0 +1,93 @@
+import {
+  DependencySpecError,
+  parseDependencySpec,
+  type DependencySpec,
+  type TaskOutcome,
+} from '../graph/index.js'
+import { UserError } from '../util/index.js'
+
+/**
+ * Pick which upstream task hashes participate in the current task's
+ * cache key, filtered by `cache.inputs.tasks`. The folded value is the
+ * upstream's own cache key (its input-based task hash) — pure-input
+ * transitive hashing, like Turbo/Nx. An upstream change propagates
+ * through its key into every dependent's key. There is deliberately NO
+ * output-content folding: an upstream that re-runs but emits identical
+ * output still re-runs its dependents (early cutoff was removed —
+ * rare in practice, not worth the cascade complexity).
+ *
+ * Patterns (Turbo/Nx micro-syntax + filter extensions):
+ *   '*'         all same-project upstream
+ *   '^*'        all dep-workspace upstream
+ *   'name'      same-project task `name`
+ *   '^name'     `name` task in every dep workspace
+ *   'pkg#name'  specific package's `name` task
+ *   '!<form>'   exclude — any of the above with a leading `!`
+ *
+ * Patterns are applied in order; last write wins, so
+ * `['*', '^*', '!^noisy']` reads as "all minus deps' noisy".
+ *
+ * Defaults:
+ *   - `filter === undefined` → all upstream contribute.
+ *   - `filter === []`        → none contribute (fully decoupled).
+ *
+ * Returns `[upstreamTaskId, hash]` pairs. The hash is the only thing
+ * folded into the cache key (the fold sorts by hash, so ordering here
+ * doesn't affect derivation); the task id rides along so Tier-3's
+ * `entry_inputs` rows can NAME which upstream a hash came from. The
+ * filter dedups by hash, as before — two upstream tasks with identical
+ * hashes contribute one pair (first id wins; their key contribution is
+ * identical anyway).
+ */
+export function filterUpstreamHashes(
+  upstream: TaskOutcome[],
+  filter: readonly string[] | undefined,
+  selfProjectName: string,
+  selfTaskId: string,
+): Array<[upstreamTaskId: string, hash: string]> {
+  if (filter === undefined) {
+    const out: Array<[string, string]> = []
+    for (const u of upstream) if (u.hash) out.push([u.node.id, u.hash])
+    return out
+  }
+
+  const specs: DependencySpec[] = filter.map((raw) => {
+    try {
+      return parseDependencySpec(raw)
+    } catch (err) {
+      if (err instanceof DependencySpecError) {
+        throw new UserError(`${selfTaskId}: cache.inputs.tasks: ${err.message}`)
+      }
+      throw err
+    }
+  })
+
+  // Dedup by hash (the key fold's unit), but remember the first task id
+  // seen for each hash so the diff row can name the upstream.
+  const selected = new Map<string, string>()
+  for (const spec of specs) {
+    for (const u of upstream) {
+      if (!u.hash) continue
+      const isSelf = u.node.projectName === selfProjectName
+      if (!matches(spec, u, isSelf)) continue
+      if (spec.negated) selected.delete(u.hash)
+      else if (!selected.has(u.hash)) selected.set(u.hash, u.node.id)
+    }
+  }
+  return [...selected].map(([hash, id]) => [id, hash])
+}
+
+function matches(spec: DependencySpec, u: TaskOutcome, isSelf: boolean): boolean {
+  switch (spec.kind) {
+    case 'wildcardSelf':
+      return isSelf
+    case 'wildcardDeps':
+      return !isSelf
+    case 'self':
+      return isSelf && u.node.taskName === spec.task
+    case 'deps':
+      return !isSelf && u.node.taskName === spec.task
+    case 'cross':
+      return u.node.projectName === spec.project && u.node.taskName === spec.task
+  }
+}

package/src/orchestrator/verify.ts

@@ -0,0 +1,141 @@
+// Cache-correctness verification (Phase 1: determinism). Pure helpers for the
+// `vx run --verify` hook in execute-task.ts: content-fingerprint a task's
+// output tree (mtime-independent) and diff two runs' trees, so a task whose
+// outputs are NOT a pure function of its declared inputs — a non-hermetic task
+// whose cache entry would replay arbitrary past bytes — is caught and named.
+// See docs/design/cache-correctness-2026-07.md.
+
+import path from 'node:path'
+import type { CacheLayer } from '../cache/index.js'
+import type { TaskOutcome, VerifyVerdict } from '../graph/index.js'
+
+/** An output file to fingerprint: absolute path + a stable, run-independent
+ *  key (project-relative, or `workspace-outputs/<rel-to-root>` for workspace
+ *  outputs — matching the cache artifact's namespace so the two never collide). */
+export interface OutputRef {
+  abs: string
+  key: string
+}
+
+/** Build the fingerprint key set from a task's resolved output paths. */
+export function outputRefs(
+  projectDir: string,
+  outputFiles: readonly string[],
+  workspaceRoot: string,
+  workspaceOutputFiles: readonly string[],
+): OutputRef[] {
+  const rel = (from: string, abs: string): string =>
+    path.relative(from, abs).split(path.sep).join('/')
+  return [
+    ...outputFiles.map((abs) => ({ abs, key: rel(projectDir, abs) })),
+    ...workspaceOutputFiles.map((abs) => ({
+      abs,
+      key: `workspace-outputs/${rel(workspaceRoot, abs)}`,
+    })),
+  ]
+}
+
+/** Content-fingerprint an output tree: key → git-blob OID. Reuses the same
+ *  `Cache.hashFile` primitive the input hashing folds, so it's byte-true and
+ *  mtime-independent — two byte-identical trees produce equal fingerprints
+ *  even though their tar.zst artifacts (which embed mtimes) would differ. */
+export async function hashOutputTree(
+  cache: CacheLayer,
+  refs: readonly OutputRef[],
+): Promise<Map<string, string>> {
+  const out = new Map<string, string>()
+  for (const r of refs) out.set(r.key, await cache.hashFile(r.abs))
+  return out
+}
+
+/** The output keys whose content OID differs between two fingerprints
+ *  (added, removed, or changed), sorted. */
+export function diffOutputTrees(a: Map<string, string>, b: Map<string, string>): string[] {
+  const changed: string[] = []
+  for (const k of new Set([...a.keys(), ...b.keys()])) {
+    if (a.get(k) !== b.get(k)) changed.push(k)
+  }
+  return changed.sort()
+}
+
+/** Turn a determinism diff into a verdict, honoring the `--verify-allow`
+ *  escape hatch (an allowed divergence is reported but never fails the run). */
+export function classifyDeterminism(changed: readonly string[], allowed: boolean): VerifyVerdict {
+  if (changed.length === 0) return { kind: 'proven-deterministic' }
+  return allowed
+    ? { kind: 'allowed-nondeterministic', changed }
+    : { kind: 'nondeterministic', changed }
+}
+
+/** Extract the workspace-relative paths a task read outside its declared inputs
+ *  (Phase 2, `--verify=inputs`). A strace-derived violation line carries the
+ *  offending absolute path in trailing brackets (`… [/abs/path]`); pull it out,
+ *  make it workspace-relative, dedup, and sort. Lines without a bracketed path
+ *  (e.g. macOS syscall lines) fall back to the raw line so nothing is lost. */
+export function undeclaredInputPaths(
+  violations: readonly { line: string }[],
+  workspaceRoot: string,
+): string[] {
+  const rels = new Set<string>()
+  for (const v of violations) {
+    const m = /\[([^\]]+)\]\s*$/.exec(v.line)
+    const raw = m ? m[1]! : v.line
+    rels.add(
+      path.isAbsolute(raw) ? path.relative(workspaceRoot, raw).split(path.sep).join('/') : raw,
+    )
+  }
+  return [...rels].sort()
+}
+
+/** The end-of-run `--verify` summary section: a counts line plus a
+ *  failures block naming each non-hermetic task and its diverging outputs.
+ *  Empty when no task carried a verdict. */
+export function formatVerifySection(outcomes: readonly TaskOutcome[]): string[] {
+  const verdicts = outcomes.filter((o) => o.verify !== undefined)
+  if (verdicts.length === 0) return []
+  let proven = 0
+  let bad = 0
+  let na = 0
+  let notVerified = 0
+  for (const o of verdicts) {
+    switch (o.verify!.kind) {
+      case 'proven-deterministic':
+      case 'proven-complete':
+        proven++
+        break
+      case 'nondeterministic':
+      case 'rerun-failed':
+      case 'undeclared-inputs':
+        bad++
+        break
+      case 'allowed-nondeterministic':
+      case 'no-outputs':
+        na++
+        break
+      case 'not-verified':
+        notVerified++
+        break
+    }
+  }
+  const lines = [
+    '',
+    `  Verify:   ${proven} proven · ${bad} unsafe · ${na} n/a · ${notVerified} not-verified`,
+  ]
+  for (const o of outcomes) {
+    const v = o.verify
+    if (v === undefined) continue
+    if (v.kind === 'nondeterministic') {
+      lines.push(`    ✗ ${o.node.id} — nondeterministic`)
+      lines.push(`        changed: ${v.changed.join(', ')}`)
+    } else if (v.kind === 'undeclared-inputs') {
+      lines.push(`    ✗ ${o.node.id} — read undeclared inputs`)
+      if (v.paths.length > 0) lines.push(`        ${v.paths.join(', ')}`)
+      lines.push('        add them to cache.inputs.files / workspaceFiles')
+    } else if (v.kind === 'rerun-failed') {
+      lines.push(`    ✗ ${o.node.id} — verify re-run failed (exit ${v.exitCode})`)
+    } else if (v.kind === 'allowed-nondeterministic') {
+      lines.push(`    ⚠ ${o.node.id} — nondeterministic (allowed)`)
+    }
+  }
+  return lines
+}

package/src/orchestrator/wire-render.ts

@@ -0,0 +1,92 @@
+// The inverse of `wireForwarder`: turn a stream of `WireEvent`s back into
+// `Logger` calls on a concrete renderer. A `vx serve` client feeds the
+// service's event stream through this into a normal `defaultLogger`, so a
+// DELEGATED run renders identically to a local one — the terminal
+// renderer stays completely untouched (it just receives reconstructed
+// node-shaped objects instead of live graph nodes). This file is the
+// whole adapter; it can be rewritten or removed without touching the
+// renderer or the producer side.
+
+import type { TaskNode, TaskOutcome } from '../graph/index.js'
+import type { Logger } from './logger.js'
+import type { OutcomeView, TaskView, WireEvent } from './events.js'
+
+/**
+ * Rebuild a node-shaped object from a `TaskView`. The formatters only ever
+ * read `id` / `projectName` / `taskName` / `requested` / `surfaced` and
+ * `config.exec` (presence ⇒ not a group; `.command`; `.persistent`), so a
+ * structural stand-in is indistinguishable from a real `TaskNode` to them.
+ */
+function reconstructNode(view: TaskView): TaskNode {
+  const exec = view.isGroup
+    ? undefined
+    : {
+        command: view.command ?? '',
+        ...(view.persistent ? { persistent: { readyWhen: '' } } : {}),
+      }
+  return {
+    id: view.id,
+    projectName: view.project,
+    taskName: view.task,
+    requested: view.requested,
+    surfaced: view.surfaced,
+    config: exec === undefined ? {} : { exec },
+  } as unknown as TaskNode
+}
+
+function reconstructOutcome(view: OutcomeView, node: TaskNode): TaskOutcome {
+  return {
+    node,
+    status: view.status,
+    exitCode: view.exitCode,
+    durationMs: view.durationMs,
+    ...(view.restored !== undefined ? { restored: view.restored } : {}),
+    ...(view.sandboxViolations !== undefined ? { sandboxViolations: view.sandboxViolations } : {}),
+    ...(view.sandboxViolationLines !== undefined
+      ? { sandboxViolationLines: view.sandboxViolationLines }
+      : {}),
+  } as TaskOutcome
+}
+
+/**
+ * Build a `WireEvent` consumer that drives `sink` (typically a
+ * `defaultLogger`). Stateful: it accumulates the reconstructed nodes from
+ * `task:start` so later `task:*` events can resolve their node by id.
+ */
+export function createWireRenderer(sink: Logger): (event: WireEvent) => void {
+  const nodes = new Map<string, TaskNode>()
+  return (event) => {
+    switch (event.kind) {
+      case 'run:start':
+        sink.runStart?.(event.info)
+        return
+      case 'task:start': {
+        const node = reconstructNode(event.task)
+        nodes.set(node.id, node)
+        sink.taskStart?.(node)
+        return
+      }
+      case 'task:stdout': {
+        const node = nodes.get(event.taskId)
+        if (node) sink.taskStdout(node, event.chunk)
+        return
+      }
+      case 'task:stderr': {
+        const node = nodes.get(event.taskId)
+        if (node) sink.taskStderr(node, event.chunk)
+        return
+      }
+      case 'task:complete': {
+        const node = nodes.get(event.outcome.taskId)
+        if (node) sink.taskComplete(node, reconstructOutcome(event.outcome, node))
+        return
+      }
+      case 'run:status':
+        sink.status(event.line)
+        return
+      case 'run:end':
+        sink.runEnd?.()
+        return
+    }
+  }
+}