@vzn/vx-ci 0.0.646 → 0.0.649

package/src/plugin.ts

@@ -1,22 +1,17 @@
 // The `github()` telemetry plugin. Contributes one observe-only sink that
 // writes the run as a GitHub Actions job summary. Off Actions
 // (`GITHUB_ACTIONS` not 'true') the factory returns undefined, which
-// `plugins` skips: no option check, no hook, no load, so declaring
-// `github()` costs nothing on a laptop.
+// `plugins` skips: no hook, no load, so declaring `github()` costs nothing
+// on a laptop. index.ts checks its options everywhere.
 import { appendFile, stat } from 'node:fs/promises'
 import { createRequire } from 'node:module'
-import {
-  refuseUnknownOptions,
-  type PluginOptionKinds,
-  definePlugin,
-  UserError,
-  type VxPlugin,
-} from '@vzn/vx'
-import type { FetchFn } from './checks.js'
+import { homedir } from 'node:os'
+import path from 'node:path'
+import { definePlugin, type VxPlugin } from '@vzn/vx'
 import { githubBranch } from './cache-scope.js'
 
-// Every run evaluates `.vx/workspace.ts`; the sink, the summary renderer
-// and the Checks API client load only where a summary file is set. The
+// Every run evaluates `.vx/workspace.ts`; the sink and the summary
+// renderer load only where a summary file is set. The
 // telemetry hook is synchronous, so the module loads by `require`.
 const loadSink = (): typeof import('./sink.js') => createRequire(import.meta.url)('./sink.js')
 
@@ -29,16 +24,6 @@ export interface GithubPluginOptions {
   summaryFile?: string
   /** Heading for the summary block. Default: `'vx run'`. */
   title?: string
-  /**
-   * Also create a completed check-run on the built commit (Checks API).
-   * Default: on when the environment carries `GITHUB_TOKEN` +
-   * `GITHUB_REPOSITORY` + `GITHUB_SHA` (the workflow must grant
-   * `permissions: checks: write`); set `false` to opt out, `true` to warn
-   * when the environment is missing instead of silently skipping.
-   */
-  checks?: boolean
-  /** Check-run name. Default: `'vx'`. */
-  checkName?: string
   /**
    * Name the run's cache scope and base commit from the Actions event: none
    * on the default branch, else `<owner>/<repo>:<branch>` (a fork's names
@@ -47,100 +32,44 @@ export interface GithubPluginOptions {
    * `false` opts out.
    */
   cacheScope?: boolean
-  /** Test seam — inject the append. Defaults to fs appendFile. */
-  append?: (file: string, markdown: string) => Promise<void>
-  /** Test seam — inject the Checks API transport. Defaults to fetch. */
-  fetchFn?: FetchFn
-  /**
-   * Test seam — bytes the summary file already holds. Defaults to its size
-   * on disk; with `append` injected, 0 (that writer owns the file).
-   */
-  sizeOf?: (file: string) => Promise<number>
-}
-
-/**
- * Why a string cannot be an HTTP header value, or null. Bun's `fetch`
- * refuses a line break, a NUL or a character past Latin-1 once it has
- * trimmed the ends (measured on 1.4.2), and quotes the value in its error.
- */
-function headerValueFault(value: string): string | null {
-  let past = false
-  for (const ch of value.trim()) {
-    const c = ch.codePointAt(0)!
-    if (c === 0x0a || c === 0x0d || c === 0) return 'a line break or NUL'
-    if (c > 0xff) past = true
-  }
-  return past ? 'a character past Latin-1' : null
 }
 
 /** Each option `GithubPluginOptions` names, with its kind: derived from the type, so the two cannot drift. */
