@vzn/vx 0.0.646 → 0.0.648

package/src/orchestrator/placement.ts

@@ -5,10 +5,11 @@
 // 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
-// floor takes what nothing claimed.
+// floor takes what nothing claimed. An `exclusive` executor lifts every
+// pin and leaves the floor nothing: a task that would land here refuses.
 
 import { machineParallelism, UserError } from '../util/index.js'
-import { isLocalExecutor, selectExecutor, type TaskExecutor } from '../exec/index.js'
+import { hostPlatform, isLocalExecutor, selectExecutor, type TaskExecutor } from '../exec/index.js'
 import { isGroupTask, type TaskNode } from '../graph/index.js'
 import { resolveDownloadModes } from './download-policy.js'
 import { type Logger, warnOf } from '../report/index.js'
@@ -34,13 +35,16 @@ export function pinnedLocalSet(
   servers = false,
   /** `false` for a `runtime` executor: it checks the probes where it runs the task. */
   runtime = true,
+  /** For an `exclusive` executor: it takes what pins elsewhere, servers included. */
+  exclusive = false,
 ): Set<string> {
   const pinned = new Set<string>()
   for (const node of nodes.values()) {
     if (
-      (node.config.exec?.persistent !== undefined && !(servers && carriable(node))) ||
-      (sandbox && node.config.exec?.sandbox !== undefined) ||
-      node.config.exec?.remote === false
+      (node.config.exec?.persistent !== undefined && !(servers && carriable(node, exclusive))) ||
+      (!exclusive &&
+        ((sandbox && node.config.exec?.sandbox !== undefined) ||
+          node.config.exec?.remote === false))
     ) {
       pinned.add(node.id)
     }
@@ -71,17 +75,17 @@ export function pinnedLocalSet(
 /**
  * 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`.
+ * (this machine's machinery) and no `exec.remote: false`, which an
+ * `exclusive` executor takes all the same.
  */
-function carriable(node: TaskNode): boolean {
+function carriable(node: TaskNode, exclusive = false): boolean {
   const exec = node.config.exec
   return (
     exec?.persistent !== undefined &&
     !node.requested &&
     node.surfaced !== true &&
-    exec.sandbox === undefined &&
-    exec.remote !== false &&
-    exec.interactive !== true
+    (exclusive ||
+      (exec.sandbox === undefined && exec.remote !== false && exec.interactive !== true))
   )
 }
 
@@ -154,6 +158,17 @@ export function terminalHolders(nodes: Map<string, TaskNode>, tty: boolean): Set
     stack.push(...nodes.get(id)!.deps)
   }
   const clash = [...holders].filter((id) => id !== server && !before.has(id))
+  // One that runs after the server cannot run before it: the advice to make
+  // the server depend on it wrote a cycle.
+  const after = clash.filter((id) => reaches(nodes, id, server))
+  if (after.length > 0) {
+    const one = after.length === 1
+    throw new UserError(
+      `${server} is persistent and interactive, so it holds the terminal until the run ends, ` +
+        `and ${after.join(', ')}, which ${one ? 'depends' : 'depend'} on it, would ask for it too: ` +
+        `run ${one ? 'it' : 'them'} on ${one ? 'its' : 'their'} own`,
+    )
+  }
   if (clash.length > 0) {
     throw new UserError(
       `${server} is persistent and interactive, so it holds the terminal until the run ends, ` +
@@ -165,6 +180,20 @@ export function terminalHolders(nodes: Map<string, TaskNode>, tty: boolean): Set
   return holders
 }
 
+/** Does `from` depend on `to`, directly or through others? */
+function reaches(nodes: Map<string, TaskNode>, from: string, to: string): boolean {
+  const seen = new Set<string>()
+  const stack = [...nodes.get(from)!.deps]
+  while (stack.length > 0) {
+    const id = stack.pop()!
+    if (id === to) return true
+    if (seen.has(id)) continue
+    seen.add(id)
+    stack.push(...(nodes.get(id)?.deps ?? []))
+  }
+  return false
+}
+
 export interface Placements {
   executors: Map<string, TaskExecutor>
   /**
@@ -181,6 +210,16 @@ export interface Placements {
   servers: Map<string, TaskNode[]>
   /** Persistent tasks every dependant of which carries them: never started here. */
   carried: Set<string>
+  /**
+   * Tasks whose `exec.platforms` leave out this machine, placed here: the
+   * run skips them and their dependants. Each → its platforms.
+   */
+  otherPlatform: Map<string, readonly string[]>
+  /**
+   * Of those, the ones an executor that routes by platform could not take:
+   * none of its `platforms` is theirs. Each → the platforms on offer.
+   */
+  unroutable: Map<string, readonly string[]>
 }
 
 /**
@@ -208,33 +247,88 @@ export function placeTasks(
 ): Placements {
   // 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}`
+  const pinsOf = (
+    e: Pick<TaskExecutor, 'sandbox' | 'servers' | 'runtime' | 'exclusive'>,
+  ): Set<string> => {
+    const k = `${e.sandbox === true}${e.servers === true}${e.runtime === true}${e.exclusive === true}`
     let set = pins.get(k)
     if (set === undefined) {
-      set = pinnedLocalSet(nodes, e.sandbox !== true, e.servers === true, e.runtime !== true)
+      set = pinnedLocalSet(
+        nodes,
+        e.sandbox !== true,
+        e.servers === true,
+        e.runtime !== true,
+        e.exclusive === 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(),
+    otherPlatform: new Map(),
+    unroutable: new Map(),
+  }
+  const host = hostPlatform()
+  /** Runs `node` here: on this machine's platform, or skipped if it is not one of its. */
+  const here = (node: TaskNode): void => {
+    const wants: readonly string[] | undefined = node.config.exec?.platforms
+    if (wants === undefined) return
+    if (wants.includes(host)) node.platform = host
+    else placements.otherPlatform.set(node.id, wants)
   }
   /** 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)!
+  // The floor alone takes every task and starts no server: nothing to pin or
+  // select. The walks below were 2.8 ms of a 1,200-task warm run.
+  if (executors.length === 1 && executors[0] === floor) {
+    for (const node of nodes.values()) {
+      delete node.platform
+      if (isGroupTask(node)) continue
+      here(node)
+      if (node.config.exec?.persistent !== undefined) continue
+      placements.executors.set(node.id, floor)
+      if (node.config.exec?.remote === 'only') placements.remoteOnlyNoop.add(node.id)
+    }
+    return placements
+  }
+  const pinned = pinsOf({})
+  const routers = executors.filter((e) => e.platforms !== undefined)
+  const sole = executors.find((e) => e.exclusive === true)
+  /** A task an `exclusive` executor leaves to this machine: the run refuses. */
+  const refuse = (id: string, why: string): never => {
+    throw new UserError(
+      `${id} would run on this machine, and ${executorLabel(sole!)} runs every task elsewhere: ${why}`,
+    )
+  }
+  // A server it cannot carry first: one asked for pins its dependants, and
+  // the run named a dependant, as folding a runtime probe (2026-10-24).
+  if (sole !== undefined)
+    for (const node of nodes.values())
+      if (
+        node.config.exec?.persistent !== undefined &&
+        !(sole.servers === true && carriable(node, true))
+      )
+        refuse(node.id, 'it starts a server only beside a task that needs it')
   for (const node of nodes.values()) {
+    delete node.platform
     if (isGroupTask(node) || node.config.exec?.persistent !== undefined) continue
-    if (node.config.exec?.interactive === true) {
+    if (node.config.exec?.interactive === true && sole === undefined) {
       placements.executors.set(node.id, floor)
+      here(node)
+      // Its servers run here with it: carried, none started under it.
+      for (const s of serversBehind(nodes, node)) heldHere.add(s.id)
       continue
     }
+    const wants: readonly string[] | undefined = node.config.exec?.platforms
+    const routes = (e: TaskExecutor): boolean =>
+      wants === undefined || e.platforms?.some((p) => wants.includes(p)) === true
     const executor = selectExecutor(
       executors,
       {
@@ -246,9 +340,33 @@ export function placeTasks(
         cacheable: node.config.cache !== undefined,
       },
       executorLabel,
-      (e) => pinsOf(e).has(node.id),
+      (e) => pinsOf(e).has(node.id) || !routes(e),
     )
+    if (sole !== undefined && executor === floor) {
+      refuse(
+        node.id,
+        pinsOf(sole).has(node.id)
+          ? 'its key includes a runtime probe, which it does not check'
+          : routes(sole)
+            ? 'it declined the task'
+            : `it offers ${sole.platforms?.join(', ') ?? 'no platform'}, and exec.platforms asks for ${wants!.join(', ')}`,
+      )
+    }
     placements.executors.set(node.id, executor)
+    if (wants !== undefined) {
+      const offered = executor.platforms
+      if (offered !== undefined && routes(executor)) {
+        node.platform =
+          wants.includes(host) && offered.includes(host)
+            ? host
+            : wants.find((p) => offered.includes(p))!
+      } else {
+        here(node)
+        if (placements.otherPlatform.has(node.id) && routers.length > 0) {
+          placements.unroutable.set(node.id, [...new Set(routers.flatMap((e) => e.platforms!))])
+        }
+      }
+    }
     const servers = serversBehind(nodes, node)
     if (servers.length > 0) {
       if (executor.servers === true) placements.servers.set(node.id, servers)
@@ -263,6 +381,11 @@ export function placeTasks(
   }
   for (const servers of placements.servers.values())
     for (const s of servers) if (!heldHere.has(s.id)) placements.carried.add(s.id)
+  for (const node of nodes.values()) {
+    if (node.config.exec?.persistent === undefined || placements.carried.has(node.id)) continue
+    if (sole !== undefined) refuse(node.id, 'it starts a server only beside a task that needs it')
+    here(node)
+  }
   return placements
 }
 
@@ -275,16 +398,20 @@ export function placeTasks(
  * 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".
+ * "everything lands locally". The tasks `exec.platforms` skip here ride
+ * along, and a platform refusal (CI, an executor that cannot route) throws
+ * as the run's does.
  */
 export async function planExecutorOf(
   prepared: Awaited<ReturnType<typeof prepareRun>>,
   log: Logger,
   policy: 'all' | 'toplevel' | 'none',
+  ci: boolean,
 ): Promise<{
   executorOf?: (id: string) => string | undefined
   downloadOf?: (id: string) => 'eager' | 'deferred' | 'never' | undefined
   downloadDowngrades?: ReadonlyArray<{ taskId: string; reason: string }>
+  otherPlatform?: ReadonlyMap<string, readonly string[]>
 }> {
   let executors: readonly TaskExecutor[]
   try {
@@ -303,6 +430,9 @@ export async function planExecutorOf(
     return {}
   }
   const placements = placeTasks(prepared.nodes, executors)
+  // What the run refuses on, the plan refuses on: on CI a skip fails the run.
+  const platforms = platformVerdict(placements, ci)
+  if (platforms !== undefined && 'refuse' in platforms) throw new UserError(platforms.refuse)
   // 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.
@@ -316,6 +446,7 @@ export async function planExecutorOf(
           remoteOnly: placements.remoteOnly,
         })
   return {
+    ...(placements.otherPlatform.size > 0 ? { otherPlatform: placements.otherPlatform } : {}),
     ...(executors.length < 2 && placements.remoteOnlyNoop.size === 0
       ? {}
       : {
@@ -380,3 +511,40 @@ export function poolOfPlacement(
     return executor === undefined ? undefined : pools.get(executor)
   }
 }
+
+/**
+ * What a run says of its `otherPlatform` tasks: a refusal when an executor
+ * that routes by platform could not take one, or the run is on CI (each
+ * task runs there or the run fails, 2026-10-23), else the warning a
+ * local run prints as it skips them and what depends on them.
+ */
+export function platformVerdict(
+  placements: Placements,
+  ci: boolean,
+): { refuse: string } | { warn: string } | undefined {
+  const skipped = placements.otherPlatform
+  if (skipped.size === 0) return undefined
+  const host = hostPlatform()
+  const needs = (id: string): string => `${id} needs ${skipped.get(id)!.join(' or ')}`
+  if (placements.unroutable.size > 0) {
+    const offered = [...new Set([...placements.unroutable.values()].flat())]
+    return {
+      refuse:
+        `no executor runs ${placements.unroutable.size === 1 ? 'this task' : 'these tasks'} on a platform ${placements.unroutable.size === 1 ? 'it lists' : 'they list'} ` +
+        `(this machine is ${host}; executors run ${offered.join(', ')}):\n` +
+        [...placements.unroutable.keys()].map((id) => `  ${needs(id)}`).join('\n') +
+        `\ngive the executor a worker of each platform listed`,
+    }
+  }
+  if (ci) {
+    return {
+      refuse:
+        `on CI every task runs or the run fails, and ${skipped.size === 1 ? 'this task' : 'these tasks'} cannot run on ${host}:\n` +
+        [...skipped.keys()].map((id) => `  ${needs(id)}`).join('\n') +
+        `\nrun a target that holds only ${host} tasks, or one DTE run with a worker of each platform`,
+    }
+  }
+  return {
+    warn: `[vx] skipped on ${host}, with what depends on them: ${[...skipped.keys()].map(needs).join('; ')}`,
+  }
+}

package/src/orchestrator/plan.ts

@@ -17,8 +17,9 @@ import { ranNoCache } from '../report/index.js'
 import { idleServers, isGroupTask, runGraph, type TaskNode } from '../graph/index.js'
 import type { AffectedReason } from './affected-tasks.js'
 import type { HistoryProvider } from '../history/index.js'
+import { hostPlatform } from '../exec/index.js'
 import { computeGroupKey, computeTaskHash } from './task-hash.js'
-import { keyedOutcome, keyUpstream } from './upstream.js'
+import { dependedOn, keyedOutcome, keylessServer, keyUpstream } from './upstream.js'
 
 export type CacheStatus =
   | 'hit-local' // entry exists in local cache
@@ -27,6 +28,7 @@ export type CacheStatus =
   | 'no-cache' // task opts out of caching (no `cache` block) or --no-cache
   | 'group' // no `exec`; just an aggregator
   | 'not-started' // a server every dependant of which restores early: the run never spawns it
+  | 'skipped' // `exec.platforms` leave this machine out, or a task it depends on is skipped
 
 export interface PlannedTask {
   node: TaskNode
@@ -58,6 +60,10 @@ export interface PlannedTask {
   remoteBytes?: number
   /** Why `--affected` kept this requested task; absent without `--affected` and on a dependency it pulled in. */
   affected?: AffectedReason
+  /** A `skipped` task's own platforms, and this machine's. */
+  otherPlatform?: { readonly needs: readonly string[]; readonly host: string }
+  /** A `skipped` task's root: the task off this machine's platform it depends on. */
+  blockedBy?: string
 }
 
 /**
@@ -121,10 +127,13 @@ export interface PlanArgs {
   executorOf?: (id: string) => string | undefined
   /**
    * The tasks the run's short-circuit would restore ahead of their deps on
-   * a local hit (stable key, no workspace-output reach). A server whose
-   * every dependant is one of those and a local hit is never spawned.
+   * a hit (stable key, no workspace-output reach). A server whose every
+   * dependant is one of those and a hit, local or remote, is never spawned:
+   * the run holds it for the remote's answer (`held-servers.ts`).
    */
   restorable?: ReadonlySet<string>
+  /** Tasks whose `exec.platforms` leave this machine out (`placement.ts`), each → its platforms. */
+  otherPlatform?: ReadonlyMap<string, readonly string[]>
 }
 
 /**
@@ -145,6 +154,7 @@ export async function plan(args: PlanArgs): Promise<RunPlan> {
   // Keyed first, probed after: a remote that can batch (`hasMany`) is
   // asked once for every key, one that cannot is asked per key.
   const probed = new Map<string, string>()
+  const depended = dependedOn(args.nodes.values())
 
   const outcomes = await runGraph({
     nodes: args.nodes,
@@ -170,7 +180,7 @@ export async function plan(args: PlanArgs): Promise<RunPlan> {
         return keyedOutcome(node, await computeGroupKey(hashArgs))
       }
 
-      const hash = await computeTaskHash(hashArgs)
+      const hash = keylessServer(node, depended) ? undefined : await computeTaskHash(hashArgs)
 
       // Prediction keys off READS: a no-read policy re-executes every task,
       // so nothing is probed. Whether that run is a miss or no cache at all
@@ -181,7 +191,7 @@ export async function plan(args: PlanArgs): Promise<RunPlan> {
       const policy = args.cachePolicy ?? FULL_CACHE_POLICY
       const reads = policy.localRead || policy.remoteRead
       let status: CacheStatus
-      if (ranNoCache({ node, cacheOff: cachesNothing(policy) })) {
+      if (hash === undefined || ranNoCache({ node, cacheOff: cachesNothing(policy) })) {
         status = 'no-cache'
       } else if (!reads) {
         status = 'miss'
@@ -208,7 +218,10 @@ export async function plan(args: PlanArgs): Promise<RunPlan> {
 
   if (args.restorable !== undefined) {
     const restoreTier = new Set(
-      [...args.restorable].filter((id) => cacheStatusById.get(id) === 'hit-local'),
+      [...args.restorable].filter((id) => {
+        const status = cacheStatusById.get(id)
+        return status === 'hit-local' || status === 'hit-remote'
+      }),
     )
     const dependents = new Map<string, string[]>()
     for (const node of args.nodes.values())
@@ -217,6 +230,7 @@ export async function plan(args: PlanArgs): Promise<RunPlan> {
       cacheStatusById.set(id, 'not-started')
   }
 
+  const skips = platformSkips(args.nodes, args.otherPlatform)
   const tasks: PlannedTask[] = []
   for (const id of args.nodes.keys()) {
     const o = outcomes.get(id)
@@ -226,11 +240,12 @@ export async function plan(args: PlanArgs): Promise<RunPlan> {
     tasks.push({
       node,
       hash: o.hash ?? '',
-      cacheStatus: cacheStatusById.get(id) ?? 'no-cache',
+      cacheStatus: skips.has(id) ? 'skipped' : (cacheStatusById.get(id) ?? 'no-cache'),
       deps: node.deps,
       ...(executor !== undefined ? { executor } : {}),
       ...(args.downloadOf?.(id) === 'deferred' ? { download: 'deferred' as const } : {}),
       ...(remoteBytesById.has(id) ? { remoteBytes: remoteBytesById.get(id)! } : {}),
+      ...skips.get(id),
     })
   }
 
@@ -258,6 +273,48 @@ export async function plan(args: PlanArgs): Promise<RunPlan> {
   return { tasks, ...downgradeField(args) }
 }
 
+/**
+ * What the run skips here, as its scheduler does: a task its `exec.platforms`
+ * leave this machine out of, and every task that depends on one, named by
+ * the root of the block. In every `--continue` mode: a skip is no failure.
+ */
+function platformSkips(
+  nodes: ReadonlyMap<string, TaskNode>,
+  otherPlatform: ReadonlyMap<string, readonly string[]> | undefined,
+): Map<string, Pick<PlannedTask, 'otherPlatform' | 'blockedBy'>> {
+  const skips = new Map<string, Pick<PlannedTask, 'otherPlatform' | 'blockedBy'>>()
+  if (otherPlatform === undefined || otherPlatform.size === 0) return skips
+  const host = hostPlatform()
+  const settled = new Set<string>()
+  const visit = (id: string): void => {
+    const stack = [id]
+    while (stack.length > 0) {
+      const top = stack[stack.length - 1]!
+      if (settled.has(top)) {
+        stack.pop()
+        continue
+      }
+      const node = nodes.get(top)!
+      const open = node.deps.filter((d) => !settled.has(d))
+      if (open.length > 0) {
+        stack.push(...open)
+        continue
+      }
+      stack.pop()
+      settled.add(top)
+      const needs = otherPlatform.get(top)
+      if (needs !== undefined) {
+        skips.set(top, { otherPlatform: { needs, host } })
+        continue
+      }
+      const via = node.deps.find((d) => skips.has(d))
+      if (via !== undefined) skips.set(top, { blockedBy: skips.get(via)!.blockedBy ?? via })
+    }
+  }
+  for (const id of nodes.keys()) visit(id)
+  return skips
+}
+
 /** Carried onto the plan only when the gate actually refused something. */
 function downgradeField(args: PlanArgs): {
   downloadDowngrades?: ReadonlyArray<{ taskId: string; reason: string }>