@vzn/vx 0.0.16 → 0.0.21

package/src/cli/run.ts

@@ -1,34 +1,22 @@
-import readline from 'node:readline/promises'
+import { appendFile } from 'node:fs/promises'
 import path from 'node:path'
-import {
-  affectedProjects,
-  applyFilters,
-  buildPackageGraph,
-  defaultAffectedBase,
-  findWorkspaceRoot,
-  listProjects,
-  loadProjectConfig,
-  loadWorkspace,
-  loadWorkspaceConfig,
-  parseFilter,
-  resolveCacheDir,
-  type ProjectMeta,
-} from '../workspace/index.js'
+import { documentedFlags, seeHelp } from './help.js'
+import { defaultAffectedBase, findWorkspaceRoot } from '../workspace/index.js'
 import {
   planRun,
   formatRunReportMarkdown,
-  optionsToRequest,
-  resolveBackend as resolvePluginBackend,
+  outcomeLabel,
+  projectOutcome,
+  run as runOrchestrator,
   type OutcomeView,
   type RunOptions,
   type RunResult,
-  type VxPlugin,
 } from '../orchestrator/index.js'
 import type { ContinueMode } from '../graph/index.js'
 import { type CachePolicy, FULL_CACHE_POLICY, parseCachePolicy } from '../cache/index.js'
-import { parseSize } from '../util/index.js'
+import { findCwdProject, pickTask, resolveFilters } from './select.js'
+import { MAX_TIMEOUT_MS, parseDecimalInt, nearest, machineParallelism } from '../util/index.js'
 import { formatGraphDot, formatPlanJson, formatPlanText } from './plan-format.js'
