@vzn/vx 0.0.15 → 0.0.18

package/src/orchestrator/upstream.ts

@@ -24,11 +24,12 @@ import { UserError } from '../util/index.js'
  *   'name'      same-project task `name`
  *   '^name'     `name` task in every dep workspace
  *   'pkg#name'  specific package's `name` task
- *   'name.*'    task-NAME patterns — the task half of any form above may
- *               contain `*` (same glob as dependsOn patterns). A filter
- *               that matched literally here while dependsOn expanded the
- *               same string would silently select ZERO upstream hashes —
- *               a stale-hit trap, so the two surfaces share the matcher.
+ *   'name.*'    patterns — EITHER half of any form above may contain `*`
+ *               (same glob as dependsOn patterns), including the project
+ *               half of `pkg#name`. A filter that matched literally here
+ *               would silently select ZERO upstream hashes and decouple the
+ *               task from its dependencies — a stale-hit trap, so every
+ *               name is matched through the shared glob.
  *   '!<form>'   exclude — any of the above with a leading `!`
  *
  * Patterns are applied in order; last write wins, so
@@ -69,19 +70,19 @@ export function filterUpstreamHashes(
     }
   })
 
-  // Per-spec task-name matcher, compiled once (exact compare or pattern).
-  const matchers = specs.map((spec) => taskMatcher(spec))
+  // Per-spec predicate, compiled once (exact compares + patterns).
+  const matchers = specs.map((spec) => specMatcher(spec))
 
   // Dedup by hash (the key fold's unit), but remember the first task id
   // seen for each hash so the diff row can name the upstream.
   const selected = new Map<string, string>()
   for (let i = 0; i < specs.length; i++) {
     const spec = specs[i]!
-    const taskMatches = matchers[i]!
+    const matches = matchers[i]!
     for (const u of upstream) {
       if (!u.hash) continue
       const isSelf = u.node.projectName === selfProjectName
-      if (!matches(spec, u, isSelf, taskMatches)) continue
+      if (!matches(u, isSelf)) continue
       if (spec.negated) selected.delete(u.hash)
       else if (!selected.has(u.hash)) selected.set(u.hash, u.node.id)
     }
@@ -89,33 +90,73 @@ export function filterUpstreamHashes(
   return [...selected].map(([hash, id]) => [id, hash])
 }
 
-/** Exact-name compare, or the shared `*`-glob when the form is a pattern. */
-function taskMatcher(spec: DependencySpec): (name: string) => boolean {
-  if (spec.kind === 'wildcardSelf' || spec.kind === 'wildcardDeps') return () => true
-  if (isTaskPattern(spec.task)) {
-    const re = compileTaskPattern(spec.task)
-    return (name) => re.test(name)
+/**
+ * Expand any GROUP among these outcomes into the real tasks it stands for,
+ * transitively, preserving order and de-duplicating by task id.
+ *
+ * A group has no `exec`, so it has no outputs and no cache entry — its hash
+ * is a synthetic roll-up. A dependent that asked the local index what its
+ * upstream produced therefore got an EMPTY output list for a group, which is
+ * invisible locally (the members' outputs are already on disk, put there by
+ * their own tasks) and fatal for an input-shipping executor, where that list
+ * IS the input root: `dependsOn: ['install']` shipped a worker an action with
+ * none of what `install` chains.
+ *
+ * Groups may nest, so the walk recurses. Only what the FILTER already
+ * selected is passed in, so a group excluded from a task's
+ * `cache.inputs.tasks` brings no members with it.
+ */
+export function expandGroupUpstream(upstream: readonly TaskOutcome[]): TaskOutcome[] {
+  const out: TaskOutcome[] = []
+  const seen = new Set<string>()
+  const walk = (list: readonly TaskOutcome[]): void => {
+    for (const u of list) {
+      if (u.groupUpstream !== undefined) {
+        walk(u.groupUpstream)
+        continue
+      }
+      if (seen.has(u.node.id)) continue
+      seen.add(u.node.id)
+      out.push(u)
+    }
+  }
+  walk(upstream)
+  return out
+}
+
+/** Exact-name compare, or the shared `*`-glob when the name is a pattern. */
+function nameMatcher(name: string): (candidate: string) => boolean {
+  if (isTaskPattern(name)) {
+    const re = compileTaskPattern(name)
+    return (candidate) => re.test(candidate)
   }
-  const exact = spec.task
-  return (name) => name === exact
+  return (candidate) => candidate === name
 }
 
-function matches(
-  spec: DependencySpec,
-  u: TaskOutcome,
-  isSelf: boolean,
-  taskMatches: (name: string) => boolean,
-): boolean {
+/**
+ * Compile one spec into an upstream predicate. BOTH halves of a `pkg#task`
+ * form glob: a filter only ever selects from upstreams that already exist,
+ * so a package pattern is unambiguous here — unlike dependsOn, which must
+ * materialize concrete edges and therefore rejects it.
+ */
+function specMatcher(spec: DependencySpec): (u: TaskOutcome, isSelf: boolean) => boolean {
   switch (spec.kind) {
     case 'wildcardSelf':
-      return isSelf
+      return (_u, isSelf) => isSelf
     case 'wildcardDeps':
-      return !isSelf
-    case 'self':
-      return isSelf && taskMatches(u.node.taskName)
-    case 'deps':
-      return !isSelf && taskMatches(u.node.taskName)
-    case 'cross':
-      return u.node.projectName === spec.project && taskMatches(u.node.taskName)
+      return (_u, isSelf) => !isSelf
+    case 'self': {
+      const task = nameMatcher(spec.task)
+      return (u, isSelf) => isSelf && task(u.node.taskName)
+    }
+    case 'deps': {
+      const task = nameMatcher(spec.task)
+      return (u, isSelf) => !isSelf && task(u.node.taskName)
+    }
+    case 'cross': {
+      const project = nameMatcher(spec.project)
+      const task = nameMatcher(spec.task)
+      return (u) => project(u.node.projectName) && task(u.node.taskName)
+    }
   }
 }

package/src/orchestrator/verify.ts

@@ -52,7 +52,7 @@ export async function hashOutputTree(refs: readonly OutputRef[]): Promise<Map<st
 
 /** Per-file map cap on a shipped fingerprint (~40 KB at the cap). The tree
  *  digest always folds ALL entries, so detection never depends on the map. */
-export const FP_MAX_FILES = 500
+const FP_MAX_FILES = 500
 
 /** Roll an output-tree fingerprint map into the shippable `OutputFingerprint`
  *  payload (Phase 4, cross-machine diff): a tree digest over ALL sorted
@@ -101,7 +101,12 @@ export function undeclaredInputPaths(
 ): string[] {
   const rels = new Set<string>()
   for (const v of violations) {
-    const m = /\[([^\]]+)\]\s*$/.exec(v.line)
+    // Two wire shapes: Linux strace lines carry `[path]`; macOS
+    // sandbox-exec lines end in a bare absolute path
+    // (`node(123) deny(1) file-read-data /abs/path`). Fall back to the
+    // raw line only when neither parses — a path the user can act on
+    // beats a log line every time.
+    const m = /\[([^\]]+)\]\s*$/.exec(v.line) ?? /\s(\/\S+)\s*$/.exec(v.line)
     const raw = m ? m[1]! : v.line
     rels.add(
       path.isAbsolute(raw) ? path.relative(workspaceRoot, raw).split(path.sep).join('/') : raw,
@@ -138,6 +143,9 @@ export function formatVerifySection(outcomes: readonly TaskOutcome[]): string[]
       case 'not-verified':
         notVerified++
         break
+      case 'unverifiable-remote-only':
+        na++
+        break
     }
   }
   const lines = [
@@ -156,6 +164,8 @@ export function formatVerifySection(outcomes: readonly TaskOutcome[]): string[]
       lines.push('        add them to cache.inputs.files / workspaceFiles')
     } else if (v.kind === 'rerun-failed') {
       lines.push(`    ✗ ${o.node.id} — verify re-run failed (exit ${v.exitCode})`)
+    } else if (v.kind === 'unverifiable-remote-only') {
+      lines.push(`    ⚠ ${o.node.id} — remote-only: no local execution to prove (unverified)`)
     } else if (v.kind === 'allowed-nondeterministic') {
       lines.push(`    ⚠ ${o.node.id} — nondeterministic (allowed)`)
     }

package/src/plugins/local-cache/index.ts

@@ -0,0 +1,11 @@
+// Core's cache as a plugin: the `.vx/cache` handle the host opened (the run
+// index + the local artifact store). Declared like any other cache layer;
+// put a remote layer BEFORE it to look there first.
+
+import type { VxPlugin } from '@vzn/vx'
+
+export const LOCAL_CACHE_PLUGIN = 'vx/local-cache'
+
+export function localCachePlugin(): VxPlugin {
+  return { name: LOCAL_CACHE_PLUGIN, cache: (ctx) => ctx.localCache }
+}

package/src/plugins/local-executor/index.ts

@@ -0,0 +1,45 @@
+// Core's executor as a plugin: spawn the task's command in-process, exactly
+// the `runCommand` / `runSandboxed` call the orchestrator used to make
+// directly. Imports core only through the public `@vzn/vx` surface so this
+// directory can become its own package unchanged.
+
+import { runCommand, runSandboxed, type TaskExecutor, type VxPlugin } from '@vzn/vx'
+
+export const LOCAL_EXECUTOR_PLUGIN = 'vx/local-executor'
+
+/** The executor itself — for tests and for plugins that wrap local execution. */
+export function localExecutor(): TaskExecutor {
+  return {
+    name: 'local',
+    async execute(req) {
+      const common = {
+        command: req.command,
+        cwd: req.cwd,
+        env: req.env,
+        forwardArgs: req.forwardArgs,
+        onStdout: req.onStdout,
+        onStderr: req.onStderr,
+        capture: req.capture,
+        ...(req.liveChildren !== undefined ? { liveChildren: req.liveChildren } : {}),
+        ...(req.timeoutMs !== undefined ? { timeoutMs: req.timeoutMs } : {}),
+      }
+      if (req.sandbox === undefined) {
+        const res = await runCommand(common)
+        return { ...res, violations: [] }
+      }
+      return await runSandboxed({
+        ...common,
+        baseAllowRead: req.sandbox.baseAllowRead,
+        baseAllowWrite: req.sandbox.baseAllowWrite,
+        baseDenyRead: req.sandbox.baseDenyRead,
+        config: req.sandbox.config,
+        settleOnCleanExit: req.sandbox.settleOnCleanExit,
+      })
+    },
+  }
+}
+
+/** Declare in vx.workspace.ts: `plugins: [localExecutorPlugin(), …]`. Accepts every task. */
+export function localExecutorPlugin(): VxPlugin {
+  return { name: LOCAL_EXECUTOR_PLUGIN, executor: () => localExecutor() }
+}

package/src/plugins/schedule-history/index.ts

@@ -0,0 +1,109 @@
+// History-based scheduling as a plugin: order ready tasks by their expected
+// REMAINING critical-path duration (own p50 + the longest chain of
+// dependents), learned from the local run history. This was core's opt-in
+// `predictive` mode until 2026-09-02; it is the reference `schedule` plugin
+// now — declared like any other, and paying its history read only in
+// workspaces that ask for it.
+//
+// Cache hits are NOT modelled as zero-cost: predicting cache state needs
+// the key and a probe, which the scheduler handles at run time (a confirmed
+// hit is backfill, never a critical-path task). The estimate here is "what
+// if everything ran", which is exactly the case where order matters.
+
+import { LocalHistoryProvider, type HistoryTable, type TaskNode, type VxPlugin } from '@vzn/vx'
+
+const SCHEDULE_HISTORY_PLUGIN = 'vx/schedule-history'
+
+/** Default duration when neither task history nor a workspace median exists. */
+const DEFAULT_DURATION_MS = 1000
+
+export interface ScheduleHistoryOptions {
+  /** How many recent runs per task to learn from. Default 20. */
+  readonly window?: number
+}
+
+export function scheduleHistoryPlugin(options: ScheduleHistoryOptions = {}): VxPlugin {
+  return {
+    name: SCHEDULE_HISTORY_PLUGIN,
+    async schedule(nodes, ctx) {
+      const provider =
+        options.window === undefined
+          ? new LocalHistoryProvider(ctx.localCache.dbHandle())
+          : new LocalHistoryProvider(ctx.localCache.dbHandle(), options.window)
+      let table: HistoryTable
+      try {
+        table = await provider.loadFor([...nodes.keys()])
+      } catch (err) {
+        // Failing open: a broken history read costs the ordering, never the run.
+        ctx.warn(
+          `[vx] schedule-history: falling back to the baseline order: ${err instanceof Error ? err.message : String(err)}`,
+        )
+        return undefined
+      }
+      return criticalPathPriorities([...nodes.values()], table)
+    },
+  }
+}
+
+/**
+ * For each node, the expected remaining critical-path duration: its own p50
+ * plus the maximum over its dependents. A node with no history takes the
+ * workspace median; an empty history takes a flat default.
+ */
+export function criticalPathPriorities(
+  nodes: readonly TaskNode[],
+  history: HistoryTable,
+): ReadonlyMap<string, number> {
+  const p50s: number[] = []
+  for (const h of history.values()) {
+    if (h.p50DurationMs !== undefined) p50s.push(h.p50DurationMs)
+  }
+  p50s.sort((a, b) => a - b)
+  const workspaceMedian =
+    p50s.length > 0
+      ? (p50s[Math.floor(p50s.length / 2)] ?? DEFAULT_DURATION_MS)
+      : DEFAULT_DURATION_MS
+
+  const dependentsOf = new Map<string, string[]>()
+  for (const n of nodes) {
+    for (const upstreamId of n.deps) {
+      const list = dependentsOf.get(upstreamId)
+      if (list) list.push(n.id)
+      else dependentsOf.set(upstreamId, [n.id])
+    }
+  }
+  const ownDuration = (n: TaskNode): number => history.get(n.id)?.p50DurationMs ?? workspaceMedian
+
+  // Reverse-topological pass: a node's value is final once every dependent's
+  // is, so start from the sinks (no dependents) and release each upstream
+  // when its last dependent has been scored.
+  const memo = new Map<string, number>()
+  const nodeById = new Map<string, TaskNode>(nodes.map((n) => [n.id, n]))
+  const pending = new Map<string, number>()
+  const queue: TaskNode[] = []
+  for (const n of nodes) {
+    const count = dependentsOf.get(n.id)?.length ?? 0
+    pending.set(n.id, count)
+    if (count === 0) queue.push(n)
+  }
+  let head = 0
+  while (head < queue.length) {
+    const n = queue[head++]!
+    let downstream = 0
+    for (const dep of dependentsOf.get(n.id) ?? []) {
+      const d = memo.get(dep) ?? 0
+      if (d > downstream) downstream = d
+    }
+    memo.set(n.id, ownDuration(n) + downstream)
+    for (const up of n.deps) {
+      const left = (pending.get(up) ?? 0) - 1
+      pending.set(up, left)
+      if (left === 0) {
+        const upNode = nodeById.get(up)
+        if (upNode) queue.push(upNode)
+      }
+    }
+  }
+  for (const n of nodes) if (!memo.has(n.id)) memo.set(n.id, ownDuration(n))
+  return memo
+}

package/src/util/edit-distance.ts

@@ -0,0 +1,21 @@
+/**
+ * Levenshtein distance, capped: anything past two edits reads as 3. Used
+ * by the "did you mean" hints for task names and flags, where a hint
+ * beyond two edits would guess rather than help.
+ */
+export function editDistance(a: string, b: string): number {
+  if (Math.abs(a.length - b.length) > 2) return 3
+  let prev = Array.from({ length: b.length + 1 }, (_, i) => i)
+  for (let i = 1; i <= a.length; i++) {
+    const cur = [i]
+    for (let j = 1; j <= b.length; j++) {
+      cur[j] = Math.min(
+        prev[j]! + 1,
+        cur[j - 1]! + 1,
+        prev[j - 1]! + (a[i - 1] === b[j - 1] ? 0 : 1),
+      )
+    }
+    prev = cur
+  }
+  return Math.min(prev[b.length]!, 3)
+}

package/src/util/errors.ts

@@ -1,7 +1,7 @@
 // Shared error types used across modules to distinguish user-input
 // failures (clean message only) from internal bugs (full stack trace).
 //
-// `bin.ts` consults `instanceof UserError` to decide what to print.
+// `bin.ts` and the scheduler consult `isUserError` to decide what to print.
 
 export class UserError extends Error {
   constructor(message: string) {
@@ -9,3 +9,17 @@ export class UserError extends Error {
     this.name = 'UserError'
   }
 }
+
+/**
+ * `instanceof UserError`, plus the same class arriving from ANOTHER COPY of
+ * core. A compiled `vx` binary carries core inside it while a plugin in the
+ * workspace imports `@vzn/vx` from node_modules, so a plugin's `UserError`
+ * is a different class object and `instanceof` is false — a plugin verb's
+ * "bad flag --x" printed as `UserError: bad flag --x` with a stack, and a
+ * REAPI refusal would have read as an "internal error" (reproduced through
+ * the real binary, 2026-09-03). The name is the contract that survives the
+ * copy boundary.
+ */
+export function isUserError(err: unknown): err is UserError {
+  return err instanceof UserError || (err instanceof Error && err.name === 'UserError')
+}

package/src/util/index.ts

@@ -1,8 +1,13 @@
 // Module contract. Cross-module imports must come through here; see
 // docs/design/module-isolation-2026-06.md and tests/module-boundaries.test.ts.
 
-export { UserError } from './errors.js'
+export { isUserError, UserError } from './errors.js'
 export { xxh3, xxh3hex } from './hash.js'
-export { relPosix } from './paths.js'
+export { mark, printTimings, span } from './timing.js'
+export { clampInt, MAX_TIMEOUT_MS, parseDecimalInt } from './num.js'
+export { relPosix, staticPrefix, wholeSubtreePrefixes } from './paths.js'
+export { settleWithin, teardownTimeoutMs } from './settle.js'
 export { parseSize } from './size.js'
+export { appendTail, createTail, resetTail, tailText, type Tail } from './tail.js'
 export { ulid } from './ulid.js'
+export { editDistance } from './edit-distance.js'

package/src/util/num.ts

@@ -0,0 +1,37 @@
+/**
+ * The largest delay `setTimeout` actually honours: 2^31 - 1 ms (~24.8 days).
+ *
+ * A larger delay does NOT saturate and does NOT throw — it silently becomes
+ * **1 ms**, which is the exact INVERSE of what the caller asked for. A task
+ * declaring a 317-year timeout is SIGTERMed 4 ms after it spawns and reported
+ * `failed`, and the only clue is a `TimeoutOverflowWarning` on stderr that a CI
+ * log swallows. Every surface that accepts a millisecond delay bounds it
+ * against this, so "effectively no limit" can never mean "kill immediately".
+ */
+export const MAX_TIMEOUT_MS = 2 ** 31 - 1
+
+/**
+ * Clamp to an INTEGER in `[min, max]`; a non-finite value collapses to `min`.
+ *
+ * The floor is load-bearing wherever the result reaches SQL: a fractional
+ * `LIMIT` is a `datatype mismatch` error, not a smaller page.
+ */
+export function clampInt(n: number, min: number, max: number): number {
+  if (!Number.isFinite(n)) return min
+  return Math.min(max, Math.max(min, Math.floor(n)))
+}
+
+/**
+ * Parse a PLAIN decimal integer from user input; `null` for anything else.
+ *
+ * `Number()` is the wrong tool at an argument boundary: it silently accepts
+ * hex (`0x10` → 16), exponents (`1e3` → 1000), fractions, a leading `+`, and
+ * surrounding whitespace — so a typo becomes a different number instead of an
+ * error. Values past `Number.MAX_SAFE_INTEGER` are rejected too: they parse to
+ * a number the user did not type (`9007199254740993` → `…92`).
+ */
+export function parseDecimalInt(input: string): number | null {
+  if (!/^\d+$/.test(input)) return null
+  const n = Number(input)
+  return Number.isSafeInteger(n) ? n : null
+}

package/src/util/paths.ts

@@ -14,3 +14,46 @@ export function toPosix(p: string): string {
 export function relPosix(from: string, to: string): string {
   return toPosix(path.relative(from, to))
 }
+
+/**
+ * The leading, wildcard-free part of a glob, trimmed back to whole path
+ * components (`dist/sub-**` → `dist`). `.` when the first component is
+ * already a wildcard, i.e. the glob can reach anything in its anchor dir.
+ *
+ * Two callers with different needs share it deliberately: the sandbox
+ * baseline joins it onto a dir to get a write prefix, and the deferral
+ * eligibility gate compares two of them for overlap. A second copy is
+ * how the two would disagree about what a prefix is.
+ */
+export function staticPrefix(glob: string): string {
+  const wildcardIdx = glob.search(/[*?[\]]/)
+  if (wildcardIdx === -1) return glob
+  const head = glob.slice(0, wildcardIdx)
+  const lastSep = head.lastIndexOf('/')
+  if (lastSep === -1) return '.'
+  return head.slice(0, lastSep) || '/'
+}
+
+/**
+ * The directories a task's declared outputs cover WHOLE — every glob is
+ * `<dir>/**` with a plain, non-root, non-escaping `<dir>` — or `null` when
+ * any glob is shaped otherwise. The directory-mtime short-circuit on a warm
+ * hit (`Cache.outputDirsCurrent`) is sound only for whole subtrees: with
+ * every directory under `<dir>` recorded, a file added or removed anywhere
+ * the glob could see bumps a recorded directory's mtime (its parent, or a
+ * new directory whose creation bumped a recorded ancestor). A root-anchored
+ * `**\/*.js` has no such closed set, so it keeps the walk.
+ */
+export function wholeSubtreePrefixes(globs: readonly string[]): string[] | null {
+  if (globs.length === 0) return null
+  const out: string[] = []
+  for (const g of globs) {
+    const m = /^([^*?[\]{}!]+?)\/\*\*$/.exec(g)
+    if (m === null) return null
+    const dir = m[1]!.replace(/\/+$/, '')
+    if (dir === '' || dir === '.' || dir.startsWith('/') || dir.split('/').includes('..'))
+      return null
+    out.push(dir)
+  }
+  return [...new Set(out)]
+}

package/src/util/settle.ts

@@ -0,0 +1,48 @@
+// End-of-run settle bound. A plugin's flush/teardown is I/O a third party
+// wrote; it must not hold the run's exit hostage.
+
+import { MAX_TIMEOUT_MS } from './num.js'
+
+/** Default upper bound on one end-of-run flush/teardown await. */
+const DEFAULT_TIMEOUT_MS = 3000
+
+/**
+ * The bound to apply, read per call so a test can drive the deadline
+ * instead of waiting it out.
+ */
+export function teardownTimeoutMs(): number {
+  const raw = process.env['VX_TEARDOWN_TIMEOUT_MS']
+  // Out-of-range falls back to the DEFAULT rather than clamping to
+  // MAX_TIMEOUT_MS, and the distinction matters. This value is a BOUND, not a
+  // duration: there is no "no limit" option here, because the whole reason the
+  // deadline exists is that a plugin's flush must not hold the run's exit
+  // hostage. Clamping would honour "wait ~24.8 days", which defeats it — the
+  // run would hang. Unbounded is worse still (the delay becomes 1 ms, so every
+  // flush times out and every buffered record is dropped). Falling back keeps
+  // the bound real in both directions.
+  if (raw !== undefined && /^[0-9]+$/.test(raw)) {
+    const n = Number(raw)
+    if (n <= MAX_TIMEOUT_MS) return n
+  }
+  return DEFAULT_TIMEOUT_MS
+}
+
+/**
+ * Await `p`, giving up after `ms`. Returns true when `p` settled first,
+ * false when the deadline won — the caller decides whether a lost result
+ * is worth reporting.
+ */
+export async function settleWithin(p: Promise<unknown>, ms: number): Promise<boolean> {
+  let timer: ReturnType<typeof setTimeout> | undefined
+  const deadline = new Promise<false>((resolve) => {
+    timer = setTimeout(() => resolve(false), ms)
+  })
+  try {
+    return (await Promise.race([p.then(() => true), deadline])) !== false
+  } finally {
+    clearTimeout(timer)
+    // A rejection landing after the deadline won already resolved the
+    // race must not surface as an unhandled-rejection crash.
+    void p.catch(() => {})
+  }
+}

package/src/util/size.ts

@@ -1,3 +1,5 @@
+import { parseDecimalInt } from './num.js'
+
 /**
  * Parse a byte-size string: a bare integer (`"1048576"`) or an integer
  * with a K/M/G/T suffix, powers of 1024, optional trailing `B`
@@ -8,7 +10,9 @@
 export function parseSize(input: string): number | null {
   const m = input.match(/^(\d+)([KMGT])?B?$/i)
   if (!m) return null
-  const n = Number(m[1])
+  // Digits past 2^53 parse to a different number than the user typed.
+  const n = parseDecimalInt(m[1]!)
+  if (n === null) return null
   const u = (m[2] ?? '').toUpperCase()
   const mult =
     u === '' ? 1 : u === 'K' ? 1024 : u === 'M' ? 1024 * 1024 : u === 'G' ? 1024 ** 3 : 1024 ** 4

package/src/util/tail.ts

@@ -0,0 +1,66 @@
+// Bounded head-evicting tail for one stream of one still-running task.
+//
+// A PERSISTENT task (dev server, watcher, daemon) is unbounded by
+// construction: unlike a one-shot command, nothing about it terminating
+// bounds how much it writes. Anything that accumulates its output therefore
+// needs a cap, and the cap has to be honest — a truncated log that reads as
+// complete is worse than one that says what it lost.
+//
+// `orchestrator/logger.ts` is the sole holder: it registers a tail per
+// persistent task at taskStart and keeps one for the rest of the run, so a
+// single mechanism covers both the pre-ready window and everything after.
+// `exec/runner.ts` used to keep a SECOND pre-ready copy fed from the same
+// chunks that nothing ever read; it was deleted rather than kept in sync,
+// since two copies of this rule is how they drift — one grew a bound and
+// the other did not, which is the defect this file was extracted to close
+// (a never-ready `readyWhen` grew vx's heap ~100 MiB/s with the 64 KiB cap
+// sitting unused, because it was only ever engaged once the task became
+// ready). It stays in `util` because `exec` cannot import `orchestrator`,
+// so a future second holder on that side has somewhere to import from.
+
+/** Per-stream cap on retained output for a task that may never end. */
+export const PERSISTENT_TAIL_CHARS = 64 * 1024
+
+export interface Tail {
+  chunks: string[]
+  chars: number
+  /** Characters evicted from the head. Non-zero means the tail is partial. */
+  dropped: number
+}
+
+export function createTail(): Tail {
+  return { chunks: [], chars: 0, dropped: 0 }
+}
+
+export function appendTail(t: Tail, chunk: string, limit = PERSISTENT_TAIL_CHARS): void {
+  if (chunk.length === 0) return
+  t.chunks.push(chunk)
+  t.chars += chunk.length
+  // Evict WHOLE chunks from the head — no concatenation until the flush
+  // joins once, so a chatty server costs one array push per chunk.
+  while (t.chars > limit && t.chunks.length > 1) {
+    const gone = t.chunks.shift()!
+    t.chars -= gone.length
+    t.dropped += gone.length
+  }
+  // A single chunk over the cap is the one place we copy.
+  if (t.chars > limit) {
+    const only = t.chunks[0]!
+    const keep = only.slice(only.length - limit)
+    t.dropped += only.length - keep.length
+    t.chunks[0] = keep
+    t.chars = keep.length
+  }
+}
+
+/** Join the retained text. The tail keeps its chunks — see `resetTail`. */
+export function tailText(t: Tail): string {
+  return t.chunks.length === 1 ? t.chunks[0]! : t.chunks.join('')
+}
+
+/** Drop everything retained, keeping the tail usable for a new phase. */
+export function resetTail(t: Tail): void {
+  t.chunks.length = 0
+  t.chars = 0
+  t.dropped = 0
+}