-const GITHUB_PLUGIN_KEYS: PluginOptionKinds<GithubPluginOptions> = {
-  summaryFile: 'string',
-  title: 'string',
-  checks: 'boolean',
-  checkName: 'string',
-  cacheScope: 'boolean',
-  append: 'function',
-  fetchFn: 'function',
-  sizeOf: 'function',
-}
-
 export function github(options: GithubPluginOptions = {}): VxPlugin | undefined {
   if (process.env['GITHUB_ACTIONS'] !== 'true') return undefined
-  refuseUnknownOptions('github()', options, GITHUB_PLUGIN_KEYS)
-  // '' passes the kind check but reads wrong: `??` keeps it, so summaryFile
-  // declined instead of using GITHUB_STEP_SUMMARY, checkName POSTed a name
-  // GitHub refuses (422) and title rendered an empty heading.
-  for (const key of ['summaryFile', 'title', 'checkName'] as const) {
-    if (options[key] === '')
-      throw new UserError(`github() option "${key}" must be a non-empty string, got ""`)
-  }
+  // Its options were checked by index.ts's github(), the only caller.
   return definePlugin(import.meta, {
-    async config(_workspace, ctx) {
+    commands: {
+      // Kept where actions/cache can save it: a hit installs the
+      // packages from it, no index fetch (14 to 52 s, 2026-10-22).
+      setup: {
+        description: 'github: install and prove the sandbox runtime on this runner',
+        run: async (argv) =>
+          (await import('./setup.js')).runSetup(
+            'github',
+            argv,
+            path.join(homedir(), '.cache', 'vx', 'setup-debs'),
+          ),
+      },
+    },
+    async config(workspace, ctx) {
       if (options.cacheScope === false) return
-      ctx.setBranch(await githubBranch(process.env))
+      ctx.setBranch(await githubBranch(process.env, workspace.baseBranch))
     },
     telemetry(ctx) {
       const file = options.summaryFile ?? process.env['GITHUB_STEP_SUMMARY']
       if (file === undefined || file === '') return undefined
-      const append = options.append ?? (async (f: string, md: string) => appendFile(f, md, 'utf8'))
-      const { GithubSummarySink, resolveCheckRunEnv } = loadSink()
-      let check: ConstructorParameters<typeof GithubSummarySink>[4]
-      if (options.checks !== false) {
-        const env = resolveCheckRunEnv(process.env)
-        // fetch refuses a token no header can carry and QUOTES it in its
-        // error, which the check-run warning printed (item 928).
-        const fault = env === null ? null : headerValueFault(env.token)
-        if (fault !== null) {
-          ctx.warn(
-            `vx-ci: GITHUB_TOKEN holds ${fault}, which no HTTP header can carry — no check-run will be created (the token is not printed)`,
-          )
-        } else if (env !== null) {
-          check = {
-            env,
-            name: options.checkName ?? 'vx',
-            fetchFn: options.fetchFn ?? (fetch as unknown as FetchFn),
-          }
-        } else if (options.checks === true) {
-          ctx.warn(
-            'vx-ci: checks requested but GITHUB_TOKEN / GITHUB_REPOSITORY / GITHUB_SHA are not all set — no check-run will be created',
-          )
-        }
-      }
+      const { GithubSummarySink } = loadSink()
       return new GithubSummarySink(
         file,
         options.title ?? 'vx run',
-        append,
+        (f, md) => appendFile(f, md, 'utf8'),
         (m) => ctx.warn(m),
-        check,
-        options.sizeOf ??
-          (options.append !== undefined
-            ? async () => 0
-            : (f: string) =>
-                stat(f).then(
-                  (st) => st.size,
-                  () => 0,
-                )),
+        (f) =>
+          stat(f).then(
+            (st) => st.size,
+            () => 0,
+          ),
       )
     },
   })

package/src/setup.ts

@@ -0,0 +1,208 @@
+// `vx setup github` / `vx setup gitlab`: what a CI machine needs before
+// `vx run` can run a sandboxed task. On Linux: bubblewrap, socat, strace
+// and ripgrep, bwrap allowed its user namespaces, and a proof it runs. On
+// macOS the sandbox is built in. A step of the job, before vx runs; the
+// verb is the plugin's, so a repo on neither CI has none.
+
+import { existsSync, readdirSync, readFileSync } from 'node:fs'
+import { mkdir, writeFile } from 'node:fs/promises'
+import os from 'node:os'
+import path from 'node:path'
+import { ui, UserError } from '@vzn/vx'
+
+const PACKAGES = ['bubblewrap', 'socat', 'strace', 'ripgrep']
+const BINARIES = ['bwrap', 'socat', 'strace', 'rg']
+
+/** A command's exit code; it writes to this process's stdout and stderr. */
+export type Shell = (argv: readonly string[]) => Promise<number>
+
+const shell: Shell = (argv) =>
+  Bun.spawn([...argv], { stdin: 'ignore', stdout: 'inherit', stderr: 'inherit' }).exited
+
+export interface SetupOptions {
+  readonly ci: 'github' | 'gitlab'
+  /** Where fetched packages are kept, for the job's cache to save and restore. */
+  readonly debs: string
+  readonly platform?: NodeJS.Platform
+  readonly root?: boolean
+  readonly sh?: Shell
+  readonly has?: (bin: string) => boolean
+  /** GitHub's step output file: `fetched=true` when packages were fetched. */
+  readonly output?: string | undefined
+  readonly print?: (line: string) => void
+  /** Whether the kernel lets a program make user namespaces only under an AppArmor profile. */
+  readonly restricted?: () => boolean
+}
+
+const userns = (): boolean => {
+  try {
+    return (
+      readFileSync('/proc/sys/kernel/apparmor_restrict_unprivileged_userns', 'utf8').trim() === '1'
+    )
+  } catch {
+    return false
+  }
+}
+
+export async function setup(o: SetupOptions): Promise<number> {
+  const print = o.print ?? ((l: string) => ui.say('info', l, 'out'))
+  const platform = o.platform ?? process.platform
+  if (platform === 'darwin') {
+    print('vx setup: macOS has its sandbox built in; nothing to set up')
+    return 0
+  }
+  if (platform !== 'linux') throw new UserError(`vx setup: ${platform} has no vx sandbox`)
+  const sh = o.sh ?? shell
+  const has = o.has ?? ((bin: string) => Bun.which(bin) !== null)
+  const sudo = (o.root ?? process.getuid?.() === 0) ? [] : ['sudo']
+  const run = async (argv: readonly string[]): Promise<void> => {
+    const code = await sh([...sudo, ...argv])
+    if (code !== 0) throw new UserError(`vx setup: \`${argv.join(' ')}\` exited ${code}`)
+  }
+  let fetched = false
+  const missing = BINARIES.filter((b) => !has(b))
+  const debs = readdir(o.debs).filter((f) => f.endsWith('.deb'))
+  // What the job's cache restored, else fetched: kept from an older
+  // image, they may not install, and a set fetched where the image had a
+  // package already holds no deb of it.
+  const kept =
+    missing.length > 0 &&
+    debs.length > 0 &&
+    has('dpkg') &&
+    (await sh([...sudo, 'dpkg', '-i', ...debs.map((f) => path.join(o.debs, f))])) === 0 &&
+    BINARIES.every((b) => has(b))
+  if (missing.length > 0 && !kept) {
+    if (has('apt-get')) {
+      await run(['rm', '-rf', o.debs])
+      // man-db re-indexes every page on each install: seconds for nothing.
+      await run(['rm', '-f', '/var/lib/man-db/auto-update'])
+      // Only the distribution's own index is needed: a third-party source
+      // (Chrome, Microsoft on GitHub's images) serving a stale index fails
+      // `apt-get update` before vx runs at all (2026-09-09).
+      if (existsSync('/etc/apt/sources.list.d/ubuntu.sources'))
+        await run([
+          'find',
+          '/etc/apt/sources.list.d',
+          '-type',
+          'f',
+          '!',
+          '-name',
+          'ubuntu.sources',
+          '-delete',
+        ])
+      await run(['apt-get', 'update'])
+      await mkdir(path.join(o.debs, 'partial'), { recursive: true })
+      await run([
+        'apt-get',
+        'install',
+        '-y',
+        '-o',
+        `Dir::Cache::Archives=${o.debs}`,
+        '-o',
+        'APT::Keep-Downloaded-Packages=true',
+        ...PACKAGES,
+      ])
+      await run(['rm', '-rf', path.join(o.debs, 'partial'), path.join(o.debs, 'lock')])
+      await run(['chown', '-R', os.userInfo().username, o.debs])
+      fetched = true
+    } else if (has('apk')) {
+      await run(['apk', 'add', '--no-cache', ...PACKAGES])
+    } else {
+      throw new UserError(
+        `vx setup: ${missing.join(', ')} missing and no apt-get or apk to install ${PACKAGES.join(' ')}`,
+      )
+    }
+  }
+  // Ubuntu 24+ lets a program make user namespaces only under an AppArmor
+  // profile granting `userns` (discourse.ubuntu.com/t/58007). Ubuntu 26
+  // ships bwrap-userns-restrict instead, which strips the capabilities of
+  // the namespace nested in bwrap's, where the sandbox applies seccomp:
+  // every sandboxed task failed "nested userns is capability-restricted"
+  // (2026-10-23). bwrap gets the plain profile in its place.
+  if ((o.restricted ?? userns)()) {
+    if (existsSync('/etc/apparmor.d/bwrap-userns-restrict')) {
+      await run(['apparmor_parser', '-R', '/etc/apparmor.d/bwrap-userns-restrict'])
+      await run(['rm', '/etc/apparmor.d/bwrap-userns-restrict'])
+    }
+    const profile = path.join(os.tmpdir(), `vx-bwrap-${process.pid}.apparmor`)
+    await writeFile(
+      profile,
+      'abi <abi/4.0>,\ninclude <tunables/global>\nprofile bwrap /usr/bin/bwrap flags=(unconfined) {\n  userns,\n}\n',
+    )
+    await run(['cp', profile, '/etc/apparmor.d/bwrap'])
+    await run(['apparmor_parser', '-r', '/etc/apparmor.d/bwrap'])
+  }
+  // GitLab keeps it in the checkout, where a root task's `**` keyed the
+  // debs: a job that had them missed every hit saved without them.
+  if (existsSync(o.debs)) await writeFile(path.join(o.debs, '.gitignore'), '*\n')
+  if (o.output !== undefined && o.output !== '')
+    await writeFile(o.output, `fetched=${fetched}\n`, { flag: 'a' })
+  // The proof: a sandbox that cannot start fails here, named, not as every
+  // sandboxed task's failure later.
+  const code = await sh([
+    'bwrap',
+    '--ro-bind',
+    '/',
+    '/',
+    '--proc',
+    '/proc',
+    '--dev',
+    '/dev',
+    '/bin/true',
+  ])
+  if (code !== 0)
+    throw new UserError(
+      `vx setup: bwrap cannot start a sandbox here (exit ${code}): the machine must allow user namespaces`,
+    )
+  print(`vx setup: the sandbox runs on this ${o.ci === 'github' ? 'runner' : 'job'}`)
+  return 0
+}
+
+function readdir(dir: string): string[] {
+  try {
+    return readdirSync(dir)
+  } catch {
+    return []
+  }
+}
+
+/**
+ * The key to save fetched packages under: this runner image's, after the
+ * `vx-setup-debs-<runner.os>-<runner.arch>-` a job restores by. Led by the
+ * image alone, no restore ever matched it and every worker fetched again
+ * (main, 2026-10-23: 6-55 s of each worker's start).
+ */
+export function debsKey(env: Record<string, string | undefined>): string {
+  return `vx-setup-debs-${env['RUNNER_OS'] ?? ''}-${env['RUNNER_ARCH'] ?? ''}-${env['ImageOS'] ?? ''}-${env['ImageVersion'] ?? ''}`
+}
+
+/** The `setup` verb of `github()` or `gitlab()`: `vx setup <ci> [--debs <dir>]`. */
+export async function runSetup(
+  ci: 'github' | 'gitlab',
+  argv: readonly string[],
+  defaultDebs: string,
+): Promise<number> {
+  const usage = `Usage: vx setup ${ci} [--debs <dir>]`
+  // Asked for, the usage is an answer: `vx setup --help` exited 1 (2026-10-26).
+  if (argv.includes('--help') || argv.includes('-h')) {
+    ui.say('info', usage, 'out')
+    return 0
+  }
+  // The bare usage said nothing of what was wrong with the line typed.
+  const wrong = (what: string): never => {
+    throw new UserError(`${what}\n${usage}`, 'VX_E_USAGE')
+  }
+  if (argv[0] === undefined) wrong(`missing the CI: vx setup ${ci}`)
+  if (argv[0] !== ci) wrong(`unknown CI: ${argv[0]} (this workspace sets up ${ci})`)
+  let debs = defaultDebs
+  for (let i = 1; i < argv.length; i++) {
+    if (argv[i] !== '--debs') wrong(`unknown argument: ${argv[i]}`)
+    if (argv[i + 1] === undefined) wrong('--debs needs a directory')
+    debs = path.resolve(argv[++i]!)
+  }
+  await mkdir(debs, { recursive: true })
+  const output = ci === 'github' ? process.env['GITHUB_OUTPUT'] : undefined
+  if (output !== undefined && output !== '')
+    await writeFile(output, `key=${debsKey(process.env)}\n`, { flag: 'a' })
+  return setup({ ci, debs, output })
+}

package/src/sink.ts

@@ -1,11 +1,8 @@
 // The job summary sink: loaded only on a runner that sets a summary file,
 // so a run elsewhere pays no module of it.
 import { type RunSummaryRecord, type TelemetrySink } from '@vzn/vx'
-import { buildCheckRunPayload, postCheckRun, type CheckRunEnv, type FetchFn } from './checks.js'
 import { clampJobSummary, MAX_JOB_SUMMARY_BYTES, renderJobSummary } from './summary.js'
 
-export { resolveCheckRunEnv } from './checks.js'
-
 export class GithubSummarySink implements TelemetrySink {
   readonly name = 'github-job-summary'
   /** Summary-only: no streaming records at all — zero per-event cost. */
@@ -17,7 +14,6 @@ export class GithubSummarySink implements TelemetrySink {
     private readonly title: string,
     private readonly append: (file: string, markdown: string) => Promise<void>,
     private readonly warn: (m: string) => void,
-    private readonly check?: { env: CheckRunEnv; name: string; fetchFn: FetchFn },
     /** Bytes the summary file already holds. */
     private readonly sizeOf: (file: string) => Promise<number> = async () => 0,
   ) {}
@@ -27,20 +23,15 @@ export class GithubSummarySink implements TelemetrySink {
     this.summary = summary
   }
 
-  async flush(signal?: AbortSignal): Promise<void> {
+  async flush(): Promise<void> {
     if (this.summary === undefined) return
     const markdown = renderJobSummary(this.summary, this.title)
-    // The two artifacts are INDEPENDENT, and the plugin already says so in
-    // one direction: it declines the check-run without a token and still
-    // writes the summary. The reverse has to hold, or a full disk on the
-    // runner costs the PR its check — the more visible of the two. Reported,
-    // not thrown: a telemetry sink may never break a run.
+    // Reported, not thrown: a telemetry sink may never break a run.
     try {
       // Clamped: past GitHub's 1 MiB cap the runner drops the summary whole,
       // so a bounded page beats none. The cap covers the step's whole file,
       // and a page clamped to 1 MiB after another writer's output lost both
-      // (F-42): the room is what is left. The check-run payload has its own,
-      // smaller cap and is clamped where it is built.
+      // (F-42): the room is what is left.
       const used = await this.sizeOf(this.file)
       // After another writer the page starts on its own line: one that left
       // no final newline ran vx's heading into its paragraph (F-51).
@@ -48,29 +39,15 @@ export class GithubSummarySink implements TelemetrySink {
       const page = clampJobSummary(markdown, MAX_JOB_SUMMARY_BYTES - used - lead.length)
       if (page === '') {
         this.warn(
-          `vx-ci: ${this.file} already holds ${used} bytes of GitHub's 1 MiB job summary cap — no room for vx's page`,
+          `[vx] vx-ci: ${this.file} already holds ${used} bytes of GitHub's 1 MiB job summary cap — no room for vx's page`,
         )
       } else {
         await this.append(this.file, lead + page)
       }
     } catch (err) {
       this.warn(
-        `vx-ci: could not write the job summary to ${this.file}: ${err instanceof Error ? err.message : String(err)}`,
+        `[vx] vx-ci: could not write the job summary to ${this.file}: ${err instanceof Error ? err.message : String(err)}`,
       )
     }
-    if (this.check !== undefined) {
-      await postCheckRun({
-        env: this.check.env,
-        payload: buildCheckRunPayload({
-          summary: this.summary,
-          markdown,
-          name: this.check.name,
-          sha: this.check.env.sha,
-        }),
-        fetchFn: this.check.fetchFn,
-        warn: this.warn,
-        ...(signal === undefined ? {} : { signal }),
-      })
-    }
   }
 }

package/src/summary.ts

@@ -21,6 +21,11 @@ const STATUS_LABEL: Record<string, string> = {
 // Rounded once, then split: rounding the remainder after flooring the
 // minutes printed 119.7 s as `1m 60s`. The tier is chosen by the rounded
 // value: 59.96 s printed `60.0s` and 999.6 ms `1000ms` (F-51).
+/** Bytes as gigabytes, one decimal. */
+function gb(bytes: number): string {
+  return (bytes / 1e9).toFixed(1)
+}
+
 function fmtMs(ms: number): string {
   if (Math.round(ms) < 1000) return `${Math.round(ms)}ms`
   if (Math.round(ms / 100) < 600) return `${(ms / 1000).toFixed(1)}s`
@@ -29,12 +34,31 @@ function fmtMs(ms: number): string {
 }
 
 function statusLabel(t: TaskTelemetry): string {
+  // A carried server ran inside each dependant, on its worker: its time is
+  // theirs, and a `ran 0ms` row read as a run that did nothing (2026-10-23).
+  if (t.carried === true) return '🔗 served'
   // A hit that found its outputs in place restored nothing: up to date,
-  // whichever layer answered, as vx's own summary says it.
+  // as vx's own summary says it (a remote hit always restored).
   if (isCacheHit(t.status) && t.restored !== true) return '✔️ up-to-date'
   return STATUS_LABEL[t.status] ?? t.status
 }
 
+/** Rows by status label, in this order; any other after them. */
+const ORDER = [
+  '❌ failed',
+  '🛑 aborted',
+  '✅ ran',
+  '🔗 served',
+  '⚡ restored',
+  '☁️ restored remote',
+  '✔️ up-to-date',
+  '⏭️ skipped',
+]
+const rank = (t: TaskTelemetry): number => {
+  const i = ORDER.indexOf(statusLabel(t))
+  return i === -1 ? ORDER.length : i
+}
+
 /** `(3 up-to-date, 2 restored)`, with the remote share when any came from there. */
 function hitSplit(s: RunSummaryRecord): string {
   const restored = s.restoredLocalCount + s.restoredRemoteCount
@@ -63,7 +87,7 @@ export function clampJobSummary(markdown: string, room = MAX_JOB_SUMMARY_BYTES):
 }
 
 /** Cuts `text` to `maxBytes` of UTF-8, `suffix` included, never splitting a character. */
-export function truncateUtf8(text: string, maxBytes: number, suffix: string): string {
+function truncateUtf8(text: string, maxBytes: number, suffix: string): string {
   // The cap is BYTES, and the page is not ASCII: every status label is an
   // emoji (4 bytes, 2 UTF-16 units) and every separator a `·` or a `—`
   // (2 and 3 bytes, 1 unit). Measured in `.length`, a clamped page of those
@@ -94,10 +118,11 @@ function escapeMarkdownCell(value: string): string {
 
 /**
  * A task id as inline markdown: `a#*x*` rendered as `a#` and an italic
- * `x` (item 1058). Table cells escape their pipes on top of this.
+ * `x` (item 1058), `a#~x~` struck through and `&lt;` as `<`. Table cells
+ * escape their pipes on top of this.
  */
 function escapeInline(s: string): string {
-  return s.replace(/[\\`*_[\]<>]/g, '\\$&')
+  return s.replace(/[\\`*_[\]<>~&]/g, '\\$&')
 }
 
 /**
@@ -123,8 +148,9 @@ export function renderJobSummary(summary: RunSummaryRecord, title = 'vx run'): s
   const lines: string[] = []
   lines.push(`## ${verdict} ${title}`)
   lines.push('')
+  // A carried server ran inside its dependants, on their worker.
   const executed = summary.tasks.filter(
-    (t) => t.status === 'success' || t.status === 'failed',
+    (t) => (t.status === 'success' || t.status === 'failed') && t.carried !== true,
   ).length
   const stats = [
     `**${summary.taskCount}** task${summary.taskCount === 1 ? '' : 's'}`,
@@ -133,7 +159,10 @@ export function renderJobSummary(summary: RunSummaryRecord, title = 'vx run'): s
       (summary.hitCount > 0 ? ` ${hitSplit(summary)}` : ''),
     ...(summary.failedCount > 0 ? [`**${summary.failedCount}** failed`] : []),
     ...(summary.abortedCount > 0 ? [`**${summary.abortedCount}** aborted`] : []),
-    fmtMs(summary.totalDurationMs),
+    // The run played perfectly on what each task took, beside the real time (2026-10-23).
+    summary.idealMs === undefined
+      ? fmtMs(summary.totalDurationMs)
+      : `${fmtMs(summary.totalDurationMs)} (ideal ${fmtMs(summary.idealMs)})`,
   ]
   lines.push(stats.join(' · '))
   lines.push('')
@@ -166,14 +195,26 @@ export function renderJobSummary(summary: RunSummaryRecord, title = 'vx run'): s
     lines.push('')
   }
 
+  if (summary.machines !== undefined && summary.machines.length > 0) {
+    lines.push(...renderWorkers(summary.machines, summary.tasks), '')
+  }
+
   const header = ['Task', 'Status', 'Duration']
   lines.push(`| ${header.join(' | ')} |`)
   lines.push(`|${header.map(() => ' --- ').join('|')}|`)
-  // Failures first (the eye lands on the table's top rows), then execution
-  // order as delivered.
-  const ordered = [...failed, ...summary.tasks.filter((t) => t.status !== 'failed')]
+  // By status, failures first (the eye lands on the table's top rows),
+  // then the longest first (2026-10-23).
+  const ordered = [...summary.tasks].sort(
+    (a, b) =>
+      rank(a) - rank(b) ||
+      (b.carried === true ? 0 : b.durationMs) - (a.carried === true ? 0 : a.durationMs),
+  )
   for (const t of ordered) {
-    const cells = [escapeMarkdownCell(escapeInline(t.taskId)), statusLabel(t), fmtMs(t.durationMs)]
+    const cells = [
+      escapeMarkdownCell(escapeInline(t.taskId)),
+      statusLabel(t),
+      t.carried === true ? '' : fmtMs(t.durationMs),
+    ]
     lines.push(`| ${cells.join(' | ')} |`)
   }
   lines.push('')
@@ -189,3 +230,81 @@ export function renderJobSummary(summary: RunSummaryRecord, title = 'vx run'): s
   lines.push('')
   return lines.join('\n')
 }
+
+// "13 (1 failed)" read as 13 run in all, of 14 (2026-10-23).
+const tasksCell = (ok: number, failed: number): string =>
+  failed > 0 ? `${ok} ok, ${failed} failed` : `${ok}`
+
+const pct = (x: number): string => `${Math.round(x * 100)}%`
+
+/**
+ * The workers an executor ran the run on (vx-dte's): the cores its tasks
+ * booked beside the cores they used, each averaged over the time the
+ * worker was online, so an idle or overfilled one shows on the page
+ * (2026-10-23). "4.0 of 4" read as a peak; it is that average (M:
+ * "is this an avg booking?").
+ */
+function renderWorkers(
+  machines: NonNullable<RunSummaryRecord['machines']>,
+  tasks: RunSummaryRecord['tasks'],
+): string[] {
+  const lines = [
+    '### Workers',
+    '',
+    '| Worker | Status | Started at | Total | Warm-up | Online after warm-up | Idle while online | Tasks | Booked cores, avg | Used cores, avg | Peak RAM | Used of all cores |',
+    '| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |',
+  ]
+  let coreMs = 0
+  let cpuMs = 0
+  // Over the workers that report a booking only: an executor may report
+  // none, and counting that as 0 read as tasks booking nothing.
+  let bookedCoreMs = 0
+  let bookedMs = 0
+  for (const m of machines) {
+    coreMs += m.cores * m.onlineMs
+    cpuMs += m.cpuAvg * m.onlineMs
+    if (m.bookedAvg !== undefined) {
+      bookedCoreMs += m.cores * m.onlineMs
+      bookedMs += m.bookedAvg * m.onlineMs
+    }
+    lines.push(
+      `| ${[
+        escapeMarkdownCell(escapeInline(m.name)),
+        escapeMarkdownCell(m.status),
+        m.startMs === undefined ? '' : fmtMs(m.startMs),
+        fmtMs((m.warmUpMs ?? 0) + m.onlineMs),
+        m.warmUpMs === undefined ? '' : fmtMs(m.warmUpMs),
+        fmtMs(m.onlineMs),
+        fmtMs(Math.max(0, m.onlineMs - m.busyMs)),
+        tasksCell(m.done, m.failed),
+        m.bookedAvg === undefined ? '' : `${m.bookedAvg.toFixed(1)} of ${m.cores}`,
+        `${m.cpuAvg.toFixed(1)} of ${m.cores}`,
+        `${gb(m.memoryPeakBytes)} of ${gb(m.memoryBytes)} GB`,
+        pct(m.utilization),
+      ].join(' | ')} |`,
+    )
+  }
+  // Nothing runs on a distributed run's own machine (2026-10-23):
+  // a task that did is named, a bug to see. A carried server ran inside its
+  // dependants, on their worker.
+  const ran = tasks.filter(
+    (t) => (t.status === 'success' || t.status === 'failed') && t.carried !== true,
+  )
+  const here = ran.filter((t) => t.where === undefined)
+  if (here.length > 0) {
+    const failed = here.filter((t) => t.status === 'failed').length
+    lines.push(
+      `| this machine | ok |  |  |  |  |  | ${tasksCell(here.length - failed, failed)} |  |  |  |  |`,
+      '',
+      `${ran.length} executed: ${ran.length - here.length} on workers, ${here.length} on this machine: ${here.map((t) => escapeMarkdownCell(escapeInline(t.taskId))).join(', ')}.`,
+    )
+  }
+  if (coreMs > 0)
+    lines.push(
+      '',
+      bookedCoreMs > 0
+        ? `Over their online time, tasks booked ${pct(bookedMs / bookedCoreMs)} of the workers' cores and used ${pct(cpuMs / coreMs)}.`
+        : `Over their online time, tasks used ${pct(cpuMs / coreMs)} of the workers' cores.`,
+    )
+  return lines
+}