@vzn/vx 0.0.646 → 0.0.648

package/src/orchestrator/local-floor.ts

@@ -1,22 +1,29 @@
 // Core's local floor for a plugin that runs tasks itself: `@vzn/vx-dte`'s
-// orchestrator for its own share, and its agents, which run tasks another
-// machine placed. A run arms the sandbox runtime before it builds a
-// sandboxed request; an agent is no run, so it arms here. It starts a
-// request's servers (`ExecuteRequest.servers`) once each, before the
-// task, and stops them when it closes.
+// workers, which run tasks another machine placed. A run arms the sandbox
+// runtime before it builds a sandboxed request; a worker is no run, so it
+// arms here. It starts a request's servers (`ExecuteRequest.servers`) once
+// each, before the task, each inside its own sandbox, and stops them when
+// it closes.
 
 import type { ExecConfig } from '../config.js'
 import {
   localExecutor,
+  PersistentReadyError,
+  releaseBridges,
   resetSandbox,
   runPersistent,
+  signalExitCode,
   type ExecuteRequest,
   type ExecuteResult,
   type ServerSpec,
+  wrapSandboxedCommand,
 } from '../exec/index.js'
-import { prepareSandbox } from './sandbox-request.js'
+import { placeholderSweeper, prepareSandbox, sandboxRequestFor } from './sandbox-request.js'
 import { forwardedSignal, terminateChildren } from './signals.js'
 
