@vzn/vx 0.0.638 → 0.0.640

package/src/orchestrator/persistent.ts

@@ -3,10 +3,11 @@
 // ownership moves to the run's registry, and this is the one place that
 // decides which of them outlive the graph and how the rest go down.
 
-import { isGroupTask, type TaskNode } from '../graph/index.js'
+import { isGroupTask, isPassStatus, type TaskNode, type TaskOutcome } from '../graph/index.js'
 import { killGraceMs } from '../util/index.js'
-import { holdGroups, killTree, untilGroupsGone } from '../exec/index.js'
-import type { HeldServer } from './options.js'
+import { holdGroups, killTree, signalExitCode, untilGroupsGone } from '../exec/index.js'
+import type { HeldPersistent, HeldServer } from './options.js'
+import { terminateChildren } from './signals.js'
 
 type Child = ReturnType<typeof Bun.spawn>
 
@@ -152,3 +153,129 @@ export function takeHeldServers(
   }
   return { kept, stale }
 }
+
+/**
+ * The kept server whose exit ends a foreground session, and its code. A
+ * server kept only as a dependency that exits 0 is a daemon that forked
+ * and returned (schema.md), not the end of the session: a
+ * `db: 'docker compose up -d'` under `app#dev` stopped the dev server
+ * right after the summary (WD-3). It ends the wait only as the last.
+ */
+export function sessionEnd(keepAlive: KeepAlive): Promise<{ code: number; i: number }> {
+  return new Promise((resolve) => {
+    let left = keepAlive.children.length
+    keepAlive.children.forEach((c, i) => {
+      void c.exited.then((code) => {
+        left--
+        const n = keepAlive.nodes[i]!
+        if (code !== 0 || n.requested || n.surfaced === true || left === 0) resolve({ code, i })
+      })
+    })
+  })
+}
+
+export interface HoldArgs {
+  forwardArgs: readonly string[] | undefined
+  /** Where a held server's output goes. */
+  outOf: (id: string) => HeldServer['out']
+  warn: (message: string) => void
+}
+
+/** The kept servers handed to the caller (`RunOptions.hold`) instead of waited on. */
+export function holdServers(keepAlive: KeepAlive, args: HoldArgs): HeldPersistent {
+  const held = keepAlive.children
+  // A held server that dies on its own is said, as the foreground's
+  // keep-alive says it: `vx watch` sat on "watching" over a dead dev
+  // server. The holder's own stop() is not such a death.
+  let stopping = false
+  // Taken by a later run (`RunOptions.keep`): kept or stopped there.
+  const handed = new Set<Child>()
+  const servers = new Map<string, HeldServer>()
+  keepAlive.nodes.forEach((n, i) => {
+    const child = held[i]!
+    servers.set(n.id, {
+      child,
+      config: serverConfig(n, args.forwardArgs),
+      out: args.outOf(n.id),
+      handOver: () => void handed.add(child),
+    })
+    // One that died during the graph was said then.
+    if (hasEnded(child)) return
+    void child.exited.then((code) => {
+      if (!stopping && !handed.has(child) && code !== 0)
+        args.warn(`vx: ${n.id} exited with code ${code}`)
+    })
+  })
+  return {
+    ids: keepAlive.nodes.map((n) => n.id),
+    servers,
+    stop: (signal) => {
+      stopping = true
+      return terminateChildren(() => held.filter((c) => !handed.has(c)), signal)
+    },
+  }
+}
+
+/**
+ * A server that died on its own before the stop failed, whatever its
+ * outcome said when it became ready: the footer counted it a success over
+ * the run's red exit (item 1071). Its code is its own, or the shell's
+ * report of the signal that took it. In place: the renderer holds this
+ * outcome (events carry live refs) and closes the server's output block
+ * from it at runEnd, where a copy left it reading `running` under its exit
+ * line (WD-10).
+ */
+export function failServer(
+  outcomes: ReadonlyMap<string, TaskOutcome>,
+  id: string,
+  code: number | string,
+): void {
+  const o = outcomes.get(id)
+  if (o === undefined) return
+  o.status = 'failed'
+  o.exitCode = typeof code === 'number' ? code : signalExitCode(code)
+}
+
+/**
+ * The end of the graph for its servers: which stay up (`selectKeepAlive`),
+ * the bounded shutdown of the rest, and each one that died on its own
+ * failed. A run that failed elsewhere keeps nothing: `vx run dev --all`
+ * with one server that never became ready sat on the others for good, so
+ * a script hung, and the Ctrl-C that ended it read 130 over the failure
+ * (C-60). A kept server's own crash ends the keep-alive wait as before,
+ * and `--continue=always` asked to keep going, and does. The watch loop
+ * (`hold`) still holds: a failing test in a cycle stopped the dev server
+ * the next change would restart anyway. A kept server that has already
+ * died fails too; the keep-alive wait names it.
+ */
+export async function disposeServers(args: {
+  registry: ReadonlyMap<string, Child>
+  nodes: ReadonlyMap<string, TaskNode>
+  outcomes: ReadonlyMap<string, TaskOutcome>
+  /** Keep the requested servers up: the CLI foreground, or a hold. */
+  keep: boolean
+  hold: boolean
+  continueAlways: boolean
+  /** The servers that had ended when a stop landed; undefined without a stop. */
+  endedBeforeStop: ReadonlySet<Child> | undefined
+}): Promise<{ keepAlive: KeepAlive; crashed: CrashedPersistent[] }> {
+  const { registry, outcomes, endedBeforeStop } = args
+  let keepAlive = selectKeepAlive(registry, args.nodes, args.keep)
+  const failedElsewhere =
+    ![...outcomes.values()].every((o) => isPassStatus(o.status)) ||
+    [...registry.values()].some(
+      (c) => hasEnded(c) && c.exitCode !== 0 && !keepAlive.children.includes(c),
+    )
+  if (failedElsewhere && !args.hold && !args.continueAlways) keepAlive = { nodes: [], children: [] }
+  const crashed = (await shutdownPersistent(registry, keepAlive.children)).filter(
+    (c) => endedBeforeStop?.has(registry.get(c.id)!) ?? true,
+  )
+  for (const c of crashed) failServer(outcomes, c.id, c.code)
+  keepAlive.nodes.forEach((n, i) => {
+    const child = keepAlive.children[i]!
+    if (!hasEnded(child) || child.exitCode === 0) return
+    if (endedBeforeStop !== undefined && !endedBeforeStop.has(child)) return
+    failServer(outcomes, n.id, child.exitCode ?? child.signalCode ?? 'unknown')
+  })
+  return { keepAlive, crashed }
+}

