@vzn/vx 0.0.639 → 0.0.640

package/src/cli/init.ts

@@ -13,7 +13,7 @@ import { gitTop, workspaceFileWritten } from '../handoff.js'
 import { flagHint, formatValue, refuse, seeHelp } from './help.js'
 import { lockAfterMigration } from './lock.js'
 import { PLUGIN_TEMPLATES } from './plugin-templates.js'
-import { isCompiledBinary } from './upgrade.js'
+import { isCompiledBinary, targetVersion } from './upgrade.js'
 import { VERSION } from '../version.js'
 import { DOT_VX_GITATTRIBUTES, DOT_VX_GITIGNORE, ui, UserError, sayNotice } from '../util/index.js'
 import {
@@ -217,8 +217,11 @@ async function starter(root: string, noGit: boolean, args: InitArgs): Promise<nu
 }
 
 /**
- * A repo with a package.json is `@vzn/vx-migrate`'s: the installed one,
- * else this version's through `bun x`. It finds the root itself, asks a
+ * A repo with a package.json is `@vzn/vx-migrate`'s, at the latest
+ * release: it installs @vzn/vx and every @vzn/vx-* plugin the root lists
+ * at its own version, so init always lands on latest with all of them
+ * together, as `vx upgrade` moves them (M, 2026-10-16: an installed 0.0.637
+ * pinned core back from 0.0.639). It finds the root itself, asks a
  * terminal native or keep in a Turbo or Nx repo, and installs what it writes.
  */
 async function migrate(dirs: readonly string[], args: InitArgs): Promise<number> {
@@ -229,21 +232,30 @@ async function migrate(dirs: readonly string[], args: InitArgs): Promise<number>
     args.mode !== undefined && `--${args.mode}`,
     args.json === true && '--format=json',
   ].filter((f): f is string => typeof f === 'string')
