@vzn/vx-dte 0.0.0 → 0.0.650

package/index.ts

@@ -0,0 +1,4 @@
+// Root entry shim: Bun 1.4.0's `--compile` binaries resolve an on-disk
+// package by `<pkg>/index.ts` and ignore package.json `exports` / `main`
+// (see packages/vx/index.ts). Same module as the exports map names.
+export * from './src/index.js'

package/package.json

@@ -1,8 +1,44 @@
 {
   "name": "@vzn/vx-dte",
-  "version": "0.0.0",
-  "description": "Placeholder; real releases are published by CI.",
+  "version": "0.0.650",
   "license": "MIT",
-  "repository": { "type": "git", "url": "git+https://github.com/vznjs/vx.git" },
-  "publishConfig": { "access": "public" }
+  "description": "Distributed task execution for vx: one run spread over workers your own CI spawns, joined through a relay.",
+  "keywords": [
+    "vx",
+    "monorepo",
+    "vx-plugin",
+    "distributed",
+    "ci"
+  ],
+  "type": "module",
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "exports": {
+    ".": {
+      "types": "./src/index.ts",
+      "import": "./src/index.ts"
+    }
+  },
+  "files": [
+    "index.ts",
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "bun": ">=1.4.4"
+  },
+  "dependencies": {
+    "@vzn/vx-dte-server": "0.0.650"
+  },
+  "peerDependencies": {
+    "@vzn/vx": "^0.0.650"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/vznjs/vx.git",
+    "directory": "packages/vx-dte"
+  },
+  "homepage": "https://github.com/vznjs/vx/tree/main/packages/vx-dte#readme",
+  "bugs": "https://github.com/vznjs/vx/issues"
 }

package/src/cpu-account.ts

