@vzn/vx 0.0.645 → 0.0.648

package/src/orchestrator/task-artifacts.ts

@@ -0,0 +1,206 @@
+// Task entries by key for an executor that runs a task on another machine
+// (`ExecutorContext.artifacts`, `CommandContext.artifacts`): the machine
+// that ran it saves its outputs and output under the key the order named,
+// and the one that needs them restores them, through the workspace's own
+// cache (design packages/vx/docs/design/dte-2026-10.md, "Files").
+
+import {
+  type CacheLayer,
+  type ResolvedRemote,
+  resolveOutputTree,
+  resolveWorkspaceOutputTree,
+  sayRemoteFault,
+} from '../cache/index.js'
+import type { CapturedChunk } from '../exec/index.js'
+import { secretMask, thrownMessage } from '../util/index.js'
+import { decodeOutputLog, encodeOutputLog, maskedOutputLog } from './output-log.js'
+
+/** The task a `TaskArtifacts` call names: where its outputs are and what ran. */
+export interface ArtifactTask {
+  /** `project#task`. */
+  readonly id: string
+  /** Absolute. */
+  readonly projectDir: string
+  readonly command: string
+  /** Its `cache.outputs`: project-relative `files`, root-relative `workspaceFiles`. */
+  readonly outputs: {
+    readonly files: readonly string[]
+    readonly workspaceFiles: readonly string[]
+  }
+  /** The projects inside `projectDir` (absolute), whose files are not its outputs. */
+  readonly nestedProjectDirs?: readonly string[]
+  /**
+   * Files under its outputs it found and left as they were (absolute): an
+   * upstream's, which an additive task builds on, not its entry's.
+   */
+  readonly others?: ReadonlySet<string>
+}
+
+/** What a task's run left besides its files: its output, and its time and usage. */
+export interface ArtifactRun {
+  /** Both streams in the order they were written, as a `BoundedCapture` keeps them. */
+  readonly output: readonly CapturedChunk[]
+  readonly durationMs: number
+  readonly cpuMs?: number
+  readonly peakRssBytes?: number
+  /** Its environment: a secret value in it is masked out of the stored output. */
+  readonly env?: Readonly<Record<string, string | undefined>>
+  /** Its `exec.env.secret`: names in `env` whose values are masked whatever the name. */
+  readonly secret?: readonly string[]
+  /** No remote held the key when the run asked: its upload asks none first. */
+  readonly absent?: boolean
+}
+
+export interface TaskArtifacts {
+  /**
+   * Keeps the files `task`'s outputs match, and its output, as entry
+   * `key`: here, and on each remote the workspace writes. Resolves once
+   * every upload has settled; a remote that fails degrades as a run's
+   * upload does.
+   */
+  save(key: string, task: ArtifactTask, run: ArtifactRun): Promise<void>
+  /**
+   * Lays entry `key`'s files into the workspace, from the local store or
+   * else the first remote holding it, and resolves its output, both streams
+   * in the order written; null when
+   * none holds it. A key restored here and then saved is not uploaded
+   * again.
+   */
+  restore(key: string, task: ArtifactTask): Promise<CapturedChunk[] | null>
+  /**
+   * Entry `key`'s output alone, laying no file; null when no cache holds
+   * it. An `exec.remote: 'only'` task's files stay off this disk.
+   */
+  output(key: string): Promise<CapturedChunk[] | null>
+  /**
+   * True once a remote the run reads holds entry `key`, this machine's
+   * entry uploaded to those it writes when none does: another machine of
+   * the run reads the remotes alone. False when none holds it and none took it.
+   */
+  share(key: string): Promise<boolean>
+  /**
+   * This machine's entry `key` uploaded over each written remote's copy,
+   * which another machine of the run found corrupt. True when one took it.
+   */
+  resend(key: string): Promise<boolean>
+  /**
+   * Whether a remote the workspace writes took entry `key` when `save`
+   * uploaded it; undefined when it writes none. Another machine of the
+   * run reads the remotes alone, so false there means only this one has it.
+   */
+  uploaded?(key: string): Promise<boolean | undefined>
+}
+
+export function taskArtifacts(cache: CacheLayer, workspaceRoot: string): TaskArtifacts {
+  return {
+    async save(key, task, run) {
+      const [tree, wsTree] = await Promise.all([
+        resolveOutputTree({
+          projectDir: task.projectDir,
+          outputs: task.outputs.files,
+          nestedProjectDirs: [...(task.nestedProjectDirs ?? [])],
+        }),
+        resolveWorkspaceOutputTree({ workspaceRoot, outputs: task.outputs.workspaceFiles }),
+      ])
+      const mine = (f: string) => task.others?.has(f) !== true
+      const files = tree.files.filter(mine)
+      const ws = wsTree.files.filter(mine)
+      const mask = secretMask([process.env, run.env ?? {}], run.secret)
+      const log = mask === null ? encodeOutputLog(run.output) : maskedOutputLog(run.output, mask)
+      await cache.save({
+        hash: key,
+        projectDir: task.projectDir,
+        outputFiles: files,
+        ...(tree.emptyDirs.length > 0 ? { outputDirs: tree.emptyDirs } : {}),
+        workspaceRoot,
+        ...(ws.length > 0 ? { workspaceOutputFiles: ws } : {}),
+        ...(wsTree.emptyDirs.length > 0 ? { workspaceOutputDirs: wsTree.emptyDirs } : {}),
+        ...(run.absent === true ? { absent: true } : {}),
+        entry: {
+          taskId: task.id,
+          command: mask?.mask(task.command) ?? task.command,
+          durationMs: run.durationMs,
+          stdout: log,
+          ...(run.cpuMs !== undefined ? { cpuMs: run.cpuMs } : {}),
+          ...(run.peakRssBytes !== undefined ? { peakRssBytes: run.peakRssBytes } : {}),
+        },
+      })
+      await cache.drainUploads?.()
+    },
+
+    async restore(key, task) {
+      const entry = await (cache.getSaved ? cache.getSaved(key) : cache.get(key))
+      if (entry === null) return null
+      await cache.restoreOutputs(key, task.projectDir, workspaceRoot, task.outputs)
+      return decodeOutputLog(entry.stdout)
+    },
+
+    async output(key) {
+      const entry = await (cache.getSaved ? cache.getSaved(key) : cache.get(key))
+      return entry === null ? null : decodeOutputLog(entry.stdout)
+    },
+
+    share: (key) => cache.share?.(key) ?? Promise.resolve(false),
+    resend: (key) => cache.resend?.(key) ?? Promise.resolve(false),
+    uploaded: (key) => cache.uploaded?.(key) ?? Promise.resolve(undefined),
+  }
+}
+
+/**
+ * What a run's cache is read under, for a machine that runs its tasks
+ * (`ExecutorContext.cacheFacts`, `CommandContext.artifactsFor`): the
+ * refs the run worked out, so that machine reads as the run would, and
+ * the access each remote lent, by plugin.
+ */
+export interface CacheFacts {
+  /** `CacheContext.refs`. */
+  readonly refs: readonly string[]
+  /** Plugin name → the token its remote's `lend` gave. */
+  readonly lent: Readonly<Record<string, string>>
+  /** Epoch ms: the first lent token's end, before which to ask again. */
+  readonly expiresAt?: number
+}
+
+/** The run's `CacheFacts`: each readable remote's `lend`, asked now; one that throws lends nothing, said. */
+export async function cacheFacts(
+  remotes: readonly ResolvedRemote[],
+  refs: readonly string[],
+): Promise<CacheFacts> {
+  const lent: Record<string, string> = {}
+  let expiresAt: number | undefined
+  await Promise.all(
+    remotes.map(async (r) => {
+      if (r.plugin === undefined || r.remote.lend === undefined || !r.read) return
+      // Through a promise, and checked: a plugin's synchronous throw skipped
+      // the catch and rejected every remote's answer, and a `null` or a
+      // numeric token met `.token` as a TypeError.
+      const got = await Promise.resolve()
+        .then(() => r.remote.lend!())
+        .then((answer: unknown) => {
+          if (answer === undefined) return undefined
+          if (typeof answer !== 'object' || answer === null)
+            throw new Error(
+              `it answered ${answer === null ? 'null' : typeof answer}, not { token, expiresAt? }`,
+            )
+          const { token, expiresAt: ends } = answer as { token?: unknown; expiresAt?: unknown }
+          if (typeof token !== 'string') throw new Error('it answered a token that is not a string')
+          if (ends !== undefined && !(typeof ends === 'number' && Number.isFinite(ends)))
+            throw new Error('it answered an expiresAt that is not a time in ms')
+          return { token, ...(ends === undefined ? {} : { expiresAt: ends }) }
+        })
+        .catch((err: unknown) => {
+          // Said: unsaid, the run's workers went without this remote and no line said why.
+          const message = thrownMessage(err)
+          sayRemoteFault(
+            r,
+            new Error(`lend of ${r.plugin}'s access failed: ${message}`, { cause: err }),
+          )
+          return undefined
+        })
+      if (got === undefined) return
+      lent[r.plugin] = got.token
+      if (got.expiresAt !== undefined) expiresAt = Math.min(expiresAt ?? Infinity, got.expiresAt)
+    }),
+  )
+  return { refs, lent, ...(expiresAt === undefined ? {} : { expiresAt }) }
+}

