@vzn/vx 0.0.639 → 0.0.641

package/src/cache/layer.ts

@@ -5,13 +5,14 @@
 // reference to `Cache` below is a type (the local handle a layer may wrap).
 
 import type { Cache } from './cache.js'
+import { fsClockLag, stampGrainMs } from './fs-clock.js'
 
 export interface CacheKeyInput {
   taskId: string
   /**
    * Hash of the resolved task config (post-evaluation). Folds in everything
    * the user wrote — command, env declarations (passThrough names + define
-   * key/value pairs), dependsOn, cache.inputs declarations, outputs — including
+   * key/value pairs), dependsOn, inputs declarations, outputs — including
    * values that arrived via `import` at config-load time.
    */
   taskConfigHash: string
@@ -22,12 +23,12 @@ export interface CacheKeyInput {
    */
   envValues: Array<[name: string, value: string | undefined]>
   /**
-   * Resolved `cache.inputs.runtime` commands as [command, output] pairs
+   * Resolved `inputs.runtime` commands as [command, output] pairs
    * (output = trimmed stdout+stderr, resolved live at hash time). Folded
    * into the key in a namespace distinct from workspaceRuntimeValues.
    */
   runtimeValues?: Array<[command: string, output: string]>
-  /** Resolved `cache.inputs.workspaceRuntime` pairs (root-cwd commands). */
+  /** Resolved `inputs.workspaceRuntime` pairs (root-cwd commands). */
   workspaceRuntimeValues?: Array<[command: string, output: string]>
   /** Absolute paths to input files. */
   inputFiles: string[]
@@ -51,7 +52,7 @@ export interface CacheKeyInput {
    * - It expands groups, which contribute a synthetic roll-up hash and no
    *   outputs of their own, so a dependent of one would otherwise describe
    *   an empty closure.
-   * - It ignores `cache.inputs.tasks`. That filter says which upstream KEYS
+   * - It ignores `inputs.tasks`. That filter says which upstream KEYS
    *   this task's key folds; what the task may READ is `dependsOn`, and
    *   locally every dependency's outputs are on disk before the command runs
    *   however the filter is written.
@@ -411,11 +412,11 @@ export const FILE_HASH_RACY_MS = 50
  * field (A-38). Pass the UNFLOORED stamp: a kernel's nanosecond stamp lands
  * on a whole second about once in 10^9, one set through a millisecond
  * `utimes` once in a thousand, and either is then trusted up to two seconds
- * later — never wrongly.
+ * later — never wrongly. And every window is widened by how far the file
+ * system's clock runs behind this process's (`fsClockLag`, fs-clock.ts).
  */
 export function racyWindowMs(stampMs: number, windowMs: number): number {
-  if (stampMs % 2000 === 0) return windowMs + 2000
-  return stampMs % 1000 === 0 ? windowMs + 1000 : windowMs
+  return windowMs + stampGrainMs(stampMs) + fsClockLag()
 }
 
 /**
@@ -676,7 +677,13 @@ export interface CacheLayer {
    * into the workspace root. Callers restoring entries that may carry
    * workspace outputs must pass `workspaceRoot`.
    */
-  restoreOutputs(hash: string, projectDir: string, workspaceRoot?: string): Promise<void>
+  restoreOutputs(
+    hash: string,
+    projectDir: string,
+    workspaceRoot?: string,
+    /** The task's declared outputs: an entry outside them fails the restore, nothing written. */
+    outputs?: DeclaredOutputs,
+  ): Promise<void>
   save(args: {
     hash: string
     /**

package/src/cache/layered-cache.ts

@@ -21,6 +21,7 @@ import type { Cache } from './cache.js'
 import type {
   CacheEntry,
   CacheGetContext,
+  DeclaredOutputs,
   CacheKeyInput,
   CacheLayer,
   CacheStats,
@@ -61,11 +62,6 @@ export interface RemoteCacheLayer {
    * dropped before it is printed.
    */
   readonly endpoint?: string
-  /**
-   * What the wire's credential allows, when less than both (a read-only
-   * token): core clears the run's remote axis it lacks. Omitted → both.
-   */
-  readonly access?: { readonly read?: boolean; readonly write?: boolean }
   /** Existence probe: `--dry` and `--force` ask it per key when the remote cannot batch. */
   has(hash: string): Promise<boolean>
   /**
@@ -330,8 +326,13 @@ export class LayeredCache implements CacheLayer {
     return this.local.hashFile(filePath)
   }
 
-  async restoreOutputs(hash: string, projectDir: string, workspaceRoot?: string): Promise<void> {
-    await this.local.restoreOutputs(hash, projectDir, workspaceRoot)
+  async restoreOutputs(
+    hash: string,
+    projectDir: string,
+    workspaceRoot?: string,
+    outputs?: DeclaredOutputs,
+  ): Promise<void> {
+    await this.local.restoreOutputs(hash, projectDir, workspaceRoot, outputs)
   }
 
   async save(args: SaveArgs): Promise<void> {

package/src/cache/linked-inputs.ts

@@ -0,0 +1,87 @@
+// A symlinked input keys the content behind it, as Nx reads a linked file
+// where it points (owner, 2026-10-16: "Do like nx"). Its own fold stays the
+// blob of its target STRING (file-hashes.ts), so a retarget to equal bytes
+// moves the key; this is what follows it. The target string alone let an
+// edit behind the link replay the old output (Growth, 2026-10-16), wherever
+// the target lies: in the project, elsewhere in the workspace, outside it.
+// A directory link keys every file beneath it, tracked or not, where Nx
+// does not enter one: an edit there is an edit to what the task reads.
+// `--affected` (workspace/affected.ts) and `vx watch` (cli/watch.ts) read
+// the same targets.
+
+import { readdirSync, realpathSync, statSync } from 'node:fs'
+import path from 'node:path'
+import { xxh3hex } from '../util/index.js'
+import { absentOr } from './key-fold.js'
+
+/** What a dangling link, or a loop of links, holds behind it: nothing to read. */
+const NOTHING_BEHIND = ''
+
+/**
+ * Directories a linked directory's walk never enters, as Nx's walker never
+ * does (its HARDCODED_IGNORE_PATTERNS): a link to a workspace would
+ * otherwise key the cache each run writes.
+ */
+const SKIPPED = ['.git', 'node_modules', '.vx/cache', '.yarn/cache']
+const skipped = (rel: string): boolean => SKIPPED.some((s) => rel === s || rel.endsWith(`/${s}`))
+
+/**
+ * The files under `dir` a linked directory keys, relative and `/`-separated,
+ * sorted: every regular file and link at any depth. A link is listed, never
+ * entered (`behindLink` follows it), so a loop of directories ends.
+ */
+export function filesBehind(dir: string): string[] {
+  const out: string[] = []
+  const walk = (abs: string, rel: string): void => {
+    let entries
+    try {
+      entries = readdirSync(abs, { withFileTypes: true })
+    } catch {
+      return
+    }
+    for (const e of entries) {
+      const childRel = rel === '' ? e.name : `${rel}/${e.name}`
+      if (e.isDirectory()) {
+        if (!skipped(childRel)) walk(path.join(abs, e.name), childRel)
+      } else if (e.isFile() || e.isSymbolicLink()) out.push(childRel)
+    }
+  }
+  walk(dir, '')
+  return out.sort()
+}
+
+/**
+ * The content behind the symlink at `link`, as one string: a file's identity
+ * (`hashFile` of its real path), a directory's files and theirs, or
+ * `NOTHING_BEHIND` for a dangling link or a loop. A special file (a FIFO, a
+ * device) is named, never read: a read can block. Never memoized: an upstream
+ * task may write behind the link between two keys.
+ */
+export async function behindLink(
+  link: string,
+  hashFile: (file: string) => Promise<string>,
+  seen: ReadonlySet<string> = new Set(),
+): Promise<string> {
+  let real: string
+  let st
+  try {
+    real = realpathSync(link)
+    st = statSync(real)
+  } catch {
+    return NOTHING_BEHIND
+  }
+  if (seen.has(real)) return NOTHING_BEHIND
+  if (st.isFile()) return `file\0${await hashFile(real).catch(absentOr)}`
+  if (!st.isDirectory()) return 'special'
+  const inner = new Set(seen).add(real)
+  const parts = await Promise.all(
+    filesBehind(real).map(async (rel) => {
+      const abs = path.join(real, rel)
+      const id = await hashFile(abs).catch(absentOr)
+      return id.startsWith('120000:')
+        ? `${rel}\0${id}\0${await behindLink(abs, hashFile, inner)}`
+        : `${rel}\0${id}`
+    }),
+  )
+  return `dir\0${xxh3hex(parts.join('\n'))}`
+}

package/src/cache/scoped-cache.ts

@@ -8,6 +8,7 @@ import type {
   CacheEntry,
   CacheGetContext,
   CacheLayer,
+  DeclaredOutputs,
   IngestMeta,
   InvocationRecord,
   OutputDirRow,
@@ -194,8 +195,13 @@ export class ScopedCache implements CacheLayer {
     return (await this.inner.outputDirsCurrent?.(projectDir, rows)) ?? false
   }
 
-  restoreOutputs(hash: string, projectDir: string, workspaceRoot?: string): Promise<void> {
-    return this.inner.restoreOutputs(this.keyOf(hash), projectDir, workspaceRoot)
+  restoreOutputs(
+    hash: string,
+    projectDir: string,
+    workspaceRoot?: string,
+    outputs?: DeclaredOutputs,
+  ): Promise<void> {
+    return this.inner.restoreOutputs(this.keyOf(hash), projectDir, workspaceRoot, outputs)
   }
 
   save(args: SaveArgs): Promise<void> {

package/src/cli/foreign-flags.ts

@@ -343,7 +343,7 @@ export const FOREIGN_FLAGS: readonly ForeignFlag[] = [
     names: ['--global-deps'],
     value: true,
     outcome: 'refuse',
-    vx: "declare them in `cache.inputs.workspaceFiles` (under `turbo()`, turbo.json's `globalDependencies`)",
+    vx: "declare them in `inputs.workspaceFiles` (under `turbo()`, turbo.json's `globalDependencies`)",
   },
   {
     runner: 'turbo',

package/src/cli/help.ts

@@ -117,7 +117,7 @@ export function helpText(pluginCommands: readonly string[] = []): string {
     '  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 upgrade [TAG] [-g|--global]',
     '  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>]',
@@ -274,6 +274,12 @@ export function helpText(pluginCommands: readonly string[] = []): string {
     '                       test (executor, cache, telemetry, schedule, admit, commands,',
     '                       project, graph, key).',
     '',
+    'Upgrade:',
+    '  vx upgrade [TAG]     Bring vx to TAG (default: latest) the way it was installed.',
+    "                       In a project: the project's vx, its @vzn/vx-* plugins and",
+    '                       the global vx that ran it, to one release.',
+    '      -g, --global     Only the global vx: no project, no plugin.',
+    '',
     'Shell completions:',
     '  vx completions <shell>   Print a completion script for bash, zsh or fish: the',
     '                           verbs (plugin verbs of this workspace included) and',

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))
   }