@vzn/vx 0.0.623 → 0.0.624

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vzn/vx",
-  "version": "0.0.623",
+  "version": "0.0.624",
   "description": "The fastest task runner and build cache for JavaScript monorepos.",
   "type": "module",
   "exports": {
@@ -21,10 +21,10 @@
     "node": ">=18"
   },
   "optionalDependencies": {
-    "@vzn/vx-linux-x64": "0.0.623",
-    "@vzn/vx-linux-arm64": "0.0.623",
-    "@vzn/vx-darwin-x64": "0.0.623",
-    "@vzn/vx-darwin-arm64": "0.0.623"
+    "@vzn/vx-linux-x64": "0.0.624",
+    "@vzn/vx-linux-arm64": "0.0.624",
+    "@vzn/vx-darwin-x64": "0.0.624",
+    "@vzn/vx-darwin-arm64": "0.0.624"
   },
   "dependencies": {
     "@anthropic-ai/sandbox-runtime": "^0.0.76"

package/src/orchestrator/forecast.ts

@@ -0,0 +1,139 @@
+// How long the rest of a live run should take, from each task's executed
+// 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'
+
+/** What the live region says about the rest of a run. */
+export interface LiveForecast {
+  /** Remaining wall ms, absent when history knows none of what is left. */
+  etaMs?: number
+  /** The running task at the head of the longest unfinished chain. */
+  critical?: string
+  /** Each running task's unfinished dependents, direct and transitive. */
+  blocks: ReadonlyMap<string, number>
+}
+
+export type Forecast = (
+  finished: ReadonlySet<string>,
+  running: ReadonlyMap<string, number>,
+  nowMs: number,
+) => LiveForecast
+
+/** How far past its p50 a running task may go before the forecast gives up. */
+const OVERRUN = 1.25
+
+/**
+ * The later of the longest unfinished chain and the unfinished work spread
+ * over the workers. A task still to run costs its p50 (a pending task may
+ * yet hit, so this leans long, and the hits finish first); a running one
+ * costs what its p50 has left, never below zero; a group or a task with no
+ * history costs nothing. A running task well past its p50 means history
+ * no longer describes this run, and the forecast says nothing of time.
+ */
+export function createForecast(
+  nodes: ReadonlyMap<string, TaskNode>,
+  p50s: ReadonlyMap<string, number>,
+  concurrency: number,
+): Forecast {
+  // Dependencies before dependents, once: each call is one pass over it.
+  const order: TaskNode[] = []
+  const placed = new Set<string>()
+  const place = (n: TaskNode): void => {
+    const stack: Array<[TaskNode, number]> = [[n, 0]]
+    while (stack.length > 0) {
+      const top = stack[stack.length - 1]!
+      const [node, i] = top
+      if (placed.has(node.id)) {
+        stack.pop()
+        continue
+      }
+      if (i < node.deps.length) {
+        top[1] = i + 1
+        const dep = nodes.get(node.deps[i]!)
+        if (dep !== undefined && !placed.has(dep.id)) stack.push([dep, 0])
+        continue
+      }
+      placed.add(node.id)
+      order.push(node)
+      stack.pop()
+    }
+  }
+  for (const n of nodes.values()) place(n)
+  const cost = new Map<string, number>()
+  for (const n of order) {
+    const p = isGroupTask(n) ? undefined : p50s.get(n.id)
+    if (p !== undefined) cost.set(n.id, p)
+  }
+  const workers = Math.max(1, concurrency)
+
+  const dependents = new Map<string, string[]>()
+  for (const n of order)
+    for (const d of n.deps) {
+      const list = dependents.get(d)
+      if (list === undefined) dependents.set(d, [n.id])
+      else list.push(n.id)
+    }
+
+  const blocked = (id: string, finished: ReadonlySet<string>): number => {
+    const seen = new Set<string>()
+    const stack = [id]
+    while (stack.length > 0) {
+      for (const next of dependents.get(stack.pop()!) ?? []) {
+        if (seen.has(next) || finished.has(next)) continue
+        seen.add(next)
+        stack.push(next)
+      }
+    }
+    return seen.size
+  }
+
+  return (finished, running, nowMs) => {
+    const blocks = new Map<string, number>()
+    for (const id of running.keys()) blocks.set(id, blocked(id, finished))
+    const end = new Map<string, number>()
+    // The running task each node's longest chain waits on.
+    const head = new Map<string, string>()
+    let chain = 0
+    let chainEnd: string | undefined
+    let work = 0
+    let known = false
+    let overrun = false
+    for (const n of order) {
+      if (finished.has(n.id)) continue
+      let start = 0
+      let via: string | undefined
+      for (const d of n.deps) {
+        const e = end.get(d)
+        if (e !== undefined && (via === undefined || e > start)) {
+          start = e
+          via = d
+        }
+      }
+      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 p = cost.get(n.id)
+      let own = 0
+      if (p !== undefined) {
+        known = true
+        if (since !== undefined && nowMs - since > p * OVERRUN) overrun = true
+        own = since === undefined ? p : Math.max(0, p - (nowMs - since))
+      }
+      const e = start + own
+      end.set(n.id, e)
+      if (e > chain || chainEnd === undefined) {
+        chain = e
+        chainEnd = n.id
+      }
+      work += own
+    }
+    if (!known || overrun) return { blocks }
+    const critical = chainEnd === undefined ? undefined : head.get(chainEnd)
+    return {
+      etaMs: Math.max(chain, work / workers),
+      ...(critical !== undefined ? { critical } : {}),
+      blocks,
+    }
+  }
+}

package/src/orchestrator/logger.ts

@@ -31,6 +31,13 @@ import {
 } from '../util/index.js'
 import { isCacheHit } from './telemetry.js'
 import { failedLabel, outcomeWord, ranNoCache } from './events.js'
+import type { Forecast } from './forecast.js'
+import {
+  notifyEscape,
+  PROGRESS_CLEAR,
+  progressEscape,
+  terminalSignals,
+} from './terminal-signals.js'
 
 export interface Logger {
   /** Header / footer / status text. Written verbatim, one trailing \n added. */
@@ -71,6 +78,12 @@ export interface DefaultLogger extends Logger {
    * throw that never reached `runEnd`.
    */
   settle(): void
+  /**
+   * 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,
+   * so a run that ends sooner never reads history for it.
+   */
+  forecast(load: () => Promise<Forecast>): void
 }
 
 /**
@@ -168,6 +181,11 @@ export function resolveOutputView(
   return mk('full')
 }
 
+/** A run shorter than this never reads history for a forecast. */
+const FORECAST_AFTER_MS = 1000
+/** A run shorter than this ends without a desktop notification. */
+const NOTIFY_AFTER_MS = 10_000
+
 export function defaultLogger(
   colors: ColorSupport = detectColors(),
   view: OutputView = { mode: 'full' },
@@ -178,6 +196,8 @@ export function defaultLogger(
     tty?: boolean
     /** The args after `--`: a requested task's `$ <command>` line shows them, as it ran. */
     forwardArgs?: readonly string[]
+    /** The environment that names the terminal (`TERM_PROGRAM`, …); `process.env` by default. */
+    env?: Readonly<Record<string, string | undefined>>
   } = {},
 ): DefaultLogger {
   const forwardArgs = opts.forwardArgs ?? []
@@ -266,6 +286,20 @@ export function defaultLogger(
   let startedAtMs = Date.now()
   let ticker: ReturnType<typeof setInterval> | null = null
   let statusDead = !writer.enabled
+  // The live run's forecast (live region only). Finished ids feed it; the
+  // set is kept only where a region can show the answer.
+  const finished = new Set<string>()
+  let forecastFn: Forecast | undefined
+  let forecastTimer: ReturnType<typeof setTimeout> | null = null
+  let etaMs: number | undefined
+  let critical: string | undefined
+  let blocks: ReadonlyMap<string, number> | undefined
+  let etaAtMs = 0
+  const signals = writer.enabled
+    ? terminalSignals(opts.env ?? process.env)
+    : { progress: false, notify: false }
+  let progressShown = -1
+  let progressRed = false
 
   // Every interactive view renders the fixed-height worker region:
   // one row per worker slot so a task's name never moves while it
@@ -357,6 +391,32 @@ export function defaultLogger(
 
   const refresh = (force: boolean): void => {
     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)) {
+      etaAtMs = now
+      const running = new Map<string, number>()
+      for (const s of slots) if (s !== null) running.set(s.id, s.startedMs)
+      for (const s of slotQueue) running.set(s.id, s.startedMs)
+      const f = forecastFn(finished, running, now)
+      etaMs = f.etaMs
+      critical = f.critical
+      blocks = f.blocks
+    }
+    if (signals.progress && total > 0) {
+      const elapsed = now - startedAtMs
+      const pct = Math.floor(
+        etaMs !== undefined && elapsed + etaMs > 0
+          ? (elapsed / (elapsed + etaMs)) * 100
+          : (done / total) * 100,
+      )
+      // Never backwards: a forecast that gives up falls back to the count.
+      if (pct > progressShown || failed > 0 !== progressRed) {
+        progressShown = Math.max(pct, progressShown)
+        progressRed = failed > 0
+        out.write(progressEscape(progressShown, progressRed))
+      }
+    }
     // The live summary IS the final summary's section, built from the
     // same formatter so the region visually becomes the printout.
     const summaryLines = formatSummarySection(
@@ -372,6 +432,7 @@ export function defaultLogger(
         noCache,
         savedMs,
         left: total - done,
+        ...(etaMs !== undefined ? { etaMs } : {}),
         spread:
           spreadCount > 0
             ? { maxMs: spreadMax, minMs: spreadMin, sumMs: spreadSum, count: spreadCount }
@@ -389,6 +450,8 @@ export function defaultLogger(
           overflow: slotQueue.length,
           nowMs: Date.now(),
           summaryLines,
+          ...(blocks !== undefined ? { blocks } : {}),
+          ...(critical !== undefined ? { critical } : {}),
         },
         colors,
       ),
@@ -400,6 +463,14 @@ export function defaultLogger(
       clearInterval(ticker)
       ticker = null
     }
+    if (forecastTimer !== null) {
+      clearTimeout(forecastTimer)
+      forecastTimer = null
+    }
+    if (progressShown >= 0) {
+      progressShown = -1
+      out.write(PROGRESS_CLEAR)
+    }
     if (statusDead) return
     statusDead = true
     writer.clearStatus()
@@ -516,7 +587,34 @@ export function defaultLogger(
       else slotQueue.push(slot)
       refresh(true)
     },
+    forecast(load) {
+      if (statusDead || forecastTimer !== null) return
+      forecastTimer = setTimeout(() => {
+        forecastTimer = null
+        if (statusDead) return
+        load().then(
+          (f) => {
+            forecastFn = f
+            if (!statusDead) refresh(true)
+          },
+          // History is observability: an unreadable one forecasts nothing.
+          () => {},
+        )
+      }, FORECAST_AFTER_MS)
+      forecastTimer.unref?.()
+    },
     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) {
+        out.write(
+          notifyEscape(
+            failed > 0
+              ? `vx: ${failed} of ${total} task${total === 1 ? '' : 's'} failed`
+              : `vx: ${total} task${total === 1 ? '' : 's'} done`,
+          ),
+        )
+      }
       killStatus()
       // Persistent tails first: they are context for whatever ran against
       // the server, so they read above the failures they explain. `none`
@@ -603,6 +701,7 @@ export function defaultLogger(
       pushChunk(stderrBuffers, node.id, chunk)
     },
     taskComplete(node, outcome) {
+      if (!statusDead) finished.add(node.id)
       // A persistent task buffered into its bounded tail rather than the
       // per-task buffers (see taskStart), so its frame is drained from
       // there — carrying how much the cap dropped, since a truncated log

package/src/orchestrator/run.ts

@@ -63,10 +63,11 @@ import { buildAdmission, executorLabel, resolveExecutors, teardownPlugins } from
 import { subscribeTelemetry, type TelemetryHandle } from './telemetry-host.js'
 import { assembleRunSummary, isPassStatus } from './telemetry.js'
 import type { RunContextRecord } from './telemetry.js'
-import { defaultLogger, resolveOutputView, type Logger } from './logger.js'
+import { defaultLogger, type DefaultLogger, resolveOutputView, type Logger } from './logger.js'
 import { detectColors, type ColorSupport } from './colors.js'
 import { plainOutput } from './plain-output.js'
 import { formatPersistentList } from './framed-output.js'
+import { createForecast } from './forecast.js'
 import { LocalHistoryProvider } from './history.js'
 import { plan, type RunPlan } from './plan.js'
 import { prepareRun, type PreparedRun } from './prepare.js'
@@ -339,7 +340,7 @@ export async function run(options: RunOptions): Promise<RunSummary> {
   }
   let held = false
   try {
-    const summary = await runOnBus(options, bus, colors)
+    const summary = await runOnBus(options, bus, colors, terminal)
     if (summary.persistent === undefined) return summary
     // Servers handed back still running still write: `vx watch dev` printed
     // none of its server's log while it idled, the renderer gone with this
@@ -362,6 +363,7 @@ async function runOnBus(
   options: RunOptions,
   bus: EventBus,
   colors: ColorSupport,
+  terminal: DefaultLogger | null,
 ): Promise<RunSummary> {
   const log = busLogger(bus)
   // A server's output goes through a cell of its own: a later watch cycle
@@ -889,6 +891,14 @@ async function runOnBus(
       context: runContext,
       startedAtMs: endedAtMsAtStart,
     })
+    // The live region's end-of-run forecast. The logger asks only if its
+    // region is still up a second in, so a warm run never reads history.
+    terminal?.forecast(async () => {
+      const ids: string[] = []
+      for (const n of nodes.values()) if (!isGroupTask(n)) ids.push(n.id)
+      const p50s = await new LocalHistoryProvider(prepared.localCache.dbHandle()).p50sFor(ids)
+      return createForecast(nodes, p50s, concurrency)
+    })
 
     // Remote-only: kick off background prefetches so remote-GET latency
     // overlaps execution. Fire-and-forget — execution starts on the next

package/src/orchestrator/status-line.ts

@@ -12,6 +12,7 @@ const NO_COLOR: ColorSupport = { enabled: false }
 // Same palette as framed-output.ts so glyphs and stats agree.
 const ACCENT = '#06b6d4'
 const ERROR = '#ef4444'
+const WARN = '#eab308' // yellow-500, as the summary's
 
 /** Erase the current line and return the cursor to column 0. */
 const CLEAR = '\x1b[2K\r'
@@ -241,6 +242,10 @@ export interface WorkerSlot {
 }
 
 export interface StatusRegionState {
+  /** A running task's unfinished dependents (`blocks 14` on its row); 0 says nothing. */
+  blocks?: ReadonlyMap<string, number>
+  /** The running task at the head of the longest unfinished chain. */
+  critical?: string
   /**
    * Ready persistent tasks (dev servers …) whose children keep
    * running after their outcome lands. Pinned until runEnd — the
@@ -331,11 +336,19 @@ export function formatStatusRegion(
   // the ticking time IS the motion), then `running`, full id (never
   // truncated — name is the last column). Idle rows hold their slot's
   // place, dim, aligned under the status column.
+  // One task running has no path to compare against.
+  const busy = s.slots.filter((x) => x !== null).length
   for (const slot of s.slots) {
     if (slot === null) {
       lines.push(`${' '.repeat(3 + TIME_COL + 1)}${paint(IDLE, 'idle', colors, { dim: true })}`)
       continue
     }
+    // What waits on it, after the id: the row to watch is the one the
+    // longest chain waits on, and the one the most tasks wait on.
+    const waiting = s.blocks?.get(slot.id) ?? 0
+    const notes: string[] = []
+    if (s.critical === slot.id && busy > 1) notes.push(paint(WARN, 'critical path', colors))
+    if (waiting > 0) notes.push(dim(`blocks ${waiting}`))
     lines.push(
       formatTaskRow(
         ' ',
@@ -346,7 +359,7 @@ export function formatStatusRegion(
         '',
         paintPinnedId(slot.id, colors),
         colors,
-      ),
+      ) + (notes.length > 0 ? `  ${notes.join(dim(' \u00b7 '))}` : ''),
     )
   }
   if (s.overflow > 0) {

package/src/orchestrator/summary.ts

@@ -21,6 +21,7 @@ const LOCAL = '#38bdf8' // sky-400
 const REMOTE = '#2563eb' // blue-600
 const ERROR = '#ef4444'
 const ABORTED = '#f97316' // orange-500: red's neighbour, not a failure
+const ACCENT = '#06b6d4' // cyan-500: the live region's running word
 
 const BAR_WIDTH = 50
 // Brand gradient for the rule: identity violet → pink (the project /
@@ -120,6 +121,8 @@ export interface SummaryStats {
   spread: { maxMs: number; minMs: number; sumMs: number; count: number } | null
   /** Tasks an `admit` policy held with a worker free, and the waits summed. Absent with no hold. */
   held?: { count: number; sumMs: number }
+  /** Live section only: the forecast of what is left, from history. */
+  etaMs?: number
   /** The hits' stored exec times summed: the work the cache skipped. */
   savedMs?: number
   /** A run of groups only: their names, so `0 tasks` says why. */
@@ -269,6 +272,11 @@ export function formatSummarySection(
     const { maxMs, minMs, sumMs, count } = stats.spread
     spread = ` ${dim(`\u00b7 max ${formatElapsed(maxMs)} \u00b7 avg ${formatElapsed(sumMs / count)} \u00b7 min ${formatElapsed(minMs)}`)}`
   }
+  // The live run's forecast leads the spread: the one number on the row
+  // that is about the future.
+  if (stats.etaMs !== undefined) {
+    spread = ` ${dim('\u00b7')} ${paint(ACCENT, `${formatEta(stats.etaMs)} left`, colors)}${spread}`
+  }
   // Run-shape footer (final summary only): worker pool + cache mode,
   // grouped with time under a blank line below the meters.
   if (context !== undefined) {
@@ -296,6 +304,17 @@ export function formatSummarySection(
   return lines
 }
 
+/**
+ * A forecast, said as coarsely as it is known: `~4s`, `~2m 05s`, `<1s`
+ * once the history says the end is due.
+ */
+function formatEta(ms: number): string {
+  if (ms < 1000) return '<1s'
+  const s = Math.ceil(ms / 1000)
+  if (s < 60) return `~${s}s`
+  return `~${Math.floor(s / 60)}m ${String(s % 60).padStart(2, '0')}s`
+}
+
 /**
  * `42 tasks · 38 cached (90%) · 3.2s`, `2 tasks · all cached · 23ms`,
  * with the failures first when there are any. Cached is every hit (up to

package/src/orchestrator/terminal-signals.ts

@@ -0,0 +1,45 @@
+// Zero-width escapes some terminals act on: a progress bar on the tab or
+// taskbar (OSC 9;4) and a desktop notification (OSC 9). Sent only to a
+// terminal known to read them: elsewhere OSC 9 IS the notification, so a
+// progress update would post "4;1;40" as one.
+
+export interface TerminalSignals {
+  progress: boolean
+  notify: boolean
+}
+
+/** What the terminal `env` names can show; tmux and screen hide it, so they get neither. */
+export function terminalSignals(
+  env: Readonly<Record<string, string | undefined>>,
+): TerminalSignals {
+  const program = env['TERM_PROGRAM']
+  if (program === 'ghostty') return { progress: true, notify: true }
+  // iTerm2 posts OSC 9 since 3.0 and draws OSC 9;4 since 3.6.
+  if (program === 'iTerm.app')
+    return { progress: atLeast(env['TERM_PROGRAM_VERSION'], 3, 6), notify: true }
+  if (program === 'WezTerm') return { progress: false, notify: true }
+  // Windows Terminal and ConEmu draw the progress; neither posts OSC 9.
+  if (env['WT_SESSION'] !== undefined || env['ConEmuPID'] !== undefined)
+    return { progress: true, notify: false }
+  return { progress: false, notify: false }
+}
+
+function atLeast(version: string | undefined, major: number, minor: number): boolean {
+  const m = /^(\d+)\.(\d+)/.exec(version ?? '')
+  if (m === null) return false
+  const [a, b] = [Number(m[1]), Number(m[2])]
+  return a > major || (a === major && b >= minor)
+}
+
+/** Tab / taskbar progress at `pct` (0–100), or `error` to draw it red. */
+export function progressEscape(pct: number, error = false): string {
+  return `\x1b]9;4;${error ? 2 : 1};${Math.max(0, Math.min(100, Math.round(pct)))}\x07`
+}
+
+export const PROGRESS_CLEAR = '\x1b]9;4;0;0\x07'
+
+/** A desktop notification. BEL and ESC end the sequence, so neither may ride in `text`. */
+export function notifyEscape(text: string): string {
+  // eslint-disable-next-line no-control-regex -- the control range is the point
+  return `\x1b]9;${text.replace(/[\x00-\x1f\x7f]/g, ' ')}\x07`
+}