@vzn/vx 0.0.18 → 0.0.21

package/src/cli/why.ts

@@ -5,20 +5,24 @@
 // names the exact cache-key components that differ. Read-only over cache.db —
 // no config evaluation, no re-hash.
 
-import { Cache } from '../cache/index.js'
+import { Cache, noteSchemaReset } from '../cache/index.js'
+import { seeHelp } from './help.js'
 import { splitTaskId } from '../graph/index.js'
 import {
   cacheKeyDiff,
   explainCacheKeyQuery as explainCacheKey,
   whyDidThisRerunQuery as whyDidThisRerun,
 } from '../orchestrator/index.js'
-import { UserError } from '../util/index.js'
-import { findWorkspaceRoot, loadWorkspaceConfig, resolveCacheDir } from '../workspace/index.js'
+import { nearMatches, UserError } from '../util/index.js'
+import { findWorkspaceRoot } from '../workspace/index.js'
+import { cliCacheDir, parseCacheDirFlag, warnToStderr } from './workspace-config.js'
 
 interface WhyArgs {
   target?: string
   runId?: string
   format: 'pretty' | 'json'
+  /** `--cache-dir`: read the history a run with the same flag wrote. */
+  cacheDir?: string
   error?: string
 }
 
@@ -51,20 +55,37 @@ export function parseWhyArgs(args: readonly string[]): WhyArgs {
       out.format = fv
       continue
     }
-    if (a.startsWith('-')) return { ...out, error: `unknown flag: ${a}` }
+    const cd = parseCacheDirFlag(args, i)
+    if (cd !== null) {
+      if ('error' in cd) return { ...out, error: cd.error }
+      out.cacheDir = cd.cacheDir
+      i = cd.next
+      continue
+    }
+    if (a.startsWith('-')) return { ...out, error: `unknown flag: ${a}${seeHelp('why')}` }
     if (out.target !== undefined) return { ...out, error: `unexpected argument: ${a}` }
     out.target = a
   }
   return out
 }
 
