@vzn/vx 0.0.644 → 0.0.646

package/src/orchestrator/index.ts

@@ -2,7 +2,13 @@
 // through here (enforced by tests/module-boundaries.test.ts).
 
 export { run, planRun, nxProjectTarget, projectNamed } from './run.js'
-export { prepareRun, type PreparedRun } from './prepare.js'
+export {
+  namesRemote,
+  openRemotes,
+  prepareRun,
+  workspaceCachePolicy,
+  type PreparedRun,
+} from './prepare.js'
 export { affectedTaskProjects } from './affected-tasks.js'
 export { applyGraphStage } from './graph-stage.js'
 export type { AffectedReason } from './affected-tasks.js'
@@ -37,6 +43,14 @@ export { forwardedSignal } from './signals.js'
 // `vx cache clean` waits for a run on the workspace before it evicts.
 export { acquireRunLock } from './run-lock.js'
 export type { RunPlan, PlannedTask, PlanPrediction, CacheStatus } from './plan.js'
+export {
+  cacheFacts,
+  taskArtifacts,
+  type ArtifactRun,
+  type ArtifactTask,
+  type CacheFacts,
+  type TaskArtifacts,
+} from './task-artifacts.js'
 export {
   installPlugins,
   type CacheContext,
@@ -120,6 +134,7 @@ export {
   currentBranch,
   detectCi,
   localBranchScope,
+  cacheRefs,
   resolveCacheScope,
 } from './run-context.js'
 export type { CiContext, GitContext, HostContext, WorkspaceIdentity } from './run-context.js'
@@ -133,3 +148,5 @@ export {
 export { type RunStep, runSteps } from './run-steps.js'
 export { resolveRunId, shortRunId } from './run-id.js'
 export { collectInfo, type CollectInfoOptions, type InfoFacts } from './doctor.js'
+export { localFloor, type LocalFloor } from './local-floor.js'
+export { sandboxRequestFor, type SandboxRequest } from './sandbox-request.js'

package/src/orchestrator/local-floor.ts

@@ -0,0 +1,104 @@
+// Core's local floor for a plugin that runs tasks itself: `@vzn/vx-dte`'s
+// orchestrator for its own share, and its agents, which run tasks another
+// machine placed. A run arms the sandbox runtime before it builds a
+// sandboxed request; an agent is no run, so it arms here. It starts a
+// request's servers (`ExecuteRequest.servers`) once each, before the
+// task, and stops them when it closes.
+
+import type { ExecConfig } from '../config.js'
+import {
+  localExecutor,
+  resetSandbox,
+  runPersistent,
+  type ExecuteRequest,
+  type ExecuteResult,
+  type ServerSpec,
+} from '../exec/index.js'
+import { prepareSandbox } from './sandbox-request.js'
+import { forwardedSignal, terminateChildren } from './signals.js'
+
+export interface LocalFloor {
+  execute(req: ExecuteRequest): Promise<ExecuteResult>
+  /** Arms the sandbox runtime for `sandboxes` from the next sandboxed task on; its servers keep running. */
+  rearm(sandboxes: readonly NonNullable<ExecConfig['sandbox']>[]): Promise<void>
+  /** Stops the servers this started and the sandbox runtime this armed. */
+  close(): Promise<void>
+}
+
+/**
+ * `sandboxes`, in a process that is no run, are the `exec.sandbox` configs
+ * of every sandboxed task the run holds: the runtime's proxy and its
+ * unix-socket filter are one per process, set from their union before the
+ * first sandboxed task (`prepareSandbox`). A request that carries a
+ * `signal` but no `liveChildren` has its children stopped here when it
+ * aborts, the way a run's stop ends its own.
+ */
+export function localFloor(
+  sandboxes: readonly NonNullable<ExecConfig['sandbox']>[] = [],
+): LocalFloor {
+  const local = localExecutor()
+  const prepare = (list: typeof sandboxes) =>
+    prepareSandbox(list.map((sandbox) => ({ config: { exec: { sandbox } } })))
+  let armer = prepare(sandboxes)
+  // Each server, by task id: shared by every task here that depends on it.
+  const servers = new Map<string, Promise<ReturnType<typeof Bun.spawn>>>()
+  const children: ReturnType<typeof Bun.spawn>[] = []
+  const serve = (spec: ServerSpec): Promise<unknown> => {
+    let up = servers.get(spec.taskId)
+    if (up === undefined) {
+      const spawn = runPersistent({
+        command: spec.command,
+        cwd: spec.cwd,
+        env: spec.env,
+        onStdout: () => {},
+        onStderr: () => {},
+        ...(spec.readyWhen === undefined ? {} : { readyWhen: spec.readyWhen }),
+        ...(spec.timeoutMs === undefined ? {} : { timeoutMs: spec.timeoutMs }),
+      })
+      children.push(spawn.child)
+      up = spawn.ready.then(() => spawn.child)
+      servers.set(spec.taskId, up)
+      // One that never became ready is asked again by the next task.
+      up.catch(() => servers.delete(spec.taskId))
+    }
+    return up
+  }
+  return {
+    async execute(req) {
+      for (const spec of req.servers ?? []) {
+        try {
+          await serve(spec)
+        } catch (err) {
+          const why = err instanceof Error ? err.message : String(err)
+          return {
+            exitCode: 1,
+            durationMs: 0,
+            stdout: '',
+            stderr: `${spec.taskId}, which ${req.taskId} depends on, did not start: ${why}\n`,
+            violations: [],
+          }
+        }
+      }
+      if (req.sandbox !== undefined) await armer?.arm()
+      const stop = req.signal
+      if (stop === undefined || req.liveChildren !== undefined) return local.execute(req)
+      // No run holds this task's children (an agent's): its stop is ours to carry out.
+      const live = new Set<ReturnType<typeof Bun.spawn>>()
+      const end = (): void => void terminateChildren(() => [...live], forwardedSignal(stop.reason))
+      stop.addEventListener('abort', end, { once: true })
+      try {
+        return await local.execute({ ...req, liveChildren: live })
+      } finally {
+        stop.removeEventListener('abort', end)
+      }
+    },
+    async rearm(list) {
+      if (armer?.armed === true) await resetSandbox()
+      armer = prepare(list)
+    },
+    async close() {
+      if (children.length > 0) await terminateChildren(() => children)
+      if (armer?.armed === true) await resetSandbox()
+    },
+  }
+}

package/src/orchestrator/local-shortcircuit.ts

@@ -45,6 +45,7 @@ import { normalizeGlob, relPosix, span, staticPrefix } from '../util/index.js'
 import type { CacheEntry, CacheLayer, GitFilesCache } from '../cache/index.js'
 import type { TaskNode } from '../graph/index.js'
 import { deriveStableKeys, workspaceInputsReach } from './stable-keys.js'
+import { readRunKeys, runKeysToken, writeRunKeys } from './run-keys.js'
 import type { HashCache, UpfrontGroupKey } from './task-hash.js'
 import { getContext } from './remote-prefetch.js'
 
@@ -100,6 +101,8 @@ export interface ShortCircuit {
   uncachedKeys: Map<string, string>
   /** Unkeyed group id → its up-front key (`deriveStableKeys`' `groupKeys`). */
   groupKeys: Map<string, UpfrontGroupKey>
+  /** Behind a remote, each stable task the local store missed → its key: the remote may hold it. */
+  remoteAsk: Map<string, string>
 }
 
 /**
@@ -117,13 +120,22 @@ export async function startLocalShortCircuit(args: ShortCircuitArgs): Promise<Sh
   const groupKeys = new Map<string, UpfrontGroupKey>()
   const endKeys = span('stable keys')
   try {
-    stableKeys = await deriveStableKeys({ ...args, uncachedKeys, groupKeys })
+    const at = runKeysToken(args)
+    const remembered = at === undefined ? undefined : readRunKeys(args, at)
+    if (remembered !== undefined) {
+      stableKeys = remembered.stableKeys
+      for (const [id, key] of remembered.uncachedKeys) uncachedKeys.set(id, key)
+    } else {
+      stableKeys = await deriveStableKeys({ ...args, uncachedKeys, groupKeys })
+      if (at !== undefined) writeRunKeys(args, at, { stableKeys, uncachedKeys })
+    }
   } catch {
     return {
       preProbed: new Map(),
       restoreTier: new Set(),
       uncachedKeys: new Map(),
       groupKeys: new Map(),
+      remoteAsk: new Map(),
     }
   } finally {
     endKeys()
@@ -134,15 +146,16 @@ export async function startLocalShortCircuit(args: ShortCircuitArgs): Promise<Sh
   const candidates = stableKeys
   const preProbed = new Map<string, ProbedEntry>()
   const restoreTier = new Set<string>()
+  const remoteAsk = new Map<string, string>()
   if (candidates.length === 0 && uncachedKeys.size === 0) {
-    return { preProbed, restoreTier, uncachedKeys, groupKeys }
+    return { preProbed, restoreTier, uncachedKeys, groupKeys, remoteAsk }
   }
 
   const keptOut = restoreTierExclusions(args.nodes, args.workspaceRoot)
   // A root-anchored output may land in a project no edge leads from, so an
   // uncached key there is derived again once the writer may have run.
   for (const id of keptOut) uncachedKeys.delete(id)
-  if (candidates.length === 0) return { preProbed, restoreTier, uncachedKeys, groupKeys }
+  if (candidates.length === 0) return { preProbed, restoreTier, uncachedKeys, groupKeys, remoteAsk }
 
   // Bounded pool over the stable candidates: probe local ONCE each. A
   // confirmed hit becomes restore-tier (unless workspace outputs disable
@@ -165,11 +178,14 @@ export async function startLocalShortCircuit(args: ShortCircuitArgs): Promise<Sh
       endProbe()
       for (const { hash, node } of candidates) {
         const hit = hits.get(hash) ?? null
-        if (hit === null && args.localOnly === true) continue
+        if (hit === null && args.localOnly === true) {
+          if (!keptOut.has(node.id)) remoteAsk.set(node.id, hash)
+          continue
+        }
         preProbed.set(node.id, { hash, hit })
         if (hit !== null && !keptOut.has(node.id)) restoreTier.add(node.id)
       }
-      return { preProbed, restoreTier, uncachedKeys, groupKeys }
+      return { preProbed, restoreTier, uncachedKeys, groupKeys, remoteAsk }
     } catch {
       // Fall through to the per-hash pool, which isolates a failing probe
       // to its own task.
@@ -182,7 +198,10 @@ export async function startLocalShortCircuit(args: ShortCircuitArgs): Promise<Sh
       const { hash, node } = candidates[next++]!
       try {
         const hit = await args.cache.get(hash, getContext(node, node.config.exec?.command ?? ''))
-        if (hit === null && args.localOnly === true) continue
+        if (hit === null && args.localOnly === true) {
+          if (!keptOut.has(node.id)) remoteAsk.set(node.id, hash)
+          continue
+        }
         preProbed.set(node.id, { hash, hit })
         if (hit !== null && !keptOut.has(node.id)) restoreTier.add(node.id)
       } catch {
@@ -193,7 +212,7 @@ export async function startLocalShortCircuit(args: ShortCircuitArgs): Promise<Sh
   }
   await Promise.all(Array.from({ length: workers }, () => pump()))
 
-  return { preProbed, restoreTier, uncachedKeys, groupKeys }
+  return { preProbed, restoreTier, uncachedKeys, groupKeys, remoteAsk }
 }
 
 /**

package/src/orchestrator/miss-save.ts

@@ -13,6 +13,7 @@ import {
   type CacheLayer,
   type GitFilesCache,
   resolveOutputTree,
+  outputWalkTakes,
   resolveOutputs,
   resolveWorkspaceOutputs,
   WORKSPACE_OUTPUT_PREFIX,
@@ -20,11 +21,12 @@ import {
 import type { TaskNode } from '../graph/index.js'
 import {
   asTrees,
+  outputDirPrefixes,
   relPosix,
   span,
+  splitNegations,
   staticPrefix,
   taskGlob,
-  wholeSubtreePrefixes,
 } from '../util/index.js'
 import { type Logger, warnOf } from '../report/index.js'
 import type { TaskInputComponent } from '../cache/index.js'
@@ -49,8 +51,12 @@ export interface OutputDirSnapshot {
  */
 export function entryHolds(
   node: TaskNode,
+  takes: (rel: string) => boolean,
 ): (files: readonly string[], rows: ReadonlyArray<{ path: string }>) => boolean {
-  return (files, rows) => {
+  return (walked, rows) => {
+    // A root-anchored glob's snapshot walks the whole project: only what
+    // the glob takes is the entry's.
+    const files = walked.filter(takes)
     const expected = new Set(
       rows
         .map((r) => r.path)
@@ -250,13 +256,13 @@ export async function saveMiss(a: SaveMissArgs): Promise<{ landed: Promise<SaveF
     // list gets no snapshot: recording here was that same refusal (item
     // 637 deleted the fallback and nothing reddened), and the next hit
     // walks, as it did.
-    const savedDirPrefixes = wholeSubtreePrefixes(a.outputs)
+    const savedDirPrefixes = outputDirPrefixes(splitNegations(a.outputs).positive)
     if (savedDirPrefixes !== null && a.outputDirSnapshots !== undefined) {
       a.outputDirSnapshots.push({
         hash: a.hash,
         projectDir: node.projectDir,
         prefixes: savedDirPrefixes,
-        holds: entryHolds(node),
+        holds: entryHolds(node, outputWalkTakes(node.projectDir, a.outputs, a.nestedProjectDirs)),
       })
     }
   }

package/src/orchestrator/options.ts

@@ -92,14 +92,6 @@ export interface RunOptions {
   remoteRequested?: boolean
   /** This run's cache scope, above `VX_CACHE_SCOPE`, a plugin's and the branch's (an embedder's). */
   cacheScope?: string
-  /**
-   * What the branch changed, for a scoped run: the tasks whose key it can
-   * move read the scope's key, every other task the default key (one
-   * lookup each). Absent, the run diffs the branch from `scopeBase`.
-   */
-  scopeChanges?: AffectedChanges
-  /** The commit a scoped run diffs the branch from (`--affected`'s base); absent, a plugin's, else the merge base with the default branch. */
-  scopeBase?: string
   /**
    * The default policy's remote write is off (`remote:r`): the CLI passes it
    * off CI (`CI` unset, `0` or `false`) unless `--cache-policy` or

package/src/orchestrator/persistent-task.ts

@@ -73,6 +73,20 @@ export async function executePersistentTask(args: ExecuteArgs): Promise<TaskOutc
           ...(args.hashCache !== undefined ? { hashCache: args.hashCache } : {}),
         })))
 
+  // Every dependant starts it where it runs (`ServerSpec`): nothing to spawn
+  // here, and nothing that ran (owner, 2026-10-22: nothing runs on a
+  // distributed run's orchestrator).
+  if (args.carried === true)
+    return {
+      node,
+      status: 'success',
+      exitCode: 0,
+      durationMs: 0,
+      ...(hash === undefined ? {} : { hash }),
+      wallclockStartNs,
+      wallclockEndNs: wallclockStartNs,
+    }
+
   // The args after `--` reach a server as they reach any task. A readyWhen
   // server once got none — "so the matcher sees the unmodified output",
   // though the args change the command, not what the matcher reads — and

package/src/orchestrator/placement.ts

@@ -1,7 +1,7 @@
 // Where each task runs: the placement of a graph over the resolved
 // executors, and the plan-mode view of it. Split from run.ts on 2026-09-10
 // (pure motion). A task is pinned to this machine when it is persistent,
-// depends on a persistent task, is sandboxed, says `exec.remote: false`, or
+// depends on a persistent task no `servers` executor carries, is sandboxed, says `exec.remote: false`, or
 // folds a runtime probe into its key; an `exec.interactive` task goes to the
 // local floor directly, as only it can hand over this terminal;
 // everything else asks the executors in declaration order, and the local
@@ -14,6 +14,7 @@ import { resolveDownloadModes } from './download-policy.js'
 import { type Logger, warnOf } from '../report/index.js'
 import { executorLabel, resolveExecutors } from './plugin-host.js'
 import type { prepareRun } from './prepare.js'
+import { cacheFacts, taskArtifacts } from './task-artifacts.js'
 
 /**
  * A task is pinned to this machine when it is persistent, transitively
@@ -22,20 +23,29 @@ import type { prepareRun } from './prepare.js'
  * machinery — a worker has none of it, and a boundary "verified" where it
  * is not enforced passes vacuously), or declares `exec.remote: false`. A
  * dependant of a pinned task is pinned with it. A task whose key folds a
- * runtime probe is pinned alone (`withProbedRuntime`).
+ * runtime probe is pinned alone (`withProbedRuntime`). `sandbox: false`
+ * leaves `exec.sandbox` out: the set for an executor that enforces it where
+ * it runs (`TaskExecutor.sandbox`).
  */
-export function pinnedLocalSet(nodes: Map<string, TaskNode>): Set<string> {
+export function pinnedLocalSet(
+  nodes: Map<string, TaskNode>,
+  sandbox = true,
+  /** For a `servers` executor: a carriable persistent task pins nothing. */
+  servers = false,
+  /** `false` for a `runtime` executor: it checks the probes where it runs the task. */
+  runtime = true,
+): Set<string> {
   const pinned = new Set<string>()
   for (const node of nodes.values()) {
     if (
-      node.config.exec?.persistent !== undefined ||
-      node.config.exec?.sandbox !== undefined ||
+      (node.config.exec?.persistent !== undefined && !(servers && carriable(node))) ||
+      (sandbox && node.config.exec?.sandbox !== undefined) ||
       node.config.exec?.remote === false
     ) {
       pinned.add(node.id)
     }
   }
-  if (pinned.size === 0) return withProbedRuntime(nodes, pinned)
+  if (pinned.size === 0) return runtime ? withProbedRuntime(nodes, pinned) : pinned
   // Pinning flows up the dependant edges from what pins itself, one walk on
   // an explicit stack: a chain is as deep as the graph, and a recursion
   // per edge threw `RangeError` on the 50,000 the builder takes (item 737).
@@ -55,14 +65,50 @@ export function pinnedLocalSet(nodes: Map<string, TaskNode>): Set<string> {
       stack.push(up)
     }
   }
-  return withProbedRuntime(nodes, pinned)
+  return runtime ? withProbedRuntime(nodes, pinned) : pinned
+}
+
+/**
+ * A persistent task a `servers` executor can start where it runs a
+ * dependant: one the run holds for its dependants only, with no sandbox
+ * (this machine's machinery) and no `exec.remote: false`.
+ */
+function carriable(node: TaskNode): boolean {
+  const exec = node.config.exec
+  return (
+    exec?.persistent !== undefined &&
+    !node.requested &&
+    node.surfaced !== true &&
+    exec.sandbox === undefined &&
+    exec.remote !== false &&
+    exec.interactive !== true
+  )
+}
+
+/** The persistent tasks `node` depends on through groups and servers, each after its own. */
+function serversBehind(nodes: ReadonlyMap<string, TaskNode>, node: TaskNode): TaskNode[] {
+  const out: TaskNode[] = []
+  const seen = new Set<string>()
+  const visit = (id: string): void => {
+    if (seen.has(id)) return
+    seen.add(id)
+    const dep = nodes.get(id)
+    if (dep === undefined) return
+    const server = dep.config.exec?.persistent !== undefined
+    if (!server && !isGroupTask(dep)) return
+    for (const d of dep.deps) visit(d)
+    if (server) out.push(dep)
+  }
+  for (const d of node.deps) visit(d)
+  return out
 }
 
 /**
  * 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
+ * hit here (C-2). Such a task runs here, or on a `runtime` executor, which
+ * fails it where its probes answer otherwise. Its dependants are not pinned with
  * it: they fold the probe through its input key, and their own output does
  * not depend on this machine's runtime.
  */
@@ -131,6 +177,10 @@ export interface Placements {
   remoteOnlyNoop: Set<string>
   /** `'only'` tasks a remote executor DID take — executed remotely, outputs stay remote. */
   remoteOnly: Set<string>
+  /** Each task placed on a `servers` executor → the persistent tasks it starts there. */
+  servers: Map<string, TaskNode[]>
+  /** Persistent tasks every dependant of which carries them: never started here. */
+  carried: Set<string>
 }
 
 /**
@@ -156,12 +206,27 @@ export function placeTasks(
   nodes: Map<string, TaskNode>,
   executors: readonly TaskExecutor[],
 ): Placements {
-  const pinned = pinnedLocalSet(nodes)
+  // Each executor's pins, computed only when one reads them.
+  const pins = new Map<string, Set<string>>()
+  const pinsOf = (e: Pick<TaskExecutor, 'sandbox' | 'servers' | 'runtime'>): Set<string> => {
+    const k = `${e.sandbox === true}${e.servers === true}${e.runtime === true}`
+    let set = pins.get(k)
+    if (set === undefined) {
+      set = pinnedLocalSet(nodes, e.sandbox !== true, e.servers === true, e.runtime !== true)
+      pins.set(k, set)
+    }
+    return set
+  }
+  const pinned = pinsOf({})
   const placements: Placements = {
     executors: new Map(),
     remoteOnlyNoop: new Set(),
     remoteOnly: new Set(),
+    servers: new Map(),
+    carried: new Set(),
   }
+  /** Persistent tasks a dependant placed off a `servers` executor needs here. */
+  const heldHere = new Set<string>()
   // `resolveExecutors` puts it last in every list.
   const floor = executors.find(isLocalExecutor)!
   for (const node of nodes.values()) {
@@ -181,8 +246,14 @@ export function placeTasks(
         cacheable: node.config.cache !== undefined,
       },
       executorLabel,
+      (e) => pinsOf(e).has(node.id),
     )
     placements.executors.set(node.id, executor)
+    const servers = serversBehind(nodes, node)
+    if (servers.length > 0) {
+      if (executor.servers === true) placements.servers.set(node.id, servers)
+      else for (const s of servers) heldHere.add(s.id)
+    }
     if (node.config.exec?.remote === 'only') {
       // A pinned 'only' task (it transitively depends on a persistent one)
       // lands here too: pinning wins, so it noops rather than shipping.
@@ -190,6 +261,8 @@ export function placeTasks(
       else placements.remoteOnlyNoop.add(node.id)
     }
   }
+  for (const servers of placements.servers.values())
+    for (const s of servers) if (!heldHere.has(s.id)) placements.carried.add(s.id)
   return placements
 }
 
@@ -220,6 +293,8 @@ export async function planExecutorOf(
       cacheDir: prepared.cacheDir,
       warn: warnOf(log),
       concurrency: machineParallelism(),
+      artifacts: taskArtifacts(prepared.cache, prepared.workspaceRoot),
+      cacheFacts: () => cacheFacts(prepared.remotes, prepared.cacheRefs),
     })
   } catch (err) {
     warnOf(log)(

package/src/orchestrator/plan.ts

@@ -54,6 +54,8 @@ export interface PlannedTask {
    * eager task is the default and saying so on every line says nothing.
    */
   download?: 'deferred'
+  /** A remote hit's stored size, when the remote said it: what restoring it downloads. */
+  remoteBytes?: number
   /** Why `--affected` kept this requested task; absent without `--affected` and on a dependency it pulled in. */
   affected?: AffectedReason
 }
@@ -139,6 +141,7 @@ export interface PlanArgs {
  */
 export async function plan(args: PlanArgs): Promise<RunPlan> {
   const cacheStatusById = new Map<string, CacheStatus>()
+  const remoteBytesById = new Map<string, number>()
   // 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>()
@@ -191,13 +194,15 @@ export async function plan(args: PlanArgs): Promise<RunPlan> {
     },
   })
   if (probed.size > 0) {
-    await args.cache.remoteHasMany?.([...new Set(probed.values())])
+    const infos = 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',
       )
+      const size = where === 'remote' ? infos?.get(hash)?.size : undefined
+      if (size !== undefined) remoteBytesById.set(id, size)
     }
   }
 
@@ -225,6 +230,7 @@ export async function plan(args: PlanArgs): Promise<RunPlan> {
       deps: node.deps,
       ...(executor !== undefined ? { executor } : {}),
       ...(args.downloadOf?.(id) === 'deferred' ? { download: 'deferred' as const } : {}),
+      ...(remoteBytesById.has(id) ? { remoteBytes: remoteBytesById.get(id)! } : {}),
     })
   }
 

package/src/orchestrator/plugin-host.ts

@@ -9,7 +9,6 @@
 
 import path from 'node:path'
 import {
-  type BranchScope,
   type Cache,
   type CacheLayer,
   type CachePolicy,
@@ -428,11 +427,12 @@ export interface ScheduleRun {
 export async function applyScheduleHooks(
   plugins: readonly VxPlugin[],
   nodes: ReadonlyMap<string, TaskNode>,
-  ctx: Omit<ScheduleHookContext, 'cache' | 'refine'>,
+  ctx: Omit<ScheduleHookContext, 'cache' | 'refine' | 'onRefine'>,
   cacheFor: (plugin: string) => PluginCache = () => absentPluginCache,
   run: ScheduleRun = {},
 ): Promise<ReadonlyMap<string, number>> {
   const sets: (ReadonlyMap<string, number> | undefined)[] = []
+  const listeners: { plugin: VxPlugin; i: number; listener: () => void }[] = []
   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)
@@ -449,8 +449,21 @@ export async function applyScheduleHooks(
         return
       }
       run.refined(merged())
+      for (const l of listeners) {
+        if (l.i === i) continue
+        try {
+          l.listener()
+        } catch (err) {
+          ctx.warn(
+            `[vx] plugin '${l.plugin.name}' failed in onRefine: ${err instanceof Error ? err.message : String(err)}`,
+          )
+        }
+      }
+    }
+    const onRefine = (listener: () => void): void => {
+      if (run.refined !== undefined) listeners.push({ plugin, i, listener })
     }
-    const own = { ...ctx, cache: cacheFor(plugin.name), refine }
+    const own = { ...ctx, cache: cacheFor(plugin.name), refine, onRefine }
     const call = (): Promise<ReadonlyMap<string, number> | undefined> =>
       safe(plugin, 'schedule', () => plugin.schedule!(nodes, own))
     const weights = await (run.step === undefined
@@ -556,10 +569,10 @@ export interface CacheHost extends CacheContext {
   readonly policy: CachePolicy
   /** Filled with each remote and what its policy lets it do, for the plugins' `ctx.cache`. */
   readonly remotes?: ResolvedRemote[]
-  /** The run's branch scope, which picks each remote key. */
-  readonly branch?: BranchScope
   /** Uploads at once, per remote (`cache.concurrency.upload`). */
   readonly uploadConcurrency?: number
+  /** What another machine's run lent, by plugin: each plugin's `ctx.lent`. */
+  readonly lentBy?: () => Readonly<Record<string, string>> | undefined
 }
 
 /**
@@ -574,10 +587,12 @@ export async function resolveCache(
   plugins: readonly VxPlugin[],
   host: CacheHost,
 ): Promise<CacheLayer> {
-  const { localCache, policy, remotes, branch, uploadConcurrency, ...ctx } = host
+  const { localCache, policy, remotes, uploadConcurrency, lentBy, ...base } = host
   const resolved: ResolvedRemote[] = []
   for (const plugin of plugins) {
     if (plugin.cache === undefined) continue
+    const ctx: CacheContext =
+      lentBy === undefined ? base : { ...base, lent: () => lentBy()?.[plugin.name] }
     const remote = await safe(plugin, 'cache', () => plugin.cache!(ctx))
     if (remote === undefined) continue
     assertShape(plugin, 'cache', remote, REMOTE_CACHE_METHODS, 'a remote cache layer')
@@ -593,7 +608,7 @@ export async function resolveCache(
   }
   return resolved.length === 0
     ? localCache
-    : new LayeredCache(localCache, resolved, branch, uploadConcurrency)
+    : new LayeredCache(localCache, resolved, uploadConcurrency)
 }
 
 /** The plugin each resolved executor came from, so a hook of it that throws is named. */