@vzn/vx 0.0.18 → 0.0.22

package/src/config.ts

@@ -14,13 +14,34 @@ 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.
+   * Evict from the local cache at the end of every run that writes to it,
+   * 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.
+   */
+  cacheRetention?: { olderThan?: string; maxSize?: 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`.
    */
   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 +53,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 +155,129 @@ 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 (`sandbox: {}`) grants almost nothing: the task reads
+ * nothing, writes nothing and reaches no network — NOT EVEN ITS OWN
+ * PROJECT DIRECTORY, which is why `allow: { read: ['.'] }` opens almost
+ * every real block. The one grant vx makes for you is dependencies:
+ * `node_modules`, and through it the real path of every workspace
+ * package linked there.
  *
- * No globs in path lists — bwrap on Linux only accepts path prefixes.
+ * `cache` grants no access in either direction: `cache.inputs` says what
+ * INVALIDATES a task, `allow` says what it may TOUCH, and deriving one
+ * from the other coupled them both ways — a declaration added for
+ * caching silently widened the sandbox, and a path the task needed had
+ * to be laundered through the cache key to get it (owner, 2026-09-05).
+ * A declared `cache.outputs` is NOT a write grant; the request
+ * `sandbox-request.ts` builds carries no write of its own and binds
+ * `allow.write` alone. This comment claimed the opposite — here and on
+ * both grant fields — while the file beside it and `schema.md` both said
+ * the truth, and no test read the bare baseline it described (item 443).
+ * That case has a test of its own now.
+ *
+ * Enforcement anchors at the WORKSPACE ROOT, so a task cannot leave its
+ * project whatever it declares here. The full account, including what a
+ * write grant costs on Linux, is in `docs/schema.md` under
+ * `exec.sandbox`.
+ *
+ * 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 ===
+  /** Capabilities granted on top of the task's own declarations. */
+  allow?: SandboxGrants
   /**
-   * 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.
+   * Capabilities taken away. Evaluated before `allow`, so a domain in both
+   * is denied.
    */
-  allowRead?: string[]
+  deny?: SandboxDenials
   /**
-   * 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`.
+   * 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
+   * ```
    */
-  allowWrite?: string[]
+  ignore?: SandboxGrants
   /**
-   * Permit writes to `.git/config` files. Default `false` — most build
-   * tools should not be reconfiguring git.
+   * 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.
    */
-  allowGitConfig?: boolean
+  weakerWhenNested?: boolean
+  /** Accept weaker network isolation (host proxy) for lower overhead. */
+  weakerNetworkIsolation?: boolean
+}
 
-  // === Network ===
+export interface SandboxGrants {
   /**
-   * Network policy.
-   *   - `false` (default) — block all outbound traffic.
-   *   - `true`            — allow all outbound traffic.
-   *   - object            — fine-grained control (domains / sockets / etc.).
+   * Readable path prefixes, added to the baseline — which is
+   * `node_modules`, NOT `cache.inputs.files`. A task that reads its own
+   * source in the sandbox says so here.
    */
-  network?: boolean | SandboxNetworkConfig
-
-  // === Process behavior ===
+  read?: string[]
   /**
-   * Allow the task to acquire a pseudo-terminal. Default `false`.
-   * Needed by tasks that interact with a TTY (rare in CI).
+   * Writable path prefixes. The task can write NOTHING without these:
+   * declaring `cache.outputs.files` grants no write, and a task whose
+   * only declaration is its outputs writes into a tmpfs that evaporates
+   * (vx then warns that `cache.outputs` matched no files).
    */
-  allowPty?: boolean
+  write?: string[]
   /**
-   * Linux only. Allow nested sandboxes (a sandboxed task spawning
-   * another sandboxed task). Default `false`.
+   * Reachable domains. `true` allows all, `['*.example.com']` a pattern.
+   * Omitted means no network at all.
    */
-  enableWeakerNestedSandbox?: boolean
+  network?: true | string[]
   /**
-   * macOS only. Skip the network namespace; routes traffic via the
-   * host proxy instead of unsharing networking. Lower overhead but
-   * weaker isolation. Default `false`.
+   * 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).
    */
-  enableWeakerNetworkIsolation?: boolean
-
-  // === Violation policy ===
+  systemInfo?: string[]
+  /** Unix socket paths the task may connect to. `true` allows any. */
+  unixSockets?: true | string[]
   /**
-   * 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.
+   * 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`.
    */
-  ignoreViolations?: Record<string, string[]>
+  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 +325,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 +334,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` does —
+   * the environment the child 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 +410,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>>

package/src/exec/executor.ts

@@ -1,9 +1,9 @@
 // The per-task execution contract. `execute-task.ts` decides WHAT to run
 // (command, env, sandbox baselines, capture) and hands a fully-resolved
-// request here; an executor decides WHERE/HOW the process runs. Core ships
-// no executor of its own: `@vzn/vx/plugins/local-executor` is the
-// in-process spawn, declared in vx.workspace.ts like any other. Persistent
-// tasks (`exec.persistent`) never reach an executor: they are local by
+// request here; an executor decides WHERE/HOW the process runs. Core's own
+// `local-executor.ts` is the in-process spawn, and it sits at the TAIL of
+// every executor list — what a plugin executor declines runs here.
+// Persistent tasks (`exec.persistent`) never reach an executor: they are local by
 // construction (a worker cannot hand the submitter a listening port) and
 // stay on `runPersistent`.
 //
@@ -13,29 +13,33 @@
 
 import type { CaptureConfig, RunResult } from './runner.js'
 import type { ResolvedSandboxConfig, SandboxViolation } from './sandbox-runtime.js'
+import { UserError } from '../util/index.js'
 
 /** Sandbox baselines + the user's resolved sandbox block, when the task is sandboxed. */
 export interface ExecuteSandbox {
   readonly baseAllowRead: readonly string[]
-  readonly baseAllowWrite: readonly string[]
   readonly baseDenyRead: readonly string[]
-  readonly config: ResolvedSandboxConfig
   /**
-   * True when an EMPTY violation store on a CLEAN exit will be read as
-   * PROOF (`--verify=inputs` treats zero violations as `proven-complete`).
-   * On macOS the store is fed asynchronously from the unified log, so the
-   * runtime must pay the bounded settle window even for a 0-exit — a leaky
-   * task that swallows its own read error exits 0, and without the wait a
-   * merely-late violation record turns into a false pass of the verify.
+   * Only denials on a path under this directory are reported. A denial
+   * outside it is still ENFORCED — the task cannot leave its project — but
+   * that is the wall doing its job, not a finding to fail a run over.
+   */
+  readonly reportWithin: string
+  /**
+   * Canonical directories of the workspace packages core withheld from
+   * this task's `node_modules` grant (its key does not answer for them).
+   * A denial under one is reported too: the task reached for a dependency,
+   * which is the finding, not the wall.
    */
-  readonly settleOnCleanExit: boolean
+  readonly reportLinked: readonly string[]
+  readonly config: ResolvedSandboxConfig
 }
 
 /** One declared input file, as the cache key saw it. */
 export interface InputFile {
   /** Workspace-relative POSIX path. */
   readonly path: string
-  /** Git blob OID of the WORKTREE bytes (the same digest the key folds). */
+  /** Git blob OID of the WORKTREE bytes — for a symlink, of its target string — the same digest the key folds. */
   readonly digest: string
 }
 
@@ -50,8 +54,8 @@ export interface InputFile {
 export interface TaskInputs {
   /** Declared `cache.inputs.files` + `workspaceFiles` (own outputs excluded), sorted by path. */
   readonly files: readonly InputFile[]
-  /** Declared `cache.inputs.env` names with their resolved values. */
-  readonly env: ReadonlyArray<{ readonly name: string; readonly value: string }>
+  /** Declared `cache.inputs.env` names with their resolved values; `undefined` when unset. */
+  readonly env: ReadonlyArray<{ readonly name: string; readonly value: string | undefined }>
   /** `cache.inputs.runtime` commands and the output that was folded — a toolchain expectation. */
   readonly runtime: ReadonlyArray<{ readonly command: string; readonly output: string }>
   /** `cache.inputs.workspaceRuntime`, same shape. */
@@ -169,24 +173,12 @@ export interface TaskPlacement {
   readonly command: string
   /**
    * Must run on this machine: the task is persistent, depends (transitively)
-   * on a persistent task, or declares `exec.remote: false`. A `remote`
-   * executor is never offered such a task.
+   * on a persistent or sandboxed task, is sandboxed itself, or declares
+   * `exec.remote: false`. A `remote` executor is never offered such a task.
    */
   readonly pinnedLocal: boolean
   /** Declares `cache` — the only tasks whose input set is described, and so the only ones that can ship. */
   readonly cacheable: boolean
-  /**
-   * `exec.resources` VERBATIM — CPU cores, megabytes, and the image a
-   * worker must be running for this task to be routed to it. All three are
-   * requirements MATCHED against what an executor has, never instructions
-   * to build a machine: a distributed executor's workers belong to whoever
-   * runs the fleet.
-   *
-   * Placement is where this belongs: `exec.resources` is stripped from the
-   * cache key precisely because it decides WHERE a task fits, never what
-   * it produces.
-   */
-  readonly resources?: Readonly<{ cpus?: number; memory?: number; image?: string }>
 }
 
 export interface TaskExecutor {
@@ -219,6 +211,45 @@ export interface TaskExecutor {
   execute(req: ExecuteRequest): Promise<ExecuteResult>
 }
 
+/**
+ * The result an executor resolves with is a plugin's, so its shape is a
+ * boundary: a plugin that resolved `{}` met `res.violations` in core and
+ * became "internal error in <task>: TypeError …" — vx's crash, the plugin's
+ * bug (2026-09-16). Name the executor and the field instead. The factory's
+ * output is checked the same way in `resolveExecutors`.
+ */
+export function assertExecuteResult(
+  executor: string,
+  taskId: string,
+  res: unknown,
+): asserts res is ExecuteResult {
+  const fail = (what: string): never => {
+    throw new UserError(
+      `executor '${executor}' returned an invalid result for ${taskId}: ${what} — a plugin bug, not a task failure`,
+    )
+  }
+  if (typeof res !== 'object' || res === null)
+    fail(`${res === null ? 'null' : typeof res} (expected an object)`)
+  const r = res as Record<string, unknown>
+  for (const key of ['exitCode', 'durationMs']) {
+    if (typeof r[key] !== 'number') fail(`${key} is ${typeof r[key]} (expected a number)`)
+  }
+  for (const key of ['stdout', 'stderr']) {
+    if (typeof r[key] !== 'string') fail(`${key} is ${typeof r[key]} (expected a string)`)
+  }
+  if (!Array.isArray(r['violations']))
+    fail(`violations is ${typeof r['violations']} (expected an array)`)
+  const outputs = r['outputs'] as { kind?: unknown; materialize?: unknown } | undefined
+  if (outputs !== undefined) {
+    if (typeof outputs !== 'object' || outputs === null) fail('outputs is not an object')
+    else if (outputs.kind === 'deferred') {
+      if (typeof outputs.materialize !== 'function')
+        fail('outputs.kind is deferred without a materialize()')
+    } else if (outputs.kind !== 'disk')
+      fail(`outputs.kind is ${String(outputs.kind)} (expected disk or deferred)`)
+  }
+}
+
 /**
  * Place one task: the first executor, in declaration order, that may take
  * it — a `remote` executor is skipped for a `pinnedLocal` task, then
@@ -234,6 +265,6 @@ export function selectExecutor(
     if (executor.accepts === undefined || executor.accepts(task)) return executor
   }
   throw new Error(
-    `no executor accepted ${task.taskId} (declared: ${executors.map((e) => e.name).join(', ')}). Declare localExecutorPlugin() after the executor that declined to run such tasks locally.`,
+    `no executor accepted ${task.taskId} (declared: ${executors.map((e) => e.name).join(', ')}). Core's local executor accepts every task, so this means it is missing from the list.`,
   )
 }

