@vzn/vx 0.0.649 → 0.0.651

package/src/cli/lock.ts

@@ -8,10 +8,16 @@ import path from 'node:path'
 import type { ProjectConfig } from '../config.js'
 import { flagHint, formatValue, refuse, refusedWord, seeHelp } from './help.js'
 import { buildTaskGraph, expandRequested, isDefaultBuild } from '../graph/index.js'
-import { applyGraphStage, discoverProjects, hasHook, loadProjects } from '../orchestrator/index.js'
+import {
+  applyGraphStage,
+  claimedDigests,
+  discoverProjects,
+  fingerprintClaims,
+  hasHook,
+  loadProjects,
+} from '../orchestrator/index.js'
 import { resolveSetting, runRules } from '../settings.js'
 import {
-  refusalNotice,
   DOT_VX_GITATTRIBUTES,
   fsRefusalHint,
   isFsRefusal,
@@ -23,11 +29,11 @@ import {
   type UserError,
   secretMask,
   type SecretMask,
-  ui,
-  sayNotice,
   refuseSymlink,
   writeNoFollow,
 } from '../util/index.js'
+import * as ui from '../ui/index.js'
+import { refusalNotice, sayNotice } from '../ui/index.js'
 import {
   ConfigsRefused,
   findProjectConfigs,
@@ -43,6 +49,11 @@ import {
   checkDependencyRules,
   computeNestedProjectDirs,
   writeLockfile,
+  DEPENDENCIES_LOCK_NAME,
+  dependenciesLock,
+  parseDependenciesLock,
+  writeDependenciesLock,
+  type DependenciesLock,
   type Lockfile,
   type ProjectMeta,
 } from '../workspace/index.js'
@@ -140,6 +151,7 @@ async function audit(root: string, warn: (message: string) => void): Promise<Gra
     reviewFiles: true,
     strayReviews: [],
     shadowed: [],
+    dependencies: null,
   }
   try {
     const { workspaceConfig, plugins, cacheDir } = await loadCliWorkspace(root)
@@ -178,6 +190,7 @@ async function audit(root: string, warn: (message: string) => void): Promise<Gra
     })
     for (const entry of projects.values()) resolved.set(entry.name, entry.config)
     out.loaded = true
+    out.dependencies = await dependenciesOf(root, out.all, plugins, cacheDir, warn)
     checkBracketLiterals(root, projects.values())
     const names = new Set<string>()
     for (const entry of projects.values()) {
@@ -252,6 +265,30 @@ interface GraphCheck {
   strayReviews: string[]
   /** Config files a higher-precedence one beside them hides (`findProjectConfigs`). */
   shadowed: { file: string; read: string }[]
+  /** What the dependencies resolve to here; null when the configs did not load. */
+  dependencies: DependenciesLock | null
+}
+
+/** Each project's edges and each claimed file's digests, as `--affected` reads them back. */
+async function dependenciesOf(
+  root: string,
+  all: readonly ProjectMeta[],
+  plugins: Parameters<typeof fingerprintClaims>[0],
+  cacheDir: string,
+  warn: (message: string) => void,
+): Promise<DependenciesLock> {
+  const ctx = {
+    workspaceRoot: root,
+    cacheDir,
+    warn,
+    projects: all.map((p) => ({ name: p.name, dir: p.dir })),
+  }
+  const files = new Map<string, NonNullable<Awaited<ReturnType<typeof claimedDigests>>>>()
+  for (const [file, plugin] of fingerprintClaims(plugins)) {
+    const answer = await claimedDigests(plugin, file, ctx)
+    if (answer !== undefined) files.set(file, answer)
+  }
+  return dependenciesLock(root, all, files)
 }
 
 function configured(all: readonly ProjectMeta[]): ConfiguredMeta[] {
@@ -415,6 +452,7 @@ async function writeLock(
     return 1
   }
   await writeLockfile(root, check.fresh)
+  if (check.dependencies !== null) await writeDependenciesLock(root, check.dependencies)
   await writeIfMissing(path.join(root, '.vx', '.gitattributes'), DOT_VX_GITATTRIBUTES)
   const n = metas.length
   say(`${n} project config${n === 1 ? '' : 's'} → ${LOCKFILE_NAME}${bareNote(bare)}`)
@@ -517,7 +555,7 @@ async function checkLock(root: string, json: boolean): Promise<number> {
         notAudited: bare.length,
         problems,
       }
-      process.stdout.write(`${JSON.stringify(out)}\n`)
+      ui.data('out', `${JSON.stringify(out)}\n`)
     }
     return problems.length === 0 ? 0 : 1
   }
