@vzn/vx 0.0.16 → 0.0.18

package/src/orchestrator/missing-plugin.ts

@@ -0,0 +1,9 @@
+/** Shown by every "no <capability> plugin declared" error. */
+export const MISSING_PLUGIN_HINT = `vx runs nothing it was not told to. Declare the plugins in vx.workspace.ts:
+
+  import { defineWorkspace } from '@vzn/vx'
+  import { localExecutorPlugin } from '@vzn/vx/plugins/local-executor'
+  import { localCachePlugin } from '@vzn/vx/plugins/local-cache'
+  export default defineWorkspace({ plugins: [localExecutorPlugin(), localCachePlugin()] })
+
+Put a remote executor or cache plugin BEFORE the local one to prefer it.`

package/src/orchestrator/options.ts

@@ -46,11 +46,26 @@ export interface RunOptions {
   /**
    * Explicit per-task output volume for the default logger. ALWAYS
    * overrides the flow default. 'full': frames for work + one-liners
-   * for quiet hits. 'errors-only': only failed tasks print. 'none':
+   * for quiet hits. 'errors-only': only failed tasks print.
+   * 'hash-only': one line per task — outcome, id, cache key — with no
+   * log output (Turbo parity). 'none':
    * no per-task output at all. Status lines (header, summary) always
    * print.
    */
-  outputLogs?: 'full' | 'errors-only' | 'none'
+  outputLogs?: 'full' | 'errors-only' | 'none' | 'hash-only'
+  /**
+   * Where a REMOTELY-executed task's outputs land. 'all' (default):
+   * every task's outputs are downloaded to this machine as it completes
+   * — today's behaviour, byte for byte. 'toplevel': only the tasks you
+   * REQUESTED land here; intermediates stay remote. 'none': outputs stay
+   * in the remote CAS and are fetched lazily, only when a locally-placed
+   * task in the run actually needs them (Bazel's "build without the
+   * bytes").
+   * Pure transfer tuning: it can never change what a command produces,
+   * so it is NEVER folded into a cache key (a RunOption, like --verify).
+   * Locally-placed tasks always write in place and ignore this.
+   */
+  download?: 'all' | 'toplevel' | 'none'
   /**
    * Run intent, derived by the CLI from selection flags: 'broad' iff
    * `--all` / `--filter` / `--affected` was passed, else 'focused'.
@@ -143,8 +158,11 @@ export interface RunOptions {
   /**
    * Inject the run's event bus. When provided, the orchestrator emits
    * onto it instead of creating its own — letting a caller subscribe a
-   * surface (e.g. the `--ui` devframe dev server) BEFORE the run starts
-   * emitting. The terminal renderer is still attached as a subscriber, so
+   * surface BEFORE the run starts emitting. This IS the surface seam:
+   * core ships the bus and the serializable `WireEvent`, and whatever
+   * renders them lives outside. (It used to name a `--ui` devframe dev
+   * server; no such flag exists, and core's devframe adapter was removed
+   * on 2026-08-26 — one consumer's adapter is not core's job.) The terminal renderer is still attached as a subscriber, so
    * default output is unchanged. Default: a fresh internal bus.
    */
   bus?: EventBus

package/src/orchestrator/plan.ts

@@ -14,6 +14,7 @@
 import type { CacheLayer, CachePolicy, GitFilesCache } from '../cache/index.js'
 import { FULL_CACHE_POLICY } from '../cache/index.js'
 import { isGroupTask, runGraph, type TaskNode, type TaskOutcome } from '../graph/index.js'
+import type { HistoryProvider } from './history.js'
 import { computeGroupHash, computeTaskHash } from './task-hash.js'
 
 export type CacheStatus =
@@ -29,14 +30,67 @@ export interface PlannedTask {
   cacheStatus: CacheStatus
   /** Sorted task ids this task depends on (same as TaskNode.deps). */
   deps: readonly string[]
+  /**
+   * The task's typical executed duration (wall-clock p50 over its recent
+   * non-hit runs in the local cache.db), when history exists. Attached to
+   * every real task so a would-run task can show what it usually costs.
+   */
+  p50Ms?: number
+  /**
+   * Name of the executor this task would be PLACED on. Attached only when
+   * the workspace declares more than one executor — with a single one every
+   * line would carry the same label and say nothing. Absent for group tasks
+   * and persistent tasks, which never reach an executor.
+   */
+  executor?: string
+  /**
+   * `'deferred'` when this task's outputs would stay in the remote store
+   * (`--download=none` / `toplevel`). Attached only when it is TRUE — an
+   * eager task is the default and saying so on every line says nothing.
+   */
+  download?: 'deferred'
+}
+
+/**
+ * Time prediction over the plan: what would this run cost? Derived purely
+ * from recorded history (each task's p50) — cache hits and groups cost 0
+ * (a restore is a tar extract, near-instant next to execution).
+ */
+export interface PlanPrediction {
+  /** Predicted wall-clock: the longest dependency chain of would-run cost. */
+  wallMs: number
+  /** Total predicted execution across would-run tasks (the CPU-time story). */
+  workMs: number
+  /** Would-run tasks with NO history — their cost is unknown and counted as
+   *  0, so wallMs/workMs are lower bounds when this is > 0. */
+  unknownCount: number
 }
 
 export interface RunPlan {
   tasks: PlannedTask[]
+  /** Present when a history provider was available and usable. */
+  predicted?: PlanPrediction
+  /**
+   * Requested task specs that matched no project. Non-empty means the
+   * plan was abandoned: planning what WOULD run is meaningless when the
+   * equivalent `vx run` would refuse to start.
+   */
+  unresolvedTasks?: readonly string[]
+  /**
+   * Producers `--download` WANTED to defer but could not, mapped to why.
+   * Without this the gate is invisible: a user asks for `--download=none`,
+   * gets no deferral, and has nothing to read. Empty/absent under
+   * `--download=all`, which defers nothing by definition.
+   */
+  downloadDowngrades?: ReadonlyArray<{ taskId: string; reason: string }>
 }
 
 export interface PlanArgs {
   nodes: Map<string, TaskNode>
+  /** Per-task `--download` decision, when the policy is not `all`. */
+  downloadOf?: (id: string) => 'eager' | 'deferred' | 'never' | undefined
+  /** See `RunPlan.downloadDowngrades`. */
+  downloadDowngrades?: ReadonlyArray<{ taskId: string; reason: string }>
   workspaceRoot: string
   workspaceFingerprint: string
   cache: CacheLayer
@@ -45,6 +99,11 @@ export interface PlanArgs {
   nestedDirsByProject: Map<string, string[]>
   gitFilesCache?: GitFilesCache
   hashCache?: import('./task-hash.js').HashCache
+  /** When provided, per-task p50s are attached and `RunPlan.predicted` is
+   *  computed. Failing open: a history error yields a plan without them. */
+  history?: HistoryProvider
+  /** Placement lookup (`run.ts`), passed only when >1 executor is declared. */
+  executorOf?: (id: string) => string | undefined
 }
 
 /**
@@ -108,14 +167,98 @@ export async function plan(args: PlanArgs): Promise<RunPlan> {
     const o = outcomes.get(id)
     const node = args.nodes.get(id)
     if (!o || !node) continue
+    const executor = args.executorOf?.(id)
     tasks.push({
       node,
       hash: o.hash ?? '',
       cacheStatus: cacheStatusById.get(id) ?? 'no-cache',
       deps: node.deps,
+      ...(executor !== undefined ? { executor } : {}),
+      ...(args.downloadOf?.(id) === 'deferred' ? { download: 'deferred' as const } : {}),
     })
   }
-  return { tasks }
+
+  if (args.history !== undefined) {
+    try {
+      const realIds = tasks.filter((t) => t.cacheStatus !== 'group').map((t) => t.node.id)
+      const table = await args.history.loadFor(realIds)
+      for (const t of tasks) {
+        const p50 = table.get(t.node.id)?.p50DurationMs
+        if (p50 !== undefined) t.p50Ms = p50
+      }
+      return { tasks, predicted: predictPlan(tasks), ...downgradeField(args) }
+    } catch {
+      // Failing open: prediction is a nicety — a broken history read must
+      // never break `--dry`.
+    }
+  }
+  return { tasks, ...downgradeField(args) }
+}
+
+/** Carried onto the plan only when the gate actually refused something. */
+function downgradeField(args: PlanArgs): {
+  downloadDowngrades?: ReadonlyArray<{ taskId: string; reason: string }>
+} {
+  const d = args.downloadDowngrades
+  return d !== undefined && d.length > 0 ? { downloadDowngrades: d } : {}
+}
+
+/** A task the plan expects to EXECUTE (a no-cache task executes every run). */
+function wouldRun(t: PlannedTask): boolean {
+  return t.cacheStatus === 'miss' || t.cacheStatus === 'no-cache'
+}
+
+/**
+ * Longest dependency chain of predicted cost, via one pass over a Kahn
+ * topological order — no recursion, so a pathologically deep chain can't
+ * overflow the stack. Hits + groups cost 0; a would-run task with no
+ * history also costs 0 (counted in `unknownCount`, making the totals
+ * honest lower bounds).
+ */
+function predictPlan(tasks: PlannedTask[]): PlanPrediction {
+  const cost = (t: PlannedTask): number => (wouldRun(t) ? (t.p50Ms ?? 0) : 0)
+  const byId = new Map(tasks.map((t) => [t.node.id, t]))
+  const dependents = new Map<string, string[]>()
+  const indeg = new Map<string, number>()
+  for (const t of tasks) {
+    const deps = t.deps.filter((d) => byId.has(d))
+    indeg.set(t.node.id, deps.length)
+    for (const d of deps) {
+      const list = dependents.get(d)
+      if (list) list.push(t.node.id)
+      else dependents.set(d, [t.node.id])
+    }
+  }
+  const dist = new Map<string, number>()
+  const queue: string[] = []
+  for (const [id, n] of indeg) if (n === 0) queue.push(id)
+  let head = 0
+  let wallMs = 0
+  while (head < queue.length) {
+    const id = queue[head++]!
+    const t = byId.get(id)!
+    let best = 0
+    for (const d of t.deps) {
+      const v = dist.get(d)
+      if (v !== undefined && v > best) best = v
+    }
+    const v = best + cost(t)
+    dist.set(id, v)
+    if (v > wallMs) wallMs = v
+    for (const dep of dependents.get(id) ?? []) {
+      const n = indeg.get(dep)! - 1
+      indeg.set(dep, n)
+      if (n === 0) queue.push(dep)
+    }
+  }
+  let workMs = 0
+  let unknownCount = 0
+  for (const t of tasks) {
+    if (!wouldRun(t)) continue
+    if (t.p50Ms === undefined) unknownCount++
+    else workMs += t.p50Ms
+  }
+  return { wallMs, workMs, unknownCount }
 }
 
 function planOutcome(node: TaskNode, hash: string): TaskOutcome {

package/src/orchestrator/plugin-host.ts

@@ -1,28 +1,32 @@
-// Plugin consultation for the three run-level extension points
-// (backend / cache / eventSink). Each function asks the declared plugins
-// in order and falls back to today's exact default, so a workspace with
-// no capability plugin is byte-identical to before the inversion.
+// Plugin consultation for the run-level extension points (cache / executor).
+// Each function asks the plugins in order. Nothing is applied by default:
+// core's own executor and cache are plugins under src/plugins/ that a
+// workspace declares like any other, so a list with no provider for a
+// load-bearing capability fails fast with MISSING_PLUGIN_HINT.
 //
 // See docs/design/core-cloud-split-2026-06.md §5.1.
 
-import type { Cache, CacheLayer } from '../cache/index.js'
-import { UserError } from '../util/index.js'
-import type { EventBus } from './events.js'
-import { wireForwarder } from './events.js'
-import type { Logger } from './logger.js'
+import { ChainedCache, type CacheLayer } from '../cache/index.js'
+import type { TaskExecutor } from '../exec/index.js'
+import { settleWithin, teardownTimeoutMs, UserError } from '../util/index.js'
+import type { ProjectConfig, WorkspaceConfig } from '../config.js'
+import { detectCycle, type TaskNode } from '../graph/index.js'
+import { MISSING_PLUGIN_HINT } from './missing-plugin.js'
 import type {
-  BackendContext,
   CacheContext,
-  EventSink,
-  EventSinkContext,
+  ExecutorContext,
+  GraphHookContext,
+  KeyHookContext,
+  ProjectHookContext,
+  ScheduleHookContext,
   VxPlugin,
+  WorkspaceHookContext,
 } from './plugin.js'
-import type { RunBackend } from './protocol.js'
 
 /**
  * Run a capability factory with crash isolation. A throw becomes a clean
  * `UserError` naming the plugin + hook for the load-bearing capabilities
- * (`backend`/`cache`/`setup`) — a broken backend or cache must abort with
+ * (`cache`/`executor`/`setup`) — a broken cache or executor must abort with
  * a clear message, never silently degrade. For `eventSink` the caller
  * logs-and-skips instead (observability must never break a run).
  */
@@ -36,146 +40,222 @@ async function safe<T>(plugin: VxPlugin, hook: string, fn: () => T | Promise<T>)
   }
 }
 
-/**
- * Resolve the run backend. First plugin returning a non-undefined
- * `backend` wins (declaration order); otherwise the caller's `fallback`
- * (today's local/serve env-probe). A broken backend factory aborts.
- */
-export async function resolveBackend(
+// --- Pipeline stages ---------------------------------------------------------
+//
+// Each stage hands plugins the object core is about to use, in declaration
+// order, and the caller re-validates afterwards. `hasHook` is the zero-cost
+// gate: with no plugin declaring a stage the caller skips the loop AND the
+// re-validation, so a workspace without pipeline plugins pays nothing.
+
+export function hasHook(
+  plugins: readonly VxPlugin[],
+  hook: 'config' | 'project' | 'graph' | 'key' | 'schedule',
+): boolean {
+  for (const p of plugins) if (p[hook] !== undefined) return true
+  return false
+}
+
+/** `config` stage: every plugin edits the workspace config in place. */
+export async function applyConfigHooks(
+  plugins: readonly VxPlugin[],
+  workspace: WorkspaceConfig,
+  ctx: WorkspaceHookContext,
+): Promise<void> {
+  for (const plugin of plugins) {
+    if (plugin.config === undefined) continue
+    await safe(plugin, 'config', () => plugin.config!(workspace, ctx))
+  }
+}
+
+/** `project` stage: every plugin edits one project's config in place. */
+export async function applyProjectHooks(
   plugins: readonly VxPlugin[],
-  ctx: BackendContext,
-  fallback: () => Promise<RunBackend>,
-): Promise<RunBackend> {
+  config: ProjectConfig,
+  ctx: ProjectHookContext,
+): Promise<void> {
   for (const plugin of plugins) {
-    if (plugin.backend === undefined) continue
-    const backend = await safe(plugin, 'backend', () => plugin.backend!(ctx))
-    if (backend !== undefined) return backend
+    if (plugin.project === undefined) continue
+    await safe(plugin, 'project', () => plugin.project!(config, ctx))
   }
-  return await fallback()
 }
 
 /**
- * Resolve the cache layer. First plugin returning a non-undefined `cache`
- * wins; otherwise the caller's `fallback` (the plain local cache — core
- * ships no wire client; a remote layer comes from a plugin or from
- * `RunOptions.remoteCache`). A broken cache factory aborts.
+ * `graph` stage: every plugin edits the task graph in place, then the graph
+ * is checked the way the builder checks its own output — every dep names a
+ * node in the graph, and there is no cycle. A violation is reported against
+ * the LAST plugin that ran, which is the one whose edit made it so.
  */
-export async function resolveCache(
+export async function applyGraphHooks(
   plugins: readonly VxPlugin[],
-  _localCache: Cache,
-  ctx: CacheContext,
-  _log: Logger,
-  fallback: () => CacheLayer,
-): Promise<CacheLayer> {
+  nodes: Map<string, TaskNode>,
+  ctx: GraphHookContext,
+): Promise<void> {
+  let last: VxPlugin | undefined
   for (const plugin of plugins) {
-    if (plugin.cache === undefined) continue
-    const cache = await safe(plugin, 'cache', () => plugin.cache!(ctx))
-    if (cache !== undefined) return cache
+    if (plugin.graph === undefined) continue
+    await safe(plugin, 'graph', () => plugin.graph!(nodes, ctx))
+    last = plugin
   }
-  return fallback()
+  if (last === undefined) return
+  await safe(last, 'graph', () => {
+    for (const node of nodes.values()) {
+      for (const dep of node.deps) {
+        if (!nodes.has(dep)) {
+          throw new Error(`${node.id} depends on '${dep}', which is not a task in this run's graph`)
+        }
+      }
+    }
+    detectCycle(nodes)
+  })
 }
 
-export interface SubscribedEventSinks {
-  /** Removes every bus subscription. Called in run()'s finally. */
-  dispose(): void
-  /** The installed sinks (with the owning plugin's name for warnings),
-   *  so run() can await each sink's `flush()` at end-of-run. */
-  sinks: ReadonlyArray<{ pluginName: string; sink: EventSink }>
+/**
+ * `key` stage: every plugin may add `{ name: value }` material to every
+ * task. Stored on the node as sorted `[plugin/name, value]` pairs so the
+ * fold is order-independent and `vx why` can name the contributor.
+ */
+export async function applyKeyHooks(
+  plugins: readonly VxPlugin[],
+  nodes: Map<string, TaskNode>,
+  ctx: KeyHookContext,
+): Promise<void> {
+  for (const node of nodes.values()) {
+    const parts: Array<readonly [string, string]> = []
+    for (const plugin of plugins) {
+      if (plugin.key === undefined) continue
+      const material = await safe(plugin, 'key', () => plugin.key!(node, ctx))
+      if (material === undefined) continue
+      for (const [name, value] of Object.entries(material)) {
+        if (typeof value !== 'string') {
+          throw new UserError(
+            `plugin '${plugin.name}' failed in key: value for '${name}' on ${node.id} is not a string`,
+          )
+        }
+        parts.push([`${plugin.name}/${name}`, value])
+      }
+    }
+    if (parts.length > 0) {
+      parts.sort((a, b) => (a[0] < b[0] ? -1 : a[0] > b[0] ? 1 : 0))
+      node.keyParts = parts
+    }
+  }
 }
 
 /**
- * Subscribe every plugin's `eventSink` to the bus via `wireForwarder`,
- * each isolated so a throwing sink can never break the run. Additive: with
- * no eventSink plugin nothing subscribes and behavior is unchanged.
- * Returns the disposer plus the installed sinks (for the end-of-run flush).
+ * `schedule` stage: the merged priorities map (a later plugin's weight for
+ * a task overrides an earlier one's). Empty when no plugin answered.
  */
-export async function subscribeEventSinks(
+export async function applyScheduleHooks(
   plugins: readonly VxPlugin[],
-  bus: EventBus,
-  ctx: EventSinkContext,
-): Promise<SubscribedEventSinks> {
-  const disposers: Array<() => void> = []
-  const sinks: Array<{ pluginName: string; sink: EventSink }> = []
+  nodes: ReadonlyMap<string, TaskNode>,
+  ctx: ScheduleHookContext,
+): Promise<ReadonlyMap<string, number>> {
+  const merged = new Map<string, number>()
   for (const plugin of plugins) {
-    if (plugin.eventSink === undefined) continue
-    let sink
-    try {
-      sink = await plugin.eventSink(ctx)
-    } catch (err) {
-      ctx.warn(
-        `[vx] plugin '${plugin.name}' eventSink failed to initialize; disabled for this run: ${err instanceof Error ? err.message : String(err)}`,
-      )
-      continue
+    if (plugin.schedule === undefined) continue
+    const weights = await safe(plugin, 'schedule', () => plugin.schedule!(nodes, ctx))
+    if (weights === undefined) continue
+    for (const [id, w] of weights) {
+      if (!nodes.has(id)) continue
+      if (typeof w !== 'number' || !Number.isFinite(w)) {
+        throw new UserError(
+          `plugin '${plugin.name}' failed in schedule: weight for ${id} is not a finite number`,
+        )
+      }
+      merged.set(id, w)
     }
-    if (sink === undefined) continue
-    sinks.push({ pluginName: plugin.name, sink })
-    disposers.push(
-      bus.subscribe(
-        wireForwarder((event) => {
-          try {
-            sink.onEvent(event)
-          } catch {
-            // observability is isolated — a sink fault can't break the run
-          }
-        }),
-      ),
-    )
-  }
-  return {
-    dispose: () => {
-      for (const dispose of disposers) dispose()
-    },
-    sinks,
   }
+  return merged
 }
 
-/** Upper bound on each teardown()/flush() await — a wedged plugin must
- *  not hold the run's exit hostage. */
-const TEARDOWN_TIMEOUT_MS = 3000
+/**
+ * Collect every plugin's `cache` layer in declaration order. One layer is
+ * used as is; two or more are chained (lookup walks them, save reaches all;
+ * see ChainedCache). A bare local layer that another declared layer already
+ * wraps (`layer.local === ctx.localCache`) is dropped, so a remote plugin
+ * that layers over the local handle composes with `localCachePlugin()`
+ * instead of writing the local store twice. No layer at all is a named error.
+ */
+export async function resolveCache(
+  plugins: readonly VxPlugin[],
+  ctx: CacheContext,
+): Promise<CacheLayer> {
+  const layers: CacheLayer[] = []
+  for (const plugin of plugins) {
+    if (plugin.cache === undefined) continue
+    const layer = await safe(plugin, 'cache', () => plugin.cache!(ctx))
+    if (layer !== undefined) layers.push(layer)
+  }
+  if (layers.length === 0) {
+    const declined = plugins.filter((p) => p.cache !== undefined).map((p) => `${p.name} declined`)
+    throw new UserError(
+      `no cache plugin declared${declined.length > 0 ? ` (${declined.join(', ')})` : ''}. ${MISSING_PLUGIN_HINT}`,
+    )
+  }
+  const wrapsLocal = layers.some((l) => l !== ctx.localCache && l.local === ctx.localCache)
+  const distinct = wrapsLocal ? layers.filter((l) => l !== ctx.localCache) : layers
+  return distinct.length === 1 ? distinct[0]! : new ChainedCache(distinct)
+}
 
-async function settleWithin(p: Promise<unknown>, ms: number): Promise<void> {
-  let timer: ReturnType<typeof setTimeout> | undefined
-  const deadline = new Promise<void>((resolve) => {
-    timer = setTimeout(resolve, ms)
-  })
-  try {
-    await Promise.race([p, deadline])
-  } finally {
-    clearTimeout(timer)
-    // A rejection landing after the deadline won already resolved the
-    // race must not surface as an unhandled-rejection crash.
-    void p.catch(() => {})
+/**
+ * Collect every plugin's `executor`, in declaration order. Unlike
+ * `cache` this is a LIST: per task, `selectExecutor` takes the first
+ * that accepts. An empty list is the same authoring error as a missing
+ * cache provider and fails the same way. A broken factory aborts — an
+ * executor is load-bearing, not observational.
+ */
+export async function resolveExecutors(
+  plugins: readonly VxPlugin[],
+  ctx: ExecutorContext,
+): Promise<TaskExecutor[]> {
+  const executors: TaskExecutor[] = []
+  for (const plugin of plugins) {
+    if (plugin.executor === undefined) continue
+    const executor = await safe(plugin, 'executor', () => plugin.executor!(ctx))
+    if (executor !== undefined) executors.push(executor)
   }
+  if (executors.length === 0) {
+    const declined = plugins
+      .filter((p) => p.executor !== undefined)
+      .map((p) => `${p.name} declined`)
+    throw new UserError(
+      `no executor plugin declared${declined.length > 0 ? ` (${declined.join(', ')})` : ''}. ${MISSING_PLUGIN_HINT}`,
+    )
+  }
+  return executors
 }
 
 /**
- * End-of-run plugin lifecycle: await each event sink's optional
- * `flush()` (its last chance to ship buffered records), then each
- * plugin's optional `teardown()`. Crash-isolated — a throwing
- * flush/teardown is logged and skipped, never propagated — and each
- * call is time-bounded at {@link TEARDOWN_TIMEOUT_MS}. Runs on the
- * normal completion path only; the finally-path disposers just
- * unsubscribe.
+ * End-of-run plugin lifecycle: each plugin's optional `teardown()`, in
+ * declaration order. Crash-isolated — a throwing teardown is logged and
+ * skipped, never propagated — and each call is time-bounded by
+ * {@link teardownTimeoutMs}. Runs on the normal completion path only; the
+ * finally-path disposers just unsubscribe. (Telemetry sinks flush before
+ * this, in telemetry-host.ts, with the same reporting rule.)
+ *
+ * The bound is PER CALL and the calls are sequential, so the worst case
+ * composes: measured at the 3s default, 1/2/3 simultaneously-hung plugins
+ * cost 3.0/6.0/9.0s. That is deliberate rather than overlooked — the
+ * telemetry sibling races its sinks concurrently, but a plugin's teardown
+ * may release something a later one still holds, and declaration order is
+ * the contract this file keeps elsewhere. Each hung call names itself, so
+ * the delay is attributable instead of mysterious.
  */
 export async function teardownPlugins(
   plugins: readonly VxPlugin[],
-  sinks: ReadonlyArray<{ pluginName: string; sink: EventSink }>,
   warn: (message: string) => void,
 ): Promise<void> {
-  for (const { pluginName, sink } of sinks) {
-    if (sink.flush === undefined) continue
-    try {
-      await settleWithin(Promise.resolve(sink.flush()), TEARDOWN_TIMEOUT_MS)
-    } catch (err) {
-      warn(
-        `[vx] plugin '${pluginName}' event sink flush failed: ${err instanceof Error ? err.message : String(err)}`,
-      )
-    }
-  }
   for (const plugin of plugins) {
     if (plugin.teardown === undefined) continue
+    const ms = teardownTimeoutMs()
     try {
-      await settleWithin(Promise.resolve(plugin.teardown()), TEARDOWN_TIMEOUT_MS)
+      const settled = await settleWithin(Promise.resolve(plugin.teardown()), ms)
+      // Same rule as the flush above. A teardown that never settles has left
+      // whatever it owns un-released, and the run exits anyway — silence would
+      // present that as a clean shutdown.
+      if (!settled) {
+        warn(`[vx] plugin '${plugin.name}' teardown timed out after ${ms}ms; it did not complete`)
+      }
     } catch (err) {
       warn(
         `[vx] plugin '${plugin.name}' teardown failed: ${err instanceof Error ? err.message : String(err)}`,