-/** Simple includes-match in both directions, case-insensitive. */
-function suggest(query: string, candidates: readonly string[]): string {
-  const q = query.toLowerCase()
-  const hits = candidates.filter((c) => {
-    const n = c.toLowerCase()
-    return n.includes(q) || q.includes(n)
-  })
+/**
+ * A bare query is a TASK name, so it is matched against the task half of
+ * every recorded id (the same rule `vx run` hints with) and the hint is
+ * the runnable `project#task`; an anchored query is matched whole.
+ */
+function suggest(query: string, ids: readonly string[]): string {
+  let hits: string[]
+  if (query.includes('#')) {
+    hits = nearMatches(query, ids)
+  } else {
+    const byTask = new Map<string, string[]>()
+    for (const id of ids) {
+      const task = splitTaskId(id)[1]
+      byTask.set(task, [...(byTask.get(task) ?? []), id])
+    }
+    hits = nearMatches(query, byTask.keys()).flatMap((t) => byTask.get(t) ?? [])
+  }
   return hits.length > 0 ? ` — did you mean ${hits.slice(0, 3).join(', ')}?` : ''
 }
 
@@ -75,12 +96,21 @@ function suggest(query: string, candidates: readonly string[]): string {
  */
 function resolveTarget(cache: Cache, target: string): string {
   const db = cache.dbHandle()
+  if (target.includes('#')) {
+    // An exact id needs one row, and its newest is where a scan from the
+    // top of the table finds it first — the full DISTINCT walk below is for
+    // the error's suggestions and the bare-name form only.
+    const [project, task] = splitTaskId(target)
+    const hit = db
+      .query('SELECT 1 FROM runs WHERE project = ? AND task = ? ORDER BY id DESC LIMIT 1')
+      .get(project, task)
+    if (hit !== null) return target
+  }
   const pairs = db
     .query('SELECT DISTINCT project, task FROM runs ORDER BY project, task')
     .all() as Array<{ project: string; task: string }>
   const ids = pairs.map((p) => `${p.project}#${p.task}`)
   if (target.includes('#')) {
-    if (ids.includes(target)) return target
     throw new UserError(`vx why: no recorded runs for "${target}"${suggest(target, ids)}`)
   }
   const matches = ids.filter((id) => id.endsWith(`#${target}`))
@@ -117,8 +147,8 @@ export async function whyCmd(args: readonly string[]): Promise<number> {
   }
 
   const root = await findWorkspaceRoot(process.cwd())
-  const cacheDir = resolveCacheDir(root, await loadWorkspaceConfig(root))
-  const cache = new Cache(cacheDir)
+  const cache = new Cache(await cliCacheDir(root, parsed.cacheDir))
+  noteSchemaReset(cache, warnToStderr)
   try {
     const db = cache.dbHandle()
     const taskId = resolveTarget(cache, parsed.target)

package/src/cli/workspace-config.ts

@@ -0,0 +1,126 @@
+// The workspace as every verb must see it: the config with the plugin
+// `config` stage applied, and the cache dir derived from THAT. The stage
+// is documented to shape `cacheDir`; a verb that read the file raw opened
+// a directory the run never used — `vx last` found no runs, `vx cache
+// prune` pruned nothing, `vx watch` ignored the wrong path.
+
+import path from 'node:path'
+import type { WorkspaceConfig } from '../config.js'
+import { UserError } from '../util/index.js'
+import { Cache, noteSchemaReset } from '../cache/index.js'
+import { loadProjects, loadWorkspacePlugins } from '../orchestrator/index.js'
+import type { VxPlugin } from '../orchestrator/index.js'
+import {
+  buildPackageGraph,
+  computeWorkspaceFingerprint,
+  FROZEN_WITHOUT_LOCK,
+  type ProjectEntry,
+  type ProjectMeta,
+  readLockfile,
+  resolveCacheDir,
+} from '../workspace/index.js'
+
+export interface CliWorkspace {
+  workspaceConfig: WorkspaceConfig | null
+  plugins: readonly VxPlugin[]
+  cacheDir: string
+}
+
+export const warnToStderr = (message: string): void => {
+  process.stderr.write(`${message}\n`)
+}
+
+export async function loadCliWorkspace(workspaceRoot: string): Promise<CliWorkspace> {
+  const { workspaceConfig, plugins } = await loadWorkspacePlugins(workspaceRoot, warnToStderr)
+  return { workspaceConfig, plugins, cacheDir: resolveCacheDir(workspaceRoot, workspaceConfig) }
+}
+
+/**
+ * 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; no closure, no
+ * lock (a verb reads live, as a default run does).
+ */
+/**
+ * `--cache-dir <path>` / `--cache-dir=<path>` for a verb that reads the
+ * cache a run wrote — `why`, `last`, `info`, `cache prune`. 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
+ * this flag; `next` is the index of the last argv slot consumed.
+ */
+export function parseCacheDirFlag(
+  args: readonly string[],
+  i: number,
+): { cacheDir: string; next: number } | { error: string } | null {
+  const a = args[i]!
+  if (a !== '--cache-dir' && !a.startsWith('--cache-dir=')) return null
+  const v = a === '--cache-dir' ? args[i + 1] : a.slice('--cache-dir='.length)
+  if (v === undefined || v === '') return { error: '--cache-dir requires a path' }
+  if (a === '--cache-dir' && v.startsWith('-')) {
+    return { error: `--cache-dir requires a path, got flag: ${v}` }
+  }
+  return { cacheDir: v, next: a === '--cache-dir' ? i + 1 : i }
+}
+
+/**
+ * The cache directory a reading verb opens: `--cache-dir` resolved against
+ * cwd exactly as `vx run` resolves it (prepare.ts), else the workspace's —
+ * so `vx run --cache-dir X` and `vx last --cache-dir X` read one history.
+ */
+export async function cliCacheDir(
+  workspaceRoot: string,
+  override: string | undefined,
+): Promise<string> {
+  if (override !== undefined) return path.resolve(process.cwd(), override)
+  return (await loadCliWorkspace(workspaceRoot)).cacheDir
+}
+
+/** 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. */
+  cacheDir?: string
+  /** `--frozen`: configs come from `vx-lock.json`, not evaluation. */
+  frozen?: boolean
+}
+
+export async function loadCliProjects(
+  workspaceRoot: string,
+  metas: readonly ProjectMeta[],
+  scope: 'all' | readonly string[] = 'all',
+  opts: CliLoadOptions = {},
+): 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 = new Cache(cacheDir)
+  noteSchemaReset(cache, warnToStderr)
+  try {
+    const loaded = await loadProjects({
+      workspaceRoot,
+      cacheDir,
+      plugins,
+      projectMetas: metas,
+      packageGraph: buildPackageGraph([...metas]),
+      seeds: scope,
+      closure: false,
+      lock,
+      evalCache: {
+        store: cache,
+        workspaceFingerprint: await computeWorkspaceFingerprint(workspaceRoot),
+      },
+      warn: warnToStderr,
+    })
+    return loaded.projects
+  } finally {
+    cache.close()
+  }
+}

package/src/config.ts

@@ -14,13 +14,25 @@ export interface WorkspaceConfig {
    */
   timeout?: number
   /**
-   * Plugins registered for this workspace. Each plugin is an
-   * in-process subscriber on the run event bus, installed once per
-   * `vx run`. See `docs/design/extension-protocol-2026-06.md` §5.
+   * 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`.
    */
   plugins?: readonly Plugin[]
 }
 
+/**
+ * The runtime brand `definePlugin` stamps on a plugin: the name of the
+ * package it was defined in. The workspace loader accepts a plugin only
+ * when this is present and equals `name`, so a plugin's name is its
+ * package name and nothing else — no field to set, no override. A
+ * registry symbol on purpose: a plugin package imports its own copy of
+ * `@vzn/vx` beside a compiled binary's, and the two copies must stamp
+ * and check the same key.
+ */
+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
@@ -32,20 +44,60 @@ export interface WorkspaceConfig {
  * before consulting capabilities.
  */
 export interface Plugin {
+  /** The package name — set by `definePlugin`, never by the plugin. */
   readonly name: string
   config?(workspace: unknown, ctx: unknown): unknown
   project?(config: unknown, ctx: unknown): unknown
   graph?(nodes: unknown, ctx: unknown): unknown
   key?(task: unknown, ctx: unknown): unknown
   schedule?(nodes: unknown, ctx: unknown): unknown
+  admit?(task: unknown, ctx: unknown): unknown
   readonly commands?: Readonly<Record<string, unknown>>
   cache?(ctx: unknown): unknown
   executor?(ctx: unknown): unknown
   telemetry?(ctx: unknown): unknown
   setup?(ctx: unknown): void | Promise<void>
   teardown?(): void | Promise<void>
+  readonly fingerprint?: unknown
 }
 
+/**
+ * Every hook a plugin may fill, in pipeline order — THE list. The loader's
+ * "must be a function" and "at least one of" checks, the host's stage gate
+ * and `vx info`'s seam column all read it, so a stage added here is a stage
+ * everywhere: `admit` reached `vx info` a day late (2026-09-12) because
+ * that column kept its own copy, and the loader kept a third. The type
+ * pin below refuses a list that drifts from `Plugin`'s keys either way.
+ */
+export const PLUGIN_HOOKS = [
+  'config',
+  'project',
+  'graph',
+  'key',
+  'fingerprint',
+  'schedule',
+  'admit',
+  'executor',
+  'cache',
+  'telemetry',
+  'setup',
+  'commands',
+  'teardown',
+] as const
+export type PluginHook = (typeof PLUGIN_HOOKS)[number]
+/** The hooks that are functions; `commands` and `fingerprint` are objects. */
+export const PLUGIN_FUNCTION_HOOKS = PLUGIN_HOOKS.filter(
+  (h): h is Exclude<PluginHook, 'commands' | 'fingerprint'> =>
+    h !== 'commands' && h !== 'fingerprint',
+)
+type PluginHookKeys = Exclude<keyof Plugin, 'name'>
+type HooksNotListed = Exclude<PluginHookKeys, PluginHook>
+type HooksNotOnPlugin = Exclude<PluginHook, PluginHookKeys>
+// Both `never`, or this line does not compile: the list and the type agree.
+const _pluginHooksMatch: [HooksNotListed, HooksNotOnPlugin] extends [never, never] ? true : never =
+  true
+void _pluginHooksMatch
+
 export interface ProjectConfig {
   /** Tasks declared by this project, keyed by task name. */
   tasks?: Record<string, TaskConfig>
@@ -94,123 +146,101 @@ export interface TaskConfig {
    * runs.
    */
   cache?: CacheConfig
-  /**
-   * Sandbox configuration. **Sandbox is opt-in per task.**
-   *   - omitted entirely → task runs unsandboxed.
-   *   - `sandbox: {}`    → opts in with the minimum baseline (only
-   *     resolved inputs readable, only static-prefix of outputs
-   *     writable, network blocked).
-   *   - `sandbox: { ... }` → opts in with the explicit options below.
-   *
-   * No inheritance, no workspace defaults, no built-in escapes. The
-   * sandbox sees STRICTLY the union of resolved `cache.inputs.files`
-   * + this block's `allowRead` (for reads) and the static prefix of
-   * `cache.outputs.files` + this block's `allowWrite` (for writes).
-   * If a task needs `node_modules` or `/tmp`, declare them here
-   * explicitly.
-   *
-   * **Policy: fail on violation.** If the sandbox detects an
-   * undeclared read/write (macOS log monitor) or the child returns
-   * non-zero because it couldn't reach a path it expected (Linux
-   * structural deny), the task fails. No cache is written for a
-   * failed task.
-   *
-   * Activation requires `exec` (group tasks have no command to wrap)
-   * and is silently skipped for persistent tasks (dev servers need
-   * unrestricted network + an indefinite process).
-   */
-  sandbox?: SandboxConfig
 }
 
 /**
- * Per-task sandbox config. Mirrors the user-facing surface of
- * `@anthropic-ai/sandbox-runtime`'s `SandboxRuntimeConfig`, minus
- * deployment-only fields (binary paths, proxy ports, ripgrep config).
+ * What a sandboxed task may do, declared as CAPABILITIES.
+ *
+ * One shape for the whole policy. You say what the task is allowed to
+ * touch; vx decides how each capability is realised — some become sandbox
+ * runtime config, some become rules in the OS policy, and one the platform
+ * cannot express is an error rather than a silent no-op. None of that
+ * reaches the config.
  *
- * Path-list fields (`allowRead`, `allowWrite`, `network.allowUnixSockets`)
- * accept:
- *   - relative paths     → resolved against the project dir
- *   - absolute paths     → used as-is (`/etc/passwd`, `/tmp`)
- *   - tilde paths        → expanded against the user's home (`~/.npmrc`)
+ * The baseline is always the task's own declarations: it may read its
+ * resolved `cache.inputs.files`, write the prefixes of its
+ * `cache.outputs.files`, and reach nothing else. Everything here is on top
+ * of that.
  *
- * No globs in path lists — bwrap on Linux only accepts path prefixes.
+ * Paths are project-relative, absolute, or `~`-expanded — and are path
+ * PREFIXES, never globs (a glob cannot be enforced by a mount).
  */
 export interface SandboxConfig {
-  // === Filesystem ===
-  /**
-   * Additional read-allowed paths beyond resolved `cache.inputs.files`.
-   * These are unioned with the declared inputs to form the complete
-   * allowRead set passed to the sandbox.
-   */
-  allowRead?: string[]
+  /** Capabilities granted on top of the task's own declarations. */
+  allow?: SandboxGrants
   /**
-   * Additional write-allowed paths beyond the static prefix of
-   * `cache.outputs.files`. Tasks with no declared outputs and no extra
-   * `allowWrite` can write to nowhere — typical for `lint`/`typecheck`.
+   * Capabilities taken away. Evaluated before `allow`, so a domain in both
+   * is denied.
    */
-  allowWrite?: string[]
+  deny?: SandboxDenials
   /**
-   * Permit writes to `.git/config` files. Default `false` — most build
-   * tools should not be reconfiguring git.
-   */
-  allowGitConfig?: boolean
-
-  // === Network ===
-  /**
-   * Network policy.
-   *   - `false` (default) — block all outbound traffic.
-   *   - `true`            — allow all outbound traffic.
-   *   - object            — fine-grained control (domains / sockets / etc.).
-   */
-  network?: boolean | SandboxNetworkConfig
-
-  // === Process behavior ===
-  /**
-   * Allow the task to acquire a pseudo-terminal. Default `false`.
-   * Needed by tasks that interact with a TTY (rare in CI).
-   */
-  allowPty?: boolean
-  /**
-   * Linux only. Allow nested sandboxes (a sandboxed task spawning
-   * another sandboxed task). Default `false`.
+   * Denials to leave out of the report, in the same shape as `allow`.
+   *
+   * This does NOT permit anything: the OS still denies the operation, and
+   * a command that cannot proceed without it still fails. It says "I know,
+   * and it does not affect this task's output" — for a denial you cannot
+   * grant away and do not want failing the run.
+   *
+   * Unlike `allow`, the values are GLOB PATTERNS, and they work the same
+   * on every platform: `allow` has to be expressible by the OS sandbox
+   * (bwrap mounts a path; it cannot mount a pattern), while `ignore` only
+   * has to match a line vx already holds. Relative patterns anchor at the
+   * project dir.
+   *
+   * ```ts
+   * ignore: { write: ['*.bun-build'] }   // bun --compile stages a random
+   *                                      // temp name in the cwd
+   * ```
    */
-  enableWeakerNestedSandbox?: boolean
+  ignore?: SandboxGrants
   /**
-   * macOS only. Skip the network namespace; routes traffic via the
-   * host proxy instead of unsharing networking. Lower overhead but
-   * weaker isolation. Default `false`.
+   * Accept a weaker sandbox when vx itself already runs inside one
+   * (a container, another sandbox). Without it, nesting fails fast rather
+   * than pretending to confine.
    */
-  enableWeakerNetworkIsolation?: boolean
+  weakerWhenNested?: boolean
+  /** Accept weaker network isolation (host proxy) for lower overhead. */
+  weakerNetworkIsolation?: boolean
+}
 
-  // === Violation policy ===
-  /**
-   * Map of command-substring → list of paths to ignore violations on
-   * for that command. Lets you silence known-noisy probes (e.g. a
-   * compiler that statx's many candidate header paths). Per SRT's
-   * own ignoreViolations field.
-   */
-  ignoreViolations?: Record<string, string[]>
+export interface SandboxGrants {
+  /** Readable path prefixes, beyond the resolved `cache.inputs.files`. */
+  read?: string[]
+  /** Writable path prefixes, beyond the `cache.outputs.files` prefixes. */
+  write?: string[]
+  /**
+   * Reachable domains. `true` allows all, `['*.example.com']` a pattern.
+   * Omitted means no network at all.
+   */
+  network?: true | string[]
+  /**
+   * Kernel information the task may query, by info type — the name that
+   * appears in a denial, e.g. `vfs.disk-space` (every Bun and git process
+   * probes free space at startup).
+   */
+  systemInfo?: string[]
+  /** Unix socket paths the task may connect to. `true` allows any. */
+  unixSockets?: true | string[]
+  /**
+   * Bind and reach localhost ports — a test that boots a server for
+   * itself. A port LIST additionally makes those ports reachable from
+   * outside the sandbox (a dev server another task or the developer
+   * talks to): on Linux, where a sandboxed task lives in its own network
+   * namespace, each listed port is bridged out to the host's loopback;
+   * on macOS the host already sees them and the list means `true`.
+   */
+  localBinding?: boolean | number[]
+  /** macOS: Mach service names the task may look up. */
+  machLookup?: string[]
+  /** Acquire a TTY. Rare outside interactive tools. */
+  pty?: boolean
+  /** Write to `.git/config`. Most build tools should not. */
+  gitConfig?: boolean
 }
 
-export interface SandboxNetworkConfig {
-  /**
-   * Domain patterns the task may reach. Wildcards: `*.example.com`,
-   * `*` (allow all).
-   */
-  allowedDomains?: string[]
-  /** Domains explicitly blocked, evaluated before allowedDomains. */
-  deniedDomains?: string[]
-  /** Unix socket paths the task may connect to. */
-  allowUnixSockets?: string[]
-  /** Allow any Unix socket. Use with care. */
-  allowAllUnixSockets?: boolean
-  /**
-   * Allow binding to local ports (e.g. a test that boots a server on
-   * localhost for itself to query).
-   */
-  allowLocalBinding?: boolean
-  /** macOS only. Mach service names the task may look up. */
-  allowMachLookup?: string[]
+export interface SandboxDenials {
+  /** Domains blocked even if `allow.network` would admit them. */
+  network?: string[]
 }
 
 export interface ExecConfig {
@@ -258,16 +288,6 @@ export interface ExecConfig {
    * default, including `retries: 0`.
    */
   retries?: number
-  /**
-   * Resource RESERVATIONS for admission control — NOT enforcement: vx
-   * does not cgroup-limit, nice, or kill the task; it only decides what
-   * to co-schedule so concurrent reservations never exceed the CPU /
-   * memory budget. Each axis defaults to 0 = reserve nothing: the task
-   * runs subject only to the concurrency-count limit. A pure scheduling
-   * hint — the whole object is stripped from the cache key, so tuning a
-   * reservation never invalidates a cached result.
-   */
-  resources?: ResourcesConfig
   /**
    * Long-running / continuous task (dev server, watcher, daemon).
    * When present, the task is spawned but the runner does NOT wait
@@ -277,30 +297,29 @@ export interface ExecConfig {
    * on ready, not on exit. The orchestrator SIGTERMs every persistent
    * subprocess once the rest of the graph has finished.
    *
-   * `cache` is silently ignored for persistent tasks — there's no
-   * exit code to cache and the work continues after vx's run notion
-   * of "done".
+   * `cache` is rejected on a persistent task — there's no exit code
+   * to cache and the work continues after vx's run notion of "done".
    */
   persistent?: PersistentConfig
-}
-
-/**
- * Per-task resource reservation (see `ExecConfig.resources`). Grouped so
- * a future axis slots in without new top-level `exec` fields; the loader
- * rejects unknown keys.
- */
-export interface ResourcesConfig {
-  /** CPU cores; fractional is allowed (`0.5`). */
-  cpus?: number
-  /** Megabytes. `memory: 4096` is four gigabytes. */
-  memory?: number
   /**
-   * The container image this task needs, MATCHED against what a worker
-   * advertises — never a provisioning instruction, since a distributed
-   * executor's workers belong to whoever runs the fleet. Ignored by
-   * executors that do not run containers.
+   * Confine this task's process: what it may read, write and reach.
+   * Nothing is confined unless this is present.
+   *
+   * It sits in `exec` because it constrains the same spawn `env` and
+   * `resources` do — the environment the child gets, the CPU and memory it
+   * gets, the filesystem and network it gets. A group task has no process,
+   * so the field cannot be reached from one.
+   *
+   * **Policy: fail on violation.** An undeclared touch of the project's own
+   * files fails the task, and a failed task is never cached. Reaching
+   * OUTSIDE the project is denied but not reported — that is the wall
+   * doing its job, not a finding.
+   *
+   * A persistent task is confined the same way but never REPORTED on: the
+   * violation report reads the trace after the process exits, and a server
+   * exits at teardown. Enforced, not reported.
    */
-  image?: string
+  sandbox?: SandboxConfig
 }
 
 export interface PersistentConfig {
@@ -354,8 +373,9 @@ export interface CacheOutputs {
    * files anywhere in the workspace, including inside other projects'
    * directories. Deliberate escape hatch — prefer project-relative
    * `files` whenever the task can write inside its own dir. Two tasks
-   * declaring overlapping workspace outputs is user responsibility;
-   * vx does not police it.
+   * whose workspace outputs provably overlap are refused at graph build,
+   * like overlapping `files` (vx cleans declared outputs before a run
+   * and before a restore, so the second would delete the first's).
    */
   workspaceFiles?: string[]
 }

package/src/exec/env.ts

@@ -42,6 +42,17 @@ export const ESSENTIAL_ENV: readonly string[] = [
   'PATHEXT',
 ]
 
+/**
+ * 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.
+ * `run()` reads them back so a task that shells out to `vx run` in its OWN
+ * workspace is refused before it forks without bound (a different
+ * workspace — a fixture, a benchmark — is fine). Not in the allowlist:
+ * they come from this run, never from the parent environment.
+ */
+export const VX_RUN_WORKSPACE_ENV = 'VX_RUN_WORKSPACE'
+export const VX_RUN_TASK_ENV = 'VX_RUN_TASK'
+
 export interface BuildEnvOptions {
   passThrough: readonly string[]
   define: Readonly<Record<string, string>>