@@ -600,6 +638,18 @@ async function checkLock(root: string, json: boolean): Promise<number> {
       failures.push(`the lock holds ${what}, which has no vx.config now — run 'vx lock'`)
     }
   }
+  // Named only over a lock that holds: a config drift moves the record too.
+  if (check.dependencies !== null && failures.length === 0) {
+    const text = await Bun.file(path.join(root, DEPENDENCIES_LOCK_NAME))
+      .bytes()
+      .catch(() => null)
+    // Compared as JSON: a formatter may lay the file out its own way.
+    const read = parseDependenciesLock(text)
+    if (read === null || !Bun.deepEquals(read, check.dependencies, true))
+      failures.push(
+        `${DEPENDENCIES_LOCK_NAME} ${text === null ? 'is missing' : 'is not what the dependencies resolve to here'} — run 'vx lock'`,
+      )
+  }
   if (json)
     // Root-relative, as every other problem: the loader names the absolute path.
     return answer([

package/src/cli/plan-format.ts

@@ -1,45 +1,37 @@
 // Formatters for `--dry` (human / JSON).
 
 import type { AffectedReason, CacheStatus, RunPlan } from '../orchestrator/index.js'
-import { skippedReason } from '../report/index.js'
-import {
-  formatBytes,
-  formatElapsed,
-  maskedCommand,
-  paint,
-  SUCCESS,
-  ui,
-  WARN,
-  type ColorSupport,
-} from '../util/index.js'
+import { computeReverseDepCount } from '../graph/index.js'
+import { planList, type PlannedRow, skippedReason } from '../report/index.js'
+import { formatBytes, formatElapsed, maskedCommand } from '../util/index.js'
+import * as ui from '../ui/index.js'
+import type { ColorSupport } from '../ui/index.js'
 
 /**
- * Human-readable preview. One line per real task (groups hidden, same
- * as the live runner), tagged with predicted cache outcome. A would-run
- * task with recorded history also shows its typical duration (~p50).
+ * `vx run --dry`'s screen: the `Plan` panel, each task on the running
+ * list's grid (what the run would do with it, its usual time, where it
+ * would run), then the counts and the predicted time.
  *
- *   would run:
- *     ✓  @vzn/vx#lint       cache hit (local)        abc12345
- *     ↓  @vzn/vx#test       cache hit (remote)       def67890
- *     ▶  @vzn/vx#build      cache miss — would exec  fedcba98  ~1.20s
+ *   ─ Plan 3 ─────────────────────────────────────────────────────
+ *         time   usual status  cache      cpu    mem outputs  blocks worker       task
+ *    ⇢                 cached  local                                 local        @vzn/vx#lint
+ *    ⇣                 cached  remote                     12MB       local        @vzn/vx#test
+ *    ⏺︎               ~1.2s run     miss                                  local        @vzn/vx#build
  *
- *   3 task(s) planned, 2 cache hits (1 local, 1 remote), 1 would run.
- *   predicted: ~1.20s wall · ~1.20s total execution
+ *     tasks      3 planned · 2 cache hits (1 local, 1 remote, 12MB) · 1 would run
+ *     predicted  ~1.20s wall · ~1.20s total execution
  */
-export function formatPlanText(plan: RunPlan, c: ColorSupport = { enabled: false }): string {
+export function planReport(plan: RunPlan): ui.Block {
   // A group the platform skip reaches is still a group: it runs nothing.
   const real = plan.tasks.filter(
     (t) =>
       t.cacheStatus !== 'group' &&
       (t.cacheStatus !== 'skipped' || t.node.config.exec !== undefined),
   )
-  const dim = (s: string): string => paint('', s, c, { dim: true })
-  if (real.length === 0) return `${dim('No tasks planned.')}\n`
-
-  const idWidth = Math.max(...real.map((t) => t.node.id.length))
-  const tagWidth = 24
+  if (real.length === 0) return ui.section('Plan', ui.text('No tasks planned.'))
 
-  const lines: string[] = [paint('', 'would run:', c, { bold: true })]
+  const blocks = downstream(plan)
+  const rows: PlannedRow[] = []
   let local = 0
   let remote = 0
   let miss = 0
@@ -50,33 +42,28 @@ export function formatPlanText(plan: RunPlan, c: ColorSupport = { enabled: false
   for (const t of real) {
     // `@noop`: the run succeeds it without running, whatever its key says.
     const skipped = t.executor === 'noop' && t.cacheStatus !== 'skipped'
-    const sym = skipped ? '·' : symbolFor(t.cacheStatus)
-    const desc = skipped
-      ? 'noop — would not run'
-      : t.cacheStatus === 'skipped'
-        ? `skipped — ${skippedReason(t)}`
-        : describe(t.cacheStatus)
-    const shortHash = t.hash ? t.hash.slice(0, 8) : ''
+    const notes: string[] = []
+    if (t.cacheStatus === 'skipped') notes.push(skippedReason(t))
+    const desc = shownDescription(t)
+    if (desc !== undefined && desc !== '') notes.push(desc)
+    if (t.affected !== undefined) notes.push(`affected: ${describeReason(t.affected)}`)
     const executes = !skipped && (t.cacheStatus === 'miss' || t.cacheStatus === 'no-cache')
-    const eta = executes && t.p50Ms !== undefined ? `  ~${formatElapsed(t.p50Ms)}` : ''
-    // Placement, by EXECUTOR NAME rather than a local/remote word: the
-    // summary line below already spends "local" and "remote" on the cache
-    // tier, and a task placed on a named executor is what the reader can
-    // act on. Present only when the workspace declared a choice.
-    const where = t.executor !== undefined ? `  @${t.executor}` : ''
-    const hue = skipped ? '' : HUE[t.cacheStatus]
-    lines.push(
-      `  ${paint(hue, sym, c, { dim: hue === '' })}  ${ui.inline(ui.id(t.node.id), c)}${' '.repeat(idWidth - t.node.id.length)}  ${paint(hue, desc.padEnd(tagWidth), c, { dim: hue === '' })}  ${dim(shortHash)}${dim(eta)}${where}`,
-    )
-    // Optional one-line description from the task config, indented
-    // under the id so the eye picks up the task → blurb mapping.
-    const taskDesc = shownDescription(t)
-    if (taskDesc) {
-      lines.push(`     ${' '.repeat(idWidth)}  ${dim(taskDesc)}`)
-    }
-    if (t.affected !== undefined) {
-      lines.push(`     ${' '.repeat(idWidth)}  ${dim(`affected: ${describeReason(t.affected)}`)}`)
-    }
+    rows.push({
+      node: t.node,
+      ...(skipped ? NOOP : LOOK[t.cacheStatus]),
+      ...(executes && t.p50Ms !== undefined ? { usualMs: t.p50Ms } : {}),
+      ...(t.cacheStatus === 'hit-remote' && t.remoteBytes !== undefined
+        ? { outputBytes: t.remoteBytes }
+        : {}),
+      blocks: blocks.get(t.node.id) ?? 0,
+      // Placement by executor name; a task that will not run reaches no
+      // machine, as a skip's row in the run has none.
+      worker:
+        skipped || t.cacheStatus === 'skipped' || t.cacheStatus === 'not-started'
+          ? ''
+          : (t.executor ?? 'local'),
+      note: notes.join(' · '),
+    })
     if (skipped) noop++
     else if (t.cacheStatus === 'hit-local') local++
     else if (t.cacheStatus === 'hit-remote') remote++
@@ -94,15 +81,14 @@ export function formatPlanText(plan: RunPlan, c: ColorSupport = { enabled: false
     hitParts.push(bytes > 0 ? `${remote} remote, ${formatBytes(bytes)}` : `${remote} remote`)
   }
   const hits = local + remote
-  const summary: string[] = [`${real.length} task(s) planned`]
+  const summary: string[] = [`${real.length} planned`]
   if (hits > 0) summary.push(`${hits} cache hit${hits === 1 ? '' : 's'} (${hitParts.join(', ')})`)
   if (miss > 0) summary.push(`${miss} would run`)
   if (nocache > 0) summary.push(`${nocache} no-cache`)
   if (noop > 0) summary.push(`${noop} noop`)
   if (idle > 0) summary.push(`${idle} not started`)
   if (platform > 0) summary.push(`${platform} skipped`)
-  lines.push('')
-  lines.push(dim(summary.join(', ') + '.'))
+  const facts: ui.FieldRow[] = [['tasks', summary.join(' · ')]]
 
   // `--cache-download` is invisible without this: the eligibility gate silently
   // keeps producers eager, so a user who asked for `none` and got no
@@ -111,16 +97,13 @@ export function formatPlanText(plan: RunPlan, c: ColorSupport = { enabled: false
   const deferred = real.filter((t) => t.download === 'deferred')
   const downgrades = plan.downloadDowngrades ?? []
   if (deferred.length > 0 || downgrades.length > 0) {
-    lines.push('')
-    lines.push(
-      dim(
-        `download: ${deferred.length} task(s) would keep outputs remote` +
-          (downgrades.length > 0 ? `, ${downgrades.length} kept eager:` : '.'),
-      ),
-    )
-    for (const d of downgrades.slice(0, 3))
-      lines.push(`    ${ui.inline(ui.id(d.taskId), c)} ${dim(`— ${d.reason}`)}`)
-    if (downgrades.length > 3) lines.push(dim(`    …and ${downgrades.length - 3} more`))
+    facts.push([
+      'download',
+      `${deferred.length} task(s) would keep outputs remote` +
+        (downgrades.length > 0 ? `, ${downgrades.length} kept eager:` : '.'),
+      ...downgrades.slice(0, 3).map((d) => [ui.id(d.taskId), ui.dim(` — ${d.reason}`)]),
+      ...(downgrades.length > 3 ? [`…and ${downgrades.length - 3} more`] : []),
+    ])
   }
 
   // Time prediction — only when history gave us something to say: at least
@@ -128,15 +111,63 @@ export function formatPlanText(plan: RunPlan, c: ColorSupport = { enabled: false
   const p = plan.predicted
   const executes = miss + nocache
   if (p !== undefined && executes > 0 && executes > p.unknownCount) {
-    const parts = [`predicted: ~${formatElapsed(p.wallMs)} wall`]
+    const parts = [`~${formatElapsed(p.wallMs)} wall`]
     parts.push(`~${formatElapsed(p.workMs)} total execution`)
     if (p.unknownCount > 0) {
       parts.push(`${p.unknownCount} task${p.unknownCount === 1 ? '' : 's'} without history (+?)`)
     }
-    lines.push(dim(parts.join(' · ')))
+    facts.push(['predicted', parts.join(' · ')])
   }
-  return lines.join('\n') + '\n'
+  return ui.section('Plan', String(real.length), planList(rows), ui.fields(facts))
+}
+
+/**
+ * How many tasks are downstream of each, all of them (groups too), by the
+ * run's own count: a closure walked per task was quadratic, and a 10,000
+ * task chain's `--dry` spent 7 s here.
+ */
+function downstream(plan: RunPlan): Map<string, number> {
+  return computeReverseDepCount(
+    new Map(plan.tasks.map((t) => [t.node.id, { ...t.node, deps: [...t.deps] }])),
+  )
+}
+
+/** The plan as plain text: what a pipe, a test or `grep` reads. */
+export function formatPlanText(plan: RunPlan, c: ColorSupport = { enabled: false }): string {
+  return ui.render([planReport(plan)], c)
+}
+
+type Look = Pick<PlannedRow, 'glyph' | 'status' | 'tone' | 'cache' | 'cacheTone'>
+
+/** Each outcome on the run's grid: its glyph and words, as the run would print them. */
+const LOOK: Record<CacheStatus, Look> = {
+  'hit-local': {
+    glyph: '\u21e2',
+    status: 'cached',
+    tone: 'ok',
+    cache: 'local',
+    cacheTone: 'local',
+  },
+  'hit-remote': {
+    glyph: '\u21e3',
+    status: 'cached',
+    tone: 'ok',
+    cache: 'remote',
+    cacheTone: 'remote',
+  },
+  miss: { glyph: '\u23fa\ufe0e', status: 'run', tone: 'info', cache: 'miss', cacheTone: 'muted' },
+  'no-cache': {
+    glyph: '\u23fa\ufe0e',
+    status: 'run',
+    tone: 'info',
+    cache: 'no-cache',
+    cacheTone: 'muted',
+  },
+  group: { glyph: '\u25cb', status: 'group', tone: 'muted', cache: '', cacheTone: '' },
+  'not-started': { glyph: '\u25cc', status: 'not run', tone: 'muted', cache: '', cacheTone: '' },
+  skipped: { glyph: '\u2298', status: 'skipped', tone: 'warn', cache: '', cacheTone: '' },
 }
+const NOOP: Look = { glyph: '\u00b7', status: 'noop', tone: 'muted', cache: '', cacheTone: '' }
 
 /** One `--affected --dry` reason line: the cause, then the edge chain that carried it. */
 function describeReason(r: AffectedReason): string {
@@ -219,52 +250,3 @@ export function formatPlanJson(
     }) + '\n'
   )
 }
-
-/** A hit is green, a task that would run is yellow, the rest dim. */
-const HUE: Record<CacheStatus, string> = {
-  'hit-local': SUCCESS,
-  'hit-remote': SUCCESS,
-  miss: WARN,
-  'no-cache': WARN,
-  group: '',
-  'not-started': '',
-  skipped: '',
-}
-
-function symbolFor(s: CacheStatus): string {
-  switch (s) {
-    case 'hit-local':
-      return '✓'
-    case 'hit-remote':
-      return '↓'
-    case 'miss':
-      return '▶'
-    case 'no-cache':
-      return '∅'
-    case 'group':
-      return '○'
-    case 'not-started':
-      return '−'
-    case 'skipped':
-      return '·'
-  }
-}
-
-function describe(s: CacheStatus): string {
-  switch (s) {
-    case 'hit-local':
-      return 'cache hit (local)'
-    case 'hit-remote':
-      return 'cache hit (remote)'
-    case 'miss':
-      return 'cache miss — would exec'
-    case 'no-cache':
-      return 'no-cache (would exec)'
-    case 'group':
-      return 'group task'
-    case 'not-started':
-      return 'not started (unneeded)'
-    case 'skipped':
-      return 'skipped'
-  }
-}

package/src/cli/plugin-commands.ts

@@ -7,6 +7,7 @@
 // reports an unknown command as it always did. Core's verbs are matched
 // before this is asked, so a plugin cannot shadow `run`.
 
+import { indexDb } from '../cache/index.js'
 import type { CachePolicy, PluginCache, ResolvedRemote } from '../cache/index.js'
 import type { WorkspaceConfig } from '../config.js'
 import type {
@@ -23,9 +24,9 @@ import {
   maskedLine,
   SecretBroker,
   thrownMessage,
-  ui,
   UserError,
 } from '../util/index.js'
+import * as ui from '../ui/index.js'
 import { resolveSetting } from '../settings.js'
 
 export interface ResolvedPluginCommand {
@@ -184,7 +185,7 @@ async function verbCache(
     remotes,
   })
   await openVerbRemotes(remotes, openRemotes)
-  return pluginCache(plugin, { db: localCache.dbHandle(), policy: VERB_POLICY, remotes, scope })
+  return pluginCache(plugin, { db: indexDb(localCache), policy: VERB_POLICY, remotes, scope })
 }
 
 /**
@@ -283,7 +284,12 @@ async function openVerbRemotes(
   await open(remotes, ci, new SecretBroker(ci, warn))
 }
 
-function lazyArtifacts(open: () => Promise<TaskArtifacts>): TaskArtifacts {
+/**
+ * `Required`, so a member `TaskArtifacts` gains cannot be left out here:
+ * this wrapper dropped `uploaded`, and `vx dte worker` took every upload a
+ * remote reset as landed (CI, 2026-10-29).
+ */
+function lazyArtifacts(open: () => Promise<TaskArtifacts>): Required<TaskArtifacts> {
   let opened: Promise<TaskArtifacts> | undefined
   const artifacts = (): Promise<TaskArtifacts> => (opened ??= open())
   return {
@@ -292,6 +298,7 @@ function lazyArtifacts(open: () => Promise<TaskArtifacts>): TaskArtifacts {
     output: async (key) => (await artifacts()).output(key),
     share: async (key) => (await artifacts()).share(key),
     resend: async (key) => (await artifacts()).resend(key),
+    uploaded: async (key) => (await artifacts()).uploaded?.(key),
   }
 }
 

package/src/cli/plugin-templates.ts

@@ -15,8 +15,8 @@ export const PLUGIN_TEMPLATES: Readonly<Record<string, { plugin: string; test: s
   },
   commands: {
     plugin:
-      "// `commands`: a CLI verb. `vx cache-dir` prints where this workspace's cache\n// lives. The verb's return value is the exit code.\nimport { definePlugin, type VxPlugin } from '@vzn/vx'\n\nexport function cacheDirVerb(): VxPlugin {\n  return definePlugin(import.meta, {\n    commands: {\n      'cache-dir': {\n        description: \"print this workspace's cache directory\",\n        run(argv, ctx) {\n          if (argv.length > 0) {\n            console.error(`vx cache-dir: takes no arguments, got ${argv.join(' ')}`)\n            return 2\n          }\n          console.log(ctx.cacheDir)\n          return 0\n        },\n      },\n    },\n  })\n}\n",
-    test: "// A test for the example `commands` plugin beside it: the verb is called\n// the way vx calls it, with the context vx hands it. `bun test` runs it.\nimport { expect, it, spyOn } from 'bun:test'\nimport { cacheDirVerb } from './commands.ts'\n\nconst verb = cacheDirVerb().commands!['cache-dir']!\nconst ctx = {\n  workspaceRoot: '/ws',\n  cacheDir: '/ws/.vx/cache',\n  warn() {},\n  concurrency: 1,\n  vx: ['vx'],\n  cache: {\n    get: async () => null,\n    put: async () => {},\n    has: async () => null,\n    hasMany: async () => null,\n    getRun: async () => null,\n  },\n  artifacts: {\n    save: async () => {},\n    restore: async () => null,\n    output: async () => null,\n    share: async () => false,\n    resend: async () => false,\n  },\n  artifactsFor: () => ({\n    save: async () => {},\n    restore: async () => null,\n    output: async () => null,\n    share: async () => false,\n    resend: async () => false,\n  }),\n}\n\nit('prints the cache directory; an argument is exit 2', async () => {\n  const out = spyOn(console, 'log').mockImplementation(() => {})\n  const err = spyOn(console, 'error').mockImplementation(() => {})\n  try {\n    expect(await verb.run([], ctx)).toBe(0)\n    expect(out.mock.calls).toEqual([['/ws/.vx/cache']])\n    expect(await verb.run(['x'], ctx)).toBe(2)\n    expect(err.mock.calls).toEqual([['vx cache-dir: takes no arguments, got x']])\n  } finally {\n    out.mockRestore()\n    err.mockRestore()\n  }\n})\n",
+      "// `commands`: a CLI verb. `vx cache-dir` prints where this workspace's cache\n// lives. The verb's return value is the exit code.\nimport { definePlugin, ui, type VxPlugin } from '@vzn/vx'\n\nexport function cacheDirVerb(): VxPlugin {\n  return definePlugin(import.meta, {\n    commands: {\n      'cache-dir': {\n        description: \"print this workspace's cache directory\",\n        run(argv, ctx) {\n          if (argv.length > 0) {\n            ui.say('error', `vx cache-dir: takes no arguments, got ${argv.join(' ')}`)\n            return 2\n          }\n          ui.data('out', `${ctx.cacheDir}\\n`)\n          return 0\n        },\n      },\n    },\n  })\n}\n",
+    test: "// A test for the example `commands` plugin beside it: the verb is called\n// the way vx calls it, with the context vx hands it. `bun test` runs it.\nimport { expect, it, spyOn } from 'bun:test'\nimport { cacheDirVerb } from './commands.ts'\n\nconst verb = cacheDirVerb().commands!['cache-dir']!\nconst ctx = {\n  workspaceRoot: '/ws',\n  cacheDir: '/ws/.vx/cache',\n  warn() {},\n  concurrency: 1,\n  vx: ['vx'],\n  cache: {\n    get: async () => null,\n    put: async () => {},\n    has: async () => null,\n    hasMany: async () => null,\n    getRun: async () => null,\n  },\n  artifacts: {\n    save: async () => {},\n    restore: async () => null,\n    output: async () => null,\n    share: async () => false,\n    resend: async () => false,\n  },\n  artifactsFor: () => ({\n    save: async () => {},\n    restore: async () => null,\n    output: async () => null,\n    share: async () => false,\n    resend: async () => false,\n  }),\n}\n\nit('prints the cache directory; an argument is exit 2', async () => {\n  const out = spyOn(process.stdout, 'write').mockImplementation(() => true)\n  const err = spyOn(process.stderr, 'write').mockImplementation(() => true)\n  try {\n    expect(await verb.run([], ctx)).toBe(0)\n    expect(out.mock.calls).toEqual([['/ws/.vx/cache\\n']])\n    expect(await verb.run(['x'], ctx)).toBe(2)\n    // On CI the line is coloured: the words are what this asserts.\n    expect(err.mock.calls.map(([l]) => Bun.stripANSI(String(l)))).toEqual([\n      'vx cache-dir: takes no arguments, got x\\n',\n    ])\n  } finally {\n    out.mockRestore()\n    err.mockRestore()\n  }\n})\n",
   },
   executor: {
     plugin:

package/src/cli/run.ts

@@ -19,17 +19,12 @@ import {
   parseCachePolicy,
 } from '../cache/index.js'
 import { affectedFilterFor, findCwdSelection, pickTask, resolveFilters } from './select.js'
-import { nxTargetHint, taskNamesHere } from './task-verb.js'
-import {
-  detectColors,
-  envFlagOn,
-  hasControl,
-  parseDecimalInt,
-  sayNotice,
-  sayLine,
-} from '../util/index.js'
+import { nxTargetHint, taskNamesHere, undeclaredTasks } from './task-verb.js'
+import { envFlagOn, hasControl, parseDecimalInt } from '../util/index.js'
+import * as ui from '../ui/index.js'
+import { sayNotice, sayLine } from '../ui/index.js'
 import { kindHint, parseSettingValue, type Setting, SETTINGS, settingRefusal } from '../settings.js'
-import { formatPlanJson, formatPlanText } from './plan-format.js'
+import { formatPlanJson, planReport } from './plan-format.js'
 
 export interface RunArgs {
   /** Failure propagation (`--continue[=never|deps-ok|always]`). */
@@ -80,6 +75,12 @@ export interface RunArgs {
    * `defaultAffectedBase`). Any other string is an explicit git ref.
    */
   affected: string | undefined
+  /**
+   * A bare `--affected` or `--profile` followed by a word: the word is read
+   * as a task, and when no project declares it the refusal names the `=`
+   * form the user likely meant.
+   */
+  spaced?: { flag: '--affected' | '--profile'; value: string }
   error?: string
 }
 
@@ -154,6 +155,12 @@ export function parseRunArgs(args: readonly string[], verb: 'run' | 'watch' = 'r
   let noCacheFlag = false
   let forceFlag = false
 
+  // Its value optional, the flag cannot take the next word: `--affected
+  // main build` reads `main` as a task, so only a refusal of it says why.
+  const spacedValue = (flag: '--affected' | '--profile', next: string | undefined): void => {
+    if (next !== undefined && !next.startsWith('-')) out.spaced ??= { flag, value: next }
+  }
+
   for (let i = 0; i < before.length; i++) {
     const a = before[i]
     if (a === '--filter' || a?.startsWith('--filter=')) {
@@ -294,6 +301,7 @@ export function parseRunArgs(args: readonly string[], verb: 'run' | 'watch' = 'r
       out.dry = fmt
     } else if (a === '--profile') {
       out.profile = 'profile.json'
+      spacedValue('--profile', before[i + 1])
     } else if (a?.startsWith('--profile=')) {
       // An optional-value flag: an empty `=` means "no value given", so it
       // takes the same documented default as the bare form. Resolving ''
@@ -302,6 +310,7 @@ export function parseRunArgs(args: readonly string[], verb: 'run' | 'watch' = 'r
       out.profile = a.slice('--profile='.length) || 'profile.json'
     } else if (a === '--affected') {
       out.affected = ''
+      spacedValue('--affected', before[i + 1])
     } else if (a?.startsWith('--affected=')) {
       out.affected = a.slice('--affected='.length)
     } else if (a === '--poll') {
@@ -505,6 +514,8 @@ export async function resolveRunOptions(
       // `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.
+      const typo = await undeclaredTasks(bareTasks, cwd)
+      if (typo !== undefined) return { error: typo, code: 'VX_E_UNKNOWN_TASK' }
       if (anchoredTasks.length === 0) return { nothingSelected: resolved.empty }
       sayNotice('info', 'vx run', `${resolved.empty} — running ${anchoredTasks.join(', ')} only`)
       projects = []
@@ -587,6 +598,8 @@ export async function runCmd(args: readonly string[]): Promise<number> {
   }
 
   const cwd = process.cwd()
+  const unknownTask = async (message: string): Promise<number> =>
+    refuse('run', args, `${message}${await spacedHint(parsed, cwd)}`, 'VX_E_UNKNOWN_TASK')
   if (parsed.profile !== undefined) {
     const problem = profileProblem(cwd, parsed.profile)
     if (problem !== undefined) return refuse('run', args, problem, 'VX_E_USAGE')
@@ -647,12 +660,14 @@ export async function runCmd(args: readonly string[]): Promise<number> {
 
   const scopeOut: { affectedBase?: string } = {}
   const resolved = await resolveRunOptions(parsed, cwd, tasks, 'run', scopeOut)
-  if ('error' in resolved) return refuse('run', args, resolved.error, resolved.code ?? 'VX_E_USAGE')
+  if ('error' in resolved)
+    return resolved.code === 'VX_E_UNKNOWN_TASK'
+      ? unknownTask(resolved.error)
+      : refuse('run', args, resolved.error, resolved.code ?? 'VX_E_USAGE')
   // `--dry=json` prints a plan even when there is nothing to run: a script
   // reading stdout broke exactly then (Growth, 2026-10-16).
   const nothingToRun = (): 0 => {
-    if (parsed.dry === 'json')
-      process.stdout.write(formatPlanJson({ tasks: [] }, scopeOut.affectedBase))
+    if (parsed.dry === 'json') ui.data('out', formatPlanJson({ tasks: [] }, scopeOut.affectedBase))
     return 0
   }
   if ('nothingSelected' in resolved) {
@@ -676,11 +691,8 @@ export async function runCmd(args: readonly string[]): Promise<number> {
     const plan = await planRun(opts)
     // Refused as a run refuses: `--dry=json` gets the error document.
     if (plan.unresolvedTasks !== undefined && plan.unresolvedTasks.length > 0) {
-      return refuse(
-        'run',
-        args,
+      return unknownTask(
         `no projects declare task(s): ${plan.unresolvedTasks.join(', ')}.${plan.unresolvedHint ?? ''}`,
-        'VX_E_UNKNOWN_TASK',
       )
     }
     if (plan.tasks.length === 0) {
@@ -694,17 +706,12 @@ export async function runCmd(args: readonly string[]): Promise<number> {
         sayNotice('info', 'vx run', `no affected project declares task(s): ${tasks.join(', ')}`)
         return nothingToRun()
       }
-      return refuse(
-        'run',
-        args,
-        `no projects declare task(s): ${tasks.join(', ')}`,
-        'VX_E_UNKNOWN_TASK',
-      )
+      return unknownTask(`no projects declare task(s): ${tasks.join(', ')}`)
     }
     if (parsed.dry === 'json') {
-      process.stdout.write(formatPlanJson(plan, scopeOut.affectedBase))
+      ui.data('out', formatPlanJson(plan, scopeOut.affectedBase))
     } else {
-      process.stdout.write(formatPlanText(plan, detectColors(process.stdout)))
+      ui.print('out', planReport(plan))
     }
     return 0
   }
@@ -715,12 +722,24 @@ export async function runCmd(args: readonly string[]): Promise<number> {
   // is no whole-run delegation seam to consult.
   const summary = await runOrchestrator(opts)
   if (summary.refused !== undefined) {
-    const unknown = summary.refused.startsWith('no projects declare')
-    return refuse('run', args, summary.refused, unknown ? 'VX_E_UNKNOWN_TASK' : 'VX_E_REFUSED')
+    return summary.refused.startsWith('no projects declare')
+      ? unknownTask(summary.refused)
+      : refuse('run', args, summary.refused, 'VX_E_REFUSED')
   }
   return summary.ok ? 0 : 1
 }
 
+/**
+ * The `=` form a refused task name was likely meant as: the word after a
+ * bare `--affected` or `--profile`, when no project declares it.
+ */
+export async function spacedHint(parsed: RunArgs, cwd: string): Promise<string> {
+  const s = parsed.spaced
+  if (s === undefined || (await undeclaredTasks([s.value], cwd)) === undefined) return ''
+  const what = s.flag === '--affected' ? 'base' : 'file'
+  return ` \`${s.flag}\` takes its ${what} with '=': ${s.flag}=${s.value}`
+}
+
 /**
  * Why `--profile` cannot write `target`, or undefined. Asked before the
  * run: a directory named as the file died with EISDIR only after it. A