@vzn/vx 0.0.650 → 0.0.652

package/src/cli/why.ts

@@ -18,19 +18,9 @@ import {
   whyDidThisRerun,
 } from '../history/index.js'
 import { resolveRunId } from '../orchestrator/index.js'
-import {
-  detectColors,
-  ERROR,
-  MASKED,
-  nearMatches,
-  paint,
-  printable,
-  refusal,
-  SUCCESS,
-  ui,
-  UserError,
-  WARN,
-} from '../util/index.js'
+import { MASKED, nearMatches, printable, refusal, UserError } from '../util/index.js'
+import * as ui from '../ui/index.js'
+import type { Style } from '../ui/index.js'
 import { runRules } from '../settings.js'
 import { buildPackageGraph, findWorkspaceRoot } from '../workspace/index.js'
 import { findCwdProject } from './select.js'
@@ -165,6 +155,7 @@ async function resolveTarget(
   cache: Cache,
   target: string,
   cwdProject: () => Promise<string | null>,
+  declared: () => Promise<boolean>,
 ): Promise<string> {
   const db = indexDb(cache)
   if (target.includes('#')) {
@@ -202,11 +193,21 @@ async function resolveTarget(
   const ids = pairs.map((p) => `${p.project}#${p.task}`)
   const invoked = ids.length === 0 && db.query('SELECT 1 FROM invocations LIMIT 1').get() !== null
   if (ids.length === 0 && !invoked) {
+    // `vx run` of a task no project declares is refused: its advice was that.
+    const known = await declared()
     throw refusal(
-      { tone: 'info', headline: `no runs of ${target} yet`, fix: `vx run ${target}` },
+      known
+        ? { tone: 'info', headline: `no runs of ${target} yet`, fix: `vx run ${target}` }
+        : {
+            tone: 'info',
+            headline: `no project declares ${target}`,
+            fix: 'vx show lists the tasks',
+          },
       {
         code: 'VX_E_NO_HISTORY',
-        message: `vx why: no recorded runs for "${target}"${suggest(target, ids, invoked)}`,
+        message: known
+          ? `vx why: no recorded runs for "${target}"${suggest(target, ids, invoked)}`
+          : `vx why: no project declares "${target}" (vx show lists the tasks)`,
       },
     )
   }
@@ -264,8 +265,12 @@ export async function whyCmd(args: readonly string[]): Promise<number> {
   const cache = Cache.inspect(await cliCacheDir(root, parsed.cacheDir))
   try {
     const db = indexDb(cache)
-    const taskId = await resolveTarget(cache, await rootSpelled(root, parsed.target), () =>
-      findCwdProject(process.cwd()),
+    const target = await rootSpelled(root, parsed.target)
+    const taskId = await resolveTarget(
+      cache,
+      target,
+      () => findCwdProject(process.cwd()),
+      () => declares(root, target),
     )
     let runId: string | null
     if (parsed.runId !== undefined) {
@@ -290,14 +295,23 @@ export async function whyCmd(args: readonly string[]): Promise<number> {
       // the persisted entry metadata so the verb still says something useful.
       const explanation = explainCacheKey(db, taskId)
       if (parsed.format === 'json') {
-        process.stdout.write(`${JSON.stringify({ taskId, why: null, diff: null, explanation })}\n`)
+        ui.data('out', `${JSON.stringify({ taskId, why: null, diff: null, explanation })}\n`)
       } else {
-        const c = detectColors(process.stdout)
-        process.stdout.write(
-          `${ui.inline(ui.id(taskId), c)}: recorded runs carry no run id — showing the latest cache entry instead\n` +
-            (explanation.latestEntry !== null
-              ? `  hash ${explanation.latestEntry.hash} · $ ${explanation.latestEntry.command}\n`
-              : '  (no cache entry either)\n'),
+        ui.print(
+          'out',
+          ui.section(
+            'Why',
+            taskId,
+            ui.text('recorded runs carry no run id: the latest cache entry instead'),
+            ui.fields(
+              explanation.latestEntry !== null
+                ? [
+                    ['key', explanation.latestEntry.hash],
+                    ['command', ui.cmd(explanation.latestEntry.command)],
+                  ]
+                : [['key', 'no cache entry either']],
+            ),
+          ),
         )
       }
       return 0
@@ -326,27 +340,22 @@ export async function whyCmd(args: readonly string[]): Promise<number> {
     const writers = inputWriters(db, root, taskId, diff.entries, roots)
 
     if (parsed.format === 'json') {
-      process.stdout.write(`${JSON.stringify({ taskId, runId, why, diff, roots, writers })}\n`)
+      ui.data('out', `${JSON.stringify({ taskId, runId, why, diff, roots, writers })}\n`)
       return 0
     }
 
-    const lines: string[] = []
-    const c = detectColors(process.stdout)
-    const dim = (text: string): string => paint('', text, c, { dim: true })
-    const head = (text: string): string => paint('', text, c, { bold: true })
     const t = why.thisRun!
-    lines.push(`${ui.inline(ui.id(taskId), c)}${dim(` — run ${runId}`)}`)
-    lines.push(`  ${dim('this run')}   ${runFacts(t)}`)
+    const head: ui.FieldRow[] = [
+      ['run', runId],
+      ['this run', runFacts(t)],
+    ]
     if (why.previousRun == null && t.hash === '') {
       // Only keyed runs are compared: a persistent task's tenth run read
       // as its first, and the note saying why went unprinted.
-      lines.push(`  ${dim('previous')}   (none with a cache key)`)
-      lines.push(`  ${dim('verdict')}    ${why.note}`)
+      head.push(['previous', 'none with a cache key'], ['verdict', why.note])
     } else if (why.previousRun == null) {
-      lines.push(`  ${dim('previous')}   (none — first recorded run of this task)`)
+      head.push(['previous', 'none: first recorded run of this task'])
     } else {
-      const p = why.previousRun
-      lines.push(`  ${dim('previous')}   ${runFacts(p)}`)
       // The key moved and the diff says by what: the verdict names it, so
       // an env-only change reads as one line, not "inputs differ" above a
       // table to scan.
@@ -354,56 +363,71 @@ export async function whyCmd(args: readonly string[]): Promise<number> {
       const moved = diff.entries.map((e) =>
         e.name === e.kind ? e.kind : `${e.kind} ${printable(e.name)}`,
       )
-      lines.push(
-        `  ${dim('verdict')}    ${
+      head.push(
+        ['previous', runFacts(why.previousRun)],
+        [
+          'verdict',
           why.hashChanged === true && moved.length > 0
-            ? paint(
-                WARN,
+            ? ui.tone(
+                'warn',
                 `cache key changed: ${moved.slice(0, 3).join(', ')}${moved.length > 3 ? ` and ${moved.length - 3} more` : ''}`,
-                c,
               )
-            : why.note
-        }`,
+            : why.note,
+        ],
       )
     }
+    if (diff.entries.length === 0 && why.hashChanged === true) head.push(['detail', diff.note])
+    const blocks: ui.Block[] = [ui.section('Why', taskId, ui.fields(head))]
 
     if (diff.entries.length > 0) {
-      lines.push('')
-      lines.push(
-        `  ${head('what changed')}${dim(` (${diff.entries.length} component${diff.entries.length === 1 ? '' : 's'}, ${diff.unchangedCount} unchanged)`)}:`,
+      blocks.push(
+        ui.section(
+          'What changed',
+          `${diff.entries.length} of ${diff.entries.length + diff.unchangedCount}`,
+          ui.table(
+            ['change', 'kind', 'name', 'before → after'],
+            diff.entries.map((e) => [
+              ui.tone(CHANGE_HUE[e.change] ?? 'warn', e.change),
+              e.kind,
+              ui.strong(printable(e.name)),
+              // A secret-named env input shows its name and its change, no hash.
+              e.before === MASKED || e.after === MASKED
+                ? ''
+                : e.change === 'added'
+                  ? `+ ${e.after}`
+                  : e.change === 'removed'
+                    ? `- ${e.before}`
+                    : `${e.before} → ${e.after}`,
+            ]),
+          ),
+        ),
       )
-      const kindW = Math.max(...diff.entries.map((e) => e.kind.length), 4)
-      for (const e of diff.entries) {
-        // A secret-named env input shows its name and its change, no hash.
-        const beforeAfter =
-          e.before === MASKED || e.after === MASKED
-            ? ''
-            : e.change === 'added'
-              ? `+ ${e.after}`
-              : e.change === 'removed'
-                ? `- ${e.before}`
-                : `${e.before} → ${e.after}`
-        lines.push(
-          `    ${paint(CHANGE_HUE[e.change] ?? WARN, e.change.padEnd(7), c)} ${dim(e.kind.padEnd(kindW))}  ${printable(e.name)}  ${dim(beforeAfter)}`.trimEnd(),
-        )
-      }
       if (roots.length > 0) {
-        lines.push('', `  ${head('root cause')}:`)
-        for (const r of roots.slice(0, ROOTS_SHOWN)) {
+        const lines: ui.Inline[] = roots.slice(0, ROOTS_SHOWN).map((r) => {
           const what = r.entries.map((e) =>
             e.name === e.kind ? e.kind : `${e.kind} ${printable(e.name)}`,
           )
-          lines.push(
-            `    ${r.chain.join(' \u2190 ')} \u2190 ${what.slice(0, 3).join(', ')}${what.length > 3 ? ` and ${what.length - 3} more` : ''}`,
-          )
-        }
-        if (roots.length > ROOTS_SHOWN) lines.push(`    and ${roots.length - ROOTS_SHOWN} more`)
+          return [
+            ...r.chain.flatMap((id, i) => [...(i > 0 ? [ui.dim(' \u2190 ')] : []), ui.id(id)]),
+            ui.dim(' \u2190 '),
+            ui.strong(
+              `${what.slice(0, 3).join(', ')}${what.length > 3 ? ` and ${what.length - 3} more` : ''}`,
+            ),
+          ]
+        })
+        if (roots.length > ROOTS_SHOWN) lines.push(`and ${roots.length - ROOTS_SHOWN} more`)
+        blocks.push(ui.section('Root cause', ui.text(...lines)))
       }
       if (writers.length > 0) {
-        lines.push('', `  ${head('changed during a run')}:`)
-        for (const w of writers) {
-          lines.push(`    ${printable(w.file)}  ${dim(`while ${w.writers.join(', ')} ran`)}`)
-        }
+        blocks.push(
+          ui.section(
+            'Changed during a run',
+            ui.table(
+              ['file', 'written while'],
+              writers.map((w) => [ui.path(printable(w.file)), w.writers.join(', ')]),
+            ),
+          ),
+        )
       }
       const rootKinds = roots.flatMap((r) => r.entries.map((e) => e.kind))
       // An upstream row names the task to ask next: the command, not a
@@ -418,31 +442,26 @@ export async function whyCmd(args: readonly string[]): Promise<number> {
           k in WHAT_TO_DO && !(k === 'upstream' && (roots.length > 0 || upstream.length === 0)),
       )
       if (kinds.length > 0) {
-        lines.push('', `  ${head('what to do')}:`)
-        // Its own column: a root cause's kind and the `written` row are
-        // not in the table above, and overflowed its width.
-        const todoW = Math.max(kindW, ...kinds.map((k) => k.length), writers.length > 0 ? 7 : 0)
+        const todo: ui.FieldRow[] = []
         for (const k of kinds) {
           if (k === 'upstream') {
-            for (const todo of upstream) lines.push(`    ${dim(k.padEnd(todoW))}  ${todo}`)
+            todo.push([k, ...upstream])
             continue
           }
-          const todo =
+          todo.push([
+            k,
             k === 'config'
               ? WHAT_TO_DO[k]!.replace('`vx show <that task>`', `\`vx show ${taskId}\``)
-              : WHAT_TO_DO[k]
-          lines.push(`    ${dim(k.padEnd(todoW))}  ${todo}`)
-        }
-        if (writers.length > 0) {
-          // A task re-writing a file a key reads moves that key every run:
-          // the miss is right, and only moving the write ends it.
-          lines.push(`    ${dim('written'.padEnd(todoW))}  ${WRITTEN_TODO}`)
+              : WHAT_TO_DO[k]!,
+          ])
         }
+        // A task re-writing a file a key reads moves that key every run:
+        // the miss is right, and only moving the write ends it.
+        if (writers.length > 0) todo.push(['written', WRITTEN_TODO])
+        blocks.push(ui.section('What to do', ui.fields(todo)))
       }
-    } else if (why.hashChanged === true) {
-      lines.push(`  ${dim('detail')}     ${diff.note}`)
     }
-    process.stdout.write(`${lines.join('\n')}\n`)
+    ui.print('out', ...blocks)
     return 0
   } finally {
     cache.close()
@@ -451,7 +470,7 @@ export async function whyCmd(args: readonly string[]): Promise<number> {
 
 const ROOTS_SHOWN = 5
 
-const CHANGE_HUE: Record<string, string> = { added: SUCCESS, removed: ERROR, changed: WARN }
+const CHANGE_HUE: Record<string, Style> = { added: 'ok', removed: 'error', changed: 'warn' }
 
 type DiffEntry = ReturnType<typeof cacheKeyDiff>['entries'][number]
 
@@ -489,6 +508,21 @@ function upstreamTodo(upstream: readonly DiffEntry[], unrecorded: readonly DiffE
   return out
 }
 
+/** Whether a project declares `target` (`pkg#task`, or a bare task); true when no config loads. */
+async function declares(root: string, target: string): Promise<boolean> {
+  try {
+    const projects = await loadCliProjects(root, await discoverCliProjects(root), 'all')
+    const [project, task] = target.includes('#') ? splitTaskId(target) : [undefined, target]
+    return [...projects.values()].some(
+      (p) =>
+        (project === undefined || p.name === project) && Object.hasOwn(p.config.tasks ?? {}, task),
+    )
+  } catch {
+    // quiet: with no lock or a broken config, the run says why itself
+    return true
+  }
+}
+
 /**
  * Each group in `taskId`'s graph with the tasks it gathers. Empty when a
  * config no longer loads: the advice then names the group to `vx show`.

package/src/cli/workspace-config.ts

@@ -7,7 +7,8 @@
 import { existsSync } from 'node:fs'
 import path from 'node:path'
 import type { WorkspaceConfig } from '../config.js'
-import { UserError, sayLine } from '../util/index.js'
+import { UserError } from '../util/index.js'
+import { sayLine } from '../ui/index.js'
 import {
   discoverProjects,
   loadProjects,

package/src/config.ts

@@ -28,6 +28,10 @@ export interface WorkspaceConfig {
   baseBranch?: string
   run?: RunSettings
   cache?: CacheSettings
+  /** Input defaults for every task. */
+  inputs?: WorkspaceInputs
+  /** Output defaults for every task. */
+  outputs?: WorkspaceOutputs
   lock?: LockSettings
   watch?: WatchSettings
   /**
@@ -76,6 +80,18 @@ export interface RunSettings {
   rules?: WorkspaceRules
 }
 
+/** `WorkspaceConfig.inputs`. */
+export interface WorkspaceInputs {
+  /** The `inputs.stability` of every task that does not set its own. */
+  stability?: InputStability
+}
+
+/** `WorkspaceConfig.outputs`. */
+export interface WorkspaceOutputs {
+  /** The `outputs.clean` of every task that does not set its own. */
+  clean?: boolean
+}
+
 /** `WorkspaceConfig.cache`: where the cache lives and what a run does with it. */
 export interface CacheSettings {
   /**
@@ -93,10 +109,6 @@ export interface CacheSettings {
   policy?: string
   /** Which remote hits land on disk: `all` (the default), only the requested tasks' (`toplevel`), or `none`. */
   download?: 'all' | 'toplevel' | 'none'
-  /** The `cache.inputStability` of every task that does not set its own. */
-  inputStability?: InputStability
-  /** The `cache.outputs.clean` of every task that does not set its own. */
-  outputs?: { clean?: boolean }
   /**
    * Which runs keep a failed task's log and the files its outputs left in
    * the remote: CI runs (`'ci'`, the default), runs off CI (`'local'`), or
@@ -305,13 +317,15 @@ export interface TaskConfig {
    * keyed group: its inputs are a key its dependents fold, with no process.
    */
   inputs?: InputsConfig
+  /** What the task produces: saved on a miss, restored on a hit. Needs `cache: true`. */
+  outputs?: TaskOutputs
   /**
-   * Caching configuration. **Caching is opt-in.** If this field is omitted,
-   * the task always runs and nothing is read from or written to the cache.
-   * Requires `exec` and `inputs`: the key is the task's inputs, and a group
-   * runs nothing to cache.
+   * `true` caches the task. **Caching is opt-in.** Omitted or `false`, the
+   * task always runs and nothing is read from or written to the cache.
+   * Requires `exec`, `inputs` and `outputs`: the key is the task's inputs,
+   * and a group runs nothing to cache.
    */
-  cache?: CacheConfig
+  cache?: boolean
 }
 
 /**
@@ -335,7 +349,7 @@ export interface TaskConfig {
  * 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 (2026-09-05).
- * A declared `cache.outputs` is NOT a write grant; the request
+ * A declared `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
@@ -391,6 +405,13 @@ export interface SandboxConfig {
   weakerWhenNested?: boolean
   /** Accept weaker network isolation (host proxy) for lower overhead. */
   weakerNetworkIsolation?: boolean
+  /**
+   * Refuse every read outside the workspace too (`/usr`, `~/.cache`, the
+   * system toolchain), not only the workspace's other projects. A path
+   * outside it is readable only when `allow.read` names it; the shell a
+   * task runs in stays readable, so a task can start.
+   */
+  hermetic?: boolean
 }
 
 /** The denials `sandbox.ignore` can leave out of the report: patterns per class. */
@@ -410,9 +431,9 @@ export interface SandboxGrants {
   read?: readonly string[]
   /**
    * Writable paths or globs. The task can write NOTHING without these:
-   * declaring `cache.outputs.files` grants no write, and a task whose
+   * declaring `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).
+   * (vx then warns that `outputs` matched no files).
    */
   write?: readonly string[]
   /**
@@ -585,17 +606,6 @@ export interface ExecEnv {
   secret?: readonly string[]
 }
 
-export interface CacheConfig {
-  /** What this task produces. Captured for restore on a cache hit. */
-  outputs: CacheOutputs
-  /**
-   * What a write to an input while the command runs means. Each field,
-   * highest first: its env var, this, the workspace's `inputStability`,
-   * the default (`'immutable'`, `'warn'`).
-   */
-  inputStability?: InputStability
-}
-
 export interface InputStability {
   /**
    * `'immutable'` (the default): any write to an input during the command
@@ -615,7 +625,7 @@ export interface InputStability {
   severity?: 'warn' | 'error'
 }
 
-export interface CacheOutputs {
+export interface TaskOutputs {
   /**
    * Files produced by this task, as project-relative globs. Pass `[]`
    * when the task has no files to capture (e.g. `lint`, `typecheck`).
@@ -640,7 +650,7 @@ export interface CacheOutputs {
    * (tsc's `.tsbuildinfo`) instead of removing them first. A run that
    * leaves a file it found untouched saves nothing, so an entry holds only
    * what a clean run would leave. A retry still starts clean. Omitted →
-   * the workspace's `cache.outputs.clean`, else `true`.
+   * the workspace's `outputs.clean`, else `true`.
    */
   clean?: boolean
 }
@@ -716,6 +726,13 @@ export interface InputsConfig {
    * tool versions, OS info, etc.
    */
   workspaceRuntime?: readonly string[]
+  /**
+   * What a write to an input while the command runs means for the save.
+   * Each field, highest first: its env var, this, the workspace's
+   * `inputs.stability`, the default (`'immutable'`, `'warn'`). Needs
+   * `cache: true`.
+   */
+  stability?: InputStability
 }
 
 /**
@@ -785,9 +802,7 @@ export function defineProject<const T extends ProjectConfig>(
           dependsOn?: readonly DependsOnEntry<Extract<keyof NonNullable<T['tasks']>, string>>[]
           exec?: Known<At<NonNullable<T['tasks']>[K], 'exec'>, ExecConfig>
           inputs?: Known<At<NonNullable<T['tasks']>[K], 'inputs'>, InputsConfig>
-          cache?: Known<At<NonNullable<T['tasks']>[K], 'cache'>, CacheConfig> & {
-            outputs?: Known<At<At<NonNullable<T['tasks']>[K], 'cache'>, 'outputs'>, CacheOutputs>
-          }
+          outputs?: Known<At<NonNullable<T['tasks']>[K], 'outputs'>, TaskOutputs>
         }
       }
     },
@@ -801,9 +816,11 @@ export function defineWorkspace<T extends WorkspaceConfig>(
       run?: Known<At<T, 'run'>, RunSettings> & {
         rules?: Known<At<At<T, 'run'>, 'rules'>, WorkspaceRules>
       }
-      cache?: Known<At<T, 'cache'>, CacheSettings> & {
-        inputStability?: Known<At<At<T, 'cache'>, 'inputStability'>, InputStability>
+      cache?: Known<At<T, 'cache'>, CacheSettings>
+      inputs?: Known<At<T, 'inputs'>, WorkspaceInputs> & {
+        stability?: Known<At<At<T, 'inputs'>, 'stability'>, InputStability>
       }
+      outputs?: Known<At<T, 'outputs'>, WorkspaceOutputs>
       lock?: Known<At<T, 'lock'>, LockSettings>
       watch?: Known<At<T, 'watch'>, WatchSettings>
     },

package/src/exec/executor.ts

@@ -16,7 +16,8 @@
 import type { SandboxConfig } from '../config.js'
 import type { CaptureConfig, RunResult } from './runner.js'
 import type { ResolvedSandboxConfig, SandboxViolation } from './sandbox-runtime.js'
-import { thrownMessage, UserError, type ui } from '../util/index.js'
+import { thrownMessage, UserError } from '../util/index.js'
+import * as ui from '../ui/index.js'
 
 /** Sandbox baselines + the user's resolved sandbox block, when the task is sandboxed. */
 export interface ExecuteSandbox {
@@ -42,6 +43,11 @@ export interface ExecuteSandbox {
    * machine's paths and platform, hands `sandboxRequestFor`.
    */
   readonly keyed?: readonly string[]
+  /**
+   * The dependencies' outputs it may read (absolute), which an executor
+   * that builds the request again hands `sandboxRequestFor` too.
+   */
+  readonly dependencyReads?: readonly string[]
 }
 
 /** One declared input file, as the cache key saw it. */
@@ -107,7 +113,7 @@ export interface ExecuteRequest {
   /** `${project}#${task}` — for executors that route or log by task. */
   readonly taskId: string
   readonly workspaceRoot: string
-  /** Present for cacheable tasks (the miss path); absent when the task declares no `cache`. */
+  /** Present for cacheable tasks (the miss path); absent for a task without `cache: true`. */
   readonly inputs?: TaskInputs
   /**
    * The task's cache key (present when the task is cacheable). An executor
@@ -144,6 +150,12 @@ export interface ExecuteRequest {
    * executor's `platforms`: its key includes it. Absent when the task names none.
    */
   readonly platform?: string
+  /**
+   * Which attempt of the task this is, from 2 when it retries; absent on
+   * the first. An executor that can, runs a retry somewhere other than
+   * the attempt before it, so the machine is not the flake.
+   */
+  readonly attempt?: number
   /**
    * Whether this task's outputs must land on the submitter's disk now.
    * 'eager' (or absent) = materialise as today. 'deferred' = leave them
@@ -376,6 +388,13 @@ export interface TaskExecutor {
    * anything but a finite number, reports none.
    */
   idealMs?(): number | undefined
+  /**
+   * The workers that would have run the run best, judged after it from
+   * what each task took: for the run summary, so its reader can change
+   * how many workers the executor may start and of what size. Asked once
+   * at the end, only when a sink is on. A throw reports none.
+   */
+  advice?(): readonly WorkerAdvice[]
   /**
    * 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.
@@ -422,6 +441,27 @@ export interface MachineReport {
   startMs?: number
 }
 
+/**
+ * Workers that would have run the run best (`TaskExecutor.advice`): `of`
+ * says on what. `declared`: as many of each size the executor may start
+ * as end it soonest; `more`: past each size's limit, when that ends it
+ * sooner; `any`: one shape a platform, of any cores, ending as soon for
+ * the least core time.
+ */
+export interface WorkerAdvice {
+  of: 'declared' | 'more' | 'any'
+  /** The run's end on them, from its start. */
+  endMs: number
+  workers: readonly {
+    count: number
+    cores: number
+    memoryBytes: number
+    platform?: string
+    /** The size it is, for `declared` and `more`. */
+    size?: string
+  }[]
+}
+
 /**
  * What a remote executor rejects with when it gives a task back: core runs
  * the same request on the local floor and says `reason` once (a remote that

package/src/exec/index.ts

@@ -64,6 +64,7 @@ export {
   type ExecuteSandbox,
   type InputFile,
   type MachineReport,
+  type WorkerAdvice,
   type ServerSpec,
   type TaskExecutor,
   type TaskInputs,