@vzn/vx 0.0.619 → 0.0.621

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vzn/vx",
-  "version": "0.0.619",
+  "version": "0.0.621",
   "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.619",
-    "@vzn/vx-linux-arm64": "0.0.619",
-    "@vzn/vx-darwin-x64": "0.0.619",
-    "@vzn/vx-darwin-arm64": "0.0.619"
+    "@vzn/vx-linux-x64": "0.0.621",
+    "@vzn/vx-linux-arm64": "0.0.621",
+    "@vzn/vx-darwin-x64": "0.0.621",
+    "@vzn/vx-darwin-arm64": "0.0.621"
   },
   "dependencies": {
     "@anthropic-ai/sandbox-runtime": "^0.0.76"

package/src/cli/watch-judge.ts

@@ -218,7 +218,7 @@ export class ChangeJudge {
       this.noticed.add(firstAbs)
       process.stdout.write(
         byServer
-          ? `vx watch: ${first} has started 3 cycles in a row, written while a server the cycle before started was running — a persistent task rewrites it. Add it to .gitignore (a git-ignored path never starts a cycle); until then every write restarts the server.\n`
+          ? `vx watch: ${first} has started 3 cycles in a row, written while a server was running — a persistent task rewrites it. Add it to .gitignore (a git-ignored path never starts a cycle); until then every write starts a cycle.\n`
           : `vx watch: ${first} has started 3 cycles in a row, written by the cycle before each — a task rewrites it every run. Declare it in cache.outputs (an output never starts a cycle) or add it to .gitignore (a git-ignored path never does); until then every run re-runs.\n`,
       )
     }

package/src/cli/watch.ts

@@ -409,8 +409,9 @@ async function runWatchLoop(args: WatchLoopArgs): Promise<void> {
   let claimedRootFiles = args.claimedRootFiles
   let configImportFiles = args.configImports
   let wsConfigImportFiles = args.workspaceConfigImports
-  // A dev server stays up while the loop idles; the cycle that replaces it
-  // stops it first, so the new one never meets the old one's port.
+  // A dev server stays up while the loop idles and across cycles; a cycle
+  // that must restart it (its config changed, it died) stops it before its
+  // graph, so the new one never meets the old one's port.
   let held = args.held
 
   // Reentrancy guard — never two orchestrator runs in flight. Events that
@@ -480,20 +481,26 @@ async function runWatchLoop(args: WatchLoopArgs): Promise<void> {
             // after the run stays, for what the run itself changed.
             if (reread) await rearm(false)
             process.stdout.write(`\nvx watch: ${label}; re-running...\n\n`)
-            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)
-            current = watchCycle(opts, stop, interruptIfWaiting)
+            // A server still up whose task is unchanged stays up: the cycle
+            // rebuilds what it depends on, and the dev tool's own reload
+            // takes it from there. The run stops the others before its graph.
+            const before = held
+            current = watchCycle(
+              { ...opts, ...(before ? { keep: before } : {}) },
+              stop,
+              interruptIfWaiting,
+            )
             const cycle = await runOrchestrator(current.opts)
             current = undefined
             held = cycle.persistent
+            // What this cycle did not take (a server whose task did not run).
+            await before?.stop()
             if (cycle.refused !== undefined) process.stderr.write(`vx watch: ${cycle.refused}\n`)
             changes.lastCycle = { start, end: Date.now() }
           } catch (err) {

package/src/orchestrator/options.ts

@@ -214,6 +214,18 @@ export interface RunOptions {
    * is replaced only when the next cycle starts.
    */
   holdPersistent?: boolean
+  /**
+   * The servers an earlier `holdPersistent` run handed back. Each one still
+   * up whose task this run would start again, with the same resolved
+   * config, is kept running and reported ready instead of restarted; what
+   * it writes reaches this run's renderer from then on. The rest are
+   * stopped before the graph starts, so a new one never meets the old
+   * one's port. The watch loop sets it: `vx watch dev` rebuilds what the
+   * server depends on and leaves the server up. The caller still stops
+   * the earlier hand-back afterwards; that stops only what this run did
+   * not take.
+   */
+  keep?: HeldPersistent
   /**
    * Print the per-task table (`--verbosity 1`) just above the footer: the
    * footer is the run's last word, so the caller cannot print it after.
@@ -305,6 +317,18 @@ export interface RunSummary {
 export interface HeldPersistent {
   /** The held tasks' ids, `pkg#task`. */
   ids: readonly string[]
-  /** Send every held task `signal` (default SIGTERM), then SIGKILL after the kill grace; resolves once each is gone. */
+  /** Send every held task a later run did not take `signal` (default SIGTERM), then SIGKILL after the kill grace; resolves once each is gone. */
   stop(signal?: 'SIGINT' | 'SIGTERM'): Promise<void>
+  /** Each held server by id, for a later run's `RunOptions.keep`. */
+  servers: ReadonlyMap<string, HeldServer>
+}
+
+export interface HeldServer {
+  child: ReturnType<typeof Bun.spawn>
+  /** The task's resolved config as the run that started it saw it: a later run keeps the server only while its own reads the same. */
+  config: string
+  /** Where what the server writes goes; a run that keeps it points this at its own bus. */
+  out: { bus: EventBus }
+  /** A later run took the server (kept or stopped it): the hand-back's `stop()` and exit notice leave it alone. */
+  handOver(): void
 }

package/src/orchestrator/persistent.ts

@@ -6,6 +6,7 @@
 import { isGroupTask, type TaskNode } from '../graph/index.js'
 import { killGraceMs } from '../util/index.js'
 import { holdGroups, killTree, untilGroupsGone } from '../exec/index.js'
+import type { HeldServer } from './options.js'
 
 type Child = ReturnType<typeof Bun.spawn>
 
@@ -116,3 +117,38 @@ export interface CrashedPersistent {
 export function hasEnded(child: Child): boolean {
   return child.exitCode !== null || child.signalCode !== null
 }
+
+/** A server's identity across watch cycles: its resolved config and the args forwarded to it. */
+export function serverConfig(node: TaskNode, forwardArgs: readonly string[] | undefined): string {
+  return JSON.stringify([node.config, forwardArgs ?? []])
+}
+
+/**
+ * Split an earlier run's held servers into the ones this graph may keep
+ * (still up, a node of this graph, same config) and the ones it stops. A
+ * stopped one is handed over now, so the earlier run names no exit; a kept
+ * one only when its task is reached, and one never reached (a dependency
+ * failed) is the earlier run's to stop.
+ */
+export function takeHeldServers(
+  held: ReadonlyMap<string, HeldServer> | undefined,
+  nodes: ReadonlyMap<string, TaskNode>,
+  forwardArgs: readonly string[] | undefined,
+): { kept: Map<string, HeldServer>; stale: Child[] } {
+  const kept = new Map<string, HeldServer>()
+  const stale: Child[] = []
+  for (const [id, server] of held ?? []) {
+    if (hasEnded(server.child)) continue
+    const node = nodes.get(id)
+    if (
+      node?.config.exec?.persistent !== undefined &&
+      serverConfig(node, forwardArgs) === server.config
+    )
+      kept.set(id, server)
+    else {
+      server.handOver()
+      stale.push(server.child)
+    }
+  }
+  return { kept, stale }
+}

package/src/orchestrator/run.ts

@@ -63,7 +63,7 @@ import { buildAdmission, executorLabel, resolveExecutors, teardownPlugins } from
 import { subscribeTelemetry, type TelemetryHandle } from './telemetry-host.js'
 import { assembleRunSummary, isPassStatus } from './telemetry.js'
 import type { RunContextRecord } from './telemetry.js'
-import { defaultLogger, resolveOutputView } from './logger.js'
+import { defaultLogger, resolveOutputView, type Logger } from './logger.js'
 import { detectColors, type ColorSupport } from './colors.js'
 import { plainOutput } from './plain-output.js'
 import { formatPersistentList } from './framed-output.js'
@@ -103,13 +103,19 @@ import {
 import { deriveStableKeys, probesAfterWrites } from './stable-keys.js'
 
 import { assembleRunRecords } from './run-records.js'
-import { hasEnded, selectKeepAlive, shutdownPersistent } from './persistent.js'
+import {
+  hasEnded,
+  selectKeepAlive,
+  serverConfig,
+  shutdownPersistent,
+  takeHeldServers,
+} from './persistent.js'
 import { writeRunProfile, writeRunSummary } from './run-artifacts.js'
 import { createSaveLane } from './save-lane.js'
 import { formatOutcomeTable, formatRunSummary } from './summary.js'
 import { detectFlaky, type FlakyCandidate, type FlakyFinding } from './failure-mode.js'
 import { createMissExplainer } from './miss-reason.js'
-import type { RunOptions, RunSummary } from './options.js'
+import type { HeldServer, RunOptions, RunSummary } from './options.js'
 
 // Per run, never shared: a `vx watch` process runs many, and a shared map
 // is one `preProbed.set` away from leaking a hit across cycles.
@@ -358,6 +364,18 @@ async function runOnBus(
   colors: ColorSupport,
 ): Promise<RunSummary> {
   const log = busLogger(bus)
+  // A server's output goes through a cell of its own: a later watch cycle
+  // that keeps the server points it at that cycle's bus (`RunOptions.keep`).
+  const serverOuts = new Map<string, { bus: EventBus }>()
+  const serverLog = (id: string): Logger => {
+    const out = { bus }
+    serverOuts.set(id, out)
+    return {
+      ...log,
+      taskStdout: (node, chunk) => out.bus.emit({ kind: 'task:stdout', node, chunk }),
+      taskStderr: (node, chunk) => out.bus.emit({ kind: 'task:stderr', node, chunk }),
+    }
+  }
 
   const prepared = await prepareRun(options, log)
   mark('plugin stages')
@@ -469,6 +487,20 @@ async function runOnBus(
     workspaceProjectCount,
   } = prepared
   const concurrency = options.concurrency ?? workspaceConfig?.concurrency ?? machineParallelism()
+  // An earlier cycle's servers: the ones this graph starts again unchanged
+  // stay up; the others go now, before anything binds their ports. A stop
+  // that lands meanwhile ends the run here, having run nothing: an aborted
+  // graph printed a `not run` row and a footer above `stopped` (WD-22).
+  const heldBefore = takeHeldServers(options.keep?.servers, nodes, options.forwardArgs)
+  if (heldBefore.stale.length > 0) {
+    await terminateChildren(() => heldBefore.stale)
+    if (options.signal?.aborted === true) {
+      disposePlugins?.()
+      await teardown()
+      prepared.cache.close()
+      return { ok: true, outcomes: [] }
+    }
+  }
 
   // Resolved ONCE per run, in declaration order, the local executor last.
   // A broken factory aborts here, before any task starts.
@@ -968,7 +1000,7 @@ async function runOnBus(
         cache,
         cachePolicy: policy,
         forwardArgs: options.forwardArgs,
-        log,
+        log: node.config.exec?.persistent !== undefined ? serverLog(node.id) : log,
         executor: placements.executors.get(node.id) ?? UNPLACED_EXECUTOR,
         deferred: deferredOutputs,
         nestedProjectDirs: nestedDirsByProject.get(node.projectName) ?? [],
@@ -1041,6 +1073,25 @@ async function runOnBus(
         // History is observability: an unreadable one judges nothing.
       }
     }
+    const keepServer = (node: TaskNode): TaskOutcome | undefined => {
+      const server = heldBefore.kept.get(node.id)
+      if (server === undefined) return undefined
+      heldBefore.kept.delete(node.id)
+      if (hasEnded(server.child)) return undefined
+      server.handOver()
+      server.out.bus = bus
+      serverOuts.set(node.id, server.out)
+      persistentRegistry.set(node.id, server.child)
+      const at = process.hrtime.bigint() - runStartHrTimeNs
+      return {
+        node,
+        status: 'success',
+        exitCode: 0,
+        durationMs: 0,
+        wallclockStartNs: at,
+        wallclockEndNs: at,
+      }
+    }
     const outcomes = await runGraph({
       nodes,
       concurrency,
@@ -1063,7 +1114,12 @@ async function runOnBus(
         narrowDemand(o.node.id)
       },
       onError: (node, line) => log.taskStderr(node, line),
-      execute: (node, upstream) => executeWithDedup(node, keyUpstream(node, upstream)),
+      execute: (node, upstream) => {
+        const kept = keepServer(node)
+        return kept !== undefined
+          ? Promise.resolve(kept)
+          : executeWithDedup(node, keyUpstream(node, upstream))
+      },
       // A `schedule` plugin's weights; the scheduler keeps its structural
       // baseline as the tie-break. Empty map → baseline only.
       ...(prepared.priorities.size > 0 ? { priorities: prepared.priorities } : {}),
@@ -1384,11 +1440,22 @@ async function runOnBus(
       // keep-alive says it: `vx watch` sat on "watching" over a dead dev
       // server. The holder's own stop() is not such a death.
       let stopping = false
+      // Taken by a later run (`RunOptions.keep`): kept or stopped there.
+      const handed = new Set<ReturnType<typeof Bun.spawn>>()
+      const servers = new Map<string, HeldServer>()
       keepAlive.nodes.forEach((n, i) => {
+        const child = held[i]!
+        servers.set(n.id, {
+          child,
+          config: serverConfig(n, options.forwardArgs),
+          out: serverOuts.get(n.id) ?? { bus },
+          handOver: () => void handed.add(child),
+        })
         // One that died during the graph was said then.
-        if (hasEnded(held[i]!)) return
-        void held[i]!.exited.then((code) => {
-          if (!stopping && code !== 0) log.status(`vx: ${n.id} exited with code ${code}`)
+        if (hasEnded(child)) return
+        void child.exited.then((code) => {
+          if (!stopping && !handed.has(child) && code !== 0)
+            log.status(`vx: ${n.id} exited with code ${code}`)
         })
       })
       return {
@@ -1396,9 +1463,10 @@ async function runOnBus(
         outcomes: list,
         persistent: {
           ids: keepAlive.nodes.map((n) => n.id),
+          servers,
           stop: (signal) => {
             stopping = true
-            return terminateChildren(() => held, signal)
+            return terminateChildren(() => held.filter((c) => !handed.has(c)), signal)
           },
         },
       }