@vzn/vx 0.0.595 → 0.0.597

package/src/cli/watch.ts

@@ -45,7 +45,7 @@ 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 { hangupIgnored, 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. */
@@ -103,7 +103,7 @@ export async function watchCmd(args: readonly string[]): Promise<number> {
   }
 
   const cwd = process.cwd()
-  const resolved = await resolveRunOptions(parsed, cwd, parsed.tasks)
+  const resolved = await resolveRunOptions(parsed, cwd, parsed.tasks, 'watch')
   if ('error' in resolved) {
     process.stderr.write(`vx watch: ${resolved.error}\n`)
     return 1
@@ -146,8 +146,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
@@ -406,6 +407,9 @@ 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
@@ -415,10 +419,6 @@ async function runWatchLoop(args: WatchLoopArgs): Promise<void> {
           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
@@ -430,6 +430,13 @@ async function runWatchLoop(args: WatchLoopArgs): Promise<void> {
           const message = 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
@@ -471,8 +478,8 @@ async function runWatchLoop(args: WatchLoopArgs): Promise<void> {
 
   /** The instant the watchers go live, on the mtime clock (see `fsClockNow`): a path last modified before it is the initial run's, not an edit. */
   const armedAt = fsClockNow(cacheDir)
-  /** What existed at the arm, so a file born and gone since is no deletion (watch-judge.ts). */
-  const existedAtArm = gitFiles(workspaceRoot)
+  /** What existed and was tracked at the arm, so a file born and gone since is no deletion and a tracked one is the user's edit (watch-judge.ts). */
+  const atArm = gitFiles(workspaceRoot)
   /** Which settled paths are changes (watch-judge.ts); `pending` holds what fired since. */
   const changes = new ChangeJudge({
     workspaceRoot,
@@ -480,7 +487,7 @@ async function runWatchLoop(args: WatchLoopArgs): Promise<void> {
     held: () => held !== undefined,
     uncached: () => uncached,
     fenced: (ownDir, abs) => fenced(ownDir, abs),
-    ...(existedAtArm !== undefined ? { existedAtArm } : {}),
+    ...(atArm !== undefined ? { existedAtArm: atArm.listed, trackedAtArm: atArm.tracked } : {}),
   })
   /** Per-project arms by directory, so `rearm` can add and drop them. */
   const perProject = new Map<string, WatchHandle>()

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

@@ -292,10 +292,10 @@ export interface SandboxConfig {
 
 /** The denials `sandbox.ignore` can leave out of the report: patterns per class. */
 export interface SandboxIgnore {
-  read?: string[]
-  write?: string[]
-  systemInfo?: string[]
-  network?: string[]
+  read?: readonly string[]
+  write?: readonly string[]
+  systemInfo?: readonly string[]
+  network?: readonly string[]
 }
 
 export interface SandboxGrants {
@@ -304,29 +304,29 @@ export interface SandboxGrants {
    * `node_modules`, NOT `cache.inputs.files`. A task that reads its own
    * source in the sandbox says so here.
    */
-  read?: string[]
+  read?: readonly string[]
   /**
    * Writable paths or globs. The task can write NOTHING without these:
    * declaring `cache.outputs.files` grants no write, and a task whose
    * only declaration is its outputs writes into a tmpfs that evaporates
    * (vx then warns that `cache.outputs` matched no files).
    */
-  write?: string[]
+  write?: readonly string[]
   /**
    * Reachable domains, `['*.example.com']` a pattern. The proxy is the
    * run's: it filters every sandboxed task against the union of the lists
    * the run's tasks declare, so `true` adds no domain and reaches only
    * those (none in a run with no list). Omitted adds none either.
    */
-  network?: true | string[]
+  network?: true | readonly string[]
   /**
    * Kernel information the task may query, by info type — the name that
    * appears in a denial, e.g. `vfs.disk-space` (every Bun and git process
    * probes free space at startup).
    */
-  systemInfo?: string[]
+  systemInfo?: readonly string[]
   /** Unix socket paths the task may connect to. `true` allows any. */
-  unixSockets?: true | string[]
+  unixSockets?: true | readonly string[]
   /**
    * Bind and reach localhost ports — a test that boots a server for
    * itself. A port LIST additionally makes those ports reachable from
@@ -335,9 +335,9 @@ export interface SandboxGrants {
    * namespace, each listed port is bridged out to the host's loopback;
    * on macOS the host already sees them and the list means `true`.
    */
-  localBinding?: boolean | number[]
+  localBinding?: boolean | readonly number[]
   /** macOS: Mach service names the task may look up. */
-  machLookup?: string[]
+  machLookup?: readonly string[]
   /** Acquire a TTY. Rare outside interactive tools. */
   pty?: boolean
   /** Write to `.git/config`. Most build tools should not. */
@@ -346,7 +346,7 @@ export interface SandboxGrants {
 
 export interface SandboxDenials {
   /** Domains blocked even if `allow.network` would admit them. */
-  network?: string[]
+  network?: readonly string[]
 }
 
 export interface ExecConfig {
@@ -458,7 +458,7 @@ export interface ExecEnv {
    * folded into the cache key — for things like CI flags, regional
    * vars, secrets that change between machines without affecting output.
    */
-  passThrough?: string[]
+  passThrough?: readonly string[]
   /**
    * Explicit `name: value` pairs. The values are set on the child AND
    * folded into the cache key (they are literal in your config, captured
@@ -471,7 +471,7 @@ export interface ExecEnv {
    * hold `TOKEN`, `SECRET`, `KEY`, `PASSWORD`, `PASSWD` or `CREDENTIAL`
    * are masked without it; this reaches `GH_PAT`, `NPM_AUTH`.
    */
-  secret?: string[]
+  secret?: readonly string[]
 }
 
 export interface CacheConfig {
@@ -488,7 +488,7 @@ export interface CacheOutputs {
    * Outputs are not filtered through gitignore — typical artifact dirs
    * like `dist/` and `coverage/` are captured normally even when ignored.
    */
-  files: string[]
+  files: readonly string[]
   /**
    * Files produced OUTSIDE the project dir, as workspace-root-relative
    * globs (the Turbo `$TURBO_ROOT$` / Nx `{workspaceRoot}` escape
@@ -500,7 +500,7 @@ export interface CacheOutputs {
    * like overlapping `files` (vx cleans declared outputs before a run
    * and before a restore, so the second would delete the first's).
    */
-  workspaceFiles?: string[]
+  workspaceFiles?: readonly string[]
 }
 
 export interface CacheInputs {
@@ -514,7 +514,7 @@ export interface CacheInputs {
    * files are excluded automatically — a task cannot invalidate itself,
    * and cannot read across project boundaries.
    */
-  files: string[]
+  files: readonly string[]
   /**
    * Workspace-root-relative globs (the Turbo `$TURBO_ROOT$` / Nx
    * `{workspaceRoot}` equivalent), for inputs that live outside the
@@ -528,7 +528,7 @@ export interface CacheInputs {
    * Declared outputs (both `outputs` fields) are excluded
    * automatically (a task cannot invalidate itself).
    */
-  workspaceFiles?: string[]
+  workspaceFiles?: readonly string[]
   /**
    * Env var names whose runtime values from parent `process.env` are
    * folded into the cache key. **Independent of `exec.env`** — declaring
@@ -536,7 +536,7 @@ export interface CacheInputs {
    * invalidation. To both forward AND track, list the name in both
    * `exec.env.passThrough` and here.
    */
-  env?: string[]
+  env?: readonly string[]
   /**
    * Which upstream tasks' cache keys participate in this task's key.
    * Uses the same Turbo/Nx micro-syntax as `dependsOn`, plus
@@ -565,7 +565,7 @@ export interface CacheInputs {
    * lock, the OUTPUT is resolved live every run — correct under
    * `--frozen`. Use for project-specific runtime probes.
    */
-  runtime?: string[]
+  runtime?: readonly string[]
   /**
    * Like `runtime`, but commands run at the WORKSPACE ROOT and are
    * deduped GLOBALLY per command across the whole run — a `node -v`
@@ -573,7 +573,7 @@ export interface CacheInputs {
    * analog of `workspaceFiles`: per-task, root-anchored. Use for global
    * tool versions, OS info, etc.
    */
-  workspaceRuntime?: string[]
+  workspaceRuntime?: readonly string[]
 }
 
 /**
@@ -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,37 @@ 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.
 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 ;;',
+  '    +*) g="$g$p " ;;',
+  '    -*) 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,31 +109,49 @@ 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()
 }
 
 /**
@@ -157,6 +195,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 +238,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 +254,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 {

package/src/exec/proc-sample.ts

@@ -26,7 +26,7 @@ interface Proc {
 
 /**
  * Linux's `/proc/<pid>/stat` counts CPU in USER_HZ ticks, fixed at 100 by
- * the ABI on every architecture; `tests/proc-sample.test.ts` pins it by
+ * the ABI on every architecture; `tests/proc-sample.unsafe.test.ts` pins it by
  * burning a known span and reading it back.
  */
 const TICK_MS = 10

package/src/exec/runner.ts

@@ -18,8 +18,8 @@ import {
   closeSignalChannel,
   holdGroups,
   killTree,
-  markGroupIfGone,
   releaseGroup,
+  releaseServerGroup,
   signalThrough,
   guardLine,
   spawnGuarded,
@@ -105,6 +105,36 @@ function taskStdio(terminal: boolean | undefined, stdin: 'ignore' | 'pipe') {
     : ([stdin, 'pipe', 'pipe'] as const)
 }
 
+/**
+ * Read the terminal's modes before a task that holds it runs, and return
+ * what puts them back once it exits: a task killed in raw mode (or one
+ * that never undid its `stty raw -echo`) left the user's terminal with no
+ * echo and no Ctrl-C. Bun restores them at exit only when vx's stdout is
+ * the terminal, so `vx run … > log` kept them, and the rest of a run
+ * printed in them. `detached`, as the task is: a vx in a background job
+ * would be stopped by SIGTTOU on the set.
+ */
+function keepTerminalModes(): (() => void) | undefined {
+  const saved = stty('-g')
+  if (saved === undefined) return undefined
+  return () => {
+    if (stty('-g') !== saved) stty(saved)
+  }
+}
+
+function stty(arg: string): string | undefined {
+  try {
+    const out = Bun.spawnSync(['stty', arg], {
+      stdio: ['inherit', 'pipe', 'ignore'],
+      detached: true,
+    })
+    return out.success ? out.stdout.toString().trim() : undefined
+  } catch {
+    // No stty: the modes stay the task's, as before.
+    return undefined
+  }
+}
+
 export function shellQuote(arg: string): string {
   if (arg === '') return `''`
   // A `#` opens a comment only at a word's start, so `app#build` stays bare.
@@ -485,12 +515,14 @@ const READY_MATCH_WINDOW_CHARS = 64 * 1024
 
 /**
  * Terminal escapes a `readyWhen` pattern is matched without: CSI (colour,
- * cursor), OSC (titles, links) and the two-byte forms. Vite under
+ * cursor), OSC (titles, links), charset picks (`tput sgr0` writes
+ * `\x1b(B\x1b[m`) and the two-byte forms. Vite under
  * `FORCE_COLOR` prints `\x1b[1mLocal\x1b[22m:`, which `Local:` never matched
  * (item 1059). The streamed bytes keep them; only the tested text drops them.
  */
-// eslint-disable-next-line no-control-regex -- ESC is the point
-const TERMINAL_ESCAPE_RE = /\x1b(?:\[[0-?]*[ -/]*[@-~]|\][^\x07\x1b]*(?:\x07|\x1b\\)|[@-Z\\-_])/g
+const TERMINAL_ESCAPE_RE =
+  // eslint-disable-next-line no-control-regex -- ESC is the point
+  /\x1b(?:\[[0-?]*[ -/]*[@-~]|\][^\x07\x1b]*(?:\x07|\x1b\\)|[ -/]+[0-~]|[@-Z\\-_])/g
 
 /**
  * Why a persistent task never became ready — the reason every label and
@@ -566,6 +598,7 @@ export function runPersistent(opts: PersistentOptions): PersistentSpawn {
   const readyRe = opts.readyWhen !== undefined ? new RegExp(opts.readyWhen) : undefined
 
   let child: ReturnType<typeof Bun.spawn>
+  const restoreModes = opts.terminal === true ? keepTerminalModes() : undefined
   try {
     const signalFd = opts.signalChannel === true
     child = spawnGuarded((guard) =>
@@ -597,6 +630,7 @@ export function runPersistent(opts: PersistentOptions): PersistentSpawn {
         },
       ),
     )
+    if (restoreModes !== undefined) void child.exited.then(restoreModes)
     if (signalFd) {
       signalThrough(child, child.stdio[3] as number)
       const spawned = child
@@ -621,7 +655,8 @@ export function runPersistent(opts: PersistentOptions): PersistentSpawn {
   })
 
   const markReady = (): void => {
-    if (readyAt === undefined) {
+    // A marker printed on the way down, once the wait gave up, is not ready.
+    if (readyAt === undefined && gaveUpAt === undefined) {
       readyAt = Date.now()
       if (readyTimer !== undefined) clearTimeout(readyTimer)
       resolveReady()
@@ -709,40 +744,42 @@ export function runPersistent(opts: PersistentOptions): PersistentSpawn {
   opts.liveChildren?.add(child)
   opts.onSpawn?.(child.pid)
 
-  // Readiness deadline. Reject FIRST so the failure reads as a
-  // timeout, then SIGTERM — the exit handler's later reject is a
-  // no-op on the settled promise. Cleared the moment ready fires so
-  // a healthy server is never killed by a stale timer.
+  // Readiness deadline: SIGTERM, wait the grace for the GROUP, SIGKILL
+  // what is left, and only then reject. The caller's teardown used to
+  // signal the group again a turn after this SIGTERM, and a server whose
+  // handler is a one-shot (`process.once('SIGTERM')`, a trap that resets
+  // itself) died on the second mid-cleanup. Cleared the moment ready
+  // fires so a healthy server is never killed by a stale timer.
   let readyTimer: ReturnType<typeof setTimeout> | undefined
   if (readyRe && opts.timeoutMs !== undefined) {
-    const giveUp = (): void => {
-      if (readyAt === undefined) {
-        gaveUpAt = Date.now()
-        rejectReady(
-          new PersistentReadyError(
-            `persistent task not ready within ${opts.timeoutMs}ms — ` +
-              `readyWhen pattern never matched; child killed`,
-            'timeout',
-          ),
-        )
-        // Listed on the group guard until the SIGKILL: the shell may die
-        // on the SIGTERM and let the group go while the server runs out
-        // the grace, and a vx that exits inside it (the timer is unref'd)
-        // leaves the server to the guard (kill-tree.ts, item 865).
-        const letGo = holdGroups([child])
+    const giveUp = async (): Promise<void> => {
+      if (readyAt !== undefined) return
+      gaveUpAt = Date.now()
+      // Listed on the group guard until the SIGKILL: the shell may die on
+      // the SIGTERM and let the group go while the server runs out the
+      // grace, and a vx killed inside it leaves the server to the guard
+      // (kill-tree.ts, item 865).
+      const letGo = holdGroups([child])
+      try {
         killTree(child, 'SIGTERM')
-        // Same escalation as `armTimeout`: a server that traps TERM and
-        // never became ready is not in the persistent registry, so nothing
-        // else would ever kill it — it outlived the run under init.
-        const killTimer = setTimeout(() => {
-          killTree(child, 'SIGKILL')
-          letGo()
-        }, killGraceMs(TIMEOUT_SIGKILL_GRACE_MS))
-        killTimer.unref?.()
+        // A server that traps TERM and never became ready is not in the
+        // persistent registry, so nothing else would ever kill it.
+        const left = await untilGroupsGone([child], killGraceMs(TIMEOUT_SIGKILL_GRACE_MS))
+        for (const c of left) killTree(c, 'SIGKILL')
+        await child.exited
+      } finally {
+        letGo()
       }
+      rejectReady(
+        new PersistentReadyError(
+          `persistent task not ready within ${opts.timeoutMs}ms — ` +
+            `readyWhen pattern never matched; child killed`,
+          'timeout',
+        ),
+      )
     }
     readyTimer = setTimeout(() => {
-      readyTimer = afterPendingExits(giveUp)
+      readyTimer = afterPendingExits(() => void giveUp())
     }, opts.timeoutMs)
   }
 
@@ -750,10 +787,9 @@ export function runPersistent(opts: PersistentOptions): PersistentSpawn {
   // — reject the ready promise so the caller can surface it.
   void child.exited.then((code) => {
     opts.liveChildren?.delete(child)
-    markGroupIfGone(child)
-    releaseGroup(child)
+    releaseServerGroup(child)
     if (readyTimer !== undefined) clearTimeout(readyTimer)
-    if (readyAt === undefined) {
+    if (readyAt === undefined && gaveUpAt === undefined) {
       rejectReady(
         new PersistentReadyError(
           `persistent task exited before becoming ready (exit ${code ?? '?'})` +
@@ -798,6 +834,7 @@ export async function runCommand(opts: RunOptions): Promise<RunResult> {
   const fullCommand = withForwardArgs(opts.command, opts.forwardArgs)
 
   let proc: ReturnType<typeof Bun.spawn>
+  const restoreModes = opts.terminal === true ? keepTerminalModes() : undefined
   try {
     proc = spawnGuarded((guard) =>
       Bun.spawn(shellArgv((guard === undefined ? '' : guardLine(3)) + execWrap(fullCommand)), {
@@ -832,6 +869,7 @@ export async function runCommand(opts: RunOptions): Promise<RunResult> {
   // lets a clean exit EOF immediately and only cuts off a stuck reader after a
   // brief grace — without this the run hangs forever.
   await proc.exited
+  restoreModes?.()
   await timeout.settle()
   let cut = false
   if (timeout.timedOut()) ac.abort()