@vzn/vx 0.0.16 → 0.0.21

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/util/cgroup.ts

@@ -0,0 +1,160 @@
+// What this process may actually use, as its cgroup bounds it. Inside a
+// container `navigator.hardwareConcurrency` and `os.totalmem()` report
+// the HOST's cores and RAM; the cgroup that runs the job (a docker
+// executor's `--cpus` / `--memory`, a Kubernetes limit) is what the
+// kernel enforces. A limit set on an ANCESTOR binds too, so each reader
+// walks from this process's cgroup up to the root and keeps the
+// tightest value. Linux only; elsewhere the machine's numbers stand.
+// Both hierarchies: v2 (unified, `memory.max` / `cpu.max`) and v1 (one
+// mount per controller, `memory.limit_in_bytes` / `cpu.cfs_*_us`).
+
+import { existsSync, readFileSync } from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+
+export interface CgroupProbe {
+  /** The cgroup filesystem root. Default `/sys/fs/cgroup`. */
+  readonly root?: string
+  /** This process's cgroup membership file. Default `/proc/self/cgroup`. */
+  readonly procSelfCgroup?: string
+}
+
+/**
+ * The tightest memory limit on this process's cgroup or any ancestor, in
+ * bytes; undefined when no cgroup bounds it. v2: `memory.max`, `max`
+ * binds nothing. v1: `memory.limit_in_bytes`, where an unlimited level
+ * writes the page-counter maximum (~2^63) — anything past 2^60 binds
+ * nothing.
+ */
+export function cgroupMemoryLimitBytes(probe: CgroupProbe = {}): number | undefined {
+  return tightest(probe, 'memory', {
+    v2: (dir) =>
+      parseLimit(read(dir, 'memory.max'), (raw) => (raw === 'max' ? undefined : Number(raw))),
+    v1: (dir) =>
+      parseLimit(read(dir, 'memory.limit_in_bytes'), (raw) => {
+        const n = Number(raw)
+        return n >= 2 ** 60 ? undefined : n
+      }),
+  })
+}
+
+/**
+ * The tightest CPU quota on this process's cgroup or any ancestor, in
+ * cores (a fraction is possible: `--cpus=1.5`); undefined when no cgroup
+ * bounds it. v2: `cpu.max` is `<quota> <period>` or `max <period>`. v1:
+ * `cpu.cfs_quota_us` (-1 for none) over `cpu.cfs_period_us`.
+ */
+export function cgroupCpuQuota(probe: CgroupProbe = {}): number | undefined {
+  return tightest(probe, 'cpu', {
+    v2: (dir) => {
+      const raw = read(dir, 'cpu.max')
+      if (raw === undefined) return undefined
+      const [quota, period] = raw.split(/\s+/)
+      return quota === 'max' ? undefined : ratio(Number(quota), Number(period ?? '100000'))
+    },
+    v1: (dir) => {
+      const quota = read(dir, 'cpu.cfs_quota_us')
+      const period = read(dir, 'cpu.cfs_period_us')
+      if (quota === undefined || period === undefined) return undefined
+      const q = Number(quota)
+      return q <= 0 ? undefined : ratio(q, Number(period))
+    },
+  })
+}
+
+/** The machine's total memory, capped by its cgroup limit. */
+export function machineMemoryBytes(probe: CgroupProbe = {}): number {
+  const total = os.totalmem()
+  if (process.platform !== 'linux') return total
+  const limit = cgroupMemoryLimitBytes(probe)
+  return limit === undefined ? total : Math.min(total, limit)
+}
+
+/**
+ * The cores this process may run on, capped by its cgroup CPU quota,
+ * rounded up (a 1.5-core quota is two workers, not one) and never below
+ * one. The default worker count.
+ */
+export function machineParallelism(probe: CgroupProbe = {}): number {
+  const cores = Math.max(1, navigator.hardwareConcurrency)
+  if (process.platform !== 'linux') return cores
+  const quota = cgroupCpuQuota(probe)
+  return quota === undefined ? cores : Math.max(1, Math.min(cores, Math.ceil(quota)))
+}
+
+function ratio(quota: number, period: number): number | undefined {
+  return Number.isFinite(quota) && Number.isFinite(period) && quota > 0 && period > 0
+    ? quota / period
+    : undefined
+}
+
+function parseLimit(
+  raw: string | undefined,
+  parse: (raw: string) => number | undefined,
+): number | undefined {
+  if (raw === undefined) return undefined
+  const n = parse(raw)
+  return n !== undefined && Number.isFinite(n) && n > 0 ? n : undefined
+}
+
+function read(dir: string, file: string): string | undefined {
+  const p = path.join(dir, file)
+  if (!existsSync(p)) return undefined
+  try {
+    return readFileSync(p, 'utf8').trim()
+  } catch {
+    // A level that cannot be read bounds nothing.
+    return undefined
+  }
+}
+
+/**
+ * The minimum over every level from this process's cgroup (for
+ * `controller`) up to the hierarchy's root. The v1 mount is
+ * `<root>/<controller>`; v2 is the one unified tree at `<root>`. A
+ * membership path that escapes the root (a foreign file) is not walked.
+ */
+function tightest(
+  probe: CgroupProbe,
+  controller: 'memory' | 'cpu',
+  readers: { v2: (dir: string) => number | undefined; v1: (dir: string) => number | undefined },
+): number | undefined {
+  const root = probe.root ?? '/sys/fs/cgroup'
+  let membership: string
+  try {
+    membership = readFileSync(probe.procSelfCgroup ?? '/proc/self/cgroup', 'utf8')
+  } catch {
+    return undefined
+  }
+  const candidates: number[] = []
+  for (const line of membership.split('\n')) {
+    const parts = line.split(':')
+    if (parts.length < 3) continue
+    const controllers = parts[1]!
+    const cgroupPath = parts.slice(2).join(':')
+    if (controllers === '') {
+      walkUp(path.join(root, cgroupPath), root, readers.v2, candidates)
+    } else if (controllers.split(',').includes(controller)) {
+      const base = path.join(root, controller)
+      walkUp(path.join(base, cgroupPath), base, readers.v1, candidates)
+    }
+  }
+  return candidates.length === 0 ? undefined : Math.min(...candidates)
+}
+
+function walkUp(
+  from: string,
+  stopAt: string,
+  readLevel: (dir: string) => number | undefined,
+  into: number[],
+): void {
+  let dir = path.resolve(from)
+  const stop = path.resolve(stopAt)
+  if (dir !== stop && !dir.startsWith(stop + path.sep)) return
+  for (;;) {
+    const n = readLevel(dir)
+    if (n !== undefined) into.push(n)
+    if (dir === stop) return
+    dir = path.dirname(dir)
+  }
+}

