@vzn/vx 0.0.18 → 0.0.22

package/src/orchestrator/status-line.ts

@@ -42,6 +42,8 @@ export interface OutputWriter {
    * `setStatus`; the two share one display slot.
    */
   setRegion(lines: readonly string[], opts?: { force?: boolean }): void
+  /** Hand over what `coalesce` holds and write straight through from now on. */
+  settle(): void
   /** Permanently remove the status display; later set* is a no-op. */
   clearStatus(): void
 }
@@ -61,6 +63,13 @@ export interface OutputWriterOptions {
   forceFloorMs?: number
   /** Injectable clock for tests. */
   now?: () => number
+  /**
+   * Off a TTY, hold writes and hand them to the stream once per turn of
+   * the event loop until `settle()`. A warm 476-package run wrote each of
+   * its 952 task lines as its own syscall (item 753). Off by default: a
+   * caller reading its stream right after a write sees it.
+   */
+  coalesce?: boolean
 }
 
 export function createOutputWriter(
@@ -71,6 +80,17 @@ export function createOutputWriter(
   const minRedrawMs = opts.minRedrawMs ?? 100
   const forceFloorMs = opts.forceFloorMs ?? 30
   const now = opts.now ?? Date.now
+  // The coalesced writes not yet handed over; null once settled or when
+  // not coalescing.
+  let held: string[] | null = !enabled && opts.coalesce === true ? [] : null
+  let flushQueued = false
+  const flushHeld = (): void => {
+    flushQueued = false
+    if (held === null || held.length === 0) return
+    const text = held.join('')
+    held.length = 0
+    stream.write(text)
+  }
 
   let current: readonly string[] | null = null
   let shown = false
@@ -169,7 +189,15 @@ export function createOutputWriter(
     enabled,
     write(chunk) {
       if (!enabled) {
-        stream.write(chunk)
+        if (held === null) {
+          stream.write(chunk)
+          return
+        }
+        held.push(chunk)
+        if (!flushQueued) {
+          flushQueued = true
+          setImmediate(flushHeld)
+        }
         return
       }
       if (shown) {
@@ -187,6 +215,10 @@ export function createOutputWriter(
     setRegion(lines, o = {}) {
       set(lines, o)
     },
+    settle() {
+      flushHeld()
+      held = null
+    },
     clearStatus() {
       if (!enabled || dead) return
       dead = true
@@ -248,13 +280,14 @@ export function formatFailureLine(
   id: string,
   durationMs: number | null,
   colors: ColorSupport = NO_COLOR,
+  cacheWord: 'miss' | 'no-cache' = 'miss',
 ): string {
   return formatTaskRow(
     paint(ERROR, '◼\uFE0E', colors),
     durationMs,
     'failed',
     ERROR,
-    'miss',
+    cacheWord,
     '',
     paintPinnedId(id, colors),
     colors,

package/src/orchestrator/summary.ts

@@ -4,6 +4,7 @@
 // aren't real work and would inflate "N total" misleadingly.
 
 import type { TaskOutcome } from '../graph/index.js'
+import type { FlakyFinding } from './failure-mode.js'
 import { paint, type ColorSupport } from './colors.js'
 import { tallyOutcomes } from './tally.js'
 import { isGroupTask } from '../graph/index.js'
@@ -101,13 +102,17 @@ export interface SummaryStats {
   upToDate: number
   restoredLocal: number
   restoredRemote: number
-  /** Tasks that executed (success + failed) — the cache misses. */
+  /** Tasks that executed (success + failed) with a `cache` block — the misses. */
   miss: number
+  /** Executed with no `cache` block: never consulted the cache, not a miss. */
+  noCache?: number
   /** Still to run (live section only; 0 in the final summary) — renders
    *  as a gray ▱ remainder so the live meters FILL toward the final. */
   left?: number
   /** Cache-miss duration spread (only tasks that actually executed). */
   spread: { maxMs: number; minMs: number; sumMs: number; count: number } | null
+  /** Tasks an `admit` policy held with a worker free, and the waits summed. Absent with no hold. */
+  held?: { count: number; sumMs: number }
 }
 
 /**
@@ -125,14 +130,6 @@ export interface RunContext {
   remoteCacheEnabled: boolean
   /** Total projects discovery found — the bar's denominator. */
   workspaceProjectCount?: number
-  /**
-   * Resource-admission budgets (`exec.resources`), set ONLY when at
-   * least one task declared a reservation — a plain run's footer is
-   * byte-identical. Shown on the `info` row so a packed run says what
-   * it packed against. memBudget in bytes.
-   */
-  cpuBudget?: number
-  memBudget?: number
 }
 
 export function formatSummarySection(
@@ -143,6 +140,7 @@ export function formatSummarySection(
 ): string[] {
   const hits = stats.upToDate + stats.restoredLocal + stats.restoredRemote
   const miss = stats.miss
+  const noCache = stats.noCache ?? 0
   const left = stats.left ?? 0
   const remainder = { n: left, color: '', glyph: '\u25b1', dim: true }
 
@@ -206,10 +204,11 @@ export function formatSummarySection(
 
   // Cache meter + numbers, fixed order: miss · up-to-date · local ·
   // remote.
-  if (miss + hits + left + stats.skipped > 0) {
+  if (miss + noCache + hits + left + stats.skipped > 0) {
     const cacheBar = segmentBar(
       [
         { n: miss, color: ERROR },
+        { n: noCache, color: '', dim: true },
         { n: stats.upToDate, color: SUCCESS },
         { n: stats.restoredLocal, color: LOCAL },
         { n: stats.restoredRemote, color: REMOTE },
@@ -220,6 +219,7 @@ export function formatSummarySection(
     )
     const cacheParts: string[] = []
     if (miss > 0) cacheParts.push(paint(ERROR, `${miss} miss`, colors))
+    if (noCache > 0) cacheParts.push(paint('', `${noCache} no-cache`, colors, { dim: true }))
     if (stats.upToDate > 0) cacheParts.push(paint(SUCCESS, `${stats.upToDate} up-to-date`, colors))
     if (stats.restoredLocal > 0)
       cacheParts.push(paint(LOCAL, `${stats.restoredLocal} local`, colors))
@@ -248,9 +248,16 @@ export function formatSummarySection(
     if (context.concurrency !== undefined)
       info.push(`${context.concurrency} worker${context.concurrency === 1 ? '' : 's'}`)
     info.push(context.remoteCacheEnabled ? 'local + remote cache' : 'local cache')
-    if (context.cpuBudget !== undefined) info.push(`cpu budget ${context.cpuBudget}`)
-    if (context.memBudget !== undefined && Number.isFinite(context.memBudget))
-      info.push(`mem budget ${formatBudgetBytes(context.memBudget)}`)
+    // The plugin's hand on the run: a task a policy held with a worker
+    // free would otherwise have started; without the line nothing says
+    // the policy acted. The duration is the waits summed, task-seconds
+    // — 85 held tasks read `4783s` beside a 160 s run on TanStack/router
+    // (2026-09-15), so the line says it is a sum.
+    if (stats.held !== undefined && stats.held.count > 0) {
+      info.push(
+        `admit held ${stats.held.count} task${stats.held.count === 1 ? '' : 's'}, ${formatDuration(stats.held.sumMs)} in all`,
+      )
+    }
     lines.push('', row('info', join(info)), row('time', `${formatDuration(totalMs)}${spread}`))
   } else {
     lines.push('', row('time', `${formatDuration(totalMs)}${spread}`))
@@ -260,29 +267,28 @@ export function formatSummarySection(
 
 // Local byte formatter — the orchestrator can't import cli/format.ts
 // (module boundary), and the footer only needs one compact form.
-function formatBudgetBytes(bytes: number): string {
-  const units = ['B', 'KB', 'MB', 'GB', 'TB']
-  let v = bytes
-  let u = 0
-  while (v >= 1024 && u < units.length - 1) {
-    v /= 1024
-    u++
-  }
-  return `${u === 0 ? v : v.toFixed(1)} ${units[u]}`
-}
-
 export function formatRunSummary(
   outcomes: readonly TaskOutcome[],
   totalMs: number,
   colors: ColorSupport = NO_COLOR,
   context?: RunContext,
 ): string[] {
+  // Counted here, not in the Tally: that object is the `--summarize` payload
+  // (ten documented fields) and a task with no `cache` block is a terminal
+  // distinction — it never consulted the cache, so it is not a miss.
+  const noCache = outcomes.filter(
+    (o) =>
+      !isGroupTask(o.node) &&
+      (o.status === 'success' || o.status === 'failed') &&
+      o.node.config.cache === undefined,
+  ).length
   const t = tallyOutcomes(outcomes)
   // Spread over executed tasks only — `success`/`failed` statuses ran
   // a command; cache-hit statuses replayed one.
   const durations = outcomes
     .filter((o) => (o.status === 'success' || o.status === 'failed') && !isGroupTask(o.node))
     .map((o) => o.durationMs)
+  const heldOutcomes = outcomes.filter((o) => o.admissionHeldMs !== undefined)
   return formatSummarySection(
     {
       failed: t.failed,
@@ -292,7 +298,8 @@ export function formatRunSummary(
       upToDate: t.upToDate,
       restoredLocal: t.restoredLocal,
       restoredRemote: t.restoredRemote,
-      miss: t.total - t.skipped - (t.cachedLocal + t.cachedRemote),
+      miss: t.total - t.skipped - (t.cachedLocal + t.cachedRemote) - noCache,
+      noCache,
       spread:
         durations.length > 0
           ? {
@@ -302,6 +309,14 @@ export function formatRunSummary(
               count: durations.length,
             }
           : null,
+      ...(heldOutcomes.length > 0
+        ? {
+            held: {
+              count: heldOutcomes.length,
+              sumMs: heldOutcomes.reduce((sum, o) => sum + o.admissionHeldMs!, 0),
+            },
+          }
+        : {}),
     },
     totalMs,
     colors,
@@ -330,6 +345,81 @@ export function formatAbortedSection(outcomes: readonly TaskOutcome[]): string[]
   return lines
 }
 
+/**
+ * Post-summary section naming the tasks that never started, under the
+ * failure that blocked them. The footer's "1 skipped" says a task was
+ * blocked and nothing about which task or by what; the broad flow prints
+ * no row for a skipped task on purpose (a wide red run would drown in
+ * them), so this is where the reader learns what the failure cost
+ * (item 266). The scheduler records the root of each block on the outcome
+ * (`blockedBy`, item 267); a skip without one is fail-fast's. Empty when
+ * nothing was skipped.
+ */
+export function formatSkippedSection(outcomes: readonly TaskOutcome[]): string[] {
+  // A group (no `exec`) never starts by definition and is not a task the
+  // tally counts; listing a blocked one here named three "tasks" the legend
+  // beside it counted as none (item 281). Its members' rows say enough.
+  const skipped = outcomes.filter((o) => o.status === 'skipped' && !isGroupTask(o.node))
+  if (skipped.length === 0) return []
+  const byId = new Map(outcomes.map((o) => [o.node.id, o]))
+  const causeOf = (o: TaskOutcome): string => {
+    if (o.blockedBy === undefined) return 'after the run stopped (fail-fast)'
+    const root = byId.get(o.blockedBy)
+    return root?.status === 'aborted'
+      ? `after ${o.blockedBy} was aborted`
+      : `after ${o.blockedBy} failed`
+  }
+  const groups = new Map<string, string[]>()
+  for (const o of skipped) {
+    const cause = causeOf(o)
+    const list = groups.get(cause) ?? []
+    list.push(o.node.id)
+    groups.set(cause, list)
+  }
+  const lines = [
+    '',
+    `  Skipped:  ${skipped.length} task${skipped.length === 1 ? '' : 's'} never started \u2014 blocked upstream`,
+  ]
+  const NAMES = 8
+  for (const [cause, ids] of [...groups].sort((a, b) => b[1].length - a[1].length)) {
+    ids.sort()
+    const shown = ids.slice(0, NAMES).join(', ')
+    const more = ids.length > NAMES ? ` \u2026 +${ids.length - NAMES} more` : ''
+    lines.push(`    \u2298 ${cause}: ${shown}${more}`)
+  }
+  return lines
+}
+
+/**
+ * Post-summary section naming the tasks this run proved flaky: identical
+ * inputs, both outcomes on record (or a retry within the run). A red run
+ * whose failure has passed on these exact inputs before is not a break to
+ * bisect, and a green run that only passed on the second attempt is not
+ * green — either way the footer's counts alone would say nothing. Empty
+ * when nothing was.
+ */
+export function formatFlakySection(findings: readonly FlakyFinding[]): string[] {
+  if (findings.length === 0) return []
+  const lines = [
+    '',
+    `  Flaky:    ${findings.length} task${findings.length === 1 ? '' : 's'} with the same inputs both passing and failing on record`,
+  ]
+  for (const f of findings) {
+    const times = (n: number): string => `${n}\u00d7`
+    const history =
+      f.status === 'failed'
+        ? `failed on inputs that passed ${times(f.passes)} before`
+        : f.failures > 0
+          ? `passed on inputs that failed ${times(f.failures)} before`
+          : 'passed'
+    const retried = f.attempts > 1 ? ` \u00b7 ${f.attempts} attempts this run` : ''
+    lines.push(
+      `    ${f.status === 'failed' ? '\u2717' : '\u2713'} ${f.taskId} \u2014 ${history}${retried}`,
+    )
+  }
+  return lines
+}
+
 export function formatDuration(ms: number): string {
   if (ms < 1000) return `${Math.round(ms)}ms`
   return `${(ms / 1000).toFixed(2)}s`

package/src/orchestrator/task-hash.ts

@@ -1,8 +1,11 @@
+import { lstatSync } from 'node:fs'
 import path from 'node:path'
 import type { TaskConfig, CacheConfig } from '../config.js'
+import type { ProjectFilesCache, WorkspaceFilesCache } from '../cache/index.js'
 import {
   type CacheKeyInput,
   type CacheLayer,
+  FILE_HASH_RACY_MS,
   resolveInputs,
   type GitFilesCache,
   WORKSPACE_OUTPUT_PREFIX,
@@ -19,6 +22,9 @@ import { expandGroupUpstream, filterUpstreamHashes } from './upstream.js'
  *     project re-reads the same `package.json`; without this, a
  *     monorepo with N projects × M tasks per project does N×M reads
  *     of the same bytes.
+ *   - `projectFiles`: keyed by the project and its input DECLARATION.
+ *     Tasks of one project that declare the same inputs and outputs
+ *     resolve the same file list; see `ProjectFilesCache`.
  *   - `taskConfig`: keyed by the resolved-config object reference.
  *     Each task's config is created once at prepareRun time; the
  *     JSON.stringify + xxh3 of it is deterministic. WeakMap so
@@ -32,6 +38,8 @@ export interface HashCache {
   taskConfig: WeakMap<TaskConfig, string>
   runtime: Map<string, Promise<string>>
   workspaceRuntime: Map<string, Promise<string>>
+  workspaceFiles: WorkspaceFilesCache
+  projectFiles: ProjectFilesCache
 }
 
 export function createHashCache(): HashCache {
@@ -40,6 +48,8 @@ export function createHashCache(): HashCache {
     taskConfig: new WeakMap(),
     runtime: new Map(),
     workspaceRuntime: new Map(),
+    workspaceFiles: new Map(),
+    projectFiles: new Map(),
   }
 }
 
@@ -98,6 +108,18 @@ export async function computeTaskHash(args: ComputeHashArgs): Promise<string> {
   }
 }
 
+/**
+ * One file the key folded: the digest it folded, and since when (ms since
+ * the epoch) that digest is known to be the file's content — the
+ * enumeration's start for an index OID (`git status` vouched for it then),
+ * the describe's start for a digest hashed from the file.
+ */
+export interface InputFact {
+  path: string
+  digest: string
+  since: number
+}
+
 /**
  * The key AND the structured input set behind it, for the executor seam.
  * Miss path only: it re-runs the (memoized) resolution `computeTaskHash`
@@ -109,7 +131,8 @@ export async function computeTaskHash(args: ComputeHashArgs): Promise<string> {
  */
 export async function describeTaskInputs(
   args: ComputeHashArgs,
-): Promise<{ hash: string; inputs: TaskInputs }> {
+): Promise<{ hash: string; inputs: TaskInputs; facts: InputFact[]; describedAt: number }> {
+  const hashedAt = Date.now()
   const input = await resolveKeyInput(args)
   const hash = await args.cache.key(input)
   const sorted = [...input.inputFiles].sort()
@@ -120,6 +143,22 @@ export async function describeTaskInputs(
     path: relPosix(input.workspaceRoot, f),
     digest: digests[i]!,
   }))
+  // The package.json digest is a per-run memo that may predate this
+  // describe, so it is dated from the enumeration, the earliest a run
+  // learns anything.
+  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,
+  }))
+  if (input.projectPackageJsonHash !== '') {
+    facts.push({
+      path: path.join(args.node.projectDir, 'package.json'),
+      digest: input.projectPackageJsonHash,
+      since: indexedAt,
+    })
+  }
   // 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
@@ -140,6 +179,8 @@ export async function describeTaskInputs(
   })
   return {
     hash,
+    facts,
+    describedAt: hashedAt,
     inputs: {
       files,
       env: input.envValues.map(([name, value]) => ({ name, value })),
@@ -156,6 +197,41 @@ export async function describeTaskInputs(
   }
 }
 
+/**
+ * The first input whose content may no longer be the digest the key folded
+ * (item 743), or undefined when every one still is. One `lstat` per file:
+ * a file whose ctime is older than its fact (by the racy window, as git
+ * judges its index) has not been written since, and one that is not gets
+ * hashed again and compared. ctime, because no writer can set it back. A
+ * file that is gone has moved. One written at or after `commandFrom` (the
+ * describe just before the command) has moved whatever it holds now: an
+ * input changed and changed BACK while the command ran matched its digest
+ * again, and the entry saved the other content's output under the key (item
+ * 1015). A write before it — an upstream's — is judged by content, as before.
+ */
+export async function movedInput(
+  facts: readonly InputFact[],
+  cache: CacheLayer,
+  commandFrom?: number,
+): Promise<string | undefined> {
+  const suspects: InputFact[] = []
+  for (const f of facts) {
+    let ctimeMs: number
+    try {
+      ctimeMs = lstatSync(f.path).ctimeMs
+    } catch {
+      return f.path
+    }
+    if (commandFrom !== undefined && ctimeMs >= commandFrom) return f.path
+    if (ctimeMs >= f.since - FILE_HASH_RACY_MS) suspects.push(f)
+  }
+  for (const f of suspects) {
+    const now = await cache.hashFile(f.path).catch(() => undefined)
+    if (now !== f.digest) return f.path
+  }
+  return undefined
+}
+
 async function resolveKeyInput(args: ComputeHashArgs): Promise<CacheKeyInput> {
   const cfg = args.node.config
   const cacheCfg: CacheConfig | undefined = cfg.cache
@@ -174,6 +250,8 @@ async function resolveKeyInput(args: ComputeHashArgs): Promise<CacheKeyInput> {
       ? {
           runtimeCache: args.hashCache.runtime,
           workspaceRuntimeCache: args.hashCache.workspaceRuntime,
+          workspaceFilesCache: args.hashCache.workspaceFiles,
+          projectFilesCache: args.hashCache.projectFiles,
         }
       : {}),
   })
@@ -247,8 +325,9 @@ async function resolveKeyInput(args: ComputeHashArgs): Promise<CacheKeyInput> {
  * participate because the loader has already baked them into the
  * resolved object before we serialize.
  *
- * The schema is JSON-serializable by construction (no functions in
- * fields). The `hashCache.taskConfig` WeakMap is consulted first —
+ * A loaded config is JSON data: every load path refuses a value JSON
+ * cannot carry (workspace/json-data.ts, item 701), so this JSON is the
+ * config as vx reads it. The `hashCache.taskConfig` WeakMap is consulted first —
  * each task's config object is created once per run, so a hit there
  * skips the JSON.stringify + xxh3 entirely.
  */
@@ -264,25 +343,28 @@ function hashTaskConfig(cfg: TaskConfig, hashCache?: HashCache): string {
 }
 
 /**
- * Project the config for hashing: `exec.resources` (cores, memory AND the
- * image a task must be matched to) and `exec.remote` are pure PLACEMENT
- * hints with zero effect on outputs, so they're stripped — tuning a
- * reservation, pinning a task to this machine, or naming the container it
- * runs in never busts a cache. `remote` in particular must not: the whole
- * contract of a remote executor is that the same command over the same
- * inputs produces the same outputs, so a key that moved when placement
- * changed would split a laptop from a worker pool over nothing. `image`
- * rides the same rule one step further: a task that ran locally and the
- * same task on a worker must share an entry, and a task whose output really
- * does depend on its toolchain says so with `cache.inputs.runtime`, which
- * works on both. A config that declares neither takes the fast path and stringifies byte-identically to before the fields existed
- * (why this needs no CACHE_VERSION bump). `timeout`/`retries` stay folded
- * — their keys are distinct by design (see the decision log); stripping
- * them retroactively would bump CACHE_VERSION.
+ * Project the config for hashing: `exec.remote` is a pure PLACEMENT hint
+ * with zero effect on outputs, so it is stripped — pinning a task to this
+ * machine never busts a cache. It must not: the whole contract of a remote
+ * executor is that the same command over the same inputs produces the
+ * same outputs, so a key that moved when placement changed would split a
+ * laptop from a worker pool over nothing. (`exec.resources` rode the same
+ * rule until 2026-09-12, when reservations left the config for the
+ * schedule plugin that learns them; a config never declares them now.) A
+ * config that declares no `remote` takes the fast path. That is a
+ * SHORTCUT, not the reason the field needed no CACHE_VERSION bump:
+ * measured (item 505), the spread path stringifies byte-identically for
+ * every config that HAS an `exec`, since a spread keeps an existing key
+ * in place. Its one behavioural case is a config with NO `exec`, where
+ * the spread would add `exec: {}` — and nothing reaches here that way,
+ * proven by throwing on a no-exec config and running the whole suite:
+ * a group takes `computeGroupHash` instead. `timeout`/`retries` stay folded — their keys are
+ * distinct by design (see the decision log); stripping them retroactively
+ * would bump CACHE_VERSION.
  */
 function hashableConfig(cfg: TaskConfig): unknown {
-  if (cfg.exec?.resources === undefined && cfg.exec?.remote === undefined) return cfg
-  const { resources: _resources, remote: _remote, ...execRest } = cfg.exec
+  if (cfg.exec?.remote === undefined) return cfg
+  const { remote: _remote, ...execRest } = cfg.exec
   return { ...cfg, exec: execRest }
 }
 
@@ -343,5 +425,5 @@ async function doHashProjectPackageJson(
   if (!(await Bun.file(filePath).exists())) return ''
   // Route through the cache layer's mtime+size fast path so the
   // typical re-run sees a stat + SQLite lookup instead of a file read.
-  return await cache.hashFile(filePath)
+  return cache.hashFile(filePath)
 }

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

@@ -1,7 +1,6 @@
 // The shared per-task log capture primitive (task-logs-2026-07 §1). ONE
-// bounded-tail buffer every telemetry sink uses — the cloud client sink (local
-// runs), the cloud serve sink (delegated runs), the dist scheduler, and the
-// OTLP logs exporter — so the capping rules can't drift between capture sites.
+// bounded-tail buffer every telemetry sink uses — today `@vzn/vx-otel`'s
+// sink — so the capping rules can't drift between capture sites.
 //
 // It lives in CORE, beside the telemetry contract, for the same reason
 // `assembleRunSummary` does: two sinks that each roll their own bounded buffer
@@ -25,8 +24,7 @@ import type { TaskStatus } from '../graph/index.js'
 import type { CacheSource } from './telemetry.js'
 
 /** Version of the drained-bundle shape below. It is the canonical drained
- *  logs format, not one transport's: cloud's `POST /v1/ingest/logs` accepts
- *  it verbatim, and any other sink ships the same object. */
+ *  logs format, not one transport's: every sink ships the same object. */
 export const LOG_WIRE_VERSION = 1
 
 /**
@@ -81,13 +79,6 @@ interface InFlight {
   truncatedHeadChars: 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
- * 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.
- */
 /**
  * Per-retained-chunk overhead, in char-equivalents, charged against the RUN
  * budget on top of the characters themselves.
@@ -112,6 +103,13 @@ function budgetCost(chars: number, chunkCount: number): number {
   return chars + chunkCount * CHUNK_OVERHEAD_CHARS
 }
 
+/**
+ * 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
+ * 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.
+ */
 export class TaskLogBuffer {
   private readonly inFlight = new Map<string, InFlight>()
   private readonly retained = new Map<string, Retained>()
@@ -256,15 +254,14 @@ export class TaskLogBuffer {
    * enough failing tasks to blow the budget). A stub costs a few dozen bytes,
    * keeps the `content.length === charsFull - truncatedHeadChars` accounting
    * honest, and renders through the truncation banner the per-task cap
-   * already uses. It is also what the STORE does when its own run budget runs
-   * out (`Analytics.ingestLogs` slices to empty and adds the remainder to
-   * `truncated_head`) — the two sides now degrade the same way.
+   * already uses — a store that enforces its own run budget should degrade
+   * the same way (slice to empty, add the remainder to the truncated count).
    *
    * The cost is a stub per evicted task in the end-of-run bundle: measured at
    * ~190 JSON bytes each, so ~1.9 MiB at the 10k-task scale target and ~9.3 MiB
-   * at 50k, against the 16 MiB `/v1/ingest/logs` cap. A run evicting past ~66k
-   * tasks would 413 the batch — remote (6x the scale target), and it does not
-   * touch the connected default, which ships per task as it finishes.
+   * at 50k — a sink that posts the whole bundle in one request sizes its cap
+   * against that; one that ships per task as it finishes (`takeEntry`) never
+   * sees it.
    */
   private evictToBudget(): void {
     if (this.retainedChars <= RUN_LOG_BUDGET_CHARS) return

package/src/orchestrator/telemetry-host.ts

@@ -18,6 +18,7 @@ import type {
   TelemetryContext,
   TelemetrySink,
 } from './telemetry.js'
+import { settleWithin, teardownTimeoutMs } from '../util/index.js'
 import { createTelemetrySource } from './telemetry.js'
 import type { VxPlugin } from './plugin.js'
 
@@ -40,7 +41,17 @@ function checkSink(sink: unknown): TelemetrySink {
   if (wants !== undefined && !Array.isArray(wants)) {
     throw new Error(`telemetry sink 'wants' must be an array, got ${typeof wants}`)
   }
-  return sink as TelemetrySink
+  // 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
+  // a throwing hook gets: never a failed run.
+  const s = sink as TelemetrySink
+  if (typeof s.onRecord !== 'function' && typeof s.onRunSummary !== 'function') {
+    throw new Error(
+      'telemetry sink handles nothing: neither onRecord nor onRunSummary is a function',
+    )
+  }
+  return s
 }
 
 /**
@@ -69,7 +80,18 @@ export async function subscribeTelemetry(
     // check sits INSIDE the try so a throwing `wants` getter is caught too.
     let accepted: TelemetrySink[]
     try {
-      const result = await plugin.telemetry(ctx)
+      // Bounded as flush and teardown are: a hook that never settles held
+      // the run before its first task, forever or until the loop drained
+      // and Bun exited 0 (item 921).
+      let result: Awaited<ReturnType<NonNullable<VxPlugin['telemetry']>>> | undefined
+      const ms = teardownTimeoutMs()
+      const arrived = await settleWithin(
+        Promise.resolve(plugin.telemetry(ctx)).then((r) => {
+          result = r
+        }),
+        ms,
+      )
+      if (!arrived) throw new Error(`did not initialize within ${ms} ms`)
       const list = result === undefined ? [] : Array.isArray(result) ? result : [result]
       accepted = list.map((sink) => checkSink(sink))
     } catch (err) {
@@ -84,15 +106,12 @@ export async function subscribeTelemetry(
   if (sinks.length === 0) return undefined
 
   const source = createTelemetrySource({ sinks, run, warn: (m) => ctx.warn(m) })
+  // The bus's unsubscribe is idempotent, so it is the handle's dispose as
+  // is (a once-flag here survived item 654).
   const dispose = bus.subscribe(source.subscriber)
-  let disposed = false
   return {
     emitSummary: (summary) => source.emitSummary(summary),
     flush: () => source.flush(),
-    dispose() {
-      if (disposed) return
-      disposed = true
-      dispose()
-    },
+    dispose,
   }
 }