@vzn/vx 0.0.634 → 0.0.636

package/src/orchestrator/run-failures.ts

@@ -9,6 +9,7 @@ import { mkdirSync, readdirSync, readFileSync, renameSync, rmSync, writeFileSync
 import path from 'node:path'
 import { isGroupTask, type TaskOutcome } from '../graph/index.js'
 import { decodeOutputLog } from './output-log.js'
+import { PASS_STATUSES } from './history.js'
 import { splitTaskId } from '../util/index.js'
 import { fileLocations, fileMemo, type OutputLocation } from './path-links.js'
 
@@ -23,6 +24,10 @@ export interface TaskFailure {
   /** Plain text, bounded, secrets masked; '' when the run kept none. */
   output: string
   locations: OutputLocation[]
+  /** The `exec.sandbox.allow` entries that would have granted its denials. */
+  sandboxFix?: NonNullable<TaskOutcome['sandboxFix']>
+  /** The first later run where this task passed (ran or hit): the failure is history. */
+  fixedIn?: string
 }
 
 export interface RunFailures {
@@ -56,6 +61,7 @@ function failuresOf(outcomes: readonly TaskOutcome[]): StoredFailure[] {
       ...(o.timedOut === true ? { timedOut: true as const } : {}),
       output,
       locations: fileLocations(output, o.node.projectDir, isFile),
+      ...(o.sandboxFix !== undefined ? { sandboxFix: o.sandboxFix } : {}),
     })
   }
   return out
@@ -110,10 +116,19 @@ export function runFailures(cacheDir: string, db: Database, runId?: string): Run
   }
   const rows = db
     .query(
-      `SELECT project, task, exit_code AS exitCode, timed_out AS timedOut FROM runs
-       WHERE run_id = ? AND status = 'failed' ORDER BY id`,
+      `SELECT r.project, r.task, r.exit_code AS exitCode, r.timed_out AS timedOut,
+         (SELECT s.run_id FROM runs s WHERE s.project = r.project AND s.task = r.task
+            AND s.id > r.id AND s.status IN ${PASS_STATUSES}
+          ORDER BY s.id LIMIT 1) AS fixedIn
+       FROM runs r WHERE r.run_id = ? AND r.status = 'failed' ORDER BY r.id`,
     )
-    .all(id) as { project: string; task: string; exitCode: number; timedOut: number | null }[]
+    .all(id) as {
+    project: string
+    task: string
+    exitCode: number
+    timedOut: number | null
+    fixedIn: string | null
+  }[]
   return {
     runId: id,
     tasks: rows.map((r) => {
@@ -125,6 +140,8 @@ export function runFailures(cacheDir: string, db: Database, runId?: string): Run
         ...(r.timedOut === 1 ? { timedOut: true as const } : {}),
         output: k?.output ?? '',
         locations: k?.locations ?? [],
+        ...(k?.sandboxFix !== undefined ? { sandboxFix: k.sandboxFix } : {}),
+        ...(r.fixedIn !== null ? { fixedIn: r.fixedIn } : {}),
       }
     }),
   }

package/src/orchestrator/run.ts

@@ -3,7 +3,12 @@
 // so the layers can be swapped without touching the others.
 
 import type { ProjectEntry } from '../workspace/index.js'
