@vzn/vx 0.0.596 → 0.0.598

package/src/cli/upgrade.ts

@@ -200,7 +200,7 @@ export async function fetchRelease(tag: string | undefined): Promise<unknown> {
   }
   // A body that is not JSON (a captive portal's page, a proxy's error
   // page served with a 200) is the same refusal as a cut one.
-  return await readOrRefuse(() => res.json() as Promise<unknown>, url, 'read the release')
+  return await readOrRefuse(() => res.json(), url, 'read the release')
 }
 
 /**

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-fs.ts

@@ -349,7 +349,9 @@ export function modifiedBefore(abs: string, t: number): boolean {
     // 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)
+    // The link's own times, not its target's: a link made after the arm
+    // to an old file is a new input, and followed it read as the target's.
+    const st = fs.lstatSync(abs)
     return Math.max(st.mtimeMs, st.ctimeMs) < t
   } catch {
     return false
@@ -398,6 +400,10 @@ export class WatcherPool {
   // network mount, a container bind — the attempt costs a denied syscall
   // and a two-second wait before the fallback takes over anyway.
   private readonly forcePoll = (process.env['VX_WATCH_POLL'] ?? '') !== ''
+  // The stop closes the pool while a cycle may still be re-arming: an arm
+  // after it, or a proof that fails because it closed the watcher, would
+  // leave a live watcher or poller nothing ever closes.
+  private closed = false
 
   constructor(private readonly skip: (dir: string, rel: string) => boolean) {
     if (this.forcePoll)
@@ -411,6 +417,7 @@ export class WatcherPool {
   // By slot, not by handle: an OS watcher that never proves delivery is
   // swapped for a poller in place, and a drop must close what is there.
   arm(dir: string, recursive: boolean, onEvent: (filename: string) => void): WatchHandle {
+    if (this.closed) return CLOSED
     const watchers = this.watchers
     const at = watchers.length
     const handle: WatchHandle = {
@@ -442,8 +449,8 @@ export class WatcherPool {
       armed.ready.then((ok) => {
         if (ok) return
         armed.watcher.close()
-        // Dropped by a rearm before its proof settled: nothing to swap in.
-        if (watchers[at] !== armed.watcher) return
+        // Dropped by a rearm or the stop before its proof settled: nothing to swap in.
+        if (this.closed || watchers[at] !== armed.watcher) return
         // The watcher never proved delivery, so it is not one: an FSEvents
         // stream the OS refused, a filesystem that reports nothing. Swap in
         // the poller rather than run a loop that silently never fires.
@@ -462,6 +469,7 @@ export class WatcherPool {
   }
 
   closeAll(): void {
+    this.closed = true
     for (const w of this.watchers) {
       try {
         w.close()

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 { 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. */
@@ -146,8 +147,9 @@ export async function watchCmd(args: readonly string[]): Promise<number> {
   }
   process.once('SIGTERM', () => stop.abort('SIGTERM'))
   // A task runs in its own session (exec/kill-tree.ts): the terminal
-  // closing reaches the loop alone, and the loop passes it on.
-  process.once('SIGHUP', () => stop.abort('SIGHUP'))
+  // closing reaches the loop alone, and the loop passes it on — unless vx
+  // was started with it ignored (nohup).
+  if (!hangupIgnored()) process.once('SIGHUP', () => stop.abort('SIGHUP'))
 
   // Enumerate projects-in-scope so we know what dirs to watch: the bare
   // tasks' scope (`opts.projects`; undefined means "every project", or