@@ -0,0 +1,134 @@
+// Where a worker's machine spent its CPU while the worker served a run,
+// said once as it leaves, in its own log: its tasks, the worker itself, its
+// other children, and the processes that used the most besides. The run's
+// summary showed machines busier than their tasks (2.8 cores against 2.0,
+// 2026-10-24) and nothing said what the rest was.
+
+import { readFileSync } from 'node:fs'
+
+/** Each process's CPU so far by pid, with its name, from one `ps`. */
+export type ProcTable = Map<number, { name: string; ms: number }>
+
+export interface CpuAccount {
+  readonly onlineMs: number
+  /** Busy core-time of the whole machine over `onlineMs`, any process's. */
+  readonly machineMs: number
+  readonly tasksMs: number
+  readonly selfMs: number
+  /** Its reaped children's, less its tasks': Linux only. */
+  readonly childrenMs?: number | undefined
+  /** The processes that used the most while it served, its own tree aside. */
+  readonly top: readonly { name: string; ms: number }[]
+}
+
+/** `ps`'s `time`, `[[dd-]hh:]mm:ss[.cc]`, in ms; macOS may print a comma for the point. */
+export function psTime(s: string): number | undefined {
+  const dash = s.indexOf('-')
+  const days = dash === -1 ? 0 : Number(s.slice(0, dash))
+  const parts = s
+    .slice(dash + 1)
+    .replace(',', '.')
+    .split(':')
+    .map(Number)
+  if (parts.length < 2 || !Number.isFinite(days) || parts.some((n) => !Number.isFinite(n))) {
+    return undefined
+  }
+  return Math.round((days * 86_400 + parts.reduce((a, n) => a * 60 + n, 0)) * 1000)
+}
+
+export interface Ps {
+  readonly table: ProcTable
+  readonly parents: Map<number, number>
+}
+
+/** `ps -A -o pid=,ppid=,time=,comm=`, read. */
+export function parsePs(text: string): Ps {
+  const table: ProcTable = new Map()
+  const parents = new Map<number, number>()
+  for (const line of text.split('\n')) {
+    const m = /^\s*(\d+)\s+(\d+)\s+(\S+)\s+(.+?)\s*$/.exec(line)
+    if (m === null) continue
+    const ms = psTime(m[3]!)
+    if (ms === undefined) continue
+    // macOS prints the path it ran; Linux a name, a kernel thread's with a
+    // slash in it (`kworker/0:1`).
+    const name = /^[./]/.test(m[4]!) ? m[4]!.split('/').pop()! : m[4]!
+    table.set(Number(m[1]), { name, ms })
+    parents.set(Number(m[1]), Number(m[2]))
+  }
+  return { table, parents }
+}
+
+/** One `ps` of every process. Undefined where it fails. */
+export function readPs(): Ps | undefined {
+  try {
+    const r = Bun.spawnSync(['ps', '-A', '-o', 'pid=,ppid=,time=,comm='], { stderr: 'ignore' })
+    return r.exitCode === 0 ? parsePs(r.stdout.toString()) : undefined
+  } catch {
+    // quiet: no `ps`, no list of the rest
+    return undefined
+  }
+}
+
+/**
+ * The CPU each process used between two tables, by name, the most first:
+ * `self`'s tree left out (its tasks and itself are counted apart). A
+ * process gone by the second table is not seen.
+ */
+export function topBetween(
+  before: ProcTable,
+  after: Ps,
+  self: number,
+  n = 5,
+): { name: string; ms: number }[] {
+  const mine = (pid: number): boolean => {
+    // `self` asked before the stop at pid 1: docker() execs the worker as
+    // its container's init.
+    for (let p: number | undefined = pid, hops = 0; p !== undefined && hops < 64; hops++) {
+      if (p === self) return true
+      if (p <= 1) break
+      p = after.parents.get(p)
+    }
+    return false
+  }
+  const byName = new Map<string, number>()
+  for (const [pid, p] of after.table) {
+    if (mine(pid)) continue
+    const was = before.get(pid)
+    const ms = was !== undefined && was.name === p.name ? p.ms - was.ms : p.ms
+    if (ms > 0) byName.set(p.name, (byName.get(p.name) ?? 0) + ms)
+  }
+  return [...byName]
+    .map(([name, ms]) => ({ name, ms }))
+    .sort((a, b) => b.ms - a.ms)
+    .slice(0, n)
+}
+
+/** The CPU its reaped children used, from `/proc/self/stat` (`cutime`, `cstime`); undefined off Linux. */
+export function childrenCpuMs(
+  read: () => string = () => readFileSync('/proc/self/stat', 'utf8'),
+): number | undefined {
+  try {
+    const stat = read()
+    const f = stat.slice(stat.lastIndexOf(')') + 2).split(' ')
+    // USER_HZ is 100 on every Linux ABI.
+    return (Number(f[13]) + Number(f[14])) * 10
+  } catch {
+    // quiet: not Linux
+    return undefined
+  }
+}
+
+const cores = (ms: number, over: number): string => `${(ms / over).toFixed(2)} cores`
+
+export function describeCpu(a: CpuAccount): string {
+  const over = Math.max(1, a.onlineMs)
+  const parts = [
+    `machine ${cores(a.machineMs, over)}`,
+    `tasks ${cores(a.tasksMs, over)}`,
+    `this worker ${cores(a.selfMs, over)}`,
+    ...(a.childrenMs === undefined ? [] : [`its other children ${cores(a.childrenMs, over)}`]),
+  ]
+  const rest = a.top.map((p) => `${p.name} ${cores(p.ms, over)}`).join(', ')
+  return `cpu over ${(over / 1000).toFixed(1)}s: ${parts.join(' · ')}${rest === '' ? '' : ` · most besides: ${rest}`}`
+}

package/src/dispatch.ts

