@vzn/vx 0.0.638 → 0.0.639

package/src/{orchestrator → report}/forecast.ts

@@ -2,7 +2,7 @@
 // p50 in local history. A display aid for the live region only: it never
 // steers the scheduler and never reaches the final summary.
 
-import { isGroupTask, type TaskNode } from '../graph/index.js'
+import { computeReverseDepCount, isGroupTask, type TaskNode } from '../graph/index.js'
 
 /** What the live region says about the rest of a run. */
 export interface LiveForecast {
@@ -14,6 +14,18 @@ export interface LiveForecast {
   blocks: ReadonlyMap<string, number>
   /** Each running task's p50, where history knows it: the row's expected duration. */
   expected?: ReadonlyMap<string, number>
+  /**
+   * Tasks not started because a dependency has not finished, in the order
+   * the scheduler would start them, at most one per worker: what an idle
+   * worker row holds (M, 2026-10-15).
+   */
+  blocked?: readonly BlockedTask[]
+}
+
+/** A task an unfinished dependency holds back, and what holds it: the running task its longest chain waits on, else that dependency. */
+export interface BlockedTask {
+  id: string
+  by: string
 }
 
 export type Forecast = (
@@ -68,6 +80,14 @@ export function createForecast(
     if (p !== undefined) cost.set(n.id, p)
   }
   const workers = Math.max(1, concurrency)
+  // The scheduler's own baseline ranking, most dependents first, ties in
+  // graph order: once per run, as the scheduler computes it.
+  const rank = computeReverseDepCount(nodes)
+  const position = new Map(order.map((n, i) => [n.id, i]))
+  const before = (a: string, b: string): boolean => {
+    const d = (rank.get(a) ?? 0) - (rank.get(b) ?? 0)
+    return d !== 0 ? d > 0 : position.get(a)! < position.get(b)!
+  }
 
   const dependents = new Map<string, string[]>()
   for (const n of order)
@@ -106,6 +126,8 @@ export function createForecast(
     let work = 0
     let known = false
     let overrun = false
+    // The best `workers` blocked tasks, kept sorted as the pass meets them.
+    const held: BlockedTask[] = []
     for (const n of order) {
       if (finished.has(n.id)) continue
       let start = 0
@@ -120,6 +142,16 @@ export function createForecast(
       const since = running.get(n.id)
       if (since !== undefined) head.set(n.id, n.id)
       else if (via !== undefined && head.has(via)) head.set(n.id, head.get(via)!)
+      const by =
+        since === undefined ? (head.get(n.id) ?? n.deps.find((d) => end.has(d))) : undefined
+      if (by !== undefined && !isGroupTask(n)) {
+        let at = held.length
+        while (at > 0 && before(n.id, held[at - 1]!.id)) at--
+        if (at < workers) {
+          held.splice(at, 0, { id: n.id, by })
+          if (held.length > workers) held.pop()
+        }
+      }
       const p = cost.get(n.id)
       let own = 0
       if (p !== undefined) {
@@ -135,13 +167,14 @@ export function createForecast(
       }
       work += own
     }
-    if (!known || overrun) return { blocks, expected }
+    if (!known || overrun) return { blocks, expected, blocked: held }
     const critical = chainEnd === undefined ? undefined : head.get(chainEnd)
     return {
       etaMs: Math.max(chain, work / workers),
       ...(critical !== undefined ? { critical } : {}),
       blocks,
       expected,
+      blocked: held,
     }
   }
 }

package/src/{orchestrator → report}/framed-output.ts

@@ -27,32 +27,27 @@
 
 import { withForwardArgs } from '../exec/index.js'
 import { isGroupTask, type TaskNode, type TaskOutcome } from '../graph/index.js'
-import { formatElapsed, maskedCommand, paint, type ColorSupport } from '../util/index.js'
+import {
+  formatElapsed,
+  identityColor,
+  maskedCommand,
+  paint,
+  type ColorSupport,
+} from '../util/index.js'
 import { neverStarted } from './summary.js'
 import { outcomeLabel, ranNoCache, skippedReason } from './events.js'
 import { fileMemo, linkPaths } from './path-links.js'
-import { sandboxFixLine } from './sandbox-fix.js'
 
 const NO_COLOR: ColorSupport = { enabled: false }
 
 const ACCENT = '#06b6d4' // cyan-500 — bullets, remote-hit hint
-// Identity hues — deliberately outside the status palette (green /
-// red / yellow / cyan) so a task id can never read as an outcome.
-// Projects hash to a stable hue (same project = same color in every
-// run, list, and region row); tasks keep one fixed hue excluded from
-// the project palette so the two halves always read apart.
+// Identity hues (`identityColor`) are outside the status palette (green /
+// red / yellow / cyan) so a task id can never read as an outcome. Each
+// half of an id hashes its own name: same project, same hue; same target,
+// same hue, in every run, list and region row.
 // Section rules + the summary rule share one frame width.
 const FRAME_WIDTH = 60
 
-const PROJECT_PALETTE = [
-  '#a78bfa', // violet-400
-  '#60a5fa', // blue-400
-  '#e879f9', // fuchsia-400
-  '#818cf8', // indigo-400
-  '#c084fc', // purple-400
-  '#93c5fd', // blue-300
-] as const
-const TASK = '#f472b6' // pink-400 — task part of an id
 const SUCCESS = '#22c55e' // green-500 — success / fresh
 const WARN = '#eab308' // yellow-500 — skipped
 const ERROR = '#ef4444' // red-500 — failed
@@ -209,7 +204,8 @@ function pushOutputSection(
 function sectionLine(title: string, color: string, colors: ColorSupport): string {
   const corner = (s: string) => paint('', s, colors, { dim: true })
   const label = paint(color, title, colors, { bold: true })
-  const rule = corner('─'.repeat(Math.max(1, FRAME_WIDTH - 4 - title.length)))
+  const width = Math.min(FRAME_WIDTH, colors.columns ?? FRAME_WIDTH)
+  const rule = corner('─'.repeat(Math.max(1, width - 4 - title.length)))
   return `${corner('├─')} ${label} ${rule}`
 }
 
@@ -222,18 +218,9 @@ function pushBodyLines(lines: string[], text: string): void {
   for (const line of text.replace(/\n$/, '').split('\n')) lines.push(line)
 }
 
-/** Stable per-project hue: FNV-style fold of the name into the palette. */
-function projectColor(projectName: string): string {
-  let h = 0
-  for (let i = 0; i < projectName.length; i++) {
-    h = (h * 31 + projectName.charCodeAt(i)) >>> 0
-  }
-  return PROJECT_PALETTE[h % PROJECT_PALETTE.length]!
-}
-
 /**
- * `project#task` halves in distinct identity hues (never status
- * colors); the dim separator keeps them reading apart. `hueSource`
+ * `project#task` halves, each in its name's identity hue (never a status
+ * color); the dim separator keeps them reading apart. `hueSource`
  * exists for truncated display strings: the hue must hash from the
  * FULL project name so it survives truncation.
  */
@@ -242,13 +229,14 @@ export function paintIdParts(
   projectText: string,
   taskText: string,
   colors: ColorSupport,
-  opts: { bold?: boolean } = {},
+  opts: { bold?: boolean; sep?: '#' | ':' } = {},
 ): string {
   const dim = (t: string) => paint('', t, colors, { dim: true })
+  const { sep = '#', ...style } = opts
   return (
-    paint(projectColor(hueSource), projectText, colors, opts) +
-    dim('#') +
-    paint(TASK, taskText, colors, opts)
+    paint(identityColor(hueSource), projectText, colors, style) +
+    dim(sep) +
+    paint(identityColor(taskText), taskText, colors, style)
   )
 }
 
@@ -553,8 +541,10 @@ function violationSection(outcome: TaskOutcome, colors: ColorSupport): string[]
             : []),
           '',
         ]
+  // vx's own notes (`vx: …`) explain a failure; they are not denials.
+  const denials = body.filter((l) => !l.startsWith('vx: ')).length
   return [
-    sectionLine(`SANDBOX VIOLATIONS (${body.length})`, ERROR, colors),
+    sectionLine(denials > 0 ? `SANDBOX VIOLATIONS (${denials})` : 'SANDBOX', ERROR, colors),
     '',
     ...body,
     '',
@@ -704,3 +694,19 @@ function formatStatusTag(o: TaskOutcome, colors: ColorSupport): string {
       return o.status
   }
 }
+
+/**
+ * The fix as the config line it is: `exec.sandbox.allow: { read: ['a'] }`,
+ * or undefined when every denial was a withheld credential path.
+ */
+function sandboxFixLine({
+  withheld: _,
+  inputs: __,
+  ...fix
+}: NonNullable<TaskOutcome['sandboxFix']>): string | undefined {
+  if (Object.keys(fix).length === 0) return undefined
+  const parts = Object.entries(fix).map(
+    ([k, list]: [string, string[]]) => `${k}: [${list.map((p) => `'${p}'`).join(', ')}]`,
+  )
+  return `exec.sandbox.allow: { ${parts.join(', ')} }`
+}

package/src/report/index.ts

@@ -0,0 +1,36 @@
+// What a run tells the people and programs watching it: the event stream
+// every output surface subscribes to, the terminal renderer (framed task
+// output, the status line, the summary, the forecast) and the plain
+// output for non-TTY runs. It renders outcomes it is handed; it never
+// runs a task or reads the cache.
+export {
+  busLogger,
+  createEventBus,
+  type EventBus,
+  type OutcomeView,
+  outcomeWord,
+  projectNode,
+  projectOutcome,
+  ranNoCache,
+  type RunEvent,
+  type RunEventSubscriber,
+  type RunStartInfo,
+  type TaskView,
+  terminalSubscriber,
+  toWireEvent,
+  type WireEvent,
+  wireForwarder,
+} from './events.js'
+export {
+  type DefaultLogger,
+  defaultLogger,
+  type Logger,
+  type OutputView,
+  resolveOutputView,
+  warnOf,
+} from './logger.js'
+export { formatPersistentList } from './framed-output.js'
+export { createForecast } from './forecast.js'
+export { fileLocations, fileMemo, type OutputLocation } from './path-links.js'
+export { plainOutput } from './plain-output.js'
+export { formatOutcomeTable, formatRunSummary } from './summary.js'

package/src/{orchestrator → report}/logger.ts

@@ -17,10 +17,18 @@ import {
   createOutputWriter,
   formatFailureLine,
   formatStatusRegion,
+  formatStepLine,
   type StatusStream,
   type WorkerSlot,
 } from './status-line.js'
-import { formatSummarySection, neverStarted, ranUnsaved, type RunContext } from './summary.js'
+import {
+  cacheBucketOf,
+  formatSummarySection,
+  neverStarted,
+  ranUnsaved,
+  type CacheBucket,
+  type RunContext,
+} from './summary.js'
 import { isGroupTask } from '../graph/index.js'
 import {
   appendTail,
@@ -32,9 +40,9 @@ import {
   detectColors,
   type ColorSupport,
 } from '../util/index.js'
-import { isCacheHit } from './telemetry.js'
+import { isCacheHit } from '../graph/index.js'
 import { failedLabel, outcomeWord, ranNoCache } from './events.js'
-import type { Forecast } from './forecast.js'
+import type { BlockedTask, Forecast } from './forecast.js'
 import {
   notifyEscape,
   PROGRESS_CLEAR,
@@ -46,6 +54,12 @@ import {
 export interface Logger {
   /** Header / footer / status text. Written verbatim, one trailing \n added. */
   status(line: string): void
+  /**
+   * A warning: something worked, but look at it. The default logger writes
+   * it to stderr, so stdout carries only the rows and the footer. A logger
+   * without it gets warnings through `status`.
+   */
+  warn?(line: string): void
   /** Streamed stdout chunk for a task. Buffered until `taskComplete`. */
   taskStdout(node: TaskNode, chunk: string): void
   /** Streamed stderr chunk for a task. Buffered until `taskComplete`. */
@@ -70,8 +84,21 @@ export interface Logger {
     startedAtMs?: number
   }): void
   taskStart?(node: TaskNode): void
-  /** Run finished (any outcome). Idempotent. */
+  /** The task graph finished (any outcome); vx's own closing steps follow. Idempotent. */
   runEnd?(): void
+  /**
+   * One of vx's own steps (`vx:keys`, `@vzn/vx-otel:setup`) began or ended.
+   * Not a task: no stat, history row or telemetry record counts it.
+   */
+  stepStart?(id: string): void
+  stepEnd?(id: string, info: { durationMs: number; ok: boolean }): void
+  /** The run's work is done; the footer follows. Idempotent. */
+  runDone?(): void
+}
+
+/** `log.warn`, or `log.status` for a logger without it. */
+export function warnOf(log: Logger): (line: string) => void {
+  return log.warn !== undefined ? (line) => log.warn!(line) : (line) => log.status(line)
 }
 
 /** The logger `run()` builds when none is passed. */
@@ -82,6 +109,12 @@ export interface DefaultLogger extends Logger {
    * throw that never reached `runEnd`.
    */
   settle(): void
+  /**
+   * Whether vx's own steps show: only beside a live region, on a terminal.
+   * A log (CI, a pipe) stays free of rows whose presence is a timing.
+   * When false, run() never times a step (zero cost).
+   */
+  readonly showsSteps: boolean
   /**
    * Hand the live region a way to predict the run's end. Called once at
    * run start; `load` runs only if the region is still live a second in,
@@ -192,6 +225,8 @@ export function resolveOutputView(
 const FORECAST_AFTER_MS = 1000
 /** A run shorter than this ends without a desktop notification. */
 const NOTIFY_AFTER_MS = 10_000
+// A step of vx's own quicker than this shows nowhere (M, 2026-10-15).
+const STEP_SHOWN_MS = 150
 
 export function defaultLogger(
   colors: ColorSupport = detectColors(),
@@ -207,9 +242,12 @@ export function defaultLogger(
     footer?: boolean
     /** The environment that names the terminal (`TERM_PROGRAM`, …); `process.env` by default. */
     env?: Readonly<Record<string, string | undefined>>
+    /** Where warnings go; `process.stderr` by default. */
+    err?: StatusStream
   } = {},
 ): DefaultLogger {
   const forwardArgs = opts.forwardArgs ?? []
+  const errOut = opts.err ?? process.stderr
   // Per-task buffers, split by stream. Splitting lets the framed-output
   // renderer put stdout under `├─ stdout` and stderr under `├─ stderr`.
   // The price: chunks that interleaved at runtime get re-ordered (all
@@ -303,6 +341,10 @@ export function defaultLogger(
   let critical: string | undefined
   let blocks: ReadonlyMap<string, number> | undefined
   let expected: ReadonlyMap<string, number> | undefined
+  let blocked: readonly BlockedTask[] | undefined
+  // The blocked task each idle worker row holds, by slot: a row keeps its
+  // task until it starts, in that row, or leaves the list, so nothing hops.
+  const heldRows: (string | null)[] = []
   let etaAtMs = 0
   const signals = writer.enabled
     ? terminalSignals(opts.env ?? process.env)
@@ -334,6 +376,15 @@ export function defaultLogger(
   let notSaved = 0
   let skippedCount = 0
   let savedMs = 0
+  // Each finished task's cache bucket by its key: its remote traffic moves it.
+  const buckets = new Map<string, CacheBucket>()
+  // The graph is done and vx's own closing steps run: the region stays,
+  // footer and step rows, until the footer replaces it (M, 2026-10-15).
+  let tail = false
+  // No footer before the run starts: vx's opening steps show alone.
+  let started = false
+  // vx's own steps running now, by id: a row once one passes STEP_SHOWN_MS.
+  const steps = new Map<string, number>()
   // Cache-miss duration spread, accumulated incrementally (the same
   // numbers the final summary computes from the outcome list).
   let spreadMax = 0
@@ -409,7 +460,7 @@ export function defaultLogger(
     if (statusDead) return
     const now = Date.now()
     // Twice a second at most: one pass over the unfinished graph.
-    if (forecastFn !== undefined && (force || now - etaAtMs >= 500)) {
+    if (forecastFn !== undefined && !tail && (force || now - etaAtMs >= 500)) {
       etaAtMs = now
       const running = new Map<string, number>()
       for (const s of slots) if (s !== null) running.set(s.id, s.startedMs)
@@ -419,6 +470,7 @@ export function defaultLogger(
       critical = f.critical
       blocks = f.blocks
       expected = f.expected
+      blocked = f.blocked
     }
     if (signals.progress && total > 0) {
       const elapsed = now - startedAtMs
@@ -437,7 +489,7 @@ export function defaultLogger(
     // The live summary IS the final summary's section, built from the
     // same formatter so the region visually becomes the printout.
     const summaryLines =
-      opts.footer === false
+      opts.footer === false || !started
         ? []
         : formatSummarySection(
             {
@@ -454,7 +506,8 @@ export function defaultLogger(
               noCache,
               savedMs,
               left: total - done,
-              ...(etaMs !== undefined ? { etaMs } : {}),
+              ...(etaMs !== undefined && !tail ? { etaMs } : {}),
+              buckets,
               spread:
                 spreadCount > 0
                   ? { maxMs: spreadMax, minMs: spreadMin, sumMs: spreadSum, count: spreadCount }
@@ -464,12 +517,18 @@ export function defaultLogger(
             colors,
             runContext,
           )
+    const held = blocked === undefined ? undefined : holdRows(blocked)
+    const shownSteps: WorkerSlot[] = []
+    for (const [id, startedMs] of steps)
+      if (now - startedMs >= STEP_SHOWN_MS) shownSteps.push({ id, startedMs })
     writer.setRegion(
       formatStatusRegion(
         {
           pinnedPersistent,
           slots: slots.slice(0, shownSlots),
+          ...(held !== undefined ? { blocked: held } : {}),
           overflow: slotQueue.length,
+          ...(shownSteps.length > 0 ? { steps: shownSteps } : {}),
           nowMs: Date.now(),
           summaryLines,
           ...(blocks !== undefined ? { blocks } : {}),
@@ -481,6 +540,46 @@ export function defaultLogger(
       { force },
     )
   }
+  // Each idle worker row holds a blocked task, in scheduler order. A row
+  // with none left to hold leaves the region (M, 2026-10-15): blocked tasks
+  // only dwindle, so it is never needed again, and the rows below close up.
+  const holdRows = (list: readonly BlockedTask[]): (BlockedTask | null)[] => {
+    const started = new Set<string>()
+    for (const s of slots) if (s !== null) started.add(s.id)
+    for (const s of slotQueue) started.add(s.id)
+    const open = new Map<string, BlockedTask>()
+    for (const b of list) if (!started.has(b.id)) open.set(b.id, b)
+    const rows: (BlockedTask | null)[] = []
+    for (let i = 0; i < shownSlots; i++) {
+      const kept = slots[i] === null ? open.get(heldRows[i] ?? '') : undefined
+      rows.push(kept ?? null)
+      if (kept !== undefined) open.delete(kept.id)
+    }
+    const rest = open.values()
+    for (let i = 0; i < shownSlots; i++)
+      if (slots[i] === null && rows[i] === null) rows[i] = rest.next().value ?? null
+    for (let i = shownSlots - 1; i >= 0; i--) {
+      if (slots[i] !== null || rows[i] !== null) continue
+      rows.splice(i, 1)
+      slots.splice(i, 1)
+      slots.push(null)
+      shownSlots--
+    }
+    heldRows.length = 0
+    for (const r of rows) heldRows.push(r?.id ?? null)
+    return rows
+  }
+  const tick = (): void => {
+    if (!writer.enabled || statusDead || ticker !== null) return
+    // Keeps the per-worker elapsed time ticking between task events
+    // (the time IS the motion — there's no spinner). The writer
+    // throttles unforced redraws, and unref means a stray ticker
+    // can never hold the process open.
+    ticker = setInterval(() => {
+      refresh(false)
+    }, 100)
+    ticker.unref?.()
+  }
   const killStatus = (): void => {
     if (ticker !== null) {
       clearInterval(ticker)
@@ -504,7 +603,11 @@ export function defaultLogger(
   // no task row (`status`). Without a footer, the caller frames the log
   // (`vx watch` opens each cycle with its own line).
   let logOpened = opts.footer === false
+  // The log ends on a blank line (a block's own): a blank status line
+  // after it (the footer's) would make two; one blank line apart is the rule.
+  let endsBlank = false
   const taskWrite = (chunk: string): void => {
+    if (chunk.length > 0) endsBlank = chunk.endsWith('\n\n')
     if (!logOpened && chunk.length > 0) {
       logOpened = true
       writer.write(`\n${chunk}`)
@@ -559,6 +662,7 @@ export function defaultLogger(
     flakyNote(outcome, colors)
 
   return {
+    showsSteps: writer.enabled,
     settle() {
       // The bus delivers one `run:end`, so the CLI's last word reaches here.
       flushKept()
@@ -574,28 +678,46 @@ export function defaultLogger(
         writer.write('\n')
         streamMidLine = false
       }
+      if (line === '' && endsBlank) return
+      endsBlank = line === ''
       writer.write(`${line}\n`)
     },
+    warn(line) {
+      flushKept()
+      if (streamMidLine) {
+        writer.write('\n')
+        streamMidLine = false
+      }
+      writer.writeTo(errOut, `${line}\n`)
+    },
     runStart(info) {
       total = info.total
       requestedCount = info.requestedCount ?? requestedCount
       runContext = info.context
       startedAtMs = Date.now()
+      started = true
       const cap = Math.max(1, Math.min(info.concurrency ?? 10, 10))
       slots = Array.from({ length: cap }, () => null)
       shownSlots = 0
-      if (writer.enabled && !statusDead && ticker === null) {
-        // Keeps the per-worker elapsed time ticking between task events
-        // (the time IS the motion — there's no spinner). The writer
-        // throttles unforced redraws, and unref means a stray ticker
-        // can never hold the process open.
-        ticker = setInterval(() => {
-          refresh(false)
-        }, 100)
-        ticker.unref?.()
-      }
+      tick()
       refresh(true)
     },
+    stepStart(id) {
+      steps.set(id, Date.now())
+      // Drawn by the ticker once it passes STEP_SHOWN_MS; a quicker one never is.
+      tick()
+    },
+    stepEnd(id, { durationMs, ok }) {
+      steps.delete(id)
+      if (durationMs < STEP_SHOWN_MS) return
+      if (ok ? view.mode !== 'none' && view.mode !== 'errors-only' : view.mode !== 'none')
+        emitLine(formatStepLine(id, durationMs, ok, colors))
+      refresh(true)
+    },
+    runDone() {
+      tail = false
+      killStatus()
+    },
     taskStart(node) {
       if (isGroupTask(node)) return
       if (holdsTerminal(node)) {
@@ -619,7 +741,14 @@ export function defaultLogger(
         persistentTails.set(node.id, { node, out: createTail(), err: createTail() })
       }
       const slot: WorkerSlot = { id: node.id, startedMs: Date.now() }
-      const free = slots.indexOf(null)
+      // A blocked task starts in the row that held it; another takes a free
+      // row, else the last held one, whose task moves to the next free row.
+      const own = heldRows.indexOf(node.id)
+      let free = own >= 0 && slots[own] === null ? own : -1
+      if (free < 0)
+        free = slots.findIndex((s, i) => s === null && i < shownSlots && heldRows[i] == null)
+      if (free < 0) free = slots.findLastIndex((s, i) => s === null && i < shownSlots)
+      if (free < 0) free = slots.indexOf(null)
       if (free >= 0) {
         slots[free] = slot
         shownSlots = Math.max(shownSlots, free + 1)
@@ -645,7 +774,7 @@ export function defaultLogger(
     runEnd() {
       // A long run says it ended where the user is not looking. Once:
       // the status is dead after the first runEnd.
-      if (signals.notify && !statusDead && Date.now() - startedAtMs >= NOTIFY_AFTER_MS) {
+      if (signals.notify && !statusDead && !tail && Date.now() - startedAtMs >= NOTIFY_AFTER_MS) {
         out.write(
           notifyEscape(
             failed > 0
@@ -654,7 +783,14 @@ export function defaultLogger(
           ),
         )
       }
-      killStatus()
+      if (!tail && !statusDead) {
+        tail = true
+        slots = []
+        blocked = undefined
+        shownSlots = 0
+        slotQueue.length = 0
+        refresh(true)
+      } else if (!tail) killStatus()
       // Persistent tails first: they are context for whatever ran against
       // the server, so they read above the failures they explain. `none`
       // prints no per-task output and `errors-only` only failed tasks: a
@@ -837,6 +973,8 @@ export function defaultLogger(
           const qi = slotQueue.findIndex((s) => s.id === node.id)
           if (qi >= 0) slotQueue.splice(qi, 1)
         }
+        const bucket = outcome.hash === undefined ? undefined : cacheBucketOf(outcome)
+        if (bucket !== undefined) buckets.set(outcome.hash!, bucket)
         switch (outcome.status) {
           case 'success':
             succeeded++