@vzn/vx 0.0.16 → 0.0.18

package/src/exec/sandbox-runtime.ts

@@ -17,8 +17,11 @@
 //   monitor in real time; violations carry the offending command +
 //   syscall line, so we get structured detection.
 //   Linux  — bwrap denies the read at the kernel boundary; the child
-//   sees ENOENT (or EPERM for some operations). SRT doesn't surface
-//   structured events for Linux, so detection is enforcement-only.
+//   sees ENOENT (or EPERM for some operations). SRT surfaces no
+//   structured events there, so we wrap the spawn in strace and parse
+//   the trace ourselves (`deniedCalls`) — detection is NOT
+//   enforcement-only on Linux, and the fail-on-violation branch in
+//   execute-task is live on both platforms.
 
 import path from 'node:path'
 import os from 'node:os'
@@ -27,10 +30,12 @@ import { unlink } from 'node:fs/promises'
 import type { SandboxConfig, SandboxNetworkConfig } from '../config.js'
 import {
   armTimeout,
+  drainOrAbort,
   shellQuote,
   signalExitCode,
   streamToString,
   resourceUsageToCpuRss,
+  type CaptureConfig,
   type RunResult,
 } from './runner.js'
 import { xxh3hex } from '../util/index.js'
@@ -155,6 +160,7 @@ export async function resetSandbox(): Promise<void> {
   const { SandboxManager } = await loadSrt()
   await SandboxManager.reset()
   availabilityCache = undefined
+  straceAvailableCache = undefined
 }
 
 export interface SandboxedRunArgs {
@@ -168,6 +174,11 @@ export interface SandboxedRunArgs {
   liveChildren?: Set<ReturnType<typeof Bun.spawn>>
   /** See `RunOptions.timeoutMs` — SIGTERM the child after this many ms. */
   timeoutMs?: number
+  /** See `CaptureConfig` — which streams are retained on the result. */
+  capture?: CaptureConfig
+  /** See `ExecuteSandbox.settleOnCleanExit` — pay the macOS settle window
+   *  even on a 0-exit, because an empty store will be read as proof. */
+  settleOnCleanExit?: boolean
   /**
    * Baseline reads — paths the sandbox unconditionally allows. The
    * caller builds this from resolved `cache.inputs.files`.
@@ -227,6 +238,32 @@ function toRealPath(p: string): string {
   }
 }
 
+/**
+ * Canonical form of every path the sandbox policy is expressed in.
+ *
+ * `resolveSandboxConfig` already canonicalizes the USER's paths; the
+ * orchestrator-supplied baselines (resolved inputs, output prefixes, the
+ * workspace-root deny anchor) arrived raw, so a workspace reached through a
+ * symlink expressed HALF its policy in real paths and half in link paths.
+ * bwrap then died mounting the link path inside its new root
+ * (`Can't mount tmpfs on /newroot/<link>`) and EVERY sandboxed task failed —
+ * whatever the config, with an error naming an internal path the user has no
+ * way to act on. Canonicalizing here is what makes the two halves agree.
+ */
+function canonicalBaselines(args: SandboxedRunArgs): {
+  allowRead: string[]
+  allowWrite: string[]
+  denyRead: string[]
+  cwd: string
+} {
+  return {
+    allowRead: args.baseAllowRead.map(toRealPath),
+    allowWrite: args.baseAllowWrite.map(toRealPath),
+    denyRead: args.baseDenyRead.map(toRealPath),
+    cwd: toRealPath(args.cwd),
+  }
+}
+
 /**
  * Convert a user-facing `SandboxConfig` (paths may be relative / tilde)
  * into a `ResolvedSandboxConfig` (all paths absolute + canonical) for a
@@ -291,7 +328,8 @@ export async function runSandboxed(args: SandboxedRunArgs): Promise<SandboxedRun
   const tag = xxh3hex(`${args.cwd}|${userCommand}|${process.hrtime.bigint()}`).slice(0, 16)
   const taggedCommand = `: 'vx-${tag}'; ${userCommand}`
 
-  const customConfig = buildCustomConfig(args)
+  const baselines = canonicalBaselines(args)
+  const customConfig = buildCustomConfig(args, baselines)
   const wrapped = await SandboxManager.wrapWithSandbox(taggedCommand, undefined, customConfig)
 
   // Linux: SRT's SandboxViolationStore is macOS-only, so structured
@@ -335,31 +373,92 @@ export async function runSandboxed(args: SandboxedRunArgs): Promise<SandboxedRun
   const timeout = armTimeout(proc, args.timeoutMs)
   const ac = new AbortController()
   const streams = Promise.all([
-    streamToString(proc.stdout, args.onStdout, ac.signal),
-    streamToString(proc.stderr, args.onStderr, ac.signal),
+    streamToString(proc.stdout, args.onStdout, ac.signal, args.capture?.stdout ?? true),
+    streamToString(proc.stderr, args.onStderr, ac.signal, args.capture?.stderr ?? true),
   ])
-  // See runCommand: gate on child exit, abort the readers on timeout so
-  // a lingering grandchild pipe can't hang the run.
+  // See runCommand: gate on child exit; a lingering grandchild pipe (timeout
+  // OR a clean exit that backgrounds a process) can't hang the run — timeout
+  // aborts at once, otherwise drainOrAbort bounds the post-exit drain.
   await proc.exited
   timeout.clear()
   if (timeout.timedOut()) ac.abort()
+  else await drainOrAbort(streams, ac)
   const [stdout, stderr] = await streams
   args.liveChildren?.delete(proc)
   const exitCode = proc.exitCode ?? (proc.signalCode ? signalExitCode(proc.signalCode) : 1)
 
   // macOS: read the violation store keyed by our tagged command.
+  //
+  // The store is fed ASYNCHRONOUSLY — SRT's monitor ingests macOS unified-log
+  // records, and log delivery lags under load — so reading it immediately
+  // after child exit races the pipeline: the denial happened, the child died
+  // on it, and the store is still empty. Observed locally as the 1-in-N
+  // "denied but zero violation lines" flake (decision log 2026-08-23/24).
+  // When the exit is a FAILURE and the store is empty, give the pipeline a
+  // bounded settle window; a clean exit skips the poll entirely, so the warm
+  // path pays nothing.
+  //
+  // MEASURED (2026-08-24, ~430 runs/arm under full-suite load): the poll
+  // HALVES the loss (5.0% → 2.2%) but cannot eliminate it — the residual
+  // failures survive the whole 1 s window, meaning those records were
+  // DROPPED by the unified log under pressure, not delayed. Reporting on
+  // macOS is therefore lossy-by-OS under load; ENFORCEMENT is unaffected
+  // (every observed loss still denied the read and failed the child).
   const store = SandboxManager.getSandboxViolationStore()
-  const macViolations = store.getViolationsForCommand(taggedCommand).map((v) => ({
-    line: v.line,
-    timestamp: v.timestamp,
-  }))
+  // Ancestor-directory traversal is NOT an input (owner call, 2026-08-24,
+  // closing the recorded false-`undeclared-inputs` item): to reach its cwd
+  // at all, a process stats/opens every directory on the path — macOS
+  // reports those as `deny(1) file-read-data <ancestor-dir>` for dirs the
+  // baseline doesn't list, node survives them, and no file CONTENT flowed.
+  // Dropping them is scoped to exact ancestor-or-self DIRECTORY paths of
+  // the task's cwd — a denied read of any file INSIDE an ancestor still
+  // reports. (These records usually arrived too late to be seen at all;
+  // the settle window made the pre-existing class visible on every clean
+  // verify exit.)
+  const cwdReal = toRealPath(args.cwd)
+  const ancestorDirs = new Set<string>()
+  for (let d = cwdReal; ; d = path.dirname(d)) {
+    ancestorDirs.add(d)
+    if (d === path.dirname(d)) break
+  }
+  const isAncestorTraversal = (line: string): boolean => {
+    const m = /deny\(\d+\)\s+file-read-(?:data|metadata)\s+(\/\S+)\s*$/.exec(line)
+    if (m === null) return false
+    return ancestorDirs.has(toRealPath(m[1]!))
+  }
+  const readMacViolations = (): SandboxViolation[] =>
+    store
+      .getViolationsForCommand(taggedCommand)
+      .filter((v) => !isAncestorTraversal(v.line))
+      .map((v) => ({
+        line: v.line,
+        timestamp: v.timestamp,
+      }))
+  let macViolations = readMacViolations()
+  // The fail-exit gate keeps the warm path free — EXCEPT when the caller
+  // says a clean exit + empty store will be read as PROOF (verify=inputs):
+  // a leaky task that swallows its own read error exits 0, so without the
+  // settle window a late unified-log record becomes a FALSE PASS of the
+  // verify (measured locally 2026-08-24: 1/30 at idle, the same lossy
+  // channel as the fail-exit case).
+  const emptyStoreIsProof = args.settleOnCleanExit === true
+  if (
+    process.platform === 'darwin' &&
+    (exitCode !== 0 || emptyStoreIsProof) &&
+    macViolations.length === 0
+  ) {
+    for (let i = 0; i < 10 && macViolations.length === 0; i++) {
+      await Bun.sleep(100)
+      macViolations = readMacViolations()
+    }
+  }
 
   // Linux: parse the strace log and emit one violation per denied
   // syscall on a path inside denyRead that wasn't unconditionally
   // allowed. Best-effort — if parsing fails we surface no Linux
   // violations rather than fail the whole task.
   const linuxViolations: SandboxViolation[] = straceLog
-    ? await parseStraceViolations(straceLog, args).catch(() => [])
+    ? await parseStraceViolations(straceLog, args, baselines).catch(() => [])
     : []
   if (straceLog) await unlink(straceLog).catch(() => undefined)
 
@@ -419,15 +518,81 @@ async function wantsStraceDetection(): Promise<boolean> {
  *   <pid> access("<path>", <mode>) = -1 EACCES (...)
  *   <pid> statx(AT_FDCWD, "<path>", <flags>, <mask>, ...) = -1 ENOENT (...)
  *
+ * …but ONLY when the syscall completes without another traced process
+ * interleaving. Under `-f` strace splits an interrupted call across two
+ * lines and the result never appears next to the path:
+ *   <pid> openat(AT_FDCWD, "<path>", <flags> <unfinished ...>
+ *   <pid> <... openat resumed>)             = -1 ENOENT (...)
+ * A single-line regex silently drops every one of those, so a task that
+ * forks concurrent children reading undeclared files reported an
+ * INCOMPLETE violation list — which for `--verify=inputs` reads as
+ * `proven-complete`. We pair them by pid instead (a process has at most
+ * one syscall in flight, so the pid is a sufficient key).
+ *
  * We capture the first quoted-string argument as the path. paths that
  * are relative resolve against the task's cwd (set by Bun.spawn).
  */
-const STRACE_RE =
-  /^\d+\s+(openat|access|statx|newfstatat)\([^"]*"([^"]+)"[^)]*\)\s*=\s*-1\s+(ENOENT|EACCES|EPERM)/gm
+const SYSCALLS = 'openat|access|statx|newfstatat'
+const STRACE_DONE_RE = new RegExp(
+  `^(\\d+)\\s+(${SYSCALLS})\\([^"]*"([^"]+)"[^)]*\\)\\s*=\\s*-1\\s+(ENOENT|EACCES|EPERM)`,
+)
+const STRACE_UNFINISHED_RE = new RegExp(`^(\\d+)\\s+(${SYSCALLS})\\([^"]*"([^"]+)"[^)]*<unfinished`)
+const STRACE_RESUMED_RE = new RegExp(
+  `^(\\d+)\\s+<\\.\\.\\. (${SYSCALLS}) resumed>.*?=\\s*-1\\s+(ENOENT|EACCES|EPERM)`,
+)
+/** A resumed call that SUCCEEDED — clears the pending entry, emits nothing. */
+const STRACE_RESUMED_OK_RE = new RegExp(`^(\\d+)\\s+<\\.\\.\\. (${SYSCALLS}) resumed>`)
+
+/** One denied syscall, however strace chose to lay it out. */
+export interface DeniedCall {
+  syscall: string
+  rawPath: string
+  errno: string
+}
+
+/**
+ * Walk the trace, pairing `<unfinished ...>` with its `<... resumed>` line.
+ *
+ * Exported for testing: this is the security-relevant half of the Linux
+ * detector, and a synthetic trace pins the split-line shapes deterministically
+ * where an end-to-end run only produces them when strace happens to interleave.
+ */
+export function deniedCalls(text: string): DeniedCall[] {
+  const pending = new Map<string, { syscall: string; rawPath: string }>()
+  const out: DeniedCall[] = []
+  for (const line of text.split('\n')) {
+    const done = STRACE_DONE_RE.exec(line)
+    if (done?.[2] !== undefined && done[3] !== undefined && done[4] !== undefined) {
+      out.push({ syscall: done[2], rawPath: done[3], errno: done[4] })
+      continue
+    }
+    const unfinished = STRACE_UNFINISHED_RE.exec(line)
+    if (
+      unfinished?.[1] !== undefined &&
+      unfinished[2] !== undefined &&
+      unfinished[3] !== undefined
+    ) {
+      pending.set(unfinished[1], { syscall: unfinished[2], rawPath: unfinished[3] })
+      continue
+    }
+    const resumedOk = STRACE_RESUMED_OK_RE.exec(line)
+    if (resumedOk?.[1] === undefined) continue
+    const held = pending.get(resumedOk[1])
+    pending.delete(resumedOk[1])
+    const resumed = STRACE_RESUMED_RE.exec(line)
+    // Only a resume that carries a DENIAL is a violation; a successful
+    // resume just retires the pending entry.
+    if (held !== undefined && resumed?.[3] !== undefined) {
+      out.push({ syscall: held.syscall, rawPath: held.rawPath, errno: resumed[3] })
+    }
+  }
+  return out
+}
 
 async function parseStraceViolations(
   logPath: string,
   args: SandboxedRunArgs,
+  baselines: { allowRead: readonly string[]; denyRead: readonly string[]; cwd: string },
 ): Promise<SandboxViolation[]> {
   const text = await Bun.file(logPath).text()
   if (text.length === 0) return []
@@ -435,18 +600,18 @@ async function parseStraceViolations(
   // Treat every baseAllow + sandbox.allowRead path as "this was
   // explicitly permitted; any -ENOENT here is the user's own missing
   // file, not a sandbox-induced denial". Same for absolute denyRead
-  // checks below.
+  // checks below. Canonical on BOTH sides — the policy is expressed in
+  // real paths (see `canonicalBaselines`), so comparing a link-path here
+  // would report an explicitly-allowed read as a violation.
   const allowAbs = new Set<string>(
-    [...args.baseAllowRead, ...args.config.allowRead].map((p) => absolutize(p)),
+    [...baselines.allowRead, ...args.config.allowRead].map((p) => toRealPath(absolutize(p))),
   )
-  const denyAnchors = args.baseDenyRead.map((p) => absolutize(p))
+  const denyAnchors = baselines.denyRead.map((p) => toRealPath(absolutize(p)))
 
   const seen = new Set<string>()
   const out: SandboxViolation[] = []
-  for (const m of text.matchAll(STRACE_RE)) {
-    const [, syscall, rawPath, errno] = m
-    if (!rawPath) continue
-    const abs = absolutize(rawPath, args.cwd)
+  for (const { syscall, rawPath, errno } of deniedCalls(text)) {
+    const abs = toRealPath(absolutize(rawPath, baselines.cwd))
     // Only report paths under the workspace-root deny anchor — system
     // libs / /proc / /sys / etc. probes are not interesting violations.
     if (!denyAnchors.some((root) => abs === root || abs.startsWith(root + path.sep))) continue
@@ -520,11 +685,16 @@ function filterIgnored(
  */
 function buildCustomConfig(
   args: SandboxedRunArgs,
+  baselines: {
+    allowRead: readonly string[]
+    allowWrite: readonly string[]
+    denyRead: readonly string[]
+  },
 ): Parameters<SrtModule['SandboxManager']['wrapWithSandbox']>[2] {
   const c = args.config
-  const allowRead = unique([...args.baseAllowRead, ...c.allowRead])
-  const denyRead = unique([...args.baseDenyRead])
-  const allowWrite = unique([...args.baseAllowWrite, ...c.allowWrite])
+  const allowRead = unique([...baselines.allowRead, ...c.allowRead])
+  const denyRead = unique([...baselines.denyRead])
+  const allowWrite = unique([...baselines.allowWrite, ...c.allowWrite])
 
   const custom: Parameters<SrtModule['SandboxManager']['wrapWithSandbox']>[2] = {
     filesystem: {

package/src/graph/index.ts

@@ -16,12 +16,14 @@ export {
   type TaskOutcome,
   type TaskStatus,
   type VerifyVerdict,
-  ZERO_COST,
 } from './scheduler.js'
 export {
   buildTaskGraph,
+  detectCycle,
   expandRequested,
   isGroupTask,
   markSurfacedDeps,
+  splitTaskId,
   type TaskNode,
+  unresolvedRequests,
 } from './task-graph.js'

package/src/graph/scheduler.ts

@@ -1,4 +1,4 @@
-import { UserError } from '../util/index.js'
+import { isUserError } from '../util/index.js'
 import type { TaskNode } from './task-graph.js'
 
 export type TaskStatus =
@@ -8,8 +8,10 @@ export type TaskStatus =
   | 'failed'
   | 'skipped'
   // A child killed by a shutdown signal (SIGINT/SIGTERM — e.g. Ctrl-C):
-  // the task never finished on its own terms, so it reverts to
-  // aborted — not counted, not shown (the run is tearing down).
+  // the task never finished on its own terms, so it reverts to aborted —
+  // excluded from the tally and the run history. It still PROPAGATES like
+  // a failure (see `willSkip`): the child died mid-write, so its outputs
+  // are partial.
   | 'aborted'
 
 /**
@@ -41,6 +43,10 @@ export type VerifyVerdict =
   | { kind: 'no-outputs' }
   /** Didn't execute (cache hit) / not cacheable / group / persistent. */
   | { kind: 'not-verified' }
+  /** A `remote: 'only'` task under `--verify=inputs`: verify pins placement
+   *  local, so the task no-ops — there is no execution to sandbox, locally
+   *  or anywhere. Reported, not silent: the proof does not cover it. */
+  | { kind: 'unverifiable-remote-only' }
 
 /**
  * Content fingerprint of a task's output tree, computed under a `--verify*`
@@ -75,9 +81,35 @@ export interface TaskOutcome {
   /** Cache key hash, if one was computed. Folded into dependents' keys
    *  (pure-input transitive — the upstream's input key, not its output). */
   hash?: string
+  /**
+   * For cache-hit statuses: the exec time the ENTRY was stored with — i.e.
+   * the work this hit skipped. Distinct from `durationMs`, which is always
+   * what THIS run spent (a hit's restore cost). The two differ by whatever
+   * the exec:restore ratio happens to be, so a surface reporting "time
+   * saved" must read this one; a surface reporting "time spent" must not.
+   * Undefined on every non-hit outcome — nothing was skipped.
+   */
+  storedDurationMs?: number
   /** v11 analytics: CPU time + peak RSS for this task's child process. */
   cpuMs?: number
   peakRssBytes?: number
+  /**
+   * A GROUP task's own dependency outcomes — the tasks it stands for.
+   * A group has no `exec` and therefore no outputs and no cache entry: its
+   * hash is a synthetic roll-up (`computeGroupHash`), so asking the local
+   * index what it produced returns nothing. A dependent needs the real
+   * tasks beneath it to describe its own input set, and only the group
+   * itself is ever in a position to say which those are. Set on group
+   * outcomes only; never folded into any key.
+   */
+  groupUpstream?: readonly TaskOutcome[]
+  /** Executor-reported placement label (`ExecuteResult.where`) — set only
+   *  when the task ran somewhere other than this host. Telemetry-only. */
+  where?: string
+  /** `'deferred'` when the task's outputs were left in the remote store
+   *  (`--download=none`) instead of landing on this machine. Absent for
+   *  every ordinary outcome. Telemetry-only. */
+  outputs?: 'deferred'
   /**
    * v11 analytics: hrtime span relative to the parent run's t=0.
    * Lets downstream analytics reconstruct the actual parallel timeline
@@ -141,15 +173,15 @@ export interface ResourceCost {
   mem: number
 }
 
-export const ZERO_COST: ResourceCost = { cpu: 0, mem: 0 }
+const ZERO_COST: ResourceCost = { cpu: 0, mem: 0 }
 
 export interface ScheduleOptions {
   nodes: Map<string, TaskNode>
   concurrency: number
   /**
    * Failure propagation (default 'deps-ok' — the historical behavior):
-   *   - 'deps-ok': a failed/skipped upstream skips its dependents;
-   *     independent siblings keep running.
+   *   - 'deps-ok': a failed/skipped/aborted upstream skips its
+   *     dependents; independent siblings keep running.
    *   - 'never': the first failure stops dispatch — in-flight tasks
    *     finish naturally, everything not yet started completes as
    *     skipped (restore-tier included: a fail-fast run stops
@@ -192,6 +224,14 @@ export interface ScheduleOptions {
    * second cache.get. When undefined/empty, behavior is byte-identical.
    */
   restoreTier?: ReadonlySet<string>
+  /**
+   * Pool assignment for tasks placed on an executor with its own capacity
+   * (a remote pool). Such a task occupies one of the pool's `capacity` slots
+   * instead of a local worker slot and reserves no local resources, so a
+   * remote pool is never throttled by the local CPU count. Undefined (or
+   * a `undefined` result) = the local pool.
+   */
+  poolOf?: (id: string) => { name: string; capacity: number } | undefined
   /**
    * Resolved per-task resource reservations (`exec.resources`, resolved
    * by the orchestrator against the run's budgets). An absent id means
@@ -458,8 +498,32 @@ export async function runGraph(options: ScheduleOptions): Promise<Map<string, Ta
   // is a cheap tar extract, not the task's real work — it reserves ZERO
   // regardless of what the config declares, so it never holds budget
   // against a real executor (and never parks).
+  const poolOf = options.poolOf
+  const poolActive = new Map<string, number>()
+  // A pooled task is admitted against ITS pool's capacity, a local one
+  // against `concurrency`; pooled tasks reserve no local resources.
+  const hasRoom = (id: string): boolean => {
+    const pool = poolOf?.(id)
+    if (pool === undefined) return active < concurrency
+    return (poolActive.get(pool.name) ?? 0) < pool.capacity
+  }
+  const admit = (id: string): (() => void) => {
+    const pool = poolOf?.(id)
+    if (pool === undefined) {
+      active++
+      return () => {
+        active--
+      }
+    }
+    poolActive.set(pool.name, (poolActive.get(pool.name) ?? 0) + 1)
+    return () => {
+      poolActive.set(pool.name, (poolActive.get(pool.name) ?? 1) - 1)
+    }
+  }
   const costOf = (id: string): ResourceCost =>
-    options.restoreTier?.has(id) ? ZERO_COST : (costs?.get(id) ?? ZERO_COST)
+    options.restoreTier?.has(id) || poolOf?.(id) !== undefined
+      ? ZERO_COST
+      : (costs?.get(id) ?? ZERO_COST)
 
   // Zero never blocks; a within-budget cost needs headroom (with an
   // exact-fill epsilon); an over-budget cost can never have headroom, so
@@ -502,7 +566,7 @@ export async function runGraph(options: ScheduleOptions): Promise<Map<string, Ta
       // Observer hook (the logger's taskComplete). Crash-isolated: a
       // throwing observer must NOT break scheduling — it would otherwise
       // skip the dependent-enqueue + tick below and hang the run. Same
-      // "observability never breaks a run" rule the telemetry/eventSink
+      // "observability never breaks a run" rule the telemetry
       // paths hold. Isolated here (not the completion arm) so a throw
       // can't be mistaken for the task itself failing.
       try {
@@ -523,7 +587,7 @@ export async function runGraph(options: ScheduleOptions): Promise<Map<string, Ta
     }
 
     // True when the task would be finished as `skipped` without running
-    // (fail-fast tripped, or a failed/skipped upstream under
+    // (fail-fast tripped, or a failed/skipped/aborted upstream under
     // continueMode !== 'always'). ONE predicate shared by the admission
     // parker and the dispatch loop's skip branch — a would-skip task
     // executes nothing, so it must never park on a resource fit (a
@@ -541,7 +605,13 @@ export async function runGraph(options: ScheduleOptions): Promise<Map<string, Ta
       const node = nodes.get(id) as TaskNode
       return node.deps.some((d) => {
         const u = outcomes.get(d)
-        return u?.status === 'failed' || u?.status === 'skipped'
+        // `aborted` propagates even though it is counted nowhere: the
+        // upstream was killed mid-write, so its declared outputs are
+        // partial. A dependent that ran anyway would CACHE what it built
+        // from them — under the key a healthy run derives, since the fold
+        // takes the upstream's INPUT key — so the next run replays those
+        // bytes as a green hit.
+        return u?.status === 'failed' || u?.status === 'skipped' || u?.status === 'aborted'
       })
     }
 
@@ -561,16 +631,20 @@ export async function runGraph(options: ScheduleOptions): Promise<Map<string, Ta
       // task returns without a fit check (finishing it is free); restore
       // tasks cost zero by construction, so they never park.
       const takeFitting = (): string | undefined => {
+        // No pools declared (the common case): a full local pool admits
+        // nothing, so do not scan — this is the legacy O(1) gate.
+        if (poolOf === undefined && active >= concurrency) return undefined
         while (execReady.size > 0) {
           const seq = execReady.peekSeq()
           const id = execReady.pop() as string
-          if (!resourcesActive || willSkip(id) || fits(id)) return id
+          if (willSkip(id) || ((!resourcesActive || fits(id)) && hasRoom(id))) return id
           parked.push([id, seq])
         }
-        return restoreReady.pop()
+        // Restore-tier tasks are local work (a cache restore on this disk).
+        return active < concurrency ? restoreReady.pop() : undefined
       }
 
-      while (active < concurrency) {
+      for (;;) {
         const id = takeFitting()
         if (id === undefined) break // nothing ready is admissible right now
         const node = nodes.get(id) as TaskNode
@@ -590,7 +664,7 @@ export async function runGraph(options: ScheduleOptions): Promise<Map<string, Ta
           continue
         }
 
-        active++
+        const leave = admit(id)
         // Reserve on dispatch; capture the cost so the release in the
         // completion callbacks is symmetric even if the maps change.
         const cost = costOf(id)
@@ -612,7 +686,7 @@ export async function runGraph(options: ScheduleOptions): Promise<Map<string, Ta
         // wedging the solo-clamp gate.
         execute(node, upstream).then(
           (outcome) => {
-            active--
+            leave()
             release(cost)
             finishOne(id, outcome)
             tick()
@@ -625,7 +699,7 @@ export async function runGraph(options: ScheduleOptions): Promise<Map<string, Ta
               exitCode: 1,
               durationMs: 0,
             }
-            active--
+            leave()
             release(cost)
             finishOne(id, outcome)
             // Surface the error live; the outcome itself doesn't
@@ -633,7 +707,7 @@ export async function runGraph(options: ScheduleOptions): Promise<Map<string, Ta
             // UserError is a config/input failure (e.g. a failed
             // `cache.inputs.runtime` command), not a vx bug — report it
             // plainly, never as an "internal error".
-            if (err instanceof UserError) {
+            if (isUserError(err)) {
               process.stderr.write(`[vx] ${id}: ${message}\n`)
             } else {
               const named = err instanceof Error && err.name !== 'Error' ? `${err.name}: ` : ''
@@ -658,7 +732,7 @@ export async function runGraph(options: ScheduleOptions): Promise<Map<string, Ta
   })
 }
 
-function mergePriorities(
+export function mergePriorities(
   baseline: ReadonlyMap<string, number>,
   overrides: ReadonlyMap<string, number>,
 ): ReadonlyMap<string, number> {