package/src/util/edit-distance.ts

@@ -0,0 +1,70 @@
+/**
+ * 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)
+}
+
+/**
+ * The ONE near-miss rule every "did you mean" hint applies: the closest
+ * candidate within two edits of `name`, or undefined — an exact match is
+ * not a hint, and anything further would guess rather than help. Task
+ * names, `pkg#task` halves, project names, flags and verbs all go through
+ * here so a typo is hinted the same way wherever it is typed.
+ */
+export function nearest(
+  name: string,
+  candidates: Iterable<string>,
+  maxEdits = 2,
+): string | undefined {
+  let best: string | undefined
+  let bestD = maxEdits + 1
+  for (const c of candidates) {
+    const d = editDistance(name, c)
+    if (d < bestD) {
+      bestD = d
+      best = c
+    }
+  }
+  return best === name ? undefined : best
+}
+
+/**
+ * Up to `limit` candidates worth offering for `name`: the nearest by edit
+ * distance first, then any that contain it (or that it contains), case-
+ * insensitively — the inspection verbs (`why`, `prune`) list a few rather
+ * than pick one, since a partial name is as common a query there as a
+ * typo. Never includes `name` itself.
+ */
+export function nearMatches(name: string, candidates: Iterable<string>, limit = 3): string[] {
+  const all = [...new Set(candidates)].filter((c) => c !== name)
+  const q = name.toLowerCase()
+  const byDistance = all
+    .map((c) => [c, editDistance(name, c)] as const)
+    .filter(([, d]) => d < 3)
+    .sort((a, b) => a[1] - b[1])
+    .map(([c]) => c)
+  const out = [...byDistance]
+  for (const c of all) {
+    if (out.length >= limit) break
+    if (out.includes(c)) continue
+    const n = c.toLowerCase()
+    if (n.includes(q) || q.includes(n)) out.push(c)
+  }
+  return out.slice(0, limit)
+}

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,21 @@
 // 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 { normalizeGlob, relPosix, staticPrefix, wholeSubtreePrefixes } from './paths.js'