-import { loadWorkspace, unreachedHint, unreachedPackages } from '../workspace/index.js'
+import {
+  inputStabilityEnv,
+  loadWorkspace,
+  unreachedHint,
+  unreachedPackages,
+} from '../workspace/index.js'
 import { realpathSync } from 'node:fs'
 import path from 'node:path'
 import {
@@ -610,6 +615,13 @@ async function runOnBus(
   // ignored (a bad timeout must not silently disable a task's own limit).
   const taskTimeoutDefault =
     options.timeout ?? readTaskTimeoutEnv() ?? workspaceConfig?.timeout ?? undefined
+  // Read once, before any task: a bad value is refused here, not mid-run.
+  const inputStability = {
+    run: inputStabilityEnv(),
+    ...(workspaceConfig?.inputStability !== undefined
+      ? { workspace: workspaceConfig.inputStability }
+      : {}),
+  }
 
   // Run-scoped registries of live subprocesses:
   //   - `liveChildren`: in-flight children. The runner adds/removes
@@ -1056,6 +1068,7 @@ async function runOnBus(
       }
       if (options.retries !== undefined) a.retries = options.retries
       if (taskTimeoutDefault !== undefined) a.timeout = taskTimeoutDefault
+      a.inputStability = inputStability
       if (download.modeOf.get(node.id) === 'deferred') a.download = 'deferred'
       if (placements.remoteOnlyNoop.has(node.id)) a.remoteOnlyNoop = true
       if (placements.remoteOnly.has(node.id)) a.remoteOnly = true
@@ -1089,6 +1102,14 @@ async function runOnBus(
     })
 
     mark('classify + probe')
+    // A run whose every task is a confirmed local hit dispatches only
+    // restores, which no weight orders: the `schedule` stage is not asked.
+    const priorities = [...nodes.values()].every(
+      (n) => n.config.exec?.command === undefined || shortCircuit.restoreTier.has(n.id),
+    )
+      ? new Map<string, number>()
+      : await prepared.priorities()
+    mark('schedule')
     // Judged as each task finishes, against the history BEFORE this run's
     // rows land, so the row that prints next carries the verdict: nothing
     // prints below the footer. A hit or a skip asks nothing; a green miss
@@ -1172,7 +1193,7 @@ async function runOnBus(
         : {}),
       // A `schedule` plugin's weights; the scheduler keeps its structural
       // baseline as the tie-break. Empty map → baseline only.
-      ...(prepared.priorities.size > 0 ? { priorities: prepared.priorities } : {}),
+      ...(priorities.size > 0 ? { priorities } : {}),
       // The baseline under them; `most-work` when the workspace names none.
       ...(prepared.workspaceConfig?.schedule !== undefined
         ? { strategy: prepared.workspaceConfig.schedule }
@@ -1718,6 +1739,8 @@ export async function planRun(options: RunOptions): Promise<RunPlan> {
     if (prepared.empty === 'none-affected')
       return { tasks: [], noneAffected: noneAffected(prepared, options) }
     if (prepared.empty !== null) return { tasks: [] }
+    // The plan orders nothing, but it refuses what the run would refuse.
+    await prepared.priorities()
     // Its own mark: a dry run's plan (every task's hash, the cache lookups,
     // the history p50s) was booked under `close`, the next mark, and read
     // as 105 ms of closing a cache at 1,000 projects (item 601).

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` (`inputStability.strategy: 'mutable'`) 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/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

@@ -10,6 +10,7 @@ import {
   PLUGIN_FUNCTION_HOOKS,
   PLUGIN_HOOKS,
   PLUGIN_PACKAGE,
+  type InputStability,
   type Plugin,
   type ProjectConfig,
   type WorkspaceConfig,
@@ -43,9 +44,65 @@ export function isCacheScope(v: unknown): v is string {
   return typeof v === 'string' && /^[\w.@/-]{1,128}$/.test(v)
 }
 
-/** Why `VX_CACHE_SCOPE` is refused, in `cacheScope`'s words. */
+/** Why a `VX_CACHE_SCOPE` or `--cache-scope` value is refused, in `cacheScope`'s words. */
+export function cacheScopeError(source = 'VX_CACHE_SCOPE'): string {
+  return `${source} ${CACHE_SCOPE_RULE}`
+}
+
+/** Why `VX_CACHE_SCOPE` is refused, as the run's error. */
 export function cacheScopeEnvError(): UserError {
-  return new UserError(`VX_CACHE_SCOPE ${CACHE_SCOPE_RULE}`)
+  return new UserError(cacheScopeError())
+}
+
+const STRATEGIES = ['immutable', 'mutable', 'unchecked'] as const
+const SEVERITIES = ['warn', 'error'] as const
+const INPUT_STABILITY_FIELDS = new Set(['strategy', 'severity'])
+const oneOf = (values: readonly string[]): string =>
+  `must be ${values
+    .map((v) => `'${v}'`)
+    .join(', ')
+    .replace(/, ([^,]*)$/, ' or $1')}`
+
+function envOneOf<T extends string>(
+  name: string,
+  raw: string | undefined,
+  values: readonly T[],
+): T | undefined {
+  if (raw === undefined || raw === '') return undefined
+  if (!(values as readonly string[]).includes(raw)) throw new UserError(`${name} ${oneOf(values)}`)
+  return raw as T
+}
+
+function validateInputStability(stability: unknown, at: string): void {
+  if (typeof stability !== 'object' || stability === null || Array.isArray(stability)) {
+    throw new UserError(`${at} must be an object — \`inputStability: { strategy: 'mutable' }\``)
+  }
+  assertKnownFields(stability, INPUT_STABILITY_FIELDS, at)
+  const { strategy, severity } = stability as Record<string, unknown>
+  if (strategy !== undefined && !STRATEGIES.includes(strategy as never)) {
+    throw new UserError(`${at}.strategy ${oneOf(STRATEGIES)}`)
+  }
+  if (severity !== undefined && !SEVERITIES.includes(severity as never)) {
+    throw new UserError(`${at}.severity ${oneOf(SEVERITIES)}`)
+  }
+}
+
+/**
+ * `VX_INPUT_STABILITY` and `VX_INPUT_STABILITY_SEVERITY`, which override
+ * every task's `cache.inputStability` for the run: each undefined when
+ * unset or empty, refused when it names no value.
+ */
+export function inputStabilityEnv(): InputStability {
+  const strategy = envOneOf('VX_INPUT_STABILITY', process.env['VX_INPUT_STABILITY'], STRATEGIES)
+  const severity = envOneOf(
+    'VX_INPUT_STABILITY_SEVERITY',
+    process.env['VX_INPUT_STABILITY_SEVERITY'],
+    SEVERITIES,
+  )
+  return {
+    ...(strategy !== undefined ? { strategy } : {}),
+    ...(severity !== undefined ? { severity } : {}),
+  }
 }
 
 const WORKSPACE_FIELDS = new Set([
@@ -57,6 +114,7 @@ const WORKSPACE_FIELDS = new Set([
   'cacheScope',
   'rules',
   'schedule',
+  'inputStability',
   'plugins',
 ])
 
@@ -136,6 +194,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
@@ -193,6 +256,9 @@ 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.inputStability !== undefined) {
+    validateInputStability(config.inputStability, `${configPath}: \`inputStability\``)
+  }
   if (config.schedule !== undefined && !Object.hasOwn(SCHEDULES, config.schedule)) {
     throw new UserError(
       `${configPath}: \`schedule\` must be one of ${Object.keys(SCHEDULES)
@@ -206,7 +272,10 @@ export function validateWorkspace(config: WorkspaceConfig, configPath: string):
     }
     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.
@@ -660,6 +729,9 @@ export function validateProjectConfig(config: ProjectConfig, configPath: string)
         )
       }
       assertKnownFields(cache, CACHE_FIELDS, `${where}.cache`)
+      const stability = (cache as { inputStability?: unknown }).inputStability
+      if (stability !== undefined)
+        validateInputStability(stability, `${where}.cache.inputStability`)
       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
@@ -896,7 +968,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', 'inputStability'])
 const CACHE_INPUT_FIELDS = new Set([
   'files',
   'workspaceFiles',
@@ -939,6 +1011,15 @@ export const REMOVED_FIELDS: ReadonlyMap<
       },
     },
   ],
+  [
+    CACHE_FIELDS,
+    {
+      rewrittenInputs: {
+        removedIn: '0.0.636',
+        use: "`inputStability: { strategy: 'immutable' | 'mutable' }` ('withhold', 'compare')",
+      },
+    },
+  ],
 ])
 
 /**

package/src/workspace/index.ts

@@ -37,6 +37,8 @@ export {
 } from './project-loader.js'
 export {
   cacheScopeEnvError,
+  cacheScopeError,
+  inputStabilityEnv,
   isCacheScope,
   validateProjectConfig,
   validateWorkspace,

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)