@@ -0,0 +1,268 @@
+// Which worker each waiting task goes to now: one rule for the live run
+// (`Orchestrator.pump`) and for the plan's play-out (`planner.ts`), so the
+// plan sizes the run the way the run packs it.
+
+import type { Strategy } from './strategy.js'
+
+/**
+ * `ids` (waiting, in the order they got ready) in the order `how` takes
+ * them. `tail`: each one's longest chain after it, its own ms included.
+ */
+export function ordered(
+  ids: readonly string[],
+  how: Strategy['order'],
+  tail: (id: string) => number,
+  need: (id: string) => Need,
+  cores: number,
+): string[] {
+  if (how === 'fifo') return [...ids]
+  const byTail = (x: string, y: string): number => tail(y) - tail(x)
+  if (how === 'critical-path') return [...ids].sort(byTail)
+  // Troublesome: within a quarter of the longest chain, or half a worker wide.
+  let longest = 0
+  for (const id of ids) longest = Math.max(longest, tail(id))
+  const hard = (id: string): boolean => tail(id) >= 0.75 * longest || need(id).cores >= cores / 2
+  return [...ids].sort((x, y) => Number(hard(y)) - Number(hard(x)) || byTail(x, y))
+}
+
+/** What a task asks of a worker: its history's cores and peak memory. */
+export interface Need {
+  readonly cores: number
+  readonly memory: number
+  /** It filled a machine this big last time: only a bigger one takes it, if any worker is. */
+  readonly above?: { readonly cores: number; readonly memory: number } | undefined
+  /** The platform it runs on (`ExecuteRequest.platform`): only a worker of it takes it. */
+  readonly platform?: string | undefined
+  /**
+   * What it counts for when the plan sizes the run, when that is not what
+   * it books: an unmeasured task books next to nothing, so it goes to any
+   * free core, but a run of only such tasks still asks enough workers.
+   */
+  readonly ask?: { readonly cores: number; readonly memory: number } | undefined
+}
+
+/** A worker as dispatch sees it: its size and what is in use on it now. */
+export interface Bin {
+  readonly id: string
+  readonly cores: number
+  readonly memory: number
+  /** Cores and memory in use: booked, or more when its load says more. */
+  readonly used: { cores: number; memory: number }
+  /** Tasks on it holding cores. */
+  running: number
+  /** Tasks whose outputs it holds. */
+  readonly has?: ReadonlySet<string>
+  /** Its machine's platform (`linux-x64`), as it reported or its size declares. */
+  readonly platform?: string | undefined
+}
+
+export interface Ask {
+  readonly id: string
+  readonly need: Need
+  /** Its dependencies, all the way up: a worker holding them is preferred. */
+  readonly up?: Iterable<string>
+  /** Names its need: asks of one kind fit and fail alike (`kindOf`). */
+  readonly kind?: string
+  /** The one bin that may take it: it holds files no cache does. */
+  readonly only?: string
+  /** A bin that may not take it. */
+  readonly avoid?: string
+}
+
+/** What `Ask.kind` names: every field of a need `assign` reads. */
+export function kindOf(need: Need): string {
+  return `${need.cores}\0${need.memory}\0${need.above?.cores}\0${need.above?.memory}\0${need.platform}`
+}
+
+/**
+ * Whether `need` fits on `bin` now: alone on an empty one, whatever it
+ * asks; beside others only in full, cores and memory. Beside others on a
+ * free core alone, main's workers booked 4.3 of 4 (2026-10-23).
+ */
+export function fits(bin: Bin, need: Need): boolean {
+  if (need.platform !== undefined && bin.platform !== need.platform) return false
+  if (bin.running === 0) return true
+  return (
+    need.cores < bin.cores &&
+    bin.used.cores + need.cores <= bin.cores + 1e-9 &&
+    bin.used.memory + need.memory <= bin.memory
+  )
+}
+
+/**
+ * Each of `asks`, in order, to the bin it fits now (`fits`): of those, the
+ * one holding most of its dependencies' outputs, then the one with fewest
+ * cores free, so workers fill before the next takes work and the rest
+ * fall idle and leave. A task bigger than every bin's last size goes to a
+ * bigger one only, unless none is or `waits(above, platform)` says one of its platform is coming.
+ * The first that fits nowhere but an empty bin holds the one using least: no task after it goes there, or later tasks fill it again and
+ * again (check.bun, the gate of 56 tasks, waited 50 s on main 871ffba).
+ * Bins' `used` and `running` count what is given. `all`, what the asks
+ * need all told (the least of each, and how many kinds), ends the pass
+ * once no bin takes the least or every kind failed since the last given:
+ * the rest change nothing.
+ */
+export function assign<B extends Bin>(
+  asks: Iterable<Ask>,
+  bins: readonly B[],
+  waits: (above: NonNullable<Need['above']>, platform: string | undefined) => boolean = () => false,
+  place: Strategy['place'] = 'best-fit',
+  all?: {
+    readonly floor: { readonly cores: number; readonly memory: number }
+    readonly kinds: number
+    /** Where it keeps the kinds spent, for the asks to skip them as it reads. */
+    readonly spent?: Set<string>
+    /** Where it keeps the bins' bounds as it gives, for the asks to skip each `dead` one as it reads. */
+    readonly bounds?: Bounds
+  },
+): Map<string, B> {
+  const out = new Map<string, B>()
+  const held = new Set<B>()
+  const bounds = all?.bounds
+  const rebound = (): void => {
+    if (bounds !== undefined) boundsOf(bins, held, bounds, all?.floor)
+  }
+  rebound()
+  // Kinds that failed and held nothing since a bin was last given a task:
+  // until one is, each ask of them fails alike.
+  const spent = all?.spent ?? new Set<string>()
+  spent.clear()
+  for (const ask of asks) {
+    if (
+      all !== undefined &&
+      (spent.size >= all.kinds || !bins.some((b) => !held.has(b) && fits(b, all.floor)))
+    )
+      break
+    if (ask.kind !== undefined && spent.has(ask.kind)) continue
+    const { need } = ask
+    const bigger = (b: B): boolean =>
+      need.above === undefined || b.cores > need.above.cores || b.memory > need.above.memory
+    const allowed =
+      ask.only === undefined && ask.avoid === undefined
+        ? bins
+        : bins.filter((b) => (ask.only === undefined || b.id === ask.only) && b.id !== ask.avoid)
+    const of =
+      need.platform === undefined ? allowed : allowed.filter((b) => b.platform === need.platform)
+    const anyBigger = of.some(bigger)
+    if (!anyBigger && need.above !== undefined && waits(need.above, need.platform)) {
+      if (ask.kind !== undefined) spent.add(ask.kind)
+      continue
+    }
+    const pool = anyBigger ? of.filter(bigger) : of
+    const up = ask.up === undefined ? [] : [...ask.up]
+    let best: B | undefined
+    let bestScore: [number, number] = [0, 0]
+    for (const b of pool) {
+      if (held.has(b) || !fits(b, need)) continue
+      let has = 0
+      for (const id of up) if (b.has?.has(id) === true) has++
+      const score: [number, number] = [has, fit(b, need, place, pool.indexOf(b))]
+      if (
+        best === undefined ||
+        score[0] > bestScore[0] ||
+        (score[0] === bestScore[0] && score[1] > bestScore[1])
+      ) {
+        best = b
+        bestScore = score
+      }
+    }
+    if (best === undefined) {
+      // One it fits only empty: the one using least is held for it.
+      let soonest: B | undefined
+      for (const b of pool) {
+        if (held.has(b) || b.running === 0) continue
+        if (need.cores < b.cores && need.memory <= b.memory - b.used.memory) continue
+        if (soonest === undefined || b.used.cores < soonest.used.cores) soonest = b
+      }
+      if (soonest !== undefined) {
+        held.add(soonest)
+        rebound()
+      } else if (ask.kind !== undefined) spent.add(ask.kind)
+      continue
+    }
+    spent.clear()
+    out.set(ask.id, best)
+    best.used.cores += Math.min(need.cores, best.cores)
+    best.used.memory += Math.min(need.memory, best.memory)
+    best.running++
+    rebound()
+  }
+  return out
+}
+
+/**
+ * The bins not held, as an ask `dead` reads them: one asked of nowhere
+ * fits it and holds nothing, so `assign` only spends its kind. With every
+ * task its own kind, a pass read each ready one to learn that: 2.4 million
+ * asks for a plan of 9000 (2026-10-25).
+ */
+export interface Bounds {
+  /** None takes the least any ask needs: the pass is over. */
+  done: boolean
+  /** One is empty: every ask fits it. */
+  open: boolean
+  /** The most cores free on one. */
+  free: number
+  /** The fewest cores one has. */
+  cores: number
+  /** The least memory free on one. */
+  memory: number
+}
+
+function boundsOf(
+  bins: readonly Bin[],
+  held: ReadonlySet<Bin>,
+  out: Bounds,
+  floor: Need | undefined,
+): void {
+  out.done = floor !== undefined
+  out.open = false
+  out.free = -Infinity
+  out.cores = Infinity
+  out.memory = Infinity
+  for (const b of bins) {
+    if (held.has(b)) continue
+    if (floor !== undefined && fits(b, floor)) out.done = false
+    if (b.running === 0) out.open = true
+    out.free = Math.max(out.free, b.cores - b.used.cores)
+    out.cores = Math.min(out.cores, b.cores)
+    out.memory = Math.min(out.memory, b.memory - b.used.memory)
+  }
+}
+
+/**
+ * True when `assign` would fit `need` on no bin and hold none for it, by
+ * `fits` and its hold rule: no bin is empty, and on each it is less than
+ * the bin, fits its memory, and wants more cores than are free.
+ */
+export function dead(need: Need, b: Bounds): boolean {
+  return (
+    need.platform === undefined &&
+    need.above === undefined &&
+    !b.open &&
+    need.cores > b.free + 1e-9 &&
+    need.cores < b.cores &&
+    need.memory <= b.memory
+  )
+}
+
+/** How well `need` suits `b` by `place`: the higher, the better. */
+function fit(b: Bin, need: Need, place: Strategy['place'], index: number): number {
+  switch (place) {
+    case 'best-fit':
+      return b.used.cores - b.cores
+    case 'worst-fit':
+      return b.cores - b.used.cores
+    case 'first-fit':
+      return -index
+    case 'tetris': {
+      // The dot product of the need and what is free, each as a share of
+      // the worker: a task goes where its shape matches the hole.
+      const cores = Math.min(need.cores, b.cores) / b.cores
+      const memory = b.memory > 0 ? Math.min(need.memory, b.memory) / b.memory : 0
+      const freeCores = (b.cores - b.used.cores) / b.cores
+      const freeMemory = b.memory > 0 ? (b.memory - b.used.memory) / b.memory : 0
+      return cores * freeCores + memory * freeMemory
+    }
+  }
+}