@@ -375,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)
@@ -406,19 +428,20 @@ async function runWatchLoop(args: WatchLoopArgs): Promise<void> {
         try {
           await held?.stop()
           held = undefined
+          // A Ctrl-C while the old server shut down ran a cycle anyway: a
+          // `not run` row and a footer printed above `stopped` (WD-22).
+          if (stop.aborted) break
           restartTimings()
           // On the mtime clock, as the arm is: from `Date.now()` a write the
           // 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() }
-          if (reread && !stop.aborted) {
-            reread = false
-            await rearm()
-          }
         } catch (err) {
           // A re-run can fail catastrophically when the workspace
           // itself moved out from under us — e.g. the user deleted
@@ -427,12 +450,27 @@ 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
+        // not load yet fails its cycle, and unarmed, the fix to that config
+        // was never an event.
+        if (reread && !stop.aborted) {
+          reread = false
+          await rearm()
+        }
         // 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()
       }
@@ -849,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/cli/workspace-config.ts

@@ -71,7 +71,9 @@ export function parseCacheDirFlag(
   const v = a === '--cache-dir' ? args[i + 1] : a.slice('--cache-dir='.length)
   if (v === undefined || v === '') return { error: '--cache-dir requires a path' }
   if (a === '--cache-dir' && v.startsWith('-')) {
-    return { error: `--cache-dir requires a path, got flag: ${v}` }
+    return {
+      error: `--cache-dir requires a path (got flag ${v}; a path that starts with - needs --cache-dir=${v})`,
+    }
   }
   return { cacheDir: v, next: a === '--cache-dir' ? i + 1 : i }
 }

package/src/config.ts

@@ -608,6 +608,25 @@ type Known<T, Shape> = { [P in keyof T]: P extends keyof Shape ? unknown : never
 /** `T[P]` when `T` has it; `unknown` (no keys to check) when it does not. */
 type At<T, P extends PropertyKey> = T extends { readonly [Q in P]?: infer V } ? V : unknown
 
+/** The objects inside each task's `exec`, held to their keys as `exec` is (D-156). */
+type KnownExecs<T extends ProjectConfig> = {
+  tasks?: {
+    [K in keyof NonNullable<T['tasks']>]?: {
+      exec?: KnownExec<At<NonNullable<T['tasks']>[K], 'exec'>>
+    }
+  }
+}
+
+type KnownExec<E> = {
+  env?: Known<At<E, 'env'>, ExecEnv>
+  persistent?: Known<At<E, 'persistent'>, PersistentConfig>
+  sandbox?: Known<At<E, 'sandbox'>, SandboxConfig> & {
+    allow?: Known<At<At<E, 'sandbox'>, 'allow'>, SandboxGrants>
+    deny?: Known<At<At<E, 'sandbox'>, 'deny'>, SandboxDenials>
+    ignore?: Known<At<At<E, 'sandbox'>, 'ignore'>, SandboxIgnore>
+  }
+}
+
 /**
  * Identity function — exists only so TypeScript narrows literal types
  * and, crucially, **validates `dependsOn` against this project's own
@@ -617,6 +636,7 @@ type At<T, P extends PropertyKey> = T extends { readonly [Q in P]?: infer V } ?
  */
 export function defineProject<const T extends ProjectConfig>(
   config: T &
+    KnownExecs<T> &
     Known<T, ProjectConfig> & {
       tasks?: {
         [K in keyof NonNullable<T['tasks']>]?: Known<NonNullable<T['tasks']>[K], TaskConfig> & {
@@ -640,6 +660,7 @@ export function defineWorkspace<T extends WorkspaceConfig>(
         At<T, 'cacheRetention'>,
         NonNullable<WorkspaceConfig['cacheRetention']>
       >
+      rules?: Known<At<T, 'rules'>, WorkspaceRules>
     },
 ): T {
   return config

package/src/exec/executor.ts

@@ -145,7 +145,7 @@ export interface ExecuteRequest {
    * `RunOptions.signal`) or when `timeoutMs` elapses. An executor ends its
    * work and returns: a child an executor spawned is not one core can
    * reach (H-10, H-12). One already aborted is work not to start (B-55).
-   * A non-zero exit after the timeout's abort is recorded `timedOut`. Core
+   * Any exit after the timeout's abort, a 0 included, is a timeout. Core
    * waits the kill grace (`VX_KILL_GRACE_MS`, 2 s) after the abort, then
    * settles the attempt without `execute` and abandons it (H-14).
    */

package/src/exec/kill-tree.ts

@@ -64,17 +64,40 @@ 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. 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=' '",
+  "g=' ' k=' ' f=' '",
   'while IFS= read -r l; do',
+  '  p=${l#?}',
   '  case $l in',
-  '    +*) g="$g${l#+} " ;;',
-  '    -*) p=${l#-}; case $g in *" $p "*) g="${g%% $p *} ${g#* $p }" ;; esac ;;',
+  '    +*) 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 ;;',
+  '    @*) f="$f$p " ;;',
+  '    !*) case $f in *" $p "*) f="${f%%" $p "*} ${f#*" $p "}" ;; esac ;;',
   '  esac',
   'done <&3',
   'for p in $g; do kill -s KILL -- "-$p"; done 2>/dev/null',
+  'for p in $k; do kill -s KILL "$p"; done 2>/dev/null',
+  'set -f; for p in $f; do rm -rf -- "$p"; done 2>/dev/null',
 ].join('\n')
 
+/** The guard's process, so a guard vx stops writing to is stopped too. */
+let guardProc: Child | undefined
+
+/**
+ * How long a write waits on a guard that is behind. Bun opens the pipe
+ * nonblocking, and the kernel queues ~280 unread writes whatever their
+ * size: a burst of releases, or a guard the scheduler has not yet run,
+ * makes a write EAGAIN while the guard lives.
+ */
+const GUARD_STALL_MS = 1_000
+
 function startGuard(): void {
   if (guardFd !== undefined) return
   guardFd = null
@@ -89,33 +112,51 @@ function startGuard(): void {
     guard.unref()
     const fd = guard.stdio[3] as number
     guardFd = fd
+    guardProc = guard
     // A guard that has died (killed, the OOM killer) is handed to no later
     // spawn: its pipe is broken, and a shell whose printf buffers (bash as
     // macOS's sh) flushed the failed `+<pgid>` line into the task's own
     // stdout, cached replay included (B-10).
     void guard.exited.then(() => {
-      if (guardFd !== fd) return
-      guardFd = null
-      try {
-        closeSync(fd)
-      } catch {
-        // already closed
-      }
+      if (guardFd === fd) stopGuard()
     })
   } catch {
     // The limit as it was: nothing takes the groups down.
   }
 }
 
-function guardWrite(line: string): void {
-  if (typeof guardFd !== 'number') return
+/**
+ * Stop guarding for the rest of the process, and stop the guard with it:
+ * a guard that lived on would keep every group whose release it never got
+ * and SIGKILL them at vx's clean exit.
+ */
+function stopGuard(): void {
+  const fd = guardFd
+  guardFd = null
+  guardProc?.kill('SIGKILL')
+  if (typeof fd !== 'number') return
   try {
-    writeSync(guardFd, line)
+    closeSync(fd)
   } catch {
-    guardFd = null
+    // already closed
   }
 }
 
+function guardWrite(line: string): void {
+  if (typeof guardFd !== 'number') return
+  const deadline = Date.now() + GUARD_STALL_MS
+  for (;;) {
+    try {
+      writeSync(guardFd, line)
+      return
+    } catch (err) {
+      if ((err as NodeJS.ErrnoException).code !== 'EAGAIN' || Date.now() >= deadline) break
+      Bun.sleepSync(1)
+    }
+  }
+  stopGuard()
+}
+
 /**
  * Spawn a task child whose group the guard kills if vx dies holding it.
  * The CHILD lists its own group, before it runs anything: vx wrote the
@@ -130,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}>&-; `
 }
 
 /**
@@ -157,6 +225,25 @@ export function releaseGroup(child: Child): void {
   else guardWrite(`-${child.pid}\n`)
 }
 
+/**
+ * List what the guard takes down besides groups if vx dies: the sandbox
+ * runtime's session. The runtime spawns its bridge socat as a plain child
+ * in vx's OWN group, which the guard must never kill, and a `kill -9`
+ * leaves its sockets in the temp directory. So each pid is killed alone
+ * and each path removed, by a name only that session carries. The
+ * returned function strikes them once the session is down, so a pid the
+ * kernel reuses is never killed on its account. Starts the guard: a spawn
+ * follows. A path holding whitespace is not listed (the lists split on it).
+ */
+export function guardSession(pids: readonly number[], paths: readonly string[]): () => void {
+  startGuard()
+  const listed = paths.filter((p) => !/\s/.test(p))
+  guardWrite(pids.map((p) => `=${p}\n`).join('') + listed.map((p) => `@${p}\n`).join(''))
+  return () => {
+    guardWrite(pids.map((p) => `_${p}\n`).join('') + listed.map((p) => `!${p}\n`).join(''))
+  }
+}
+
 /** Groups a teardown is still taking down: how many hold each, and whether its runner let it go. */
 const holds = new Map<number, { count: number; released: boolean }>()
 
@@ -181,7 +268,7 @@ export function holdGroups(children: readonly Child[]): () => void {
       if (hold === undefined) continue
       if (--hold.count > 0) continue
       holds.delete(pid)
-      if (hold.released) guardWrite(`-${pid}\n`)
+      if (owed.delete(pid) || hold.released) guardWrite(`-${pid}\n`)
     }
   }
 }
@@ -197,9 +284,23 @@ export function holdGroups(children: readonly Child[]): () => void {
  */
 const goneGroups = new WeakSet<Child>()
 
-/** Note, as `child`'s leader exits, whether its group went with it. */
-export function markGroupIfGone(child: Child): void {
-  if (!groupAlive(child)) goneGroups.add(child)
+/** Server groups that outlived their leader: struck when a teardown next lets them go. */
+const owed = new Set<number>()
+
+/**
+ * A persistent child's leader has exited. An empty group is struck and
+ * never signalled again. One with a member left stays listed until a
+ * teardown lets it go: the run's registry still owns a ready server after
+ * its shell exits and stops its group at the end, and struck here, the
+ * `server` of a `server & echo up` was left to nobody by a `kill -9` of vx.
+ */
+export function releaseServerGroup(child: Child): void {
+  if (groupAlive(child)) {
+    owed.add(child.pid)
+    return
+  }
+  goneGroups.add(child)
+  releaseGroup(child)
 }
 
 export function killTree(child: Child, signal: 'SIGINT' | 'SIGTERM' | 'SIGKILL'): void {