@vzn/vx 0.0.646 → 0.0.649

package/src/exec/executor.ts

@@ -13,9 +13,10 @@
 // process primitives — the module-boundary matrix forbids `exec` → `cache`,
 // which is why sandbox baselines arrive pre-resolved on the request.
 
+import type { SandboxConfig } from '../config.js'
 import type { CaptureConfig, RunResult } from './runner.js'
 import type { ResolvedSandboxConfig, SandboxViolation } from './sandbox-runtime.js'
-import { UserError, type ui } from '../util/index.js'
+import { thrownMessage, UserError, type ui } from '../util/index.js'
 
 /** Sandbox baselines + the user's resolved sandbox block, when the task is sandboxed. */
 export interface ExecuteSandbox {
@@ -94,6 +95,12 @@ export interface ServerSpec {
   readonly readyWhen?: string
   /** Bounds the readiness wait. */
   readonly timeoutMs?: number
+  /**
+   * Its `exec.sandbox`, and the directories of the projects nested in its
+   * own (a wall its grants do not reach): it starts inside that sandbox,
+   * built where it runs, as a one-shot task's.
+   */
+  readonly sandbox?: { readonly config: SandboxConfig; readonly nested: readonly string[] }
 }
 
 export interface ExecuteRequest {
@@ -109,6 +116,15 @@ export interface ExecuteRequest {
    * this machine — needs a stable address, and the key is that address.
    */
   readonly cacheKey?: string
+  /**
+   * Core saves no entry under `cacheKey` after this attempt: the run's
+   * policy writes no layer (`--no-cache`, `--cache-policy local:r`), or an
+   * upstream failed under `--continue=always`, ran unkeyed or is keyless.
+   * An executor that saves a task's result for its dependants keeps it off
+   * that key too: a distributed run's worker saved it, and the next run
+   * hit an entry the user had said not to write (2026-10-24).
+   */
+  readonly unsaved?: boolean
   /**
    * Cache READS are disabled for this run (`--force` / `--no-cache`). An
    * executor that keeps its OWN remote record of executions must not serve
@@ -123,6 +139,11 @@ export interface ExecuteRequest {
    * execution under the same key.
    */
   readonly remoteOnly?: boolean
+  /**
+   * The platform to run it on, one of the task's `exec.platforms` and the
+   * executor's `platforms`: its key includes it. Absent when the task names none.
+   */
+  readonly platform?: string
   /**
    * Whether this task's outputs must land on the submitter's disk now.
    * 'eager' (or absent) = materialise as today. 'deferred' = leave them
@@ -198,9 +219,17 @@ export interface ExecuteResult extends RunResult {
    * existed. `deferred` means they are NOT on disk and `materialize()`
    * fetches them; core calls it lazily, at most once, and then saves an
    * ordinary cache entry, so a deferred task leaves no permanent third
-   * state behind.
+   * state behind. An executor may answer `deferred` to an `eager` request
+   * too, when it cannot bring them here: core saves nothing from this disk.
    */
   readonly outputs?: { kind: 'disk' } | { kind: 'deferred'; materialize: () => Promise<void> }
+  /**
+   * Tracked files the command changed where it ran, workspace-relative
+   * POSIX: an executor that runs it elsewhere says so, as this disk shows
+   * none of it. One the key read withholds the save under the key, as an
+   * input changed here does.
+   */
+  readonly changed?: readonly string[]
   /**
    * Executor-reported placement label — which machine ran the command
    * (a REAPI worker id, a pool member). Absent = this host. Rides
@@ -214,7 +243,16 @@ export interface ExecuteResult extends RunResult {
    * them: the run history keeps them, so a task that used all of one
    * reads as wanting a bigger one (`TaskResources.saturated*`).
    */
-  readonly machine?: { readonly cores: number; readonly memoryBytes: number }
+  readonly machine?: {
+    readonly cores: number
+    readonly memoryBytes: number
+    /**
+     * The share of a core each runnable thread got there over the task's
+     * run (1 when a core was free). On a crowded machine the CPU a task
+     * used is its share, not its need: the run history divides by this.
+     */
+    readonly cpuShare?: number
+  }
 }
 
 /** What an executor sees when a task is PLACED — once per task, before scheduling. */
@@ -251,7 +289,7 @@ export interface TaskExecutor {
    * it runs the task (`ExecuteRequest.servers`). It is offered the
    * dependants of a persistent task with no `exec.sandbox` and no
    * `exec.remote: false`; that task then runs here only for a dependant
-   * placed here (owner, 2026-10-22: nothing runs on a distributed run's
+   * placed here (2026-10-22: nothing runs on a distributed run's
    * orchestrator).
    */
   readonly servers?: boolean
@@ -263,6 +301,31 @@ export interface TaskExecutor {
    * here: their key holds this machine's answer (C-2).
    */
   readonly runtime?: boolean
+  /**
+   * A `remote` executor that runs every task of the run, so none runs on
+   * this machine; only cache hits restore here (2026-10-24: "no
+   * task should ever run on the orchestrator"). Nothing is pinned for it:
+   * it is offered `exec.remote: false` and `exec.interactive` tasks too,
+   * and starts every server a dependant needs. A task it cannot take (a
+   * platform it does not offer, one it declines, a server requested on its
+   * own) refuses the run, and a task it gives back fails.
+   */
+  readonly exclusive?: boolean
+  /**
+   * A `remote` executor that enforces `ExecuteRequest.timeoutMs` where it
+   * runs the command, timed from its start, and reports `timedOut`. Core
+   * then arms no clock of its own: armed at the request, it counted the
+   * wait for a worker still booting and killed a 1 s task with a 3 s
+   * timeout before it began (2026-10-24). The run's stop still aborts.
+   */
+  readonly timeouts?: boolean
+  /**
+   * The platforms this executor runs tasks on (`exec.platforms`' names). It
+   * is offered a task that declares `exec.platforms` only when one of them
+   * is listed, and runs it on `ExecuteRequest.platform`; an executor that
+   * declares none is never offered such a task off this machine.
+   */
+  readonly platforms?: readonly string[]
   /**
    * How many tasks this executor runs at once. Its tasks then occupy a pool
    * of this size instead of the local worker slots, so a remote pool is not
@@ -273,9 +336,10 @@ export interface TaskExecutor {
   /** Per-task opt-out at placement time. Absent = accepts every task it is offered. */
   accepts?(task: TaskPlacement): boolean
   /**
-   * The tasks placed here that have NOT finished yet — called once after
-   * placement with the whole set, then again after each completion (any
-   * outcome: a cache hit and a failure both remove one).
+   * The tasks placed here that will run and have NOT finished yet — called
+   * first once the run's cache has said which placed tasks it holds (those
+   * restore, so they are left out), then again after each completion (any
+   * outcome, a failure too) and when a task it left out executes after all.
    *
    * An executor that provisions something per task — a container, an
    * allocation, a pod — otherwise has to guess. `capacity` says how much it
@@ -284,8 +348,14 @@ export interface TaskExecutor {
    * moment the run can no longer use it, rather than holding it until
    * teardown. Absent = the executor does not care and nothing is computed
    * for it.
+   *
+   * `missed`: of `remaining`, those whose keys the run's up-front probe
+   * found in no store (each store asked answered for every key), or, when
+   * the remote has no batch probe, those the index keeps no hit of: they
+   * will run. The rest may still restore, or were not probed (a key an upstream's outputs can
+   * change). The same set each call, changed in place.
    */
-  demand?(remaining: ReadonlySet<string>): void
+  demand?(remaining: ReadonlySet<string>, missed: ReadonlySet<string>): void
   /**
    * Rows the run's footer shows for this executor, `[label, text]`, the
    * text plain or a `ui` inline (a tone colors it): what only it knows, such as the machines it ran tasks on. Asked on every
@@ -299,6 +369,20 @@ export interface TaskExecutor {
    * sink is on. A throw reports none.
    */
   machines?(): readonly MachineReport[]
+  /**
+   * The run's end had it placed its tasks perfectly, from the run's
+   * start: what each took, replayed on the machines it could have had, for
+   * the run summary beside the real time. Asked once at the end, only when a sink is on. A throw, or
+   * anything but a finite number, reports none.
+   */
+  idealMs?(): number | undefined
+  /**
+   * Its own Chrome-trace events for `vx run --profile` (the machines it ran
+   * tasks on, in time), asked once at the end, only when the flag is set.
+   * `ts` is in microseconds of `performance.now()`; `pid` from 1, which
+   * the run moves past its own process. A throw adds none.
+   */
+  profile?(): readonly Record<string, unknown>[]
   /**
    * Where a task it was handed runs (`small#2`), for the live row; asked
    * per frame. `null` while it holds the task for a machine to begin it:
@@ -318,8 +402,9 @@ export interface MachineReport {
   memoryBytes: number
   done: number
   failed: number
+  /** From when it joined to when it left or the run ended: warm-up not counted. */
   onlineMs: number
-  /** Time with at least one task running. */
+  /** Time with at least one task on it, from its send to its result. */
   busyMs: number
   /** Cores in use at once, at the most and on average over its time online. */
   cpuPeak: number
@@ -329,6 +414,12 @@ export interface MachineReport {
   memoryAvgBytes: number
   /** Core-time its tasks used over the core-time it had, 0 to 1. */
   utilization: number
+  /** Cores the executor booked for the tasks it ran, on average over its time online. */
+  bookedAvg?: number
+  /** From when the executor asked for it to when it joined, for one it started. */
+  warmUpMs?: number
+  /** When it was asked for (else when it joined), from the executor's start. */
+  startMs?: number
 }
 
 /**
@@ -365,6 +456,8 @@ export function assertExecuteResult(
       `executor '${executor}' returned an invalid result for ${taskId}: ${what} — a plugin bug, not a task failure`,
     )
   }
+  const shown = (v: unknown): string =>
+    typeof v === 'object' && v !== null ? 'an object' : String(v as string)
   if (typeof res !== 'object' || res === null)
     fail(`${res === null ? 'null' : typeof res} (expected an object)`)
   const r = res as Record<string, unknown>
@@ -382,6 +475,46 @@ export function assertExecuteResult(
   }
   if (!Array.isArray(r['violations']))
     fail(`violations is ${typeof r['violations']} (expected an array)`)
+  // The optional fields reach the task's row, telemetry and the run
+  // history: a `where` object lost the whole run's history to a bind error
+  // naming no executor, and a `null` violation failed the task as a TypeError.
+  for (const [i, v] of (r['violations'] as unknown[]).entries()) {
+    if (typeof v !== 'object' || v === null || typeof (v as { line?: unknown }).line !== 'string')
+      fail(`violations[${i}] is not an object with a string line`)
+  }
+  const where = r['where']
+  if (where !== undefined && (typeof where !== 'string' || where === ''))
+    fail(`where is ${where === '' ? 'empty' : typeof where} (expected a non-empty string)`)
+  for (const key of ['cpuMs', 'peakRssBytes']) {
+    const n = r[key]
+    if (n !== undefined && !(typeof n === 'number' && Number.isFinite(n) && n >= 0))
+      fail(`${key} is ${shown(n)} (expected a non-negative number)`)
+  }
+  const signal = r['signal']
+  if (
+    signal !== undefined &&
+    typeof signal !== 'string' &&
+    !(typeof signal === 'number' && Number.isInteger(signal) && signal > 0)
+  )
+    fail(`signal is ${shown(signal)} (expected a name or a signal number)`)
+  if (r['timedOut'] !== undefined && typeof r['timedOut'] !== 'boolean')
+    fail(`timedOut is ${typeof r['timedOut']} (expected a boolean)`)
+  const machine = r['machine']
+  if (machine !== undefined) {
+    if (typeof machine !== 'object' || machine === null) fail('machine is not an object')
+    const m = machine as Record<string, unknown>
+    // A worker that cannot read its memory reports 0 (vx-dte's join takes it).
+    for (const [key, least] of [
+      ['cores', 'positive'],
+      ['memoryBytes', 'non-negative'],
+      ['cpuShare', 'positive'],
+    ] as const) {
+      const n = m[key]
+      if (key === 'cpuShare' && n === undefined) continue
+      if (!(typeof n === 'number' && Number.isFinite(n) && (least === 'positive' ? n > 0 : n >= 0)))
+        fail(`machine.${key} is ${shown(n)} (expected a ${least} number)`)
+    }
+  }
   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')
@@ -391,6 +524,12 @@ export function assertExecuteResult(
     } else if (outputs.kind !== 'disk')
       fail(`outputs.kind is ${String(outputs.kind)} (expected disk or deferred)`)
   }
+  const changed = r['changed']
+  if (
+    changed !== undefined &&
+    (!Array.isArray(changed) || changed.some((f) => typeof f !== 'string'))
+  )
+    fail('changed is not an array of paths')
 }
 
 /**
@@ -424,7 +563,7 @@ export function selectExecutor(
         throw new Error('returned a Promise; accepts is synchronous')
       }
     } catch (err) {
-      const m = err instanceof Error ? err.message : String(err)
+      const m = thrownMessage(err)
       throw new UserError(`${label(executor)} failed in accepts for ${task.taskId}: ${m}`)
     }
     if (taken) return executor
@@ -433,3 +572,8 @@ export function selectExecutor(
     `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.`,
   )
 }
+
+/** This machine as `exec.platforms` names it: `os-arch` as Bun reports them, `linux-x64`. */
+export function hostPlatform(): string {
+  return `${process.platform}-${process.arch}`
+}

package/src/exec/index.ts

@@ -9,7 +9,9 @@ export {
   VX_RUN_WORKSPACE_ENV,
 } from './env.js'
 export {
+  lineEnds,
   runCommand,
+  restoreTerminalModes,
   runPersistent,
   PersistentReadyError,
   withForwardArgs,
@@ -19,6 +21,7 @@ export {
   type CaptureConfig,
   execWord,
   maskCaptured,
+  isDroppedOutputChunk,
   BoundedCapture,
   type CapturedChunk,
 } from './runner.js'
@@ -48,11 +51,12 @@ export {
 } from './sandbox-paths.js'
 export { bindableWrites, punchWalls } from './sandbox-binds.js'
 export { isLocalExecutor, localExecutor } from './local-executor.js'
-export { holdGroups, killTree, untilGroupsGone } from './kill-tree.js'
-export { sampleTrees } from './proc-sample.js'
+export { holdGroups, killTree, pauseTree, untilGroupsGone } from './kill-tree.js'
+export { sampleTrees, type TreeUsage } from './proc-sample.js'
 export {
   assertExecuteResult,
   executorFallback,
+  hostPlatform,
   isExecutorFallback,
   selectExecutor,
   type ExecuteRequest,

package/src/exec/kill-tree.ts

@@ -328,6 +328,21 @@ export function killTree(child: Child, signal: 'SIGINT' | 'SIGTERM' | 'SIGKILL')
   }
 }
 
+/**
+ * Stop or continue `child`'s group with vx (Ctrl-Z, `fg`). Straight to
+ * the group, never down a sandbox's channel: its watcher passes one
+ * signal and is gone. Under a Linux sandbox that stops bwrap, and the
+ * command inside blocks once its output pipe fills.
+ */
+export function pauseTree(child: Child, signal: 'SIGSTOP' | 'SIGCONT'): void {
+  if (!(child.pid > 0) || goneGroups.has(child)) return
+  try {
+    process.kill(-child.pid, signal)
+  } catch {
+    // The group is gone, or not ours: nothing of it to stop.
+  }
+}
+
 /**
  * How often a group whose leader has exited is asked again whether any
  * member is left. Only a group that outlived its leader is polled.

package/src/exec/local-executor.ts

@@ -2,7 +2,7 @@
 // process. Not a plugin — "run it on this machine" is not a capability
 // someone else supplies differently, it is what running MEANS when no
 // plugin claims the task, so it sits at the TAIL of every executor list
-// (owner, 2026-09-05). An executor plugin places work ELSEWHERE; its
+// (2026-09-05). An executor plugin places work ELSEWHERE; its
 // absence is "here".
 import { runCommand, signalExitCode, stopSignal } from './runner.js'
 import { runSandboxed } from './sandbox-runtime.js'

package/src/exec/proc-sample.ts

@@ -8,7 +8,7 @@
 // counted; nor is the CPU of a descendant that already exited.
 
 import { readdir, readFile } from 'node:fs/promises'
-import { procfsIsOwn } from '../util/index.js'
+import { helperEnv, procfsIsOwn } from '../util/index.js'
 
 export interface TreeUsage {
   /** CPU time of the live tree, user + system, in ms. */
@@ -125,7 +125,9 @@ async function linuxRssKiB(pid: number): Promise<number> {
 async function psTable(): Promise<Map<number, Proc> | undefined> {
   let text: string
   try {
+    // It runs beside the tasks, readable by them (`ps eww`): PATH alone.
     const ps = Bun.spawn(['ps', '-A', '-o', 'pid=,ppid=,rss=,time='], {
+      env: helperEnv(),
       stdin: 'ignore',
       stdout: 'pipe',
       stderr: 'ignore',