@vzn/vx 0.0.646 → 0.0.649

package/src/cli/why.ts

@@ -2,24 +2,46 @@
 // terminal. The runs table names the run-over-run hash change, and
 // `entry_inputs` (the input-fingerprint moat) names the exact cache-key
 // components that differ. Read-only over cache.db plus a stat of each
-// moved input file — no config evaluation, no re-hash.
+// moved input file, no re-hash. Configs are evaluated only when a moved
+// upstream is a group: it records no run, so the graph names what it gathers.
 
 import { Cache } from '../cache/index.js'
-import { flagHint, formatValue, seeHelp } from './help.js'
-import { splitTaskId } from '../graph/index.js'
+import { anchoredSpecError, flagHint, formatValue, seeHelp } from './help.js'
+import { buildTaskGraph, isGroupTask, splitTaskId } from '../graph/index.js'
 import {
   cacheKeyDiff,
   explainCacheKey,
   inputWriters,
   latestRunId,
   rootCauses,
+  upstreamTask,
   whyDidThisRerun,
 } from '../history/index.js'
 import { resolveRunId } from '../orchestrator/index.js'
-import { MASKED, nearMatches, printable, refusal, UserError } from '../util/index.js'
-import { findWorkspaceRoot } from '../workspace/index.js'
+import {
+  detectColors,
+  ERROR,
+  MASKED,
+  nearMatches,
+  paint,
+  printable,
+  refusal,
+  SUCCESS,
+  ui,
+  UserError,
+  WARN,
+} from '../util/index.js'
+import { runRules } from '../settings.js'
+import { buildPackageGraph, findWorkspaceRoot } from '../workspace/index.js'
 import { findCwdProject } from './select.js'
