@vzn/vx 0.0.645 → 0.0.646

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/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/plugin-host.ts

@@ -427,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)
@@ -448,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
@@ -557,6 +571,8 @@ export interface CacheHost extends CacheContext {
   readonly remotes?: ResolvedRemote[]
   /** 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
 }
 
 /**
@@ -571,10 +587,12 @@ export async function resolveCache(
   plugins: readonly VxPlugin[],
   host: CacheHost,
 ): Promise<CacheLayer> {
-  const { localCache, policy, remotes, 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')

package/src/orchestrator/plugin.ts

@@ -24,6 +24,7 @@ import { maskedLine, nearest, type PluginSecrets, SecretBroker, UserError } from
 import type { ProjectMeta } from '../workspace/index.js'
 import type { EventBus, Logger, RunStartInfo } from '../report/index.js'
 import type { CiContext } from './run-context.js'
+import type { CacheFacts, TaskArtifacts } from './task-artifacts.js'
 import type { TelemetryContext, TelemetrySink } from './telemetry.js'
 
 /**
@@ -334,6 +335,20 @@ export interface CommandContext extends BaseContext {
    * workspace's cache plugins supply, under the run's scope. Opened on first use.
    */
   readonly cache: PluginCache
+  /**
+   * Task entries by key in the workspace's cache, under a run's policy and
+   * scope (a laptop writes no remote unless the workspace's policy names
+   * it): what a verb that runs a run's tasks on this machine saves and
+   * restores through (`TaskArtifacts`). Opened on first use.
+   */
+  readonly artifacts: TaskArtifacts
+  /**
+   * `artifacts` read as another machine's run would read them: under its
+   * refs, with the access its remotes lent (`CacheFacts`, asked on each
+   * request, so a token it lends again replaces the last). Opened on first
+   * use; until `facts` answers, under this machine's own.
+   */
+  artifactsFor(facts: () => CacheFacts | undefined): TaskArtifacts
 }
 
 /** `config` runs before the cache dir is known — it may be what the hook changes. */
@@ -500,6 +515,13 @@ export interface ScheduleHookContext extends BaseContext {
    * from a remote). Ignored in a plan and once the run's tasks are done.
    */
   refine(weights: ReadonlyMap<string, number>): void
+  /**
+   * Calls `listener` each time another plugin `refine`s: the late data it
+   * waited for (timings fetched from a remote) has landed in history, so a
+   * plugin that read history in `schedule` may read it again. Never called
+   * in a plan.
+   */
+  onRefine(listener: () => void): void
 }
 
 /** A `cache` hook's context: the workspace and the run's scope, never the local store or the policy, which core owns. */
@@ -515,6 +537,13 @@ export interface CacheContext extends BaseContext {
    * keys or scopes its entries by them; core keys task entries by none.
    */
   readonly refs: readonly string[]
+  /**
+   * The token a run lent this plugin's remote (`RemoteCacheLayer.lend`),
+   * on a machine that runs that run's tasks (`CommandContext.artifactsFor`);
+   * undefined anywhere else. Read it per request: a run lends again before
+   * a token ends. A plugin uses it only when it has no access of its own.
+   */
+  readonly lent?: () => string | undefined
 }
 
 export interface OutputContext extends BaseContext {
@@ -527,6 +556,14 @@ export interface OutputContext extends BaseContext {
 export interface ExecutorContext extends BaseContext {
   /** The run's worker count — an executor that paces itself reads it here. */
   readonly concurrency: number
+  /** Task entries by key in the run's cache, for a task another machine ran (`TaskArtifacts`). */
+  readonly artifacts: TaskArtifacts
+  /**
+   * What a machine that runs this run's tasks reads the cache under
+   * (`CacheFacts`): the run's refs, and each remote's lent access, asked
+   * now. Ask again before `expiresAt`.
+   */
+  cacheFacts(): Promise<CacheFacts>
 }
 
 export interface PluginContext extends PluginSetupContext {

package/src/orchestrator/prepare.ts

@@ -116,6 +116,8 @@ export interface PreparedRun {
   cacheScope: string | undefined
   /** The run's remotes in declared order, as the policy gates each; `openRemotes` turns one off. */
   remotes: ResolvedRemote[]
+  /** The refs the run reads, in order (`CacheContext.refs`). */
+  cacheRefs: readonly string[]
   /**
    * Scheduling priorities from plugins' `schedule` stage (task id → weight,
    * merged over the structural baseline by the scheduler). Empty when no
@@ -494,6 +496,8 @@ export async function prepareRun(options: RunOptions, log: Logger): Promise<Prep
       onError: (err) => warnOf(log)(`[vx] remote cache: ${err.message}`),
     })
   }
+  // An injected remote is no plugin's: nothing reads refs for it.
+  const refs = options.remoteCache ? [] : cacheRefs(workspaceRoot, baseBranch)
   try {
     cache = options.remoteCache
       ? new LayeredCache(localCache, remotes, options.uploadConcurrency)
@@ -502,7 +506,7 @@ export async function prepareRun(options: RunOptions, log: Logger): Promise<Prep
           cacheDir,
           warn: warnOf(log),
           scope: cacheScope,
-          refs: cacheRefs(workspaceRoot, baseBranch),
+          refs,
           localCache,
           policy,
           remotes,
@@ -554,6 +558,7 @@ export async function prepareRun(options: RunOptions, log: Logger): Promise<Prep
       cachePolicy: policy,
       cacheScope,
       remotes,
+      cacheRefs: refs,
       keepRunEntry: undefined,
       priorities: () => Promise.resolve(new Map()),
       branch,
@@ -804,6 +809,7 @@ export async function prepareRun(options: RunOptions, log: Logger): Promise<Prep
       cachePolicy: policy,
       cacheScope,
       remotes,
+      cacheRefs: refs,
       priorities,
       branch,
       cacheFor,
@@ -915,7 +921,7 @@ function pruneToClosure(nodes: Map<string, TaskNode>, roots: ReadonlySet<string>
   }
 }
 
-const namesRemote = (spec: string | undefined): boolean =>
+export const namesRemote = (spec: string | undefined): boolean =>
   spec !== undefined && /remote:[rw]/.test(spec)
 
 /**
@@ -923,7 +929,9 @@ const namesRemote = (spec: string | undefined): boolean =>
  * since the grammar lives in the cache module the workspace module may not
  * import. Undefined when it names none.
  */
-function workspaceCachePolicy(config: WorkspaceConfig | null | undefined): CachePolicy | undefined {
+export function workspaceCachePolicy(
+  config: WorkspaceConfig | null | undefined,
+): CachePolicy | undefined {
   const spec = config?.cache?.policy
   if (spec === undefined) return undefined
   try {