package/src/docker.ts

@@ -0,0 +1,156 @@
+// `docker()`: each worker a container on this machine, held to its size's
+// cores and memory, in a fresh clone made inside it of the tracked files
+// as the run sees them, sharing this machine's store. The relay
+// is the run's own on loopback; a container reaches it through the host's
+// network on Linux and through `host.docker.internal` elsewhere.
+
+import { mkdirSync, realpathSync } from 'node:fs'
+import { homedir } from 'node:os'
+import path from 'node:path'
+import { refuseUnknownOptions, UserError, type PluginOptionKinds } from '@vzn/vx'
+import { loopbackRelay, reasons } from './local.js'
+import type { DteAdapter } from './plugin.js'
+
+export interface DockerOptions {
+  /** An image with Bun and git, such as one built `FROM oven/bun` with git added. */
+  readonly image: string
+  /** A shell line the clone runs before its worker starts, such as `bun install`. */
+  readonly prepare?: string
+}
+
+const KEYS: PluginOptionKinds<DockerOptions> = { image: 'string', prepare: 'string' }
+
+export function docker(options: DockerOptions): DteAdapter {
+  refuseUnknownOptions('docker()', options, KEYS)
+  // A bare `docker()` read `options.image` off undefined: a TypeError, a crash.
+  if (typeof options?.image !== 'string' || options.image === '') {
+    throw new UserError(
+      "docker() needs image: one with Bun and git, such as 'oven/bun:1.4' plus git",
+    )
+  }
+  let relay: { url: string; stop(): void } | undefined
+  const workers = new Map<string, ReturnType<typeof Bun.spawn>>()
+  const linux = process.platform === 'linux'
+  let closed = false
+  const why = reasons()
+
+  return {
+    // Each run asks for one (`vx watch` runs again): a new run, on the tree as it is now.
+    async relay() {
+      closed = false
+      relay = await loopbackRelay()
+      return relay.url
+    },
+
+    async spawn(a) {
+      const git = (...args: string[]): string => {
+        const r = Bun.spawnSync(['git', ...args], { cwd: a.workspaceRoot, stderr: 'pipe' })
+        if (r.exitCode !== 0) throw new Error(`git ${args[0]}: ${r.stderr.toString().trim()}`)
+        return r.stdout.toString().trim()
+      }
+      const top = git('rev-parse', '--show-toplevel')
+      // The tracked files as the run saw them at its start, uncommitted
+      // changes too: a clone holds only refs, so the commit is fetched by its id.
+      const sha = a.commit
+      // git names the real path: through a link (macOS's /tmp) the relative one climbed out.
+      const rel = path.relative(top, realpathSync(a.workspaceRoot)) || '.'
+      // The store is keyed by the repository's identity, its origin: the
+      // clone's would be /src, a store of its own the run never reads.
+      const origin = Bun.spawnSync(['git', 'remote', 'get-url', 'origin'], {
+        cwd: a.workspaceRoot,
+        stderr: 'ignore',
+      })
+        .stdout.toString()
+        .trim()
+      // On Linux a container's root writes the store as root; as this user
+      // it has no home but /tmp, where the store is mounted instead.
+      const uid = process.getuid?.() ?? 0
+      const asUser = linux && uid !== 0
+      const work = asUser ? '/tmp/work' : '/work'
+      const script = [
+        'set -e',
+        `git clone -q /src ${work}`,
+        `cd ${work}`,
+        origin === '' ? 'git remote remove origin' : `git remote set-url origin ${quote(origin)}`,
+        `git fetch -q --upload-pack='git -c uploadpack.allowAnySHA1InWant=true upload-pack' /src ${sha}`,
+        `git checkout -q --detach ${sha}`,
+        `cd ${quote(rel)}`,
+        // On stderr, which names why a container failed: pnpm prints an install's error on stdout.
+        ...(options.prepare === undefined ? [] : ['{', options.prepare, '} >&2']),
+        'exec ./node_modules/.bin/vx dte worker',
+      ].join('\n')
+      // This machine's store and cache dir at their own paths, as local()'s
+      // workers share them: what a worker saves, the run reads.
+      const home = process.env['HOME'] || homedir()
+      const store = path.join(home, '.vx')
+      mkdirSync(store, { recursive: true })
+      const mounts = [store]
+      const cacheEnv: Record<string, string> = {}
+      if (a.cacheDir !== undefined) {
+        mkdirSync(a.cacheDir, { recursive: true })
+        mounts.push(a.cacheDir)
+        cacheEnv['VX_CACHE_DIR'] = a.cacheDir
+      }
+      const inHome = asUser ? '/tmp' : home
+      const env = {
+        ...a.env,
+        HOME: inHome,
+        ...cacheEnv,
+        ...(linux ? {} : { VX_DTE_RELAY: a.relay.replace('127.0.0.1', 'host.docker.internal') }),
+        // The checkout is the host's, owned by another user than the container's.
+        GIT_CONFIG_COUNT: '1',
+        GIT_CONFIG_KEY_0: 'safe.directory',
+        GIT_CONFIG_VALUE_0: '*',
+      }
+      const name = `vx-dte-${process.pid}-${a.index}`
+      const proc = Bun.spawn(
+        [
+          'docker',
+          'run',
+          '--rm',
+          '--name',
+          name,
+          '--cpus',
+          String(a.cpu),
+          '--memory',
+          `${a.memory}b`,
+          ...(linux ? ['--network', 'host'] : []),
+          '--volume',
+          `${top}:/src:ro`,
+          ...(asUser ? ['--user', `${uid}:${process.getgid?.() ?? uid}`] : []),
+          ...mounts.flatMap((m) => [
+            '--volume',
+            `${m}:${m === store ? path.join(inHome, '.vx') : m}`,
+          ]),
+          ...Object.keys(env).flatMap((k) => ['--env', k]),
+          options.image,
+          'sh',
+          '-c',
+          script,
+        ],
+        { env: { ...process.env, ...env }, stdin: 'ignore', stdout: 'ignore', stderr: 'pipe' },
+      )
+      workers.set(name, proc)
+      void (async () => {
+        const [err, code] = await Promise.all([new Response(proc.stderr).text(), proc.exited])
+        workers.delete(name)
+        if (!closed) a.exited(await why(`exited ${code}`, a.id, err))
+      })()
+    },
+
+    async close() {
+      closed = true
+      // The relay closing the run tells each worker to leave; a container
+      // still up after the grace is removed.
+      relay?.stop()
+      relay = undefined
+      const left = [...workers]
+      await Promise.race([Promise.all(left.map(([, p]) => p.exited)), Bun.sleep(2_000)])
+      const up = left.filter(([name]) => workers.has(name)).map(([name]) => name)
+      if (up.length > 0)
+        Bun.spawnSync(['docker', 'rm', '-f', ...up], { stdout: 'ignore', stderr: 'ignore' })
+    },
+  }
+}
+
+const quote = (s: string): string => `'${s.replaceAll("'", `'\\''`)}'`

package/src/forecast.ts

@@ -0,0 +1,68 @@
+// Which cached tasks will miss, guessed before any worker can say: those
+// whose inputs the last commit changed, and every task after one, its key
+// folding theirs. The run learns a task missed only once a worker keys it,
+// 20 s in: main a09b987's plan saw its 56 shards only then, and ended
+// 14 s after the best (tests/sim.test.ts). The guess only sizes the run: a
+// hit it names costs a worker the plan cancels, a miss it does not names
+// the wait the run always had.
+
+import type { TaskNode } from '@vzn/vx'
+
+/** Root files every key reads: a lockfile, the workspace config. */
+const WHOLE = /^(?:\.vx\/|(?:bun\.lockb?|pnpm-lock\.yaml|package-lock\.json|yarn\.lock)$)/
+const GLOB = /[*?[{]/
+
+/** Whether `rel` is one of `patterns`' files: a literal names a file or its tree; `!` entries are left out, so it errs to a miss. */
+function matches(patterns: readonly string[] | undefined, rel: string): boolean {
+  for (const raw of patterns ?? []) {
+    if (raw.startsWith('!')) continue
+    const p = raw.replace(/^\.\//, '').replace(/\/$/, '')
+    if (GLOB.test(p) ? new Bun.Glob(p).match(rel) : rel === p || rel.startsWith(`${p}/`))
+      return true
+  }
+  return false
+}
+
+/**
+ * The cached tasks of `nodes` that `changed` (workspace-relative paths)
+ * makes miss: a task whose `inputs` match one, whose project's
+ * `package.json` or config is one, or after such a task.
+ */
+export function likelyMisses(
+  nodes: ReadonlyMap<string, TaskNode>,
+  changed: readonly string[],
+  workspaceRoot: string,
+): Set<string> {
+  const out = new Set<string>()
+  if (changed.length === 0) return out
+  const whole = changed.some((p) => WHOLE.test(p))
+  const root = workspaceRoot.endsWith('/') ? workspaceRoot : `${workspaceRoot}/`
+  const own = (n: TaskNode): boolean => {
+    const inputs = n.config.inputs
+    if (inputs === undefined) return false
+    if (whole) return true
+    const dir = n.projectDir.startsWith(root) ? n.projectDir.slice(root.length) : ''
+    for (const p of changed) {
+      if (matches(inputs.workspaceFiles, p)) return true
+      if (dir !== '' && !p.startsWith(`${dir}/`)) continue
+      const rel = dir === '' ? p : p.slice(dir.length + 1)
+      if (rel === 'package.json' || /^vx\.config\.[cm]?[jt]s$/.test(rel)) return true
+      if (matches(inputs.files, rel)) return true
+    }
+    return false
+  }
+  const keyed = new Map<string, boolean>()
+  const changes = (id: string): boolean => {
+    const known = keyed.get(id)
+    if (known !== undefined) return known
+    keyed.set(id, false)
+    const n = nodes.get(id)
+    const c = n !== undefined && (own(n) || n.deps.some(changes))
+    keyed.set(id, c)
+    return c
+  }
+  for (const [id, n] of nodes)
+    if (n.config.exec?.command !== undefined && n.config.cache !== undefined && changes(id))
+      out.add(id)
+  return out
+}