-import { localBackend } from './backend.js'
 
 export interface RunArgs {
   /** Failure propagation (`--continue[=never|deps-ok|always]`). */
@@ -54,6 +42,8 @@ export interface RunArgs {
    * / `--force` in precedence order. Defaults to all-on.
    */
   cache: CachePolicy
+  /** `--cache` named a remote axis (`remote:r`, `:w`, `:rw`): the run says so when no plugin serves one. */
+  remoteRequested?: boolean
   /** `--cache-dir <path>`: override the cache directory (cwd-relative). */
   cacheDir: string | undefined
   frozen: boolean
@@ -68,24 +58,8 @@ export interface RunArgs {
    * env and workspace `timeout` defaults. Undefined when not passed.
    */
   timeout: number | undefined
-  /**
-   * `--memory <size>` / `--memory=<size>`: memory budget (resolved to
-   * bytes) for `exec.resources.memory` reservations. Defaults to
-   * os.totalmem() when not passed — pass it in cgroup-limited containers.
-   */
-  memory: number | undefined
-  /**
-   * `--verify[=determinism|inputs|fingerprint|all]`: cache-correctness
-   * verification. Undefined when not passed. `determinism` re-runs and
-   * content-compares outputs; `inputs` sandboxes with the declared-input
-   * baseline and flags undeclared reads; `fingerprint` ships output-tree
-   * fingerprints for the cross-machine diff (no re-run; the determinism
-   * modes set it too, for free). `allow` (from `--verify-allow=<pkg#task>,…`)
-   * exempts tasks from failing the run on a divergence.
-   */
-  verify: { determinism: boolean; inputs: boolean; fingerprint: boolean } | undefined
-  verifyAllow: string[]
-  outputLogs?: 'full' | 'errors-only' | 'none'
+  outputLogs?: 'full' | 'errors-only' | 'none' | 'hash-only'
+  download?: 'all' | 'toplevel' | 'none'
   forwardArgs: string[]
   verbosity: number
   dry: 'text' | 'json' | undefined
@@ -102,9 +76,39 @@ export interface RunArgs {
   tags: Record<string, string>
   /** `--report[=markdown]`. Undefined when the flag wasn't passed. */
   report: 'markdown' | undefined
+  /**
+   * `--report-file=<path>`. Undefined when the flag wasn't passed. Writes
+   * the same markdown as `--report`, but to a file — because redirecting
+   * vx's stdout captures the whole run log, not just the report.
+   */
+  reportFile: string | undefined
   error?: string
 }
 
+// The camelCase spelling the flag shipped with (retired 2026-09-10): two
+// edits past the suggester's reach, so it is named outright. A regex, not a
+// quoted literal, so the doc-drift test does not count it as an accepted flag.
+const RETIRED_EXCLUDE_DEPENDENCIES = /^--excludeDependencies(=|$)/
+
+/**
+ * `--concurrency <n>` is a positive decimal integer, or `<n>%` of the
+ * cores this process may use (`50%` on eight cores is 4, never below 1;
+ * over 100% is allowed for I/O-bound work; a container's CPU quota caps
+ * the count the way it caps the default). The percent form resolves
+ * here, at parse time, so the run sees one number and the summary says
+ * what it ran with.
+ */
+export function parseConcurrency(v: string, cpus = machineParallelism()): number | null {
+  const pct = /^(\d+)%$/.exec(v)
+  if (pct) {
+    const n = parseDecimalInt(pct[1]!)
+    if (n === null || n < 1) return null
+    return Math.max(1, Math.round((Math.max(1, cpus) * n) / 100))
+  }
+  const n = parseDecimalInt(v)
+  return n === null || n < 1 ? null : n
+}
+
 export function parseRunArgs(args: readonly string[]): RunArgs {
   const out: RunArgs = {
     tasks: [],
@@ -117,9 +121,6 @@ export function parseRunArgs(args: readonly string[]): RunArgs {
     frozen: false,
     retries: undefined,
     timeout: undefined,
-    memory: undefined,
-    verify: undefined,
-    verifyAllow: [],
     forwardArgs: [],
     verbosity: 0,
     dry: undefined,
@@ -129,6 +130,7 @@ export function parseRunArgs(args: readonly string[]): RunArgs {
     affected: undefined,
     tags: {},
     report: undefined,
+    reportFile: undefined,
   }
 
   const sepIdx = args.indexOf('--')
@@ -146,22 +148,39 @@ export function parseRunArgs(args: readonly string[]): RunArgs {
 
   for (let i = 0; i < before.length; i++) {
     const a = before[i]
-    if (a === '--filter') {
-      const v = before[++i]
-      if (v === undefined) return { ...out, error: `${a} requires a value` }
+    if (a === '--filter' || a?.startsWith('--filter=')) {
+      const v = a === '--filter' ? before[++i] : a.slice('--filter='.length)
+      if (v === undefined || v === '') return { ...out, error: `--filter requires a value` }
       out.filters.push(v)
-    } else if (a === '--concurrency') {
-      const v = before[++i]
-      if (v === undefined) return { ...out, error: `${a} requires a value` }
-      const n = Number(v)
-      if (!Number.isFinite(n) || n < 1) return { ...out, error: `invalid concurrency: ${v}` }
-      out.concurrency = Math.floor(n)
+    } else if (a === '--concurrency' || a?.startsWith('--concurrency=')) {
+      const v = a === '--concurrency' ? before[++i] : a.slice('--concurrency='.length)
+      if (v === undefined) return { ...out, error: `--concurrency requires a value` }
+      const n = parseConcurrency(v)
+      if (n === null) return { ...out, error: `invalid concurrency: ${v}` }
+      out.concurrency = n
     } else if (a === '--all') {
       out.all = true
-    } else if (a === '--excludeDependencies') {
+    } else if (RETIRED_EXCLUDE_DEPENDENCIES.test(a ?? '')) {
+      return {
+        ...out,
+        error: `unknown flag: ${a} (the flag is --exclude-dependencies)${seeHelp('run')}`,
+      }
+    } else if (a === '--exclude-dependencies') {
       out.excludeDependencies = 'all'
-    } else if (a?.startsWith('--excludeDependencies=')) {
-      const raw = a.slice('--excludeDependencies='.length)
+    } else if (a?.startsWith('--exclude-dependencies=')) {
+      const raw = a.slice('--exclude-dependencies='.length)
+      // An empty value is genuinely ambiguous — "drop every edge" (the
+      // bare flag) and "drop none" (an empty list) are equally defensible
+      // readings, and silently picking either does the opposite of what
+      // half the callers mean. Reject and name both explicit forms; the
+      // sibling value flags (--retry=, --timeout=, --cache-dir=)
+      // reject an empty `=` value the same way.
+      if (raw === '') {
+        return {
+          ...out,
+          error: `--exclude-dependencies= needs a value — pass bare --exclude-dependencies to drop every dependsOn edge, or omit the flag to keep them`,
+        }
+      }
       out.excludeDependencies = raw
         .split(',')
         .map((s) => s.trim())
@@ -171,71 +190,70 @@ export function parseRunArgs(args: readonly string[]): RunArgs {
     } else if (a === '--retry' || a?.startsWith('--retry=')) {
       const v = a === '--retry' ? before[++i] : a.slice('--retry='.length)
       if (v === undefined) return { ...out, error: `--retry requires a value` }
-      const n = Number(v)
-      if (v === '' || !Number.isInteger(n) || n < 0) {
+      const n = parseDecimalInt(v)
+      if (n === null) {
         return { ...out, error: `--retry must be a non-negative integer, got: ${v}` }
       }
       out.retries = n
     } else if (a === '--timeout' || a?.startsWith('--timeout=')) {
       const v = a === '--timeout' ? before[++i] : a.slice('--timeout='.length)
       if (v === undefined) return { ...out, error: `--timeout requires a value` }
-      const n = Number(v)
-      if (v === '' || !Number.isInteger(n) || n <= 0) {
-        return { ...out, error: `--timeout must be a positive integer (ms), got: ${v}` }
-      }
-      out.timeout = n
-    } else if (a === '--memory' || a?.startsWith('--memory=')) {
-      const v = a === '--memory' ? before[++i] : a.slice('--memory='.length)
-      if (v === undefined || v === '') return { ...out, error: `--memory requires a value` }
-      const bytes = parseSize(v)
-      if (bytes === null || bytes <= 0) {
-        return { ...out, error: `--memory must be a size like 8GB or 512MB, got: ${v}` }
-      }
-      out.memory = bytes
-    } else if (a === '--verify' || a?.startsWith('--verify=')) {
-      const what = a === '--verify' ? 'determinism' : a.slice('--verify='.length)
-      if (what === 'determinism') {
-        out.verify = { determinism: true, inputs: false, fingerprint: true }
-      } else if (what === 'inputs') {
-        out.verify = { determinism: false, inputs: true, fingerprint: false }
-      } else if (what === 'fingerprint') {
-        out.verify = { determinism: false, inputs: false, fingerprint: true }
-      } else if (what === 'all') {
-        out.verify = { determinism: true, inputs: true, fingerprint: true }
-      } else {
+      const n = parseDecimalInt(v)
+      if (n !== null && n > MAX_TIMEOUT_MS) {
+        // Not "effectively no limit" — setTimeout reduces a delay past 2^31-1
+        // to 1 ms, so this would kill every task the moment it spawned.
         return {
           ...out,
-          error: `--verify must be determinism | inputs | fingerprint | all (or bare --verify), got: ${what}`,
+          error:
+            `--timeout ${n} exceeds the maximum timer delay (${MAX_TIMEOUT_MS} ms, ~24.8 days); ` +
+            `larger values are silently reduced to 1 ms. Omit --timeout for no limit.`,
         }
       }
-    } else if (a?.startsWith('--verify-allow=')) {
-      out.verifyAllow = a
-        .slice('--verify-allow='.length)
-        .split(',')
-        .map((s) => s.trim())
-        .filter((s) => s.length > 0)
-    } else if (a === '--output-logs') {
-      const v = before[++i]
-      if (v !== 'full' && v !== 'errors-only' && v !== 'none') {
-        return { ...out, error: `--output-logs must be full, errors-only, or none` }
+      if (n === null || n <= 0) {
+        return { ...out, error: `--timeout must be a positive integer (ms), got: ${v}` }
+      }
+      out.timeout = n
+    } else if (a === '--output-logs' || a?.startsWith('--output-logs=')) {
+      const v = a === '--output-logs' ? before[++i] : a.slice('--output-logs='.length)
+      if (v !== 'full' && v !== 'errors-only' && v !== 'none' && v !== 'hash-only') {
+        return { ...out, error: `--output-logs must be full, errors-only, hash-only, or none` }
       }
       out.outputLogs = v
+    } else if (a === '--download' || a?.startsWith('--download=')) {
+      const v = a === '--download' ? before[++i] : a.slice('--download='.length)
+      if (v !== 'all' && v !== 'toplevel' && v !== 'none') {
+        return { ...out, error: `--download must be all, toplevel, or none` }
+      }
+      out.download = v
     } else if (a === '--cache-dir' || a?.startsWith('--cache-dir=')) {
       const v = a === '--cache-dir' ? before[++i] : a.slice('--cache-dir='.length)
       if (v === undefined || v === '') return { ...out, error: `--cache-dir requires a value` }
+      // Unlike every other value flag, a cache dir is an arbitrary
+      // string — nothing about its shape rejects a swallowed flag. An
+      // unquoted empty shell var (`--cache-dir $EMPTY --force`) would
+      // otherwise create a directory literally named `--force` and drop
+      // the flag. A path starting with `-` needs the `=` form.
+      if (a === '--cache-dir' && v.startsWith('-')) {
+        return { ...out, error: `--cache-dir requires a path, got flag: ${v}` }
+      }
       out.cacheDir = v
-    } else if (a === '--cache') {
-      const v = before[++i]
-      if (v === undefined) return { ...out, error: `${a} requires a value` }
-      try {
-        cachePolicy = parseCachePolicy(v, cachePolicy)
-      } catch (err) {
-        cacheSpecError = err instanceof Error ? err.message : String(err)
+    } else if (a === '--cache' || a?.startsWith('--cache=')) {
+      const v = a === '--cache' ? before[++i] : a.slice('--cache='.length)
+      if (v === undefined) return { ...out, error: `--cache requires a value` }
+      // A spec with no segment at all applies NOTHING, so `--cache=`
+      // (an empty shell var, or someone reaching for "no cache") left
+      // all four axes ON — the opposite of the intent. Reject it; an
+      // empty flag list for a NAMED layer (`local:`) stays valid and
+      // means that layer off.
+      if (!v.split(',').some((seg) => seg.trim().length > 0)) {
+        return {
+          ...out,
+          error: `--cache needs a spec like local:r, local:rw, remote:, or local:,remote:rw — pass --no-cache to disable every axis`,
+        }
       }
-    } else if (a?.startsWith('--cache=')) {
-      const v = a.slice('--cache='.length)
       try {
         cachePolicy = parseCachePolicy(v, cachePolicy)
+        if (/remote:[rw]/.test(v)) out.remoteRequested = true
       } catch (err) {
         cacheSpecError = err instanceof Error ? err.message : String(err)
       }
@@ -244,7 +262,14 @@ export function parseRunArgs(args: readonly string[]): RunArgs {
     } else if (a === '--force') {
       forceFlag = true
     } else if (a === '--continue') {
-      // Bare --continue = 'always' (the Turbo convention).
+      // Bare --continue = 'always' (the Turbo convention). Its mode comes
+      // with '=' only: `--continue never` would read `never` as a TASK, and
+      // the run would then say "No projects declare task(s): never" — true,
+      // and no help at all.
+      const next = before[i + 1]
+      if (next === 'never' || next === 'deps-ok' || next === 'always') {
+        return { ...out, error: `--continue takes its mode with '=': --continue=${next}` }
+      }
       out.continueMode = 'always'
     } else if (a?.startsWith('--continue=')) {
       const v = a.slice('--continue='.length)
@@ -252,11 +277,11 @@ export function parseRunArgs(args: readonly string[]): RunArgs {
         return { ...out, error: `--continue must be never, deps-ok, or always` }
       }
       out.continueMode = v
-    } else if (a === '--verbosity') {
-      const v = before[++i]
-      if (v === undefined) return { ...out, error: `${a} requires a value` }
-      const n = Number(v)
-      if (!Number.isInteger(n) || n < 0) return { ...out, error: `invalid verbosity: ${v}` }
+    } else if (a === '--verbosity' || a?.startsWith('--verbosity=')) {
+      const v = a === '--verbosity' ? before[++i] : a.slice('--verbosity='.length)
+      if (v === undefined) return { ...out, error: `--verbosity requires a value` }
+      const n = parseDecimalInt(v)
+      if (n === null) return { ...out, error: `invalid verbosity: ${v}` }
       out.verbosity = n
     } else if (a === '--dry') {
       out.dry = 'text'
@@ -277,7 +302,11 @@ export function parseRunArgs(args: readonly string[]): RunArgs {
     } else if (a === '--profile') {
       out.profile = 'profile.json'
     } else if (a?.startsWith('--profile=')) {
-      out.profile = a.slice('--profile='.length)
+      // An optional-value flag: an empty `=` means "no value given", so it
+      // takes the same documented default as the bare form. Resolving ''
+      // against cwd would name the cwd DIRECTORY and die with EISDIR after
+      // the whole run — and `--summarize=` already degrades to its default.
+      out.profile = a.slice('--profile='.length) || 'profile.json'
     } else if (a === '--affected') {
       out.affected = ''
     } else if (a?.startsWith('--affected=')) {
@@ -289,6 +318,16 @@ export function parseRunArgs(args: readonly string[]): RunArgs {
       const eq = raw.indexOf('=')
       if (eq <= 0) return { ...out, error: `invalid --tag (expected k=v): ${raw}` }
       out.tags[raw.slice(0, eq)] = raw.slice(eq + 1)
+    } else if (a === '--report-file' || a?.startsWith('--report-file=')) {
+      const v = a === '--report-file' ? before[++i] : a.slice('--report-file='.length)
+      if (v === undefined || v === '') return { ...out, error: `--report-file requires a path` }
+      // Same reasoning as --cache-dir: a path is an arbitrary string, so
+      // nothing about its shape rejects a swallowed flag. A path starting
+      // with `-` needs the `=` form.
+      if (a === '--report-file' && v.startsWith('-')) {
+        return { ...out, error: `--report-file requires a path, got flag: ${v}` }
+      }
+      out.reportFile = v
     } else if (a === '--report') {
       out.report = 'markdown'
     } else if (a?.startsWith('--report=')) {
@@ -298,7 +337,7 @@ export function parseRunArgs(args: readonly string[]): RunArgs {
       }
       out.report = fmt
     } else if (a !== undefined && a.startsWith('-')) {
-      return { ...out, error: `unknown flag: ${a}` }
+      return { ...out, error: `unknown flag: ${a}${didYouMeanFlag(a)}${seeHelp('run')}` }
     } else if (a !== undefined) {
       out.tasks.push(a)
     }
@@ -351,9 +390,11 @@ export function detectFlow(
  * honor the same selection semantics (cwd / `--all` / `--filter` /
  * `--affected` / anchored positionals).
  *
- * Returns either the resolved options or an error message string. The
- * caller is responsible for prefixing the message with its subcommand
- * name (`vx run: <msg>` / `vx watch: <msg>`) and exiting non-zero.
+ * Returns the resolved options, an error message, or `nothingSelected` —
+ * the selection legitimately resolved to zero projects (nothing changed
+ * since the `--affected` base), which is a clean exit, not a failure. The
+ * caller prefixes messages with its subcommand name (`vx run: <msg>` /
+ * `vx watch: <msg>`).
  *
  * Assumes the caller has already populated `parsed.tasks` (e.g. via
  * the interactive picker for `vx run`).
@@ -362,7 +403,7 @@ export async function resolveRunOptions(
   parsed: RunArgs,
   cwd: string,
   tasks: readonly string[],
-): Promise<RunOptions | { error: string }> {
+): Promise<RunOptions | { error: string } | { nothingSelected: string }> {
   for (const t of tasks) {
     const idx = t.indexOf('#')
     if (idx >= 0) {
@@ -387,13 +428,32 @@ export async function resolveRunOptions(
   // Project scope applies to bare task names only. Anchored entries
   // (pkg#task) resolve directly to their own project regardless.
   const bareTasks = tasks.filter((t) => !t.includes('#'))
+  const anchoredTasks = tasks.filter((t) => t.includes('#'))
   let projects: string[] | undefined
+  let staged: RunOptions['staged']
   if (bareTasks.length === 0) {
     projects = undefined
   } else if (filterStrings.length > 0) {
-    const resolved = await resolveFilters(cwd, filterStrings)
-    if (resolved.error) return { error: resolved.error }
-    projects = resolved.names
+    const resolved = await resolveFilters(cwd, filterStrings, {
+      ...(parsed.cacheDir !== undefined ? { cacheDir: parsed.cacheDir } : {}),
+      ...(parsed.frozen ? { frozen: true } : {}),
+    })
+    if ('error' in resolved) return { error: resolved.error }
+    if ('empty' in resolved) {
+      // "Nothing changed" is a clean exit for the BARE tasks the filter
+      // scopes — but it must never cancel an explicitly anchored
+      // `pkg#task`, which resolves to its own project regardless of
+      // scope. An empty project list keeps the bare tasks unselected
+      // while the anchored ones still run.
+      if (anchoredTasks.length === 0) return { nothingSelected: resolved.empty }
+      process.stderr.write(`vx: ${resolved.empty} — running ${anchoredTasks.join(', ')} only\n`)
+      projects = []
+    } else {
+      projects = resolved.names
+      // The graph walk staged every config; the run reuses those entries
+      // instead of evaluating and staging them a second time.
+      staged = resolved.staged
+    }
   } else if (parsed.all) {
     projects = undefined
   } else {
@@ -411,9 +471,11 @@ export async function resolveRunOptions(
     cwd,
     tasks: [...tasks],
     cache: parsed.cache,
+    ...(parsed.remoteRequested ? { remoteRequested: true } : {}),
     flow: detectFlow(parsed),
     ...(parsed.frozen ? { frozen: true } : {}),
     ...(parsed.outputLogs !== undefined ? { outputLogs: parsed.outputLogs } : {}),
+    ...(parsed.download !== undefined ? { download: parsed.download } : {}),
     ...(parsed.continueMode !== undefined ? { continueMode: parsed.continueMode } : {}),
     forwardArgs: parsed.forwardArgs,
   }
@@ -423,18 +485,10 @@ export async function resolveRunOptions(
     opts.excludeDependencies = parsed.excludeDependencies
   }
   if (projects !== undefined) opts.projects = projects
+  if (staged !== undefined) opts.staged = staged
   if (parsed.retries !== undefined) opts.retries = parsed.retries
   if (parsed.timeout !== undefined) opts.timeout = parsed.timeout
-  if (parsed.memory !== undefined) opts.memory = parsed.memory
   if (parsed.cacheDir !== undefined) opts.cacheDir = parsed.cacheDir
-  if (parsed.verify !== undefined) {
-    opts.verify = {
-      determinism: parsed.verify.determinism,
-      inputs: parsed.verify.inputs,
-      fingerprint: parsed.verify.fingerprint,
-      allow: new Set(parsed.verifyAllow),
-    }
-  }
   if (parsed.concurrency !== undefined) opts.concurrency = parsed.concurrency
   if (parsed.summarize !== undefined) opts.summarize = parsed.summarize
   if (parsed.profile !== undefined) opts.profile = parsed.profile
@@ -461,7 +515,14 @@ export async function runCmd(args: readonly string[]): Promise<number> {
       process.stderr.write(`vx run: missing task name (stdin is not a TTY)\n`)
       return 1
     }
-    const picked = await pickTask(cwd)
+    const picked = await pickTask(
+      cwd,
+      {},
+      {
+        ...(parsed.cacheDir !== undefined ? { cacheDir: parsed.cacheDir } : {}),
+        ...(parsed.frozen ? { frozen: true } : {}),
+      },
+    )
     if (!picked) return 1
     tasks = [`${picked.project}#${picked.task}`]
   }
@@ -471,6 +532,10 @@ export async function runCmd(args: readonly string[]): Promise<number> {
     process.stderr.write(`vx run: ${resolved.error}\n`)
     return 1
   }
+  if ('nothingSelected' in resolved) {
+    process.stderr.write(`vx run: ${resolved.nothingSelected}\n`)
+    return 0
+  }
   const opts = resolved
   // The raw invocation, recorded on the `invocations` row so dashboards
   // show what was actually run. `args` is everything after `run`.
@@ -480,6 +545,12 @@ export async function runCmd(args: readonly string[]): Promise<number> {
   // graph + probe the cache; the difference is just the formatter.
   if (parsed.dry !== undefined || parsed.graph !== undefined) {
     const plan = await planRun(opts)
+    if (plan.unresolvedTasks !== undefined && plan.unresolvedTasks.length > 0) {
+      process.stderr.write(
+        `vx run: no projects declare task(s): ${plan.unresolvedTasks.join(', ')}.\n`,
+      )
+      return 1
+    }
     if (plan.tasks.length === 0) {
       process.stderr.write(`vx run: no projects declare task(s): ${tasks.join(', ')}.\n`)
       return 1
@@ -499,134 +570,41 @@ export async function runCmd(args: readonly string[]): Promise<number> {
     return 0
   }
 
-  // Resolve where this run executes. A plugin's `backend` capability wins
-  // first (e.g. a backend plugin routes to a local-or-hosted service);
-  // otherwise core's default is pure in-process. Core names no service —
-  // delegation is entirely a plugin concern.
-  const request = optionsToRequest(opts)
-  const root = await findWorkspaceRoot(cwd)
-  const workspaceConfig = await loadWorkspaceConfig(root)
-  const plugins = (workspaceConfig?.plugins ?? []) as readonly VxPlugin[]
-  const backend = await resolvePluginBackend(
-    plugins,
-    {
-      workspaceRoot: root,
-      cacheDir: resolveCacheDir(root, workspaceConfig),
-      warn: (m) => process.stderr.write(`${m}\n`),
-      request,
-    },
-    () => Promise.resolve(localBackend()),
-  )
-  const result = await backend.run(request)
+  // A run executes in THIS process, always. Where an individual task's
+  // command runs is the `executor` capability's business (per task, with
+  // the scheduler, cache, retries and telemetry unchanged above it); there
+  // is no whole-run delegation seam to consult.
+  const summary = await runOrchestrator(opts)
+  const result: RunResult = { ok: summary.ok, outcomes: summary.outcomes.map(projectOutcome) }
   if (parsed.verbosity > 0) printSummary(result)
-  // Report generation is post-run, gated on the flag — zero cost when
-  // absent. Goes to stdout (NOT the status logger) so it stays
-  // machine-clean for `vx run ci --report=markdown >> $GITHUB_STEP_SUMMARY`.
-  if (parsed.report === 'markdown') {
-    process.stdout.write(formatRunReportMarkdown(result))
-  }
-  return result.ok ? 0 : 1
-}
-
-async function loadWorkspaceProjects(cwd: string): Promise<ProjectMeta[]> {
-  const root = await findWorkspaceRoot(cwd)
-  const ws = await loadWorkspace(root)
-  return await listProjects(ws)
-}
-
-async function findCwdProject(cwd: string): Promise<string | null> {
-  const projects = await loadWorkspaceProjects(cwd)
-  const abs = path.resolve(cwd)
-  let best: ProjectMeta | null = null
-  for (const p of projects) {
-    if (abs === p.dir || abs.startsWith(p.dir + path.sep)) {
-      if (!best || p.dir.length > best.dir.length) best = p
-    }
-  }
-  return best?.name ?? null
-}
-
-async function resolveFilters(
-  cwd: string,
-  raw: string[],
-): Promise<{ names?: string[]; error?: string }> {
-  const root = await findWorkspaceRoot(cwd)
-  const projects = await loadWorkspaceProjects(cwd)
-  const graph = buildPackageGraph(projects)
-  const parsed = raw.map((r) => parseFilter(r, root))
-
-  // Resolve every `[<since>]` filter against git before the pure
-  // applyFilters pass runs. One spawn per distinct ref — usually
-  // there's only one anyway.
-  const affectedByFilter = new Map<(typeof parsed)[number], Set<string>>()
-  for (const f of parsed) {
-    if (f.gitSince === undefined) continue
-    try {
-      const names = await affectedProjects({ workspaceRoot: root, since: f.gitSince, projects })
-      affectedByFilter.set(f, names)
-    } catch (err) {
-      const msg = err instanceof Error ? err.message : String(err)
-      return { error: msg }
-    }
-  }
-
-  const selected = applyFilters({ filters: parsed, projects, graph, affectedByFilter })
-  if (selected.size === 0) {
-    return { error: `no projects matched filter(s): ${raw.join(', ')}` }
-  }
-  return { names: [...selected].sort() }
-}
-
-interface PickedTask {
-  project: string
-  task: string
-  description?: string
-}
-
-export async function pickTask(
-  cwd: string,
-  io: { input?: NodeJS.ReadableStream; output?: NodeJS.WritableStream } = {},
-): Promise<PickedTask | null> {
-  const projects = await loadWorkspaceProjects(cwd)
-  const entries: PickedTask[] = []
-  for (const meta of projects) {
-    if (!meta.configPath) continue
-    const config = await loadProjectConfig(meta.configPath)
-    const taskNames = Object.keys(config.tasks ?? {}).sort()
-    for (const t of taskNames) {
-      const desc = config.tasks?.[t]?.description
-      entries.push({ project: meta.name, task: t, ...(desc ? { description: desc } : {}) })
-    }
-  }
-  if (entries.length === 0) {
-    process.stderr.write(`vx run: no tasks declared in any project\n`)
-    return null
-  }
-  const out = io.output ?? process.stdout
-  const numW = String(entries.length).length
-  const idW = Math.max(...entries.map((e) => `${e.project}#${e.task}`.length))
-  out.write('Tasks:\n')
-  entries.forEach((e, i) => {
-    const n = String(i + 1).padStart(numW, ' ')
-    const id = `${e.project}#${e.task}`.padEnd(idW)
-    const desc = e.description ? `  ${e.description}` : ''
-    out.write(`  ${n}. ${id}${desc}\n`)
-  })
-  const rl = readline.createInterface({
-    input: io.input ?? process.stdin,
-    output: io.output ?? process.stdout,
-  })
-  try {
-    const answer = (await rl.question(`Pick a task [1-${entries.length}]: `)).trim()
-    const n = Number(answer)
-    if (!Number.isInteger(n) || n < 1 || n > entries.length) {
-      process.stderr.write(`vx run: invalid selection: ${answer}\n`)
-      return null
+  // Report generation is post-run, gated on the flags — zero cost when
+  // both are absent. Rendered once, however many sinks asked for it.
+  if (parsed.report === 'markdown' || parsed.reportFile !== undefined) {
+    const md = formatRunReportMarkdown(result)
+    // `--report` writes stdout. The report ITSELF is machine-clean, but
+    // stdout is not vx's alone — the status logger writes there too, so
+    // `--report=markdown >> "$GITHUB_STEP_SUMMARY"` captures every frame,
+    // meter bar and `::group::` command above the table. `--report-file`
+    // is the redirect-free form.
+    if (parsed.report === 'markdown') process.stdout.write(md)
+    if (parsed.reportFile !== undefined) {
+      const target = path.resolve(cwd, parsed.reportFile)
+      try {
+        // APPEND, not overwrite: the flag exists for `$GITHUB_STEP_SUMMARY`,
+        // which GitHub documents as append-only and which other steps in the
+        // same job also write to. Truncating it would silently destroy their
+        // content, and would make replacing the documented `>>` recipe a
+        // behaviour change rather than a drop-in.
+        await appendFile(target, md)
+      } catch (err) {
+        // Same contract as --summarize / --profile: the run already
+        // happened, so a write failure is reported, not fatal.
+        const message = err instanceof Error ? err.message : String(err)
+        process.stderr.write(`vx: failed to write report to ${target}: ${message}\n`)
+      }
     }
-    return entries[n - 1] ?? null
-  } finally {
-    rl.close()
   }
+  return result.ok ? 0 : 1
 }
 
 function printSummary(summary: RunResult): void {
@@ -658,26 +636,22 @@ function printSummary(summary: RunResult): void {
 }
 
 function formatRow(o: OutcomeView): { task: string; status: string; duration: string } {
-  // Same outcome vocabulary as the framed blocks + summary:
-  // executed / restored-local / restored-remote / up-to-date /
-  // failed / skipped.
-  const status =
-    o.status === 'cache-hit'
-      ? o.restored === false
-        ? 'up-to-date'
-        : 'restored-local'
-      : o.status === 'cache-hit-remote'
-        ? o.restored === false
-          ? 'up-to-date'
-          : 'restored-remote'
-        : o.status === 'success'
-          ? 'executed'
-          : o.status === 'failed'
-            ? `failed (exit ${o.exitCode})`
-            : o.status
-  return {
-    task: o.taskId,
-    status,
-    duration: `${o.durationMs}ms`,
-  }
+  return { task: o.taskId, status: outcomeLabel(o), duration: `${o.durationMs}ms` }
+}
+
+/** `(did you mean --concurrency?)` for a flag within two edits of a documented one. */
+function didYouMeanFlag(flag: string): string {
+  const name = flag.replace(/=.*$/, '')
+  const flags = documentedFlags('run')
+  // The usual two edits; a third only between flags that share their
+  // first five characters, so `--retries` reaches `--retry` (the i/y)
+  // while `--zzz` does not reach `--all` — a plain three-edit budget did.
+  const best =
+    nearest(name, flags) ??
+    nearest(
+      name,
+      flags.filter((f) => f.slice(0, 5) === name.slice(0, 5)),
+      3,
+    )
+  return best === undefined ? '' : ` (did you mean ${best}?)`
 }