@vzn/vx 0.0.638 → 0.0.640

package/src/orchestrator/task-process.ts

@@ -0,0 +1,94 @@
+// What a task's process runs with (its env, its timeout) and what an
+// undeclared write costs the run's memos. Shared by the one-shot path
+// (execute-task.ts) and the server path (persistent-task.ts).
+
+import path from 'node:path'
+import type { ExecConfig } from '../config.js'
+import type { GitFilesCache } from '../cache/index.js'
+import {
+  buildIsolatedEnv,
+  packageManagerPath,
+  PM_EXEC_ENV,
+  VX_RUN_TASK_ENV,
+  VX_RUN_WORKSPACE_ENV,
+} from '../exec/index.js'
+import type { TaskNode } from '../graph/index.js'
+import { parseDuration } from '../util/index.js'
+
+/**
+ * Drop the run's facts about files a task may have written without
+ * declaring them (`undeclaredWriteReach`): the project's git snapshot and
+ * its index OIDs. The next reader
+ * re-enumerates the project (one `git ls-files`) and hashes its files by
+ * content; the per-declaration file-list memos are keyed on the snapshot
+ * array, so they miss with it (item 743).
+ */
+export function forgetUndeclaredWrites(
+  args: { node: TaskNode; gitFilesCache?: GitFilesCache | undefined },
+  reach: 'none' | 'project' | 'workspace',
+): void {
+  if (reach === 'none') return
+  if (reach === 'workspace') {
+    args.gitFilesCache?.clear()
+    return
+  }
+  args.gitFilesCache?.delete(args.node.projectDir)
+  args.gitFilesCache?.invalidateWorkspacePartition()
+}
+
+/** The two bin directories a task's PATH starts with: its own, then the root's (once when they coincide). */
+export function taskBinDirs(node: TaskNode, workspaceRoot: string): string[] {
+  const bins = [path.join(node.projectDir, 'node_modules', '.bin')]
+  const rootBin = path.join(workspaceRoot, 'node_modules', '.bin')
+  // Identical when the root is itself a project — dedupe rather than list it
+  // twice, so PATH reads the same either way.
+  if (rootBin !== bins[0]) bins.push(rootBin)
+  return bins
+}
+
+/**
+ * Build the child-process env for one task. Same arguments at every call site
+ * (persistent + cached). Two `node_modules/.bin` directories are prepended to
+ * PATH: the project's own, then the WORKSPACE ROOT's. Never a sibling
+ * project's, and never an arbitrary ancestor — that is the project-isolation
+ * rule, and the root is not a sibling.
+ *
+ * The root entry is where a monorepo's shared tooling actually lives: declare
+ * `oxlint` once as a root devDependency and every member's `.bin` is empty of
+ * it. Without the root on PATH such a task exits 127, which is what this
+ * repo's own gate did the moment core stopped BEING the root and the two
+ * paths stopped coinciding. It also removes a divergence that mattered more:
+ * the REAPI executor already rebuilds both entries in the action's command,
+ * so a task that resolved on a worker failed on the machine that submitted
+ * it. npm/pnpm/yarn all put the ancestor chain on PATH for the same reason.
+ */
+export function taskEnv(
+  node: TaskNode,
+  step: ExecConfig,
+  workspaceRoot: string,
+): NodeJS.ProcessEnv {
+  const bins = taskBinDirs(node, workspaceRoot)
+  const env = buildIsolatedEnv({
+    passThrough: step.env?.passThrough ?? [],
+    define: step.env?.define ?? {},
+    source: process.env,
+    binPaths: bins,
+  })
+  env[VX_RUN_WORKSPACE_ENV] = workspaceRoot
+  env[VX_RUN_TASK_ENV] = node.id
+  // A task's own passThrough or define wins.
+  if (env[PM_EXEC_ENV] === undefined) {
+    const manager = packageManagerPath(workspaceRoot)
+    if (manager !== null) env[PM_EXEC_ENV] = manager
+  }
+  return env
+}
+
+/** A task's own `exec.timeout` in ms; the schema has checked its form. */
+export function taskTimeoutMs(step: ExecConfig): number | undefined {
+  return step.timeout === undefined ? undefined : parseDuration(step.timeout)!
+}
+
+export function isAborted(signal: AbortSignal | undefined): boolean {
+  return signal?.aborted === true
+}

