@vzn/vx 0.0.91 → 0.0.92

package/README.md

@@ -88,6 +88,8 @@ rm -rf packages/*/dist
 npx vx run build --all    # restored from the cache, not rebuilt
 ```
 
+<img src="https://vznjs.github.io/vx/demo.svg" width="760" alt="vx run ci --all on examples/basic: cold, three tasks run; again, three up-to-date.">
+
 Or copy [`examples/basic`](examples/basic), a two-package starter CI
 runs on every commit. More: [Quickstart](https://vznjs.github.io/vx/quickstart/) ·
 [Configure](https://vznjs.github.io/vx/guides/configure/) ·
@@ -112,6 +114,10 @@ When you want configs of your own, one command writes them:
 bunx @vzn/vx-migrate      # vx.config.ts per package, from turbo.json or an Nx graph
 ```
 
+The written configs derive the same cache keys, so what `turbo()` cached
+still hits: [`examples/turbo`](examples/turbo) runs both steps on every
+commit.
+
 `turboCache()` and `nxCache()` keep the remote cache you have (Turbo's
 `/v8/artifacts` API, Vercel's included, or Nx's `/v1/cache`). What each
 Turbo and Nx feature is in vx, pinned by a test:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vzn/vx",
-  "version": "0.0.91",
+  "version": "0.0.92",
   "description": "A fast, correct task runner and build cache for JavaScript monorepos.",
   "type": "module",
   "exports": {
@@ -17,10 +17,10 @@
     "node": ">=18"
   },
   "optionalDependencies": {
-    "@vzn/vx-linux-x64": "0.0.91",
-    "@vzn/vx-linux-arm64": "0.0.91",
-    "@vzn/vx-darwin-x64": "0.0.91",
-    "@vzn/vx-darwin-arm64": "0.0.91"
+    "@vzn/vx-linux-x64": "0.0.92",
+    "@vzn/vx-linux-arm64": "0.0.92",
+    "@vzn/vx-darwin-x64": "0.0.92",
+    "@vzn/vx-darwin-arm64": "0.0.92"
   },
   "dependencies": {
     "@anthropic-ai/sandbox-runtime": "^0.0.76"

package/src/cli/init.ts

@@ -5,6 +5,7 @@
 
 import path from 'node:path'
 import { flagHint, seeHelp } from './help.js'
+import { isUserError, UserError } from '../util/index.js'
 import {
   applyMigration,
   findWorkspaceRoot,
@@ -42,7 +43,16 @@ export async function initCmd(args: readonly string[]): Promise<number> {
     return 1
   }
   const reads: LoadReads = new Map()
-  const root = await findWorkspaceRoot(process.cwd(), reads)
+  // "a workspace from nowhere" still needs a package.json to start from,
+  // and the lookup's own refusal named no next step.
+  const root = await findWorkspaceRoot(process.cwd(), reads).catch((err: unknown) => {
+    if (isUserError(err) && err.message.startsWith('Could not find a workspace root')) {
+      throw new UserError(
+        'vx init: no package.json here or in any parent directory; create one (`bun init` or `npm init -y`) and run vx init again',
+      )
+    }
+    throw err
+  })
   const metas = await listProjects(await loadWorkspace(root, reads))
   // `init` reads scripts only; a runner's own config beside them is the
   // richer source (dependsOn, inputs, outputs) and was ignored without a

package/src/cli/select.ts

@@ -413,9 +413,20 @@ function didYouMeanProject(
   projects: Iterable<{ name: string }>,
 ): string {
   const names = [...projects].map((p) => p.name)
+  // A scoped name typed without its scope (`vx-mcp` for `@vzn/vx-mcp`) is
+  // many edits from the whole name and none from the part after the `/`.
+  const byBare = new Map<string, string[]>()
+  for (const n of names) {
+    const bare = n.slice(n.indexOf('/') + 1)
+    if (bare !== n) byBare.set(bare, [...(byBare.get(bare) ?? []), n])
+  }
   for (const pattern of unmatched) {
-    const best = nearest(pattern.replace(/^!|\.\.\.$|^\.\.\.|\^/g, ''), names)
+    const typed = pattern.replace(/^!|\.\.\.$|^\.\.\.|\^/g, '')
+    const best = nearest(typed, names)
     if (best !== undefined) return `. Did you mean ${best}?`
+    const bare = byBare.has(typed) ? typed : nearest(typed, byBare.keys())
+    const scoped = bare === undefined ? undefined : byBare.get(bare)
+    if (scoped?.length === 1) return `. Did you mean ${scoped[0]}?`
   }
   return ''
 }

package/src/cli/show.ts

@@ -118,22 +118,25 @@ export async function showCmd(args: readonly string[]): Promise<number> {
   const task = declaredTask(config, taskName)
   if (task === undefined) {
     throw new UserError(
-      `unknown task: "${meta.name}#${taskName}"${suggest(taskName, Object.keys(config?.tasks ?? {}))}`,
+      `unknown task: "${meta.name}#${taskName}"${suggest(taskName, Object.keys(config?.tasks ?? {}), `${meta.name}#`)}`,
     )
   }
   process.stdout.write(renderTask(meta.name, dir, taskName, task, parsed.format))
   return 0
 }
 
-/** Near misses by edit distance, plus partial names in either direction. */
-function suggest(query: string, candidates: readonly string[]): string {
+/**
+ * Near misses by edit distance, plus partial names in either direction.
+ * `prefix` makes each a spec the user can paste (`app#build`, not `build`).
+ */
+function suggest(query: string, candidates: readonly string[], prefix = ''): string {
   const q = query.toLowerCase()
   const near = new Set(nearMatches(query, candidates))
   for (const c of candidates) {
     const n = c.toLowerCase()
     if (n.includes(q) || q.includes(n)) near.add(c)
   }
-  return near.size > 0 ? ` — did you mean ${[...near].join(', ')}?` : ''
+  return near.size > 0 ? ` — did you mean ${[...near].map((n) => prefix + n).join(', ')}?` : ''
 }
 
 function projectDir(root: string, meta: ProjectMeta): string {

package/src/cli/watch-fs.ts

@@ -0,0 +1,248 @@
+// `vx watch`'s file-system side: the OS watcher and the proof it delivers,
+// the stat poller that stands in where it cannot, and the clock both are
+// judged against. Nothing here knows about tasks, cycles or the cache.
+
+import fs from 'node:fs'
+import path from 'node:path'
+
+/** Paths whose changes never trigger a re-run. */
+export const IGNORED_SEGMENTS = ['node_modules', '.git', '.vx']
+
+/**
+ * The file `armWatcher` writes under a watched directory to prove the
+ * watcher delivers. Intercepted by name before any other handling, so it
+ * can never trigger a cycle, and removed before "watching" is printed.
+ */
+export const WATCH_PROBE = '.vx-watch-probe'
+
+/** How long a watcher gets to report its own probe before the loop goes on without proof. */
+export const WATCH_PROBE_TIMEOUT_MS = 2_000
+/** The file `fsClockNow` writes and removes, under the cache dir the watchers ignore. */
+const WATCH_CLOCK_STAMP = '.vx-watch-clock'
+
+/** Anything the loop needs to shut down at exit. */
+export interface WatchHandle {
+  close(): void
+}
+
+export interface ArmedWatcher {
+  watcher: fs.FSWatcher
+  /** Resolves `true` once the watcher reported the probe, `false` on timeout. */
+  ready: Promise<boolean>
+}
+
+/** How often the fallback re-walks a watched tree. */
+export const POLL_INTERVAL_MS = 250
+
+/**
+ * Directory names the fallback never descends into WHEN no better filter is
+ * supplied. The justification is that `makeWatchIgnore` already drops their
+ * EVENTS, so the walk buys nothing — a poller pays for it either way, and
+ * `node_modules` is the difference between a cheap fallback and one that
+ * re-stats 40 000 files four times a second.
+ *
+ * That justification is exactly `IGNORED_SEGMENTS`, so this IS that set.
+ * It used to carry a fourth name, `dist`, which the justification does NOT
+ * cover: `dist` is dropped only when a project DECLARES it as an output, and
+ * a project that does not declare it had its `dist/` sources silently
+ * invisible to `vx watch` on every host the poller exists for — a macOS
+ * sandbox, a network mount, a container bind — while the native watcher
+ * delivered them. Two watchers disagreeing about what an edit is (item 482).
+ * The real per-project answer is the caller's `skipDir`, below.
+ */
+const POLL_SKIP = new Set(IGNORED_SEGMENTS)
+
+/**
+ * A watcher built from `stat`, for when the OS one cannot deliver.
+ *
+ * `fs.watch` on macOS is FSEvents, which needs `mach-lookup` on
+ * `com.apple.FSEvents`; inside a sandbox that does not grant it the call
+ * SUCCEEDS and then never fires (measured 2026-09-05: 0 events recursive,
+ * 0 non-recursive, against 3 and 2 for the same writes outside — while
+ * `fs.watchFile` polling delivered in both). A network filesystem or a
+ * container bind mount fails the same way. Polling is slower and coarser,
+ * and it is the difference between `vx watch` working there and silently
+ * doing nothing.
+ */
+export function pollWatcher(
+  dir: string,
+  recursive: boolean,
+  onEvent: (filename: string) => void,
+  intervalMs = POLL_INTERVAL_MS,
+  /**
+   * Directories not worth descending into, by their path relative to `dir`.
+   * The watch loop passes its own event filter, so the poller skips exactly
+   * what the filter would drop anyway — every declared output container, not
+   * a hard-coded name. The default covers the unconditional segments alone.
+   */
+  skipDir: (rel: string) => boolean = (rel) => POLL_SKIP.has(path.basename(rel)),
+): WatchHandle {
+  let previous = new Map<string, number>()
+  let first = true
+  const scan = (): void => {
+    const current = new Map<string, number>()
+    const walk = (abs: string, rel: string): void => {
+      let entries: fs.Dirent[]
+      try {
+        entries = fs.readdirSync(abs, { withFileTypes: true })
+      } catch {
+        return // vanished or unreadable: its files simply stop appearing
+      }
+      for (const e of entries) {
+        if (e.name === WATCH_PROBE) continue
+        const childRel = rel === '' ? e.name : `${rel}/${e.name}`
+        if (e.isDirectory()) {
+          if (recursive && !skipDir(childRel)) walk(path.join(abs, e.name), childRel)
+          continue
+        }
+        if (!e.isFile()) continue
+        try {
+          // The later of the two clocks, as `modifiedBefore` reads them: a
+          // replacement that carries the old file's mtime (`cp -p`, `rsync
+          // -a`, `mv` of a file stamped the same) moved nothing under mtime
+          // alone, and the poller never ran it where the native watcher did.
+          // A rename or a write moves ctime, and no process can set it.
+          const st = fs.statSync(path.join(abs, e.name))
+          current.set(childRel, Math.max(st.mtimeMs, st.ctimeMs))
+        } catch {
+          // raced with a delete; the next scan settles it
+        }
+      }
+    }
+    walk(dir, '')
+    if (!first) {
+      for (const [rel, mtime] of current) {
+        if (previous.get(rel) !== mtime) onEvent(rel)
+      }
+      for (const rel of previous.keys()) {
+        if (!current.has(rel)) onEvent(rel)
+      }
+    }
+    previous = current
+    first = false
+  }
+  scan()
+  // Deliberately NOT unref'd: once the native watcher is closed this timer
+  // is the only thing keeping `vx watch` alive.
+  const timer = setInterval(scan, intervalMs)
+  return {
+    close(): void {
+      clearInterval(timer)
+    },
+  }
+}
+
+/**
+ * `fs.watch` plus proof of delivery. On macOS a recursive watcher is an
+ * FSEvents stream that another thread schedules AFTER the call returns, and
+ * a change landing in that gap is never delivered — MEASURED 2026-09-03: a
+ * write made immediately after `fs.watch` was lost 5 times in 30 under CPU
+ * load (0 in 30 idle, 0 in 30 after a 50 ms pause). The gap has no fixed
+ * width, so no pause is the answer and no timeout on the waiting side ever
+ * was (the e2e flake this closes had one of 45 s). A probe file written
+ * under the watcher and waited for is: once ITS event arrives, the stream
+ * is live for everything after it.
+ *
+ * `onEvent` never sees the probe (create or unlink), and the probe is
+ * removed before `ready` resolves.
+ */
+export function armWatcher(
+  dir: string,
+  recursive: boolean,
+  onEvent: (filename: string) => void,
+  timeoutMs = WATCH_PROBE_TIMEOUT_MS,
+): ArmedWatcher {
+  let markReady: (ok: boolean) => void = () => {}
+  const seen = new Promise<boolean>((resolve) => {
+    markReady = resolve
+  })
+  const watcher = fs.watch(dir, { recursive, persistent: true }, (_event, filename) => {
+    if (filename == null || typeof filename !== 'string') return
+    // An event naming the watched directory itself (macOS reports the
+    // directory a write landed in as its own item) carries nothing a key
+    // can see; the write's own event names the file.
+    if (filename === '' || filename === '.') return
+    if (filename === WATCH_PROBE) {
+      markReady(true)
+      return
+    }
+    // Another arm's probe, seen by this recursive watcher under a nested
+    // directory (a nested project's, a member base inside a project): no
+    // key sees it, and passing it on ran a cycle, and restarted a dev
+    // server, with no edit made (item 1016). Only the watcher's own probe
+    // proves this stream live.
+    if (path.basename(filename) === WATCH_PROBE) return
+    onEvent(filename)
+  })
+  const probe = path.join(dir, WATCH_PROBE)
+  const ready = (async (): Promise<boolean> => {
+    // The probe is subject to the very race it detects: a write that lands
+    // in the gap is lost like any other (1 in 20 under a full gate's load,
+    // measured 2026-09-03, with every delivered event under 60 ms). So it is
+    // re-written on a short backoff until its event arrives — the first write
+    // after the stream goes live is the one that proves it.
+    const deadline = Date.now() + timeoutMs
+    let ok = false
+    let step = 50
+    while (!ok) {
+      try {
+        fs.writeFileSync(probe, String(Date.now()))
+      } catch {
+        break // an unwritable dir gets no proof; the watcher is kept
+      }
+      const remaining = deadline - Date.now()
+      if (remaining <= 0) break
+      const pause = new Promise<boolean>((resolve) => {
+        setTimeout(() => resolve(false), Math.min(step, remaining)).unref()
+      })
+      ok = await Promise.race([seen, pause])
+      step = Math.min(step * 2, 400)
+    }
+    try {
+      fs.unlinkSync(probe)
+    } catch {
+      // already gone
+    }
+    return ok
+  })()
+  return { watcher, ready }
+}
+
+/** True when `abs` was last modified before `t` (epoch ms); false when it cannot be read. */
+export function modifiedBefore(abs: string, t: number): boolean {
+  try {
+    // The later of the two clocks: `mv`, `cp -p`, `rsync -a` and `tar x`
+    // carry a file's OLD mtime onto the new one, and judged by mtime alone
+    // such an edit was "before the arm" and never ran (item 945). No
+    // process can set a ctime, and a rename or a write moves it.
+    const st = fs.statSync(abs)
+    return Math.max(st.mtimeMs, st.ctimeMs) < t
+  } catch {
+    return false
+  }
+}
+
+/**
+ * "Now" as the filesystem will stamp the next write, not as `Date.now()`
+ * reads it. A file's mtime comes from the kernel's coarse clock, which
+ * runs up to a tick behind the fine clock `Date.now()` reads — measured
+ * on the Linux bench box 2026-09-11: 2 of 3,000 tight writes carried an
+ * mtime 5.8 ms EARLIER than a `Date.now()` taken before the write, and
+ * more under CPU load, where the tick is skipped. An `armedAt` from the
+ * fine clock then judged an edit made right after the ready line as
+ * "modified before the arm" and dropped it (the watch e2e flake, three
+ * shard runs that day; traced: raw event, trigger, `same=true`). A stamp
+ * read off a file written here is on the mtime clock itself, and every
+ * later write's mtime is at or after it.
+ */
+export function fsClockNow(dir: string): number {
+  const stamp = path.join(dir, WATCH_CLOCK_STAMP)
+  try {
+    fs.writeFileSync(stamp, '')
+    const at = fs.statSync(stamp).mtimeMs
+    fs.unlinkSync(stamp)
+    return at
+  } catch {
+    return Date.now()
+  }
+}

package/src/cli/watch.ts

@@ -50,12 +50,20 @@ import {
 import type { ProjectConfig } from '../config.js'
 import { type CliLoadOptions, loadCliProjects, loadCliWorkspace } from './workspace-config.js'
 import { taskEdges, taskEdgesFrom } from './select.js'
+import {
+  armWatcher,
+  fsClockNow,
+  IGNORED_SEGMENTS,
+  modifiedBefore,
+  pollWatcher,
+  POLL_INTERVAL_MS,
+  WATCH_PROBE_TIMEOUT_MS,
+  type WatchHandle,
+} from './watch-fs.js'
 
 /** Wait this long after the last filesystem event before re-running. */
 const DEBOUNCE_MS = 150
 
-/** Paths whose changes never trigger a re-run. */
-const IGNORED_SEGMENTS = ['node_modules', '.git', '.vx']
 const IGNORED_SUFFIXES = ['.tsbuildinfo', '~']
 
 /**
@@ -167,13 +175,6 @@ function outputContainer(raw: string): string {
   return prefix === '.' || prefix === '/' ? '' : prefix
 }
 
-/**
- * The file `armWatcher` writes under a watched directory to prove the
- * watcher delivers. Intercepted by name before any other handling, so it
- * can never trigger a cycle, and removed before "watching" is printed.
- */
-export const WATCH_PROBE = '.vx-watch-probe'
-
 /**
  * The subset of `paths` git ignores, asked once per judgement (one
  * `git check-ignore` per debounce window that has candidates, never per
@@ -210,199 +211,6 @@ export function gitIgnored(workspaceRoot: string, paths: readonly string[]): Set
   return ignored
 }
 
-/** How long a watcher gets to report its own probe before the loop goes on without proof. */
-const WATCH_PROBE_TIMEOUT_MS = 2_000
-/** The file `fsClockNow` writes and removes, under the cache dir the watchers ignore. */
-const WATCH_CLOCK_STAMP = '.vx-watch-clock'
-
-/** Anything the loop needs to shut down at exit. */
-export interface WatchHandle {
-  close(): void
-}
-
-export interface ArmedWatcher {
-  watcher: fs.FSWatcher
-  /** Resolves `true` once the watcher reported the probe, `false` on timeout. */
-  ready: Promise<boolean>
-}
-
-/** How often the fallback re-walks a watched tree. */
-const POLL_INTERVAL_MS = 250
-
-/**
- * Directory names the fallback never descends into WHEN no better filter is
- * supplied. The justification is that `makeWatchIgnore` already drops their
- * EVENTS, so the walk buys nothing — a poller pays for it either way, and
- * `node_modules` is the difference between a cheap fallback and one that
- * re-stats 40 000 files four times a second.
- *
- * That justification is exactly `IGNORED_SEGMENTS`, so this IS that set.
- * It used to carry a fourth name, `dist`, which the justification does NOT
- * cover: `dist` is dropped only when a project DECLARES it as an output, and
- * a project that does not declare it had its `dist/` sources silently
- * invisible to `vx watch` on every host the poller exists for — a macOS
- * sandbox, a network mount, a container bind — while the native watcher
- * delivered them. Two watchers disagreeing about what an edit is (item 482).
- * The real per-project answer is the caller's `skipDir`, below.
- */
-const POLL_SKIP = new Set(IGNORED_SEGMENTS)
-
-/**
- * A watcher built from `stat`, for when the OS one cannot deliver.
- *
- * `fs.watch` on macOS is FSEvents, which needs `mach-lookup` on
- * `com.apple.FSEvents`; inside a sandbox that does not grant it the call
- * SUCCEEDS and then never fires (measured 2026-09-05: 0 events recursive,
- * 0 non-recursive, against 3 and 2 for the same writes outside — while
- * `fs.watchFile` polling delivered in both). A network filesystem or a
- * container bind mount fails the same way. Polling is slower and coarser,
- * and it is the difference between `vx watch` working there and silently
- * doing nothing.
- */
-export function pollWatcher(
-  dir: string,
-  recursive: boolean,
-  onEvent: (filename: string) => void,
-  intervalMs = POLL_INTERVAL_MS,
-  /**
-   * Directories not worth descending into, by their path relative to `dir`.
-   * The watch loop passes its own event filter, so the poller skips exactly
-   * what the filter would drop anyway — every declared output container, not
-   * a hard-coded name. The default covers the unconditional segments alone.
-   */
-  skipDir: (rel: string) => boolean = (rel) => POLL_SKIP.has(path.basename(rel)),
-): WatchHandle {
-  let previous = new Map<string, number>()
-  let first = true
-  const scan = (): void => {
-    const current = new Map<string, number>()
-    const walk = (abs: string, rel: string): void => {
-      let entries: fs.Dirent[]
-      try {
-        entries = fs.readdirSync(abs, { withFileTypes: true })
-      } catch {
-        return // vanished or unreadable: its files simply stop appearing
-      }
-      for (const e of entries) {
-        if (e.name === WATCH_PROBE) continue
-        const childRel = rel === '' ? e.name : `${rel}/${e.name}`
-        if (e.isDirectory()) {
-          if (recursive && !skipDir(childRel)) walk(path.join(abs, e.name), childRel)
-          continue
-        }
-        if (!e.isFile()) continue
-        try {
-          // The later of the two clocks, as `modifiedBefore` reads them: a
-          // replacement that carries the old file's mtime (`cp -p`, `rsync
-          // -a`, `mv` of a file stamped the same) moved nothing under mtime
-          // alone, and the poller never ran it where the native watcher did.
-          // A rename or a write moves ctime, and no process can set it.
-          const st = fs.statSync(path.join(abs, e.name))
-          current.set(childRel, Math.max(st.mtimeMs, st.ctimeMs))
-        } catch {
-          // raced with a delete; the next scan settles it
-        }
-      }
-    }
-    walk(dir, '')
-    if (!first) {
-      for (const [rel, mtime] of current) {
-        if (previous.get(rel) !== mtime) onEvent(rel)
-      }
-      for (const rel of previous.keys()) {
-        if (!current.has(rel)) onEvent(rel)
-      }
-    }
-    previous = current
-    first = false
-  }
-  scan()
-  // Deliberately NOT unref'd: once the native watcher is closed this timer
-  // is the only thing keeping `vx watch` alive.
-  const timer = setInterval(scan, intervalMs)
-  return {
-    close(): void {
-      clearInterval(timer)
-    },
-  }
-}
-
-/**
- * `fs.watch` plus proof of delivery. On macOS a recursive watcher is an
- * FSEvents stream that another thread schedules AFTER the call returns, and
- * a change landing in that gap is never delivered — MEASURED 2026-09-03: a
- * write made immediately after `fs.watch` was lost 5 times in 30 under CPU
- * load (0 in 30 idle, 0 in 30 after a 50 ms pause). The gap has no fixed
- * width, so no pause is the answer and no timeout on the waiting side ever
- * was (the e2e flake this closes had one of 45 s). A probe file written
- * under the watcher and waited for is: once ITS event arrives, the stream
- * is live for everything after it.
- *
- * `onEvent` never sees the probe (create or unlink), and the probe is
- * removed before `ready` resolves.
- */
-export function armWatcher(
-  dir: string,
-  recursive: boolean,
-  onEvent: (filename: string) => void,
-  timeoutMs = WATCH_PROBE_TIMEOUT_MS,
-): ArmedWatcher {
-  let markReady: (ok: boolean) => void = () => {}
-  const seen = new Promise<boolean>((resolve) => {
-    markReady = resolve
-  })
-  const watcher = fs.watch(dir, { recursive, persistent: true }, (_event, filename) => {
-    if (filename == null || typeof filename !== 'string') return
-    // An event naming the watched directory itself (macOS reports the
-    // directory a write landed in as its own item) carries nothing a key
-    // can see; the write's own event names the file.
-    if (filename === '' || filename === '.') return
-    if (filename === WATCH_PROBE) {
-      markReady(true)
-      return
-    }
-    // Another arm's probe, seen by this recursive watcher under a nested
-    // directory (a nested project's, a member base inside a project): no
-    // key sees it, and passing it on ran a cycle, and restarted a dev
-    // server, with no edit made (item 1016). Only the watcher's own probe
-    // proves this stream live.
-    if (path.basename(filename) === WATCH_PROBE) return
-    onEvent(filename)
-  })
-  const probe = path.join(dir, WATCH_PROBE)
-  const ready = (async (): Promise<boolean> => {
-    // The probe is subject to the very race it detects: a write that lands
-    // in the gap is lost like any other (1 in 20 under a full gate's load,
-    // measured 2026-09-03, with every delivered event under 60 ms). So it is
-    // re-written on a short backoff until its event arrives — the first write
-    // after the stream goes live is the one that proves it.
-    const deadline = Date.now() + timeoutMs
-    let ok = false
-    let step = 50
-    while (!ok) {
-      try {
-        fs.writeFileSync(probe, String(Date.now()))
-      } catch {
-        break // an unwritable dir gets no proof; the watcher is kept
-      }
-      const remaining = deadline - Date.now()
-      if (remaining <= 0) break
-      const pause = new Promise<boolean>((resolve) => {
-        setTimeout(() => resolve(false), Math.min(step, remaining)).unref()
-      })
-      ok = await Promise.race([seen, pause])
-      step = Math.min(step * 2, 400)
-    }
-    try {
-      fs.unlinkSync(probe)
-    } catch {
-      // already gone
-    }
-    return ok
-  })()
-  return { watcher, ready }
-}
-
 /**
  * The run flags a watch loop cannot honour, as the refusal line it prints; null
  * when there is none. `WATCH_REFUSED_FLAGS` (help.ts) is the same list for
@@ -1516,45 +1324,6 @@ export function pendingAfterCycle(
   return [abs, label]
 }
 
-/** True when `abs` was last modified before `t` (epoch ms); false when it cannot be read. */
-export function modifiedBefore(abs: string, t: number): boolean {
-  try {
-    // The later of the two clocks: `mv`, `cp -p`, `rsync -a` and `tar x`
-    // carry a file's OLD mtime onto the new one, and judged by mtime alone
-    // such an edit was "before the arm" and never ran (item 945). No
-    // process can set a ctime, and a rename or a write moves it.
-    const st = fs.statSync(abs)
-    return Math.max(st.mtimeMs, st.ctimeMs) < t
-  } catch {
-    return false
-  }
-}
-
-/**
- * "Now" as the filesystem will stamp the next write, not as `Date.now()`
- * reads it. A file's mtime comes from the kernel's coarse clock, which
- * runs up to a tick behind the fine clock `Date.now()` reads — measured
- * on the Linux bench box 2026-09-11: 2 of 3,000 tight writes carried an
- * mtime 5.8 ms EARLIER than a `Date.now()` taken before the write, and
- * more under CPU load, where the tick is skipped. An `armedAt` from the
- * fine clock then judged an edit made right after the ready line as
- * "modified before the arm" and dropped it (the watch e2e flake, three
- * shard runs that day; traced: raw event, trigger, `same=true`). A stamp
- * read off a file written here is on the mtime clock itself, and every
- * later write's mtime is at or after it.
- */
-export function fsClockNow(dir: string): number {
-  const stamp = path.join(dir, WATCH_CLOCK_STAMP)
-  try {
-    fs.writeFileSync(stamp, '')
-    const at = fs.statSync(stamp).mtimeMs
-    fs.unlinkSync(stamp)
-    return at
-  } catch {
-    return Date.now()
-  }
-}
-
 /**
  * The directory entries under a package glob's directory that can be
  * members: directories (or links) whose name is not dotted and not

package/src/orchestrator/plugin-host.ts

@@ -323,7 +323,15 @@ export function buildAdmission(
     for (const plugin of answering) {
       if (broken.has(plugin)) continue
       try {
-        if (plugin.admit!(task, ctx) !== false) continue
+        const verdict: unknown = plugin.admit!(task, ctx)
+        // An `async admit` answers a Promise: truthy, so it admitted every
+        // task and its policy never ran, and its rejection was unhandled and
+        // ended the run with a stack (H-16). Named once, admitting after.
+        if (verdict instanceof Promise) {
+          verdict.catch(() => {})
+          throw new Error('returned a Promise; admit is synchronous')
+        }
+        if (verdict !== false) continue
         if (running.size > 0) return false
         if (!overridden.has(plugin)) {
           overridden.add(plugin)

package/src/orchestrator/plugin.ts

@@ -130,8 +130,9 @@ export interface VxPlugin {
    * Admission over the worker count: asked for every task about to start
    * on this machine, with the tasks running here right now. Return `false`
    * to hold it until something finishes (it is asked again then). Asked
-   * many times per run, so it must be cheap and synchronous; a throw is
-   * reported once and the plugin admits from then on — a policy never
+   * many times per run, so it must be cheap and synchronous; a throw, or
+   * an answer that is a Promise, is reported once and the plugin admits
+   * from then on — a policy never
    * breaks a run. Restore-tier hits and tasks on an executor pool hold no
    * local resources and are never asked. When several plugins answer, all
    * must admit. Core keeps no notion of what a task needs: a plugin that
@@ -144,7 +145,8 @@ export interface VxPlugin {
 
   /**
    * Verbs this plugin adds to the `vx` CLI, keyed by name. Consulted only
-   * for a verb core does not know — core's own verbs always win — and only
+   * for a verb core does not know — a verb named like a core verb is
+   * refused at load — and only
    * when the cwd is inside a workspace that declares the plugin. `vx help`
    * lists them under "Plugin commands". A verb's exit code is the process
    * exit code; a thrown `UserError` prints cleanly, like core's own.
@@ -348,6 +350,18 @@ export type PluginHookName =
   | 'onRunStatus'
   | 'onRunEnd'
 
+// A Record so the compiler holds it to `PluginHookName` both ways: a name
+// missing here, or one the type lacks, does not compile.
+const HOOK_NAMES: Record<PluginHookName, true> = {
+  onRunStart: true,
+  onTaskStart: true,
+  onTaskStdout: true,
+  onTaskStderr: true,
+  onTaskComplete: true,
+  onRunStatus: true,
+  onRunEnd: true,
+}
+
 export interface PluginHookHandlers {
   onRunStart: (info: RunStartInfo) => void | Promise<void>
   onTaskStart: (node: TaskNode) => void | Promise<void>
@@ -508,6 +522,13 @@ export async function installPlugins(args: InstallPluginsArgs): Promise<() => vo
         },
       },
       on(hook, handler) {
+        // A misspelt name ('taskComplete') subscribed a handler that never
+        // ran, and no word of it; a config file has no type-checker (H-16).
+        if (!Object.hasOwn(HOOK_NAMES, hook)) {
+          throw new Error(
+            `ctx.on: unknown hook '${String(hook)}' (one of ${Object.keys(HOOK_NAMES).join(', ')})`,
+          )
+        }
         const fail = (err: unknown): void => {
           if (disabled.has(plugin.name)) return
           disabled.add(plugin.name)

package/src/workspace/migrate-scripts.ts

@@ -116,6 +116,15 @@ function upstreamBuildOnWorker(tasks: GeneratedTask[]): void {
     at = Array.isArray(deps) ? byName.get(String(deps[0])) : undefined
   }
   if (at === undefined || at.name === 'build' || at.task === null || at.task === undefined) return
+  // The worker IS `build`'s work, and so is every group on the way to it:
+  // a `typecheck` behind `build: npm run typecheck` waited for `build`,
+  // and the run refused the cycle (D-16).
+  for (const name of [...seen, at.name]) {
+    const t = byName.get(name)!.task!
+    if (name !== 'build' && Array.isArray(t['dependsOn'])) {
+      t['dependsOn'] = (t['dependsOn'] as string[]).filter((d) => d !== 'build')
+    }
+  }
   const deps = Array.isArray(at.task['dependsOn']) ? (at.task['dependsOn'] as string[]) : []
   if (!deps.includes('^build')) at.task['dependsOn'] = ['^build', ...deps]
   if (!at.todos.includes(CACHE_TODO)) at.todos.push(CACHE_TODO)