+/** How much of a server's output before ready a failure to start quotes. */
+const HEARD_BYTES = 8192
+
 export interface LocalFloor {
   execute(req: ExecuteRequest): Promise<ExecuteResult>
   /** Arms the sandbox runtime for `sandboxes` from the next sandboxed task on; its servers keep running. */
@@ -43,20 +50,84 @@ export function localFloor(
   // Each server, by task id: shared by every task here that depends on it.
   const servers = new Map<string, Promise<ReturnType<typeof Bun.spawn>>>()
   const children: ReturnType<typeof Bun.spawn>[] = []
-  const serve = (spec: ServerSpec): Promise<unknown> => {
-    let up = servers.get(spec.taskId)
-    if (up === undefined) {
-      const spawn = runPersistent({
-        command: spec.command,
+  // A sandboxed one starts inside its sandbox, built here as a one-shot
+  // task's; its port bridges and untouched placeholders go when it exits.
+  const start = async (spec: ServerSpec, root: string): Promise<ReturnType<typeof Bun.spawn>> => {
+    let command = spec.command
+    let signalChannel = false
+    let gone = async (): Promise<unknown> => undefined
+    if (spec.sandbox !== undefined) {
+      await armer?.arm()
+      const sb = await sandboxRequestFor(
+        { projectDir: spec.cwd },
+        spec.sandbox.config,
+        root,
+        undefined,
+        spec.sandbox.nested,
+      )
+      const swept = placeholderSweeper(sb.placeholders)
+      const wrapped = await wrapSandboxedCommand({
+        command,
         cwd: spec.cwd,
         env: spec.env,
-        onStdout: () => {},
-        onStderr: () => {},
-        ...(spec.readyWhen === undefined ? {} : { readyWhen: spec.readyWhen }),
-        ...(spec.timeoutMs === undefined ? {} : { timeoutMs: spec.timeoutMs }),
+        ...sb.sandbox,
+        server: true,
+      }).catch(async (err: unknown) => {
+        await swept()
+        throw err
       })
+      command = wrapped.wrapped
+      signalChannel = wrapped.forwardsSignals
+      gone = async () => {
+        if (wrapped.tag !== undefined) releaseBridges(wrapped.tag)
+        return swept()
+      }
+    }
+    // Its output until ready, the tail kept: a server that dies first says
+    // why (`docker run` exiting 125 said nothing on CI, 2026-10-26).
+    let heard: string | undefined = ''
+    const hear = (t: string): void => {
+      if (heard !== undefined) heard = (heard + t).slice(-HEARD_BYTES)
+    }
+    const spawn = runPersistent({
+      command,
+      cwd: spec.cwd,
+      env: spec.env,
+      onStdout: hear,
+      onStderr: hear,
+      ...(spec.readyWhen === undefined ? {} : { readyWhen: spec.readyWhen }),
+      ...(spec.timeoutMs === undefined ? {} : { timeoutMs: spec.timeoutMs }),
+      ...(signalChannel ? { signalChannel } : {}),
+    })
+    // A spawn that threw hands back no child, only a rejected `ready`.
+    if (spawn.child === undefined) void gone()
+    else {
       children.push(spawn.child)
-      up = spawn.ready.then(() => spawn.child)
+      void spawn.child.exited.then(gone, gone)
+    }
+    try {
+      await spawn.ready
+    } catch (err) {
+      // A shell that exited before ready can leave its group running
+      // (`server & …; exit`), holding the port of the one the next task starts.
+      if (
+        err instanceof PersistentReadyError &&
+        err.reason === 'exited' &&
+        spawn.child !== undefined
+      )
+        await terminateChildren(() => [spawn.child!])
+      const why = err instanceof Error ? err.message : String(err)
+      const said = (heard ?? '').trimEnd()
+      throw new Error(said === '' ? why : `${why}; its output:\n${said}`)
+    }
+    heard = undefined
+    // Ready, so it spawned: only a failed spawn has no child.
+    return spawn.child!
+  }
+  const serve = (spec: ServerSpec, root: string): Promise<ReturnType<typeof Bun.spawn>> => {
+    let up = servers.get(spec.taskId)
+    if (up === undefined) {
+      up = start(spec, root)
       servers.set(spec.taskId, up)
       // One that never became ready is asked again by the next task.
       up.catch(() => servers.delete(spec.taskId))
@@ -65,24 +136,47 @@ export function localFloor(
   }
   return {
     async execute(req) {
+      // A stop while a server is not yet ready ends the wait: one that never
+      // prints its `readyWhen` line held the task, and a worker's shutdown
+      // waits on its tasks before `close()` stops the servers. The aborted
+      // request then reads as one stopped before its spawn.
+      const signal = req.signal
+      const stopped =
+        signal === undefined
+          ? undefined
+          : new Promise<void>((resolve) => {
+              if (signal.aborted) resolve()
+              else signal.addEventListener('abort', () => resolve(), { once: true })
+            })
       for (const spec of req.servers ?? []) {
+        if (signal?.aborted === true) break
         try {
-          await serve(spec)
+          const up = serve(spec, req.workspaceRoot)
+          const child = await (stopped === undefined ? up : Promise.race([up, stopped]))
+          // One that crashed after it was ready serves nobody: the task ran
+          // against nothing and failed on its own "connection refused". A
+          // clean exit is a setup step that did its work (runPersistent).
+          const died = child === undefined ? null : (child.exitCode ?? child.signalCode)
+          if (died !== null && died !== 0) {
+            const code = typeof died === 'number' ? died : signalExitCode(died)
+            const text = `${spec.taskId}, which ${req.taskId} depends on, exited with code ${code} after it was ready\n`
+            req.onStderr(text)
+            return { exitCode: 1, durationMs: 0, stdout: '', stderr: text, violations: [] }
+          }
         } catch (err) {
           const why = err instanceof Error ? err.message : String(err)
-          return {
-            exitCode: 1,
-            durationMs: 0,
-            stdout: '',
-            stderr: `${spec.taskId}, which ${req.taskId} depends on, did not start: ${why}\n`,
-            violations: [],
-          }
+          const text = `${spec.taskId}, which ${req.taskId} depends on, did not start: ${why}\n`
+          // Through `onStderr` too, as a spawn failure's text goes: a worker
+          // ships only what its callbacks heard, and a dependant failed
+          // "exit 1, 0ms" with no word of why (CI, 2026-10-25).
+          req.onStderr(text)
+          return { exitCode: 1, durationMs: 0, stdout: '', stderr: text, violations: [] }
         }
       }
       if (req.sandbox !== undefined) await armer?.arm()
       const stop = req.signal
       if (stop === undefined || req.liveChildren !== undefined) return local.execute(req)
-      // No run holds this task's children (an agent's): its stop is ours to carry out.
+      // No run holds this task's children (a worker's): its stop is ours to carry out.
       const live = new Set<ReturnType<typeof Bun.spawn>>()
       const end = (): void => void terminateChildren(() => [...live], forwardedSignal(stop.reason))
       stop.addEventListener('abort', end, { once: true })

package/src/orchestrator/local-shortcircuit.ts

@@ -44,8 +44,8 @@
 import { normalizeGlob, relPosix, span, staticPrefix } from '../util/index.js'
 import type { CacheEntry, CacheLayer, GitFilesCache } from '../cache/index.js'
 import type { TaskNode } from '../graph/index.js'
-import { deriveStableKeys, workspaceInputsReach } from './stable-keys.js'
-import { readRunKeys, runKeysToken, writeRunKeys } from './run-keys.js'
+import { deriveStableKeys, rederiveKeys, workspaceInputsReach } from './stable-keys.js'
+import { readRunDelta, readRunKeys, runKeysToken, writeRunDelta, writeRunKeys } from './run-keys.js'
 import type { HashCache, UpfrontGroupKey } from './task-hash.js'
 import { getContext } from './remote-prefetch.js'
 
@@ -126,8 +126,32 @@ export async function startLocalShortCircuit(args: ShortCircuitArgs): Promise<Sh
       stableKeys = remembered.stableKeys
       for (const [id, key] of remembered.uncachedKeys) uncachedKeys.set(id, key)
     } else {
-      stableKeys = await deriveStableKeys({ ...args, uncachedKeys, groupKeys })
-      if (at !== undefined) writeRunKeys(args, at, { stableKeys, uncachedKeys })
+      // An edit moved some files tokens: the last derivation under the same
+      // graph keys again only the tasks the edit reaches.
+      const delta = at === undefined ? undefined : readRunDelta(args, at)
+      let derivation
+      if (delta !== undefined) {
+        derivation = delta.derivation
+        await rederiveKeys(args, derivation.keys, delta.dirty)
+        const keys = derivation.keys
+        stableKeys = derivation.stable.map((id) => ({
+          hash: keys.get(id)!,
+          node: args.nodes.get(id)!,
+        }))
+        for (const id of derivation.uncached) uncachedKeys.set(id, keys.get(id)!)
+      } else {
+        const keys = new Map<string, string>()
+        stableKeys = await deriveStableKeys({ ...args, uncachedKeys, groupKeys, keys })
+        derivation = {
+          keys,
+          stable: stableKeys.map((k) => k.node.id),
+          uncached: [...uncachedKeys.keys()],
+        }
+      }
+      if (at !== undefined) {
+        writeRunKeys(args, at, { stableKeys, uncachedKeys })
+        writeRunDelta(args, at, derivation)
+      }
     }
   } catch {
     return {

package/src/orchestrator/lockfile-claim.ts

@@ -15,7 +15,7 @@
 
 import path from 'node:path'
 import { rename, stat } from 'node:fs/promises'
-import { relPosix, xxh3, xxh3hex } from '../util/index.js'
+import { relPosix, UserError, xxh3, xxh3hex } from '../util/index.js'
 import type { TaskNode } from '../graph/index.js'
 import type {
   FingerprintChange,
@@ -37,7 +37,7 @@ export interface LockfileClaimOptions {
   /**
    * Root-relative files the lockfile names whose BYTES the install uses but
    * the lockfile does not pin (bun.lock's `patchedDependencies` names a patch
-   * file and records no hash of it). Their content hashes ('' when absent)
+   * file and records no hash of it). Their content hashes ('' when absent; unreadable refuses)
    * reach `digest` as `files` and join the memo's identity, so an edited
    * patch moves the key (item 1014). A directory (a `file:` dependency the
    * install copies) hashes every file under it but `node_modules` and
@@ -108,18 +108,30 @@ interface Memo {
   edges?: Record<string, LockfileImporter>
 }
 
-/** A root-relative extra file's content hash, '' when absent; a path leaving the root is never read. */
+/**
+ * A root-relative extra file's content hash, '' when absent; a path leaving
+ * the root is never read. One there but unreadable (EACCES, a symlink loop)
+ * refuses, as a settings file does: folded as '', it keyed as no file at all.
+ */
 async function hashExtra(workspaceRoot: string, rel: string): Promise<string> {
   if (path.isAbsolute(rel) || rel.split(/[\\/]/).includes('..')) return 'outside-root'
   const abs = path.join(workspaceRoot, rel)
   try {
     return xxh3hex(await Bun.file(abs).bytes())
   } catch (err) {
-    if ((err as NodeJS.ErrnoException).code === 'EISDIR') return hashDir(abs)
-    return ''
+    const code = (err as NodeJS.ErrnoException).code
+    if (code === 'EISDIR') return hashDir(abs)
+    if (code === 'ENOENT' || code === 'ENOTDIR') return ''
+    throw unreadable(rel, err)
   }
 }
 
+function unreadable(rel: string, err: unknown): UserError {
+  return new UserError(
+    `${rel}: cannot be read (${err instanceof Error ? err.message : String(err)})`,
+  )
+}
+
 /**
  * Every file under `dir` but its `node_modules` and `.git`, as `rel\0hash`
  * lines in sorted order. Links are followed: a linked file is what a task
@@ -322,7 +334,18 @@ export function lockfileClaim(options: LockfileClaimOptions): LockfileClaimHooks
         return names
       },
       ...(options.extraFiles !== undefined
-        ? { extraFiles: (_file: string, bytes: Uint8Array) => options.extraFiles!(decode(bytes)) }
+        ? {
+            // The memo records which files these exact bytes name, for this
+            // parser: `--affected` asks on every diff, and a cold parse of
+            // a large lockfile was most of its selection's cost.
+            async extraFiles(_file: string, bytes: Uint8Array, ctx: FingerprintContext) {
+              const memoFile = path.join(ctx.cacheDir, 'lockfile-claims', `${file}.json`)
+              const memo = await readMemo(memoFile, version, claimant, xxh3hex(bytes))
+              return memo !== undefined
+                ? Object.keys(memo.extras)
+                : options.extraFiles!(decode(bytes))
+            },
+          }
         : {}),
     },
     async key(task, ctx) {
@@ -347,15 +370,22 @@ export function lockfileClaim(options: LockfileClaimOptions): LockfileClaimHooks
  * Node's resolution walking up to the root `node_modules` (`@types/*`,
  * a config's plugins) — so a root devDependency bump that moved only the
  * root's digest replayed the old tool's output (nx#36415 class,
- * 2026-09-24). A project the lockfile has no importer for (outside the
- * workspace's `packages`) folds the root's alone; a file with neither
- * folds a constant.
+ * 2026-09-24). A project the lockfile has no importer for folds its
+ * nearest listed ancestor's, as Node resolves from that ancestor's
+ * `node_modules` (`packages/a/e2e` from `packages/a`'s): the root's alone
+ * keyed it on no bump only `a` reached. Outside every importer it folds
+ * the root's alone; a file with neither folds a constant.
  */
 function digestFor(importers: ReadonlyMap<string, string>, importer: string): string {
-  const own = importers.get(importer)
+  let dir = importer
+  while (dir !== '.' && !importers.has(dir)) {
+    const slash = dir.lastIndexOf('/')
+    dir = slash === -1 ? '.' : dir.slice(0, slash)
+  }
+  const own = importers.get(dir)
   const root = importers.get('.')
   if (own === undefined) return root ?? 'no-importer'
-  if (root === undefined || importer === '.') return own
+  if (root === undefined || dir === '.') return own
   return xxh3hex(`${own}\0${root}`)
 }
 
@@ -423,6 +453,49 @@ function decode(bytes: Uint8Array): string {
 
 // --- Reach digests -----------------------------------------------------------
 
+/**
+ * Each member of a cycle as what it is and where its edges land, by
+ * colour refinement: a member starts as its material and the child
+ * digests its edges leave the cycle for, then folds its in-cycle
+ * targets' labels until no two labels part further. npm and bun key two
+ * copies of one version alike (`a/node_modules/foo` → bar@1,
+ * `node_modules/foo` → bar@2), so by material alone two members swapping
+ * copies, in the cycle or out of it, moved nothing. Two members left with
+ * one label have the same material, reach the same children, and their
+ * in-cycle edges land on labels alike to every depth. Telling such a pair
+ * apart takes an isomorphism test; it needs a cycle where copies of one
+ * version reach alike at every step, which no swap of what one reaches
+ * produces.
+ */
+function cycleLabels(
+  g: ReachGraph,
+  members: readonly number[],
+  childOf: (w: number) => string | undefined,
+): string[] {
+  let label = new Map<number, string>()
+  for (const m of members) {
+    const out = new Set<string>()
+    for (const w of g.edges[m]!) {
+      const child = w === m ? undefined : childOf(w)
+      if (child !== undefined) out.add(child)
+    }
+    label.set(m, xxh3hex(`${g.material[m]!}\0${[...out].sort().join('\0')}`))
+  }
+  let parts = new Set(label.values()).size
+  for (;;) {
+    const next = new Map<number, string>()
+    for (const m of members) {
+      const inner = new Set<string>()
+      for (const w of g.edges[m]!) if (w !== m && label.has(w)) inner.add(label.get(w)!)
+      next.set(m, xxh3hex(`${label.get(m)!}\0${[...inner].sort().join('\0')}`))
+    }
+    label = next
+    const now = new Set(label.values()).size
+    if (now === parts) return members.map((m) => label.get(m)!)
+    parts = now
+  }
+}
+
 /** A dependency graph: one material string per node and its out-edges by index. */
 export interface ReachGraph {
   readonly material: readonly string[]
@@ -493,11 +566,18 @@ export function reachDigests(g: ReachGraph): string[] {
       // share one digest, so retargeting an edge between two of them (an
       // importer's `y@1.0.0` → `y@1.1.0` inside one cycle) moved nothing
       // and replayed a stale output (item 1013). A self-loop reaches
-      // nothing new and is left out.
-      const lines = members.map((m) => {
-        const targets = [...new Set(g.edges[m]!.filter((w) => w !== m).map((w) => g.material[w]!))]
-        return `${g.material[m]!}\0${targets.sort().join('\0')}`
-      })
+      // nothing new and is left out. A singleton's children already say
+      // where its edges land, and its line stays as it was, so an acyclic
+      // digest keeps its value.
+      const lines =
+        members.length === 1
+          ? members.map((m) => {
+              const targets = [
+                ...new Set(g.edges[m]!.filter((w) => w !== m).map((w) => g.material[w]!)),
+              ]
+              return `${g.material[m]!}\0${targets.sort().join('\0')}`
+            })
+          : cycleLabels(g, members, (w) => (comp[w] === id ? undefined : compHash[comp[w]!]!))
       let h = xxh3(`members:${members.length}`)
       for (const line of lines.sort()) h = xxh3(`${line}\n`, h)
       h = xxh3(`children:${children.size}`, h)

package/src/orchestrator/miss-save.ts

@@ -7,7 +7,7 @@
 // a later run replays. Moved out of execute-task.ts 2026-09-09 as pure
 // code motion.
 
-import { lstatSync, realpathSync, statSync } from 'node:fs'
+import { existsSync, lstatSync, realpathSync, statSync } from 'node:fs'
 import path from 'node:path'
 import {
   type CacheLayer,
@@ -16,6 +16,7 @@ import {
   outputWalkTakes,
   resolveOutputs,
   resolveWorkspaceOutputs,
+  resolveWorkspaceOutputTree,
   WORKSPACE_OUTPUT_PREFIX,
 } from '../cache/index.js'
 import type { TaskNode } from '../graph/index.js'
@@ -166,12 +167,11 @@ export async function saveMiss(a: SaveMissArgs): Promise<{ landed: Promise<SaveF
           nestedProjectDirs: a.nestedProjectDirs,
         })
   const outputFiles = tree.files
-  const wsOutputFiles =
-    a.ownWsOutputFiles ??
-    (await resolveWorkspaceOutputs({
-      workspaceRoot: a.workspaceRoot,
-      outputs: a.wsOutputs,
-    }))
+  const wsTree =
+    a.ownWsOutputFiles !== undefined
+      ? { files: a.ownWsOutputFiles, emptyDirs: [] }
+      : await resolveWorkspaceOutputTree({ workspaceRoot: a.workspaceRoot, outputs: a.wsOutputs })
+  const wsOutputFiles = wsTree.files
   endResolve()
   // The mirror of the input warning: declared outputs that resolve to
   // nothing save an empty artifact, and the next hit "restores" it —
@@ -202,7 +202,11 @@ export async function saveMiss(a: SaveMissArgs): Promise<{ landed: Promise<SaveF
           ? ` — ${linkedOut.dir} is a symlink to ${linkedOut.target}, outside ${linkedOut.base}, and vx keeps only outputs inside it: make ${linkedOut.dir} a directory`
           : sandboxed && !grantsWrite
             ? ` — the task is sandboxed and declares no exec.sandbox.allow.write, so its writes never reached disk`
-            : ''),
+            : '') +
+        bracketLiteralHint([
+          ...a.outputs.map((g) => [node.projectDir, g] as const),
+          ...a.wsOutputs.map((g) => [a.workspaceRoot, g] as const),
+        ]),
     )
   }
   const facts: SaveFacts = {}
@@ -220,6 +224,7 @@ export async function saveMiss(a: SaveMissArgs): Promise<{ landed: Promise<SaveF
       // The root an output symlink's target must stay inside, outputs.workspaceFiles or not.
       workspaceRoot: a.workspaceRoot,
       ...(wsOutputFiles.length > 0 ? { workspaceOutputFiles: wsOutputFiles } : {}),
+      ...(wsTree.emptyDirs.length > 0 ? { workspaceOutputDirs: wsTree.emptyDirs } : {}),
       inputComponents: a.captured.map((c) => ({ entryHash: a.hash, ...c })),
       // No `exitCode`: the save only runs under `effectiveExitCode === 0`, and
       // the contract no longer accepts one — so the invariant is enforced by
@@ -386,3 +391,32 @@ function realpathOrNull(p: string): string | null {
     return null
   }
 }
+
+/**
+ * The clause a "matched no files" warning gains when a glob holds an
+ * unescaped `[` and, read as a literal path, names something on disk:
+ * `app/[slug]/page.tsx` is a character class (caching.md) that matches
+ * no route, so the key stops following the file and an edit replays the
+ * old output. Only on the already-empty path; one stat per such glob, on
+ * its literal prefix up to the first segment holding another glob token.
+ */
+export function bracketLiteralHint(
+  globs: readonly (readonly [base: string, glob: string])[],
+): string {
+  let hint = ''
+  for (const [base, glob] of globs) {
+    if (glob.startsWith('!') || !/(^|[^\\])\[/.test(glob)) continue
+    const segments: string[] = []
+    for (const seg of glob.split('/')) {
+      if (/(^|[^\\])[*?{}]/.test(seg)) break
+      segments.push(seg)
+    }
+    const prefix = segments.join('/')
+    if (!/(^|[^\\])\[/.test(prefix)) continue
+    const literal = prefix.replace(/\\(.)/g, '$1')
+    if (!existsSync(path.join(base, literal))) continue
+    const escaped = glob.replace(/(^|[^\\])(?=[[\]])/g, '$1\\')
+    hint += ` — [ starts a character class and ${literal} exists: write ${escaped} to name it`
+  }
+  return hint
+}

package/src/orchestrator/options.ts

@@ -84,12 +84,12 @@ export interface RunOptions {
    */
   cacheFlags?: CacheFlags
   /**
-   * The caller asked for a remote axis by name (`--cache-policy=remote:rw`). With
-   * no cache plugin supplying a remote layer the axes are inert, and a CI
-   * job that believes it is filling a shared cache deserves one line
-   * saying it is not.
+   * The setting that asked for a remote axis by name (`'--cache-policy'` for
+   * `--cache-policy=remote:rw`), named in the warning. With no cache plugin
+   * supplying a remote layer the axes are inert, and a CI job that believes
+   * it is filling a shared cache deserves one line saying it is not.
    */
-  remoteRequested?: boolean
+  remoteRequested?: string
   /** This run's cache scope, above `VX_CACHE_SCOPE`, a plugin's and the branch's (an embedder's). */
   cacheScope?: string
   /**
@@ -205,7 +205,9 @@ export interface RunOptions {
    * never-started ones `aborted`. The seam for an embedder that owns its
    * process's lifetime instead of `handleSignals` — the watch loop aborts
    * its in-flight cycle on SIGINT/SIGTERM this way, so a cancellation
-   * never orphans a cycle's children.
+   * never orphans a cycle's children. A reason naming a signal
+   * (`'SIGINT'`, `'SIGTERM'`, `'SIGHUP'`) is a stop as vx's own handler
+   * makes one: the run records no history, only what finished.
    */
   signal?: AbortSignal
   /**

package/src/orchestrator/output-host.ts

@@ -4,10 +4,12 @@
 
 import { terminalSubscriber, type RunEventSubscriber } from '../report/index.js'
 import type { Logger } from '../report/index.js'
+import { settleWithin, teardownTimeoutMs, thrownMessage } from '../util/index.js'
 import type { OutputContext, VxPlugin } from './plugin.js'
 
 const REQUIRED = ['status', 'taskStdout', 'taskStderr', 'taskComplete'] as const
 const OPTIONAL = [
+  'warn',
   'runStart',
   'taskStart',
   'runEnd',
@@ -26,14 +28,17 @@ function checkLogger(value: unknown): Logger {
   const missing = REQUIRED.filter((k) => typeof o[k] !== 'function')
   if (missing.length > 0) throw new Error(`output Logger has no ${missing.join(', ')}`)
   const wrong = OPTIONAL.filter((k) => o[k] !== undefined && typeof o[k] !== 'function')
-  if (wrong.length > 0) throw new Error(`output Logger's ${wrong.join(', ')} must be functions`)
+  if (wrong.length > 0)
+    throw new Error(
+      `output Logger's ${wrong.join(', ')} must be ${wrong.length === 1 ? 'a function' : 'functions'}`,
+    )
   return value as Logger
 }
 
 /**
  * The first plugin, in declaration order, whose `output` returns a Logger.
- * A hook that throws or returns something else is warned about and passed
- * over: a renderer must never fail a run.
+ * A hook that throws, returns something else or does not answer in time
+ * is warned about and passed over: a renderer must never fail a run.
  */
 export async function claimOutput(
   plugins: readonly VxPlugin[],
@@ -42,12 +47,20 @@ export async function claimOutput(
   for (const plugin of plugins) {
     if (plugin.output === undefined) continue
     try {
-      const logger = await plugin.output(ctx)
+      // Bounded as telemetry's hook is: one that never settled held the
+      // run before its first task until the loop drained, exit 1 (item 921).
+      let logger: Logger | undefined
+      const ms = teardownTimeoutMs()
+      const arrived = await settleWithin(
+        Promise.resolve(plugin.output(ctx)).then((l) => {
+          logger = l
+        }),
+        ms,
+      )
+      if (!arrived) throw new Error(`did not answer within ${ms} ms`)
       if (logger !== undefined) return { logger: checkLogger(logger), owner: plugin.name }
     } catch (err) {
-      ctx.warn(
-        `[vx] plugin '${plugin.name}' output: ${err instanceof Error ? err.message : String(err)}; vx renders the run`,
-      )
+      ctx.warn(`[vx] plugin '${plugin.name}' output: ${thrownMessage(err)}; vx renders the run`)
     }
   }
   return undefined
@@ -62,19 +75,35 @@ export function guardedOutput(
   claimed: { logger: Logger; owner: string },
   fallback: RunEventSubscriber,
 ): RunEventSubscriber {
-  const render = terminalSubscriber(claimed.logger)
   let failed = false
+  const fail = (err: unknown): void => {
+    if (failed) return
+    failed = true
+    fallback({
+      kind: 'run:status',
+      warn: true,
+      line: `[vx] plugin '${claimed.owner}' output failed: ${thrownMessage(err)}; vx renders the rest of the run`,
+    })
+  }
+  // An `async` method's rejection reached no one: an unhandled rejection
+  // ended the run with a stack, exit 1, after its tasks had passed. It
+  // fails the Logger as a throw does; the event it was handed stays its.
+  const logger = Object.create(claimed.logger) as Logger
+  for (const k of [...REQUIRED, ...OPTIONAL, 'warn'] as const) {
+    const method = claimed.logger[k] as ((...args: unknown[]) => unknown) | undefined
+    if (typeof method !== 'function') continue
+    ;(logger as unknown as Record<string, unknown>)[k] = (...args: unknown[]): void => {
+      const ret = method.apply(claimed.logger, args)
+      if (ret instanceof Promise) ret.catch(fail)
+    }
+  }
+  const render = terminalSubscriber(logger)
   return (event) => {
     if (failed) return fallback(event)
     try {
       render(event)
     } catch (err) {
-      failed = true
-      fallback({
-        kind: 'run:status',
-        warn: true,
-        line: `[vx] plugin '${claimed.owner}' output failed: ${err instanceof Error ? err.message : String(err)}; vx renders the rest of the run`,
-      })
+      fail(err)
       fallback(event)
     }
   }