@vzn/vx 0.0.636 → 0.0.637

package/src/cli/why.ts

@@ -1,17 +1,16 @@
 // `vx why [pkg#task | task]` — answer "why did this task re-run?" from the
-// terminal. The same persisted data the MCP `whyDidThisRerun` tool reads:
-// the runs table names the
-// run-over-run hash change, and `entry_inputs` (the input-fingerprint moat)
-// names the exact cache-key components that differ. Read-only over cache.db —
-// no config evaluation, no re-hash.
+// terminal. The runs table names the run-over-run hash change, and
+// `entry_inputs` (the input-fingerprint moat) names the exact cache-key
+// components that differ. Read-only over cache.db plus a stat of each
+// moved input file — no config evaluation, no re-hash.
 
-import path from 'node:path'
 import { Cache } from '../cache/index.js'
 import { flagHint, formatValue, seeHelp } from './help.js'
 import { splitTaskId } from '../graph/index.js'
 import {
   cacheKeyDiff,
   explainCacheKeyQuery as explainCacheKey,
+  inputWriters,
   latestRunId,
   rootCauses,
   whyDidThisRerunQuery as whyDidThisRerun,
@@ -20,7 +19,7 @@ import {
 import { MASKED, nearMatches, printable, UserError } from '../util/index.js'
 import { findWorkspaceRoot } from '../workspace/index.js'
 import { findCwdProject } from './select.js'
-import { cliCacheDir, parseCacheDirFlag } from './workspace-config.js'
+import { cliCacheDir, discoverCliProjects, parseCacheDirFlag } from './workspace-config.js'
 
 interface WhyArgs {
   target?: string
@@ -43,9 +42,6 @@ export const WHAT_TO_DO: Readonly<Record<string, string>> = {
   'ws-runtime':
     'the workspace command printed something else; drop timestamps and paths from its output',
   forward: 'the arguments after -- differ; the same arguments share one entry',
-  package: "the project's package.json changed (a dependency, version or script)",
-  workspace:
-    'a lockfile or root manifest changed, which re-keys every task; a lockfile plugin keys each project on its own dependencies',
   config:
     "the task's evaluated config changed (its vx.config or a file it imports); `vx show <that task>` prints it as it is now",
   upstream: "a dependency's key moved; `vx why <that task>` says why",
@@ -174,14 +170,14 @@ async function resolveTarget(
 
 const fmtWhen = (ms: number): string => new Date(ms).toISOString()
 
-/** `//#task`, Turbo's root package, as the root project's id: its package.json name (D-39). */
+/** `//#task`, Turbo's root package, as the root project's id: the name discovery gives it (D-39). */
 async function rootSpelled(root: string, target: string): Promise<string> {
   if (!target.startsWith('//#')) return target
-  const name = await Bun.file(path.join(root, 'package.json'))
-    .json()
-    .then((j: { name?: unknown }) => j.name)
-    .catch(() => undefined)
-  return typeof name === 'string' && name !== '' ? `${name}#${target.slice(3)}` : target
+  const name = await discoverCliProjects(root).then(
+    (metas) => metas.find((m) => m.dir === root)?.name,
+    () => undefined,
+  )
+  return name === undefined ? target : `${name}#${target.slice(3)}`
 }
 
 /** ` · up-to-date` or ` · restored` on a hit, as the run's summary said it; nothing otherwise. */
@@ -247,9 +243,10 @@ export async function whyCmd(args: readonly string[]): Promise<number> {
     // each moved dependency in this run down to the tasks whose own
     // inputs moved, so one `vx why` names the file, not the next task.
     const roots = rootCauses(db, runId, taskId, diff.entries)
+    const writers = inputWriters(db, root, taskId, diff.entries, roots)
 
     if (parsed.format === 'json') {
-      process.stdout.write(`${JSON.stringify({ taskId, runId, why, diff, roots })}\n`)
+      process.stdout.write(`${JSON.stringify({ taskId, runId, why, diff, roots, writers })}\n`)
       return 0
     }
 
@@ -320,6 +317,12 @@ export async function whyCmd(args: readonly string[]): Promise<number> {
         }
         if (roots.length > ROOTS_SHOWN) lines.push(`    and ${roots.length - ROOTS_SHOWN} more`)
       }
+      if (writers.length > 0) {
+        lines.push('', '  changed during a run:')
+        for (const w of writers) {
+          lines.push(`    ${printable(w.file)}  while ${w.writers.join(', ')} ran`)
+        }
+      }
       const rootKinds = roots.flatMap((r) => r.entries.map((e) => e.kind))
       const kinds = [...new Set([...diff.entries.map((e) => e.kind), ...rootKinds])].filter(
         (k) => k in WHAT_TO_DO && !(k === 'upstream' && roots.length > 0),
@@ -341,6 +344,11 @@ export async function whyCmd(args: readonly string[]): Promise<number> {
                 : WHAT_TO_DO[k]
           lines.push(`    ${k.padEnd(kindW)}  ${todo}`)
         }
+        if (writers.length > 0) {
+          // A task re-writing a file a key reads moves that key every run:
+          // the miss is right, and only moving the write ends it.
+          lines.push(`    ${'written'.padEnd(kindW)}  ${WRITTEN_TODO}`)
+        }
       }
     } else if (why.hashChanged === true) {
       lines.push(`  detail     ${diff.note}`)
@@ -353,3 +361,6 @@ export async function whyCmd(args: readonly string[]): Promise<number> {
 }
 
 const ROOTS_SHOWN = 5
+
+const WRITTEN_TODO =
+  'a task that writes a file a key reads re-keys it every run; give that write its own task with the file as an output, or keep the file out of cache.inputs.files'

package/src/cli/workspace-config.ts

@@ -8,17 +8,18 @@ import { existsSync } from 'node:fs'
 import path from 'node:path'
 import type { WorkspaceConfig } from '../config.js'
 import { UserError } from '../util/index.js'
-import { Cache } from '../cache/index.js'
-import { discoverProjects, loadProjects, loadWorkspacePlugins } from '../orchestrator/index.js'
+import {
+  discoverProjects,
+  loadProjects,
+  loadWorkspacePlugins,
+  lockOfDiscovery,
+  lockReader,
+} from '../orchestrator/index.js'
 import type { VxPlugin } from '../orchestrator/index.js'
 import {
   buildPackageGraph,
-  computeWorkspaceFingerprint,
-  FROZEN_WITHOUT_LOCK,
-  type Workspace,
   type ProjectEntry,
   type ProjectMeta,
-  readLockfile,
   resolveCacheDir,
   resolveStoreRoot,
 } from '../workspace/index.js'
@@ -46,17 +47,18 @@ export async function loadCliWorkspace(workspaceRoot: string): Promise<CliWorksp
 }
 
 /**
- * The workspace's projects as a run discovers them: core's, then the
- * plugin `discover` stage, with the cache dir the run uses.
+ * The workspace's projects as a run discovers them: the lock's, then the
+ * plugin `discover` stage, with the cache dir the run uses. No lock is
+ * `NO_LOCK`.
  */
-export async function discoverCliProjects(workspace: Workspace): Promise<ProjectMeta[]> {
-  const { plugins, cacheDir } = await loadCliWorkspace(workspace.root)
-  return await discoverProjects(workspace, plugins, cacheDir, warnToStderr)
+export async function discoverCliProjects(root: string): Promise<ProjectMeta[]> {
+  const { plugins, cacheDir } = await loadCliWorkspace(root)
+  return await discoverProjects(root, lockReader(root), plugins, cacheDir, warnToStderr)
 }
 
 /**
  * `--cache-dir <path>` / `--cache-dir=<path>` for a verb that reads the
- * cache a run wrote — `why`, `last`, `info`, `cache prune`. Same rules as
+ * cache a run wrote — `why`, `last`, `info`, `cache clean`. Same rules as
  * `vx run`'s: a value is required, and the space form refuses a value
  * that looks like a flag (an unquoted empty shell variable would otherwise
  * swallow the next flag as the path). Returns null when `args[i]` is not
@@ -104,16 +106,8 @@ export async function cliCacheDir(
 
 /** The run flags a verb's staged load must honour to see what the run sees. */
 export interface CliLoadOptions {
-  /** `--cache-dir`: where the cached evaluations live. */
+  /** `--cache-dir`: the cache dir a plugin's `project` stage is told. */
   cacheDir?: string
-  /** `--frozen`: configs come from `vx-lock.json`, not evaluation. */
-  frozen?: boolean
-  /**
-   * A reading verb (`vx show`) makes nothing on disk (item 900): with no
-   * cache directory yet, it evaluates without the cache rather than
-   * create one.
-   */
-  noCreate?: boolean
   /**
    * Load what each seed's package closure reaches too, as a run does: a
    * config-less package a configured one depends on gets the default
@@ -124,10 +118,9 @@ export interface CliLoadOptions {
 
 /**
  * The run path's project-config load (`loadProjects`) for a verb that only
- * reads: the plugin `project` stage applies, and the local cache opens only
- * to serve cached evaluations — a pure config costs a stat, not an
- * evaluation. `scope` is every project or a list of names; their closure
- * only with `closure`, no lock (a verb reads live, as a default run does).
+ * reads: configs from the lock, the plugin `project` stage applied. `scope`
+ * is every project or a list of names; their closure only with `closure`.
+ * No lock is `NO_LOCK`, whatever the scope: only `vx lock` evaluates.
  */
 export async function loadCliProjects(
   workspaceRoot: string,
@@ -137,48 +130,18 @@ export async function loadCliProjects(
 ): Promise<Map<string, ProjectEntry>> {
   const ws = await loadCliWorkspace(workspaceRoot)
   const { plugins } = ws
-  // The cached evaluations live where the run's do: a verb given
-  // `--cache-dir` must not open (and create) the workspace's default one.
   const cacheDir = opts.cacheDir ?? ws.cacheDir
-  // A frozen run reads its configs from the lock; what it SELECTS must be
-  // decided from the same configs, or an env-dependent `workspaceFiles`
-  // glob could select live what the run then treats otherwise.
-  const lock = opts.frozen === true ? await readLockfile(workspaceRoot) : null
-  if (opts.frozen === true && lock === null) throw new UserError(FROZEN_WITHOUT_LOCK)
-  const cache =
-    opts.noCreate === true && !existsSync(cacheDir)
-      ? null
-      : new Cache(
-          cacheDir,
-          { read: true, write: true },
-          workspaceRoot,
-          undefined,
-          'open',
-          opts.cacheDir === undefined ? await ws.storeRoot : null,
-        )
-  try {
-    const loaded = await loadProjects({
-      workspaceRoot,
-      cacheDir,
-      plugins,
-      projectMetas: metas,
-      seeds: scope,
-      ...(opts.closure === true
-        ? { closure: true as const, packageGraph: buildPackageGraph([...metas]) }
-        : { closure: false as const }),
-      lock: lock === null ? null : async () => lock,
-      evalCache:
-        cache === null
-          ? undefined
-          : {
-              store: cache,
-              workspaceRoot,
-              workspaceFingerprint: await computeWorkspaceFingerprint(workspaceRoot),
-            },
-      warn: warnToStderr,
-    })
-    return loaded.projects
-  } finally {
-    cache?.close()
-  }
+  const loaded = await loadProjects({
+    workspaceRoot,
+    cacheDir,
+    plugins,
+    projectMetas: metas,
+    seeds: scope,
+    ...(opts.closure === true
+      ? { closure: true as const, packageGraph: buildPackageGraph([...metas]) }
+      : { closure: false as const }),
+    configs: lockOfDiscovery(metas) ?? lockReader(workspaceRoot),
+    warn: warnToStderr,
+  })
+  return loaded.projects
 }

package/src/config.ts

@@ -1,85 +1,140 @@
 // Public schema for vx project and workspace configuration.
 
+/**
+ * A duration with its unit: `'500ms'`, `'30s'`, `'5m'`, `'2h'`, `'1d'`. A
+ * bare number is refused: a unit in the value keeps the name free of one.
+ */
+export type Duration = `${number}${'ms' | 's' | 'm' | 'h' | 'd'}`
+
+/**
+ * The workspace: settings in groups (`run`, `cache`, `lock`, `watch`) and the
+ * plugins. Each setting's environment variable and flag derive from its
+ * path (`run.concurrency` → `VX_RUN_CONCURRENCY`, `vx run --concurrency`); a flag beats
+ * the variable, which beats this file. `docs/schema.md` lists them all.
+ * Nothing here is folded into a cache key.
+ */
 export interface WorkspaceConfig {
-  /** Maximum concurrent tasks. Defaults to the number of CPUs. */
-  concurrency?: number
-  /**
-   * Cache directory, relative to the workspace root. Named, it holds the whole
-   * cache and shares nothing; unset, the workspace keeps its index in
-   * `.vx/cache` and its entries in the user's shared store.
-   */
-  cacheDir?: string
+  run?: RunSettings
+  cache?: CacheSettings
+  lock?: LockSettings
+  watch?: WatchSettings
   /**
-   * Default per-task timeout (ms) — the lowest-precedence fallback for a
-   * task that declares no `exec.timeout`. Precedence, highest first:
-   * per-task `exec.timeout` → `VX_TASK_TIMEOUT` env → this workspace
-   * default. Purely a runaway-process guard; never folded into a cache
-   * key (a timed-out task fails and is never cached). Omitted → no default.
+   * Plugins registered for this workspace, consulted in this order once
+   * per `vx run`: each fills any of the pipeline stages and capabilities
+   * below, and core's own executor and cache store sit at the tail of
+   * every list. See `docs/design/pipeline-2026-09.md`. An `undefined`,
+   * `null` or `false` entry is skipped, so a factory that declines
+   * (`github()` off Actions) or `cond && plugin()` needs no filter.
    */
-  timeout?: number
+  plugins?: readonly (Plugin | undefined | null | false)[]
+}
+
+/** `WorkspaceConfig.run`: how a run runs. */
+export interface RunSettings {
+  /** Tasks at once: a positive integer, or a share of the cores (`'50%'`). Omitted → the cores this process may use. */
+  concurrency?: number | `${number}%`
   /**
-   * Evict from the local cache at the end of every run, whatever its
-   * `--cache` policy (a remote hit is ingested under any), by the same policy `vx cache prune` takes as flags: entries not used
-   * for `olderThan` (`30d`, `12h`), then least-recently-used entries
-   * until the cache is under `maxSize` (`10G`, `500MB`). Either or both.
-   * Omitted → nothing is evicted unless you run `vx cache prune`. Never
-   * folded into a cache key.
+   * Which ready task starts first when there are more than workers, with no
+   * timings: `most-work` (the default) the one the most work waits on at
+   * any depth, `critical-path` the head of the longest chain of tasks,
+   * `direct-dependents` the one the most tasks wait on directly (Nx's
+   * rule), `ready-order` the one that became ready first (Turbo's). A
+   * `schedule` plugin's weights still come first; this breaks their ties.
    */
-  cacheRetention?: { olderThan?: string; maxSize?: string }
+  schedule?: 'most-work' | 'critical-path' | 'direct-dependents' | 'ready-order'
   /**
    * The git ref a bare `--affected` compares with (`origin/develop`).
    * `--affected=<base>` overrides it. Omitted → `origin/HEAD`, then the
    * first of `origin/main`, `origin/master`, `main`, `master` that is not
-   * HEAD, else `HEAD~1`. Never folded into a cache key.
+   * HEAD, else `HEAD~1`.
    */
   affectedBase?: string
   /**
-   * Where this run's remote cache writes land. `'trusted'` reads and
-   * writes the trusted keys, for the default branch's CI. `'read-only'`
-   * reads them and writes nothing; omitted, `vx run` off CI takes it, and
-   * on CI (or with `--cache` naming the remote) `'trusted'`. Any other
-   * name (`'pr-123'`) is an untrusted scope: reads try the scope's keys,
-   * then the trusted ones, and writes go to the scope's only, so a PR never
-   * writes what the default branch reads. A client-side convention, not a
-   * security boundary: only a cache server that scopes writes by token
-   * can refuse a run that ignores it. `VX_CACHE_SCOPE` beats it, and
-   * `vx run --cache-scope` beats both. Never
-   * folded into a cache key.
+   * A task's time limit, for tasks without their own `exec.timeout` (which
+   * beats every run-level source). A runaway-process guard: a timed-out
+   * task fails and is never cached. Omitted → no limit.
    */
-  cacheScope?: string
+  timeout?: Duration
+  /** Re-runs of a failed task, for tasks without their own `exec.retries`. Omitted → 0. */
+  retries?: number
   /**
-   * Which ready task starts first when there are more than workers, with no
-   * timings: `most-work` (the default) the one the most work waits on at
-   * any depth, `critical-path` the head of the longest chain of tasks,
-   * `direct-dependents` the one the most tasks wait on directly (Nx's
-   * rule), `ready-order` the one that became ready first (Turbo's). A
-   * `schedule` plugin's weights still come first; this breaks their ties.
+   * What a failed task takes down: `never` stops the run, `deps-ok` (the
+   * default) skips its dependents, `always` runs them too.
    */
-  schedule?: 'most-work' | 'critical-path' | 'direct-dependents' | 'ready-order'
+  continue?: 'never' | 'deps-ok' | 'always'
+  /** How long a task that ignores SIGTERM gets before SIGKILL. Omitted → `'2s'`. */
+  killGrace?: Duration
+  /** The bound on each plugin's end-of-run flush and teardown. Omitted → `'3s'`. */
+  teardownTimeout?: Duration
+  /** How long a persistent task may take to match `readyWhen` before vx says it waits. Omitted → `'10s'`. */
+  readyNotice?: Duration
   /**
-   * The `cache.inputStability` of every task that does not set its own
-   * field. `VX_INPUT_STABILITY` / `VX_INPUT_STABILITY_SEVERITY` override
-   * both for the run.
+   * Graph rules checked by `vx lock` and `vx lock --check`, never by a
+   * run. Each is on
+   * unless set to `false`; turning one off allows a shape vx handles
+   * correctly but more slowly.
    */
-  inputStability?: InputStability
+  rules?: WorkspaceRules
+}
+
+/** `WorkspaceConfig.cache`: where the cache lives and what a run does with it. */
+export interface CacheSettings {
   /**
-   * Graph rules a run checks before it schedules anything. Each is on unless
-   * set to `false`; turning one off allows a shape vx handles correctly but
-   * more slowly. Never folded into a cache key.
+   * Cache directory, relative to the workspace root. Named, it holds the whole
+   * cache and shares nothing; unset, the workspace keeps its index in
+   * `.vx/cache` and its entries in the user's shared store.
    */
-  rules?: WorkspaceRules
+  dir?: string
   /**
-   * Plugins registered for this workspace, consulted in this order once
-   * per `vx run`: each fills any of the pipeline stages and capabilities
-   * below, and core's own executor and cache store sit at the tail of
-   * every list. See `docs/design/pipeline-2026-09.md`. An `undefined`,
-   * `null` or `false` entry is skipped, so a factory that declines
-   * (`github()` off Actions) or `cond && plugin()` needs no filter.
+   * Evict from the local cache at the end of every run, whatever its
+   * policy (a remote hit is ingested under any), by the same policy
+   * `vx cache clean` takes as flags: entries not used for `olderThan`
+   * (`'30d'`, `'12h'`), then least-recently-used entries until the cache
+   * is under `maxSize` (`'10GB'`, `'500MB'`). Either or both. Omitted →
+   * nothing is evicted unless you run `vx cache clean`.
+   */
+  retention?: { olderThan?: Duration; maxSize?: string }
+  /**
+   * Which layers a run reads and writes (`'local:rw,remote:r'`; a layer it
+   * leaves out stays on); `--no-cache` and `--force` still apply on top.
+   * Omitted → every layer reads and writes. The local layer is always read
+   * first, then each remote in declared order.
+   */
+  policy?: string
+  /**
+   * Where this run's cache writes land. Omitted, a run reads and writes the
+   * default keys. A name (`'pr-123'`) reads the default key first, then the
+   * scope's, and writes only the scope's, so a PR never writes what the
+   * default branch reads. Whether a run writes at all is `policy`'s call.
+   * A client-side convention, not a security boundary: the boundary is a
+   * cache token the server limits.
+   */
+  scope?: string
+  /** Which remote hits land on disk: `all` (the default), only the requested tasks' (`toplevel`), or `none`. */
+  download?: 'all' | 'toplevel' | 'none'
+  /** The `cache.inputStability` of every task that does not set its own. */
+  inputStability?: InputStability
+  /** The `cache.outputs.clean` of every task that does not set its own. */
+  outputs?: { clean?: boolean }
+}
+
+/** `WorkspaceConfig.lock`. */
+export interface LockSettings {
+  /**
+   * `vx lock` writes each project's resolved config, pretty, to
+   * `vx.lock.json` beside its `vx.config`, for review; vx never reads it.
+   * On unless `false`.
    */
-  plugins?: readonly (Plugin | undefined | null | false)[]
+  reviewFiles?: boolean
+}
+
+/** `WorkspaceConfig.watch`. */
+export interface WatchSettings {
+  /** Poll for changes from the start instead of the OS watcher. */
+  poll?: boolean
 }
 
-/** `WorkspaceConfig.rules`. */
+/** `WorkspaceConfig.run.rules`. */
 export interface WorkspaceRules {
   /**
    * Refuse two tasks whose declared outputs overlap even when a `dependsOn`
@@ -94,6 +149,27 @@ export interface WorkspaceRules {
    * waits for its producer (`caching.md` § Local restore tier).
    */
   upfrontKeys?: boolean
+  /**
+   * Which workspace projects a project may depend on, checked by `vx lock`
+   * over each project's direct dependencies (its manifest's and its tasks'
+   * cross-project `dependsOn`). Every rule whose `from` selects a project
+   * applies to it; a project no rule selects is free.
+   */
+  dependencies?: readonly DependencyRule[]
+}
+
+/**
+ * One `run.rules.dependencies` entry. A selector is `tag:<tag>`, matching
+ * a project that carries the tag, or a project name; `*` matches any
+ * characters in either (`tag:scope:*`, `@acme/*`, `*`).
+ */
+export interface DependencyRule {
+  /** The projects this rule constrains. */
+  from: string
+  /** Given, each dependency must match one of these. */
+  allow?: readonly string[]
+  /** No dependency may match one of these; beats `allow`. */
+  deny?: readonly string[]
 }
 
 /**
@@ -110,7 +186,7 @@ export const PLUGIN_PACKAGE: unique symbol = Symbol.for('vx.plugin.package')
 /**
  * Structural plugin shape — any subset of the pipeline stages
  * (`config`/`project`/`graph`/`key`/`schedule`), run-level capabilities
- * (`cache`/`executor`/`telemetry`) and CLI `commands`, plus optional
+ * (`cache`/`executor`/`telemetry`/`output`) and CLI `commands`, plus optional
  * `setup`/`teardown`. The fully-typed `VxPlugin` lives in
  * `src/orchestrator/plugin.ts` and is what users import; this is a
  * re-declaration with opaque function types so `config.ts` stays a leaf
@@ -131,6 +207,7 @@ export interface Plugin {
   cache?(ctx: unknown): unknown
   executor?(ctx: unknown): unknown
   telemetry?(ctx: unknown): unknown
+  output?(ctx: unknown): unknown
   setup?(ctx: unknown): void | Promise<void>
   teardown?(): void | Promise<void>
   readonly fingerprint?: unknown
@@ -156,6 +233,7 @@ export const PLUGIN_HOOKS = [
   'executor',
   'cache',
   'telemetry',
+  'output',
   'setup',
   'commands',
   'teardown',
@@ -175,6 +253,13 @@ const _pluginHooksMatch: [HooksNotListed, HooksNotOnPlugin] extends [never, neve
 void _pluginHooksMatch
 
 export interface ProjectConfig {
+  /**
+   * The project's name, as task specs, filters and `dependsOn` address it.
+   * Unset: the name a `discover` plugin gives (a lockfile plugin's
+   * `package.json#name`), else the directory's root-relative path (`//`
+   * for the root).
+   */
+  name?: string
   /**
    * Labels for selection: `--filter tag:<name>` picks the projects that
    * carry one. Not in any cache key: a tag changes no task's behaviour.
@@ -387,7 +472,8 @@ export interface ExecConfig {
   /** Environment exposed to the child process. */
   env?: ExecEnv
   /**
-   * Upper bound (ms) before vx SIGTERMs the child. A normal task that
+   * Upper bound before vx SIGTERMs the child (`'10m'`), beating
+   * `run.timeout` and its flag and variable. A normal task that
    * runs longer is killed and reported `failed` (timed out) — never
    * cached. Omitted → no limit.
    *
@@ -398,7 +484,7 @@ export interface ExecConfig {
    * on spawn (no `readyWhen`) becomes ready before the timer can fire,
    * so the timeout is a no-op for it.
    */
-  timeout?: number
+  timeout?: Duration
   /**
    * Max ADDITIONAL attempts after a failed attempt. `retries: 2` means
    * up to 3 executions total. 0 / omitted → no retries (today's
@@ -408,8 +494,8 @@ export interface ExecConfig {
    * a failed attempt's partial outputs can't leak into the next. The
    * final outcome (and the cached artifact) is the last attempt's.
    * Not allowed with `persistent` — a persistent task has no exit to
-   * retry. Explicit config wins over the run-level `--retry <n>`
-   * default, including `retries: 0`.
+   * retry. Beats `run.retries` and its flag and variable, including
+   * `retries: 0`.
    */
   retries?: number
   /**
@@ -511,7 +597,8 @@ export interface InputStability {
    * withholds the entry, whatever the file holds after, since an edit
    * undone mid-run cannot be told from no edit. `'mutable'`: a file
    * rewritten to the bytes the key folded counts as unchanged, for a task
-   * that rewrites its own input identically (tsdown's `package.json`).
+   * that rewrites its own input identically (tsdown's `package.json`),
+   * unless another task that may write it ran meanwhile.
    * `'unchecked'`: no check.
    */
   strategy?: 'immutable' | 'mutable' | 'unchecked'
@@ -543,6 +630,14 @@ export interface CacheOutputs {
    * and before a restore, so the second would delete the first's).
    */
   workspaceFiles?: readonly string[]
+  /**
+   * `false`: a miss leaves the declared outputs in place for the command
+   * (tsc's `.tsbuildinfo`) instead of removing them first. A run that
+   * leaves a file it found untouched saves nothing, so an entry holds only
+   * what a clean run would leave. A retry still starts clean. Omitted →
+   * the workspace's `cache.outputs.clean`, else `true`.
+   */
+  clean?: boolean
 }
 
 export interface CacheInputs {
@@ -604,8 +699,8 @@ export interface CacheInputs {
    * trimmed (stdout + stderr) output is folded into the cache key.
    * Deduped per (projectDir, command) within a run. A non-zero exit
    * fails the run. Modeled on `env`: the COMMANDS are frozen in the
-   * lock, the OUTPUT is resolved live every run — correct under
-   * `--frozen`. Use for project-specific runtime probes.
+   * lock, the OUTPUT is resolved live every run. Use for
+   * project-specific runtime probes.
    */
   runtime?: readonly string[]
   /**
@@ -698,11 +793,15 @@ export function defineProject<const T extends ProjectConfig>(
 export function defineWorkspace<T extends WorkspaceConfig>(
   config: T &
     Known<T, WorkspaceConfig> & {
-      cacheRetention?: Known<
-        At<T, 'cacheRetention'>,
-        NonNullable<WorkspaceConfig['cacheRetention']>
-      >
-      rules?: Known<At<T, 'rules'>, WorkspaceRules>
+      run?: Known<At<T, 'run'>, RunSettings> & {
+        rules?: Known<At<At<T, 'run'>, 'rules'>, WorkspaceRules>
+      }
+      cache?: Known<At<T, 'cache'>, CacheSettings> & {
+        retention?: Known<At<At<T, 'cache'>, 'retention'>, NonNullable<CacheSettings['retention']>>
+        inputStability?: Known<At<At<T, 'cache'>, 'inputStability'>, InputStability>
+      }
+      lock?: Known<At<T, 'lock'>, LockSettings>
+      watch?: Known<At<T, 'watch'>, WatchSettings>
     },
 ): T {
   return config

package/src/exec/env.ts

@@ -1,5 +1,6 @@
 import { existsSync, readFileSync } from 'node:fs'
 import path from 'node:path'
+import { ESSENTIAL_ENV } from '../util/index.js'
 
 // Build the environment exposed to a task.
 //
@@ -9,37 +10,6 @@ import path from 'node:path'
 //   3. define: explicit name=value pairs from the task config.
 //   4. binPaths prepended to PATH (after all the above resolve PATH).
 
-/**
- * Exported so the schema doc's enumeration of it can be PINNED against the
- * real list: a hand-copied allowlist is how the two drift, and a reader
- * asking "what does my build script actually see?" is asking a
- * security-shaped question that a stale list answers wrongly.
- */
-export const ESSENTIAL_ENV: readonly string[] = [
-  'PATH',
-  'HOME',
-  'SHELL',
-  'USER',
-  'LOGNAME',
-  'TMPDIR',
-  'TEMP',
-  'TMP',
-  'LANG',
-  'LC_ALL',
-  'LC_CTYPE',
-  'TERM',
-  'COLORTERM',
-  'FORCE_COLOR',
-  'NO_COLOR',
-  'CI',
-  'NODE_OPTIONS',
-  // Where corepack and pnpm keep their own binaries, as HOME is: a machine
-  // path, never task output. Without them a corepack shim re-downloads its
-  // manager (offline or sandboxed: fails) and pnpm loses its global dir.
-  'COREPACK_HOME',
-  'PNPM_HOME',
-]
-
 /**
  * The two variables vx sets on every task it spawns, over the layers
  * above: the workspace root the run is in and the `project#task` running.