-import { cliCacheDir, discoverCliProjects, parseCacheDirFlag } from './workspace-config.js'
+import {
+  cliCacheDir,
+  discoverCliProjects,
+  loadCliProjects,
+  loadCliWorkspace,
+  parseCacheDirFlag,
+  rootSpelled,
+} from './workspace-config.js'
 
 interface WhyArgs {
   target?: string
@@ -47,7 +69,8 @@ export const WHAT_TO_DO: Readonly<Record<string, string>> = {
   config:
     "the task's evaluated config changed (its vx.config or a file it imports); `vx show <that task>` prints it as it is now",
   upstream: "a dependency's key moved; `vx why <that task>` says why",
-  plugin: "a key plugin's material changed; that plugin decides what it folds",
+  plugin: "a key plugin's material changed; that plugin decides what goes into the key",
+  platform: 'it ran on another platform; each of its `exec.platforms` keeps its own entry',
   format:
     'vx keys tasks differently since an upgrade; every cached task misses once, nothing to fix',
 }
@@ -65,8 +88,13 @@ export function parseWhyArgs(args: readonly string[]): WhyArgs {
     // got two different diagnoses depending on how it was typed.
     if (a === '--run' || a.startsWith('--run=')) {
       const rv = a === '--run' ? args[++i] : a.slice(6)
-      if (rv === undefined || rv === '')
-        return { ...out, error: '--run requires a run id (`vx last --list` shows them)' }
+      // A run id is hex: one opening with `-` is the next flag, swallowed.
+      const flag = a === '--run' && rv?.startsWith('-') === true ? `got flag ${rv}; ` : ''
+      if (rv === undefined || rv === '' || flag !== '')
+        return {
+          ...out,
+          error: `--run requires a run id (${flag}\`vx last --list\` shows them)${seeHelp('why')}`,
+        }
       out.runId = rv
       continue
     }
@@ -78,7 +106,7 @@ export function parseWhyArgs(args: readonly string[]): WhyArgs {
     }
     const cd = parseCacheDirFlag(args, i)
     if (cd !== null) {
-      if ('error' in cd) return { ...out, error: cd.error }
+      if ('error' in cd) return { ...out, error: `${cd.error}${seeHelp('why')}` }
       out.cacheDir = cd.cacheDir
       i = cd.next
       continue
@@ -90,6 +118,13 @@ export function parseWhyArgs(args: readonly string[]): WhyArgs {
     // Empty is no task: read as a query it matched every recorded one.
     if (a !== '') out.target = a
   }
+  if (out.target !== undefined) {
+    const error = anchoredSpecError(
+      out.target,
+      (task) => `vx why ${task} finds the project that ran it`,
+    )
+    if (error !== undefined) return { ...out, error }
+  }
   return out
 }
 
@@ -141,6 +176,25 @@ async function resolveTarget(
       .query('SELECT 1 FROM runs WHERE project = ? AND task = ? ORDER BY id DESC LIMIT 1')
       .get(project, task)
     if (hit !== null) return target
+  } else {
+    // A bare name reads only its own task's rows: the DISTINCT over every
+    // pair sorted the whole history (24 of 26 ms at 58k rows), and its list
+    // serves only the miss's suggestions below.
+    const matches = (
+      db.query('SELECT DISTINCT project FROM runs WHERE task = ? ORDER BY project').all(target) as {
+        project: string
+      }[]
+    ).map((r) => `${r.project}#${target}`)
+    if (matches.length === 1) return matches[0]!
+    if (matches.length > 1) {
+      const here = await cwdProject()
+      if (here !== null && matches.includes(`${here}#${target}`)) return `${here}#${target}`
+      throw new UserError(
+        `vx why: "${target}" ran in ${matches.length} projects — pick one:\n` +
+          matches.map((m) => `  ${m}`).join('\n'),
+        'VX_E_AMBIGUOUS',
+      )
+    }
   }
   const pairs = db
     .query('SELECT DISTINCT project, task FROM runs ORDER BY project, task')
@@ -162,17 +216,6 @@ async function resolveTarget(
       'VX_E_NO_HISTORY',
     )
   }
-  const matches = ids.filter((id) => id.endsWith(`#${target}`))
-  if (matches.length === 1) return matches[0]!
-  if (matches.length > 1) {
-    const here = await cwdProject()
-    if (here !== null && matches.includes(`${here}#${target}`)) return `${here}#${target}`
-    throw new UserError(
-      `vx why: "${target}" ran in ${matches.length} projects — pick one:\n` +
-        matches.map((m) => `  ${m}`).join('\n'),
-      'VX_E_AMBIGUOUS',
-    )
-  }
   throw new UserError(
     `vx why: no recorded runs for task "${target}"${suggest(target, ids, invoked)}`,
     'VX_E_NO_HISTORY',
@@ -181,27 +224,38 @@ async function resolveTarget(
 
 const fmtWhen = (ms: number): string => new Date(ms).toISOString()
 
-/** `//#task`, Turbo's root package, as the root project's id: the name discovery gives it (D-39). */
-async function rootSpelled(root: string, target: string): Promise<string> {
-  if (!target.startsWith('//#')) return target
-  const name = await discoverCliProjects(root).then(
-    (metas) => metas.find((m) => m.dir === root)?.name,
-    () => undefined,
-  )
-  return name === undefined ? target : `${name}#${target.slice(3)}`
-}
-
 /** ` · up-to-date` or ` · restored` on a hit, as the run's summary said it; nothing otherwise. */
 function restoredWord(r: { restored: boolean | null }): string {
   return r.restored === null ? '' : r.restored ? ' · restored' : ' · up-to-date'
 }
 
+/**
+ * One run of the task, the same for `this run` and `previous`. A hit's
+ * status (`cache-hit`, `cache-hit-remote`) already names it and its tier,
+ * and `up-to-date` / `restored` says what it did to the disk; only an
+ * executed run needs the word. A skipped task never ran and has no key: it
+ * read `skipped · executed · key ` (item 898).
+ */
+function runFacts(r: {
+  startedAt: number
+  status: string
+  cacheHit: boolean | null
+  restored: boolean | null
+  hash: string
+}): string {
+  const ran = r.cacheHit === false && r.status !== 'skipped'
+  return (
+    `${fmtWhen(r.startedAt)} · ${r.status}${restoredWord(r)}${ran ? ' · executed' : ''}` +
+    (r.hash === '' ? ' · no key' : ` · key ${r.hash}`)
+  )
+}
+
 export async function whyCmd(args: readonly string[]): Promise<number> {
   const parsed = parseWhyArgs(args)
   if (parsed.error !== undefined) throw new UserError(`vx why: ${parsed.error}`, 'VX_E_USAGE')
   if (parsed.target === undefined) {
     throw new UserError(
-      'vx why: <task> required (e.g. vx why app#build, or vx why build)',
+      `vx why: <task> required (e.g. vx why app#build, or vx why build)${seeHelp('why')}`,
       'VX_E_USAGE',
     )
   }
@@ -215,7 +269,13 @@ export async function whyCmd(args: readonly string[]): Promise<number> {
     )
     let runId: string | null
     if (parsed.runId !== undefined) {
-      runId = resolveRunId(db, parsed.runId, 'vx why')
+      // A stopped run keeps rows but no header (item 854), and `vx last
+      // --log` prints its id, so the whole id is taken from its rows too.
+      runId =
+        resolveRunId(db, parsed.runId, 'vx why') ??
+        (db.query('SELECT 1 FROM runs WHERE run_id = ? LIMIT 1').get(parsed.runId) !== null
+          ? parsed.runId
+          : null)
       // An unknown id read as a known run missing the task (X-18).
       if (runId === null) {
         throw new UserError(
@@ -232,8 +292,9 @@ export async function whyCmd(args: readonly string[]): Promise<number> {
       if (parsed.format === 'json') {
         process.stdout.write(`${JSON.stringify({ taskId, why: null, diff: null, explanation })}\n`)
       } else {
+        const c = detectColors(process.stdout)
         process.stdout.write(
-          `${taskId}: recorded runs carry no run id — showing the latest cache entry instead\n` +
+          `${ui.inline(ui.id(taskId), c)}: recorded runs carry no run id — showing the latest cache entry instead\n` +
             (explanation.latestEntry !== null
               ? `  hash ${explanation.latestEntry.hash} · $ ${explanation.latestEntry.command}\n`
               : '  (no cache entry either)\n'),
@@ -253,7 +314,15 @@ export async function whyCmd(args: readonly string[]): Promise<number> {
     // An upstream change is never the cause, only its carrier: follow
     // each moved dependency in this run down to the tasks whose own
     // inputs moved, so one `vx why` names the file, not the next task.
-    const roots = rootCauses(db, runId, taskId, diff.entries)
+    // A group records no run: the graph names what it gathers.
+    const unrecorded = diff.entries.filter(
+      (e) =>
+        e.kind === 'upstream' &&
+        e.change === 'changed' &&
+        !cacheKeyDiff(db, runId, upstreamTask(e.name)).found,
+    )
+    const groups = unrecorded.length > 0 ? await groupMembers(root, taskId) : new Map()
+    const roots = rootCauses(db, runId, taskId, diff.entries, groups)
     const writers = inputWriters(db, root, taskId, diff.entries, roots)
 
     if (parsed.format === 'json') {
@@ -262,24 +331,22 @@ export async function whyCmd(args: readonly string[]): Promise<number> {
     }
 
     const lines: string[] = []
+    const c = detectColors(process.stdout)
+    const dim = (text: string): string => paint('', text, c, { dim: true })
+    const head = (text: string): string => paint('', text, c, { bold: true })
     const t = why.thisRun!
-    lines.push(`${taskId} — run ${runId}`)
-    // A hit's status (`cache-hit`, `cache-hit-remote`) already names it and
-    // its tier, and `up-to-date` / `restored` says what it did to the disk;
-    // only an executed run needs the word. A skipped task never ran and has
-    // no key: it read `skipped · executed · key ` (item 898).
-    const ran = t.cacheHit === false && t.status !== 'skipped'
-    lines.push(
-      `  this run   ${fmtWhen(t.startedAt)} · ${t.status}${restoredWord(t)}` +
-        `${ran ? ' · executed' : ''}${t.hash === '' ? ' · no key' : ` · key ${t.hash}`}`,
-    )
-    if (why.previousRun == null) {
-      lines.push('  previous   (none — first recorded run of this task)')
+    lines.push(`${ui.inline(ui.id(taskId), c)}${dim(` — run ${runId}`)}`)
+    lines.push(`  ${dim('this run')}   ${runFacts(t)}`)
+    if (why.previousRun == null && t.hash === '') {
+      // Only keyed runs are compared: a persistent task's tenth run read
+      // as its first, and the note saying why went unprinted.
+      lines.push(`  ${dim('previous')}   (none with a cache key)`)
+      lines.push(`  ${dim('verdict')}    ${why.note}`)
+    } else if (why.previousRun == null) {
+      lines.push(`  ${dim('previous')}   (none — first recorded run of this task)`)
     } else {
       const p = why.previousRun
-      lines.push(
-        `  previous   ${fmtWhen(p.startedAt)} · ${p.status}${restoredWord(p)} · key ${p.hash}`,
-      )
+      lines.push(`  ${dim('previous')}   ${runFacts(p)}`)
       // The key moved and the diff says by what: the verdict names it, so
       // an env-only change reads as one line, not "inputs differ" above a
       // table to scan.
@@ -288,9 +355,13 @@ export async function whyCmd(args: readonly string[]): Promise<number> {
         e.name === e.kind ? e.kind : `${e.kind} ${printable(e.name)}`,
       )
       lines.push(
-        `  verdict    ${
+        `  ${dim('verdict')}    ${
           why.hashChanged === true && moved.length > 0
-            ? `cache key changed: ${moved.slice(0, 3).join(', ')}${moved.length > 3 ? ` and ${moved.length - 3} more` : ''}`
+            ? paint(
+                WARN,
+                `cache key changed: ${moved.slice(0, 3).join(', ')}${moved.length > 3 ? ` and ${moved.length - 3} more` : ''}`,
+                c,
+              )
             : why.note
         }`,
       )
@@ -299,7 +370,7 @@ export async function whyCmd(args: readonly string[]): Promise<number> {
     if (diff.entries.length > 0) {
       lines.push('')
       lines.push(
-        `  what changed (${diff.entries.length} component${diff.entries.length === 1 ? '' : 's'}, ${diff.unchangedCount} unchanged):`,
+        `  ${head('what changed')}${dim(` (${diff.entries.length} component${diff.entries.length === 1 ? '' : 's'}, ${diff.unchangedCount} unchanged)`)}:`,
       )
       const kindW = Math.max(...diff.entries.map((e) => e.kind.length), 4)
       for (const e of diff.entries) {
@@ -313,11 +384,11 @@ export async function whyCmd(args: readonly string[]): Promise<number> {
                 ? `- ${e.before}`
                 : `${e.before} → ${e.after}`
         lines.push(
-          `    ${e.change.padEnd(7)} ${e.kind.padEnd(kindW)}  ${printable(e.name)}  ${beforeAfter}`.trimEnd(),
+          `    ${paint(CHANGE_HUE[e.change] ?? WARN, e.change.padEnd(7), c)} ${dim(e.kind.padEnd(kindW))}  ${printable(e.name)}  ${dim(beforeAfter)}`.trimEnd(),
         )
       }
       if (roots.length > 0) {
-        lines.push('', '  root cause:')
+        lines.push('', `  ${head('root cause')}:`)
         for (const r of roots.slice(0, ROOTS_SHOWN)) {
           const what = r.entries.map((e) =>
             e.name === e.kind ? e.kind : `${e.kind} ${printable(e.name)}`,
@@ -329,40 +400,47 @@ export async function whyCmd(args: readonly string[]): Promise<number> {
         if (roots.length > ROOTS_SHOWN) lines.push(`    and ${roots.length - ROOTS_SHOWN} more`)
       }
       if (writers.length > 0) {
-        lines.push('', '  changed during a run:')
+        lines.push('', `  ${head('changed during a run')}:`)
         for (const w of writers) {
-          lines.push(`    ${printable(w.file)}  while ${w.writers.join(', ')} ran`)
+          lines.push(`    ${printable(w.file)}  ${dim(`while ${w.writers.join(', ')} ran`)}`)
         }
       }
       const rootKinds = roots.flatMap((r) => r.entries.map((e) => e.kind))
+      // An upstream row names the task to ask next: the command, not a
+      // placeholder to fill in from the row above. A group records no run,
+      // so `vx why` on one refuses: its members are asked instead.
+      const upstream = upstreamTodo(
+        diff.entries.filter((e) => e.kind === 'upstream'),
+        unrecorded,
+      )
       const kinds = [...new Set([...diff.entries.map((e) => e.kind), ...rootKinds])].filter(
-        (k) => k in WHAT_TO_DO && !(k === 'upstream' && roots.length > 0),
+        (k) =>
+          k in WHAT_TO_DO && !(k === 'upstream' && (roots.length > 0 || upstream.length === 0)),
       )
       if (kinds.length > 0) {
-        lines.push('', '  what to do:')
-        // An upstream row names the task to ask next: the command, not a
-        // placeholder to fill in from the row above.
-        const upstream = diff.entries.filter((e) => e.kind === 'upstream').map((e) => e.name)
+        lines.push('', `  ${head('what to do')}:`)
+        // Its own column: a root cause's kind and the `written` row are
+        // not in the table above, and overflowed its width.
+        const todoW = Math.max(kindW, ...kinds.map((k) => k.length), writers.length > 0 ? 7 : 0)
         for (const k of kinds) {
+          if (k === 'upstream') {
+            for (const todo of upstream) lines.push(`    ${dim(k.padEnd(todoW))}  ${todo}`)
+            continue
+          }
           const todo =
-            k === 'upstream'
-              ? WHAT_TO_DO[k]!.replace(
-                  '`vx why <that task>`',
-                  upstream.map((n) => `\`vx why ${n}\``).join(', '),
-                )
-              : k === 'config'
-                ? WHAT_TO_DO[k]!.replace('`vx show <that task>`', `\`vx show ${taskId}\``)
-                : WHAT_TO_DO[k]
-          lines.push(`    ${k.padEnd(kindW)}  ${todo}`)
+            k === 'config'
+              ? WHAT_TO_DO[k]!.replace('`vx show <that task>`', `\`vx show ${taskId}\``)
+              : WHAT_TO_DO[k]
+          lines.push(`    ${dim(k.padEnd(todoW))}  ${todo}`)
         }
         if (writers.length > 0) {
           // A task re-writing a file a key reads moves that key every run:
           // the miss is right, and only moving the write ends it.
-          lines.push(`    ${'written'.padEnd(kindW)}  ${WRITTEN_TODO}`)
+          lines.push(`    ${dim('written'.padEnd(todoW))}  ${WRITTEN_TODO}`)
         }
       }
     } else if (why.hashChanged === true) {
-      lines.push(`  detail     ${diff.note}`)
+      lines.push(`  ${dim('detail')}     ${diff.note}`)
     }
     process.stdout.write(`${lines.join('\n')}\n`)
     return 0
@@ -373,5 +451,65 @@ export async function whyCmd(args: readonly string[]): Promise<number> {
 
 const ROOTS_SHOWN = 5
 
+const CHANGE_HUE: Record<string, string> = { added: SUCCESS, removed: ERROR, changed: WARN }
+
+type DiffEntry = ReturnType<typeof cacheKeyDiff>['entries'][number]
+
+/**
+ * The upstream advice: a moved key names the task to ask next, a group
+ * (no run of its own) the verb that names what it gathers, and an edge
+ * added or removed says the graph changed, since no key moved.
+ */
+function upstreamTodo(upstream: readonly DiffEntry[], unrecorded: readonly DiffEntry[]): string[] {
+  const out: string[] = []
+  const groups = new Set(unrecorded.map((e) => e.name))
+  const moved = [
+    ...new Set(
+      upstream
+        .filter((e) => e.change === 'changed' && !groups.has(e.name))
+        .map((e) => upstreamTask(e.name)),
+    ),
+  ]
+  if (moved.length > 0)
+    out.push(
+      WHAT_TO_DO['upstream']!.replace(
+        '`vx why <that task>`',
+        moved.map((n) => `\`vx why ${n}\``).join(', '),
+      ),
+    )
+  for (const g of groups)
+    out.push(
+      `${g} is a group and records no run; \`vx show ${g}\` names what it gathers, \`vx why\` on the one whose key moved says why`,
+    )
+  const edges = upstream.filter((e) => e.change !== 'changed')
+  if (edges.length > 0)
+    out.push(
+      `a dependency joined or left the graph (${edges.map((e) => `${e.name} ${e.change}`).join(', ')}): its \`dependsOn\` or a project edge changed, which re-keys the task by design`,
+    )
+  return out
+}
+
+/**
+ * Each group in `taskId`'s graph with the tasks it gathers. Empty when a
+ * config no longer loads: the advice then names the group to `vx show`.
+ */
+async function groupMembers(root: string, taskId: string): Promise<Map<string, string[]>> {
+  try {
+    const metas = await discoverCliProjects(root)
+    const projects = await loadCliProjects(root, metas, 'all', { closure: true })
+    const [project, task] = splitTaskId(taskId)
+    const nodes = buildTaskGraph({
+      projects,
+      packageGraph: buildPackageGraph(metas),
+      requested: [{ project, task }],
+      workspaceRoot: root,
+      rules: runRules((await loadCliWorkspace(root)).workspaceConfig),
+    })
+    return new Map([...nodes.values()].filter(isGroupTask).map((n) => [n.id, n.deps]))
+  } catch {
+    return new Map()
+  }
+}
+
 const WRITTEN_TODO =
   'a task that writes a file a key reads re-keys it every run; give that write its own task with the file as an output, or keep the file out of inputs.files'

package/src/cli/workspace-config.ts

@@ -30,25 +30,29 @@ interface CliWorkspace {
   /** What a plugin's `config` stage said of the branch: its cache scope and base commit. */
   branch: BranchFacts
   cacheDir: string
-  /** The shared store a run opens `cacheDir` with (`resolveStoreRoot`), asked on load. */
-  storeRoot: Promise<string | null>
+  /**
+   * The shared store a run opens `cacheDir` with (`resolveStoreRoot`), asked
+   * on first call: with no remote, the answer is a git spawn, and a verb that
+   * never opens the store (help, show, last) paid it.
+   */
+  storeRoot: () => Promise<string | null>
 }
 
 export const warnToStderr = (message: string): void => {
   sayLine('warn', message)
 }
 
-export async function loadCliWorkspace(workspaceRoot: string): Promise<CliWorkspace> {
-  const { workspaceConfig, plugins, branch } = await loadWorkspacePlugins(
-    workspaceRoot,
-    warnToStderr,
-  )
+export async function loadCliWorkspace(
+  workspaceRoot: string,
+  warn: (message: string) => void = warnToStderr,
+): Promise<CliWorkspace> {
+  const { workspaceConfig, plugins, branch } = await loadWorkspacePlugins(workspaceRoot, warn)
   return {
     workspaceConfig,
     plugins,
     branch,
     cacheDir: resolveCacheDir(workspaceRoot, workspaceConfig),
-    storeRoot: resolveStoreRoot(workspaceRoot, workspaceConfig),
+    storeRoot: () => resolveStoreRoot(workspaceRoot, workspaceConfig),
   }
 }
 
@@ -57,9 +61,35 @@ export async function loadCliWorkspace(workspaceRoot: string): Promise<CliWorksp
  * plugin `discover` stage, with the cache dir the run uses. No lock is
  * `NO_LOCK`.
  */
-export async function discoverCliProjects(root: string): Promise<ProjectMeta[]> {
-  const { plugins, cacheDir } = await loadCliWorkspace(root)
-  return await discoverProjects(root, lockReader(root), plugins, cacheDir, warnToStderr)
+export async function discoverCliProjects(
+  root: string,
+  load: CliLoadOptions = {},
+): Promise<ProjectMeta[]> {
+  const warn = load.warn ?? warnToStderr
+  const ws = await loadCliWorkspace(root, warn)
+  return await discoverProjects(root, lockReader(root), ws.plugins, stageCacheDir(ws, load), warn)
+}
+
+/**
+ * The cache dir a plugin stage is told: `--cache-dir` resolved against the
+ * working directory as the run resolves it (prepare.ts), else the
+ * workspace's. The run reuses what these stages answered.
+ */
+export function stageCacheDir(ws: { cacheDir: string }, load: CliLoadOptions): string {
+  return load.cacheDir === undefined ? ws.cacheDir : path.resolve(process.cwd(), load.cacheDir)
+}
+
+/**
+ * `//#task`, Turbo's root package, as the root project's id: the name
+ * discovery gives it (D-39), for a verb that reads history by task id.
+ */
+export async function rootSpelled(root: string, target: string): Promise<string> {
+  if (!target.startsWith('//#')) return target
+  const name = await discoverCliProjects(root).then(
+    (metas) => metas.find((m) => m.dir === root)?.name,
+    () => undefined,
+  )
+  return name === undefined ? target : `${name}#${target.slice(3)}`
 }
 
 /**
@@ -93,7 +123,9 @@ export function parseCacheDirFlag(
  */
 export function namedCacheDir(override: string): string {
   const dir = path.resolve(process.cwd(), override)
-  if (!existsSync(dir)) throw new UserError(`--cache-dir ${override}: no such directory (${dir})`)
+  if (!existsSync(dir)) {
+    throw new UserError(`--cache-dir ${override}: no such directory (${dir})`, 'VX_E_USAGE')
+  }
   return dir
 }
 
@@ -120,6 +152,12 @@ export interface CliLoadOptions {
    * `build` there, and a reader that skipped it showed less than a run.
    */
   closure?: boolean
+  /**
+   * Where a plugin's warning goes, stderr by default. `vx watch` re-reads
+   * the configs around every cycle, and the cycle's run says each warning
+   * itself: printed per read, one cycle said it seven times.
+   */
+  warn?: (message: string) => void
 }
 
 /**
@@ -134,9 +172,10 @@ export async function loadCliProjects(
   scope: 'all' | readonly string[] = 'all',
   opts: CliLoadOptions = {},
 ): Promise<Map<string, ProjectEntry>> {
-  const ws = await loadCliWorkspace(workspaceRoot)
+  const warn = opts.warn ?? warnToStderr
+  const ws = await loadCliWorkspace(workspaceRoot, warn)
   const { plugins } = ws
-  const cacheDir = opts.cacheDir ?? ws.cacheDir
+  const cacheDir = stageCacheDir(ws, opts)
   const loaded = await loadProjects({
     workspaceRoot,
     cacheDir,
@@ -147,7 +186,7 @@ export async function loadCliProjects(
       ? { closure: true as const, packageGraph: buildPackageGraph([...metas]) }
       : { closure: false as const }),
     configs: lockOfDiscovery(metas) ?? lockReader(workspaceRoot),
-    warn: warnToStderr,
+    warn,
   })
   return loaded.projects
 }

package/src/config.ts

@@ -6,6 +6,11 @@
  */
 export type Duration = `${number}${'ms' | 's' | 'm' | 'h' | 'd'}`
 
+/** The machines a task can name in `exec.platforms`: `os-arch`, as Bun's compile targets name them. */
+export const PLATFORMS = ['linux-x64', 'linux-arm64', 'darwin-x64', 'darwin-arm64'] as const
+
+export type Platform = (typeof PLATFORMS)[number]
+
 /**
  * The workspace: settings in groups (`run`, `cache`, `lock`, `watch`) and the
  * plugins. Each setting's environment variable and flag derive from its
@@ -329,7 +334,7 @@ export interface TaskConfig {
  * INVALIDATES a task, `allow` says what it may TOUCH, and deriving one
  * from the other coupled them both ways — a declaration added for
  * caching silently widened the sandbox, and a path the task needed had
- * to be laundered through the cache key to get it (owner, 2026-09-05).
+ * to be laundered through the cache key to get it (2026-09-05).
  * A declared `cache.outputs` is NOT a write grant; the request
  * `sandbox-request.ts` builds carries no write of its own and binds
  * `allow.write` alone. This comment claimed the opposite — here and on
@@ -464,6 +469,13 @@ export interface ExecConfig {
    * state the machine has, exactly as they did before the field existed.
    */
   remote?: boolean | 'only'
+  /**
+   * The machines this task can run on, any of them. On one that is not
+   * listed the task is skipped, never failed, and so are its dependants;
+   * an executor that routes by platform (`TaskExecutor.platforms`) runs
+   * it on a worker that is. Omitted → anywhere.
+   */
+  platforms?: readonly Platform[]
   /** Environment exposed to the child process. */
   env?: ExecEnv
   /**

package/src/exec/env.ts

@@ -1,6 +1,6 @@
 import { existsSync, readFileSync } from 'node:fs'
 import path from 'node:path'
-import { ESSENTIAL_ENV } from '../util/index.js'
+import { ESSENTIAL_ENV, withoutWorkspaceBins } from '../util/index.js'
 
 // Build the environment exposed to a task.
 //
@@ -34,6 +34,8 @@ export interface BuildEnvOptions {
    * One holding `path.delimiter` is left out: PATH cannot name it.
    */
   binPaths?: readonly string[]
+  /** When set, the PATH taken from `source` drops each `node_modules/.bin` inside it. */
+  workspaceRoot?: string
 }
 
 export function buildIsolatedEnv(opts: BuildEnvOptions): NodeJS.ProcessEnv {
@@ -47,6 +49,9 @@ export function buildIsolatedEnv(opts: BuildEnvOptions): NodeJS.ProcessEnv {
     const value = opts.source[name]
     if (value !== undefined) out[name] = value
   }
+  if (opts.workspaceRoot !== undefined && out['PATH'] !== undefined) {
+    out['PATH'] = withoutWorkspaceBins(out['PATH'], opts.workspaceRoot)
+  }
   for (const [name, value] of Object.entries(opts.define)) {
     out[name] = value
   }
@@ -73,7 +78,7 @@ export function buildIsolatedEnv(opts: BuildEnvOptions): NodeJS.ProcessEnv {
  * A tool that runs other scripts reads it to call the same manager back
  * (npm-run-all's `run-s`, `run-p`) and falls back to `npm` without it:
  * solidjs/solid's `npm-run-all -nl build:*` needed a global npm under vx,
- * where `pnpm run build` passed (owner, 2026-10-06). It names a binary on
+ * where `pnpm run build` passed (2026-10-06). It names a binary on
  * this machine, so it is not in the key, as PATH is not.
  */
 export const PM_EXEC_ENV = 'npm_execpath'