-  return Bun.spawn(migrateCommand(dirs, flags), {
+  // An exact version: `bun x` may answer `@latest` from its cache.
+  const latest = VERSION === '0.0.0' ? 'latest' : await targetVersion(undefined, 'vx init')
+  return Bun.spawn(migrateCommand(dirs, flags, latest), {
     stdio: ['inherit', 'inherit', 'inherit'],
     // A compiled vx is a Bun runtime only when told so.
     env: isCompiledBinary() ? { ...process.env, BUN_BE_BUN: '1' } : process.env,
   }).exited
 }
 
-export function migrateCommand(dirs: readonly string[], flags: readonly string[]): string[] {
-  for (const d of dirs) {
-    const installed = path.join(d, 'node_modules', '@vzn', 'vx-migrate', 'src', 'bin.ts')
-    if (existsSync(installed)) return [process.execPath, '--no-install', installed, ...flags]
+export function migrateCommand(
+  dirs: readonly string[],
+  flags: readonly string[],
+  latest: string,
+  running = VERSION,
+): string[] {
+  // A source checkout (0.0.0, which npm never had) runs the vx-migrate
+  // beside it; a release never runs an installed one.
+  if (running === '0.0.0') {
+    for (const d of dirs) {
+      const installed = path.join(d, 'node_modules', '@vzn', 'vx-migrate', 'src', 'bin.ts')
+      if (existsSync(installed)) return [process.execPath, '--no-install', installed, ...flags]
+    }
   }
-  // A source checkout is 0.0.0, which npm never had.
-  const version = VERSION === '0.0.0' ? 'latest' : VERSION
   // Bun's own install output ("Slow filesystem detected…") in a pnpm or npm
   // repo reads as a stranger speaking (Growth's first-run funnel F2).
-  return [process.execPath, 'x', '--silent', `@vzn/vx-migrate@${version}`, ...flags]
+  return [process.execPath, 'x', '--silent', `@vzn/vx-migrate@${latest}`, ...flags]
 }

package/src/cli/last.ts

@@ -22,6 +22,8 @@ import {
   exitSignal,
   resolveRunId,
   runFailures,
+  type RunStep,
+  runSteps,
   shortRunId,
   taskLog,
 } from '../orchestrator/index.js'
@@ -328,6 +330,22 @@ function reasonParts(t: RunSummaryRow): string {
 /** Hit rows shown before the rest fold — the slowest restores. */
 const HITS_SHOWN = 16
 
+/**
+ * The steps the run did not wait on (`vx:prefetch`), which its own output
+ * never showed (M, 2026-10-16): here for debugging, marked `internal`.
+ */
+function formatStepRows(steps: readonly RunStep[]): string[] {
+  if (steps.length === 0) return []
+  const idW = Math.max(...steps.map((s) => s.id.length), 4)
+  return [
+    '',
+    ...steps.map(
+      (s) =>
+        `  ${(s.ok ? 'success' : 'failed').padEnd(17)} ${s.id.padEnd(idW)}  ${fmtMs(s.durationMs).padStart(8)}  internal`,
+    ),
+  ]
+}
+
 /**
  * The per-task rows: failures first, then what executed or was skipped,
  * then cache hits. Hits are the noise of a warm run — 996 of a thousand
@@ -336,6 +354,7 @@ const HITS_SHOWN = 16
  * count; the ones shown are the slowest restores, the one thing a hit's
  * row tells. `--format json` lists every row.
  */
+
 export function formatTaskRows(tasks: readonly RunSummaryRow[]): string[] {
   if (tasks.length === 0) return []
   const failed = tasks.filter((t) => t.status === 'failed')
@@ -545,7 +564,10 @@ export async function lastCmd(args: readonly string[]): Promise<number> {
               ...(f.fixedIn !== undefined ? { fixedIn: f.fixedIn } : {}),
             }
       })
-      process.stdout.write(`${JSON.stringify({ invocation: inv, tasks })}\n`)
+      const steps = runSteps(cacheDir, inv.runId)
+      process.stdout.write(
+        `${JSON.stringify({ invocation: inv, tasks, ...(steps.length > 0 ? { steps } : {}) })}\n`,
+      )
       return 0
     }
 
@@ -563,6 +585,7 @@ export async function lastCmd(args: readonly string[]): Promise<number> {
         `${inv.failedCount > 0 ? ` · ${inv.failedCount} failed` : ''}`,
     )
     lines.push(...formatTaskRows(detail?.tasks ?? []))
+    lines.push(...formatStepRows(runSteps(cacheDir, inv.runId)))
     // The next command after reading a failed run, with the arguments the
     // run forwarded to the tasks that got them (a failure under `-- --shard
     // 2` is that shard's); a dependency never got them, so its line has none.

package/src/cli/plugin-templates.ts

@@ -11,7 +11,7 @@ export const PLUGIN_TEMPLATES: Readonly<Record<string, { plugin: string; test: s
   cache: {
     plugin:
       "// `cache`: where artifacts live. A directory stands in for a remote store;\n// core puts it behind the local cache, so a remote error is a miss and a\n// warning, never a failed run.\nimport { link, mkdir, unlink } from 'node:fs/promises'\nimport path from 'node:path'\nimport { definePlugin, type RemoteCacheLayer, type VxPlugin } from '@vzn/vx'\n\nclass DirRemote implements RemoteCacheLayer {\n  constructor(readonly endpoint: string) {}\n  async has(hash: string): Promise<boolean> {\n    return Bun.file(path.join(this.endpoint, hash)).exists()\n  }\n  async get(hash: string) {\n    const file = Bun.file(path.join(this.endpoint, hash))\n    return (await file.exists()) ? { body: file, durationMs: undefined } : null\n  }\n  async put(hash: string, body: Blob): Promise<void> {\n    await mkdir(this.endpoint, { recursive: true })\n    // Written aside, then linked: on a shared directory a rename can swap\n    // the file under a reader, while a link never replaces an existing one.\n    // EEXIST is success: the same hash means the same bytes.\n    const tmp = path.join(this.endpoint, `.${hash}.${process.pid}`)\n    await Bun.write(tmp, body)\n    try {\n      await link(tmp, path.join(this.endpoint, hash))\n    } catch (err) {\n      if ((err as NodeJS.ErrnoException).code !== 'EEXIST') throw err\n    } finally {\n      await unlink(tmp)\n    }\n  }\n}\n\nexport function dirCache(dir: string): VxPlugin {\n  return definePlugin(import.meta, {\n    cache() {\n      return new DirRemote(dir)\n    },\n  })\n}\n",
-    test: "// A test for the example `cache` plugin beside it: a throwaway workspace\n// declares the plugin and vx's own run() drives it. `bun test` runs it.\nimport { mkdir, mkdtemp, rm, writeFile } from 'node:fs/promises'\nimport os from 'node:os'\nimport path from 'node:path'\nimport { afterEach, beforeEach, expect, it } from 'bun:test'\nimport { run, type Logger } from '@vzn/vx'\n\nlet root: string\nbeforeEach(async () => {\n  root = await mkdtemp(path.join(os.tmpdir(), 'vx-plugin-cache-'))\n  await writeFile(path.join(root, 'package.json'), JSON.stringify({ name: 'ws', private: true }))\n  await writeFile(path.join(root, 'pnpm-workspace.yaml'), 'packages:\\n  - \"packages/*\"\\n')\n  Bun.spawnSync({ cmd: ['git', 'init', '-q'], cwd: root })\n})\nafterEach(async () => {\n  await rm(root, { recursive: true, force: true })\n})\n\n/** A package `name` whose `vx.config.mjs` is `config`. */\nasync function pkg(\n  name: string,\n  config: string,\n  scripts?: Record<string, string>,\n): Promise<string> {\n  const dir = path.join(root, 'packages', name)\n  await mkdir(dir, { recursive: true })\n  await writeFile(\n    path.join(dir, 'package.json'),\n    JSON.stringify({ name, version: '1.0.0', ...(scripts ? { scripts } : {}) }),\n  )\n  // Core reads no package.json: the config names the project.\n  await writeFile(\n    path.join(dir, 'vx.config.mjs'),\n    config.replace('export default {', `export default { name: ${JSON.stringify(name)},`),\n  )\n  return dir\n}\n\n/**\n * A `.vx/workspace.mjs` declaring `call`, e.g. `dirCache()`, from the plugin file\n * beside this test, then `vx lock`: a run reads project configs only from the lock.\n */\nasync function workspace(call: string): Promise<void> {\n  const from = JSON.stringify(path.join(import.meta.dir, 'cache.ts'))\n  await Bun.write(\n    path.join(root, '.vx/workspace.mjs'),\n    `import { dirCache } from ${from}\\nexport default { plugins: [${call}] }\\n`,\n  )\n  const vx = path.join(path.dirname(new URL(import.meta.resolve('@vzn/vx')).pathname), 'bin.ts')\n  const lock = Bun.spawnSync({ cmd: [process.execPath, vx, 'lock'], cwd: root })\n  expect([lock.exitCode, lock.stderr.toString()]).toEqual([0, ''])\n}\n\nfunction log(order: string[] = []): Logger {\n  return {\n    status() {},\n    taskStart(node) {\n      order.push(`start ${node.id}`)\n    },\n    taskStdout() {},\n    taskStderr() {},\n    taskComplete(node) {\n      order.push(`end ${node.id}`)\n    },\n  }\n}\n\nit('a run on an empty local cache restores from the directory', async () => {\n  const dir = await pkg(\n    'a',\n    `export default { tasks: { build: {\n      exec: { command: 'mkdir -p dist && echo built > dist/out.txt' },\n      cache: { inputs: { files: ['package.json'] }, outputs: { files: ['dist/**'] } },\n    } } }`,\n  )\n  await workspace(`dirCache(${JSON.stringify(path.join(root, 'remote'))})`)\n  const first = await run({ cwd: root, tasks: ['build'], log: log(), handleSignals: false })\n  expect(first.outcomes.map((o) => o.status)).toEqual(['success'])\n  await rm(path.join(root, '.vx', 'cache'), { recursive: true, force: true })\n  await rm(path.join(dir, 'dist'), { recursive: true, force: true })\n  const second = await run({ cwd: root, tasks: ['build'], log: log(), handleSignals: false })\n  expect(second.outcomes.map((o) => o.status)).toEqual(['cache-hit-remote'])\n  expect(await Bun.file(path.join(dir, 'dist', 'out.txt')).text()).toBe('built\\n')\n}, 20_000)\n",
+    test: "// A test for the example `cache` plugin beside it: a throwaway workspace\n// declares the plugin and vx's own run() drives it. `bun test` runs it.\nimport { mkdir, mkdtemp, rm, writeFile } from 'node:fs/promises'\nimport os from 'node:os'\nimport path from 'node:path'\nimport { afterEach, beforeEach, expect, it } from 'bun:test'\nimport { run, type Logger } from '@vzn/vx'\n\nlet root: string\nbeforeEach(async () => {\n  root = await mkdtemp(path.join(os.tmpdir(), 'vx-plugin-cache-'))\n  await writeFile(path.join(root, 'package.json'), JSON.stringify({ name: 'ws', private: true }))\n  await writeFile(path.join(root, 'pnpm-workspace.yaml'), 'packages:\\n  - \"packages/*\"\\n')\n  Bun.spawnSync({ cmd: ['git', 'init', '-q'], cwd: root })\n})\nafterEach(async () => {\n  await rm(root, { recursive: true, force: true })\n})\n\n/** A package `name` whose `vx.config.mjs` is `config`. */\nasync function pkg(\n  name: string,\n  config: string,\n  scripts?: Record<string, string>,\n): Promise<string> {\n  const dir = path.join(root, 'packages', name)\n  await mkdir(dir, { recursive: true })\n  await writeFile(\n    path.join(dir, 'package.json'),\n    JSON.stringify({ name, version: '1.0.0', ...(scripts ? { scripts } : {}) }),\n  )\n  // Core reads no package.json: the config names the project.\n  await writeFile(\n    path.join(dir, 'vx.config.mjs'),\n    config.replace('export default {', `export default { name: ${JSON.stringify(name)},`),\n  )\n  return dir\n}\n\n/**\n * A `.vx/workspace.mjs` declaring `call`, e.g. `dirCache()`, from the plugin file\n * beside this test, then `vx lock`: a run reads project configs only from the lock.\n */\nasync function workspace(call: string): Promise<void> {\n  const from = JSON.stringify(path.join(import.meta.dir, 'cache.ts'))\n  await Bun.write(\n    path.join(root, '.vx/workspace.mjs'),\n    `import { dirCache } from ${from}\\nexport default { plugins: [${call}] }\\n`,\n  )\n  const vx = path.join(path.dirname(new URL(import.meta.resolve('@vzn/vx')).pathname), 'bin.ts')\n  const lock = Bun.spawnSync({ cmd: [process.execPath, vx, 'lock'], cwd: root })\n  expect([lock.exitCode, lock.stderr.toString()]).toEqual([0, ''])\n}\n\nfunction log(order: string[] = []): Logger {\n  return {\n    status() {},\n    taskStart(node) {\n      order.push(`start ${node.id}`)\n    },\n    taskStdout() {},\n    taskStderr() {},\n    taskComplete(node) {\n      order.push(`end ${node.id}`)\n    },\n  }\n}\n\nit('a run on an empty local cache restores from the directory', async () => {\n  const dir = await pkg(\n    'a',\n    `export default { tasks: { build: {\n      exec: { command: 'mkdir -p dist && echo built > dist/out.txt' },\n      inputs: { files: ['package.json'] }, cache: { outputs: { files: ['dist/**'] } },\n    } } }`,\n  )\n  await workspace(`dirCache(${JSON.stringify(path.join(root, 'remote'))})`)\n  const first = await run({ cwd: root, tasks: ['build'], log: log(), handleSignals: false })\n  expect(first.outcomes.map((o) => o.status)).toEqual(['success'])\n  await rm(path.join(root, '.vx', 'cache'), { recursive: true, force: true })\n  await rm(path.join(dir, 'dist'), { recursive: true, force: true })\n  const second = await run({ cwd: root, tasks: ['build'], log: log(), handleSignals: false })\n  expect(second.outcomes.map((o) => o.status)).toEqual(['cache-hit-remote'])\n  expect(await Bun.file(path.join(dir, 'dist', 'out.txt')).text()).toBe('built\\n')\n}, 20_000)\n",
   },
   commands: {
     plugin:
@@ -31,7 +31,7 @@ export const PLUGIN_TEMPLATES: Readonly<Record<string, { plugin: string; test: s
   key: {
     plugin:
       "// `key`: extra cache-key material. The value of each named environment\n// variable is folded into every cached task's key and named in `vx why`,\n// so a change to it is a miss. An unset variable folds as ''.\nimport { definePlugin, type VxPlugin } from '@vzn/vx'\n\nexport function envKey(names: readonly string[]): VxPlugin {\n  return definePlugin(import.meta, {\n    key() {\n      return Object.fromEntries(names.map((n) => [n, process.env[n] ?? '']))\n    },\n  })\n}\n",
-    test: "// A test for the example `key` plugin beside it: a throwaway workspace\n// declares the plugin and vx's own run() drives it. `bun test` runs it.\nimport { mkdir, mkdtemp, rm, writeFile } from 'node:fs/promises'\nimport os from 'node:os'\nimport path from 'node:path'\nimport { afterEach, beforeEach, expect, it } from 'bun:test'\nimport { planRun, type Logger } from '@vzn/vx'\n\nlet root: string\nbeforeEach(async () => {\n  root = await mkdtemp(path.join(os.tmpdir(), 'vx-plugin-key-'))\n  await writeFile(path.join(root, 'package.json'), JSON.stringify({ name: 'ws', private: true }))\n  await writeFile(path.join(root, 'pnpm-workspace.yaml'), 'packages:\\n  - \"packages/*\"\\n')\n  Bun.spawnSync({ cmd: ['git', 'init', '-q'], cwd: root })\n})\nafterEach(async () => {\n  await rm(root, { recursive: true, force: true })\n})\n\n/** A package `name` whose `vx.config.mjs` is `config`. */\nasync function pkg(\n  name: string,\n  config: string,\n  scripts?: Record<string, string>,\n): Promise<string> {\n  const dir = path.join(root, 'packages', name)\n  await mkdir(dir, { recursive: true })\n  await writeFile(\n    path.join(dir, 'package.json'),\n    JSON.stringify({ name, version: '1.0.0', ...(scripts ? { scripts } : {}) }),\n  )\n  // Core reads no package.json: the config names the project.\n  await writeFile(\n    path.join(dir, 'vx.config.mjs'),\n    config.replace('export default {', `export default { name: ${JSON.stringify(name)},`),\n  )\n  return dir\n}\n\n/**\n * A `.vx/workspace.mjs` declaring `call`, e.g. `envKey()`, from the plugin file\n * beside this test, then `vx lock`: a run reads project configs only from the lock.\n */\nasync function workspace(call: string): Promise<void> {\n  const from = JSON.stringify(path.join(import.meta.dir, 'key.ts'))\n  await Bun.write(\n    path.join(root, '.vx/workspace.mjs'),\n    `import { envKey } from ${from}\\nexport default { plugins: [${call}] }\\n`,\n  )\n  const vx = path.join(path.dirname(new URL(import.meta.resolve('@vzn/vx')).pathname), 'bin.ts')\n  const lock = Bun.spawnSync({ cmd: [process.execPath, vx, 'lock'], cwd: root })\n  expect([lock.exitCode, lock.stderr.toString()]).toEqual([0, ''])\n}\n\nfunction log(order: string[] = []): Logger {\n  return {\n    status() {},\n    taskStart(node) {\n      order.push(`start ${node.id}`)\n    },\n    taskStdout() {},\n    taskStderr() {},\n    taskComplete(node) {\n      order.push(`end ${node.id}`)\n    },\n  }\n}\n\nit(\"the variable's value moves the key; the same value keeps it\", async () => {\n  await pkg(\n    'a',\n    `export default { tasks: { build: {\n      exec: { command: 'true' },\n      cache: { inputs: { files: ['package.json'] }, outputs: { files: [] } },\n    } } }`,\n  )\n  await workspace(`envKey(['EXAMPLE_FLAG'])`)\n  const hash = async (value: string): Promise<string | undefined> => {\n    process.env['EXAMPLE_FLAG'] = value\n    try {\n      const plan = await planRun({ cwd: root, tasks: ['build'], log: log() })\n      return plan.tasks[0]!.hash\n    } finally {\n      delete process.env['EXAMPLE_FLAG']\n    }\n  }\n  const one = await hash('1')\n  expect(one).toBeDefined()\n  expect(await hash('1')).toBe(one)\n  expect(await hash('2')).not.toBe(one)\n}, 20_000)\n",
+    test: "// A test for the example `key` plugin beside it: a throwaway workspace\n// declares the plugin and vx's own run() drives it. `bun test` runs it.\nimport { mkdir, mkdtemp, rm, writeFile } from 'node:fs/promises'\nimport os from 'node:os'\nimport path from 'node:path'\nimport { afterEach, beforeEach, expect, it } from 'bun:test'\nimport { planRun, type Logger } from '@vzn/vx'\n\nlet root: string\nbeforeEach(async () => {\n  root = await mkdtemp(path.join(os.tmpdir(), 'vx-plugin-key-'))\n  await writeFile(path.join(root, 'package.json'), JSON.stringify({ name: 'ws', private: true }))\n  await writeFile(path.join(root, 'pnpm-workspace.yaml'), 'packages:\\n  - \"packages/*\"\\n')\n  Bun.spawnSync({ cmd: ['git', 'init', '-q'], cwd: root })\n})\nafterEach(async () => {\n  await rm(root, { recursive: true, force: true })\n})\n\n/** A package `name` whose `vx.config.mjs` is `config`. */\nasync function pkg(\n  name: string,\n  config: string,\n  scripts?: Record<string, string>,\n): Promise<string> {\n  const dir = path.join(root, 'packages', name)\n  await mkdir(dir, { recursive: true })\n  await writeFile(\n    path.join(dir, 'package.json'),\n    JSON.stringify({ name, version: '1.0.0', ...(scripts ? { scripts } : {}) }),\n  )\n  // Core reads no package.json: the config names the project.\n  await writeFile(\n    path.join(dir, 'vx.config.mjs'),\n    config.replace('export default {', `export default { name: ${JSON.stringify(name)},`),\n  )\n  return dir\n}\n\n/**\n * A `.vx/workspace.mjs` declaring `call`, e.g. `envKey()`, from the plugin file\n * beside this test, then `vx lock`: a run reads project configs only from the lock.\n */\nasync function workspace(call: string): Promise<void> {\n  const from = JSON.stringify(path.join(import.meta.dir, 'key.ts'))\n  await Bun.write(\n    path.join(root, '.vx/workspace.mjs'),\n    `import { envKey } from ${from}\\nexport default { plugins: [${call}] }\\n`,\n  )\n  const vx = path.join(path.dirname(new URL(import.meta.resolve('@vzn/vx')).pathname), 'bin.ts')\n  const lock = Bun.spawnSync({ cmd: [process.execPath, vx, 'lock'], cwd: root })\n  expect([lock.exitCode, lock.stderr.toString()]).toEqual([0, ''])\n}\n\nfunction log(order: string[] = []): Logger {\n  return {\n    status() {},\n    taskStart(node) {\n      order.push(`start ${node.id}`)\n    },\n    taskStdout() {},\n    taskStderr() {},\n    taskComplete(node) {\n      order.push(`end ${node.id}`)\n    },\n  }\n}\n\nit(\"the variable's value moves the key; the same value keeps it\", async () => {\n  await pkg(\n    'a',\n    `export default { tasks: { build: {\n      exec: { command: 'true' },\n      inputs: { files: ['package.json'] }, cache: { outputs: { files: [] } },\n    } } }`,\n  )\n  await workspace(`envKey(['EXAMPLE_FLAG'])`)\n  const hash = async (value: string): Promise<string | undefined> => {\n    process.env['EXAMPLE_FLAG'] = value\n    try {\n      const plan = await planRun({ cwd: root, tasks: ['build'], log: log() })\n      return plan.tasks[0]!.hash\n    } finally {\n      delete process.env['EXAMPLE_FLAG']\n    }\n  }\n  const one = await hash('1')\n  expect(one).toBeDefined()\n  expect(await hash('1')).toBe(one)\n  expect(await hash('2')).not.toBe(one)\n}, 20_000)\n",
   },
   project: {
     plugin:

package/src/cli/select.ts

@@ -51,7 +51,7 @@ import {
 import { resolveSetting } from '../settings.js'
 
 /**
- * The projects whose tasks declare a `cache.inputs.workspaceFiles` glob
+ * The projects whose tasks declare an `inputs.workspaceFiles` glob
  * matching a changed path, one inside another project included (item
  * 954): `--affected` selects them, since the glob is that task's input. Through the run
  * path's staged load, so a glob a `project` plugin gave a config-less
@@ -71,10 +71,8 @@ export async function workspaceGlobOwners(
 ): Promise<string[]> {
   const declaresMatch = (config: ProjectConfig): boolean => {
     for (const task of Object.values(config.tasks ?? {})) {
-      const cache = task.cache
-      if (cache === undefined) continue
-      if (changed.some((rel) => declaresInput(cache, null, rel))) return true
-      if (nested.some((dir) => workspaceFilesReachInto(cache, dir))) return true
+      if (changed.some((rel) => declaresInput(task, null, rel))) return true
+      if (nested.some((dir) => workspaceFilesReachInto(task, dir))) return true
     }
     return false
   }
@@ -335,7 +333,19 @@ export async function resolveFilters(
         workspaceGlobOwners: (changed: readonly string[], nested: readonly string[]) =>
           workspaceGlobOwners(root, projects, changed, load, stagedOnce, nested),
         fingerprintClaims: () => workspaceFingerprintClaims(root, projects, load),
-        ...(git !== undefined ? { untracked: async () => (await git.start()).untracked } : {}),
+        ...(git !== undefined
+          ? {
+              untracked: async () => (await git.start()).untracked,
+              // A scoped enumeration lists only its projects: null asks git.
+              links: async () => {
+                const g = await git.start()
+                if (!g.scopes.includes('.')) return null
+                const out: string[] = []
+                for (const [rel, oid] of g.trusted) if (oid.startsWith('120000:')) out.push(rel)
+                return out
+              },
+            }
+          : {}),
       }
       let names: Set<string>
       if (f.raw === affected) {

package/src/cli/show.ts

@@ -466,14 +466,17 @@ function taskRows(raw: TaskConfig): ui.FieldRow[] {
     )
   }
   add('interactive', exec?.interactive === undefined ? undefined : exec.interactive ? 'yes' : 'no')
+  const inputs = task.inputs
+  if (inputs !== undefined) {
+    add('inputs.files', list(inputs.files))
+    add('inputs.workspaceFiles', list(inputs.workspaceFiles))
+    add('inputs.env', list(inputs.env))
+    add('inputs.tasks', list(inputs.tasks))
+    add('inputs.runtime', list(inputs.runtime))
+    add('inputs.workspaceRuntime', list(inputs.workspaceRuntime))
+  }
   const cache = task.cache
   if (cache !== undefined) {
-    add('inputs.files', list(cache.inputs.files))
-    add('inputs.workspaceFiles', list(cache.inputs.workspaceFiles))
-    add('inputs.env', list(cache.inputs.env))
-    add('inputs.tasks', list(cache.inputs.tasks))
-    add('inputs.runtime', list(cache.inputs.runtime))
-    add('inputs.workspaceRuntime', list(cache.inputs.workspaceRuntime))
     add('outputs.files', list(cache.outputs.files))
     add('outputs.workspaceFiles', list(cache.outputs.workspaceFiles))
   }

package/src/cli/upgrade.ts

@@ -112,13 +112,18 @@ export function versionSpec(tag: string | undefined): string {
  * as an internal error with a stack (a network namespace without a
  * route, 2026-09-16). One line, the host and the reason.
  */
-async function fetchOrRefuse(url: string, init: RequestInit, what: string): Promise<Response> {
+async function fetchOrRefuse(
+  url: string,
+  init: RequestInit,
+  what: string,
+  verb = 'vx upgrade',
+): Promise<Response> {
   try {
     return await fetch(url, init)
   } catch (err) {
     const message = err instanceof Error ? err.message : String(err)
     throw new UserError(
-      `vx upgrade: could not reach ${new URL(url).host} to ${what} (${message}) — check the network or the proxy and re-run`,
+      `${verb}: could not reach ${new URL(url).host} to ${what} (${message}) — check the network or the proxy and re-run`,
     )
   }
 }
@@ -130,33 +135,43 @@ async function fetchOrRefuse(url: string, init: RequestInit, what: string): Prom
  * connection was closed unexpectedly"), which `fetchOrRefuse` never sees
  * and the CLI printed as an internal error with a stack.
  */
-async function readOrRefuse<T>(read: () => Promise<T>, url: string, what: string): Promise<T> {
+async function readOrRefuse<T>(
+  read: () => Promise<T>,
+  url: string,
+  what: string,
+  verb = 'vx upgrade',
+): Promise<T> {
   try {
     return await read()
   } catch (err) {
     const message = err instanceof Error ? err.message : String(err)
     throw new UserError(
-      `vx upgrade: could not ${what} from ${new URL(url).host} (${message}) — nothing replaced; check the network or the proxy and re-run`,
+      `${verb}: could not ${what} from ${new URL(url).host} (${message}) — nothing replaced; check the network or the proxy and re-run`,
     )
   }
 }
 
 /** The registry's document for `pkg@spec` (`latest` or a version). */
-export async function fetchManifest(pkg: string, spec: string): Promise<unknown> {
+export async function fetchManifest(
+  pkg: string,
+  spec: string,
+  verb = 'vx upgrade',
+): Promise<unknown> {
   const url = `${REGISTRY}/${pkg}/${spec}`
   const res = await fetchOrRefuse(
     url,
     { redirect: 'follow', headers: { Accept: 'application/json', 'User-Agent': `vx/${VERSION}` } },
     'read the release',
+    verb,
   )
   if (!res.ok) {
     throw new UserError(
-      `vx upgrade: could not read ${pkg}@${spec} from the npm registry (${res.status})${res.status === 404 && spec !== 'latest' ? ` — is ${spec} a published version?` : ''}`,
+      `${verb}: could not read ${pkg}@${spec} from the npm registry (${res.status})${res.status === 404 && spec !== 'latest' ? ` — is ${spec} a published version?` : ''}`,
     )
   }
   // A body that is not JSON (a captive portal's page, a proxy's error
   // page served with a 200) is the same refusal as a cut one.
-  return await readOrRefuse(() => res.json(), url, 'read the release')
+  return await readOrRefuse(() => res.json(), url, 'read the release', verb)
 }
 
 /** What a verified registry document names: the version, its tarball and the signed integrity. */
@@ -395,6 +410,8 @@ export interface ManagedInstall {
   cwd: string
   /** The project field that lists `@vzn/vx`. */
   field?: 'dependencies' | 'devDependencies' | 'optionalDependencies'
+  /** The `@vzn/vx-*` plugins the same package.json lists from the registry, moved with core. */
+  plugins?: string[]
 }
 
 const FIELDS = ['devDependencies', 'dependencies', 'optionalDependencies'] as const
@@ -417,6 +434,45 @@ function listingField(dir: string): ManagedInstall['field'] | undefined {
   })
 }
 
+/** A release's platform binary, which the launcher pulls in itself: no plugin. */
+const PLATFORM = /^@vzn\/vx-(?:darwin|linux)-(?:x64|arm64)$/
+
+/**
+ * The `@vzn/vx-*` plugins `dir`'s package.json lists from the registry
+ * (a `workspace:` or `file:` link is the repo's own). Every @vzn package
+ * releases together, so they move with core in its one install (M,
+ * 2026-10-16); one in another field would move fields under core's flag,
+ * so it is refused.
+ */
+function pluginsBeside(dir: string, field: NonNullable<ManagedInstall['field']>): string[] {
+  const pkg = readJson(path.join(dir, 'package.json'))
+  const plugins: string[] = []
+  for (const f of FIELDS) {
+    const deps = pkg?.[f]
+    if (typeof deps !== 'object' || deps === null) continue
+    for (const [name, spec] of Object.entries(deps as Record<string, unknown>)) {
+      if (!name.startsWith(`${PACKAGE}-`) || PLATFORM.test(name)) continue
+      if (typeof spec !== 'string' || /^(?:workspace|file|link|portal):/.test(spec)) continue
+      if (f !== field) {
+        throw new UserError(
+          `vx upgrade: ${name} is in ${f} and ${PACKAGE} in ${field}; list them in one field so one install moves them together`,
+        )
+      }
+      plugins.push(name)
+    }
+  }
+  return plugins.sort()
+}
+
+/** The version of `pkg` installed where `dir` resolves it, if any. */
+function installedVersion(dir: string, pkg: string): string | undefined {
+  for (let d = dir; ; d = path.dirname(d)) {
+    const v = readJson(path.join(d, 'node_modules', pkg, 'package.json'))?.['version']
+    if (typeof v === 'string') return v
+    if (path.dirname(d) === d) return undefined
+  }
+}
+
 /** The project's package manager: its lockfile, then `packageManager`, then the tree's shape. */
 function projectManager(dir: string, execPath: string): ManagedInstall['manager'] {
   for (let d = dir; ; d = path.dirname(d)) {
@@ -463,12 +519,15 @@ export function managedInstall(execPath: string, cwd: string): ManagedInstall |
   if (/\/yarn\/global\//.test(p)) return { manager: 'yarn', scope: 'global', cwd: root }
   const field = listingField(root)
   if (field !== undefined) {
-    return { manager: projectManager(root, execPath), scope: 'project', cwd: root, field }
+    const plugins = pluginsBeside(root, field)
+    return { manager: projectManager(root, execPath), scope: 'project', cwd: root, field, plugins }
   }
   for (let d = path.resolve(cwd); d.startsWith(root); d = path.dirname(d)) {
     const f = listingField(d)
-    if (f !== undefined)
-      return { manager: projectManager(d, execPath), scope: 'project', cwd: d, field: f }
+    if (f !== undefined) {
+      const plugins = pluginsBeside(d, f)
+      return { manager: projectManager(d, execPath), scope: 'project', cwd: d, field: f, plugins }
+    }
     if (path.dirname(d) === d) break
   }
   // npm's global tree: `<prefix>/lib/node_modules` (nvm, volta, Homebrew alike).
@@ -503,7 +562,8 @@ export function upgradeArgv(install: ManagedInstall, version: string): string[]
     bun: { devDependencies: '--dev', dependencies: '', optionalDependencies: '--optional' },
     yarn: { devDependencies: '--dev', dependencies: '', optionalDependencies: '--optional' },
   }[manager][field]
-  const argv = manager === 'npm' ? ['npm', 'install', spec] : [manager, 'add', spec]
+  const specs = [spec, ...(install.plugins ?? []).map((p) => `${p}@${version}`)]
+  const argv = manager === 'npm' ? ['npm', 'install', ...specs] : [manager, 'add', ...specs]
   if (flag !== '') argv.push(flag)
   // pnpm refuses an `add` at a workspace's root without saying it means the root.
   if (manager === 'pnpm' && existsSync(path.join(install.cwd, 'pnpm-workspace.yaml')))
@@ -511,13 +571,17 @@ export function upgradeArgv(install: ManagedInstall, version: string): string[]
   return argv
 }
 
-/** The version `tag` names, or the registry's latest, read for the "already at" check. */
-async function targetVersion(tag: string | undefined): Promise<string> {
+/**
+ * The version `tag` names, or the registry's latest: read for the "already
+ * at" check, and by `vx init`, which always installs the latest release.
+ */
+export async function targetVersion(tag: string | undefined, verb = 'vx upgrade'): Promise<string> {
   const spec = versionSpec(tag)
   if (spec !== 'latest') return spec
-  const v = ((await fetchManifest(PACKAGE, 'latest')) as { version?: unknown } | null)?.version
+  const v = ((await fetchManifest(PACKAGE, 'latest', verb)) as { version?: unknown } | null)
+    ?.version
   if (typeof v !== 'string' || !/^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/.test(v)) {
-    throw new UserError(`vx upgrade: the npm registry named no latest version of ${PACKAGE}`)
+    throw new UserError(`${verb}: the npm registry named no latest version of ${PACKAGE}`)
   }
   return v
 }
@@ -527,13 +591,14 @@ async function targetVersion(tag: string | undefined): Promise<string> {
  * `version`; vx never installs one. `step` names the install when a run
  * moves two (`project `, `global `).
  */
-async function upgradeManaged(
+export async function upgradeManaged(
   install: ManagedInstall,
   version: string,
   current = VERSION,
   step = '',
 ): Promise<void> {
-  if (version === current) {
+  const plugins = install.plugins ?? []
+  if (version === current && plugins.every((p) => installedVersion(install.cwd, p) === version)) {
     ui.print('out', ui.status('info', 'vx upgrade', `${step}already at ${current}`))
     return
   }
@@ -547,7 +612,11 @@ async function upgradeManaged(
   }
   ui.print(
     'out',
-    ui.status('info', 'vx upgrade', `${step}${current} → ${version}`),
+    ui.status(
+      'info',
+      'vx upgrade',
+      `${step}${version === current ? 'plugins' : current} → ${version}`,
+    ),
     ui.text([ui.cmd(argv.join(' ')), ui.dim(` in ${install.cwd}`)]),
   )
   const proc = Bun.spawnSync({
@@ -557,7 +626,14 @@ async function upgradeManaged(
   })
   if (proc.exitCode !== 0) {
     throw new UserError(
-      `vx upgrade: ${argv.join(' ')} failed (exit ${proc.exitCode}) — vx changed nothing itself`,
+      `vx upgrade: ${argv.join(' ')} failed (exit ${proc.exitCode}) — vx changed nothing itself${
+        // The install is pinned, so pnpm refuses a release younger than
+        // its minimumReleaseAge instead of mixing releases; its words
+        // print above, so the way out is named (as vx-migrate does).
+        install.manager === 'pnpm'
+          ? `; if pnpm refused a version published within its minimumReleaseAge, list ${[PACKAGE, ...plugins].join(', ')} under minimumReleaseAgeExclude in pnpm-workspace.yaml`
+          : ''
+      }`,
     )
   }
 }

package/src/cli/watch-filter.ts

@@ -2,6 +2,7 @@
 // rules, git-ignored paths, the root arm's filter) and which files reshape
 // the watched set. Pure decisions over paths; the loop acts on them.
 
+import fs from 'node:fs'
 import path from 'node:path'
 import {
   executablePath,
@@ -369,12 +370,14 @@ export function gitSpeller(root: string): (p: string) => string {
  * a project moved away whole is one event on its directory): what existed
  * when watch armed, so a path born and gone since is told from a deletion
  * (watch-judge.ts). `tracked` is the files git tracks: a user edits those,
- * so a server cannot be blamed for one. Undefined when git cannot answer:
+ * so a server cannot be blamed for one. `links` is the symlinks among the
+ * files: a key reads what each points to (cache/linked-inputs.ts), so watch
+ * arms that too. Undefined when git cannot answer:
  * no inventory, every gone path is a deletion as before.
  */
 export function gitFiles(
   workspaceRoot: string,
-): { listed: Set<string>; tracked: Set<string> } | undefined {
+): { listed: Set<string>; tracked: Set<string>; links: Set<string> } | undefined {
   let proc: ReturnType<typeof Bun.spawnSync>
   try {
     proc = Bun.spawnSync({
@@ -383,6 +386,7 @@ export function gitFiles(
         'ls-files',
         '-z',
         '-t',
+        '-s',
         '--cached',
         '--others',
         '--exclude-standard',
@@ -398,18 +402,30 @@ export function gitFiles(
   if (proc.exitCode !== 0) return undefined
   const files = new Set<string>()
   const tracked = new Set<string>()
+  const links = new Set<string>()
   for (const entry of new TextDecoder('utf-8', { ignoreBOM: true })
     .decode(proc.stdout)
     .split('\0')) {
     if (entry.length === 0) continue
-    // `-t` prefixes a tag and a space; `?` is untracked.
-    const p = entry.slice(2)
+    // `-t` prefixes a tag and a space; `?` is untracked, a bare path. A
+    // tracked entry is `-s`'s `<mode> <oid> <stage>\t<path>` after the tag.
+    const untracked = entry[0] === '?'
+    const p = untracked ? entry.slice(2) : entry.slice(entry.indexOf('\t') + 1)
     // An untracked nested repository is listed as `dir/`.
     let abs = path.join(workspaceRoot, p.endsWith('/') ? p.slice(0, -1) : p)
     files.add(abs)
-    if (entry[0] !== '?') tracked.add(abs)
+    if (!untracked) tracked.add(abs)
+    if (untracked ? isLink(abs) : entry.startsWith('120000 ', 2)) links.add(abs)
     for (abs = path.dirname(abs); abs !== workspaceRoot && !files.has(abs); abs = path.dirname(abs))
       files.add(abs)
   }
-  return { listed: files, tracked }
+  return { listed: files, tracked, links }
+}
+
+function isLink(abs: string): boolean {
+  try {
+    return fs.lstatSync(abs).isSymbolicLink()
+  } catch {
+    return false
+  }
 }

package/src/cli/watch-judge.ts

@@ -4,6 +4,7 @@
 
 import fs from 'node:fs'
 import path from 'node:path'
+import { filesBehind } from '../cache/index.js'
 import { xxh3 } from '../util/index.js'
 import { gitIgnored, gitSpeller } from './watch-filter.js'
 import { modifiedBefore } from './watch-fs.js'
@@ -13,9 +14,10 @@ const ABSENT = -1n
 function settledState(abs: string): bigint {
   let st: fs.Stats
   try {
-    // A link is its target string, as the key folds it: following it saw
-    // a retarget to equal bytes as "the same" and ran nothing.
-    if (fs.lstatSync(abs).isSymbolicLink()) return xxh3(`link:${fs.readlinkSync(abs)}`)
+    // A link is its target string and what it points to, as the key folds
+    // it: following it alone saw a retarget to equal bytes as "the same".
+    if (fs.lstatSync(abs).isSymbolicLink())
+      return xxh3(`link:${fs.readlinkSync(abs)}\0${behindState(abs)}`)
     st = fs.statSync(abs)
   } catch {
     return ABSENT
@@ -50,6 +52,34 @@ function settledState(abs: string): bigint {
   return xxh3(Buffer.from(entries.join('\n')))
 }
 
+/**
+ * What a link points to, as change detection reads it: a file's bytes and
+ * mode, a directory's files by size and times (cache/linked-inputs.ts keys
+ * their bytes), nothing for a dangling link.
+ */
+function behindState(link: string): string {
+  let real: string
+  let st: fs.Stats
+  try {
+    real = fs.realpathSync(link)
+    st = fs.statSync(real)
+  } catch {
+    return ''
+  }
+  if (st.isFile()) return `${xxh3(fs.readFileSync(real))}:${st.mode & 0o7777}`
+  if (!st.isDirectory()) return ''
+  return filesBehind(real)
+    .map((rel) => {
+      try {
+        const f = fs.statSync(path.join(real, rel))
+        return `${rel}\0${f.size}\0${f.mtimeMs}\0${f.ctimeMs}`
+      } catch {
+        return rel
+      }
+    })
+    .join('\n')
+}
+
 /** What the judgement reads from the loop, which owns it and may replace it. */
 export interface JudgeContext {
   workspaceRoot: string
@@ -59,6 +89,8 @@ export interface JudgeContext {
   held(): boolean
   /** Projects whose uncached task may read a git-ignored file. */
   uncached(): ReadonlySet<string>
+  /** Paths a task's inputs name outright: a git-ignored file at or under one is an input. */
+  namedIgnored?(): readonly string[]
   /** Whether `abs`, under the project at `ownDir`, lies in a project nested there (`makeFence`). */
   fenced?(ownDir: string, abs: string): boolean
   /** The files git listed at the arm; absent when git could not answer. */
@@ -113,6 +145,15 @@ export class ChangeJudge {
 
   constructor(private readonly ctx: JudgeContext) {}
 
+  /**
+   * Record a path's state as it is, if this loop has not: a link armed for
+   * what it points to, whose own times say "before the arm" whatever
+   * changed behind it, so its first sighting compares against this.
+   */
+  seed(abs: string): void {
+    if (!this.lastState.has(abs)) this.lastState.set(abs, settledState(abs))
+  }
+
   // A path this loop has never judged is a change only if it moved since
   // the watchers went live (its mtime or ctime, `modifiedBefore`). macOS delivers the initial run's own writes
   // AFTER the arm (CI, 2026-09-11: `app dist; re-running...` with no edit
@@ -192,10 +233,13 @@ export class ChangeJudge {
     // user wrote it; one the last cycle wrote (the pid file an uncached
     // task rewrites every run, the loop the filter exists for) stays out,
     // as does one in a project nested under it, which it does not own.
+    // So is one a task's inputs name outright (`.env.local`, `dist/**`).
     const editForUncached = (p: string): boolean =>
-      [...this.ctx.uncached()].some(
+      ([...this.ctx.uncached()].some(
         (dir) => p.startsWith(dir + path.sep) && this.ctx.fenced?.(dir, p) !== true,
-      ) && !this.writtenDuringLastCycle(p)
+      ) ||
+        (this.ctx.namedIgnored?.() ?? []).some((n) => p === n || p.startsWith(n + path.sep))) &&
+      !this.writtenDuringLastCycle(p)
     // A path still there names the cycle before a gone one: an editor or
     // `sed -i` saving through a temporary file fires that file first, and
     // the cycle was announced by a name already renamed away.