package/src/exec/index.ts

@@ -1,25 +1,39 @@
 // Module contract. Cross-module imports must come through here; see
 // docs/design/module-isolation-2026-06.md and tests/module-boundaries.test.ts.
 
-export { buildIsolatedEnv } from './env.js'
+export { buildIsolatedEnv, VX_RUN_TASK_ENV, VX_RUN_WORKSPACE_ENV } from './env.js'
 export {
   runCommand,
   runPersistent,
+  PersistentReadyError,
   shellQuote,
   signalExitCode,
+  exitSignal,
   type CaptureConfig,
+  execWord,
 } from './runner.js'
 export {
   initSandbox,
   probeSandbox,
+  unavailableReason,
   resetSandbox,
   resolveSandboxConfig,
   runSandboxed,
-  type DeniedCall,
+  releaseBridges,
+  wrapSandboxedCommand,
   type ResolvedSandboxConfig,
   type SandboxViolation,
+  dependencyReason,
+  socketPathRefusal,
+  thrownReason,
 } from './sandbox-runtime.js'
+export { type DeniedCall } from './sandbox-violations.js'
+export { isMountableLiteral, MOUNT_WILDCARDS, toRealPath } from './sandbox-paths.js'
+export { bindableWrites, punchWalls } from './sandbox-binds.js'
+export { localExecutor } from './local-executor.js'
+export { holdGroups, killTree, untilGroupsGone } from './kill-tree.js'
 export {
+  assertExecuteResult,
   selectExecutor,
   type ExecuteRequest,
   type ExecuteResult,