package/src/orchestrator/task-hash.ts

@@ -6,6 +6,7 @@ import {
   ABSENT_INPUT,
   absentOr,
   addedInput,
+  behindLink,
   filesToken,
   foldHead,
   type InputListing,
@@ -21,7 +22,16 @@ import {
 } from '../cache/index.js'
 import type { InputFile, TaskInputs } from '../exec/index.js'
 import { isGroupTask, type TaskNode, type TaskOutcome } from '../graph/index.js'
-import { isUserError, relPosix, secretMask, span, UserError, xxh3hex } from '../util/index.js'
+import { GROUP_VIA } from '../history/index.js'
+import {
+  isUserError,
+  keysSorted,
+  relPosix,
+  secretMask,
+  span,
+  UserError,
+  xxh3hex,
+} from '../util/index.js'
 import { expandGroupUpstream, filterUpstreamHashes } from './upstream.js'
 
 /**
@@ -46,6 +56,11 @@ export interface HashCache {
   projectFiles: ProjectFilesCache
   /** Each task's last key by its probe, across runs (the local cache's `FoldMemo`). */
   folds?: FoldMemo | undefined
+  /**
+   * The token of the remembered graph the run's nodes are (graph-memo.ts),
+   * while no plugin or flag has edited them since.
+   */
+  graph?: string | undefined
 }
 
 export function createHashCache(folds?: FoldMemo): HashCache {
@@ -131,15 +146,15 @@ const FOLD_MEMO_VERSION = 'fold-memo-v1'
 /**
  * A task that runs a command and declares no `inputs`: nothing says what
  * it read, so no key can stand for its outputs, and a key that folds it
- * would replay a stale entry (owner, 2026-10-16).
+ * would replay a stale entry (2026-10-16).
  */
 export function isKeyless(task: TaskConfig): boolean {
   return task.exec !== undefined && task.inputs === undefined
 }
 
 /**
- * Drawn once per process, so no run derives another run's keyless keys;
- * on first use, as the browser playground loads this module with no `crypto`.
+ * Drawn once per process, on first use, so no run derives another run's
+ * keyless keys.
  */
 let keylessSalt: string | undefined
 
@@ -159,6 +174,12 @@ export interface InputFact {
   path: string
   digest: string
   since: number
+  /**
+   * For a link, the content behind it (`behindLink`), which the key folds
+   * after the link's own target string. An edit there leaves the link
+   * untouched, so the re-check compares this rather than the link's ctime.
+   */
+  behind?: string
 }
 
 /**
@@ -180,11 +201,21 @@ export async function describeTaskInputs(args: ComputeHashArgs): Promise<{
 }> {
   const hashedAt = Date.now()
   const { input, listings } = await resolveKeyInput(args)
-  const hash = await args.cache.key(input)
   const sorted = [...input.inputFiles].sort()
   const digests = await Promise.all(
     sorted.map((f) => input.fileHashes?.get(f) ?? args.cache.hashFile(f).catch(absentOr)),
   )
+  // Learned BEFORE the key folds it: an edit in between then reads as a
+  // move at the re-check (a withheld save), never as content the key
+  // did not fold matching it (a stale entry).
+  const hashFile = (f: string): Promise<string> => args.cache.hashFile(f)
+  const behind = new Map<string, string>()
+  await Promise.all(
+    sorted.map(async (f, i) => {
+      if (digests[i]!.startsWith('120000:')) behind.set(f, await behindLink(f, hashFile))
+    }),
+  )
+  const hash = await args.cache.key(input)
   // A file gone since the enumeration is no input: the task will not read it.
   const files: InputFile[] = sorted.flatMap((f, i) =>
     digests[i] === ABSENT_INPUT
@@ -192,11 +223,16 @@ export async function describeTaskInputs(args: ComputeHashArgs): Promise<{
       : [{ path: relPosix(input.workspaceRoot, f), digest: digests[i]! }],
   )
   const indexedAt = args.gitFilesCache?.enumeratedAtMs ?? 0
-  const facts: InputFact[] = sorted.map((f, i) => ({
-    path: f,
-    digest: digests[i]!,
-    since: input.fileHashes?.has(f) === true ? indexedAt : hashedAt,
-  }))
+  const facts: InputFact[] = sorted.map((f, i) => {
+    const fact: InputFact = {
+      path: f,
+      digest: digests[i]!,
+      since: input.fileHashes?.has(f) === true ? indexedAt : hashedAt,
+    }
+    const linked = behind.get(f)
+    if (linked !== undefined) fact.behind = linked
+    return fact
+  })
   // Groups expanded: this list describes the INPUT ROOT, not the key, and a
   // group produces nothing of its own (see `CacheKeyInput.upstreamGraft`).
   // Sorted by hash so the list — and any action digest derived from it — is
@@ -260,7 +296,8 @@ export async function describeTaskInputs(args: ComputeHashArgs): Promise<{
  * the command by content too, when it answers true for that file and its
  * ctime: the task says the same bytes are its own identical rewrite
  * (tsdown's package.json), not an edit undone, unless another command that
- * may write the file ran until then (command-windows.ts).
+ * may write the file ran until then (command-windows.ts). A link's content
+ * behind it (`InputFact.behind`) is followed again and compared.
  */
 export async function movedInput(
   facts: readonly InputFact[],
@@ -294,9 +331,25 @@ export async function movedInput(
     const now = await cache.hashFile(f.path).catch(() => undefined)
     if (now !== f.digest) return f.path
   }
+  // What a link points to changes without touching the link: each is
+  // followed again (links are rare, so a task without one pays nothing).
+  const hashFile = (file: string): Promise<string> => cache.hashFile(file)
+  for (const f of facts) {
+    if (f.behind !== undefined && (await behindLink(f.path, hashFile)) !== f.behind) return f.path
+  }
   return undefined
 }
 
+/** A task's `filesToken`, as its key's fold memo probe takes it. */
+export function taskFilesToken(
+  args: Pick<
+    ComputeHashArgs,
+    'node' | 'workspaceRoot' | 'nestedProjectDirs' | 'gitFilesCache' | 'hashCache'
+  >,
+): string | undefined {
+  return filesToken(inputsArgs({ ...args, upstream: [], cache: undefined as never }))
+}
+
 /** What `resolveInputs` is asked for a task's key. */
 function inputsArgs(args: ComputeHashArgs): ResolveInputsArgs {
   const cfg = args.node.config
@@ -348,6 +401,24 @@ async function resolveKeyInput(
   const upstreamHashes = upstreamPairs.map(([, hash]) => hash)
   // hash → upstream task id, for capture-row naming only (not folded).
   const upstreamIds = new Map(upstreamPairs.map(([id, hash]) => [hash, id]))
+  // A group records no run and keeps no fingerprints, so `vx why` could not
+  // see past one: each folded group's members are captured as rows of their
+  // own, named through it. Rows only, never folded: the group's hash already
+  // folds theirs.
+  if (args.captureInto !== undefined) {
+    const folded = new Set(upstreamPairs.map(([id]) => id))
+    for (const g of args.upstream) {
+      if (g.groupUpstream === undefined || !folded.has(g.node.id)) continue
+      for (const m of expandGroupUpstream(g.groupUpstream)) {
+        if (m.hash === undefined) continue
+        args.captureInto.push({
+          kind: 'upstream',
+          name: `${g.node.id}${GROUP_VIA}${m.node.id}`,
+          hash: m.hash,
+        })
+      }
+    }
+  }
   // The DEPENDENCY closure, groups expanded — for the executor's input root.
   // Deliberately NOT the filtered set above: `inputs.tasks` says which
   // upstream KEYS this task's key folds, and what a task may READ is
@@ -393,6 +464,7 @@ async function resolveKeyInput(
     forwardArgs: effectiveForwardArgs,
     ...(fileHashes !== undefined ? { fileHashes } : {}),
     ...(args.node.keyParts !== undefined ? { pluginParts: args.node.keyParts } : {}),
+    ...(args.node.platform !== undefined ? { platform: args.node.platform } : {}),
     ...(args.captureInto !== undefined ? { captureInto: args.captureInto } : {}),
   }
   return { input, listings: resolved.listings }
@@ -411,7 +483,7 @@ async function resolveKeyInput(
  * each task's config object is created once per run, so a hit there
  * skips the JSON.stringify + xxh3 entirely.
  */
-function hashTaskConfig(cfg: TaskConfig, hashCache?: HashCache): string {
+export function hashTaskConfig(cfg: TaskConfig, hashCache?: HashCache): string {
   if (hashCache) {
     const cached = hashCache.taskConfig.get(cfg)
     if (cached !== undefined) return cached
@@ -444,9 +516,12 @@ function hashTaskConfig(cfg: TaskConfig, hashCache?: HashCache): string {
  * would bump CACHE_VERSION.
  */
 function hashableConfig(cfg: TaskConfig): unknown {
-  if (cfg.exec?.remote === undefined) return cfg
+  // Keys sorted: moving `cache` above `exec`, or a `define` in another
+  // order, missed every key of the task, and a `project` or `graph` plugin
+  // writes a config the lock never sorted (2026-10-25).
+  if (cfg.exec?.remote === undefined) return keysSorted(cfg)
   const { remote: _remote, ...execRest } = cfg.exec
-  return { ...cfg, exec: execRest }
+  return keysSorted({ ...cfg, exec: execRest })
 }
 
 /**

package/src/orchestrator/task-log-buffer.ts

@@ -105,7 +105,7 @@ function budgetCost(chars: number, chunkCount: number): number {
 
 /**
  * Bounded per-run capture. `append` keeps a chunk LIST + running char count per
- * task, evicting whole chunks from the head past `TASK_LOG_TAIL_CHARS` — no
+ * task, evicting from the head past `TASK_LOG_TAIL_CHARS` — no
  * string concatenation until `drain`, so a cache-hit replay (one big chunk) is
  * one array push, zero copies. `finish` decides retention; `drain` emits the
  * bundle, failures first.
@@ -115,6 +115,16 @@ export class TaskLogBuffer {
   private readonly retained = new Map<string, Retained>()
   private retainedChars = 0
   private seq = 0
+  /**
+   * Retained entries in eviction order, kept as they arrive: successes are
+   * stubbed from `successHead` on (oldest first), failures from the end
+   * (newest first). An entry since stubbed, taken or replaced is skipped
+   * where it lies. A sort of every entry per finish made a run past the
+   * budget quadratic: 40,000 tasks took 17 s in a sink's `onRecord`.
+   */
+  private readonly successes: Retained[] = []
+  private successHead = 0
+  private failures: Retained[] = []
 
   append(taskId: string, chunk: string): void {
     if (chunk.length === 0) return
@@ -126,24 +136,27 @@ export class TaskLogBuffer {
     acc.chunks.push(chunk)
     acc.chars += chunk.length
     acc.charsFull += chunk.length
-    // Evict whole chunks from the head until under the per-task tail cap. A
-    // single over-cap chunk is sliced to its tail (the only place we copy).
-    while (acc.chars > TASK_LOG_TAIL_CHARS && acc.chunks.length > 1) {
-      const dropped = acc.chunks.shift()!
-      acc.chars -= dropped.length
-      acc.truncatedHeadChars += dropped.length
-    }
-    if (acc.chars > TASK_LOG_TAIL_CHARS && acc.chunks.length === 1) {
-      const only = acc.chunks[0]!
-      let start = only.length - TASK_LOG_TAIL_CHARS
+    // Evict whole chunks from the head until under the per-task tail cap;
+    // the one that straddles the cap is sliced to what still fits (the only
+    // place we copy). Dropped whole, a 128 KiB chunk and a 7-char one after
+    // it kept the 7 chars alone.
+    while (acc.chars > TASK_LOG_TAIL_CHARS) {
+      const head = acc.chunks[0]!
+      const excess = acc.chars - TASK_LOG_TAIL_CHARS
+      if (head.length <= excess) {
+        acc.chunks.shift()
+        acc.chars -= head.length
+        acc.truncatedHeadChars += head.length
+        continue
+      }
+      let start = excess
       // A cut between a surrogate pair would open the tail on a lone low
       // surrogate, which a sink's UTF-8 encode turns into U+FFFD.
-      const first = only.charCodeAt(start)
+      const first = head.charCodeAt(start)
       if (first >= 0xdc00 && first <= 0xdfff) start++
-      const keep = only.slice(start)
-      acc.truncatedHeadChars += only.length - keep.length
-      acc.chunks[0] = keep
-      acc.chars = keep.length
+      acc.chunks[0] = head.slice(start)
+      acc.chars -= start
+      acc.truncatedHeadChars += start
     }
   }
 
@@ -180,9 +193,32 @@ export class TaskLogBuffer {
     if (prior !== undefined) this.retainedChars -= budgetCost(prior.chars, prior.chunks.length)
     this.retained.set(taskId, entry)
     this.retainedChars += budgetCost(entry.chars, entry.chunks.length)
+    ;(status === 'success' ? this.successes : this.failures).push(entry)
+    this.compact()
     this.evictToBudget()
   }
 
+  /** Whether `e` may still be stubbed: retained as it is, content and all. */
+  private evictable(e: Retained): boolean {
+    return e.chars > 0 && this.retained.get(e.taskId) === e
+  }
+
+  /**
+   * Drop what eviction would only skip, once the queues hold twice what is
+   * retained: a sink that takes every entry (`takeEntry`) never evicts, and
+   * its queues would grow by a task each. Amortized constant per finish.
+   */
+  private compact(): void {
+    const room = 2 * this.retained.size + 1024
+    if (this.successes.length - this.successHead > room || this.successHead > room) {
+      const live = this.successes.slice(this.successHead).filter((e) => this.evictable(e))
+      this.successes.length = 0
+      this.successes.push(...live)
+      this.successHead = 0
+    }
+    if (this.failures.length > room) this.failures = this.failures.filter((e) => this.evictable(e))
+  }
+
   /**
    * Take ONE finished task's retained tail as a wire entry, removing it from
    * the buffer (so a later `drain` won't re-ship it). Used by per-task
@@ -249,7 +285,7 @@ export class TaskLogBuffer {
   /**
    * Evict until `retainedChars <= RUN_LOG_BUDGET_CHARS`. Successes go first
    * (oldest by seq); only when failures ALONE still exceed the budget do the
-   * oldest failures go — a failure is never dropped to keep a success.
+   * newest failures go — a failure is never dropped to keep a success.
    *
    * An evicted task is degraded to a STUB (no content, `truncatedHeadChars`
    * = everything it emitted) rather than removed. Dropping the entry makes a
@@ -269,25 +305,25 @@ export class TaskLogBuffer {
    * sees it.
    */
   private evictToBudget(): void {
-    if (this.retainedChars <= RUN_LOG_BUDGET_CHARS) return
-    const order = [...this.retained.values()].sort((a, b) => {
-      const sa = a.status === 'success' ? 0 : 1
-      const sb = b.status === 'success' ? 0 : 1
-      if (sa !== sb) return sa - sb // successes are dropped first, always
-      // Within a tier the tiebreak DIFFERS by status, and the failed one is
-      // the point: when failures alone blow the budget, the FIRST failure is
-      // usually the root cause and the later ones its cascade, so it must be
-      // the last thing stubbed. Successes keep oldest-first — none of them
-      // is more interesting than another, and recency is the better guess.
-      return a.status === 'failed' ? b.seq - a.seq : a.seq - b.seq
-    })
-    for (const e of order) {
-      if (this.retainedChars <= RUN_LOG_BUDGET_CHARS) break
-      if (e.chars === 0) continue // already a stub — frees nothing
-      this.retainedChars -= budgetCost(e.chars, e.chunks.length)
-      e.truncatedHeadChars += e.chars
-      e.chunks = []
-      e.chars = 0
+    // Successes are dropped first, always, and keep oldest-first: none of
+    // them is more interesting than another, and recency is the better
+    // guess. Failures go newest-first: when failures alone blow the budget,
+    // the FIRST failure is usually the root cause and the later ones its
+    // cascade, so it must be the last thing stubbed.
+    while (this.retainedChars > RUN_LOG_BUDGET_CHARS && this.successHead < this.successes.length) {
+      const e = this.successes[this.successHead++]!
+      if (this.evictable(e)) this.stub(e)
+    }
+    while (this.retainedChars > RUN_LOG_BUDGET_CHARS && this.failures.length > 0) {
+      const e = this.failures.pop()!
+      if (this.evictable(e)) this.stub(e)
     }
   }
+
+  private stub(e: Retained): void {
+    this.retainedChars -= budgetCost(e.chars, e.chunks.length)
+    e.truncatedHeadChars += e.chars
+    e.chunks = []
+    e.chars = 0
+  }
 }

package/src/orchestrator/task-process.ts

@@ -11,6 +11,7 @@ import {
   PM_EXEC_ENV,
   VX_RUN_TASK_ENV,
   VX_RUN_WORKSPACE_ENV,
+  type ServerSpec,
 } from '../exec/index.js'
 import type { TaskNode } from '../graph/index.js'
 import { parseDuration } from '../util/index.js'
@@ -73,6 +74,7 @@ export function taskEnv(
     define: step.env?.define ?? {},
     source: process.env,
     binPaths: bins,
+    workspaceRoot,
   })
   env[VX_RUN_WORKSPACE_ENV] = workspaceRoot
   env[VX_RUN_TASK_ENV] = node.id
@@ -89,6 +91,26 @@ export function taskTimeoutMs(step: ExecConfig): number | undefined {
   return step.timeout === undefined ? undefined : parseDuration(step.timeout)!
 }
 
+/** Persistent task `node` as a `servers` executor starts it: no forwarded args, which a dependency never gets. */
+export function serverSpec(
+  node: TaskNode,
+  workspaceRoot: string,
+  nested: readonly string[],
+): ServerSpec {
+  const step = node.config.exec!
+  const timeoutMs = taskTimeoutMs(step)
+  const readyWhen = step.persistent?.readyWhen
+  return {
+    taskId: node.id,
+    command: step.command,
+    cwd: node.projectDir,
+    env: taskEnv(node, step, workspaceRoot),
+    ...(readyWhen === undefined ? {} : { readyWhen }),
+    ...(timeoutMs === undefined ? {} : { timeoutMs }),
+    ...(step.sandbox === undefined ? {} : { sandbox: { config: step.sandbox, nested } }),
+  }
+}
+
 export function isAborted(signal: AbortSignal | undefined): boolean {
   return signal?.aborted === true
 }

package/src/orchestrator/telemetry-host.ts

@@ -17,9 +17,11 @@ import type {
   RunContextRecord,
   RunSummaryRecord,
   TelemetryContext,
+  TelemetryRecord,
   TelemetrySink,
+  TreeLoad,
 } from './telemetry.js'
-import { settleWithin, teardownTimeoutMs } from '../util/index.js'
+import { settleWithin, teardownTimeoutMs, thrownMessage } from '../util/index.js'
 import { createTelemetrySource } from './telemetry.js'
 import type { VxPlugin } from './plugin.js'
 
@@ -32,7 +34,17 @@ export interface TelemetryHandle {
   /** Remove the bus subscription. Idempotent. */
   dispose(): void
   /** Sample a running task's process tree; see `TelemetrySource.track`. */
-  readonly track?: (taskId: string, pid: number) => () => void
+  readonly track?: (taskId: string, pid: number) => () => TreeLoad | undefined
+}
+
+// Every kind once: a kind added to `TelemetryRecord` fails to compile here.
+const RECORD_KINDS: Record<TelemetryRecord['kind'], true> = {
+  'run.start': true,
+  'task.start': true,
+  'task.log': true,
+  'task.sample': true,
+  'task.end': true,
+  'run.end': true,
 }
 
 /** Reject anything that is not sink-shaped, naming what arrived. */
@@ -44,6 +56,15 @@ function checkSink(sink: unknown): TelemetrySink {
   if (wants !== undefined && !Array.isArray(wants)) {
     throw new Error(`telemetry sink 'wants' must be an array, got ${typeof wants}`)
   }
+  // A misspelt kind (`task.logs`) was a sink that never heard it, with no word.
+  const unknown = (wants as readonly unknown[] | undefined)?.find(
+    (k) => typeof k !== 'string' || !Object.hasOwn(RECORD_KINDS, k),
+  )
+  if (unknown !== undefined) {
+    throw new Error(
+      `telemetry sink 'wants' names ${typeof unknown === 'string' ? JSON.stringify(unknown) : typeof unknown}, which is no record kind (${Object.keys(RECORD_KINDS).join(', ')})`,
+    )
+  }
   // Every handler is optional, so `{ nope: true }` was a valid sink that
   // subscribed to the bus and heard nothing — the plugin was "on" and did
   // nothing. Refused here, which the caller turns into the same warning
@@ -101,7 +122,7 @@ export async function subscribeTelemetry(
       accepted = list.map((sink) => checkSink(sink))
     } catch (err) {
       ctx.warn(
-        `[vx] plugin '${plugin.name}' telemetry failed to initialize; disabled for this run: ${err instanceof Error ? err.message : String(err)}`,
+        `[vx] plugin '${plugin.name}' telemetry failed to initialize; disabled for this run: ${thrownMessage(err)}`,
       )
       continue
     }