@vzn/vx 0.0.636 → 0.0.638

package/src/cli/help.ts

@@ -1,14 +1,21 @@
-import type { ColorSupport, paint as Paint } from '../orchestrator/index.js'
-import { CORE_VERBS, errorDocument, maskedLine, nearest, wantsJson } from '../util/index.js'
+import {
+  CORE_VERBS,
+  detectColors,
+  errorDocument,
+  maskedLine,
+  nearest,
+  paint,
+  refusalNotice,
+  ui,
+  wantsJson,
+  type ColorSupport,
+} from '../util/index.js'
 
 export async function printHelp(
   pluginCommands: readonly string[] = [],
   verb?: string,
 ): Promise<void> {
   const text = verb === undefined ? helpText(pluginCommands) : verbHelpText(verb)
-  // The orchestrator is already loaded by the plugin-verb lookup every
-  // caller awaits first, so this import costs `vx --version` nothing.
-  const { detectColors, paint } = await import('../orchestrator/index.js')
   process.stdout.write(paintHelp(text, helpColors(process.stdout, detectColors), paint))
 }
 
@@ -33,7 +40,7 @@ const TERM = '#22d3ee' // cyan-400 — a flag, a selector, an example
  * `(for <verb>)` dim), `vx <verb>` bold cyan, and the term an option or
  * example line opens with cyan. Prose and continuation lines stay plain.
  */
