@vzn/vx 0.0.644 → 0.0.646

package/src/history/history.ts

@@ -30,6 +30,9 @@ export const PASS_STATUSES = `(${TASK_STATUSES.filter(isPassStatus)
   .map((s) => `'${s}'`)
   .join(', ')})`
 
+/** The share of a machine a task must use to have filled it. */
+const SATURATED = 0.9
+
 /** Per (project#task) — last RECENT runs collapsed into a summary. */
 export interface TaskHistory {
   /** Total runs in the recent window. */
@@ -58,6 +61,16 @@ export interface TaskHistory {
    * whole task. Undefined when no row carried both numbers.
    */
   maxCpuParallelism?: number
+  /**
+   * The most cores, and the most memory, of a machine an executor ran it
+   * on (`ExecuteResult.machine`) that it used all of: 90% of the cores
+   * over its whole run, or 90% of the memory. A burst to every core is
+   * not one: tasks beside it slow for a moment, and booking a machine for
+   * it left CI agents half idle (M, 2026-10-22). A
+   * task that filled a machine wanted a bigger one. Set by `resourcesFor`.
+   */
+  saturatedCores?: number
+  saturatedMemoryBytes?: number
 }
 
 /** Map keyed by `project#task`. */
@@ -66,7 +79,11 @@ export type HistoryTable = ReadonlyMap<string, TaskHistory>
 /** What a scheduler learns from a task's history: its p50 and its resource maxima. */
 export type TaskResources = Pick<
   TaskHistory,
-  'p50DurationMs' | 'maxPeakRssBytes' | 'maxCpuParallelism'
+  | 'p50DurationMs'
+  | 'maxPeakRssBytes'
+  | 'maxCpuParallelism'
+  | 'saturatedCores'
+  | 'saturatedMemoryBytes'
 >
 
 export interface HistoryProvider {
@@ -238,20 +255,38 @@ export class LocalHistoryProvider implements HistoryProvider {
 
   /**
    * Keep default-branch commit `sha`'s timings (task id → ms) as forecast
-   * rows: one per task, so a repeat import, by this worktree or another
-   * at once, adds nothing.
+   * rows, each with the task's measured need from `needs` when it has one
+   * (what `resourcesFor` answers for a task with no run here): one row per
+   * task, so a repeat import, by this worktree or another at once, adds
+   * nothing.
    */
-  importTimings(sha: string, timings: ReadonlyMap<string, number>): void {
+  importTimings(
+    sha: string,
+    timings: ReadonlyMap<string, number>,
+    needs: ReadonlyMap<string, TaskResources> = new Map(),
+  ): void {
     const insert = this.db.query(
-      `INSERT OR IGNORE INTO task_durations(project, task, source, sha, duration_ms, recorded_at)
-       VALUES (?, ?, 'remote', ?, ?, ?)`,
+      `INSERT OR IGNORE INTO task_durations(project, task, source, sha, duration_ms, recorded_at,
+         cpu_parallelism, peak_rss_bytes, saturated_cores, saturated_memory_bytes)
+       VALUES (?, ?, 'remote', ?, ?, ?, ?, ?, ?, ?)`,
     )
     const now = Date.now()
     this.db
       .transaction(() => {
         for (const [id, ms] of timings) {
           const [project, task] = splitTaskId(id)
-          insert.run(project, task, sha, Math.round(ms), now)
+          const n = needs.get(id)
+          insert.run(
+            project,
+            task,
+            sha,
+            Math.round(ms),
+            now,
+            n?.maxCpuParallelism ?? null,
+            n?.maxPeakRssBytes ?? null,
+            n?.saturatedCores ?? null,
+            n?.saturatedMemoryBytes ?? null,
+          )
         }
       })
       .immediate()
@@ -388,11 +423,88 @@ export class LocalHistoryProvider implements HistoryProvider {
         ...(cpu !== -Infinity ? { maxCpuParallelism: cpu } : {}),
       })
     }
+    // A failure counts: a task killed for memory filled its machine too.
+    type Saturated = { project: string; task: string; cores: number | null; memory: number | null }
+    const saturated = this.db
+      .query(
+        `SELECT project, task,
+           MAX(CASE WHEN cpu_ms * 1.0 / duration_ms >= ${SATURATED} * placement_cores
+                    THEN placement_cores END) AS cores,
+           MAX(CASE WHEN peak_rss_bytes >= ${SATURATED} * placement_memory
+                    THEN placement_memory END) AS memory
+         FROM runs
+         WHERE id >= ? AND placement_cores IS NOT NULL AND duration_ms > 0
+           AND status IN ('success', 'failed') AND (cache_hit IS NULL OR cache_hit = 0)
+         GROUP BY project, task`,
+      )
+      .all(floor) as Saturated[]
+    for (const row of saturated) {
+      const key = `${row.project}#${row.task}`
+      if (!wanted.has(key) || (row.cores === null && row.memory === null)) continue
+      out.set(key, {
+        ...(out.get(key) ?? { p50DurationMs: p50s.get(key) }),
+        ...(row.cores !== null ? { saturatedCores: row.cores } : {}),
+        ...(row.memory !== null ? { saturatedMemoryBytes: row.memory } : {}),
+      })
+    }
     // A forecast reads past the window: a task with none in it still has one.
     for (const [key, p50] of p50s) if (!out.has(key)) out.set(key, { p50DurationMs: p50 })
+    this.remoteNeeds(wanted, out)
     return out
   }
 
+  /**
+   * A task never measured here takes its need from the newest imported
+   * row that has one (`importTimings`): a fresh CI machine packs by what
+   * the default branch measured. One probe skips a store with none.
+   */
+  private remoteNeeds(wanted: ReadonlySet<string>, out: Map<string, TaskResources>): void {
+    const pending = [...wanted].filter((id) => out.get(id)?.maxCpuParallelism === undefined)
+    if (pending.length === 0) return
+    if (
+      this.db
+        .query(
+          `SELECT 1 FROM task_durations WHERE source = 'remote' AND cpu_parallelism IS NOT NULL LIMIT 1`,
+        )
+        .get() === null
+    )
+      return
+    const rows = this.db
+      .query(
+        `SELECT j.key AS i, d.cpu_parallelism AS cpu, d.peak_rss_bytes AS rss,
+           d.saturated_cores AS sc, d.saturated_memory_bytes AS sm
+         FROM json_each(?) AS j
+         JOIN task_durations d ON d.id = (
+           SELECT id FROM task_durations
+           WHERE project = j.value ->> 0 AND task = j.value ->> 1 AND source = 'remote'
+             AND cpu_parallelism IS NOT NULL
+           ORDER BY id DESC LIMIT 1)`,
+      )
+      .all(JSON.stringify(pending.map(splitTaskId))) as {
+      i: number
+      cpu: number
+      rss: number | null
+      sc: number | null
+      sm: number | null
+    }[]
+    for (const r of rows) {
+      const id = pending[r.i]!
+      const had = out.get(id)
+      out.set(id, {
+        p50DurationMs: had?.p50DurationMs,
+        maxCpuParallelism: r.cpu,
+        ...(r.rss !== null ? { maxPeakRssBytes: r.rss } : {}),
+        // A saturation measured here wins.
+        ...(r.sc !== null ? { saturatedCores: r.sc } : {}),
+        ...(r.sm !== null ? { saturatedMemoryBytes: r.sm } : {}),
+        ...(had?.saturatedCores !== undefined ? { saturatedCores: had.saturatedCores } : {}),
+        ...(had?.saturatedMemoryBytes !== undefined
+          ? { saturatedMemoryBytes: had.saturatedMemoryBytes }
+          : {}),
+      })
+    }
+  }
+
   /** The first `runs` id of the newest `recent` invocations (see `loadFor`). */
   private floor(): number {
     const row = this.db

package/src/history/metrics.ts

@@ -44,6 +44,12 @@ export interface RunSummaryRow {
   hash: string
   cpuMs: number | null
   peakRssBytes: number | null
+  /** The most cores one sampling interval burned (v43); null when nothing sampled. */
+  peakCores: number | null
+  /** The mean resident memory over the samples, in bytes (v43); null when nothing sampled. */
+  avgRssBytes: number | null
+  /** Where an executor ran it (`small#1`, v44); null = here. */
+  placement: string | null
   // High-precision spans relative to run start. Decimal strings on the wire
   // (bigints aren't JSON-safe); use BigInt or Number on the client.
   wallclockStartNs: string | null
@@ -114,6 +120,7 @@ export function listRuns(db: Database, args: ListRunsArgs = {}): RunSummaryRow[]
               duration_ms AS durationMs, started_at AS startedAt, ended_at AS endedAt,
               cache_hit AS cacheHit, restored, cached, hash,
               cpu_ms AS cpuMs, peak_rss_bytes AS peakRssBytes,
+              peak_cores AS peakCores, avg_rss_bytes AS avgRssBytes, placement,
               wallclock_start_ns AS wallclockStartNs, wallclock_end_ns AS wallclockEndNs,
               blocked_by AS blockedBy, timed_out AS timedOut,
               sandbox_violations AS sandboxViolations, not_ready AS notReady,
@@ -486,11 +493,19 @@ export function latestRunId(db: Database, taskId: string): string | null {
   return row?.runId ?? null
 }
 
+/** Why a key that folds a task with no `inputs` never hits, and the fix. */
+function keylessNote(taskId: string, keylessBy: string): string {
+  return keylessBy === taskId
+    ? 'never cached: this task declares no `inputs`, so each run derives a new key; declare its `inputs`'
+    : `never cached: its key folds ${keylessBy}, which declares no \`inputs\`, so each run derives a new key; declare inputs on ${keylessBy}`
+}
+
 export function whyDidThisRerun(db: Database, runId: string, taskId: string): WhyDidThisRerun {
   const [project, task] = splitTaskId(taskId)
   const this_ = db
     .query(
-      `SELECT id, hash, status, cache_hit AS cacheHit, restored, cached, started_at AS startedAt
+      `SELECT id, hash, status, cache_hit AS cacheHit, restored, cached, started_at AS startedAt,
+              keyless_by AS keylessBy
        FROM runs WHERE run_id = ? AND project = ? AND task = ?`,
     )
     .get(runId, project, task) as
@@ -502,6 +517,7 @@ export function whyDidThisRerun(db: Database, runId: string, taskId: string): Wh
         restored: number | null
         cached: number | null
         startedAt: number
+        keylessBy: string | null
       }
     | undefined
   if (!this_) {
@@ -563,17 +579,19 @@ export function whyDidThisRerun(db: Database, runId: string, taskId: string): Wh
         ? // Not a cache decision at all: the task runs every time by design,
           // and its key is derived only so dependents can fold it.
           'this task declares no `cache` block — it runs on every invocation; its key is folded by dependents only'
-        : prev && prev.hash !== this_.hash
-          ? 'cache key changed between the previous run and this one (inputs differ)'
-          : prev
-            ? // An unchanged key has two very different endings, and calling
-              // both a "re-run" answered the question wrong: a cache HIT did not
-              // re-run at all, so blaming `--no-cache` named a cause that cannot
-              // have applied. Only a run that EXECUTED on an unchanged key is
-              // the case this verb exists to explain. A row with no recorded
-              // cacheHit (older rows) is neither — say that, do not guess.
-              unchangedKeyNote(db, runId, this_, prev)
-            : 'no prior run for this (project, task)',
+        : this_.keylessBy !== null
+          ? keylessNote(taskId, this_.keylessBy)
+          : prev && prev.hash !== this_.hash
+            ? 'cache key changed between the previous run and this one (inputs differ)'
+            : prev
+              ? // An unchanged key has two very different endings, and calling
+                // both a "re-run" answered the question wrong: a cache HIT did not
+                // re-run at all, so blaming `--no-cache` named a cause that cannot
+                // have applied. Only a run that EXECUTED on an unchanged key is
+                // the case this verb exists to explain. A row with no recorded
+                // cacheHit (older rows) is neither — say that, do not guess.
+                unchangedKeyNote(db, runId, this_, prev)
+              : 'no prior run for this (project, task)',
   }
 }
 
@@ -688,10 +706,17 @@ export function cacheKeyDiff(db: Database, runId: string, taskId: string): Cache
   const [project, task] = splitTaskId(taskId)
   const this_ = db
     .query(
-      'SELECT id, hash, cached, status, started_at AS startedAt FROM runs WHERE run_id = ? AND project = ? AND task = ?',
+      'SELECT id, hash, cached, status, started_at AS startedAt, keyless_by AS keylessBy FROM runs WHERE run_id = ? AND project = ? AND task = ?',
     )
     .get(runId, project, task) as
-    | { id: number; hash: string; cached: number | null; status: string; startedAt: number }
+    | {
+        id: number
+        hash: string
+        cached: number | null
+        status: string
+        startedAt: number
+        keylessBy: string | null
+      }
     | undefined
   if (!this_) {
     return {
@@ -720,6 +745,18 @@ export function cacheKeyDiff(db: Database, runId: string, taskId: string): Cache
     }
   }
 
+  if (this_.keylessBy !== null) {
+    return {
+      runId,
+      taskId,
+      found: true,
+      previousRunId: null,
+      entries: [],
+      unchangedCount: 0,
+      note: `${this_.keylessBy} declares no \`inputs\`, so no fingerprints are kept to diff`,
+    }
+  }
+
   const prev = db
     .query(
       `SELECT run_id AS runId, hash, status FROM runs
@@ -809,8 +846,8 @@ export function cacheKeyDiff(db: Database, runId: string, taskId: string): Cache
       note:
         this_.cached === 0
           ? // The verdict already says the task is uncached; this line says
-            // what moved a key that declares nothing.
-            'no `cache` block declares its inputs, so its key folds every file in its project — a file it wrote, or any untracked file, moves it — and no fingerprints are kept to say which'
+            // why no input can be named.
+            'with no `cache` block it saves no entry, so no input fingerprints are kept to say which of its `inputs` moved its key; with no `inputs`, every run gives it a new key'
           : unsaved !== null
             ? `cache key changed but input fingerprints are unavailable — ${unsaved} and saved no entry; only the key change is known`
             : 'cache key changed but input fingerprints are unavailable — the entry was pruned (or the row predates the `cached` column); only the key change is known',

package/src/index.ts

@@ -83,8 +83,9 @@ export { Cache } from './cache/index.js'
 export type {
   CacheLayer,
   PluginCache,
+  ArtifactInfo,
+  LentAccess,
   RemoteCacheLayer,
-  RemoteKey,
   RemoteOpenContext,
   RunRecord,
   InvocationRecord,
@@ -163,6 +164,10 @@ export type {
   ExecutorContext,
   OutputContext,
   CommandContext,
+  ArtifactRun,
+  ArtifactTask,
+  CacheFacts,
+  TaskArtifacts,
   FingerprintChange,
   FingerprintClaim,
   FingerprintContext,
@@ -197,11 +202,21 @@ export { executorFallback } from './exec/index.js'
 // trailing comment or a template literal's closing newline lost the args
 // there while the local floor kept them (X-112).
 export { withForwardArgs } from './exec/index.js'
+// Core's local executor, sandbox included, for a plugin that runs tasks
+// itself: `@vzn/vx-dte`'s orchestrator and its agents.
+export { localFloor, type LocalFloor } from './orchestrator/index.js'
+// A task's sandbox request built where an agent runs it: the paths and the
+// walls are that machine's (`@vzn/vx-dte`, an orchestrator of another OS).
+export { sandboxRequestFor, type SandboxRequest } from './orchestrator/index.js'
+// A runtime probe answered where a `runtime` executor runs the task.
+export { answerRuntime } from './cache/index.js'
 export type {
   ExecuteRequest,
   ExecuteResult,
   ExecuteSandbox,
+  MachineReport,
   ResolvedSandboxConfig,
+  ServerSpec,
   TaskExecutor,
   TaskPlacement,
 } from './exec/index.js'

package/src/orchestrator/affected-tasks.ts

@@ -229,24 +229,6 @@ export function affectedRoots(
   return kept
 }
 
-/**
- * The tasks of `nodes` whose key the change can move (a branch's cache
- * scope, owner 2026-10-17): a changed path one of its inputs declares, a
- * whole project, or a task its closure holds. Unlike `--affected`, a path
- * no task declares (a README) reaches none: its key is the default
- * branch's, so it reads the default key.
- */
-export function keyedByChange(
-  nodes: ReadonlyMap<string, TaskNode>,
-  changes: AffectedChanges,
-  projects: ReadonlyMap<string, ProjectEntry>,
-  packageGraph: PackageGraph,
-): Set<string> {
-  return new Set(
-    affectedRoots(nodes, [...nodes.keys()], changes, projects, packageGraph, undefined, true),
-  )
-}
-
 /**
  * The requested tasks `--affected` keeps, in their order: one the user
  * named (`pkg#task`), one in a project another include selected outright

package/src/orchestrator/execute-args.ts

@@ -69,6 +69,9 @@ export function executeArgsOf(
     if (facts.downloadModeOf.get(id) === 'deferred') a.download = 'deferred'
     if (placements.remoteOnlyNoop.has(id)) a.remoteOnlyNoop = true
     if (placements.remoteOnly.has(id)) a.remoteOnly = true
+    if (placements.carried.has(id)) a.carried = true
+    const servers = placements.servers.get(id)
+    if (servers !== undefined) a.servers = servers
     if (probe !== undefined) a.preProbed = probe
     if (upfrontKey !== undefined) a.upfrontKey = upfrontKey
     if (upfrontGroupKey !== undefined) a.upfrontGroupKey = upfrontGroupKey

package/src/orchestrator/execute-task.ts

@@ -76,6 +76,7 @@ import { sandboxFix } from './sandbox-fix.js'
 // The hit path's entry stays importable from here (tests).
 export { restoreHit, type RestoreHitArgs } from './hit-restore.js'
 import type { DeferredOutputs } from './deferred-outputs.js'
+import type { TreeLoad } from './telemetry.js'
 import { type Logger, warnOf } from '../report/index.js'
 import {
   computeGroupHash,
@@ -94,6 +95,7 @@ import {
   forgetUndeclaredWrites,
   isAborted,
   taskBinDirs,
+  serverSpec,
   taskEnv,
   taskTimeoutMs,
 } from './task-process.js'
@@ -161,7 +163,7 @@ export interface ExecuteArgs {
    */
   liveChildren?: Set<ReturnType<typeof Bun.spawn>>
   /** Sample a spawned task's process tree (`TelemetrySource.track`); absent when nobody samples. */
-  track?: (taskId: string, pid: number) => () => void
+  track?: (taskId: string, pid: number) => () => TreeLoad | undefined
   /** Name what a missed key changed (`createMissExplainer`); absent when nobody listens. */
   explainMiss?: MissExplainer
   /**
@@ -270,6 +272,10 @@ export interface ExecuteArgs {
   noDependants?: true
   /** The task holds vx's terminal (`terminalHolders`): its stdio is vx's own. */
   terminal?: true
+  /** A persistent task every dependant of which starts it where it runs: never spawned here. */
+  carried?: true
+  /** The persistent tasks its `servers` executor starts where it runs it. */
+  servers?: readonly TaskNode[]
   /** When each command of the run ran and where it may write (command-windows.ts). */
   commandWindows?: CommandWindows
 }
@@ -498,8 +504,12 @@ async function executeCachedTask(args: ExecuteArgs): Promise<TaskOutcome> {
     filterUpstreamHashes(present, cfg.inputs?.tasks, node.projectName, node.id).map(([id]) => id),
   )
   const foldedTasks = expandGroupUpstream(present.filter((u) => folded.has(u.node.id)))
-  const keyless =
-    isKeyless(cfg) || foldedTasks.some((u) => u.keyless === true || isKeyless(u.node.config))
+  const keylessBy = isKeyless(cfg)
+    ? node.id
+    : foldedTasks
+        .map((u) => u.keylessBy ?? (isKeyless(u.node.config) ? u.node.id : undefined))
+        .find((id) => id !== undefined)
+  const keyless = keylessBy !== undefined
   const reads = policy.localRead || policy.remoteRead
   const willRead = !remoteOnly && cfgCacheable && !keyless && reads
   const willWrite = !remoteOnly && cfgCacheable && (policy.localWrite || policy.remoteWrite)
@@ -964,7 +974,7 @@ async function executeCachedTask(args: ExecuteArgs): Promise<TaskOutcome> {
         unlistenStop?.()
         unlistenStop = undefined
         flushMasked()
-        untrack?.()
+        load = untrack?.() ?? load
         untrack = undefined
       })
     endExec()
@@ -1088,7 +1098,9 @@ async function executeCachedTask(args: ExecuteArgs): Promise<TaskOutcome> {
   const storedOutput = (): string => encodeOutputLog(output?.chunks() ?? [])
   const failedAttempts: { endedAt: number; exitCode: number; timedOut?: true }[] = []
   // The sampling of the attempt's process tree, stopped once it settles.
-  let untrack: (() => void) | undefined
+  let untrack: (() => TreeLoad | undefined) | undefined
+  // What the last attempt's samples saw, for the run history.
+  let load: TreeLoad | undefined
   // The entry's command is shown by `vx why` and sent with the entry to a
   // remote cache: a value a config interpolated stays out of both.
   const storedCommand = secrets?.mask(step.command) ?? step.command
@@ -1160,6 +1172,7 @@ async function executeCachedTask(args: ExecuteArgs): Promise<TaskOutcome> {
         hash,
         wallclockStartNs,
         wallclockEndNs: process.hrtime.bigint() - args.runStartHrTimeNs,
+        ...(result.where !== undefined ? { where: result.where } : {}),
       }
     }
 
@@ -1225,12 +1238,16 @@ async function executeCachedTask(args: ExecuteArgs): Promise<TaskOutcome> {
       ...(cfgCacheable && !(policy.localRead || policy.remoteRead) ? { refresh: true } : {}),
       outputs: { files: outputs, workspaceFiles: wsOutputs },
       ...(args.terminal === true ? { terminal: true as const } : {}),
+      ...(args.servers === undefined
+        ? {}
+        : { servers: args.servers.map((s) => serverSpec(s, args.workspaceRoot)) }),
     }
     // The signal last: it arms a plugin's `exec.timeout`, and the sandbox's arming
     // below is vx's work, not the task's. Armed first, a 60 ms timeout
     // expired before the spawn and failed `echo` as timed out, unrun.
     if (!userSandbox) return { ...base, signal: requestSignal(local) }
-    await args.armSandbox?.()
+    // A remote executor enforces it where it runs the task.
+    if (args.executor.remote !== true) await args.armSandbox?.()
     const sb = await sandboxRequestFor(
       node,
       step.sandbox!,
@@ -1463,7 +1480,7 @@ async function executeCachedTask(args: ExecuteArgs): Promise<TaskOutcome> {
       : {}),
     ...(inputChanges !== undefined ? { inputChanges } : {}),
     ...(unkeyed ? { unkeyed: true as const } : {}),
-    ...(keyless ? { keyless: true as const } : {}),
+    ...(keylessBy !== undefined ? { keylessBy } : {}),
     ...(saved ? { saved: true as const } : {}),
     ...(effectiveExitCode !== 0 && output !== undefined
       ? { failedOutput: failedOutputLog(output, willSave || args.keepRun !== undefined) }
@@ -1477,7 +1494,11 @@ async function executeCachedTask(args: ExecuteArgs): Promise<TaskOutcome> {
     ...(movedFails !== undefined ? { inputMoved: movedFails } : {}),
     ...(result.cpuMs !== undefined ? { cpuMs: result.cpuMs } : {}),
     ...(result.peakRssBytes !== undefined ? { peakRssBytes: result.peakRssBytes } : {}),
+    ...(load !== undefined ? { peakCores: load.peakCores, avgRssBytes: load.avgRssBytes } : {}),
     ...(result.where !== undefined ? { where: result.where } : {}),
+    ...(result.where !== undefined && result.machine !== undefined
+      ? { whereCores: result.machine.cores, whereMemoryBytes: result.machine.memoryBytes }
+      : {}),
     ...(deferralRequested && result.outputs?.kind === 'deferred'
       ? { outputs: 'deferred' as const }
       : {}),

package/src/orchestrator/held-servers.ts

@@ -0,0 +1,86 @@
+// A server the run's local store cannot settle: some dependant missed here
+// but may be a hit the remote holds. The scheduler holds such a server
+// until the remote answers; when every dependant hit, the server never
+// starts (M 2026-10-22), as it never starts behind local hits.
+
+import type { TaskNode } from '../graph/index.js'
+import type { CacheEntry, CacheLayer } from '../cache/index.js'
+import type { ShortCircuit } from './local-shortcircuit.js'
+import { getContext } from './remote-prefetch.js'
+
+/** The persistent tasks nobody asked for whose every dependant is a local hit or a key the remote may hold. */
+export function serversToHold(
+  nodes: ReadonlyMap<string, TaskNode>,
+  restoreTier: ReadonlySet<string>,
+  remoteAsk: ReadonlyMap<string, string>,
+): Map<string, string[]> {
+  const out = new Map<string, string[]>()
+  if (remoteAsk.size === 0) return out
+  const dependents = new Map<string, string[]>()
+  for (const n of nodes.values())
+    for (const d of n.deps) {
+      const list = dependents.get(d)
+      if (list === undefined) dependents.set(d, [n.id])
+      else list.push(n.id)
+    }
+  for (const n of nodes.values()) {
+    if (n.config.exec?.persistent === undefined || n.requested || n.surfaced === true) continue
+    const ds = dependents.get(n.id)
+    if (
+      ds !== undefined &&
+      ds.every((d) => restoreTier.has(d) || remoteAsk.has(d)) &&
+      ds.some((d) => remoteAsk.has(d))
+    )
+      out.set(n.id, ds)
+  }
+  return out
+}
+
+/**
+ * For each held server, whether the remote holds every dependant: one
+ * `get` per dependant through the layered cache, which shares the
+ * prefetch's request. All hits join the restore tier at once, so the
+ * scheduler finds the server idle; the first miss answers at once, with
+ * nothing promoted, so the server starts without waiting on the rest.
+ */
+export function askRemote(
+  held: ReadonlyMap<string, readonly string[]>,
+  nodes: ReadonlyMap<string, TaskNode>,
+  shortCircuit: Pick<ShortCircuit, 'preProbed' | 'restoreTier' | 'remoteAsk'>,
+  cache: CacheLayer,
+): Map<string, Promise<readonly string[]>> {
+  const asked = new Map<string, Promise<CacheEntry | null>>()
+  const ask = (id: string): Promise<CacheEntry | null> => {
+    let p = asked.get(id)
+    if (p === undefined) {
+      const node = nodes.get(id)!
+      p = cache
+        .get(shortCircuit.remoteAsk.get(id)!, getContext(node, node.config.exec?.command ?? ''))
+        .catch(() => null)
+      asked.set(id, p)
+    }
+    return p
+  }
+  const out = new Map<string, Promise<readonly string[]>>()
+  for (const [server, ds] of held) {
+    const remote = ds.filter((d) => shortCircuit.remoteAsk.has(d))
+    out.set(
+      server,
+      new Promise((resolve) => {
+        const hits = new Map<string, CacheEntry>()
+        for (const d of remote)
+          void ask(d).then((hit) => {
+            if (hit === null) return resolve([])
+            hits.set(d, hit)
+            if (hits.size < remote.length) return
+            for (const [id, entry] of hits) {
+              shortCircuit.preProbed.set(id, { hash: shortCircuit.remoteAsk.get(id)!, hit: entry })
+              shortCircuit.restoreTier.add(id)
+            }
+            resolve(remote)
+          })
+      }),
+    )
+  }
+  return out
+}

package/src/orchestrator/hit-restore.ts

@@ -14,6 +14,8 @@ import {
   type CacheEntry,
   cleanOutputPaths,
   committedFiles,
+  OUTPUT_DIRS_OVER_CAP,
+  outputWalkTakes,
   resolveOutputs,
   resolveWorkspaceOutputs,
   sweepRestoreTemps,
@@ -27,7 +29,7 @@ import {
   span,
   splitNegations,
   taskGlob,
-  wholeSubtreePrefixes,
+  outputDirPrefixes,
 } from '../util/index.js'
 import type { ExecuteArgs } from './execute-task.js'
 import { entryHolds } from './miss-save.js'
@@ -202,7 +204,12 @@ export async function restoreHit(restore: RestoreHitArgs): Promise<TaskOutcome>
         // The walk ran and proved the tree current (rows absent, or a
         // directory had moved — a benign touch): snapshot the directories
         // so the next hit skips the walk.
-        if (skipRestore && !setKnown && dirPrefixes !== null) {
+        if (
+          skipRestore &&
+          !setKnown &&
+          dirPrefixes !== null &&
+          hit.outputDirRows?.some((r) => r.mtimeMs === OUTPUT_DIRS_OVER_CAP) !== true
+        ) {
           await args.cache.recordOutputDirs?.(hash, node.projectDir, dirPrefixes)
         }
       }
@@ -323,7 +330,7 @@ export async function restoreHit(restore: RestoreHitArgs): Promise<TaskOutcome>
         hash,
         projectDir: node.projectDir,
         prefixes: dirPrefixes,
-        holds: entryHolds(node),
+        holds: entryHolds(node, outputWalkTakes(node.projectDir, outputs, args.nestedProjectDirs)),
       })
     }
     // Restored outputs changed the project's tree — but on this
@@ -396,7 +403,7 @@ function dirPrefixesOf(outputs: readonly string[]): readonly string[] | null {
   const key = JSON.stringify(outputs)
   let prefixes = prefixMemo.get(key)
   if (prefixes === undefined) {
-    prefixes = wholeSubtreePrefixes(splitNegations(outputs).positive)
+    prefixes = outputDirPrefixes(splitNegations(outputs).positive)
     prefixMemo.set(key, prefixes)
   }
   return prefixes