package/src/orchestrator/placement.ts

@@ -11,7 +11,7 @@ import { machineParallelism, UserError } from '../util/index.js'
 import { isLocalExecutor, selectExecutor, type TaskExecutor } from '../exec/index.js'
 import { isGroupTask, type TaskNode } from '../graph/index.js'
 import { resolveDownloadModes } from './download-policy.js'
-import type { Logger } from './logger.js'
+import { type Logger, warnOf } from '../report/index.js'
 import { executorLabel, resolveExecutors } from './plugin-host.js'
 import type { prepareRun } from './prepare.js'
 
@@ -59,7 +59,7 @@ export function pinnedLocalSet(nodes: Map<string, TaskNode>): Set<string> {
 }
 
 /**
- * A key that folds `cache.inputs.runtime` / `workspaceRuntime` holds what
+ * A key that folds `inputs.runtime` / `workspaceRuntime` holds what
  * THIS machine answered (`node -v`); a worker runs its own runtime, which no
  * executor can prove equal, and its output saved under this key is a stale
  * hit here (C-2). Such a task runs here. Its dependants are not pinned with
@@ -68,7 +68,7 @@ export function pinnedLocalSet(nodes: Map<string, TaskNode>): Set<string> {
  */
 function withProbedRuntime(nodes: Map<string, TaskNode>, pinned: Set<string>): Set<string> {
   for (const node of nodes.values()) {
-    const inputs = node.config.cache?.inputs
+    const inputs = node.config.inputs
     if ((inputs?.runtime?.length ?? 0) > 0 || (inputs?.workspaceRuntime?.length ?? 0) > 0) {
       pinned.add(node.id)
     }
@@ -218,11 +218,11 @@ export async function planExecutorOf(
     executors = await resolveExecutors(prepared.plugins, {
       workspaceRoot: prepared.workspaceRoot,
       cacheDir: prepared.cacheDir,
-      warn: (m: string) => log.status(m),
+      warn: warnOf(log),
       concurrency: machineParallelism(),
     })
   } catch (err) {
-    log.status(
+    warnOf(log)(
       `[vx] placement not shown — ${err instanceof Error ? err.message : String(err)} (the run would refuse on it)`,
     )
     return {}

package/src/orchestrator/plan.ts

@@ -1,22 +1,22 @@
 // Planning: walk the task graph, compute every task's cache key, and
 // probe the cache to predict what would happen if `vx run` actually
-// ran. Used by `--dry-run` (preview output) and `--graph` (DOT export).
+// ran. Used by `--dry`.
 //
 // No TASK execution happens: no task spawn, no cleanOutputs, no
 // restoreOutputs. Cache probing uses the byte-free `cache.has()`
 // existence probe (a remote layer answers it its own way — no
 // artifact download, no local ingest), so the plan is read-only — with
-// one deliberate exception: `cache.inputs.runtime` / `workspaceRuntime`
+// one deliberate exception: `inputs.runtime` / `workspaceRuntime`
 // probe commands DO run, because predicting a task's key requires
 // resolving them (same as a real run). Keep runtime inputs
 // side-effect-free pure probes.
 
 import type { CacheLayer, CachePolicy, GitFilesCache } from '../cache/index.js'
 import { cachesNothing, FULL_CACHE_POLICY } from '../cache/index.js'
-import { ranNoCache } from './events.js'
+import { ranNoCache } from '../report/index.js'
 import { idleServers, isGroupTask, runGraph, type TaskNode } from '../graph/index.js'
 import type { AffectedReason } from './affected-tasks.js'
-import type { HistoryProvider } from './history.js'
+import type { HistoryProvider } from '../history/index.js'
 import { computeGroupKey, computeTaskHash } from './task-hash.js'
 import { keyedOutcome, keyUpstream } from './upstream.js'
 
@@ -139,6 +139,9 @@ export interface PlanArgs {
  */
 export async function plan(args: PlanArgs): Promise<RunPlan> {
   const cacheStatusById = new Map<string, CacheStatus>()
+  // Keyed first, probed after: a remote that can batch (`hasMany`) is
+  // asked once for every key, one that cannot is asked per key.
+  const probed = new Map<string, string>()
 
   const outcomes = await runGraph({
     nodes: args.nodes,
@@ -176,13 +179,23 @@ export async function plan(args: PlanArgs): Promise<RunPlan> {
       } else if (!reads) {
         status = 'miss'
       } else {
-        const where = await args.cache.has(hash)
-        status = where === null ? 'miss' : where === 'remote' ? 'hit-remote' : 'hit-local'
+        probed.set(node.id, hash)
+        return keyedOutcome(node, hash)
       }
       cacheStatusById.set(node.id, status)
       return keyedOutcome(node, hash)
     },
   })
+  if (probed.size > 0) {
+    await args.cache.remoteHasMany?.([...new Set(probed.values())])
+    for (const [id, hash] of probed) {
+      const where = await args.cache.has(hash)
+      cacheStatusById.set(
+        id,
+        where === null ? 'miss' : where === 'remote' ? 'hit-remote' : 'hit-local',
+      )
+    }
+  }
 
   if (args.restorable !== undefined) {
     const restoreTier = new Set(

package/src/orchestrator/plugin-host.ts

@@ -10,13 +10,12 @@
 import path from 'node:path'
 import {
   type Cache,
-  ChainedCache,
   type CacheLayer,
   type CachePolicy,
   LayeredCache,
   absentPluginCache,
   type PluginCache,
-  type PluginCacheRemote,
+  type ResolvedRemote,
 } from '../cache/index.js'
 import { localExecutor, type TaskExecutor } from '../exec/index.js'
 import { maskedLine, settleWithin, teardownTimeoutMs, UserError } from '../util/index.js'
@@ -382,41 +381,81 @@ export async function claimedAffected(
   return names
 }
 
+/** What a run hands the `schedule` stage: a step per plugin, and where refined weights go. */
+export interface ScheduleRun {
+  readonly step?: <T>(id: string, work: () => Promise<T>) => Promise<T>
+  readonly refined?: (merged: ReadonlyMap<string, number>) => void
+}
+
 /**
  * `schedule` stage: the merged priorities map (a later plugin's weight for
- * a task overrides an earlier one's). Empty when no plugin answered.
+ * a task overrides an earlier one's). Empty when no plugin answered. Each
+ * plugin's call is the step `<plugin>:schedule`. A plugin's `ctx.refine`
+ * replaces its own weights and hands `refined` the merge again; with no
+ * `refined` (a plan), it is ignored.
  */
 export async function applyScheduleHooks(
   plugins: readonly VxPlugin[],
   nodes: ReadonlyMap<string, TaskNode>,
-  ctx: Omit<ScheduleHookContext, 'cache'>,
+  ctx: Omit<ScheduleHookContext, 'cache' | 'refine'>,
   cacheFor: (plugin: string) => PluginCache = () => absentPluginCache,
+  run: ScheduleRun = {},
 ): Promise<ReadonlyMap<string, number>> {
-  const merged = new Map<string, number>()
-  for (const plugin of plugins) {
+  const sets: (ReadonlyMap<string, number> | undefined)[] = []
+  const merged = (): ReadonlyMap<string, number> => {
+    const out = new Map<string, number>()
+    for (const set of sets) if (set !== undefined) for (const [id, w] of set) out.set(id, w)
+    return out
+  }
+  for (const [i, plugin] of plugins.entries()) {
     if (plugin.schedule === undefined) continue
-    const own = { ...ctx, cache: cacheFor(plugin.name) }
-    const weights = await safe(plugin, 'schedule', () => plugin.schedule!(nodes, own))
-    if (weights === undefined) continue
-    // Iterating a string destructures its characters into `[id, w]` pairs
-    // that match no task — a plugin returning `'fast'` used to be a no-op
-    // with no word said.
-    if (!(weights instanceof Map)) {
+    const refine = (weights: ReadonlyMap<string, number>): void => {
+      if (run.refined === undefined) return
+      try {
+        sets[i] = scheduleWeights(plugin, weights, nodes)
+      } catch (err) {
+        ctx.warn(`[vx] ${err instanceof Error ? err.message : String(err)}; refine ignored`)
+        return
+      }
+      run.refined(merged())
+    }
+    const own = { ...ctx, cache: cacheFor(plugin.name), refine }
+    const call = (): Promise<ReadonlyMap<string, number> | undefined> =>
+      safe(plugin, 'schedule', () => plugin.schedule!(nodes, own))
+    const weights = await (run.step === undefined
+      ? call()
+      : run.step(`${plugin.name}:schedule`, call))
+    // A refine that landed while the call ran is the newer set.
+    if (weights !== undefined) sets[i] ??= scheduleWeights(plugin, weights, nodes)
+  }
+  return merged()
+}
+
+/** A `schedule` answer's weights for tasks in the graph, refused by name when it is not a Map of finite numbers. */
+function scheduleWeights(
+  plugin: VxPlugin,
+  weights: unknown,
+  nodes: ReadonlyMap<string, TaskNode>,
+): ReadonlyMap<string, number> {
+  // Iterating a string destructures its characters into `[id, w]` pairs
+  // that match no task — a plugin returning `'fast'` used to be a no-op
+  // with no word said.
+  if (!(weights instanceof Map)) {
+    throw new UserError(
+      `plugin '${plugin.name}' failed in schedule: returned ${describeValue(weights)}, not a Map of task id → weight`,
+    )
+  }
+  const out = new Map<string, number>()
+  for (const [id, w] of weights as Map<unknown, unknown>) {
+    if (typeof id !== 'string' || !nodes.has(id)) continue
+    if (typeof w !== 'number' || !Number.isFinite(w)) {
       throw new UserError(
-        `plugin '${plugin.name}' failed in schedule: returned ${describeValue(weights)}, not a Map of task id → weight`,
+        `plugin '${plugin.name}' failed in schedule: weight for ${id} is not a finite number`,
       )
     }
-    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)
-    }
+    out.set(id, w)
   }
-  return merged
+  return out
 }
 
 /**
@@ -485,70 +524,39 @@ export interface CacheHost extends CacheContext {
   readonly localCache: Cache
   readonly policy: CachePolicy
   /** Filled with each remote and what its policy lets it do, for the plugins' `ctx.cache`. */
-  readonly remotes?: PluginCacheRemote[]
+  readonly remotes?: ResolvedRemote[]
 }
 
 /**
  * Collect every plugin's remote (`cache` hook) in declaration order and
  * layer each over the local store: a lookup asks the local store first,
  * then each remote in order (owner, 2026-10-13), and a save reaches every
- * remote. The run's policy, narrowed by a remote's `access`, and its scope
- * gate each remote; a remote's throw is a miss and a warning naming its
- * plugin. No remote → the local store alone.
+ * remote. The run's policy, narrowed by a remote's `access`, gates each
+ * remote; a remote's throw is a miss and a warning naming its plugin. No
+ * remote → the local store alone.
  */
 export async function resolveCache(
   plugins: readonly VxPlugin[],
   host: CacheHost,
 ): Promise<CacheLayer> {
   const { localCache, policy, remotes, ...ctx } = host
-  const layers: CacheLayer[] = []
-  const owners: string[] = []
+  const resolved: ResolvedRemote[] = []
   for (const plugin of plugins) {
     if (plugin.cache === undefined) continue
     const remote = await safe(plugin, 'cache', () => plugin.cache!(ctx))
     if (remote === undefined) continue
-    // The hook returned a whole layer until 0.0.637: name the fix, not the
-    // three methods such a layer happens to have.
-    if (isRecordLike(remote) && typeof remote['restoreOutputs'] === 'function') {
-      throw new UserError(
-        `plugin '${plugin.name}' returned a cache layer from cache: since vx 0.0.637 the hook ` +
-          'returns the remote alone (a RemoteCacheLayer: has, get, put) and core layers it over ' +
-          'the local cache — return the remote you passed to LayeredCache',
-      )
-    }
     assertShape(plugin, 'cache', remote, REMOTE_CACHE_METHODS, 'a remote cache layer')
     const access = remote.access
-    const own: CachePolicy = {
-      ...policy,
-      remoteRead: policy.remoteRead && access?.read !== false,
-      remoteWrite: policy.remoteWrite && access?.write !== false,
+    const entry: ResolvedRemote = {
+      remote,
+      read: policy.remoteRead && access?.read !== false,
+      write: policy.remoteWrite && access?.write !== false,
+      onError: (err) => ctx.warn(`[vx] plugin '${plugin.name}': ${err.message}`),
     }
-    remotes?.push({ remote, read: own.remoteRead, write: own.remoteWrite })
-    layers.push(
-      new LayeredCache(localCache, remote, {
-        policy: own,
-        onRemoteError: (err) => ctx.warn(`[vx] plugin '${plugin.name}': ${err.message}`),
-      }),
-    )
-    owners.push(`the cache layer of plugin '${plugin.name}'`)
+    resolved.push(entry)
+    remotes?.push(entry)
   }
-  if (layers.length === 0) return localCache
-  if (layers.length === 1) return layers[0]!
-  // One line per layer and method: a layer that throws on every lookup
-  // would otherwise print once per task.
-  const told = new Set<string>()
-  return new ChainedCache(layers, (i, method, err) => {
-    if (told.has(`${i}\0${method}`)) return
-    told.add(`${i}\0${method}`)
-    const m = err instanceof Error ? err.message : String(err)
-    const then =
-      method === 'save' ? 'the other layers still save' : 'a miss there; the next layer answers'
-    ctx.warn(`[vx] ${owners[i]} failed in cache ${method}: ${m}; ${then}`)
-  })
-}
-
-function isRecordLike(v: unknown): v is Record<string, unknown> {
-  return typeof v === 'object' && v !== null
+  return resolved.length === 0 ? localCache : new LayeredCache(localCache, resolved)
 }
 
 /** The plugin each resolved executor came from, so a hook of it that throws is named. */
@@ -581,6 +589,55 @@ export function executorLabel(executor: TaskExecutor): string {
     : `plugin '${plugin}' (executor '${executor.name}')`
 }
 
+/**
+ * Demand: what each executor still has left to run. An executor that
+ * provisions per task (a container, an allocation, a pod) otherwise has to
+ * guess from `capacity` alone and hold everything until teardown. Built
+ * ONLY for executors that asked: with none declared there is no map, no
+ * set, and the returned narrower does nothing.
+ *
+ * The SAME set is handed back every time, narrowed in place: a consumer
+ * reading it later sees the truth rather than a stale snapshot. A hint,
+ * as `admit` is: one that throws is named once and asked no more, where
+ * it surfaced as a bare stack, or mid-run from the completion path
+ * (item 1022). Returns the call that drops a finished task's id.
+ */
+export function executorDemand(
+  placed: ReadonlyMap<string, TaskExecutor>,
+  warn: (message: string) => void,
+): (id: string) => void {
+  const demandOf = new Map<TaskExecutor, Set<string>>()
+  for (const [id, executor] of placed) {
+    if (executor.demand === undefined) continue
+    let remaining = demandOf.get(executor)
+    if (remaining === undefined) demandOf.set(executor, (remaining = new Set()))
+    remaining.add(id)
+  }
+  if (demandOf.size === 0) return () => {}
+  const tell = (executor: TaskExecutor, remaining: ReadonlySet<string>): void => {
+    const failed = (err: unknown): void => {
+      if (!demandOf.delete(executor)) return
+      const m = err instanceof Error ? err.message : String(err)
+      warn(`[vx] ${executorLabel(executor)} failed in demand: ${m}; not asked again this run`)
+    }
+    try {
+      // An `async demand` that rejects did so where no one listened: an
+      // unhandled rejection, a stack, the run killed. Its rejection is a
+      // throw like any other.
+      const ret: unknown = executor.demand!(remaining)
+      if (ret instanceof Promise) ret.catch(failed)
+    } catch (err) {
+      failed(err)
+    }
+  }
+  for (const [executor, remaining] of demandOf) tell(executor, remaining)
+  return (id) => {
+    for (const [executor, remaining] of demandOf) {
+      if (remaining.delete(id)) tell(executor, remaining)
+    }
+  }
+}
+
 /**
  * Collect every plugin's `executor`, in declaration order, with core's
  * own appended at the tail: per task, `selectExecutor` takes the first
@@ -638,12 +695,15 @@ export async function teardownPlugins(
   plugins: readonly VxPlugin[],
   warn: (message: string) => void,
   report?: RunReport,
+  step: <T>(id: string, work: () => Promise<T>) => Promise<T> = (_id, work) => work(),
 ): Promise<void> {
   for (const plugin of plugins) {
     if (plugin.teardown === undefined) continue
     const ms = teardownTimeoutMs()
     try {
-      const settled = await settleWithin(Promise.resolve(plugin.teardown(report)), ms)
+      const settled = await step(`${plugin.name}:teardown`, () =>
+        settleWithin(Promise.resolve(plugin.teardown?.(report)), 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.

package/src/orchestrator/plugin.ts

@@ -22,10 +22,9 @@ import type { TaskExecutor } from '../exec/index.js'
 import type { TaskNode, TaskOutcome, TaskStatus } from '../graph/index.js'
 import { maskedLine, nearest, UserError } from '../util/index.js'
 import type { ProjectMeta } from '../workspace/index.js'
-import type { EventBus, RunStartInfo } from './events.js'
+import type { EventBus, Logger, RunStartInfo } from '../report/index.js'
 import type { CiContext } from './run-context.js'
 import type { TelemetryContext, TelemetrySink } from './telemetry.js'
-import type { Logger } from './logger.js'
 
 /**
  * A vx plugin. Contributes any subset of the run-level capabilities —
@@ -138,6 +137,9 @@ export interface VxPlugin {
    * only when a task will start: a run of confirmed local hits restores
    * in no order a weight changes. A later plugin's weight for a task
    * overrides an earlier one's. Return undefined to leave the baseline.
+   * The run waits for this answer before its first task, so it should
+   * come from what is at hand (local history); better weights that need
+   * a fetch go to `ctx.refine` when they arrive, without holding the run.
    */
   schedule?(
     nodes: ReadonlyMap<string, TaskNode>,
@@ -245,8 +247,9 @@ export interface VxPlugin {
 /**
  * What a finished run hands each plugin's `teardown`: its facts and every
  * task, with the names core kept the task's bytes under. Core keeps them
- * only when a remote takes the run's writes (CI by default): a failed
- * task's log and the files its outputs left, an uncached task's log. Read
+ * only when a remote takes the run's writes (CI by default): the log of a
+ * task that saved no entry, and a failed task's log and the files its
+ * outputs left when `cache.upload.failures` covers the run. Read
  * them with `ctx.cache.getRun(name)`. Core keeps no manifest of its own; a
  * plugin that wants one writes it from here (`ctx.cache.put`).
  */
@@ -449,6 +452,12 @@ export interface ScheduleHookContext extends BaseContext {
   readonly branch: string | null
   /** This plugin's entries in the workspace's cache, as `setup` has them. */
   readonly cache: PluginCache
+  /**
+   * Replace this plugin's weights while the run goes on: the tasks not yet
+   * started re-rank at once. For weights that arrive late (timings fetched
+   * from a remote). Ignored in a plan and once the run's tasks are done.
+   */
+  refine(weights: ReadonlyMap<string, number>): void
 }
 
 /** A `cache` hook's context: the workspace and the run's scope, never the local store or the policy, which core owns. */
@@ -462,12 +471,10 @@ export interface CacheContext extends BaseContext {
 }
 
 export interface OutputContext extends BaseContext {
-  /** Core would write to a terminal: stdout (stderr under `json`) is a TTY. */
+  /** Core would write to a terminal: stdout is a TTY. */
   readonly isTTY: boolean
   /** The run is on CI (`CI` set, or a provider core detects). */
   readonly ci: boolean
-  /** `--format json`: stdout carries the machine-readable result. */
-  readonly json: boolean
 }
 
 export interface ExecutorContext extends BaseContext {
@@ -688,6 +695,8 @@ export interface InstallPluginsArgs {
   ci?: boolean
   /** Default null. */
   branch?: string | null
+  /** Each setup as the step `<plugin>:setup`; default: untimed. */
+  step?: <T>(id: string, work: () => Promise<T>) => Promise<T>
 }
 
 /**
@@ -824,7 +833,8 @@ export async function installPlugins(args: InstallPluginsArgs): Promise<() => vo
     }
 
     try {
-      await plugin.setup(ctx)
+      if (args.step === undefined) await plugin.setup(ctx)
+      else await args.step(`${plugin.name}:setup`, async () => plugin.setup?.(ctx))
     } catch (err) {
       // Earlier plugins' subscriptions too: the caller never gets the
       // disposer, and a bus that outlives the run would keep them.