+export { killGraceMs, settleWithin, teardownTimeoutMs } from './settle.js'
 export { parseSize } from './size.js'
+export {
+  cgroupCpuQuota,
+  cgroupMemoryLimitBytes,
+  machineMemoryBytes,
+  machineParallelism,
+  type CgroupProbe,
+} from './cgroup.js'
+export { appendTail, createTail, resetTail, tailText, type Tail } from './tail.js'
 export { ulid } from './ulid.js'
+export { editDistance, nearMatches, nearest } from './edit-distance.js'
+export { CORE_VERBS, DISPATCHED_VERBS, MOVED_VERBS } from './verbs.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,67 @@ 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 {
+  // A brace set is a wildcard too: `{dist,build}/**` reaches either dir,
+  // and reading it as the literal directory `{dist,build}` gave the
+  // sandbox baseline a prefix that exists nowhere (2026-09-10).
+  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.map(normalizeGlob)) {
+    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)]
+}
+
+/**
+ * The spellings a reader, Turbo and `.gitignore` all accept but a matcher
+ * fed the raw string turns into NOTHING — and a task keyed on nothing
+ * replays old outputs as a green hit (2026-09-10, probed one by one):
+ * a leading `./`, an inner `/./` segment, a doubled `//`, and a trailing
+ * `/` on a pattern (`src/*\/` means the trees under `src`, so it becomes
+ * `src/*\/**`; a trailing slash on a LITERAL is `asTrees`' job). Applied
+ * after an optional `!`; a bare `.` is the empty entry the schema refuses.
+ */
+export function normalizeGlob(glob: string): string {
+  const neg = glob.startsWith('!')
+  let g = neg ? glob.slice(1) : glob
+  g = g.replace(/\/{2,}/g, '/').replace(/(^|\/)(\.\/)+/g, '$1')
+  if (g === '.') g = ''
+  if (/[*?[\]{}]/.test(g) && g.endsWith('/')) g = `${g.replace(/\/+$/, '')}/**`
+  return neg ? `!${g}` : g
+}

package/src/util/settle.ts

@@ -0,0 +1,67 @@
+// 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
+}
+
+/**
+ * The SIGTERM→SIGKILL grace a run grants a child that ignores SIGTERM: the
+ * one-shot timeout escalation (`exec/runner.ts`) and the end-of-run
+ * persistent shutdown (`orchestrator/persistent.ts`) share it. Two seconds
+ * is generous for a real server's cleanup and is what every run waits when
+ * a child wedges. `VX_KILL_GRACE_MS` overrides it, read per call and bounded
+ * like the teardown deadline (out of range falls back to the default): the
+ * tests that prove the escalation used to wait the full two seconds each,
+ * a third of the suite's wall time for a claim a 200 ms grace proves too.
+ */
+export function killGraceMs(defaultMs: number): number {
+  const raw = process.env['VX_KILL_GRACE_MS']
+  if (raw !== undefined && /^[0-9]+$/.test(raw)) {
+    const n = Number(raw)
+    if (n > 0 && n <= MAX_TIMEOUT_MS) return n
+  }
+  return defaultMs
+}
+
+/**
+ * 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