@vzn/vx 0.0.637 → 0.0.639

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'
 
@@ -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,6 +1,6 @@
 // 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()`
@@ -13,10 +13,10 @@
 
 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,10 +10,12 @@
 import path from 'node:path'
 import {
   type Cache,
-  ChainedCache,
   type CacheLayer,
   type CachePolicy,
   LayeredCache,
+  absentPluginCache,
+  type PluginCache,
+  type ResolvedRemote,
 } from '../cache/index.js'
 import { localExecutor, type TaskExecutor } from '../exec/index.js'
 import { maskedLine, settleWithin, teardownTimeoutMs, UserError } from '../util/index.js'
@@ -29,6 +31,7 @@ import type {
   KeyHookContext,
   DiscoveredProject,
   ProjectHookContext,
+  RunReport,
   ScheduleHookContext,
   VxPlugin,
   WorkspaceHookContext,
@@ -385,12 +388,14 @@ export async function claimedAffected(
 export async function applyScheduleHooks(
   plugins: readonly VxPlugin[],
   nodes: ReadonlyMap<string, TaskNode>,
-  ctx: ScheduleHookContext,
+  ctx: Omit<ScheduleHookContext, 'cache'>,
+  cacheFor: (plugin: string) => PluginCache = () => absentPluginCache,
 ): Promise<ReadonlyMap<string, number>> {
   const merged = new Map<string, number>()
   for (const plugin of plugins) {
     if (plugin.schedule === undefined) continue
-    const weights = await safe(plugin, 'schedule', () => plugin.schedule!(nodes, ctx))
+    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
@@ -478,68 +483,40 @@ export function buildAdmission(
 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?: 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, ...ctx } = host
-  const layers: CacheLayer[] = []
-  const owners: string[] = []
+  const { localCache, policy, remotes, ...ctx } = host
+  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}`),
     }
-    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. */
@@ -572,6 +549,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
@@ -628,12 +654,16 @@ export async function resolveExecutors(
 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()), 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

@@ -11,15 +11,20 @@
 import { readFileSync } from 'node:fs'
 import path from 'node:path'
 import { fileURLToPath } from 'node:url'
-import type { Cache, RemoteCacheLayer } from '../cache/index.js'
+import {
+  absentPluginCache,
+  type Cache,
+  type PluginCache,
+  type RemoteCacheLayer,
+} from '../cache/index.js'
 import { PLUGIN_PACKAGE, type ProjectConfig, type WorkspaceConfig } from '../config.js'
 import type { TaskExecutor } from '../exec/index.js'
-import type { TaskNode, TaskOutcome } from '../graph/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 —
@@ -221,15 +226,51 @@ export interface VxPlugin {
    * Optional one-time setup per run (validate the workspace, open a
    * connection, read a token). Throwing aborts the run with a clean
    * UserError naming the plugin. It is not a guard over the pipeline: the
-   * config, project, cache, graph, key and schedule stages have run by the
-   * time it is called, and a plan (`--dry`, `planRun`) never calls it. It
-   * precedes the executors, the telemetry sinks, admission and the first
-   * task (tests/plugin-e2e.test.ts).
+   * config, project, cache, graph and key stages have run by the time it
+   * is called, and a plan (`--dry`, `planRun`) never calls it. It
+   * precedes the schedule stage, the executors, the telemetry sinks,
+   * admission and the first task (tests/plugin-e2e.test.ts).
    */
   setup?(ctx: PluginSetupContext): void | Promise<void>
 
-  /** Optional teardown at end-of-run (flush a sink, close a socket). Errors are logged, never thrown. */
-  teardown?(): void | Promise<void>
+  /**
+   * Optional teardown at end-of-run (flush a sink, close a socket). Errors
+   * are logged, never thrown. A run that ran to its end passes its
+   * `RunReport`; every other exit (a refused setup, a stop) passes none.
+   */
+  teardown?(run?: RunReport): void | Promise<void>
+}
+
+/**
+ * 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
+ * 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`).
+ */
+export interface RunReport {
+  /** The `run_id` the run's history rows and telemetry carry. */
+  readonly runId: string
+  /** `HEAD`'s commit, null outside a git worktree. */
+  readonly commit: string | null
+  /** What the CI provider says about this run: provider, run URL, pipeline, job, attempt. */
+  readonly ciRun: CiContext
+  readonly ok: boolean
+  /** Every task the run decided, in completion order; group tasks are left out. */
+  readonly tasks: readonly RunReportTask[]
+}
+
+export interface RunReportTask {
+  readonly id: string
+  readonly status: TaskStatus
+  readonly durationMs: number
+  /** The task's cache key, when one was computed. */
+  readonly key?: string
+  /** Its output (both streams, secrets masked), when core kept it: `ctx.cache.getRun(log)`. */
+  readonly log?: string
+  /** A tar of the files its declared outputs left, when core kept it: `ctx.cache.getRun(outputs)`. */
+  readonly outputs?: string
 }
 
 /** Shared, read-only context every capability factory receives. */
@@ -242,6 +283,12 @@ interface BaseContext {
 
 /** What `setup` receives: the run's lifecycle, observe-only. */
 export interface PluginSetupContext extends BaseContext {
+  /** This plugin's entries in the workspace's cache (`PluginCache`). */
+  readonly cache: PluginCache
+  /** The run is on CI (`CI` set, or a provider core detects). */
+  readonly ci: boolean
+  /** The run's branch (`currentBranch`): `run.branch`, else git's, else the CI provider's. */
+  readonly branch: string | null
   /**
    * Subscribe a lifecycle handler; it leaves with the run. A throw or a
    * rejection warns once and switches the plugin's handlers off for the run.
@@ -271,6 +318,12 @@ export interface CommandContext extends BaseContext {
    * which `vx` a PATH holds.
    */
   readonly vx: readonly string[]
+  /**
+   * This plugin's entries in the workspace's cache, as `setup` reaches them
+   * (`PluginCache`), read-only: the local store, then each remote the
+   * workspace's cache plugins supply, under the run's scope. Opened on first use.
+   */
+  readonly cache: PluginCache
 }
 
 /** `config` runs before the cache dir is known — it may be what the hook changes. */
@@ -327,6 +380,13 @@ export interface ProjectHookContext extends BaseContext {
    * process.
    */
   readonly projects: readonly ProjectMeta[]
+  /**
+   * True when `vx lock` (or `--check`) visits: the one pass that checks the
+   * configs, so the place to report what a plugin's mapping could not say.
+   * A run checks nothing (the lock model), so such a report there repeats
+   * on every run.
+   */
+  readonly lock: boolean
 }
 
 export interface GraphHookContext extends BaseContext {
@@ -386,6 +446,8 @@ export interface ScheduleHookContext extends BaseContext {
   readonly localCache: Cache
   /** The run's branch (`currentBranch`), the timings a forecast reads first: pass it to `LocalHistoryProvider`. */
   readonly branch: string | null
+  /** This plugin's entries in the workspace's cache, as `setup` has them. */
+  readonly cache: PluginCache
 }
 
 /** A `cache` hook's context: the workspace and the run's scope, never the local store or the policy, which core owns. */
@@ -399,12 +461,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 {
@@ -619,6 +679,14 @@ export interface InstallPluginsArgs {
    * `run:status` channel.
    */
   warn?: (message: string) => void
+  /** Each plugin's `ctx.cache`, by plugin name. Default: a cache with no layer. */
+  cache?: (plugin: string) => PluginCache
+  /** Default false. */
+  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>
 }
 
 /**
@@ -675,6 +743,9 @@ export async function installPlugins(args: InstallPluginsArgs): Promise<() => vo
       workspaceRoot,
       cacheDir,
       warn,
+      cache: args.cache?.(plugin.name) ?? absentPluginCache,
+      ci: args.ci ?? false,
+      branch: args.branch ?? null,
       // A subscription made past the hooks leaves with the run like a
       // hook's does: the bus can outlive the run (`RunOptions.bus`), and
       // one left behind hears every later run on it (item 635).
@@ -752,7 +823,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.