@vzn/vx 0.0.18 → 0.0.21

package/src/orchestrator/summary.ts

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

package/src/orchestrator/task-hash.ts

@@ -1,5 +1,6 @@
 import path from 'node:path'
 import type { TaskConfig, CacheConfig } from '../config.js'
+import type { WorkspaceFilesCache } from '../cache/index.js'
 import {
   type CacheKeyInput,
   type CacheLayer,
@@ -32,6 +33,7 @@ export interface HashCache {
   taskConfig: WeakMap<TaskConfig, string>
   runtime: Map<string, Promise<string>>
   workspaceRuntime: Map<string, Promise<string>>
+  workspaceFiles: WorkspaceFilesCache
 }
 
 export function createHashCache(): HashCache {
@@ -40,6 +42,7 @@ export function createHashCache(): HashCache {
     taskConfig: new WeakMap(),
     runtime: new Map(),
     workspaceRuntime: new Map(),
+    workspaceFiles: new Map(),
   }
 }
 
@@ -174,6 +177,7 @@ async function resolveKeyInput(args: ComputeHashArgs): Promise<CacheKeyInput> {
       ? {
           runtimeCache: args.hashCache.runtime,
           workspaceRuntimeCache: args.hashCache.workspaceRuntime,
+          workspaceFilesCache: args.hashCache.workspaceFiles,
         }
       : {}),
   })
@@ -264,25 +268,23 @@ function hashTaskConfig(cfg: TaskConfig, hashCache?: HashCache): string {
 }
 
 /**
- * Project the config for hashing: `exec.resources` (cores, memory AND the
- * image a task must be matched to) and `exec.remote` are pure PLACEMENT
- * hints with zero effect on outputs, so they're stripped — tuning a
- * reservation, pinning a task to this machine, or naming the container it
- * runs in never busts a cache. `remote` in particular must not: the whole
- * contract of a remote executor is that the same command over the same
- * inputs produces the same outputs, so a key that moved when placement
- * changed would split a laptop from a worker pool over nothing. `image`
- * rides the same rule one step further: a task that ran locally and the
- * same task on a worker must share an entry, and a task whose output really
- * does depend on its toolchain says so with `cache.inputs.runtime`, which
- * works on both. A config that declares neither takes the fast path and stringifies byte-identically to before the fields existed
- * (why this needs no CACHE_VERSION bump). `timeout`/`retries` stay folded
- * — their keys are distinct by design (see the decision log); stripping
- * them retroactively would bump CACHE_VERSION.
+ * Project the config for hashing: `exec.remote` is a pure PLACEMENT hint
+ * with zero effect on outputs, so it is stripped — pinning a task to this
+ * machine never busts a cache. It must not: the whole contract of a remote
+ * executor is that the same command over the same inputs produces the
+ * same outputs, so a key that moved when placement changed would split a
+ * laptop from a worker pool over nothing. (`exec.resources` rode the same
+ * rule until 2026-09-12, when reservations left the config for the
+ * schedule plugin that learns them; a config never declares them now.) A
+ * config that declares no `remote` takes the fast path and stringifies
+ * byte-identically to before the field existed (why this needs no
+ * CACHE_VERSION bump). `timeout`/`retries` stay folded — their keys are
+ * distinct by design (see the decision log); stripping them retroactively
+ * would bump CACHE_VERSION.
  */
 function hashableConfig(cfg: TaskConfig): unknown {
-  if (cfg.exec?.resources === undefined && cfg.exec?.remote === undefined) return cfg
-  const { resources: _resources, remote: _remote, ...execRest } = cfg.exec
+  if (cfg.exec?.remote === undefined) return cfg
+  const { remote: _remote, ...execRest } = cfg.exec
   return { ...cfg, exec: execRest }
 }
 
@@ -343,5 +345,5 @@ async function doHashProjectPackageJson(
   if (!(await Bun.file(filePath).exists())) return ''
   // Route through the cache layer's mtime+size fast path so the
   // typical re-run sees a stat + SQLite lookup instead of a file read.
-  return await cache.hashFile(filePath)
+  return cache.hashFile(filePath)
 }

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

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

package/src/orchestrator/telemetry-host.ts

@@ -40,7 +40,17 @@ function checkSink(sink: unknown): TelemetrySink {
   if (wants !== undefined && !Array.isArray(wants)) {
     throw new Error(`telemetry sink 'wants' must be an array, got ${typeof wants}`)
   }
-  return sink as TelemetrySink
+  // Every handler is optional, so `{ nope: true }` was a valid sink that
+  // subscribed to the bus and heard nothing — the plugin was "on" and did
+  // nothing. Refused here, which the caller turns into the same warning
+  // a throwing hook gets: never a failed run.
+  const s = sink as TelemetrySink
+  if (typeof s.onRecord !== 'function' && typeof s.onRunSummary !== 'function') {
+    throw new Error(
+      'telemetry sink handles nothing: neither onRecord nor onRunSummary is a function',
+    )
+  }
+  return s
 }
 
 /**

package/src/orchestrator/telemetry.ts

@@ -16,7 +16,7 @@
 // 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 { TaskStatus } from '../graph/index.js'
 import { settleWithin, teardownTimeoutMs } from '../util/index.js'
 import type { RunEvent, RunEventSubscriber } from './events.js'
 
@@ -160,7 +160,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 +169,6 @@ 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
   /** bigint hrtime ns relative to run t=0, encoded as a decimal string. */
   wallclockStartNs?: string
   wallclockEndNs?: string
@@ -254,7 +242,7 @@ 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(
@@ -454,8 +442,6 @@ export function createTelemetrySource(args: {
         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)

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)
+}

package/src/util/index.ts

@@ -5,9 +5,17 @@ export { isUserError, UserError } from './errors.js'
 export { xxh3, xxh3hex } from './hash.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 { 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 } from './edit-distance.js'
+export { editDistance, nearMatches, nearest } from './edit-distance.js'
+export { CORE_VERBS, DISPATCHED_VERBS, MOVED_VERBS } from './verbs.js'

package/src/util/paths.ts

@@ -26,7 +26,10 @@ export function relPosix(from: string, to: string): string {
  * how the two would disagree about what a prefix is.
  */
 export function staticPrefix(glob: string): string {
-  const wildcardIdx = glob.search(/[*?[\]]/)
+  // 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('/')
@@ -47,7 +50,7 @@ export function staticPrefix(glob: string): string {
 export function wholeSubtreePrefixes(globs: readonly string[]): string[] | null {
   if (globs.length === 0) return null
   const out: string[] = []
-  for (const g of globs) {
+  for (const g of globs.map(normalizeGlob)) {
     const m = /^([^*?[\]{}!]+?)\/\*\*$/.exec(g)
     if (m === null) return null
     const dir = m[1]!.replace(/\/+$/, '')
@@ -57,3 +60,21 @@ export function wholeSubtreePrefixes(globs: readonly string[]): string[] | null
   }
   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
+}