@vzn/vx 0.0.16 → 0.0.21

package/src/orchestrator/miss-save.ts

@@ -0,0 +1,169 @@
+// What a MISS leaves behind once the command exited 0 and the task will
+// save: the declared outputs resolved, the artifact and its rows saved in
+// one transaction, the whole-subtree output prefixes recorded for the
+// next hit's skip-restore, and the exact written paths marked against the
+// git snapshot so a same-project consumer re-spawns git only when its
+// globs can see them. Stale-hit-critical: a line moved here changes what
+// a later run replays. Moved out of execute-task.ts 2026-09-09 as pure
+// code motion.
+
+import path from 'node:path'
+import {
+  type CacheLayer,
+  type GitFilesCache,
+  resolveOutputs,
+  resolveWorkspaceOutputs,
+} from '../cache/index.js'
+import type { TaskNode } from '../graph/index.js'
+import { span, wholeSubtreePrefixes } from '../util/index.js'
+import type { Logger } from './logger.js'
+import type { TaskInputComponent } from './task-hash.js'
+
+/** A snapshot request for `recordOutputDirs`, taken at run end. */
+export interface OutputDirSnapshot {
+  hash: string
+  projectDir: string
+  prefixes: readonly string[]
+}
+
+export interface SaveMissArgs {
+  node: TaskNode
+  hash: string
+  cache: CacheLayer
+  log: Logger
+  workspaceRoot: string
+  nestedProjectDirs: string[]
+  gitFilesCache?: GitFilesCache | undefined
+  /** Declared `cache.outputs.files` / `.workspaceFiles`. */
+  outputs: string[]
+  wsOutputs: string[]
+  /** The Tier-3 input fingerprint rows captured by the pre-exec describe. */
+  captured: readonly TaskInputComponent[]
+  command: string
+  durationMs: number
+  stdout: string
+  /** The execution's usage, when the runner reported it — rides the artifact's sidecar. */
+  cpuMs?: number | undefined
+  peakRssBytes?: number | undefined
+  /** When present, the directory snapshot is queued here instead of taken now. */
+  outputDirSnapshots?: OutputDirSnapshot[] | undefined
+  /**
+   * When present, the cache save itself runs off the execution slot: the
+   * outputs are resolved and the git snapshot marked here, in the slot
+   * (a same-project downstream task reads both), and the pack + write +
+   * index go to the run's save lane (save-lane.ts).
+   */
+  deferSave?: ((save: () => Promise<void>) => Promise<void>) | undefined
+}
+
+/** `landed` settles when the entry is in the cache — at once without a lane. */
+export async function saveMiss(a: SaveMissArgs): Promise<{ landed: Promise<void> }> {
+  const { node, cache, log } = a
+  const endResolve = span('miss: resolve outputs')
+  const outputFiles = await resolveOutputs({
+    projectDir: node.projectDir,
+    outputs: a.outputs,
+    nestedProjectDirs: a.nestedProjectDirs,
+  })
+  const wsOutputFiles = await resolveWorkspaceOutputs({
+    workspaceRoot: a.workspaceRoot,
+    outputs: a.wsOutputs,
+  })
+  endResolve()
+  // The mirror of the input warning: declared outputs that resolve to
+  // nothing save an empty artifact, and the next hit "restores" it —
+  // the build that ran nowhere looks like a build that ran. `files: []`
+  // is a deliberate cached no-op and says nothing; a glob that matched
+  // nothing is a glob against the wrong directory.
+  if (
+    a.outputs.length + a.wsOutputs.length > 0 &&
+    outputFiles.length + wsOutputFiles.length === 0
+  ) {
+    log.status(
+      `[vx] ${node.id}: cache.outputs matched no files (${[...a.outputs, ...a.wsOutputs].join(', ')}) — ` +
+        `an empty artifact is saved; a later hit restores nothing`,
+    )
+  }
+  const save = async (): Promise<void> => {
+    const endSave = span('miss: save')
+    // Tier-3 input fingerprint: the digest rows captured by the pre-exec
+    // describe above, persisted with the entry inside `cache.save`'s
+    // transaction. Miss path only — the warm/hit path never reaches here.
+    await cache.save({
+      hash: a.hash,
+      projectDir: node.projectDir,
+      outputFiles,
+      ...(wsOutputFiles.length > 0
+        ? { workspaceOutputFiles: wsOutputFiles, workspaceRoot: a.workspaceRoot }
+        : {}),
+      inputComponents: a.captured.map((c) => ({ entryHash: a.hash, ...c })),
+      // No `exitCode`: the save only runs under `effectiveExitCode === 0`, and
+      // the contract no longer accepts one — so the invariant is enforced by
+      // the type rather than by every call site remembering the gate.
+      entry: {
+        taskId: node.id,
+        command: a.command,
+        durationMs: a.durationMs,
+        stdout: a.stdout,
+        ...(a.cpuMs !== undefined ? { cpuMs: a.cpuMs } : {}),
+        ...(a.peakRssBytes !== undefined ? { peakRssBytes: a.peakRssBytes } : {}),
+      },
+    })
+    endSave()
+    // The directory snapshot behind the next hit's skip-restore. Taken at
+    // run end when the run keeps a list: the task wrote these directories
+    // milliseconds ago, inside the snapshot's racy window, so a snapshot
+    // taken here was refused and the next hit walked every output tree —
+    // 1,000 walks, 296 ms accumulated, on the first warm run after a cold
+    // build of the 1,000-project bench (2026-09-10).
+    const savedDirPrefixes = wholeSubtreePrefixes(a.outputs)
+    if (savedDirPrefixes !== null) {
+      if (a.outputDirSnapshots !== undefined) {
+        a.outputDirSnapshots.push({
+          hash: a.hash,
+          projectDir: node.projectDir,
+          prefixes: savedDirPrefixes,
+        })
+      } else {
+        await cache.recordOutputDirs?.(a.hash, node.projectDir, savedDirPrefixes)
+      }
+    }
+  }
+  // This task just wrote outputs to the project's tree. Record the
+  // exact declared-output paths as changed (same as the cache-hit
+  // restore path) instead of dropping the whole snapshot: a downstream
+  // same-project task then re-spawns git ONLY when its input globs can
+  // actually see one of these paths. On a 1000-package cold run this
+  // removes ~one synchronous `git ls-files` spawn per project (the
+  // single largest cold-run cost — 22% of CPU in profiling). Contract:
+  // outputs must be declared — an executed task that writes files
+  // outside `cache.outputs.files` which a same-project downstream task
+  // reads is undeclared behavior (the restore path already assumes it).
+  if (outputFiles.length > 0) {
+    a.gitFilesCache?.markOutputsChanged(
+      node.projectDir,
+      outputFiles.map((p) => path.relative(node.projectDir, p).split(path.sep).join('/')),
+    )
+  }
+  // Declared workspace outputs may have landed inside OTHER
+  // projects' dirs (no-boundary escape hatch) — mark the exact
+  // paths against every partition that can see them.
+  if (wsOutputFiles.length > 0) {
+    a.gitFilesCache?.markWorkspaceOutputsChanged(
+      a.workspaceRoot,
+      wsOutputFiles.map((f) => path.relative(a.workspaceRoot, f).split(path.sep).join('/')),
+    )
+  }
+  // The workspace-wide partition (when one exists) spans this
+  // project's subtree, so it inherits the same "undeclared writes
+  // are only visible to git" rule as the project drop above.
+  if (outputFiles.length + wsOutputFiles.length > 0) {
+    a.gitFilesCache?.invalidateWorkspacePartition()
+  }
+  // Off the slot when the run keeps a lane (the save lane bounds and
+  // drains it); in the slot otherwise — an embedder without a lane gets
+  // the entry before the outcome.
+  if (a.deferSave !== undefined) return { landed: a.deferSave(save) }
+  await save()
+  return { landed: Promise.resolve() }
+}