-export function paintHelp(text: string, colors: ColorSupport, paint: typeof Paint): string {
+export function paintHelp(text: string, colors: ColorSupport, paint: Paint): string {
   if (!colors.enabled) return text
   const lines = text.split('\n')
   return lines
@@ -102,19 +109,19 @@ export function verbHelpText(verb: string): string {
 
 export function helpText(pluginCommands: readonly string[] = []): string {
   return [
-    'vx — open, extensible monorepo task runner',
+    'vx — task orchestration you own',
     '',
     'Usage:',
     '  vx run [OPTIONS] [TASK | PKG#TASK ...] [-- forwarded-args...]',
-    '  vx watch [OPTIONS] TASK [-- forwarded-args...]',
-    '  vx cache prune [--older-than <duration>] [--max-size <size>] [--dry-run] [--format pretty|json] [--cache-dir <path>]',
+    '  vx watch [OPTIONS] [--poll] TASK [-- forwarded-args...]',
+    '  vx cache clean [--older-than <duration>] [--max-size <size>] [--global] [--dry-run] [--format pretty|json] [--cache-dir <path>]',
     '  vx lock [--check] [--format pretty|json]',
     '  vx init [--dry [--format pretty|json]] [--force] [--mjs] [--native|--keep] [--plugin <seam>]',
     '  vx upgrade [TAG]',
     '  vx show [PROJECT[#TASK] | TASK] [--filter <pattern>] [--affected[=<ref>]] [--format pretty|json]',
     '  vx info [--format pretty|json] [--cache-dir <path>]',
     '  vx why (TASK | PKG#TASK) [--run RUNID] [--format pretty|json] [--cache-dir <path>]',
-    '  vx last [RUNID] [--list[=N]] [--failed] [--log <task>] [--format pretty|json] [--cache-dir <path>]',
+    '  vx last [RUNID] [--list[=N]] [--failed] [--log <task>] [--stats [<task>] [--branch <name>]] [--format pretty|json] [--cache-dir <path>]',
     '  vx docs <query> [--limit N] [--format pretty|json]',
     '  vx completions bash|zsh|fish',
     '  vx help [VERB]',
@@ -126,56 +133,80 @@ export function helpText(pluginCommands: readonly string[] = []): string {
     '      --filter <pat>       pnpm-style filter (repeatable). Examples:',
     '                             foo, @scope/*, ./packages/foo, foo..., ...foo,',
     '                             foo^..., !foo, [<since>]',
-    '      --affected[=<base>]  Sugar for --filter "...[<base>]". Default base =',
-    '                             affectedBase, else origin/HEAD, else main or',
-    '                             master, else HEAD~1.',
+    '      --affected[=<base>]  Projects changed since <base>, and dependents',
+    '                             (--filter "...[<base>]"); default run.affectedBase,',
+    '                             else origin/HEAD, main, master, HEAD~1.',
     "  pkg#task                 Run a specific project's task directly.",
     '',
     'Execution (for run):',
-    '      --concurrency <n>           Max parallel tasks (default: the cores this process may use); `50%` = half of them.',
-    '      --exclude-dependencies[=names]  Skip dependsOn edges. No value = all; comma list = specific names.',
-    '      --no-cache                  Disable caching entirely (no reads, no writes, outputs left alone).',
-    '      --force                     Re-execute everything (skip reads) but still refresh the cache (writes on).',
-    '      --cache <spec>              Per-layer read/write control. Comma list of <layer>:<flags>',
-    '                                  (layer = local|remote, flags ⊆ rw). A named layer is set EXACTLY',
-    '                                  to its flags; unnamed layers keep their value. Examples:',
-    '                                  local:rw,remote:r (remote read-only), remote: (remote off),',
-    '                                  local:r (local read-only). Without it, VX_CACHE holds the spec.',
-    "      --cache-scope <name>        This run's cacheScope: trusted | read-only | a scope (pr-123).",
-    '                                  Beats VX_CACHE_SCOPE and the workspace cacheScope.',
-    '      --cache-dir <path>          Cache directory override (cwd-relative). Beats VX_CACHE_DIR,',
-    '                                  the workspace cacheDir field and the ~/.vx/<id>/cache default.',
-    '      --retry <n>                 Re-run a failed task up to <n> more times (default for tasks',
-    "                                  without their own exec.retries; explicit config wins). Doesn't",
-    '                                  affect cache keys.',
-    '      --timeout <ms>              Default per-task timeout for tasks without their own exec.timeout',
-    '                                  (above VX_TASK_TIMEOUT env + workspace timeout). Kills + fails',
-    '                                  a runaway task. Per-task exec.timeout always wins.',
-    '      --continue[=<mode>]         What a failed task takes down: never | deps-ok (default, skips',
-    '                                  its dependents) | always (bare form; dependents run, never save).',
-    '      --frozen                    Load configs from vx-lock.json (CI; pair with vx lock --check).',
-    '      --output-logs <mode>        full | errors-only | hash-only | none — overrides the flow default',
-    '                                  (focused without --all/--filter/--affected, broad with, full in CI).',
-    '      --download <mode>           all (default) | toplevel | none — where remote outputs land.',
-    '      --verbosity <n>             0 (default) or 1+: print a per-task summary table after the run.',
+    '  Each setting flag beats its VX_* variable, which beats .vx/workspace',
+    '  (docs/schema.md § Settings).',
+    '      --concurrency <n>           Max parallel tasks (default: usable cores);',
+    '                                  50% means half of them.',
+    '      --schedule <rule>           most-work (default) | critical-path |',
+    '                                  direct-dependents | ready-order.',
+    '      --branch <name>             The branch history records and forecasts read',
+    "                                  (default: git's, else the CI provider's).",
+    '      --exclude-dependencies[=names]  Skip dependsOn edges: all with no value,',
+    '                                  or a comma list of names.',
+    '      --no-cache                  No cache reads or writes; outputs are left',
+    '                                  alone.',
+    '      --force                     Skip cache reads but still write: every task',
+    '                                  runs and refreshes its entry.',
+    '      --cache-policy <spec>       Per-layer read/write: a comma list of',
+    '                                  <layer>:<flags> (layer local or remote, flags',
+    '                                  from rw). A named layer is set to exactly its',
+    '                                  flags; unnamed layers keep theirs. Examples:',
+    '                                  local:rw,remote:r (remote read-only), remote:',
+    '                                  (remote off), local:r (local read-only).',
+    "      --cache-scope <name>        This run's cache.scope (pr-123): write there,",
+    '                                  read the default keys first.',
+    '      --cache-dir <path>          Cache directory (cwd-relative); default',
+    '                                  .vx/cache, entries in ~/.vx/<id>/cache.',
+    '      --cache-download <mode>     all (default) | toplevel | none:',
+    '                                  where remote outputs land.',
+    '      --retries <n>               Up to <n> more runs of a failed task, for',
+    '                                  tasks without their own exec.retries. Not',
+    '                                  folded into cache keys.',
+    "      --timeout <duration>        A task's time limit (30s, 10m), for tasks",
+    '                                  without their own exec.timeout. A task past it',
+    '                                  is killed and fails.',
+    '      --kill-grace <duration>     How long a task that ignores SIGTERM gets',
+    '                                  before SIGKILL (default 2s).',
+    "      --teardown-timeout <duration>  The bound on each plugin's end-of-run flush",
+    '                                  (default 3s).',
+    '      --ready-notice <duration>   When vx says a persistent task still waits for',
+    '                                  readyWhen (default 10s).',
+    '      --continue[=<mode>]         What a failed task takes down: never | deps-ok',
+    '                                  (default, skips its dependents) | always (bare',
+    '                                  form; dependents run, never save).',
+    '      --output-logs <mode>        full | errors-only | hash-only | none, over',
+    '                                  the flow default (focused without',
+    '                                  --all/--filter/--affected, broad with, full in',
+    '                                  CI).',
+    '      --verbosity <n>             0 (default), or 1 and up for a per-task',
+    '                                  summary table after the run.',
     '',
     'Planning (for run — skips execution):',
-    '      --dry[=text|json]    Print the task graph + cache hit/miss prediction.',
+    "      --dry[=text|json]    Print the task graph and each task's predicted hit",
+    '                           or miss.',
     '      --graph[=<path>]     Emit Graphviz DOT (stdout if no path).',
     '',
     'Artifacts (for run):',
-    '      --format <fmt>        pretty (default) | json: print the --summarize document',
-    '                            on stdout when the run ends; every other line goes to stderr.',
+    '      --format <fmt>        pretty (default) | json: print the --summarize',
+    '                            document on stdout when the run ends; every other',
+    '                            line goes to stderr.',
     '      --summarize[=<path>]  Write per-run JSON to <cacheDir>/runs/<run_id>.json.',
     '      --profile[=<path>]    Write Chrome-trace JSON (default profile.json).',
     '      --report[=markdown]   Print a markdown run report to stdout after the run.',
-    '      --report-file <path>  Append that report to <path> (for $GITHUB_STEP_SUMMARY).',
-    '      --tag <k=v>           Label this invocation (repeatable); recorded on its history row.',
+    '      --report-file <path>  Append that report to <path> ($GITHUB_STEP_SUMMARY).',
+    '      --tag <k=v>           Label this invocation (repeatable); recorded on its',
+    '                            history row.',
     '',
     'Extensions (plugins):',
     '  vx core runs tasks in-process and nothing else. A dashboard, remote',
     '  cache, distributed execution, and telemetry export are provided by',
-    '  PLUGINS declared in vx.workspace.ts — first-party or your own. Core',
+    '  PLUGINS declared in .vx/workspace.ts — first-party or your own. Core',
     '  depends on none of them; a plain `vx run` never requires a plugin.',
     '  See the plugin guide: https://vznjs.github.io/vx/guides/plugins/',
     '',
@@ -194,24 +225,27 @@ export function helpText(pluginCommands: readonly string[] = []): string {
     '                             Uses the same flags as `vx run` except --dry /',
     '                             --graph / --summarize / --profile / --report /',
     '                             --report-file / --verbosity (they plan or report',
-    '                             one run). Press Ctrl+C to stop. Cache means most',
+    '                             one run), plus --poll (watch.poll: poll instead of',
+    '                             the OS watcher). Press Ctrl+C to stop. Cache means most',
     '                             re-runs are near-zero cost (cache hits restore',
     '                             outputs + replay logs).',
     '',
     'Cache management:',
-    '  vx cache prune --older-than 30d     Evict entries last accessed > 30 days ago.',
-    '  vx cache prune --max-size 1G        Keep total cache under 1 GB (LRU eviction).',
+    '  vx cache clean --older-than 30d     Evict entries last accessed > 30 days ago.',
+    '  vx cache clean --max-size 1G        Keep total cache under 1 GB (LRU eviction).',
+    "  vx cache clean                      Clear .vx/cache and this repo's store ~/.vx/<id>/cache.",
+    "      --global                        Clear every repo's store under ~/.vx.",
     '      --dry-run                       Say what the policy would reap; delete nothing.',
     '      --format <fmt>                  pretty (default) | json.',
     '      --cache-dir <path>              The cache a run with the same flag uses (why, last, info too).',
     '',
-    '  Duration units: s, m, h, d. Size units: K, M, G, T (powers of 1024).',
+    '  Duration units: ms, s, m, h, d. Size units: K, M, G, T (powers of 1024).',
     '  Cache statistics — directory, entry count, size — are part of `vx info`.',
     '',
     'Introspection:',
     '  vx show              List every project: name, dir, declared task count.',
-    "  vx show <project>    Print the project's LIVE resolved config (fresh",
-    '                       evaluation, not the lock), one block per task.',
+    "  vx show <project>    Print the project's resolved config as a run reads",
+    '                       it from the lock, one block per task.',
     "  vx show <pkg>#<task> Print a single task's resolved config.",
     '  vx show <task>       That task in every project declaring it.',
     "      --filter <pattern>  The list (or a task's projects) as `vx run --filter` selects.",
@@ -234,25 +268,27 @@ export function helpText(pluginCommands: readonly string[] = []): string {
     '      --failed         Only failed runs: the latest one, or with --list the list.',
     "      --log <task>     That task's output in the run (latest that ran it): a failure's",
     '                       or the cached log; none for an uncached pass.',
+    '      --stats [<task>] Per-task p50/p99, pass and hit rate, failure mode, peak',
+    '                       RSS and CPU over the last 50 runs; a task id or name narrows.',
+    "      --branch <name>  The branch --stats' p50 forecasts from (default: the run's).",
     '      --format <fmt>   pretty (default) | json.',
     '  info, why and last:',
     '      --cache-dir <path>  Read the cache a run with the same flag uses.',
     '',
     'Migration:',
-    '  vx init              Generate vx.workspace.ts + one vx.config.ts per package',
-    '                       from package.json scripts. Unmappable settings become',
-    '                       TODO(vx-migrate) comments. Beside turbo.json or nx.json:',
-    '                       runs @vzn/vx-migrate, which asks native or keep.',
+    '  vx init              With no package.json: write .vx/workspace.ts and an empty',
+    '                       root vx.config.ts. With one: runs @vzn/vx-migrate, which maps',
+    '                       turbo.json, an Nx graph or package.json scripts to one',
+    '                       vx.config.ts per package (asking native or keep in Turbo/Nx).',
     '      --dry            Print the generated files instead of writing them.',
     '      --format json    With --dry: the plan as one JSON document (schemas/init.json).',
     '      --force          Overwrite existing vx.config.* files.',
     '      --mjs            Write .mjs files (no type import) instead of .ts.',
     '      --native         Turbo or Nx: write a vx.config.ts per package (no question).',
-    '      --keep           Turbo or Nx: only vx.workspace.ts, declaring turbo() or nx().',
+    '      --keep           Turbo or Nx: only .vx/workspace.ts, declaring turbo() or nx().',
     '      --plugin <seam>  Instead: write plugins/<seam>.ts, a runnable plugin, and its',
     '                       test (executor, cache, telemetry, schedule, admit, commands,',
     '                       project, graph, key).',
-    '  From turbo.json or an Nx project graph: `vx init` runs `@vzn/vx-migrate` (its own package).',
     '',
     'Shell completions:',
     '  vx completions <shell>   Print a completion script for bash, zsh or fish: the',
@@ -269,14 +305,15 @@ export function helpText(pluginCommands: readonly string[] = []): string {
     '      --format json    {query, hits: [{page, heading, url, text}]}.',
     '',
     'Config lock:',
-    '  vx lock              Evaluate every vx.config in the current environment and',
-    '                       freeze the resolved objects into vx-lock.json. Plain runs',
-    '                       always evaluate live; only `vx run --frozen` consumes the',
-    '                       lock (CI reproducibility, frozen-env semantics).',
+    '  vx lock              Evaluate every vx.config in the current environment, check',
+    '                       the graph rules (run.rules) and freeze the resolved objects',
+    '                       into .vx/projects.lock.json, the only place a run reads configs',
+    '                       from. A run never evaluates one, never checks the rules',
+    '                       and never writes the lock: with none it fails.',
     '  vx lock --check      Audit the lock: file-changed hash report PLUS a full',
-    '                       re-evaluation compared against the frozen objects. Exits 1',
-    '                       on drift (e.g. configs that read env vars). Run it before',
-    '                       `vx run --frozen` in CI. With --format json it prints',
+    '                       re-evaluation compared against the frozen objects, and the',
+    '                       graph rules. Exits 1 on drift (e.g. configs that read env',
+    '                       vars). Run it before the run in CI. With --format json it prints',
     '                       {upToDate, audited, notAudited, problems}.',
     '',
     ...(pluginCommands.length > 0 ? ['Plugin commands:', ...pluginCommands, ''] : []),
@@ -315,7 +352,7 @@ export function refusedWord(arg: string): string {
  * `(did you mean --concurrency?)` for a flag within two edits of one `verb`
  * accepts; empty for anything else (a positional included). A third edit
  * is allowed only between flags that share their first five characters,
- * so `--retries` reaches `--retry` while `--zzz` does not reach `--all`.
+ * so `--timeouts` reaches `--timeout` while `--zzz` does not reach `--all`.
  */
 export function flagHint(verb: string, arg: string): string {
   if (!arg.startsWith('-')) return ''
@@ -343,8 +380,8 @@ export function flagHint(verb: string, arg: string): string {
  * The documented `--flags` of one verb, read from the help text's
  * sections headed `… (for <verb>):` so there is no second list to drift —
  * and no hint that names another verb's flag. Only the flag an option line
- * OPENS with is one: `--frozen`'s line says "pair with vx lock --check", and
- * reading every flag on it put `--check` in the list, so `vx run --chek`
+ * OPENS with is one: an option line that named `vx lock --check` once put
+ * `--check` in the list, so `vx run --chek`
  * was told "did you mean --check?" and `--check` was then refused.
  */
 export function documentedFlags(verb: string, text = helpText()): string[] {
@@ -354,8 +391,9 @@ export function documentedFlags(verb: string, text = helpText()): string[] {
     if (/^[A-Z][A-Za-z ]*(?: \(for [a-z]+\))?:$/.test(line))
       inVerb = line.endsWith(`(for ${verb}):`)
     if (!inVerb) continue
-    const own = /^\s+(--[a-zA-Z][a-zA-Z-]*)/.exec(line)
-    if (own !== null) flags.add(own[1]!)
+    // `--x, --no-x`: a flag and its negation.
+    const own = /^\s+(--[a-zA-Z][a-zA-Z-]*)(?:, (--[a-zA-Z][a-zA-Z-]*))?/.exec(line)
+    if (own !== null) for (const f of own.slice(1)) if (f !== undefined) flags.add(f)
   }
   return [...flags]
 }
@@ -414,7 +452,9 @@ export function refuse(
   code: string,
 ): number {
   const line = `vx ${verb}: ${message}`
-  process.stderr.write(`${line}\n`)
+  ui.print('err', refusalNotice(`vx ${verb}`, message))
   if (wantsJson(args)) process.stdout.write(errorDocument(code, maskedLine(line)))
   return 1
 }
+
+type Paint = typeof paint

package/src/cli/index.ts

@@ -2,14 +2,20 @@
 // handler lives in a sibling `<name>.ts`; tests import its parsers there.
 
 import { VERSION } from '../version.js'
+import { checkSettingsEnv } from '../settings.js'
 import { CORE_VERBS, flagHint, printHelp, refusedWord, seeHelp } from './help.js'
 import { FOREIGN_VERBS } from './foreign-flags.js'
 import {
   errorDocument,
+  hideEnvFromTasks,
+  sayNotice,
+  isFsRefusal,
+  isOutOfFds,
   isUserError,
   maskedLine,
-  MOVED_VERBS,
   nearest,
+  refusalNotice,
+  ui,
   UserError,
   wantsJson,
 } from '../util/index.js'
@@ -24,6 +30,7 @@ const plugins = () => import('./plugin-commands.js')
 
 export async function run(argv: readonly string[]): Promise<number> {
   const [command, ...rest] = argv
+  await hideEnvFromTasks()
 
   // `vx <verb> --help` is the universal reflex, and every verb answered
   // `unknown flag: --help` and exited 1 (walkthrough, 2026-09-04). Only args
@@ -34,7 +41,33 @@ export async function run(argv: readonly string[]): Promise<number> {
     await printHelp(await (await plugins()).pluginCommandHelp(), command)
     return 0
   }
+  // Each setting's variable once, before any verb: a renamed one is named,
+  // and a deep reader trusts what it reads.
+  checkSettingsEnv()
 
+  try {
+    return await dispatch(command, rest)
+  } catch (err) {
+    throw await brokenLockNamed(err)
+  }
+}
+
+/**
+ * A crash from a hand-broken lock entry is that entry's fault: runs validate
+ * no entry, so it surfaced as a raw TypeError (M, 2026-10-14). The lock is
+ * read only on the crash path, so a normal run pays nothing.
+ */
+async function brokenLockNamed(err: unknown): Promise<unknown> {
+  if (isUserError(err) || isFsRefusal(err) || isOutOfFds(err)) return err
+  try {
+    const { findWorkspaceRoot, LOCK_INVALID, lockEntryBroken } =
+      await import('../workspace/index.js')
+    if (lockEntryBroken(await findWorkspaceRoot(process.cwd()))) return new UserError(LOCK_INVALID)
+  } catch {}
+  return err
+}
+
+async function dispatch(command: string | undefined, rest: string[]): Promise<number> {
   switch (command) {
     case undefined: {
       // A bare `vx` where no workspace is printed 151 lines of help, none
@@ -44,7 +77,8 @@ export async function run(argv: readonly string[]): Promise<number> {
         await findWorkspaceRoot(process.cwd())
       } catch (err) {
         if (!isUserError(err)) throw err
-        process.stderr.write(`vx: ${err.message}; \`vx help\` lists the verbs\n`)
+        const parts = err.parts ?? { headline: err.message }
+        ui.print('err', refusalNotice('vx', err.message, { ...parts, why: 'see vx help' }))
         return 1
       }
       await printHelp(await (await plugins()).pluginCommandHelp())
@@ -65,21 +99,25 @@ export async function run(argv: readonly string[]): Promise<number> {
         // for the whole reference: it printed 145 lines and no hint.
         const resolved = await (await plugins()).resolvePluginCommand(verb)
         const unknown = resolved === null || 'declaredVerbs' in resolved
-        const pointer = MOVED_VERBS[verb] ?? FOREIGN_VERBS[verb]
+        const pointer = FOREIGN_VERBS[verb]
         if (unknown && pointer !== undefined) {
-          process.stderr.write(`${pointer}\n`)
+          sayNotice('info', 'vx', pointer)
           return 1
         }
         if (unknown && verb.startsWith('-')) {
-          process.stderr.write(
-            `vx help: unknown flag: ${verb}${flagHint('help', verb)} (see \`vx help\`)\n`,
+          sayNotice(
+            'error',
+            'vx help',
+            `unknown flag: ${verb}${flagHint('help', verb)} (see \`vx help\`)`,
           )
           return 1
         }
         if (unknown) {
           const declared = resolved === null ? [] : resolved.declaredVerbs
-          process.stderr.write(
-            `vx help: unknown command: ${verb}${didYouMeanVerb(verb, declared)} (see \`vx help\`)\n`,
+          sayNotice(
+            'error',
+            'vx help',
+            `unknown command: ${verb}${didYouMeanVerb(verb, declared)} (see \`vx help\`)`,
           )
           return 1
         }
@@ -93,8 +131,10 @@ export async function run(argv: readonly string[]): Promise<number> {
       // takes no more of is refused, as every other verb refuses one.
       const extra = rest[0]
       if (extra !== undefined) {
-        process.stderr.write(
-          `vx version: ${refusedWord(extra)}: ${extra}${flagHint('version', extra)}${seeHelp('version')}\n`,
+        sayNotice(
+          'error',
+          'vx version',
+          `${refusedWord(extra)}: ${extra}${flagHint('version', extra)}${seeHelp('version')}`,
         )
         return 1
       }
@@ -163,22 +203,25 @@ export async function run(argv: readonly string[]): Promise<number> {
       // points at the file that broke it.
       // Every answer below is "no such verb here": under --format json the
       // agent reads it as one code, as a verb's own refusal gives one.
-      const unknown = (text: string, code = 'VX_E_UNKNOWN_COMMAND'): number => {
-        process.stderr.write(text)
+      const unknown = (
+        text: string,
+        code = 'VX_E_UNKNOWN_COMMAND',
+        tone: 'error' | 'info' = 'error',
+      ): number => {
+        sayNotice(tone, 'vx', text.replace(/^vx: /, '').trimEnd())
         if (wantsJson(rest))
           process.stdout.write(errorDocument(code, maskedLine(text.split('\n')[0]!)))
         return 1
       }
       const loadNote =
         resolved !== null && 'loadError' in resolved
-          ? `\n  (plugin verbs could not be looked up: vx.workspace failed to load: ${resolved.loadError})`
+          ? `\n  (plugin verbs could not be looked up: .vx/workspace failed to load: ${resolved.loadError})`
           : ''
-      // A verb core owned once (`migrate`, `prune`) and a package owns now:
-      // the pointer, but only after the plugins had their chance — a
-      // workspace that declares a plugin verb of that name keeps it.
-      const moved = MOVED_VERBS[command] ?? FOREIGN_VERBS[command]
+      // Another tool's verb: the pointer, but only after the plugins had
+      // their chance — a workspace that declares a plugin verb of that name keeps it.
+      const moved = FOREIGN_VERBS[command]
       if (moved !== undefined) {
-        return unknown(`${moved}${loadNote}\n`)
+        return unknown(`${moved}${loadNote}\n`, undefined, 'info')
       }
       // A task typed where the verb goes (`turbo build`, `nx build app`),
       // `turbo dev` included: a repo's own `dev` task beats the no-service note.
@@ -198,7 +241,7 @@ export async function run(argv: readonly string[]): Promise<number> {
       if (command === 'serve' || command === 'dev') {
         // vx core is only a task runner — it has no service layer of its
         // own. A dashboard, remote cache, distributed execution, etc. are
-        // provided by PLUGINS (declared in vx.workspace.ts), never by core.
+        // provided by PLUGINS (declared in .vx/workspace.ts), never by core.
         // We keep this neutral hint for the common muscle-memory verbs, but
         // core names no specific plugin package: any package can provide
         // these.
@@ -213,10 +256,10 @@ export async function run(argv: readonly string[]): Promise<number> {
       // help after a typo was a hundred lines past the hint that mattered.
       // The verbs this workspace's plugins declare are verbs HERE, so they
       // join the "did you mean" set, and when nothing is close the second
-      // line says where a verb can come from: `vx mpc` in a workspace
-      // declaring `mcp` read as a plain unknown command, and `vx mcp`
-      // before the plugin was declared said nothing about the file that
-      // would declare it (2026-09-20).
+      // line says where a verb can come from: a typo of a plugin verb read
+      // as a plain unknown command, and a plugin verb before the plugin was
+      // declared said nothing about the file that would declare it
+      // (2026-09-20).
       // A word that opens with a dash is a flag, and vx itself takes only
       // --help and --version: "unknown command: --bogus" named the wrong
       // thing (M-60).
@@ -268,5 +311,5 @@ function verbSourceNote(resolved: unknown, declaredVerbs: readonly string[]): st
     return `  This workspace's plugins declare: ${[...declaredVerbs].sort().join(', ')}.\n`
   }
   const here = resolved === null ? 'there is no workspace here' : 'this workspace declares none'
-  return `  A plugin declared in vx.workspace.ts can add verbs; ${here}.\n`
+  return `  A plugin declared in .vx/workspace.ts can add verbs; ${here}.\n`
 }