@vzn/vx 0.0.597 → 0.0.598

package/package.json

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

package/src/bin.ts

@@ -30,8 +30,12 @@ async function main(): Promise<void> {
     // is set, and `exitOnceFlushed` exits after both streams have ended.
     process.exitCode = code
   } catch (err) {
-    const { fsRefusalHint, isFsRefusal, isOutOfFds, isUserError, OUT_OF_FDS_HINT } =
+    const { fsRefusalHint, isFsRefusal, isOutOfFds, isUserError, maskedLine, OUT_OF_FDS_HINT } =
       await import('./util/index.js')
+    // A plugin's failure quotes what it was told (a remote's reply, a
+    // header), and a config's own throw is its author's text: a secret in
+    // either reached stderr whole (L-11).
+    const say = (line: string): void => void process.stderr.write(maskedLine(line))
     // UserError (workspace not found, cycle, config invalid, ...) —
     // print the message only; the stack is noise the user can't act
     // on. Everything else gets the full stack so internal bugs are
@@ -41,16 +45,16 @@ async function main(): Promise<void> {
       // that wants its own name in the line) is printed as it is; prefixing
       // it produced `vx: vx why: …` (walkthrough, 2026-09-04).
       const m = err.message
-      process.stderr.write(m.startsWith('vx ') ? `${m}\n` : `vx: ${m}\n`)
+      say(m.startsWith('vx ') ? `${m}\n` : `vx: ${m}\n`)
     } else if (isOutOfFds(err)) {
-      process.stderr.write(`vx: ${err.message} — ${OUT_OF_FDS_HINT}\n`)
+      say(`vx: ${err.message} — ${OUT_OF_FDS_HINT}\n`)
     } else if (isFsRefusal(err)) {
       // The file system's refusal names the path; the stack would name
       // the verb's write, which the reader cannot act on either.
-      process.stderr.write(`vx: ${err.message} — ${fsRefusalHint(err)}\n`)
+      say(`vx: ${err.message} — ${fsRefusalHint(err)}\n`)
     } else {
       const message = err instanceof Error ? (err.stack ?? err.message) : String(err)
-      process.stderr.write(`vx: ${message}\n`)
+      say(`vx: ${message}\n`)
     }
     // Same reason as the success path above: a large stderr is truncated by
     // `process.exit` too, and an error message cut in half is the one a

package/src/cache/cache.ts

@@ -660,15 +660,6 @@ export class Cache implements CacheLayer {
   /** The shared store this index attached, or undefined when it holds its entries itself. */
   readonly storeDir: string | undefined
 
-  /**
-   * The store this open was asked for and could not use, with why: the
-   * entries went to a store inside `cacheDir` instead. Never printed.
-   */
-  readonly storeFallback: string | null = null
-
-  /** Set when this open moved a workspace index's own entries out for a shared store. */
-  readonly storeMoved: { from: string; to: string } | null = null
-
   /**
    * Set when THIS open found an index written by another `SCHEMA_VERSION`
    * and dropped every table. The next open sees the current version and
@@ -913,9 +904,6 @@ export class Cache implements CacheLayer {
         // the entries stay in this workspace rather than fail the run.
         const fallback = cacheDir
         if (fallback !== storeDir) {
-          // Set by the open that falls back, never printed; the ones after it
-          // find it recorded.
-          if (recorded !== fallback) this.storeFallback = `${storeDir} (${blocked})`
           storeDir = fallback
           openCacheDir(fallback)
         }
@@ -932,13 +920,11 @@ export class Cache implements CacheLayer {
             .get() != null,
       )
       if (holds) {
-        const had = this.db.prepare('SELECT 1 FROM main.entries LIMIT 1').get() != null
         this.db
           .transaction(() => {
             for (const t of STORE_TABLES) this.db.exec(`DROP TABLE IF EXISTS main.${t}`)
           })
           .immediate()
-        if (had) this.storeMoved = { from: cacheDir, to: storeDir }
       }
     }
     this.storeDir = storeDir
@@ -1050,13 +1036,25 @@ export class Cache implements CacheLayer {
    * Attach the shared store as `store`, with the pragmas the index takes:
    * WAL for both, so a workspace's run and another's share the store as
    * two runs on one `--cache-dir` share an index. A reading verb over a
-   * store with no file yet reads an empty one in memory.
+   * store with no file or no tables yet reads an empty one in memory.
    */
   private attachStore(storeDir: string, inspecting: boolean): void {
     const storeFile = path.join(storeDir, 'store.db')
-    const absent = inspecting && !existsSync(storeFile)
+    let absent = inspecting && !existsSync(storeFile)
     try {
       this.db.prepare('ATTACH DATABASE ? AS store').run(absent ? ':memory:' : storeFile)
+      // One with no tables yet is read empty in memory too: the journal
+      // switch and the table creation below are writes, under no write
+      // lock, racing an opener making that store.
+      if (
+        inspecting &&
+        !absent &&
+        this.db.prepare("SELECT 1 FROM store.sqlite_master WHERE name = 'entries'").get() == null
+      ) {
+        this.db.exec('DETACH DATABASE store')
+        this.db.prepare('ATTACH DATABASE ? AS store').run(':memory:')
+        absent = true
+      }
       this.db.exec('PRAGMA store.journal_mode = WAL')
       if (!absent) this.db.fileControl('store', SQLITE_FCNTL_PERSIST_WAL, 1)
       this.db.exec('PRAGMA store.journal_size_limit = 67108864')
@@ -1760,6 +1758,21 @@ export class Cache implements CacheLayer {
     return this.packArtifact(args)
   }
 
+  /**
+   * The artifact under a private second name, for a body read more than
+   * once (a digest pass then an upload, a retry). The live name is not
+   * stable: a re-save of the key renames other bytes over it, and a body
+   * opened by path read those mid-upload (a digest of one artifact over
+   * the bytes of another). A `Bun.file` over an fd is no answer — its
+   * second read starts where the first ended. Throws when the artifact is
+   * gone; `release` unlinks the name.
+   */
+  pinArtifact(hash: string): { body: Blob; release: () => Promise<void> } {
+    const pinned = this.tempPath(hash)
+    linkSync(this.tarPath(hash), pinned)
+    return { body: Bun.file(pinned), release: () => unlink(pinned).catch(() => undefined) }
+  }
+
   /**
    * The remote body goes to the temp by `Bun.write`, which streams a
    * `Response` and copies a file `Blob` without collecting either, so a
@@ -2310,9 +2323,9 @@ export class Cache implements CacheLayer {
     // Delete DB rows in a single transaction (one fsync; ON DELETE
     // CASCADE clears `output_files`) and unlink artifacts in parallel.
     // Replaces N round-trips + serialized rm with one transaction + a
-    // Promise.all over the unlinks. The IN-list is chunked at 900 like
-    // flushAccessed so a huge eviction stays under any build's
-    // bound-parameter ceiling.
+    // Promise.all over the unlinks. The hash list binds as one `json_each`
+    // parameter, so a huge eviction stays under any build's bound-parameter
+    // ceiling.
     if (dryRun) {
       return { evicted: victims.size, bytesFreed, orphans: picked.files.length, orphanBytes }
     }

package/src/cache/layered-cache.ts

@@ -82,7 +82,8 @@ export interface RemoteCacheLayer {
   /**
    * Store an artifact (fire-and-forget from LayeredCache's perspective).
    * `body` is file-backed (`Bun.file`) when the local store holds the
-   * artifact, so a plugin that streams it never holds it whole.
+   * artifact, so a plugin that streams it never holds it whole, and every
+   * read of it sees the same bytes.
    */
   put(hash: string, body: Blob, meta: { durationMs: number }): Promise<void>
 }
@@ -549,12 +550,12 @@ export class LayeredCache implements CacheLayer {
     // succeeded; we don't fail it on cache-server issues.
     //
     // The job hands the plugin a file-backed Blob over the local artifact,
-    // opened when the plugin reads it: a queued job holds a path, not a
-    // buffer, and a plugin that streams the Blob never holds it whole. The
-    // artifact is content-addressed and immutable, so a deferred read sees
-    // the same bytes; if a concurrent `vx cache prune` removed it first the
-    // plugin's read throws and this upload is skipped — the never-fail
-    // contract.
+    // pinned under a private name when the job starts (`pinArtifact`): a
+    // queued job holds a path, not a buffer, a plugin that streams the Blob
+    // never holds it whole, and every read of it sees the same bytes though
+    // a re-save of the key renames others over the live name. If a
+    // concurrent `vx cache prune` removed the artifact first the pin throws
+    // and this upload is skipped — the never-fail contract.
     const hash = args.hash
     const durationMs = args.entry.durationMs
     // Local writes disabled (`--cache=local:,remote:rw`): there is no
@@ -575,9 +576,11 @@ export class LayeredCache implements CacheLayer {
     this.enqueueUpload(async () => {
       const tally = this.local.uploads
       const start = performance.now()
+      let release: (() => Promise<void>) | undefined
       try {
-        const body =
-          packed !== undefined ? new Blob([packed]) : Bun.file(this.local.outputsPath(hash))
+        let body: Blob
+        if (packed !== undefined) body = new Blob([packed])
+        else ({ body, release } = this.local.pinArtifact(hash))
         await this.wire.put(hash, body, { durationMs })
         tally.count++
         tally.bytes += body.size
@@ -585,6 +588,8 @@ export class LayeredCache implements CacheLayer {
       } catch (err) {
         tally.failed++
         this.reportRemoteError('upload', hash, err)
+      } finally {
+        await release?.()
       }
     })
   }

package/src/cache/output-index.ts

@@ -336,13 +336,18 @@ export class OutputIndex {
     if (this.pendingStamps.size > 0) {
       const stamps = [...this.pendingStamps]
       this.pendingStamps.clear()
-      this.db.transaction(() => {
-        for (const [hash, rows] of stamps) {
-          // A stamp outlives nothing: an entry pruned since has no rows to vouch for.
-          if (this.entryExists.get(hash) === null) continue
-          for (const [rel, ino, ctime] of rows) this.stampOutputFile.run(hash, rel, ino, ctime)
-        }
-      })()
+      // IMMEDIATE: the body reads `entries` before it writes, and a
+      // deferred transaction that did could not wait for the lock
+      // (run-history.ts).
+      this.db
+        .transaction(() => {
+          for (const [hash, rows] of stamps) {
+            // A stamp outlives nothing: an entry pruned since has no rows to vouch for.
+            if (this.entryExists.get(hash) === null) continue
+            for (const [rel, ino, ctime] of rows) this.stampOutputFile.run(hash, rel, ino, ctime)
+          }
+        })
+        .immediate()
     }
     if (this.pendingDirs.size === 0) return
     const pending = [...this.pendingDirs]

package/src/cache/run-history.ts

@@ -69,10 +69,9 @@ export class RunHistory {
       this.insertRun.run(...bindRun(runs[0]!, this.digestValue))
       return
     }
-    // `bun:sqlite`'s `transaction()` returns a callable that wraps the
-    // body in BEGIN/COMMIT, fsyncing once at the end. For a 200-task
-    // run that's one fsync instead of 200.
-    this.db.transaction(() => this.insertRuns(runs))()
+    // One transaction, one fsync: for a 200-task run, one instead of 200.
+    // IMMEDIATE, as `recordRunBundle` explains.
+    this.db.transaction(() => this.insertRuns(runs)).immediate()
   }
 
   /** `runs` as few INSERTs; each distinct forward-args list digested once. */
@@ -99,10 +98,19 @@ export class RunHistory {
     // the entry-save transaction (`save`/`ingest`) so a warm
     // all-cache-hit run — which writes no `runs`-vs-`entry_inputs`
     // mismatch — pays nothing for the moat it isn't refreshing.
-    this.db.transaction(() => {
-      this.insertRuns(bundle.runs)
-      this.insertInvocation.run(...bindInvocation(bundle.invocation))
-    })()
+    //
+    // IMMEDIATE: the write lock is taken at BEGIN, where the busy timeout
+    // waits for it. A run's rows digest their forward args under a salt
+    // the body READS first (`[]` from every CLI run), and a deferred
+    // transaction that read before it wrote could not wait: 13 of 48 runs
+    // on one shared cache dir lost their history to `database is locked`
+    // in 2–60 ms (BUSY_SNAPSHOT, a retry passing at once).
+    this.db
+      .transaction(() => {
+        this.insertRuns(bundle.runs)
+        this.insertInvocation.run(...bindInvocation(bundle.invocation))
+      })
+      .immediate()
   }
 
   /**

package/src/cli/plan-format.ts

@@ -1,7 +1,7 @@
 // Formatters for `--dry-run` (human / JSON) and `--graph` (DOT).
 
 import type { CacheStatus, RunPlan } from '../orchestrator/index.js'
-import { formatElapsed } from '../util/index.js'
+import { formatElapsed, maskedCommand } from '../util/index.js'
 
 /**
  * Human-readable preview. One line per real task (groups hidden, same
@@ -48,7 +48,7 @@ export function formatPlanText(plan: RunPlan): string {
     )
     // Optional one-line description from the task config, indented
     // under the id so the eye picks up the task → blurb mapping.
-    const taskDesc = t.node.config.description
+    const taskDesc = shownDescription(t)
     if (taskDesc) {
       lines.push(`     ${' '.repeat(idWidth)}  ${taskDesc}`)
     }
@@ -104,6 +104,12 @@ export function formatPlanText(plan: RunPlan): string {
   return lines.join('\n') + '\n'
 }
 
+/** A TS config may build the description from `process.env` (L-11). */
+function shownDescription(t: RunPlan['tasks'][number]): string | undefined {
+  const { description, exec } = t.node.config
+  return description === undefined ? undefined : maskedCommand(description, exec?.env)
+}
+
 /** One task of `vx run --dry=json`: the wire, stated by `schemas/plan.json`. */
 export interface PlanTaskJson {
   id: string
@@ -122,21 +128,21 @@ export function formatPlanJson(plan: RunPlan): string {
   return (
     JSON.stringify(
       {
-        tasks: plan.tasks.map((t): PlanTaskJson => ({
-          id: t.node.id,
-          project: t.node.projectName,
-          task: t.node.taskName,
-          hash: t.hash,
-          cacheStatus: t.cacheStatus,
-          deps: t.deps,
-          ...(t.p50Ms !== undefined ? { p50Ms: t.p50Ms } : {}),
-          ...(t.executor !== undefined ? { executor: t.executor } : {}),
-          ...(t.download !== undefined ? { download: t.download } : {}),
-
-          ...(t.node.config.description !== undefined
-            ? { description: t.node.config.description }
-            : {}),
-        })),
+        tasks: plan.tasks.map((t): PlanTaskJson => {
+          const description = shownDescription(t)
+          return {
+            id: t.node.id,
+            project: t.node.projectName,
+            task: t.node.taskName,
+            hash: t.hash,
+            cacheStatus: t.cacheStatus,
+            deps: t.deps,
+            ...(t.p50Ms !== undefined ? { p50Ms: t.p50Ms } : {}),
+            ...(t.executor !== undefined ? { executor: t.executor } : {}),
+            ...(t.download !== undefined ? { download: t.download } : {}),
+            ...(description !== undefined ? { description } : {}),
+          }
+        }),
         ...(plan.predicted !== undefined ? { predicted: plan.predicted } : {}),
         // The gate's refusals belong on the SCRIPTING surface too: a CI job
         // asking "did --download=none actually defer anything, and if not

package/src/cli/select.ts

@@ -27,7 +27,14 @@ import type { ProjectConfig } from '../config.js'
 import type { ProjectEntry } from '../workspace/index.js'
 import { parseDependencySpec } from '../graph/index.js'
 import { declaresInput, workspaceFilesReachInto } from '../cache/index.js'
-import { isUserError, listed, maskedLine, nearest, UserError } from '../util/index.js'
+import {
+  isUserError,
+  listed,
+  maskedCommand,
+  maskedLine,
+  nearest,
+  UserError,
+} from '../util/index.js'
 import {
   claimedAffected,
   fingerprintClaims,
@@ -483,7 +490,11 @@ export async function pickTask(
       .filter((t) => !isDefaultBuild(config.tasks?.[t]))
       .sort()
     for (const t of taskNames) {
-      const desc = config.tasks?.[t]?.description
+      const task = config.tasks?.[t]
+      const desc =
+        task?.description === undefined
+          ? undefined
+          : maskedCommand(task.description, task.exec?.env)
       entries.push({ project: meta.name, task: t, ...(desc ? { description: desc } : {}) })
     }
   }

package/src/cli/show.ts

@@ -221,33 +221,21 @@ function projectDir(root: string, meta: ProjectMeta): string {
 }
 
 /**
- * A task as `vx show` prints it: a secret variable's value masked
- * wherever it appears, in `env.define` and in the command a TS config
- * built from `process.env` (L-11).
+ * A task as `vx show` prints it: a secret variable's value masked in every
+ * string it holds, where a TS config that builds one from `process.env`
+ * put it (the command, `env.define`, a runtime probe, `readyWhen`, the
+ * description) (L-11).
  */
 function shownTask(task: TaskConfig): TaskConfig {
-  const exec = task.exec
-  if (exec === undefined) return task
-  const define = exec.env?.define
-  const secrets = secretMask([process.env, define], exec.env?.secret)
-  if (secrets === null) return task
-  return {
-    ...task,
-    exec: {
-      ...exec,
-      ...(exec.command !== undefined ? { command: secrets.mask(exec.command) } : {}),
-      ...(define !== undefined
-        ? {
-            env: {
-              ...exec.env,
-              define: Object.fromEntries(
-                Object.entries(define).map(([k, v]) => [k, secrets.mask(v)]),
-              ),
-            },
-          }
-        : {}),
-    },
-  }
+  const secrets = secretMask([process.env, task.exec?.env?.define], task.exec?.env?.secret)
+  return secrets === null ? task : (maskStrings(task, secrets.mask) as TaskConfig)
+}
+
+function maskStrings(value: unknown, mask: (text: string) => string): unknown {
+  if (typeof value === 'string') return mask(value)
+  if (Array.isArray(value)) return value.map((v) => maskStrings(v, mask))
+  if (typeof value !== 'object' || value === null) return value
+  return Object.fromEntries(Object.entries(value).map(([k, v]) => [k, maskStrings(v, mask)]))
 }
 
 /** A project config with each task as `shownTask` prints it. */

package/src/cli/watch-cycle.ts

@@ -0,0 +1,43 @@
+// One watch cycle's run, stoppable on its own. A cycle whose dev server
+// never prints its `readyWhen` line and has no `exec.timeout` never ended,
+// so every later edit (the fix included) waited behind it for good (WD-15).
+// While nothing but persistent tasks is in flight, an edit stops the cycle
+// as Ctrl-C would and the loop starts the next one; a cycle running any
+// other work is never stopped.
+
+import { createEventBus, type RunOptions } from '../orchestrator/index.js'
+
+export interface WatchCycle {
+  /** The options for this cycle's run: its own bus and a stop of its own beside watch's. */
+  readonly opts: RunOptions
+  /** Every task in flight is a persistent one not yet ready. */
+  waitsOnReadiness(): boolean
+  /** Stop the run as a SIGTERM would; watch keeps going. */
+  interrupt(): void
+  readonly interrupted: boolean
+}
+
+/** `onWaiting` hears each task event after which the cycle waits on readiness alone. */
+export function watchCycle(opts: RunOptions, stop: AbortSignal, onWaiting: () => void): WatchCycle {
+  const own = new AbortController()
+  const bus = createEventBus()
+  // id → persistent; a group task has no process and holds nothing up.
+  const active = new Map<string, boolean>()
+  const waitsOnReadiness = (): boolean =>
+    active.size > 0 && [...active.values()].every((persistent) => persistent)
+  bus.subscribe((e) => {
+    if (e.kind === 'task:start' && e.node.config.exec !== undefined)
+      active.set(e.node.id, e.node.config.exec.persistent !== undefined)
+    else if (e.kind === 'task:complete') active.delete(e.node.id)
+    else return
+    if (waitsOnReadiness()) onWaiting()
+  })
+  return {
+    opts: { ...opts, bus, signal: AbortSignal.any([stop, own.signal]) },
+    waitsOnReadiness,
+    interrupt: () => own.abort('SIGTERM'),
+    get interrupted() {
+      return own.signal.aborted
+    },
+  }
+}

package/src/cli/watch.ts

@@ -45,7 +45,8 @@ import {
 } from './watch-filter.js'
 import { CLOSED, fsClockNow, type WatchHandle, WatcherPool } from './watch-fs.js'
 import { ChangeJudge } from './watch-judge.js'
-import { hangupIgnored, restartTimings } from '../util/index.js'
+import { type WatchCycle, watchCycle } from './watch-cycle.js'
+import { hangupIgnored, maskedLine, restartTimings } from '../util/index.js'
 import { memberEntries, sameMembers, sweepConfigs, watchedProjects } from './watch-set.js'
 
 /** One line for a watcher or re-read the OS refused; the loop goes on without it. */
@@ -376,11 +377,31 @@ async function runWatchLoop(args: WatchLoopArgs): Promise<void> {
   /** The cycle in flight, so the stop path can wait for its teardown before resolving. */
   let inFlight: Promise<void> = Promise.resolve()
   let debounceTimer: ReturnType<typeof setTimeout> | null = null
+  /** The run in flight, while one is. */
+  let current: WatchCycle | undefined
+  /** What stopped a cycle that waited on a server's readiness; the loop runs it next. */
+  let interruptedBy: string | undefined
+  let interruptTimer: ReturnType<typeof setTimeout> | null = null
+  // Judged on settled state one window later, as an idle edit is, and only
+  // if the cycle still waits on readiness alone by then.
+  const interruptIfWaiting = (): void => {
+    if (changes.pending.size === 0 || current?.waitsOnReadiness() !== true) return
+    if (interruptTimer) clearTimeout(interruptTimer)
+    interruptTimer = setTimeout(() => {
+      interruptTimer = null
+      const c = current
+      if (c === undefined || c.interrupted || !c.waitsOnReadiness() || stop.aborted) return
+      const label = changes.judge()
+      if (label === undefined) return
+      interruptedBy = label
+      c.interrupt()
+    }, DEBOUNCE_MS)
+  }
   let windowOpened = 0
 
   const trigger = (label: string, abs: string): void => {
     if (!changes.pending.has(abs)) changes.pending.set(abs, label)
-    if (running) return
+    if (running) return interruptIfWaiting()
     if (debounceTimer) {
       if (Date.now() - windowOpened >= DEBOUNCE_MAX_MS) return
       clearTimeout(debounceTimer)
@@ -415,7 +436,9 @@ async function runWatchLoop(args: WatchLoopArgs): Promise<void> {
           // run made within a tick of it carried an earlier mtime and read as
           // an edit (WD-20). The end needs no stamp: an mtime never leads it.
           const start = fsClockNow(cacheDir)
-          const cycle = await runOrchestrator(opts)
+          current = watchCycle(opts, stop, interruptIfWaiting)
+          const cycle = await runOrchestrator(current.opts)
+          current = undefined
           held = cycle.persistent
           if (cycle.refused !== undefined) process.stderr.write(`vx watch: ${cycle.refused}\n`)
           changes.lastCycle = { start, end: Date.now() }
@@ -427,7 +450,8 @@ async function runWatchLoop(args: WatchLoopArgs): Promise<void> {
           // message but DON'T let it crash the watch loop; the next
           // FS event (if any) will retry. The dispose() on SIGINT
           // is the canonical exit; we don't unilaterally abort here.
-          const message = err instanceof Error ? err.message : String(err)
+          // A config's own throw or a plugin's failure may quote a secret (L-11).
+          const message = maskedLine(err instanceof Error ? err.message : String(err))
           process.stderr.write(`vx watch: cycle failed: ${message}\n`)
         }
         // After a failed cycle too: a package added with a config that does
@@ -439,7 +463,14 @@ async function runWatchLoop(args: WatchLoopArgs): Promise<void> {
         }
         // What landed mid-run is judged on settled state, one window
         // after the run, under the label of what actually arrived.
-        if (changes.pending.size === 0 || stop.aborted) break
+        current = undefined
+        if (stop.aborted) break
+        if (interruptedBy !== undefined) {
+          label = interruptedBy
+          interruptedBy = undefined
+          continue
+        }
+        if (changes.pending.size === 0) break
         await Bun.sleep(DEBOUNCE_MS)
         label = changes.judge()
       }
@@ -856,6 +887,7 @@ async function runWatchLoop(args: WatchLoopArgs): Promise<void> {
     const cleanup = async (): Promise<void> => {
       pool.closeAll()
       if (debounceTimer) clearTimeout(debounceTimer)
+      if (interruptTimer) clearTimeout(interruptTimer)
       // The aborted cycle is tearing its children down; resolve only once
       // it has returned, so the process never exits over a live child.
       await inFlight

package/src/exec/kill-tree.ts

@@ -65,13 +65,16 @@ export function closeSignalChannel(child: Child): void {
 let guardFd: number | null | undefined
 
 // Three lists: groups (`+`/`-`), single pids (`=`/`_`) and paths to
-// remove (`@`/`!`), killed and removed in that order at EOF.
+// remove (`@`/`!`), killed and removed in that order at EOF. A
+// group is listed once however often its line arrives: a `-` strikes
+// one entry, and a shell that keeps a failed printf buffered (bash as
+// macOS's sh, B-10) sends the line again with its retry.
 const GUARD_SCRIPT = [
   "g=' ' k=' ' f=' '",
   'while IFS= read -r l; do',
   '  p=${l#?}',
   '  case $l in',
-  '    +*) g="$g$p " ;;',
+  '    +*) case $g in *" $p "*) ;; *) g="$g$p " ;; esac ;;',
   '    -*) case $g in *" $p "*) g="${g%% $p *} ${g#* $p }" ;; esac ;;',
   '    =*) k="$k$p " ;;',
   '    _*) case $k in *" $p "*) k="${k%% $p *} ${k#* $p }" ;; esac ;;',
@@ -168,18 +171,45 @@ function guardWrite(line: string): void {
  */
 export function spawnGuarded(spawn: (guard: number | undefined) => Child): Child {
   startGuard()
-  return spawn(typeof guardFd === 'number' ? guardFd : undefined)
+  if (typeof guardFd !== 'number') return spawn(undefined)
+  handingTo = guardProc?.pid
+  try {
+    return spawn(guardFd)
+  } finally {
+    handingTo = undefined
+  }
 }
 
+/**
+ * The guard whose pipe `spawnGuarded` is handing over right now. Only a
+ * line built for that hand-over retries: its pipe is broken only once
+ * the guard has exited, so `kill -0` ends the wait. A line for any other
+ * pipe would wait on a guard that has nothing to do with it.
+ */
+let handingTo: number | undefined
+
 /**
  * The shell line that lists `$$`'s group on the guard's pipe at `fd` and
  * closes it, so the task never holds the guard open. `$$` is the spawned
  * shell, which leads its group (every guarded spawn is `detached`); a
  * program that is not a shell is `exec`'d after it. A write to a guard
  * that has died is ignored rather than a SIGPIPE that kills the task.
+ * The pipe is vx's own nonblocking one, so a full queue fails the write
+ * (EAGAIN) and the group went unlisted: the write is retried while the
+ * guard lives. The shell cannot tell EAGAIN from EPIPE, so the guard's
+ * pid ends the wait, and vx SIGKILLs a guard it gives up on.
  */
 export function guardLine(fd: number): string {
-  return `trap '' PIPE; printf '+%s\\n' $$ >&${fd} 2>/dev/null; trap - PIPE; exec ${fd}>&-; `
+  const add = `printf '+%s\\n' $$ >&${fd} 2>/dev/null`
+  // `kill -0` counts a zombie, and a guard vx has not reaped (its event
+  // loop busy, or an init that never reaps an orphan after vx's kill -9)
+  // kept the shell spinning. Where /proc is ours, its state says dead;
+  // `##*) ` cuts at the LAST ')', as comm may hold one.
+  const alive = procfsIsOwn()
+    ? `{ read -r vx_g </proc/${handingTo}/stat; } 2>/dev/null && case "\${vx_g##*) }" in [ZX]*) false ;; esac`
+    : `kill -0 ${handingTo} 2>/dev/null`
+  const retry = handingTo === undefined ? '' : ` || until ${add}; do ${alive} || break; done`
+  return `trap '' PIPE; ${add}${retry}; trap - PIPE; exec ${fd}>&-; `
 }
 
 /**