package/src/orchestrator/options.ts

@@ -8,6 +8,7 @@ import type { TaskOutcome } from '../graph/index.js'
 import type { EventBus } from './events.js'
 import type { TelemetrySink } from './telemetry.js'
 import type { Logger } from './logger.js'
+import type { ProjectEntry } from '../workspace/index.js'
 
 export interface RunOptions {
   cwd: string
@@ -19,6 +20,16 @@ export interface RunOptions {
    */
   tasks: readonly string[]
   projects?: string[]
+  /**
+   * Configs a selection pass in this same process already loaded and
+   * staged with the same `cacheDir` and `frozen` (the CLI walks every
+   * `pkg#task` edge for `--filter 'app...'` and `--affected`). The run
+   * seeds and scopes as it always does and reuses these entries instead
+   * of evaluating and staging them again. One run only — never carry a
+   * map across runs, a config can change between them (`vx watch` drops
+   * it per cycle).
+   */
+  staged?: ReadonlyMap<string, ProjectEntry>
   concurrency?: number
   /**
    * Cache directory override (`--cache-dir <path>`). Absolute, or relative
@@ -34,6 +45,13 @@ export interface RunOptions {
    * both reads false (re-execute, still refresh the cache).
    */
   cache?: CachePolicy
+  /**
+   * The caller asked for a remote axis by name (`--cache=remote:rw`). With
+   * no cache plugin supplying a remote layer the axes are inert, and a CI
+   * job that believes it is filling a shared cache deserves one line
+   * saying it is not.
+   */
+  remoteRequested?: boolean
   /**
    * CI mode: load configs FROM the committed vx-lock.json instead of
    * evaluating them (frozen-env reproducibility). Requires the lock
@@ -46,11 +64,26 @@ export interface RunOptions {
   /**
    * Explicit per-task output volume for the default logger. ALWAYS
    * overrides the flow default. 'full': frames for work + one-liners
-   * for quiet hits. 'errors-only': only failed tasks print. 'none':
+   * for quiet hits. 'errors-only': only failed tasks print.
+   * 'hash-only': one line per task — outcome, id, cache key — with no
+   * log output (Turbo parity). 'none':
    * no per-task output at all. Status lines (header, summary) always
    * print.
    */
-  outputLogs?: 'full' | 'errors-only' | 'none'
+  outputLogs?: 'full' | 'errors-only' | 'none' | 'hash-only'
+  /**
+   * Where a REMOTELY-executed task's outputs land. 'all' (default):
+   * every task's outputs are downloaded to this machine as it completes
+   * — today's behaviour, byte for byte. 'toplevel': only the tasks you
+   * REQUESTED land here; intermediates stay remote. 'none': outputs stay
+   * in the remote CAS and are fetched lazily, only when a locally-placed
+   * task in the run actually needs them (Bazel's "build without the
+   * bytes").
+   * Pure transfer tuning: it can never change what a command produces,
+   * so it is NEVER folded into a cache key: it is a RunOption, not config.
+   * Locally-placed tasks always write in place and ignore this.
+   */
+  download?: 'all' | 'toplevel' | 'none'
   /**
    * Run intent, derived by the CLI from selection flags: 'broad' iff
    * `--all` / `--filter` / `--affected` was passed, else 'focused'.
@@ -67,24 +100,6 @@ export interface RunOptions {
    * the same run with and without `--retry` derives identical keys.
    */
   retries?: number
-  /**
-   * Cache-correctness verification (`vx run --verify`). When set, an
-   * executed + cacheable task is re-run after its save and its outputs are
-   * content-compared: a divergence means the task is non-hermetic and its
-   * cache entry is provably unsafe (see docs/design/cache-correctness).
-   * `fingerprint` computes + ships an output-tree fingerprint on executed
-   * tasks (no re-run — the cross-machine diff feed; `--verify`/`=all` set
-   * it too, for free). `allow` (from `--verify-allow=<pkg#task>,…`) exempts
-   * known-nondeterministic tasks from failing the run. A pure side-channel —
-   * never folded into a cache key; the re-run never saves. Undefined = off
-   * (a plain run is byte-identical).
-   */
-  verify?: {
-    determinism: boolean
-    inputs: boolean
-    fingerprint: boolean
-    allow: ReadonlySet<string>
-  }
   /**
    * Run-level default task timeout (ms), for tasks that declare no
    * `exec.timeout`. Highest of the run-level defaults: `--timeout` /
@@ -94,14 +109,6 @@ export interface RunOptions {
    * cached), so a `--timeout` run cache-hits a plain run's entry.
    */
   timeout?: number
-  /**
-   * Memory budget (bytes) that per-task `exec.resources.memory`
-   * reservations pack against (`--memory <size>`). Defaults to
-   * `os.totalmem()` — override it in cgroup-limited containers, where
-   * totalmem() reports the HOST's RAM, not the limit. A per-run
-   * scheduling knob only — never folded into any cache key.
-   */
-  memory?: number
   /**
    * Failure propagation: 'never' stops dispatch on the first failure
    * (in-flight tasks finish; everything queued skips), 'deps-ok'
@@ -139,18 +146,32 @@ export interface RunOptions {
    * exit the process out from under it.
    */
   handleSignals?: boolean
+  /**
+   * Abort the run from outside. On `abort` every live and persistent
+   * child is SIGTERMed, given the kill grace, then SIGKILLed; nothing
+   * further is dispatched; run() returns with the killed tasks and the
+   * never-started ones `aborted`. The seam for an embedder that owns its
+   * process's lifetime instead of `handleSignals` — the watch loop aborts
+   * its in-flight cycle on SIGINT/SIGTERM this way, so a cancellation
+   * never orphans a cycle's children.
+   */
+  signal?: AbortSignal
   log?: Logger
   /**
    * Inject the run's event bus. When provided, the orchestrator emits
    * onto it instead of creating its own — letting a caller subscribe a
-   * surface (e.g. the `--ui` devframe dev server) BEFORE the run starts
-   * emitting. The terminal renderer is still attached as a subscriber, so
+   * surface BEFORE the run starts emitting. This IS the surface seam:
+   * core ships the bus and the serializable `WireEvent`, and whatever
+   * renders them lives outside. (It used to name a `--ui` devframe dev
+   * server; no such flag exists, and core's devframe adapter was removed
+   * on 2026-08-26 — one consumer's adapter is not core's job.) The terminal renderer is still attached as a subscriber, so
    * default output is unchanged. Default: a fresh internal bus.
    */
   bus?: EventBus
   /**
    * Shared in-flight execution registry, keyed by task hash. Supplied by a
-   * long-lived service (`vx serve`) so concurrent runs DEDUP work: a task
+   * long-lived embedder (a daemon built on the façade; core ships none) so
+   * concurrent runs DEDUP work: a task
    * already executing for one run is awaited by another (which then
    * restores the just-saved artifact from cache) instead of re-running.
    * A stateless `vx run` passes none and is byte-identical to before.
@@ -165,8 +186,8 @@ export interface RunOptions {
   /**
    * Additional observe-only telemetry sinks, merged with whatever the
    * workspace plugins contribute. The embedder seam: a host executing
-   * runs on behalf of others (a serve recording delegated runs
-   * into its ingest store) attaches a sink without needing a workspace
+   * runs on behalf of others (a daemon recording delegated runs
+   * into its own store) attaches a sink without needing a workspace
    * plugin. Undefined → zero cost, identical to before; the telemetry
    * host's zero-sink invariant still applies when both sources are
    * empty.
@@ -182,7 +203,7 @@ export interface RunOptions {
   /**
    * An injected remote cache layer — the embedder seam mirroring
    * `telemetrySinks`: a host that already holds a wire client (a
-   * distribution agent, a serve executing on behalf of a submitter)
+   * distribution agent, a daemon executing on behalf of a submitter)
    * passes it here and run() composes `LayeredCache(local, injected)`.
    * Explicit injection WINS over the plugin `cache` capability (the
    * host knows best; prevents double-wrapping when the workspace also

package/src/orchestrator/persistent.ts

@@ -0,0 +1,79 @@
+// End-of-run disposition of persistent children (dev servers, watchers).
+// `executeTask` spawns them and returns at "ready" without awaiting exit;
+// 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 type { TaskNode } from '../graph/index.js'
+import { killGraceMs } from '../util/index.js'
+
+type Child = ReturnType<typeof Bun.spawn>
+
+/**
+ * Grace after SIGTERMing the dependency-only persistent tasks before
+ * force-killing any that trap or ignore it — so a wedged mock server can't
+ * hang a normal run at completion. Well-behaved servers exit far under
+ * this, so the happy path never waits it out.
+ */
+export const PERSISTENT_SHUTDOWN_GRACE_MS = 2000
+
+export interface KeepAlive {
+  nodes: TaskNode[]
+  children: Child[]
+}
+
+/**
+ * A persistent task the user REQUESTED (or one surfaced for display) is the
+ * run's whole purpose — it is left running and blocked on at the very end,
+ * after the summary. Only in the real CLI foreground: a custom logger or
+ * `handleSignals: false` (watch mode, embedders) expects `run()` to return,
+ * not to sit on a server.
+ */
+export function selectKeepAlive(
+  registry: ReadonlyMap<string, Child>,
+  nodes: ReadonlyMap<string, TaskNode>,
+  foreground: boolean,
+): KeepAlive {
+  const out: KeepAlive = { nodes: [], children: [] }
+  if (!foreground) return out
+  for (const [id, child] of registry) {
+    const n = nodes.get(id)
+    if (n !== undefined && (n.requested || n.surfaced === true)) {
+      out.nodes.push(n)
+      out.children.push(child)
+    }
+  }
+  return out
+}
+
+/**
+ * SIGTERM every persistent child not kept alive and wait for them, bounded:
+ * SIGTERM gives well-behaved servers (vite, next, esbuild --watch) a moment
+ * to clean up; past the grace the stragglers are SIGKILLed so the run's
+ * normal completion cannot hang on one that traps the signal. Bun's
+ * `kill` is idempotent on an exited child; the timer is cleared and
+ * unref'd so a fast shutdown never delays CLI exit.
+ */
+export async function shutdownPersistent(
+  registry: ReadonlyMap<string, Child>,
+  keepAlive: readonly Child[],
+  graceMs: number = killGraceMs(PERSISTENT_SHUTDOWN_GRACE_MS),
+): Promise<void> {
+  const kept = new Set(keepAlive)
+  const dying = [...registry.values()].filter((c) => !kept.has(c))
+  if (dying.length === 0) return
+  for (const child of dying) child.kill('SIGTERM')
+  const allExited = Promise.allSettled(dying.map((c) => c.exited))
+  let graceTimer: ReturnType<typeof setTimeout> | undefined
+  const winner = await Promise.race([
+    allExited.then(() => 'exited' as const),
+    new Promise<'grace'>((resolve) => {
+      graceTimer = setTimeout(() => resolve('grace'), graceMs)
+      graceTimer.unref?.()
+    }),
+  ])
+  if (graceTimer !== undefined) clearTimeout(graceTimer)
+  if (winner === 'grace') {
+    for (const child of dying) child.kill('SIGKILL')
+    await allExited
+  }
+}

package/src/orchestrator/placement.ts

@@ -0,0 +1,182 @@
+// 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, or says `exec.remote: false`; everything
+// else asks the executors in declaration order, and the local floor takes
+// what nothing claimed.
+
+import { machineParallelism } from '../util/index.js'
+import { 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 { resolveExecutors } from './plugin-host.js'
+import type { prepareRun } from './prepare.js'
+
+/**
+ * A task is pinned to this machine when it is persistent, transitively
+ * depends on a persistent task (a worker cannot reach a port on the
+ * submitter), or declares `exec.remote: false`.
+ */
+export function pinnedLocalSet(nodes: Map<string, TaskNode>): Set<string> {
+  const pinned = new Set<string>()
+  const memo = new Map<string, boolean>()
+  const visit = (id: string): boolean => {
+    const known = memo.get(id)
+    if (known !== undefined) return known
+    const node = nodes.get(id)
+    if (node === undefined) return false
+    memo.set(id, false) // cycle guard; the graph builder already rejects cycles
+    const result =
+      node.config.exec?.persistent !== undefined ||
+      node.config.exec?.remote === false ||
+      node.deps.some((d) => visit(d))
+    memo.set(id, result)
+    if (result) pinned.add(id)
+    return result
+  }
+  for (const id of nodes.keys()) visit(id)
+  return pinned
+}
+
+export interface Placements {
+  executors: Map<string, TaskExecutor>
+  /**
+   * `exec.remote: 'only'` tasks that no REMOTE executor took — a NO-OP on
+   * this machine: never executed, declared outputs never cleaned or
+   * restored. The task exists to produce a remote input tree; without a
+   * remote pool, dependents use the machine's ambient state exactly as they
+   * did before the field existed.
+   */
+  remoteOnlyNoop: Set<string>
+  /** `'only'` tasks a remote executor DID take — executed remotely, outputs stay remote. */
+  remoteOnly: Set<string>
+}
+
+export function placeTasks(
+  nodes: Map<string, TaskNode>,
+  executors: readonly TaskExecutor[],
+  pinAllLocal = false,
+): Placements {
+  const pinned = pinnedLocalSet(nodes)
+  const placements: Placements = {
+    executors: new Map(),
+    remoteOnlyNoop: new Set(),
+    remoteOnly: new Set(),
+  }
+  for (const node of nodes.values()) {
+    if (isGroupTask(node) || node.config.exec?.persistent !== undefined) continue
+    const executor = selectExecutor(executors, {
+      taskId: node.id,
+      projectName: node.projectName,
+      projectDir: node.projectDir,
+      command: node.config.exec!.command,
+      pinnedLocal: pinAllLocal || pinned.has(node.id),
+      cacheable: node.config.cache !== undefined,
+    })
+    placements.executors.set(node.id, executor)
+    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.
+      if (executor.remote === true) placements.remoteOnly.add(node.id)
+      else placements.remoteOnlyNoop.add(node.id)
+    }
+  }
+  return placements
+}
+
+/**
+ * `executorOf` for `planRun`, or nothing. Declining plugins, a single
+ * executor, or a resolution error all yield nothing: `--dry` is an
+ * inspection command and must not fail over a label. The error is still
+ * said, on the status line, in the plugin's name: the run this plan
+ * previews would refuse on it, and a plan that hid that would read as
+ * "everything lands locally".
+ */
+export async function planExecutorOf(
+  prepared: Awaited<ReturnType<typeof prepareRun>>,
+  log: Logger,
+  policy: 'all' | 'toplevel' | 'none',
+): Promise<{
+  executorOf?: (id: string) => string | undefined
+  downloadOf?: (id: string) => 'eager' | 'deferred' | 'never' | undefined
+  downloadDowngrades?: ReadonlyArray<{ taskId: string; reason: string }>
+}> {
+  let executors: readonly TaskExecutor[]
+  try {
+    executors = await resolveExecutors(prepared.plugins, {
+      workspaceRoot: prepared.workspaceRoot,
+      cacheDir: prepared.cacheDir,
+      warn: (m: string) => log.status(m),
+      concurrency: machineParallelism(),
+    })
+  } catch (err) {
+    log.status(
+      `[vx] placement not shown — ${err instanceof Error ? err.message : String(err)} (the run would refuse on it)`,
+    )
+    return {}
+  }
+  const placements = placeTasks(prepared.nodes, executors)
+  // Download modes need placement regardless of how many executors there
+  // are (a single REMOTE one still defers); executor LABELS only earn their
+  // column when there is a choice to report.
+  const download =
+    policy === 'all'
+      ? undefined
+      : resolveDownloadModes({
+          nodes: prepared.nodes,
+          policy,
+          localPlaced: new Set(
+            [...prepared.nodes.keys()].filter(
+              (id) => placements.executors.get(id)?.remote !== true,
+            ),
+          ),
+          remoteOnly: placements.remoteOnly,
+        })
+  return {
+    ...(executors.length < 2
+      ? {}
+      : {
+          executorOf: (id: string) =>
+            placements.remoteOnlyNoop.has(id) ? 'noop' : placements.executors.get(id)?.name,
+        }),
+    ...(download === undefined
+      ? {}
+      : {
+          downloadOf: (id: string) => download.modeOf.get(id),
+          downloadDowngrades: [...download.downgrades].map(([taskId, reason]) => ({
+            taskId,
+            reason,
+          })),
+        }),
+  }
+}
+
+/**
+ * Stands in for the executor of a task that was never placed — a group task
+ * (runs nothing) or a persistent one (`executePersistentTask` owns it and
+ * never reads this field). It THROWS rather than silently picking some
+ * executor from the list, so a refactor that routes such a task through the
+ * exec path fails loudly instead of shipping a localhost server to a worker.
+ */
+export const UNPLACED_EXECUTOR: TaskExecutor = {
+  name: 'unplaced',
+  execute: (req) => {
+    throw new Error(`internal error: ${req.taskId} reached an executor without being placed`)
+  },
+}
+
+export function hasPooledExecutor(executors: readonly TaskExecutor[]): boolean {
+  return executors.some((e) => e.capacity !== undefined)
+}
+
+export function poolOfPlacement(
+  placements: Placements,
+): (id: string) => { name: string; capacity: number } | undefined {
+  return (id) => {
+    const executor = placements.executors.get(id)
+    return executor?.capacity === undefined
+      ? undefined
+      : { name: executor.name, capacity: executor.capacity }
+  }
+}