@vzn/vx 0.0.633 → 0.0.635

package/src/orchestrator/sandbox-fix.ts

@@ -0,0 +1,123 @@
+// The `exec.sandbox.allow` entries that would have granted what a failed
+// task was denied, so the report names the line to add (CLI, JSON, MCP)
+// rather than leaving the user to turn absolute paths into grants. Built on
+// the failure path only: a passing run never calls it.
+
+import { lstatSync } from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+import type { SandboxViolation } from '../exec/index.js'
+import type { TaskOutcome } from '../graph/index.js'
+import { isLiteralPattern } from '../util/index.js'
+
+/** Grants to add under `exec.sandbox.allow`, each list sorted and unique. */
+type SandboxFix = NonNullable<TaskOutcome['sandboxFix']>
+type Kind = Exclude<keyof SandboxFix, 'withheld'>
+
+// Where credentials live. A denial here is never turned into a grant: an
+// agent applies `sandboxFix` as given, so a dependency probing ~/.ssh would
+// get its grant suggested and applied (Security, 2026-10-12).
+const CREDENTIAL_DIRS = ['.ssh', '.aws', '.gnupg', '.kube', '.config/gh', '.config/gcloud']
+const CREDENTIAL_FILES = ['.netrc', '.npmrc', '.docker/config.json', '.git-credentials', '.pypirc']
+
+function isCredential(abs: string): boolean {
+  const base = path.basename(abs)
+  if (base === '.env' || base.startsWith('.env.')) return true
+  const rel = path.relative(os.homedir(), abs)
+  if (rel === '' || rel.startsWith('..') || path.isAbsolute(rel)) return false
+  return (
+    CREDENTIAL_FILES.includes(rel) ||
+    CREDENTIAL_DIRS.some((d) => rel === d || rel.startsWith(d + path.sep))
+  )
+}
+
+/**
+ * A path as a grant spells it: project-relative inside the project, `~/…`
+ * under home, else absolute.
+ */
+function grantPath(abs: string, projectDir: string): string {
+  const rel = path.relative(projectDir, abs)
+  if (rel !== '' && !rel.startsWith('..') && !path.isAbsolute(rel)) return rel
+  const home = os.homedir()
+  return abs.startsWith(home + path.sep) ? `~/${abs.slice(home.length + 1)}` : abs
+}
+
+/**
+ * A write grant covers the top directory the write landed in: granting
+ * `dist/a.js` alone fails the run again on `dist/b.js`. Not when the task
+ * reads that directory as an input: the grant would let it write its own
+ * inputs, so it names the path alone.
+ */
+function writeGrant(grant: string, isDir: boolean, inputs: readonly string[]): string {
+  const slash = grant.indexOf('/')
+  const exact = isDir ? `${grant}/` : grant
+  if (grant.startsWith('~/') || path.isAbsolute(grant) || slash === -1) return exact
+  const top = grant.slice(0, slash)
+  return inputs.some((g) => readsDir(g, top)) ? exact : `${top}/`
+}
+
+/** Whether input glob `g` can match under top directory `top`. */
+function readsDir(g: string, top: string): boolean {
+  if (g.startsWith('!')) return false
+  const first = g.replace(/^\.\//, '').split('/')[0] ?? ''
+  return first === top || !isLiteralPattern(first)
+}
+
+function kindOf(v: SandboxViolation): Kind | undefined {
+  const can = v.ignorable ?? []
+  if (can.length === 1) return can[0]
+  // Linux reports a refused `openat` as either: the flags the parse drops
+  // decide. A file the host has was hidden from a read; one it lacks was
+  // being created.
+  if (can.includes('read') && can.includes('write') && v.path !== undefined)
+    return lstatSync(v.path, { throwIfNoEntry: false }) !== undefined ? 'read' : 'write'
+  return undefined
+}
+
+export function sandboxFix(
+  violations: readonly SandboxViolation[],
+  projectDir: string,
+  mask: (text: string) => string = (t) => t,
+  /** The task's `cache.inputs.files`: a write under one is granted exactly. */
+  inputs: readonly string[] = [],
+): SandboxFix | undefined {
+  const fix: Record<Kind | 'withheld', Set<string>> = {
+    read: new Set(),
+    write: new Set(),
+    network: new Set(),
+    systemInfo: new Set(),
+    withheld: new Set(),
+  }
+  for (const v of violations) {
+    if (v.hint === true || v.target === undefined) continue
+    const kind = kindOf(v)
+    if (kind === undefined) continue
+    if (kind === 'network') fix.network.add(v.target.replace(/:\d+$/, ''))
+    else if (kind === 'systemInfo') fix.systemInfo.add(v.target)
+    else if (v.path === undefined) continue
+    else if (isCredential(v.path)) fix.withheld.add(grantPath(v.path, projectDir))
+    else if (kind === 'read') fix.read.add(grantPath(v.path, projectDir))
+    else {
+      const isDir =
+        v.line.startsWith('mkdir') ||
+        lstatSync(v.path, { throwIfNoEntry: false })?.isDirectory() === true
+      fix.write.add(writeGrant(grantPath(v.path, projectDir), isDir, inputs))
+    }
+  }
+  const out: SandboxFix = {}
+  for (const k of ['read', 'write', 'network', 'systemInfo', 'withheld'] as const)
+    if (fix[k].size > 0) out[k] = [...new Set([...fix[k]].map(mask))].sort()
+  return Object.keys(out).length > 0 ? out : undefined
+}
+
+/**
+ * The fix as the config line it is: `exec.sandbox.allow: { read: ['a'] }`,
+ * or undefined when every denial was a withheld credential path.
+ */
+export function sandboxFixLine({ withheld: _, ...fix }: SandboxFix): string | undefined {
+  if (Object.keys(fix).length === 0) return undefined
+  const parts = Object.entries(fix).map(
+    ([k, list]: [string, string[]]) => `${k}: [${list.map((p) => `'${p}'`).join(', ')}]`,
+  )
+  return `exec.sandbox.allow: { ${parts.join(', ')} }`
+}

package/src/orchestrator/task-hash.ts

@@ -238,11 +238,15 @@ export async function describeTaskInputs(args: ComputeHashArgs): Promise<{
  * input changed and changed BACK while the command ran matched its digest
  * again, and the entry saved the other content's output under the key (item
  * 1015). A write before it — an upstream's — is judged by content, as before.
+ * `writesByBytes` (`cache.rewrittenInputs: 'compare'`) judges a write
+ * during the command by content too: the task says the same bytes are its
+ * own identical rewrite (tsdown's package.json), not an edit undone.
  */
 export async function movedInput(
   facts: readonly InputFact[],
   cache: CacheLayer,
   commandFrom?: number,
+  writesByBytes = false,
 ): Promise<string | undefined> {
   const suspects: InputFact[] = []
   for (const f of facts) {
@@ -260,7 +264,9 @@ export async function movedInput(
     // an even one, FAT's tick), one during the command included
     // (`racyWindowMs`).
     if (commandFrom !== undefined && ctimeMs >= commandFrom - racyWindowMs(ctimeMs, 0)) {
-      return f.path
+      if (!writesByBytes) return f.path
+      suspects.push(f)
+      continue
     }
     if (ctimeMs >= f.since - racyWindowMs(ctimeMs, FILE_HASH_RACY_MS)) suspects.push(f)
   }

package/src/util/errors.ts

@@ -62,9 +62,16 @@ export function wantsJson(argv: readonly string[]): boolean {
   return false
 }
 
-/** The JSON a verb that answers JSON prints for a refusal: one line. */
+/**
+ * The JSON a verb that answers JSON prints for a refusal: one line. A
+ * core code (`VX_E_…`) links its section of cli.md, which says the fix;
+ * `vx docs <code>` prints the same section offline. A plugin's code has none.
+ */
 export function errorDocument(code: string, message: string): string {
-  return `${JSON.stringify({ ok: false, error: { code, message } })}\n`
+  const docs = code.startsWith('VX_E_')
+    ? { docs: `https://vznjs.github.io/vx/cli/#${code.toLowerCase()}` }
+    : {}
+  return `${JSON.stringify({ ok: false, error: { code, message, ...docs } })}\n`
 }
 
 /**

package/src/util/paths.ts

@@ -195,6 +195,30 @@ export const EXTGLOB = /[!@+*?]\(/
  * else: one site that forgot is a route directory that keys nothing.
  */
 export function taskGlob(pattern: string): Bun.Glob {
+  const memo = memoFor(taskGlobs)
+  let glob = memo.get(pattern)
+  if (glob === undefined) memo.set(pattern, (glob = compileTaskGlob(pattern)))
+  return glob
+}
+
+/**
+ * Compiled once per pattern: a Turbo-mapped config repeats one 400-entry
+ * list across two thousand tasks, and the graph's overlap checks compiled
+ * each entry per task pair, 3.3 s of an astro plan (2026-10-09). A pattern
+ * comes from a config, so the set is bounded by what the configs say. Kept
+ * per `Bun.Glob` in force: the playground and a test swap it, and a glob
+ * built by one is not the other's.
+ */
+const taskGlobs = new WeakMap<object, Map<string, Bun.Glob>>()
+const anyTaskGlobs = new WeakMap<object, Map<string, (rel: string) => boolean>>()
+
+function memoFor<T>(memos: WeakMap<object, Map<string, T>>): Map<string, T> {
+  let memo = memos.get(Bun.Glob)
+  if (memo === undefined) memos.set(Bun.Glob, (memo = new Map()))
+  return memo
+}
+
+function compileTaskGlob(pattern: string): Bun.Glob {
   // A `]` with no `[` before it is already literal to `Bun.Glob`.
   const source = pattern.includes('[') ? pattern.replace(/(?<!\\)[[\]]/g, '\\$&') : pattern
   const glob = new Bun.Glob(source)
@@ -228,6 +252,14 @@ export function taskGlob(pattern: string): Bun.Glob {
  * `src/a.ts` and never `src/deep/a.ts`, and an edit there was a stale hit.
  */
 export function anyTaskGlob(rawPatterns: readonly string[]): (rel: string) => boolean {
+  const memo = memoFor(anyTaskGlobs)
+  const key = rawPatterns.join('\0')
+  let any = memo.get(key)
+  if (any === undefined) memo.set(key, (any = compileAnyTaskGlob(rawPatterns)))
+  return any
+}
+
+function compileAnyTaskGlob(rawPatterns: readonly string[]): (rel: string) => boolean {
   const patterns = rawPatterns.flatMap(braceAlternatives)
   if (patterns.length === 0) return () => false
   const sources = patterns.map(regExpSource)

package/src/workspace/affected.ts

@@ -173,6 +173,7 @@ export async function affectedChanges(
   if (since.length === 0 || since.startsWith('-')) {
     throw new UserError(
       `git ref "${since}" is not a ref: a base cannot be empty or start with "-".`,
+      'VX_E_AFFECTED_BASE',
     )
   }
   // `A..B` / `A...B` reached `rev-parse --verify`, which refuses a range, and
@@ -183,6 +184,7 @@ export async function affectedChanges(
     throw new UserError(
       `git ref "${since}" is a range: ranges are not supported — pass the base alone ` +
         `("${since.slice(0, range) || 'HEAD'}"); vx diffs it against the working tree.`,
+      'VX_E_AFFECTED_BASE',
     )
   }
   // `^main` is rev-list's exclusion, not a ref: merge-base refused it, it
@@ -191,6 +193,7 @@ export async function affectedChanges(
   if (since.startsWith('^')) {
     throw new UserError(
       `git ref "${since}" is an exclusion, not a ref: pass the base alone ("${since.replace(/^\^+/, '') || 'HEAD'}").`,
+      'VX_E_AFFECTED_BASE',
     )
   }
   // Diff from the MERGE BASE of `since` and HEAD, not from `since` itself:
@@ -556,12 +559,13 @@ async function gitBlobsAt(
     proc.exited,
   ])
   if (exit !== 0) {
-    throw new UserError(`git cat-file --batch failed (exit ${exit}): ${stderr.trim()}`)
+    throw new UserError(`git cat-file --batch failed (exit ${exit}): ${stderr.trim()}`, 'VX_E_GIT')
   }
   let at = 0
   for (const file of batched) {
     const eol = out.indexOf(0x0a, at)
-    if (eol === -1) throw new UserError(`git cat-file --batch ended before ${ref}:./${file}`)
+    if (eol === -1)
+      throw new UserError(`git cat-file --batch ended before ${ref}:./${file}`, 'VX_E_GIT')
     const header = new TextDecoder().decode(out.subarray(at, eol))
     at = eol + 1
     // `<oid> <type> <size>`, or `<spec> missing` / `<spec> ambiguous`.
@@ -636,7 +640,10 @@ async function gitBytesAt(
   // "exists on disk but not in <ref>" and "path does not exist in <ref>"
   // are the file being absent at the ref; anything else is git failing.
   if (/does not exist in|exists on disk, but not in/.test(stderr)) return null
-  throw new UserError(`git show ${ref}:./${file} failed (exit ${exit}): ${stderr.trim()}`)
+  throw new UserError(
+    `git show ${ref}:./${file} failed (exit ${exit}): ${stderr.trim()}`,
+    'VX_E_GIT',
+  )
 }
 
 async function bytesOrNull(file: string): Promise<Uint8Array | null> {
@@ -654,7 +661,7 @@ async function gitPaths(workspaceRoot: string, cmd: string[]): Promise<string[]>
   const stderr = await new Response(proc.stderr).text()
   const exit = await proc.exited
   if (exit !== 0) {
-    throw new UserError(`git ${cmd[0]} failed (exit ${exit}): ${stderr.trim()}`)
+    throw new UserError(`git ${cmd[0]} failed (exit ${exit}): ${stderr.trim()}`, 'VX_E_GIT')
   }
   return stdout.split('\0').filter((s) => s.length > 0)
 }
@@ -724,6 +731,7 @@ export async function defaultAffectedBase(workspaceRoot: string): Promise<string
       '--affected has no base here: origin/HEAD is not set (or names a branch that is gone) and HEAD has no parent to compare ' +
         'with — a shallow clone? Fetch history (actions/checkout: fetch-depth: 0) or name the ' +
         'base: --affected=origin/main',
+      'VX_E_AFFECTED_BASE',
     )
   }
   return 'HEAD~1'
@@ -742,6 +750,7 @@ function noHistoryRefusal(workspaceRoot: string): UserError | undefined {
   if (revParse(workspaceRoot, 'HEAD') === undefined) {
     return new UserError(
       '--affected has no base here: this repository has no commit yet. Commit first, or run without --affected.',
+      'VX_E_AFFECTED_BASE',
     )
   }
   return undefined
@@ -832,6 +841,7 @@ async function mergeBase(workspaceRoot: string, ref: string): Promise<string> {
     throw new UserError(
       `git ref "${ref}" names what is at ${sub[2]}, not a commit: vx diffs the whole ` +
         `workspace, so pass the commit alone ("${sub[1] || 'HEAD'}").`,
+      'VX_E_AFFECTED_BASE',
     )
   }
   return ref
@@ -857,6 +867,7 @@ async function verifyRef(workspaceRoot: string, ref: string): Promise<void> {
     throw new UserError(
       `git rev-parse failed (exit ${proc.exitCode}) in ${workspaceRoot}` +
         (stderr.length > 0 ? `: ${stderr}` : ''),
+      'VX_E_GIT',
     )
   }
   // A shallow clone (CI's checkout fetches one commit by default) has no
@@ -868,6 +879,7 @@ async function verifyRef(workspaceRoot: string, ref: string): Promise<void> {
       (isShallow
         ? ' This clone is shallow: fetch the history the base needs (`git fetch --unshallow`, or `fetch-depth: 0` on actions/checkout).'
         : ''),
+    'VX_E_AFFECTED_BASE',
   )
 }
 

package/src/workspace/config-schema.ts

@@ -56,9 +56,18 @@ const WORKSPACE_FIELDS = new Set([
   'affectedBase',
   'cacheScope',
   'rules',
+  'schedule',
   'plugins',
 ])
 
+type Schedule = NonNullable<WorkspaceConfig['schedule']>
+const SCHEDULES = {
+  'most-work': true,
+  'critical-path': true,
+  'direct-dependents': true,
+  'ready-order': true,
+} satisfies Record<Schedule, true>
+
 const RULE_FIELDS = new Set(['exclusiveOutputs', 'upfrontKeys'])
 
 function validateRules(rules: unknown, configPath: string): void {
@@ -127,6 +136,11 @@ function validateRetention(retention: unknown, configPath: string): void {
   }
 }
 
+/** A `plugins` entry that stands for no plugin: `undefined`, `null` or `false`. */
+export function isSkippedPlugin(p: unknown): p is undefined | null | false {
+  return p === undefined || p === null || p === false
+}
+
 export function validateWorkspace(config: WorkspaceConfig, configPath: string): void {
   // No JSON-data rule here, unlike `validateProjectConfig`: `plugins` holds
   // objects of functions by design, the file is evaluated in-process on
@@ -184,13 +198,23 @@ export function validateWorkspace(config: WorkspaceConfig, configPath: string):
     throw new UserError(`${configPath}: \`cacheScope\` ${CACHE_SCOPE_RULE}`)
   }
   if (config.rules !== undefined) validateRules(config.rules, configPath)
+  if (config.schedule !== undefined && !Object.hasOwn(SCHEDULES, config.schedule)) {
+    throw new UserError(
+      `${configPath}: \`schedule\` must be one of ${Object.keys(SCHEDULES)
+        .map((k) => `'${k}'`)
+        .join(', ')}`,
+    )
+  }
   if (config.plugins !== undefined) {
     if (!Array.isArray(config.plugins)) {
       throw new UserError(`${configPath}: \`plugins\` must be an array of plugin objects`)
     }
     const verbOwners = new Map<string, string>()
     const fileClaimants = new Map<string, { name: string; at: number }>()
-    for (const [i, p] of config.plugins.entries()) {
+    for (const [i, p] of (config.plugins as readonly unknown[]).entries()) {
+      // A factory that declines returns nothing, and `cond && plugin()` is
+      // false: both are skipped, as Vite skips them.
+      if (isSkippedPlugin(p)) continue
       if (p === null || typeof p !== 'object') {
         // Nx's nx.json lists plugins by module name (`'@nx/vite/plugin'`);
         // a vx plugin is the value its package's function returns.
@@ -644,6 +668,10 @@ export function validateProjectConfig(config: ProjectConfig, configPath: string)
         )
       }
       assertKnownFields(cache, CACHE_FIELDS, `${where}.cache`)
+      const rewritten = (cache as { rewrittenInputs?: unknown }).rewrittenInputs
+      if (rewritten !== undefined && rewritten !== 'withhold' && rewritten !== 'compare') {
+        throw new UserError(`${where}.cache.rewrittenInputs must be 'withhold' or 'compare'`)
+      }
       const inputs = (cache as { inputs?: unknown }).inputs
       const outputs = (cache as { outputs?: unknown }).outputs
       // A present field of the wrong shape (`outputs: 'dist'`) was told it
@@ -880,7 +908,7 @@ const EXEC_FIELDS = new Set([
 ])
 const PERSISTENT_FIELDS = new Set(['readyWhen'])
 const ENV_FIELDS = new Set(['passThrough', 'define', 'secret'])
-const CACHE_FIELDS = new Set(['inputs', 'outputs'])
+const CACHE_FIELDS = new Set(['inputs', 'outputs', 'rewrittenInputs'])
 const CACHE_INPUT_FIELDS = new Set([
   'files',
   'workspaceFiles',

package/src/workspace/lockfile.ts

@@ -36,6 +36,8 @@ export interface LockfileEntry {
 export interface Lockfile {
   version: number
   projects: Record<string, LockfileEntry>
+  /** Written by `writeLockfile` from the bytes; never read off the object. */
+  validated?: string
 }
 
 export function lockfilePath(root: string): string {
@@ -100,12 +102,33 @@ export async function readLockfile(root: string): Promise<Lockfile | null> {
     }
   }
   lockDigests.set(parsed, xxh3(text).toString(16))
+  const stamped = VALIDATED_LINE.exec(text)
+  if (stamped !== null && stamped[1] === validatedDigest(text.slice(0, stamped.index) + '\n}')) {
+    selfValidated.add(parsed)
+  }
   return parsed as Lockfile
 }
 
 /** The digest of the bytes each lock `readLockfile` returned was parsed from. */
 const lockDigests = new WeakMap<object, string>()
 
+/**
+ * The lock's own record that this vx validated its entries: `vx lock`
+ * evaluates and validates every config, then writes a digest of the bytes
+ * it wrote, under vx's version (validation's rules are vx's alone, so Bun's
+ * is left out and does not churn a committed lock), as the last field. A lock
+ * whose digest matches is validated already, and a cold `--frozen` run
+ * skips the ~30 ms of validating 1,090 entries before its first task. An
+ * edit, a merge, or another vx version leaves it unmatched, and the
+ * entries are validated as before.
+ */
+const VALIDATED_LINE = /,\n {2}"validated": "([0-9a-f]+)"\n\}\n?$/
+const selfValidated = new WeakSet<object>()
+
+function validatedDigest(body: string): string {
+  return xxh3(`vx-lock-valid-v${CONFIG_EVAL_VERSION}\0${VERSION}\0${body}`).toString(16)
+}
+
 export async function writeLockfile(root: string, lock: Lockfile): Promise<void> {
   // Written beside its name and renamed over it: `Bun.write` truncates in
   // place, so a `--frozen` run, or `vx watch --frozen` woken by the write
@@ -114,7 +137,8 @@ export async function writeLockfile(root: string, lock: Lockfile): Promise<void>
   const file = lockfilePath(root)
   const tmp = `${file}.tmp-${process.pid}-${Math.random().toString(36).slice(2)}`
   try {
-    await Bun.write(tmp, `${JSON.stringify(lock, null, 2)}\n`)
+    const body = JSON.stringify({ version: lock.version, projects: lock.projects }, null, 2)
+    await Bun.write(tmp, `${body.slice(0, -2)},\n  "validated": "${validatedDigest(body)}"\n}\n`)
     await rename(tmp, file)
   } catch (err) {
     // Best effort: where the write was refused the temp cannot be named
@@ -187,7 +211,10 @@ export async function frozenProjectConfigs(
   // asked for 1,090 per-project rows in one `IN` query, ~10 ms of its
   // config load, where the eval-cache path it replaces is cheaper (X-181).
   // A scoped run still validates, and remembers, only what it loads.
-  if (prefix !== undefined && store !== undefined && store.getConfigEval(prefix) !== null) {
+  if (
+    selfValidated.has(lock) ||
+    (prefix !== undefined && store !== undefined && store.getConfigEval(prefix) !== null)
+  ) {
     return entries.map((e) => e.config)
   }
   const keys = prefix === undefined ? undefined : metas.map((m) => `${prefix}\0${m.name}`)

package/src/workspace/migration.ts

@@ -377,6 +377,18 @@ export async function applyMigration(args: ApplyMigrationArgs): Promise<number>
   // One reason, its tasks: on a Turbo template the same two-line cache TODO
   // printed five times and the persistent one eight (the first-five-minutes
   // walk, 2026-09-28), and the list read as noise.
+  // A file .gitignore drops is lost at the first commit, unnoticed: vueuse
+  // ignores `packages/**/*.mjs`, so `--mjs` wrote configs git never saw.
+  const ignored = gitIgnored(
+    root,
+    files.map((f) => f.relPath),
+  )
+  const ignoredNote =
+    ignored.length === 0
+      ? []
+      : [
+          `.gitignore drops ${ignored.length} file${ignored.length === 1 ? '' : 's'} this ${dry ? 'would write' : 'wrote'} (${ignored.slice(0, TODO_IDS_SHOWN).join(', ')}${ignored.length > TODO_IDS_SHOWN ? ', …' : ''}): add ${[...new Set(ignored.map((f) => `!${path.posix.basename(f)}`))].join(' and ')} to .gitignore, or commit them with git add -f`,
+        ]
   const todos = new Map<string, string[]>()
   let todoCount = 0
   let clean = 0
@@ -423,7 +435,7 @@ export async function applyMigration(args: ApplyMigrationArgs): Promise<number>
       args.unmapped === true
         ? `${verb}: no package.json scripts became tasks.`
         : `${verb}: no package.json scripts to turn into tasks.`,
-      ...[...noMembers, ...(args.notes ?? [])].map((n) => `note: ${n}`),
+      ...[...noMembers, ...(args.notes ?? []), ...ignoredNote].map((n) => `note: ${n}`),
       hasWorkspaceFile
         ? `${workspaceName} already exists.`
         : dry
@@ -438,7 +450,7 @@ export async function applyMigration(args: ApplyMigrationArgs): Promise<number>
     )
   } else {
     report.push(`${verb}: ${source} → ${configName}`)
-    for (const n of args.notes ?? []) report.push(`note: ${n}`)
+    for (const n of [...(args.notes ?? []), ...ignoredNote]) report.push(`note: ${n}`)
     for (const n of plan.headerNotes) report.push(`note: ${n}`)
     report.push(
       '',
@@ -470,7 +482,10 @@ export async function applyMigration(args: ApplyMigrationArgs): Promise<number>
   // A run of tasks none of which caches is never a hit, and a first try
   // that runs twice to see the cache work saw it run twice.
   if (!cached && [...todos.keys()].some(isCacheTodo)) {
-    report.push('', 'no task caches yet: add the cache block a TODO shows, and a second run hits')
+    report.push(
+      '',
+      'no task caches yet: uncomment the cache line in each TODO task with its real globs, and a second run hits',
+    )
   }
   const installed = existsSync(path.join(root, 'node_modules', '@vzn', 'vx', 'package.json'))
   // The line is the next thing to type, so it names what that run would
@@ -495,6 +510,7 @@ export async function applyMigration(args: ApplyMigrationArgs): Promise<number>
           ...(empty && unreached.length > 0 ? [unreachedHint(unreached, root)] : []),
           ...(empty ? noMembers : []),
           ...(args.notes ?? []),
+          ...ignoredNote,
           ...plan.headerNotes,
           ...plan.notes,
         ],
@@ -508,6 +524,28 @@ export async function applyMigration(args: ApplyMigrationArgs): Promise<number>
   return 0
 }
 
+/** The paths (root-relative) git's ignore rules drop; none outside a work tree. */
+function gitIgnored(root: string, relPaths: readonly string[]): string[] {
+  if (relPaths.length === 0) return []
+  try {
+    const r = Bun.spawnSync({
+      cmd: [executablePath('git'), 'check-ignore', '--stdin', '-z'],
+      cwd: root,
+      stdin: Buffer.from(relPaths.map((p) => `${p}\0`).join('')),
+      stdout: 'pipe',
+      stderr: 'ignore',
+    })
+    // 0: some ignored; 1: none; anything else (no work tree): nothing to say.
+    if (r.exitCode !== 0) return []
+    return r.stdout
+      .toString()
+      .split('\0')
+      .filter((p) => p !== '')
+  } catch {
+    return []
+  }
+}
+
 function inGitWorkTree(root: string): boolean {
   try {
     return (
@@ -660,7 +698,16 @@ function renderConfigFile(p: GeneratedProject, format: MigrationFormat): string
         : IDENT.test(t.name)
           ? t.name
           : quoteTsLiteral(t.name)
-    lines.push(`    ${key}: ${renderValue(t.task, '    ')},`)
+    const rendered = renderValue(t.task, '    ')
+    // The suggested block sits in the task, commented: deleting `// `
+    // after setting the real globs caches it, no copying from the TODO.
+    const block =
+      t.task['cache'] === undefined
+        ? t.todos.find(isCacheTodo)?.match(/^cache: add `(.+?)`/)?.[1]
+        : undefined
+    lines.push(
+      `    ${key}: ${block === undefined ? rendered : rendered.replace('{\n', `{\n      // ${block},\n`)},`,
+    )
   }
   lines.push('  },', format === 'ts' ? '} satisfies ProjectConfig' : '}', '')
   return lines.join('\n')

package/src/workspace/project-loader.ts

@@ -2,7 +2,7 @@ import { existsSync, realpathSync, statSync } from 'node:fs'
 import path from 'node:path'
 import type { ProjectConfig, WorkspaceConfig } from '../config.js'
 import { UserError, xxh3hex } from '../util/index.js'
-import { validateProjectConfig, validateWorkspace } from './config-schema.js'
+import { isSkippedPlugin, validateProjectConfig, validateWorkspace } from './config-schema.js'
 import {
   beginEvalRound,
   builtinsChangedBy,
@@ -1163,6 +1163,8 @@ export async function loadWorkspaceConfig(root: string): Promise<WorkspaceConfig
     // config at all (D-6).
     assertDefaultObject(mod, 'Workspace', configPath)
     validateWorkspace(mod, configPath)
+    if (mod.plugins?.some(isSkippedPlugin) === true)
+      mod = { ...mod, plugins: mod.plugins.filter((p) => !isSkippedPlugin(p)) }
     // Set by a load that succeeded: a failed one may have left nothing in
     // the registry, and its fix must not be refused.
     if (since === undefined) workspaceLoadedAt.set(configPath, startedAt)