package/src/orchestrator/telemetry-host.ts

@@ -11,7 +11,7 @@
 //
 // See docs/design/observability-architecture-2026-06.md §1, §3.
 
-import type { EventBus } from './events.js'
+import type { EventBus } from '../report/index.js'
 import type { TaskNode } from '../graph/index.js'
 import type {
   RunContextRecord,
@@ -27,8 +27,8 @@ import type { VxPlugin } from './plugin.js'
 export interface TelemetryHandle {
   /** Emit the per-run summary to every sink (crash-isolated). */
   emitSummary(summary: RunSummaryRecord): void
-  /** Await every sink's flush (crash-isolated, time-bounded by the sink). */
-  flush(): Promise<void>
+  /** Await every sink's flush (crash-isolated, time-bounded by the sink), each as a `<plugin>:telemetry` step. */
+  flush(step?: <T>(id: string, work: () => Promise<T>) => Promise<T>): Promise<void>
   /** Remove the bus subscription. Idempotent. */
   dispose(): void
   /** Sample a running task's process tree; see `TelemetrySource.track`. */
@@ -125,7 +125,7 @@ export async function subscribeTelemetry(
   const dispose = bus.subscribe(source.subscriber)
   return {
     emitSummary: (summary) => source.emitSummary(summary),
-    flush: () => source.flush(),
+    flush: (step) => source.flush(step),
     dispose,
     ...(source.track !== undefined ? { track: source.track } : {}),
   }

package/src/orchestrator/telemetry.ts

@@ -18,6 +18,9 @@
 
 import { sampleTrees } from '../exec/index.js'
 import {
+  type CacheSource,
+  deriveCacheSource,
+  isCacheHit,
   isGroupTask,
   type InputChanges,
   type TaskNode,
@@ -25,88 +28,10 @@ import {
   type TaskStatus,
 } from '../graph/index.js'
 import { maskedCommand, settleWithin, teardownTimeoutMs } from '../util/index.js'
-import type { RunEvent, RunEventSubscriber } from './events.js'
+import type { RunEvent, RunEventSubscriber } from '../report/index.js'
 
 /** Bumped when the record shape changes. Readers MUST check `v`. */
-export const TELEMETRY_SCHEMA_VERSION = 3
-
-/** 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;
- * `isCacheHit` below is derived from it rather than re-listing the two
- * hit statuses, so there is one decision, not two that can disagree.
- */
-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'
-  }
-}
-
-/**
- * Whether each status counts as a PASS. Written as a `Record<TaskStatus, …>`
- * rather than a `new Set([...])` on purpose: a Record must name every member,
- * so adding a status to the union is a COMPILE error HERE and the omission
- * cannot ship. A Set of string literals has no such tripwire — it silently
- * answers `false` for the new member, which is how ten hand-rolled copies of
- * this vocabulary accumulated across core, cloud and the dashboard.
- */
-const PASSES: Record<TaskStatus, boolean> = {
-  success: true,
-  'cache-hit': true,
-  'cache-hit-remote': true,
-  failed: false,
-  skipped: false,
-  aborted: false,
-}
-
-/**
- * Every `TaskStatus`, at runtime. Read off `PASSES`'s keys, which the
- * `Record<TaskStatus, …>` type guarantees is exactly the union — so this is
- * derived, not a second list that can fall behind. Exported so a consumer that
- * cannot import the type (a test asserting a copy of this vocabulary in
- * another package agrees) can still enumerate the real set.
- */
-export const TASK_STATUSES: readonly TaskStatus[] = Object.keys(PASSES) as TaskStatus[]
-
-/**
- * Did the task pass? A cache hit counts — it produced the same result without
- * spending the time, which is the whole point. `skipped` and `aborted` do NOT:
- * neither finished on its own terms, so neither can vouch for anything.
- *
- * Takes `string`, not `TaskStatus`, because most callers hold a status that
- * arrived over a wire or out of a database column. An unrecognised string
- * reads as NOT passing — the safe direction, since the alternative is calling
- * a run green on a status this build has never heard of.
- */
-export function isPassStatus(status: string): boolean {
-  return PASSES[status as TaskStatus] === true
-}
-
-/**
- * Did the task's result come out of the cache (either layer)? Derived from
- * `deriveCacheSource` rather than re-listing the two hit statuses, so the two
- * cannot disagree about what a hit is. Unknown strings read as not-a-hit.
- */
-export function isCacheHit(status: string): boolean {
-  // No known-status guard: an unknown string falls through the switch to
-  // undefined, which is neither hit source (the guard survived item 654).
-  const source = deriveCacheSource(status as TaskStatus)
-  return source === 'local' || source === 'remote'
-}
+export const TELEMETRY_SCHEMA_VERSION = 4
 
 /** Identifies which run a record belongs to + its captured context. Maps
  *  cleanly onto OTel CI/CD + VCS resource attributes. */
@@ -162,8 +87,6 @@ export interface RunContextRecord {
   host: string | null
   os: string
   arch: string
-  /** `--tag k=v` pairs. */
-  tags: Readonly<Record<string, string>>
 }
 
 /** One attempt of a retried task that failed and was run again. */
@@ -468,8 +391,11 @@ export interface TelemetrySource {
   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, all time-bounded). */
-  flush(): Promise<void>
+  /**
+   * Await every sink's `flush()` (each crash-isolated, all time-bounded),
+   * each as the step `<plugin>:telemetry` through `step`.
+   */
+  flush(step?: <T>(id: string, work: () => Promise<T>) => Promise<T>): Promise<void>
   /**
    * Sample this task's process tree every `SAMPLE_MS` until the returned
    * function is called, the root exits, or the run ends. Present only when
@@ -702,7 +628,7 @@ export function createTelemetrySource(args: {
         }
       }
     },
-    async flush(): Promise<void> {
+    async flush(step = <T>(_id: string, work: () => Promise<T>): Promise<T> => work()) {
       const ms = teardownTimeoutMs()
       // Bounded, for the same reason plugin teardown is bounded in
       // plugin-host.ts: run() awaits this BEFORE closeCache() and before it
@@ -718,7 +644,9 @@ export function createTelemetrySource(args: {
           sinks.map(async (sink) => {
             if (disabled.has(sink) || sink.flush === undefined) return
             try {
-              await sink.flush(deadline.signal)
+              await step(`${args.owners?.get(sink) ?? label(sink)}:telemetry`, () =>
+                sink.flush!(deadline.signal),
+              )
             } catch (err) {
               // A flush failure can never break the run — but it still costs
               // this sink its export, so say so rather than dropping it.

package/src/orchestrator/upstream.ts

@@ -1,14 +1,9 @@
 import {
-  DependencySpecError,
-  compileTaskPattern,
-  isGroupTask,
-  isTaskPattern,
-  parseDependencySpec,
-  type DependencySpec,
+  selectFoldedDeps,
+  type FoldCandidate,
   type TaskNode,
   type TaskOutcome,
 } from '../graph/index.js'
-import { UserError } from '../util/index.js'
 
 /**
  * A task's upstream as its KEY reads it: the live outcomes of its scheduled
@@ -36,15 +31,9 @@ export function keyedOutcome(node: TaskNode, hash: string | undefined): TaskOutc
   return o
 }
 
-/** `node.deps` less its ordering-only edges: the dependencies a key may fold. */
-export function keyedDeps(node: TaskNode): readonly string[] {
-  const order = node.orderOnly
-  return order === undefined ? node.deps : node.deps.filter((d) => !order.includes(d))
-}
-
 /**
  * Pick which upstream task hashes participate in the current task's
- * cache key, filtered by `cache.inputs.tasks`. The folded value is the
+ * cache key, filtered by `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
@@ -77,135 +66,6 @@ export function filterUpstreamHashes(
   ])
 }
 
-/**
- * A filter selects among the task's own dependencies, never through a
- * group: `dependsOn: ['build']` over a group `build` of `build.a` and
- * `build.b` offers the filter `build`, not its members. A pattern that
- * matches only a member (`build.*`) therefore selected nothing, and the key stopped moving
- * with that member's inputs: a stale hit under a green run. Such a spec
- * is refused, once, over the graph every key site reads. One that matches
- * nothing anywhere stays legal (a preset's pattern needn't match in every
- * project). An exact name is refused earlier, at load, unless `dependsOn`
- * names it (`assertFilterNamesDeclaredDeps`).
- */
-export function refuseFiltersThroughGroups(nodes: ReadonlyMap<string, TaskNode>): void {
-  for (const node of nodes.values()) {
-    const filter = node.config.cache?.inputs?.tasks
-    if (filter === undefined || filter.length === 0) continue
-    const deps = keyedDeps(node).flatMap((id) => nodes.get(id) ?? [])
-    const groups = deps.filter(isGroupTask)
-    if (groups.length === 0) continue
-    for (const raw of filter) {
-      const spec = parseSpec(raw, node.id)
-      if (spec.negated) continue
-      const matches = specMatcher(spec)
-      const hit = (n: TaskNode): boolean => matches(n, n.projectName === node.projectName)
-      if (deps.some(hit)) continue
-      for (const group of groups) {
-        const member = groupMembers(group, nodes).find(hit)
-        if (member === undefined) continue
-        throw new UserError(
-          `${node.id}: cache.inputs.tasks: '${raw}' matches ${member.id} only through the group ${group.id}, so it selects nothing; name '${group.taskName}' or depend on ${member.id} directly`,
-        )
-      }
-    }
-  }
-}
-
-function parseSpec(raw: string, selfTaskId: string): DependencySpec {
-  try {
-    return parseDependencySpec(raw)
-  } catch (err) {
-    if (err instanceof DependencySpecError) {
-      throw new UserError(`${selfTaskId}: cache.inputs.tasks: ${err.message}`)
-    }
-    throw err
-  }
-}
-
-/** Every task a group stands for, through nested groups, each once. */
-function groupMembers(group: TaskNode, nodes: ReadonlyMap<string, TaskNode>): TaskNode[] {
-  const out: TaskNode[] = []
-  const seen = new Set<string>([group.id])
-  const stack = group.deps.toReversed()
-  while (stack.length > 0) {
-    const id = stack.pop()!
-    if (seen.has(id)) continue
-    seen.add(id)
-    const n = nodes.get(id)
-    if (n === undefined) continue
-    out.push(n)
-    if (isGroupTask(n)) stack.push(...n.deps.toReversed())
-  }
-  return out
-}
-
-/**
- * One dependency as the key fold sees it: the task, and the value the
- * fold dedups by — its hash on the hash path, a structural stand-in for
- * the hash on the graph (`foldUnit` in keyed-projects.ts).
- */
-export interface FoldCandidate {
-  node: TaskNode
-  unit: string
-}
-
-/**
- * The dependencies a task's key folds, per its `cache.inputs.tasks`.
- *
- * 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
- *   'name.*'    patterns — EITHER half of any form above may contain `*`
- *               (same glob as dependsOn patterns), including the project
- *               half of `pkg#name`. A filter that matched literally here
- *               would silently select ZERO upstream hashes and decouple the
- *               task from its dependencies — a stale-hit trap, so every
- *               name is matched through the shared glob.
- *   '!<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` → every candidate, as given.
- *   - `filter === []`        → none (fully decoupled).
- *
- * Otherwise deduped by `unit`, first candidate kept. The unit is the
- * fold's own identity, not the task's: two groups over the same members
- * share one hash, so excluding either excludes both, and a selection by
- * task id would keep the other while the key folded neither.
- */
-export function selectFoldedDeps(
-  deps: readonly FoldCandidate[],
-  filter: readonly string[] | undefined,
-  selfProjectName: string,
-  selfTaskId: string,
-): FoldCandidate[] {
-  if (filter === undefined) return [...deps]
-
-  const specs: DependencySpec[] = filter.map((raw) => parseSpec(raw, selfTaskId))
-
-  // Per-spec predicate, compiled once (exact compares + patterns).
-  const matchers = specs.map((spec) => specMatcher(spec))
-
-  const selected = new Map<string, FoldCandidate>()
-  for (let i = 0; i < specs.length; i++) {
-    const spec = specs[i]!
-    const matches = matchers[i]!
-    for (const d of deps) {
-      const isSelf = d.node.projectName === selfProjectName
-      if (!matches(d.node, isSelf)) continue
-      if (spec.negated) selected.delete(d.unit)
-      else if (!selected.has(d.unit)) selected.set(d.unit, d)
-    }
-  }
-  return [...selected.values()]
-}
-
 /**
  * Expand any GROUP among these outcomes into the real tasks it stands for,
  * transitively, preserving order and de-duplicating by task id.
@@ -223,7 +83,7 @@ export function selectFoldedDeps(
  * along two paths (a group `build` whose `^build` meets a package diamond)
  * is expanded once, or the walk doubles per layer. Only what the FILTER
  * already selected is passed in, so a group excluded from a task's
- * `cache.inputs.tasks` brings no members with it.
+ * `inputs.tasks` brings no members with it.
  */
 export function expandGroupUpstream(upstream: readonly TaskOutcome[]): TaskOutcome[] {
   const out: TaskOutcome[] = []
@@ -245,40 +105,3 @@ export function expandGroupUpstream(upstream: readonly TaskOutcome[]): TaskOutco
   }
   return out
 }
-
-/** Exact-name compare, or the shared `*`-glob when the name is a pattern. */
-function nameMatcher(name: string): (candidate: string) => boolean {
-  if (isTaskPattern(name)) {
-    const re = compileTaskPattern(name)
-    return (candidate) => re.test(candidate)
-  }
-  return (candidate) => candidate === name
-}
-
-/**
- * Compile one spec into an upstream predicate. BOTH halves of a `pkg#task`
- * form glob: a filter only ever selects from upstreams that already exist,
- * so a package pattern is unambiguous here — unlike dependsOn, which must
- * materialize concrete edges and therefore rejects it.
- */
-function specMatcher(spec: DependencySpec): (n: TaskNode, isSelf: boolean) => boolean {
-  switch (spec.kind) {
-    case 'wildcardSelf':
-      return (_n, isSelf) => isSelf
-    case 'wildcardDeps':
-      return (_n, isSelf) => !isSelf
-    case 'self': {
-      const task = nameMatcher(spec.task)
-      return (n, isSelf) => isSelf && task(n.taskName)
-    }
-    case 'deps': {
-      const task = nameMatcher(spec.task)
-      return (n, isSelf) => !isSelf && task(n.taskName)
-    }
-    case 'cross': {
-      const project = nameMatcher(spec.project)
-      const task = nameMatcher(spec.task)
-      return (n) => project(n.projectName) && task(n.taskName)
-    }
-  }
-}

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

@@ -16,7 +16,7 @@ import type { RunContext } from './summary.js'
 /**
  * A task no cache answered for: it declares no `cache`, or the run's policy
  * read and wrote nothing. Its run is `no-cache`, never a miss, on every
- * surface — `--dry`'s plan, the frame, the footer, `--report`, `--summarize`.
+ * surface — `--dry`'s plan, the frame, the footer, the run history.
  */
 export function ranNoCache(o: { node: TaskNode; cacheOff?: boolean }): boolean {
   return o.node.config.cache === undefined || o.cacheOff === true
@@ -50,7 +50,12 @@ export type RunEvent =
   | { kind: 'task:stderr'; node: TaskNode; chunk: string }
   | { kind: 'task:complete'; node: TaskNode; outcome: TaskOutcome }
   | { kind: 'run:status'; line: string }
+  /** A warning, which the terminal prints on stderr. */
+  | { kind: 'run:status'; line: string; warn: true }
+  | { kind: 'step:start'; id: string }
+  | { kind: 'step:end'; id: string; durationMs: number; ok: boolean }
   | { kind: 'run:end' }
+  | { kind: 'run:done' }
 
 export type RunEventSubscriber = (event: RunEvent) => void
 
@@ -112,11 +117,13 @@ export function busLogger(bus: EventBus): Logger {
   // run() reaches runEnd on its success path, in its finally and from a
   // signal; a plugin's onRunEnd hears the first only.
   let ended = false
+  let done = false
   // A status line carries plugin warnings, and a remote layer's warning
   // quotes the server's reply, which may echo what it was sent (L-40).
   const secrets = secretMask([process.env])
   return {
     status: (line) => bus.emit({ kind: 'run:status', line: secrets?.mask(line) ?? line }),
+    warn: (line) => bus.emit({ kind: 'run:status', line: secrets?.mask(line) ?? line, warn: true }),
     taskStdout: (node, chunk) => bus.emit({ kind: 'task:stdout', node, chunk }),
     taskStderr: (node, chunk) => bus.emit({ kind: 'task:stderr', node, chunk }),
     taskComplete: (node, outcome) => bus.emit({ kind: 'task:complete', node, outcome }),
@@ -127,6 +134,13 @@ export function busLogger(bus: EventBus): Logger {
       ended = true
       bus.emit({ kind: 'run:end' })
     },
+    stepStart: (id) => bus.emit({ kind: 'step:start', id }),
+    stepEnd: (id, info) => bus.emit({ kind: 'step:end', id, ...info }),
+    runDone: () => {
+      if (done) return
+      done = true
+      bus.emit({ kind: 'run:done' })
+    },
   }
 }
 
@@ -156,11 +170,21 @@ export function terminalSubscriber(sink: Logger): RunEventSubscriber {
         sink.taskComplete(event.node, event.outcome)
         return
       case 'run:status':
-        sink.status(event.line)
+        if ('warn' in event && sink.warn !== undefined) sink.warn(event.line)
+        else sink.status(event.line)
+        return
+      case 'step:start':
+        sink.stepStart?.(event.id)
+        return
+      case 'step:end':
+        sink.stepEnd?.(event.id, { durationMs: event.durationMs, ok: event.ok })
         return
       case 'run:end':
         sink.runEnd?.()
         return
+      case 'run:done':
+        sink.runDone?.()
+        return
     }
   }
 }
