@vzn/vx 0.0.18 → 0.0.22

package/src/orchestrator/telemetry.ts

@@ -16,12 +16,12 @@
 // what or how tasks run. Contrast `cache`/`executor`, which return objects
 // core calls INTO; those are the behavior capabilities, kept separate.
 
-import type { OutputFingerprint, TaskStatus, VerifyVerdict } from '../graph/index.js'
+import type { TaskOutcome, TaskStatus } from '../graph/index.js'
 import { settleWithin, teardownTimeoutMs } from '../util/index.js'
 import type { RunEvent, RunEventSubscriber } from './events.js'
 
 /** Bumped when the record shape changes. Readers MUST check `v`. */
-export const TELEMETRY_SCHEMA_VERSION = 2
+export const TELEMETRY_SCHEMA_VERSION = 3
 
 /** Where a task's result came from, derived ONCE in core from the status. */
 export type CacheSource = 'miss' | 'local' | 'remote' | 'none'
@@ -75,8 +75,6 @@ const PASSES: Record<TaskStatus, boolean> = {
  */
 export const TASK_STATUSES: readonly TaskStatus[] = Object.keys(PASSES) as TaskStatus[]
 
-const KNOWN_STATUSES: ReadonlySet<string> = new Set(TASK_STATUSES)
-
 /**
  * Did the task pass? A cache hit counts — it produced the same result without
  * spending the time, which is the whole point. `skipped` and `aborted` do NOT:
@@ -97,7 +95,8 @@ export function isPassStatus(status: string): boolean {
  * cannot disagree about what a hit is. Unknown strings read as not-a-hit.
  */
 export function isCacheHit(status: string): boolean {
-  if (!KNOWN_STATUSES.has(status)) return false
+  // No known-status guard: an unknown string falls through the switch to
+  // undefined, which is neither hit source (the guard survived item 654).
   const source = deriveCacheSource(status as TaskStatus)
   return source === 'local' || source === 'remote'
 }
@@ -160,7 +159,7 @@ export interface TaskTelemetry {
   cpuMs?: number
   peakRssBytes?: number
   /** Executor-reported placement (a worker id) — absent for local runs.
-   *  Additive-optional, no schema bump (the `attempts`/`verify` precedent). */
+   *  Additive-optional, no schema bump (the `attempts` precedent). */
   where?: string
   /** `'deferred'` when the outputs stayed remote (`--download=none`).
    *  Additive-optional, same no-bump precedent as `where`. */
@@ -169,18 +168,18 @@ export interface TaskTelemetry {
    *  / `--retry` produced more than one attempt. A retried-then-passed task is
    *  flaky by definition; this is the telemetry-side flaky signal. */
   attempts?: number
-  /** Cache-correctness verdict — set ONLY on a `--verify` run (absent
-   *  otherwise). A `nondeterministic` verdict means the task's cache entry is
-   *  unsound (its outputs aren't a pure function of its declared inputs); this
-   *  is the telemetry-side hermeticity signal a dashboard surfaces. */
-  verify?: VerifyVerdict
-  /** Output-tree fingerprint — set ONLY under a fingerprinting `--verify*`
-   *  mode (`--verify` / `=all` / `=fingerprint`), executed tasks only. A
-   *  connected serve pairs fingerprints for the SAME `hash` across platforms
-   *  and names diverging outputs (the cross-machine diff). Absent on plain
-   *  runs — additive-optional, no schema bump (the `attempts`/`verify`
-   *  precedent). */
-  outputFp?: OutputFingerprint
+  /**
+   * On a `skipped` task: the id of the failed (or aborted) task at the
+   * root of what blocked it, through any chain of skips. Absent on a
+   * fail-fast skip and on every other status. Additive (schema stays 2).
+   */
+  blockedBy?: string
+  /** On a `failed` task: vx's own `timeout` killed it (exit 143 is the deadline, not a signal). Additive. */
+  timedOut?: true
+  /** On a sandboxed task: how many declared-boundary violations the sandbox recorded (a failure on its own). Additive. */
+  sandboxViolations?: number
+  /** On a failed persistent task: why it never became ready. `exitCode` is the child's own when it exited. Additive. */
+  notReady?: 'timeout' | 'exited' | 'spawn'
   /** bigint hrtime ns relative to run t=0, encoded as a decimal string. */
   wallclockStartNs?: string
   wallclockEndNs?: string
@@ -239,6 +238,12 @@ export interface RunSummaryRecord {
   totalDurationMs: number
   taskCount: number
   failedCount: number
+  /**
+   * Tasks a shutdown signal or an embedder's abort killed (v3). They are
+   * not in `tasks`, which holds real runs only, so without this a stopped
+   * run read as a failure with nothing failed (item 851).
+   */
+  abortedCount: number
   hitCount: number
   hitLocalCount: number
   hitRemoteCount: number
@@ -254,13 +259,19 @@ export interface RunSummaryRecord {
  * distributed run and a local run produce byte-identical summaries and land in
  * the same ingest. The per-task tallies (taskCount / failedCount /
  * hitLocal|Remote|Count) derive from `tasks`; `totalDurationMs` (wall time) and
- * `exitOk` (the run's overall verdict — which counts skipped/verify beyond the
+ * `exitOk` (the run's overall verdict — which counts skipped tasks beyond the
  * recorded task list) are run-level facts and are passed in.
  */
 export function assembleRunSummary(
   run: RunContextRecord,
   tasks: readonly TaskTelemetry[],
-  timing: { startedAt: number; endedAt: number; totalDurationMs: number; exitOk: boolean },
+  timing: {
+    startedAt: number
+    endedAt: number
+    totalDurationMs: number
+    exitOk: boolean
+    abortedCount: number
+  },
 ): RunSummaryRecord {
   let failedCount = 0
   let hitLocalCount = 0
@@ -278,6 +289,7 @@ export function assembleRunSummary(
     totalDurationMs: timing.totalDurationMs,
     taskCount: tasks.length,
     failedCount,
+    abortedCount: timing.abortedCount,
     hitCount: hitLocalCount + hitRemoteCount,
     hitLocalCount,
     hitRemoteCount,
@@ -364,8 +376,9 @@ export function createTelemetrySource(args: {
   // Never silently. The standing rule is that a never-fail path must still
   // WARN — telemetry that vanishes without a word is indistinguishable from
   // telemetry nobody configured.
+  // Every hook call site skips a disabled sink first, so this runs at most
+  // once per sink without a guard of its own (item 654).
   const disable = (sink: TelemetrySink, hook: string, err: unknown): void => {
-    if (disabled.has(sink)) return
     disabled.add(sink)
     warn?.(
       `[vx] telemetry sink '${sink.name}' threw in ${hook}; disabled for this run: ${err instanceof Error ? err.message : String(err)}`,
@@ -435,32 +448,13 @@ export function createTelemetrySource(args: {
       case 'task:complete': {
         const { node, outcome } = event
         if (node.config.exec === undefined) return // group task
-        const rec: TelemetryRecord = {
+        deliver({
           v: TELEMETRY_SCHEMA_VERSION,
           kind: 'task.end',
           runId,
           ts,
-          taskId: node.id,
-          project: node.projectName,
-          task: node.taskName,
-          status: outcome.status,
-          cacheSource: deriveCacheSource(outcome.status),
-          exitCode: outcome.exitCode,
-          durationMs: outcome.durationMs,
-        }
-        if (outcome.hash !== undefined) rec.hash = outcome.hash
-        if (outcome.cpuMs !== undefined) rec.cpuMs = outcome.cpuMs
-        if (outcome.peakRssBytes !== undefined) rec.peakRssBytes = outcome.peakRssBytes
-        if (outcome.where !== undefined) rec.where = outcome.where
-        if (outcome.outputs !== undefined) rec.outputs = outcome.outputs
-        if (outcome.attempts !== undefined) rec.attempts = outcome.attempts
-        if (outcome.verify !== undefined) rec.verify = outcome.verify
-        if (outcome.outputFp !== undefined) rec.outputFp = outcome.outputFp
-        if (outcome.wallclockStartNs !== undefined)
-          rec.wallclockStartNs = outcome.wallclockStartNs.toString()
-        if (outcome.wallclockEndNs !== undefined)
-          rec.wallclockEndNs = outcome.wallclockEndNs.toString()
-        deliver(rec)
+          ...taskTelemetryOf(outcome),
+        })
         return
       }
       case 'run:status':
@@ -490,7 +484,8 @@ export function createTelemetrySource(args: {
       const ms = teardownTimeoutMs()
       // Bounded, for the same reason plugin teardown is bounded in
       // plugin-host.ts: run() awaits this BEFORE closeCache() and before it
-      // returns, and bin.ts is `process.exit(await run(...))`. A sink whose
+      // returns, and bin.ts exits with run()'s code once it returns (through
+      // stdout's end callback since 2026-09-15; the code is still that). A sink whose
       // flush never settles therefore drains the event loop with no exit code
       // pending — Bun exits 0 and a FAILED run reports green, with the cache's
       // accessed_at bumps and every later plugin's teardown lost with it.
@@ -516,3 +511,35 @@ export function createTelemetrySource(args: {
     },
   }
 }
+
+/**
+ * The one projection of an outcome into `TaskTelemetry`, for the streaming
+ * `task.end` record and the summary's `tasks[]` alike. Two copies drifted:
+ * `task.end` dropped `blockedBy`, `timedOut`, `sandboxViolations` and
+ * `notReady`, so a streaming sink saw a timed-out or blocked task as a plain
+ * failure or skip (item 660).
+ */
+export function taskTelemetryOf(o: TaskOutcome): TaskTelemetry {
+  const t: TaskTelemetry = {
+    taskId: o.node.id,
+    project: o.node.projectName,
+    task: o.node.taskName,
+    status: o.status,
+    cacheSource: deriveCacheSource(o.status),
+    exitCode: o.exitCode,
+    durationMs: o.durationMs,
+  }
+  if (o.hash !== undefined) t.hash = o.hash
+  if (o.cpuMs !== undefined) t.cpuMs = o.cpuMs
+  if (o.peakRssBytes !== undefined) t.peakRssBytes = o.peakRssBytes
+  if (o.where !== undefined) t.where = o.where
+  if (o.outputs !== undefined) t.outputs = o.outputs
+  if (o.attempts !== undefined) t.attempts = o.attempts
+  if (o.blockedBy !== undefined) t.blockedBy = o.blockedBy
+  if (o.timedOut === true) t.timedOut = true
+  if (o.sandboxViolations !== undefined) t.sandboxViolations = o.sandboxViolations
+  if (o.notReady !== undefined) t.notReady = o.notReady
+  if (o.wallclockStartNs !== undefined) t.wallclockStartNs = o.wallclockStartNs.toString()
+  if (o.wallclockEndNs !== undefined) t.wallclockEndNs = o.wallclockEndNs.toString()
+  return t
+}

package/src/orchestrator/upstream.ts

@@ -4,10 +4,22 @@ import {
   isTaskPattern,
   parseDependencySpec,
   type DependencySpec,
+  type TaskNode,
   type TaskOutcome,
 } from '../graph/index.js'
 import { UserError } from '../util/index.js'
 
+/**
+ * A task's upstream as its KEY reads it: the live outcomes of its scheduled
+ * dependencies, plus the keys of any `--exclude-dependencies` took out of
+ * the schedule (`excluded-keys.ts`). Every key site goes through this —
+ * the run, the plan, the up-front classify — so a selection cannot change
+ * a key at one of them and not the others.
+ */
+export function keyUpstream(node: TaskNode, upstream: TaskOutcome[]): TaskOutcome[] {
+  return node.excludedUpstream === undefined ? upstream : [...upstream, ...node.excludedUpstream]
+}
+
 /**
  * Pick which upstream task hashes participate in the current task's
  * cache key, filtered by `cache.inputs.tasks`. The folded value is the
@@ -18,6 +30,44 @@ import { UserError } from '../util/index.js'
  * output still re-runs its dependents (early cutoff was removed —
  * rare in practice, not worth the cascade complexity).
  *
+ * The selection itself is `selectFoldedDeps`, which the sandbox's keyed
+ * set (keyed-projects.ts) walks over the graph before any hash exists:
+ * one matcher, so what the key folds and what the sandbox believes it
+ * folds cannot drift.
+ *
+ * Returns `[upstreamTaskId, hash]` pairs. The hash is the only thing
+ * folded into the cache key (the fold sorts by hash, so ordering here
+ * doesn't affect derivation); the task id rides along so Tier-3's
+ * `entry_inputs` rows can NAME which upstream a hash came from. An
+ * upstream with no hash (a persistent task) folds nothing.
+ */
+export function filterUpstreamHashes(
+  upstream: TaskOutcome[],
+  filter: readonly string[] | undefined,
+  selfProjectName: string,
+  selfTaskId: string,
+): Array<[upstreamTaskId: string, hash: string]> {
+  const candidates: FoldCandidate[] = []
+  for (const u of upstream) if (u.hash) candidates.push({ node: u.node, unit: u.hash })
+  return selectFoldedDeps(candidates, filter, selfProjectName, selfTaskId).map((c) => [
+    c.node.id,
+    c.unit,
+  ])
+}
+
+/**
+ * One dependency as the key fold sees it: the task, and the value the
+ * fold dedups by — its hash on the hash path, a structural stand-in for
+ * the hash on the graph (`foldUnit` in keyed-projects.ts).
+ */
+export interface FoldCandidate {
+  node: TaskNode
+  unit: string
+}
+
+/**
+ * The dependencies a task's key folds, per its `cache.inputs.tasks`.
+ *
  * Patterns (Turbo/Nx micro-syntax + filter extensions):
  *   '*'         all same-project upstream
  *   '^*'        all dep-workspace upstream
@@ -36,28 +86,21 @@ import { UserError } from '../util/index.js'
  * `['*', '^*', '!^noisy']` reads as "all minus deps' noisy".
  *
  * Defaults:
- *   - `filter === undefined` → all upstream contribute.
- *   - `filter === []`        → none contribute (fully decoupled).
+ *   - `filter === undefined` → every candidate, as given.
+ *   - `filter === []`        → none (fully decoupled).
  *
- * Returns `[upstreamTaskId, hash]` pairs. The hash is the only thing
- * folded into the cache key (the fold sorts by hash, so ordering here
- * doesn't affect derivation); the task id rides along so Tier-3's
- * `entry_inputs` rows can NAME which upstream a hash came from. The
- * filter dedups by hash, as before — two upstream tasks with identical
- * hashes contribute one pair (first id wins; their key contribution is
- * identical anyway).
+ * Otherwise deduped by `unit`, first candidate kept. The unit is the
+ * fold's own identity, not the task's: two groups over the same members
+ * share one hash, so excluding either excludes both, and a selection by
+ * task id would keep the other while the key folded neither.
  */
-export function filterUpstreamHashes(
-  upstream: TaskOutcome[],
+export function selectFoldedDeps(
+  deps: readonly FoldCandidate[],
   filter: readonly string[] | undefined,
   selfProjectName: string,
   selfTaskId: string,
-): Array<[upstreamTaskId: string, hash: string]> {
-  if (filter === undefined) {
-    const out: Array<[string, string]> = []
-    for (const u of upstream) if (u.hash) out.push([u.node.id, u.hash])
-    return out
-  }
+): FoldCandidate[] {
+  if (filter === undefined) return [...deps]
 
   const specs: DependencySpec[] = filter.map((raw) => {
     try {
@@ -73,21 +116,18 @@ export function filterUpstreamHashes(
   // 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>()
+  const selected = new Map<string, FoldCandidate>()
   for (let i = 0; i < specs.length; i++) {
     const spec = specs[i]!
     const matches = matchers[i]!
-    for (const u of upstream) {
-      if (!u.hash) continue
-      const isSelf = u.node.projectName === selfProjectName
-      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)
+    for (const d of deps) {
+      const isSelf = d.node.projectName === selfProjectName
+      if (!matches(d.node, isSelf)) continue
+      if (spec.negated) selected.delete(d.unit)
+      else if (!selected.has(d.unit)) selected.set(d.unit, d)
     }
   }
-  return [...selected].map(([hash, id]) => [id, hash])
+  return [...selected.values()]
 }
 
 /**
@@ -102,25 +142,31 @@ export function filterUpstreamHashes(
  * 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
+ * Groups may nest, as deep as the graph (the builder takes a 50,000-deep
+ * chain, item 737), so the walk keeps its own stack; and a group reached
+ * along two paths (a group `build` whose `^build` meets a package diamond)
+ * is expanded once, or the walk doubles per layer. 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)
+  const expanded = new Set<TaskOutcome>()
+  const stack = upstream.toReversed()
+  while (stack.length > 0) {
+    const u = stack.pop()!
+    if (expanded.has(u)) continue
+    const members = u.groupUpstream
+    if (members !== undefined) {
+      expanded.add(u)
+      for (let i = members.length - 1; i >= 0; i--) stack.push(members[i]!)
+      continue
     }
+    if (seen.has(u.node.id)) continue
+    seen.add(u.node.id)
+    out.push(u)
   }
-  walk(upstream)
   return out
 }
 
@@ -139,24 +185,24 @@ function nameMatcher(name: string): (candidate: string) => boolean {
  * 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 {
+function specMatcher(spec: DependencySpec): (n: TaskNode, isSelf: boolean) => boolean {
   switch (spec.kind) {
     case 'wildcardSelf':
-      return (_u, isSelf) => isSelf
+      return (_n, isSelf) => isSelf
     case 'wildcardDeps':
-      return (_u, isSelf) => !isSelf
+      return (_n, isSelf) => !isSelf
     case 'self': {
       const task = nameMatcher(spec.task)
-      return (u, isSelf) => isSelf && task(u.node.taskName)
+      return (n, isSelf) => isSelf && task(n.taskName)
     }
     case 'deps': {
       const task = nameMatcher(spec.task)
-      return (u, isSelf) => !isSelf && task(u.node.taskName)
+      return (n, isSelf) => !isSelf && task(n.taskName)
     }
     case 'cross': {
       const project = nameMatcher(spec.project)
       const task = nameMatcher(spec.task)
-      return (u) => project(u.node.projectName) && task(u.node.taskName)
+      return (n) => project(n.projectName) && task(n.taskName)
     }
   }
 }

package/src/util/bun-version.ts

@@ -0,0 +1,43 @@
+/**
+ * The runtime floor. `package.json`'s `engines` states it, but `engines` is
+ * advice an install may print and a run never reads: `bun src/bin.ts` on an
+ * older Bun starts fine and then answers WRONGLY, which is the failure class
+ * this repo treats as the worst one.
+ *
+ * Measured on Bun 1.3.11 (2026-09-19, STATUS item 366): a 2 MiB `--format
+ * json` answer reached a pipe as 219 KB — `bin.ts` ends stdout in a callback
+ * precisely to prevent that, and the fix does not hold below the floor; the
+ * runner read no `peakRssBytes` at all, so `vx last` and `vx why` reported
+ * nothing a task used; and a config syntax error arrived as a `BuildMessage`
+ * the loader's classifier does not know, surfacing as an internal error
+ * instead of the UserError naming file, line and column. Ten of that
+ * container's twenty-three failures were this, and every one of them is a
+ * green exit over a wrong answer.
+ *
+ * `@vzn/vx-reapi` REFUSES an old Bun at its wire, because its failure mode is
+ * a hang and a hang leaves the user nothing to read. Core warns instead: most
+ * of it works below the floor (23 of ~2,000 tests failed on 1.3.11), so
+ * refusing would be heavier than the measurement supports. What the
+ * measurement supports is that a green exit can hide a truncated answer, and
+ * that is what the warning says.
+ */
+export const MIN_BUN = [1, 4, 0] as const
+
+/** True when `version` is older than {@link MIN_BUN}. */
+export function isUnsupportedBun(version: string): boolean {
+  const [maj = 0, min = 0, patch = 0] = version.split('.').map((p) => Number.parseInt(p, 10) || 0)
+  const [reqMaj, reqMin, reqPatch] = MIN_BUN
+  if (maj !== reqMaj) return maj < reqMaj
+  if (min !== reqMin) return min < reqMin
+  return patch < reqPatch
+}
+
+/** The warning a CLI entry prints once, before the verb runs. */
+export function unsupportedBunMessage(version: string): string {
+  return (
+    `vx needs Bun >= ${MIN_BUN.join('.')} (running ${version}). ` +
+    `An older Bun does not fail — it answers wrongly: a large \`--format json\` ` +
+    `answer is truncated mid-write, no task reports what it used, and a config ` +
+    `syntax error surfaces as an internal error. Upgrade with \`bun upgrade\`.`
+  )
+}

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

@@ -19,3 +19,52 @@ export function editDistance(a: string, b: string): number {
   }
   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)
+}