@vzn/vx 0.0.637 → 0.0.639

package/src/cli/plan-format.ts

@@ -1,4 +1,4 @@
-// Formatters for `--dry-run` (human / JSON) and `--graph` (DOT).
+// Formatters for `--dry` (human / JSON).
 
 import type { AffectedReason, CacheStatus, RunPlan } from '../orchestrator/index.js'
 import { formatElapsed, maskedCommand } from '../util/index.js'
@@ -9,7 +9,7 @@ import { formatElapsed, maskedCommand } from '../util/index.js'
  * task with recorded history also shows its typical duration (~p50).
  *
  *   would run:
- *     ◉  @vzn/vx#lint       cache hit (local)        abc12345
+ *     ✓  @vzn/vx#lint       cache hit (local)        abc12345
  *     ↓  @vzn/vx#test       cache hit (remote)       def67890
  *     ▶  @vzn/vx#build      cache miss — would exec  fedcba98  ~1.20s
  *
@@ -33,7 +33,7 @@ export function formatPlanText(plan: RunPlan): string {
   for (const t of real) {
     // `@noop`: the run succeeds it without running, whatever its key says.
     const skipped = t.executor === 'noop'
-    const sym = skipped ? '∅' : symbolFor(t.cacheStatus)
+    const sym = skipped ? '·' : symbolFor(t.cacheStatus)
     const desc = skipped ? 'noop — would not run' : describe(t.cacheStatus)
     const shortHash = t.hash ? t.hash.slice(0, 8) : ''
     const executes = !skipped && (t.cacheStatus === 'miss' || t.cacheStatus === 'no-cache')
@@ -118,9 +118,11 @@ function describeReason(r: AffectedReason): string {
           ? `a ^ edge passes changed package ${r.project}`
           : r.kind === 'input'
             ? `${r.file} changed (an input)`
-            : r.file !== undefined
-              ? `${r.file} changed (in its project)`
-              : 'its project changed as a whole'
+            : r.kind === 'workspace'
+              ? `${r.file} changed (workspace-wide)`
+              : r.file !== undefined
+                ? `${r.file} changed (in its project)`
+                : 'its project changed as a whole'
   return r.via === undefined ? cause : `${cause}, via ${r.via.join(' ← ')}`
 }
 
@@ -184,52 +186,16 @@ export function formatPlanJson(plan: RunPlan, affectedBase?: string): string {
   )
 }
 
-/**
- * Render the task graph as a Graphviz DOT document. Includes group
- * nodes — they're real nodes in the graph (just not real units of
- * work), and a `--graph` consumer wants to see the whole structure.
- *
- * Layout: `rankdir=LR`. Node fillcolor varies by predicted cache
- * status so a quick visual scan tells you which boxes get to skip
- * actual work.
- */
-export function formatGraphDot(plan: RunPlan): string {
-  const lines: string[] = ['digraph TaskGraph {', '  rankdir=LR;', '  node [shape=box];']
-  for (const t of plan.tasks) {
-    const color = dotColor(t.cacheStatus)
-    lines.push(
-      `  ${dotString(t.node.id)} [label=${dotString(`${t.node.id}\n${t.hash.slice(0, 8)}`)}, style="filled", fillcolor="${color}"];`,
-    )
-  }
-  for (const t of plan.tasks) {
-    for (const dep of t.deps) {
-      lines.push(`  ${dotString(dep)} -> ${dotString(t.node.id)};`)
-    }
-  }
-  lines.push('}')
-  return lines.join('\n') + '\n'
-}
-
-/**
- * A DOT double-quoted ID. A task name is any object key in a config, so
- * `"`, `\` and a newline are all reachable; unescaped they end the
- * string early and the document stops parsing. `\n` is DOT's own line
- * break inside a label.
- */
-function dotString(s: string): string {
-  return `"${s.replace(/\\/g, '\\\\').replace(/"/g, '\\"').replace(/\r?\n/g, '\\n')}"`
-}
-
 function symbolFor(s: CacheStatus): string {
   switch (s) {
     case 'hit-local':
-      return '◉'
+      return '✓'
     case 'hit-remote':
       return '↓'
     case 'miss':
       return '▶'
     case 'no-cache':
-      return '·'
+      return '∅'
     case 'group':
       return '○'
     case 'not-started':
@@ -253,20 +219,3 @@ function describe(s: CacheStatus): string {
       return 'not started (unneeded)'
   }
 }
-
-function dotColor(s: CacheStatus): string {
-  switch (s) {
-    case 'hit-local':
-      return '#bbf7d0' // green-200
-    case 'hit-remote':
-      return '#bae6fd' // sky-200
-    case 'miss':
-      return '#fed7aa' // orange-200
-    case 'no-cache':
-      return '#e5e7eb' // gray-200
-    case 'group':
-      return '#f5d0fe' // fuchsia-200
-    case 'not-started':
-      return '#ffffff'
-  }
-}

package/src/cli/plugin-commands.ts

@@ -7,8 +7,10 @@
 // reports an unknown command as it always did. Core's verbs are matched
 // before this is asked, so a plugin cannot shadow `run`.
 
+import type { CachePolicy, PluginCache, ResolvedRemote } from '../cache/index.js'
+import type { WorkspaceConfig } from '../config.js'
 import type { VxPlugin, PluginCommand, CommandContext } from '../orchestrator/index.js'
-import { findWorkspaceRoot } from '../workspace/index.js'
+import { cacheScopeEnvError, findWorkspaceRoot, isCacheScope } from '../workspace/index.js'
 import { machineParallelism, maskedLine } from '../util/index.js'
 import { resolveSetting } from '../settings.js'
 
@@ -39,10 +41,15 @@ export interface UnresolvedPluginCommand {
   loadError: string
 }
 
-async function workspacePlugins(
-  cwd: string,
-): Promise<
-  | { workspaceRoot: string; cacheDir: string; concurrency: number; plugins: readonly VxPlugin[] }
+async function workspacePlugins(cwd: string): Promise<
+  | {
+      workspaceRoot: string
+      cacheDir: string
+      storeRoot: Promise<string | null>
+      workspaceConfig: WorkspaceConfig | null
+      concurrency: number
+      plugins: readonly VxPlugin[]
+    }
   | UnresolvedPluginCommand
   | null
 > {
@@ -62,6 +69,8 @@ async function workspacePlugins(
   return {
     workspaceRoot,
     cacheDir: ws.cacheDir,
+    storeRoot: ws.storeRoot,
+    workspaceConfig: ws.workspaceConfig,
     // What run.ts takes when no --concurrency is given.
     concurrency:
       (resolveSetting('run.concurrency', ws.workspaceConfig).value as number | undefined) ??
@@ -98,13 +107,75 @@ export async function resolvePluginCommand(
         vx: (await import('./upgrade.js')).isCompiledBinary()
           ? [process.execPath]
           : [process.execPath, Bun.main],
-        warn: (m) => process.stderr.write(`${maskedLine(m)}\n`),
+        warn,
+        cache: lazyCache(() => verbCache(ws, plugin.name)),
       },
     }
   }
   return { declaredVerbs: [...declaredVerbs] }
 }
 
+const warn = (m: string): void => {
+  process.stderr.write(`${maskedLine(m)}\n`)
+}
+
+/** Read-only: a verb reads what runs stored, and only a run's policy may write. */
+const VERB_POLICY: CachePolicy = {
+  localRead: true,
+  localWrite: false,
+  remoteRead: true,
+  remoteWrite: false,
+}
+
+/**
+ * The verb's `ctx.cache`: the plugin's entries in the local store, then each
+ * remote the workspace's cache plugins supply, under the run's scope. Opened
+ * on first use, so a verb that never reads it opens nothing.
+ */
+async function verbCache(
+  ws: Exclude<Awaited<ReturnType<typeof workspacePlugins>>, UnresolvedPluginCommand | null>,
+  plugin: string,
+): Promise<PluginCache> {
+  const [{ Cache, pluginCache }, { resolveCache }] = await Promise.all([
+    import('../cache/index.js'),
+    import('../orchestrator/index.js'),
+  ])
+  const envScope = process.env['VX_CACHE_SCOPE'] || undefined
+  if (envScope !== undefined && !isCacheScope(envScope)) throw cacheScopeEnvError()
+  const scope = envScope ?? ws.workspaceConfig?.cache?.scope
+  const localCache = new Cache(
+    ws.cacheDir,
+    { read: true, write: false },
+    ws.workspaceRoot,
+    undefined,
+    'open',
+    await ws.storeRoot,
+  )
+  const remotes: ResolvedRemote[] = []
+  await resolveCache(ws.plugins, {
+    workspaceRoot: ws.workspaceRoot,
+    cacheDir: ws.cacheDir,
+    warn,
+    scope,
+    localCache,
+    policy: VERB_POLICY,
+    remotes,
+  })
+  return pluginCache(plugin, { db: localCache.dbHandle(), policy: VERB_POLICY, remotes, scope })
+}
+
+function lazyCache(open: () => Promise<PluginCache>): PluginCache {
+  let opened: Promise<PluginCache> | undefined
+  const cache = (): Promise<PluginCache> => (opened ??= open())
+  return {
+    get: async (key) => (await cache()).get(key),
+    put: async (key, bytes) => (await cache()).put(key, bytes),
+    has: async (key) => (await cache()).has(key),
+    hasMany: async (keys) => (await cache()).hasMany(keys),
+    getRun: async (name) => (await cache()).getRun(name),
+  }
+}
+
 /** The plugin verbs the workspace around `cwd` declares, in declaration order; none when it does not load. */
 export async function pluginVerbs(cwd = process.cwd()): Promise<string[]> {
   const ws = await workspacePlugins(cwd).catch(() => null)

package/src/cli/plugin-templates.ts

@@ -16,7 +16,7 @@ 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}\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",
+    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}\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",
   },
   executor: {
     plugin:

package/src/cli/run.ts

@@ -1,18 +1,14 @@
-import { appendFileSync, mkdirSync } from 'node:fs'
-import path from 'node:path'
 import { isatty } from 'node:tty'
 import { cacheScopeError, findWorkspaceRoot, isCacheScope } from '../workspace/index.js'
 import { translateForeign } from './foreign-flags.js'
-import { flagHint, formatValue, refuse, seeHelp } from './help.js'
+import { flagHint, refuse, seeHelp } from './help.js'
 import {
   planRun,
-  formatRunReportMarkdown,
-  projectOutcome,
   run as runOrchestrator,
   shellQuote,
   type RunOptions,
 } from '../orchestrator/index.js'
-import type { ContinueMode, TaskOutcome } from '../graph/index.js'
+import type { ContinueMode } from '../graph/index.js'
 import {
   applyCacheFlags,
   type CacheFlags,
@@ -23,9 +19,9 @@ import {
 } from '../cache/index.js'
 import { affectedFilterFor, findCwdSelection, pickTask, resolveFilters } from './select.js'
 import { nxTargetHint, taskNamesHere } from './task-verb.js'
-import { parseDecimalInt } from '../util/index.js'
+import { parseDecimalInt, sayNotice, sayLine } from '../util/index.js'
 import { kindHint, parseSettingValue, type Setting, SETTINGS, settingRefusal } from '../settings.js'
-import { formatGraphDot, formatPlanJson, formatPlanText } from './plan-format.js'
+import { formatPlanJson, formatPlanText } from './plan-format.js'
 
 export interface RunArgs {
   /** Failure propagation (`--continue[=never|deps-ok|always]`). */
@@ -71,10 +67,6 @@ export interface RunArgs {
   forwardArgs: string[]
   verbosity: number
   dry: 'text' | 'json' | undefined
-  /** `--format json`: the run's result document on stdout, every other line on stderr. */
-  format: 'pretty' | 'json'
-  graph: string | undefined
-  summarize: string | undefined
   profile: string | undefined
   /**
    * `--affected[=<base>]`. When undefined the flag wasn't passed.
@@ -82,16 +74,6 @@ export interface RunArgs {
    * `defaultAffectedBase`). Any other string is an explicit git ref.
    */
   affected: string | undefined
-  /** `--tag k=v` pairs (repeatable). Empty key is a parse error. */
-  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
 }
 
@@ -130,9 +112,6 @@ const SETTING_OPTIONS = [
   ['run.timeout', 'timeout'],
   ['run.retries', 'retries'],
   ['run.outputLogs', 'outputLogs'],
-  ['run.killGrace', 'killGrace'],
-  ['run.teardownTimeout', 'teardownTimeout'],
-  ['run.readyNotice', 'readyNotice'],
   ['cache.download', 'download'],
 ] as const satisfies readonly (readonly [string, keyof RunOptions])[]
 
@@ -150,14 +129,8 @@ export function parseRunArgs(rawArgs: readonly string[], verb: 'run' | 'watch' =
     forwardArgs: [],
     verbosity: 0,
     dry: undefined,
-    format: 'pretty',
-    graph: undefined,
-    summarize: undefined,
     profile: undefined,
     affected: undefined,
-    tags: {},
-    report: undefined,
-    reportFile: undefined,
   }
 
   // A Turbo or Nx spelling becomes vx's, or a refusal naming vx's.
@@ -301,58 +274,18 @@ export function parseRunArgs(rawArgs: readonly string[], verb: 'run' | 'watch' =
         return { ...out, error: `--dry must be text or json (got ${fmt})` }
       }
       out.dry = fmt
-    } else if (a === '--format' || a?.startsWith('--format=')) {
-      const f = formatValue(a === '--format' ? before[++i] : a.slice('--format='.length), verb)
-      if (typeof f !== 'string') return { ...out, error: f.error }
-      out.format = f
-    } else if (a === '--graph') {
-      out.graph = ''
-    } else if (a?.startsWith('--graph=')) {
-      out.graph = a.slice('--graph='.length)
-    } else if (a === '--summarize') {
-      out.summarize = ''
-    } else if (a?.startsWith('--summarize=')) {
-      out.summarize = a.slice('--summarize='.length)
     } else if (a === '--profile') {
       out.profile = 'profile.json'
     } 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 ''
       // against cwd would name the cwd DIRECTORY and die with EISDIR after
-      // the whole run — and `--summarize=` already degrades to its default.
+      // the whole run.
       out.profile = a.slice('--profile='.length) || 'profile.json'
     } else if (a === '--affected') {
       out.affected = ''
     } else if (a?.startsWith('--affected=')) {
       out.affected = a.slice('--affected='.length)
-    } else if (a === '--tag' || a?.startsWith('--tag=')) {
-      const raw = a === '--tag' ? before[++i] : a.slice('--tag='.length)
-      if (raw === undefined) return { ...out, error: `${a} requires a value (k=v)` }
-      // Split on the FIRST `=` so values may contain `=` (e.g. a URL).
-      const eq = raw.indexOf('=')
-      if (eq <= 0) return { ...out, error: `--tag must be k=v (got ${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}; a path that starts with - needs --report-file=${v})`,
-        }
-      }
-      out.reportFile = v
-    } else if (a === '--report') {
-      out.report = 'markdown'
-    } else if (a?.startsWith('--report=')) {
-      const fmt = a.slice('--report='.length)
-      if (fmt !== 'markdown') {
-        return { ...out, error: `--report must be markdown (got ${fmt})` }
-      }
-      out.report = fmt
     } else if (verb === 'watch' && a === '--poll') {
       out.poll = true
     } else if (a !== undefined && settingFlagOf(a) !== undefined) {
@@ -400,39 +333,10 @@ export function parseRunArgs(rawArgs: readonly string[], verb: 'run' | 'watch' =
   out.cache = applyCacheFlags(cachePolicy, flags)
   if (!cacheFlag && envSpec === undefined) out.cacheFlags = flags
 
-  if (out.dry !== undefined && out.graph !== undefined) {
-    return { ...out, error: '--dry and --graph are mutually exclusive' }
-  }
-  // Every flag that promises a file or a section about the run: the
-  // planning branch returns before any of them is written, and
-  // `--report-file="$GITHUB_STEP_SUMMARY" --dry` exited 0 having written
-  // nothing (item 992).
-  const needsRun =
-    out.summarize !== undefined ||
-    out.profile !== undefined ||
-    out.report !== undefined ||
-    out.reportFile !== undefined
-  const runOnly = '--summarize / --profile / --report / --report-file need a real run'
-  if (out.dry !== undefined && needsRun) {
-    return { ...out, error: `--dry skips execution; ${runOnly}` }
-  }
-  if (out.graph !== undefined && needsRun) {
-    return { ...out, error: `--graph skips execution; ${runOnly}` }
-  }
-  if (out.format === 'json') {
-    // Each of these prints something else on stdout, which the document owns.
-    if (out.dry !== undefined)
-      return { ...out, error: '--format json runs the tasks; --dry=json prints the plan' }
-    if (out.graph === '')
-      return {
-        ...out,
-        error: '--format json and --graph both print on stdout; give --graph a file',
-      }
-    if (out.report === 'markdown')
-      return {
-        ...out,
-        error: '--format json and --report=markdown both print on stdout; use --report-file',
-      }
+  // A profile is about a run: the planning branch returns before it is
+  // written (item 992).
+  if (out.dry !== undefined && out.profile !== undefined) {
+    return { ...out, error: '--dry skips execution; --profile needs a real run' }
   }
   return out
 }
@@ -556,7 +460,7 @@ export async function resolveRunOptions(
       // 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`)
+      sayNotice('info', 'vx run', `${resolved.empty} — running ${anchoredTasks.join(', ')} only`)
       projects = []
     } else {
       projects = resolved.names
@@ -619,10 +523,7 @@ export async function resolveRunOptions(
   for (const [path, field] of SETTING_OPTIONS) {
     if (parsed.settings[path] !== undefined) Object.assign(opts, { [field]: parsed.settings[path] })
   }
-  if (parsed.summarize !== undefined) opts.summarize = parsed.summarize
-  if (parsed.format === 'json') opts.json = true
   if (parsed.profile !== undefined) opts.profile = parsed.profile
-  if (Object.keys(parsed.tags).length > 0) opts.tags = parsed.tags
 
   return opts
 }
@@ -646,7 +547,7 @@ export async function runCmd(args: readonly string[]): Promise<number> {
   if (tasks.length === 0) {
     // A JSON answer is for a program, which cannot pick from a menu: an
     // agent on a pty waited at the picker forever.
-    const forProgram = parsed.format === 'json' || parsed.dry === 'json'
+    const forProgram = parsed.dry === 'json'
     if (!process.stdin.isTTY || forProgram) {
       const names = await taskNamesHere(cwd)
       const shown = (names ?? []).slice(0, TASKS_SHOWN)
@@ -665,7 +566,7 @@ export async function runCmd(args: readonly string[]): Promise<number> {
     // Every run needs git: refused here, not after the user has chosen.
     const refusal = gitRefusal(await findWorkspaceRoot(cwd))
     if (refusal !== undefined) {
-      process.stderr.write(`${refusal.message}\n`)
+      sayLine('error', refusal.message, 'vx run')
       return 1
     }
     const load = parsed.cacheDir !== undefined ? { cacheDir: parsed.cacheDir } : {}
@@ -679,7 +580,7 @@ export async function runCmd(args: readonly string[]): Promise<number> {
       if ('error' in selected)
         return refuse('run', args, selected.error, selected.code ?? 'VX_E_USAGE')
       if ('empty' in selected) {
-        process.stderr.write(`vx run: ${selected.empty}\n`)
+        sayNotice('info', 'vx run', selected.empty)
         return 0
       }
       only = new Set(selected.names)
@@ -695,7 +596,7 @@ export async function runCmd(args: readonly string[]): Promise<number> {
   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 ('nothingSelected' in resolved) {
-    process.stderr.write(`vx run: ${resolved.nothingSelected}\n`)
+    sayNotice('info', 'vx run', resolved.nothingSelected)
     return 0
   }
   const opts = resolved
@@ -710,48 +611,37 @@ export async function runCmd(args: readonly string[]): Promise<number> {
     ...args.map(shellQuote),
   ].join(' ')
 
-  // Planning paths short-circuit execution. Both build the full task
-  // graph + probe the cache; the difference is just the formatter.
-  if (parsed.dry !== undefined || parsed.graph !== undefined) {
+  // Planning short-circuits execution: the full task graph + a cache probe.
+  if (parsed.dry !== undefined) {
     const plan = await planRun(opts)
+    // Refused as a run refuses: `--dry=json` gets the error document.
     if (plan.unresolvedTasks !== undefined && plan.unresolvedTasks.length > 0) {
-      process.stderr.write(
-        `vx run: no projects declare task(s): ${plan.unresolvedTasks.join(', ')}.${plan.unresolvedHint ?? ''}\n`,
+      return refuse(
+        'run',
+        args,
+        `no projects declare task(s): ${plan.unresolvedTasks.join(', ')}.${plan.unresolvedHint ?? ''}`,
+        'VX_E_UNKNOWN_TASK',
       )
-      return 1
     }
     if (plan.tasks.length === 0) {
       // The run's own line: a dry run that guessed from the scope alone
       // said no affected project declared a task one did (X-141).
       if (plan.noneAffected !== undefined) {
-        process.stderr.write(`${plan.noneAffected}\n`)
+        sayLine('info', plan.noneAffected, 'vx run')
         return 0
       }
       if (opts.selectedByDiff === true) {
-        process.stderr.write(`vx run: no affected project declares task(s): ${tasks.join(', ')}.\n`)
+        sayNotice('info', 'vx run', `no affected project declares task(s): ${tasks.join(', ')}`)
         return 0
       }
-      process.stderr.write(`vx run: no projects declare task(s): ${tasks.join(', ')}.\n`)
-      return 1
+      return refuse(
+        'run',
+        args,
+        `no projects declare task(s): ${tasks.join(', ')}`,
+        'VX_E_UNKNOWN_TASK',
+      )
     }
-    if (parsed.graph !== undefined) {
-      const out = formatGraphDot(plan)
-      if (parsed.graph === '') {
-        process.stdout.write(out)
-      } else {
-        // The graph is the command's one product, so a path it cannot write
-        // is exit 1, said in one line as the other output paths say theirs:
-        // a directory or an unreachable path printed a raw stack (item 993).
-        const target = path.resolve(cwd, parsed.graph)
-        try {
-          await Bun.write(target, out)
-        } catch (err) {
-          const message = err instanceof Error ? err.message : String(err)
-          process.stderr.write(`vx run: failed to write graph to ${target}: ${message}\n`)
-          return 1
-        }
-      }
-    } else if (parsed.dry === 'json') {
+    if (parsed.dry === 'json') {
       process.stdout.write(formatPlanJson(plan, scopeOut.affectedBase))
     } else {
       process.stdout.write(formatPlanText(plan))
@@ -759,25 +649,6 @@ export async function runCmd(args: readonly string[]): Promise<number> {
     return 0
   }
 
-  // The report prints above the footer: nothing prints below it (owner).
-  // Rendered once, however many sinks asked for it; a kept server's crash
-  // after the footer re-renders the file's copy (C-53).
-  const wantsReport = parsed.report === 'markdown' || parsed.reportFile !== undefined
-  let reported: { outcomes: readonly TaskOutcome[]; md: string } | undefined
-  if (wantsReport) {
-    opts.beforeFooter = (outcomes, ok) => {
-      reported = {
-        outcomes,
-        md: formatRunReportMarkdown({ ok, outcomes: outcomes.map(projectOutcome) }),
-      }
-      // `--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.
-      return parsed.report === 'markdown' ? reported.md : ''
-    }
-  }
   // 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
@@ -787,37 +658,6 @@ export async function runCmd(args: readonly string[]): Promise<number> {
     const unknown = summary.refused.startsWith('no projects declare')
     return refuse('run', args, summary.refused, unknown ? 'VX_E_UNKNOWN_TASK' : 'VX_E_REFUSED')
   }
-  if (wantsReport) {
-    const md =
-      reported?.outcomes === summary.outcomes
-        ? reported.md
-        : formatRunReportMarkdown({
-            ok: summary.ok,
-            outcomes: summary.outcomes.map(projectOutcome),
-          })
-    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.
-        // Its directory made first, as `--summarize`, `--profile` and
-        // `--graph` make theirs: `nr/r.md` failed alone of the four (item 993).
-        // Sync: on a Ctrl-C the signal path exits once stdout drains, and
-        // an awaited write lost the race every time (E-23).
-        mkdirSync(path.dirname(target), { recursive: true })
-        appendFileSync(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`)
-      }
-    }
-  }
-  if (summary.json !== undefined) process.stdout.write(`${JSON.stringify(summary.json)}\n`)
   return summary.ok ? 0 : 1
 }