@@ -234,9 +258,8 @@ export interface OutcomeView {
   durationMs: number
   /**
    * Group node (no `exec`) — organizational, not work. `TaskView` carries
-   * this too, but a consumer that only holds outcomes (the `--report`
-   * writer) has no node to ask, and counting groups as executed tasks is
-   * exactly how it drifted from the terminal and `--summarize`.
+   * this too, but a consumer that only holds outcomes has no node to ask,
+   * and counting groups as executed tasks drifts from the terminal.
    */
   isGroup?: boolean
   /** Executed with no `cache` block: never consulted the cache, not a miss. */
@@ -329,7 +352,7 @@ export function skippedReason(blockedBy: string | undefined): string {
 }
 
 /** `skipped (blocked by lib#build)`, or a bare `skipped` for fail-fast's. */
-export function skippedLabel(blockedBy: string | undefined): string {
+function skippedLabel(blockedBy: string | undefined): string {
   const why = skippedReason(blockedBy)
   return why === '' ? 'skipped' : `skipped (${why})`
 }
@@ -439,7 +462,12 @@ export type WireEvent =
   | { kind: 'task:stderr'; taskId: string; chunk: string }
   | { kind: 'task:complete'; outcome: OutcomeView }
   | { kind: 'run:status'; line: string }
+  /** A warning, which the terminal prints on stderr. */
+  | { kind: 'run:status'; line: string; warn: true }
+  | { kind: 'step:start'; id: string }
+  | { kind: 'step:end'; id: string; durationMs: number; ok: boolean }
   | { kind: 'run:end' }
+  | { kind: 'run:done' }
 
 /** Map an in-process event to its serializable wire form. */
 export function toWireEvent(event: RunEvent): WireEvent {
@@ -455,8 +483,13 @@ export function toWireEvent(event: RunEvent): WireEvent {
     case 'task:complete':
       return { kind: 'task:complete', outcome: projectOutcome(event.outcome) }
     case 'run:status':
-      return { kind: 'run:status', line: event.line }
+      return 'warn' in event
+        ? { kind: 'run:status', line: event.line, warn: true }
+        : { kind: 'run:status', line: event.line }
+    case 'step:start':
+    case 'step:end':
     case 'run:end':
-      return { kind: 'run:end' }
+    case 'run:done':
+      return event
   }
 }

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,
     }
   }
 }