@vzn/vx 0.0.645 → 0.0.648

package/src/orchestrator/run-keys.ts

@@ -0,0 +1,300 @@
+// The run key memo: every up-front key a warm run derived, read back whole
+// when nothing any of them folds has moved. Deriving them again cost 250 ms
+// of a 1,070 ms warm run at 9,600 tasks even with every fold memo row
+// answering (2026-10-22): the per-task walk itself, not the files.
+//
+// The token is everything `deriveStableKeys` reads: each node's id, edges,
+// resolved config, plugin key parts and files token, the declared env
+// values, the forward args and the code that derives. A run the token cannot
+// vouch for (a keyless or runtime-probed task, a declaration no files token
+// covers) derives as before.
+
+import { readdirSync, statSync } from 'node:fs'
+import path from 'node:path'
+import type { GitFilesCache } from '../cache/index.js'
+import type { TaskNode } from '../graph/index.js'
+import { xxh3hex } from '../util/index.js'
+import type { StableKey } from './stable-keys.js'
+import { hashTaskConfig, isKeyless, taskFilesToken, type HashCache } from './task-hash.js'
+
+/** Moves every remembered run: bump it when what a token stands for changes. */
+const RUN_MEMO_VERSION = 'run-memo-v1'
+
+export interface RunKeysArgs {
+  nodes: Map<string, TaskNode>
+  workspaceRoot: string
+  claimedFiles: readonly string[]
+  forwardArgs?: readonly string[] | undefined
+  nestedDirsByProject: Map<string, string[]>
+  gitFilesCache: GitFilesCache
+  hashCache: HashCache
+}
+
+/** What a run's up-front pass yields, as the memo holds it. */
+export interface RunKeys {
+  stableKeys: StableKey[]
+  uncachedKeys: Map<string, string>
+}
+
+/** Where a run's keys are remembered: the selection's row, under its token. */
+export interface RunKeysAt {
+  id: string
+  token: string
+  /**
+   * The token less each node's files, and each node's files token, when a
+   * remembered graph fixes every edge and config (`graph`): an edit then
+   * moves only the files of the projects it touched, and the keys it
+   * reaches are all that derive again (`readRunDelta`).
+   */
+  delta?: () => { global: string; files: Map<string, string> }
+}
+
+/**
+ * The memo row's name (the selection) and the token its keys stand for, or
+ * undefined when a node's key reads something the token cannot name.
+ */
+export function runKeysToken(args: RunKeysArgs): RunKeysAt | undefined {
+  if (args.hashCache.folds === undefined) return undefined
+  const parts: string[] = [
+    RUN_MEMO_VERSION,
+    codeIdentity(),
+    args.workspaceRoot,
+    JSON.stringify(args.forwardArgs ?? []),
+    JSON.stringify([...args.claimedFiles].sort()),
+    JSON.stringify([...args.nestedDirsByProject]),
+    // Which outputs git ignores decides which a reader may see (`readableOutputs`).
+    [...args.gitFilesCache.ignoredOutputs].sort().join('\0'),
+  ]
+  // A remembered graph's token names every node's edges and config, so
+  // each node adds only what may differ under it (4 of 8 ms at 1,206
+  // tasks, 2026-10-23).
+  const graph = args.hashCache.graph
+  parts.push(graph ?? '')
+  const ids: string[] = []
+  const envNames = new Set<string>()
+  // Tasks of one project mostly declare the same files and outputs, and the
+  // token is a function of that declaration (`filesToken`): one walk each,
+  // not one per task (5 of 12 ms at 1,206 tasks, 2026-10-23).
+  const tokens = new Map<string, string>()
+  const filesAt: number[] = []
+  for (const node of args.nodes.values()) {
+    const cfg = node.config
+    if (isKeyless(cfg) || node.excludedUpstream !== undefined) return undefined
+    const inputs = cfg.inputs
+    if ((inputs?.runtime?.length ?? 0) > 0 || (inputs?.workspaceRuntime?.length ?? 0) > 0) {
+      return undefined
+    }
+    let files = ''
+    if (inputs !== undefined) {
+      if ((inputs.workspaceFiles?.length ?? 0) > 0) return undefined
+      // No positive entry resolves no files (`filesPlan`).
+      if (inputs.files === undefined || inputs.files.some((e) => !e.startsWith('!'))) {
+        const outputs = cfg.cache?.outputs
+        const declared = `${node.projectName}\0${JSON.stringify([inputs.files, outputs?.files, outputs?.workspaceFiles])}`
+        let token = tokens.get(declared)
+        if (token === undefined) {
+          token = taskFilesToken({
+            node,
+            workspaceRoot: args.workspaceRoot,
+            nestedProjectDirs: args.nestedDirsByProject.get(node.projectName) ?? [],
+            gitFilesCache: args.gitFilesCache,
+            hashCache: args.hashCache,
+          })
+          if (token === undefined) return undefined
+          tokens.set(declared, token)
+        }
+        files = token
+      }
+      for (const name of inputs.env ?? []) envNames.add(name)
+    }
+    ids.push(node.id)
+    if (graph !== undefined) {
+      parts.push(node.id, node.requested ? '1' : '0', node.platform ?? '')
+      filesAt.push(parts.push(files) - 1)
+      continue
+    }
+    parts.push(
+      node.id,
+      node.projectName,
+      node.projectDir,
+      node.deps.join('\u0001'),
+      (node.orderOnly ?? []).join('\u0001'),
+      node.requested ? '1' : '0',
+      hashTaskConfig(cfg, args.hashCache),
+      JSON.stringify(node.keyParts ?? []),
+      node.platform ?? '',
+      JSON.stringify(node.addsToOutputsOf ?? []),
+      JSON.stringify(node.outputsAddedToBy ?? []),
+      files,
+    )
+  }
+  for (const name of [...envNames].sort()) {
+    const value = process.env[name]
+    parts.push(value === undefined ? name : `${name}=${value}`)
+  }
+  const selection = xxh3hex(ids.join('\0'))
+  const at: RunKeysAt = { id: `\0run\0${selection}`, token: xxh3hex(parts.join('\0')) }
+  if (graph !== undefined) {
+    let delta: { global: string; files: Map<string, string> } | undefined
+    at.delta = () => {
+      if (delta !== undefined) return delta
+      const files = new Map<string, string>()
+      const hashed = new Map<string, string>()
+      const rest = [...parts]
+      filesAt.forEach((i, n) => {
+        const token = parts[i]!
+        let h = hashed.get(token)
+        if (h === undefined) hashed.set(token, (h = xxh3hex(token)))
+        files.set(ids[n]!, h)
+        rest[i] = ''
+      })
+      return (delta = { global: `${selection}\0${xxh3hex(rest.join('\0'))}`, files })
+    }
+  }
+  return at
+}
+
+/** The keys remembered under `token`, mapped back onto this run's nodes. */
+export function readRunKeys(
+  args: RunKeysArgs,
+  at: { id: string; token: string },
+): RunKeys | undefined {
+  const row = args.hashCache.folds?.get(at.id, at.token)
+  if (row === undefined) return undefined
+  let parsed: { s: [string, string][]; u: [string, string][] }
+  try {
+    parsed = JSON.parse(row)
+  } catch {
+    return undefined
+  }
+  const stableKeys: StableKey[] = []
+  for (const [id, hash] of parsed.s) {
+    const node = args.nodes.get(id)
+    if (node === undefined) return undefined
+    stableKeys.push({ hash, node })
+  }
+  return { stableKeys, uncachedKeys: new Map(parsed.u) }
+}
+
+/**
+ * What a run's derivation leaves for the next one to start from: every key
+ * it made, in the order it made them, and which became stable or uncached
+ * keys. Those verdicts are a function of the graph, the configs and what
+ * git ignores, all in the global token, so a run under the same global
+ * token keeps them and derives only the keys an edit reaches.
+ */
+export interface RunDerivation {
+  keys: Map<string, string>
+  stable: string[]
+  uncached: string[]
+}
+
+interface DeltaRow {
+  k: [string, string][]
+  f: [string, string][]
+  s: string[]
+  u: string[]
+}
+
+const deltaId = (at: RunKeysAt): string => `\0rund\0${at.id.slice('\0run\0'.length)}`
+
+/**
+ * The last derivation under this run's global token, and the tasks whose
+ * keys may have moved since: each one whose files token did, and every task
+ * folding one of theirs. Undefined when no such derivation is remembered.
+ */
+export function readRunDelta(
+  args: RunKeysArgs,
+  at: RunKeysAt,
+): { derivation: RunDerivation; dirty: Set<string> } | undefined {
+  if (at.delta === undefined) return undefined
+  const { global, files } = at.delta()
+  const row = args.hashCache.folds?.get(deltaId(at), global)
+  if (row === undefined) return undefined
+  let parsed: DeltaRow
+  try {
+    parsed = JSON.parse(row)
+  } catch {
+    return undefined
+  }
+  const was = new Map(parsed.f)
+  const dirty = new Set<string>()
+  for (const [id, token] of files) if (was.get(id) !== token) dirty.add(id)
+  const dependants = new Map<string, string[]>()
+  for (const node of args.nodes.values()) {
+    for (const dep of node.deps) {
+      const list = dependants.get(dep)
+      if (list === undefined) dependants.set(dep, [node.id])
+      else list.push(node.id)
+    }
+  }
+  const stack = [...dirty]
+  while (stack.length > 0) {
+    for (const up of dependants.get(stack.pop()!) ?? []) {
+      if (dirty.has(up)) continue
+      dirty.add(up)
+      stack.push(up)
+    }
+  }
+  return {
+    derivation: { keys: new Map(parsed.k), stable: parsed.s, uncached: parsed.u },
+    dirty,
+  }
+}
+
+export function writeRunDelta(args: RunKeysArgs, at: RunKeysAt, derivation: RunDerivation): void {
+  if (at.delta === undefined || args.hashCache.folds === undefined) return
+  const { global, files } = at.delta()
+  const row: DeltaRow = {
+    k: [...derivation.keys],
+    f: [...files],
+    s: derivation.stable,
+    u: derivation.uncached,
+  }
+  args.hashCache.folds.set(deltaId(at), global, JSON.stringify(row))
+}
+
+export function writeRunKeys(
+  args: RunKeysArgs,
+  at: { id: string; token: string },
+  keys: RunKeys,
+): void {
+  args.hashCache.folds?.set(
+    at.id,
+    at.token,
+    JSON.stringify({
+      s: keys.stableKeys.map((k) => [k.node.id, k.hash]),
+      u: [...keys.uncachedKeys],
+    }),
+  )
+}
+
+let identity: string | undefined
+
+/**
+ * The code that derives the keys: a compiled binary is its file; a source
+ * checkout is every module under `src/`, so an edit to the derivation from
+ * source never reads back a key the old code made.
+ */
+export function codeIdentity(): string {
+  if (identity !== undefined) return identity
+  // `Bun.main`, not `import.meta.dir`: `--minify` inlines the build
+  // machine's source path, so an installed binary walked a `src/` that is
+  // not there, threw, and lost every warm run's short circuit (2026-10-22).
+  // ctime and inode with the mtime, as the file hash memo keys: an npm
+  // tarball stamps every file 1985-10-26 and extraction keeps that mtime,
+  // so an upgrade that kept a file's size left its stamp alone, and `cp
+  // -p` does the same to a binary. No write can set ctime back.
+  if (Bun.main.startsWith('/$bunfs/')) {
+    const st = statSync(process.execPath)
+    return (identity = `${process.execPath}:${st.size}:${st.mtimeMs}:${st.ctimeMs}:${st.ino}`)
+  }
+  const src = path.resolve(import.meta.dir, '..')
+  const stamps: string[] = []
+  for (const rel of readdirSync(src, { recursive: true, encoding: 'utf8' }).sort()) {
+    if (!rel.endsWith('.ts')) continue
+    const st = statSync(path.join(src, rel))
+    stamps.push(`${rel}:${st.size}:${st.mtimeMs}:${st.ctimeMs}:${st.ino}`)
+  }
+  return (identity = xxh3hex(stamps.join('\0')))
+}

package/src/orchestrator/run-live.ts

@@ -0,0 +1,294 @@
+// The run in progress, for `vx last --live` (2026-10-28): an agent that
+// started `vx run` in the background asks what runs, what already failed
+// and what it was warned of while the run goes on; the history holds a
+// run only once it ended.
+//
+// The run answers on a unix socket beside its run lock (run-lock.ts),
+// `<lock>.sock`: in this user's own lock directory, so no other user
+// reaches it, and taken only while the lock is held, so a socket a killed
+// run left is this run's to replace. Nothing is written for it: the run
+// keeps which task started when (one Map entry per task) and builds the
+// snapshot only when asked. Output is not kept; a reader that wants it
+// follows (`--follow`), and a follower is fed only while it is attached
+// and keeps up: one that falls a megabyte behind is let go, so a stuck
+// reader never holds the run's memory or its event loop.
+//
+// The path is left with the lock, before the run's last steps, and a
+// follower stays attached through `run:done`.
+//
+// The protocol is one request line, `snapshot` or `follow`, then the
+// snapshot as one JSON line; a follower then gets each `WireEvent` as a
+// line until `run:done`, and the run closes the connection.
+
+import { unlinkSync } from 'node:fs'
+import type { Socket, UnixSocketListener } from 'bun'
+import { isGroupTask, type TaskNode } from '../graph/index.js'
+import {
+  type EventBus,
+  type OutcomeView,
+  projectOutcome,
+  toWireEvent,
+  type WireEvent,
+} from '../report/index.js'
+import { runLockPath } from './run-lock.js'
+
+/** One task as a live reader sees it. */
+export interface LiveTask {
+  taskId: string
+  /** `waiting`, `running`, or the status it ended with. */
+  status: 'waiting' | 'running' | OutcomeView['status']
+  /** Epoch ms it started; null while it waits (and for a skip, which never starts). */
+  startedAt: number | null
+  /** Null until it ends. */
+  durationMs: number | null
+}
+
+/** What `vx last --live --format json` prints, the snapshot line. */
+export interface LiveSnapshot {
+  live: { runId: string; command: string; pid: number; startedAt: number; elapsedMs: number }
+  tasks: LiveTask[]
+  warnings: string[]
+}
+
+/** Where the run of `workspaceRoot` answers: beside its run lock. */
+export function liveSocketPath(workspaceRoot: string, lockDir?: string): string {
+  return liveSocketOf(runLockPath(workspaceRoot, lockDir))
+}
+
+/** The live socket beside the run lock at `lockPath`. */
+export function liveSocketOf(lockPath: string): string {
+  return `${lockPath}.sock`
+}
+
+/** A follower this far behind is let go. */
+const FOLLOW_BACKLOG = 1 << 20
+
+interface Peer {
+  follow: boolean
+  /** Bytes the socket did not take yet. */
+  pending: Uint8Array[]
+  pendingBytes: number
+  /** End the connection once `pending` drains. */
+  ending: boolean
+  request: string
+}
+
+const encoder = new TextEncoder()
+
+/**
+ * The sockets this process listens on. A signal exit is `process.exit`
+ * (signals.ts): `unlisten` never runs, and a second Ctrl-C left the
+ * socket beside the released lock. The `exit` event runs on every exit
+ * path, synchronously, as run-lock.ts's release does; this one runs
+ * first, so the path is left before the lock frees it for the next run.
+ */
+const listening = new Set<string>()
+let exitHooked = false
+function unlinkOnExit(socketPath: string): void {
+  listening.add(socketPath)
+  if (exitHooked) return
+  exitHooked = true
+  process.prependListener('exit', () => {
+    for (const p of listening) {
+      try {
+        unlinkSync(p)
+      } catch {
+        // Gone already.
+      }
+    }
+  })
+}
+
+/**
+ * Serve the run's live state on `socketPath` until the returned close.
+ * Never fails the run: a socket that cannot be made (a path too long, a
+ * second run in this process holding it) leaves the run unanswered.
+ */
+export function serveLive(opts: {
+  socketPath: string
+  bus: EventBus
+  runId: string
+  command: string
+  startedAt: number
+  nodes: () => Iterable<TaskNode>
+  warnings: () => readonly string[]
+}): { unlisten(): void; dispose(): void } {
+  const started = new Map<string, number>()
+  const ended = new Map<
+    string,
+    OutcomeView['status'] | { status: OutcomeView['status']; durationMs: number }
+  >()
+  const peers = new Map<Socket<Peer>, Peer>()
+  let followers = 0
+
+  const flush = (sock: Socket<Peer>, peer: Peer): void => {
+    while (peer.pending.length > 0) {
+      const head = peer.pending[0]!
+      const n = sock.write(head)
+      if (n < 0) return
+      peer.pendingBytes -= n
+      if (n < head.length) {
+        peer.pending[0] = head.subarray(n)
+        return
+      }
+      peer.pending.shift()
+    }
+    if (peer.ending) sock.end()
+  }
+  const send = (sock: Socket<Peer>, peer: Peer, line: string): void => {
+    const bytes = encoder.encode(`${line}\n`)
+    peer.pending.push(bytes)
+    peer.pendingBytes += bytes.length
+    if (peer.follow && peer.pendingBytes > FOLLOW_BACKLOG) {
+      drop(sock, peer)
+      return
+    }
+    if (peer.pending.length === 1) flush(sock, peer)
+  }
+  const drop = (sock: Socket<Peer>, peer: Peer): void => {
+    if (peers.delete(sock) && peer.follow) followers--
+    sock.end()
+  }
+
+  const snapshot = (): LiveSnapshot => {
+    const now = Date.now()
+    const tasks: LiveTask[] = []
+    for (const node of opts.nodes()) {
+      if (isGroupTask(node)) continue
+      const at = started.get(node.id) ?? null
+      const end = ended.get(node.id)
+      tasks.push(
+        end !== undefined && typeof end === 'object'
+          ? { taskId: node.id, status: end.status, startedAt: at, durationMs: end.durationMs }
+          : at !== null
+            ? { taskId: node.id, status: 'running', startedAt: at, durationMs: null }
+            : { taskId: node.id, status: 'waiting', startedAt: null, durationMs: null },
+      )
+    }
+    const rank = (t: LiveTask): number =>
+      t.status === 'running' ? 0 : t.status === 'waiting' ? 2 : 1
+    tasks.sort(
+      (a, b) => rank(a) - rank(b) || (a.taskId < b.taskId ? -1 : a.taskId > b.taskId ? 1 : 0),
+    )
+    return {
+      live: {
+        runId: opts.runId,
+        command: opts.command,
+        pid: process.pid,
+        startedAt: opts.startedAt,
+        elapsedMs: now - opts.startedAt,
+      },
+      tasks,
+      warnings: opts.warnings().map((w) => Bun.stripANSI(w)),
+    }
+  }
+
+  const unsubscribe = opts.bus.subscribe((event) => {
+    if (event.kind === 'task:start') started.set(event.node.id, Date.now())
+    else if (event.kind === 'task:complete') {
+      ended.set(event.node.id, {
+        status: event.outcome.status,
+        durationMs: event.outcome.durationMs,
+      })
+    }
+    if (followers === 0) return
+    if (
+      (event.kind === 'task:start' || event.kind === 'task:complete') &&
+      isGroupTask(event.node)
+    ) {
+      return
+    }
+    const wire: WireEvent =
+      event.kind === 'task:complete'
+        ? { kind: 'task:complete', outcome: projectOutcome(event.outcome) }
+        : toWireEvent(event)
+    const line = JSON.stringify(wire)
+    for (const [sock, peer] of peers) {
+      if (!peer.follow) continue
+      send(sock, peer, line)
+      if (event.kind === 'run:done') peer.ending = true
+      if (peer.ending && peer.pending.length === 0) drop(sock, peer)
+    }
+  })
+
+  let listener: UnixSocketListener<Peer> | undefined
+  try {
+    unlinkSync(opts.socketPath)
+  } catch {
+    // None there: the usual case.
+  }
+  try {
+    const made = Bun.listen<Peer>({
+      unix: opts.socketPath,
+      socket: {
+        open(sock) {
+          const peer: Peer = {
+            follow: false,
+            pending: [],
+            pendingBytes: 0,
+            ending: false,
+            request: '',
+          }
+          sock.data = peer
+          peers.set(sock, peer)
+        },
+        data(sock, chunk) {
+          const peer = sock.data
+          if (peer.request.includes('\n')) return
+          peer.request += chunk.toString()
+          if (!peer.request.includes('\n')) return
+          const what = peer.request.trim()
+          send(sock, peer, JSON.stringify(snapshot()))
+          if (what === 'follow') {
+            peer.follow = true
+            followers++
+          } else {
+            peer.ending = true
+            if (peer.pending.length === 0) drop(sock, peer)
+          }
+        },
+        drain(sock) {
+          flush(sock, sock.data)
+        },
+        close(sock) {
+          const peer = peers.get(sock)
+          if (peer !== undefined) drop(sock, peer)
+        },
+        error(sock) {
+          const peer = peers.get(sock)
+          if (peer !== undefined) drop(sock, peer)
+        },
+      },
+    })
+    // The socket must never keep a run's process alive past its end.
+    made.unref()
+    listener = made
+    unlinkOnExit(opts.socketPath)
+  } catch {
+    listener = undefined
+  }
+
+  return {
+    // With the run lock: the next run may take the path the moment the lock
+    // is free, so this run stops taking connections and leaves the path
+    // first. Followers already attached stay, through `run:done`.
+    unlisten: () => {
+      if (listener === undefined) return
+      listener.stop()
+      listener = undefined
+      listening.delete(opts.socketPath)
+      try {
+        unlinkSync(opts.socketPath)
+      } catch {
+        // Gone already.
+      }
+    },
+    dispose: () => {
+      unsubscribe()
+      for (const [sock, peer] of [...peers]) {
+        if (peer.pending.length > 0) peer.ending = true
+        else drop(sock, peer)
+      }
+    },
+  }
+}

package/src/orchestrator/run-lock.ts

@@ -126,6 +126,9 @@ export interface RunLockOptions {
   signal?: AbortSignal | undefined
 }
 
+/** Releases a taken run lock; `path` is its directory (`runLockPath`). */
+export type RunLockRelease = (() => Promise<void>) & { readonly path: string }
+
 /**
  * The lock directory for a workspace root: stable across this user's runs,
  * private to this machine. Keyed by the REAL path: a CLI's cwd comes back
@@ -323,16 +326,18 @@ async function leave(lockDir: string, entry: string): Promise<void> {
 /**
  * Take the workspace's run lock, waiting for a live holder in another
  * process to release it. Resolves to the release function; the caller
- * runs it on every exit path.
+ * runs it on every exit path. It carries the lock's `path`, so a run's
+ * live socket beside it costs no second realpath and hash.
  */
 export async function acquireRunLock(
   workspaceRoot: string,
   opts: RunLockOptions,
-): Promise<() => Promise<void>> {
+): Promise<RunLockRelease> {
   const lockDir = runLockPath(workspaceRoot, opts.dir)
   // A task's own process (`vx cache clean` in a task) would wait for the
   // run that started it, which holds the lock until that task ends.
-  const outer = process.env[VX_RUN_WORKSPACE_ENV]
+  // Empty is unset: resolved, '' named the cwd.
+  const outer = process.env[VX_RUN_WORKSPACE_ENV] || undefined
   if (outer !== undefined && runLockPath(outer, opts.dir) === lockDir) {
     throw new UserError(
       `this vx runs inside task ${process.env[VX_RUN_TASK_ENV] ?? '<unknown>'} of a vx run on this workspace, which holds its run lock until it ends — run it before or after that run, not from one of its tasks`,
@@ -363,12 +368,13 @@ export async function acquireRunLock(
       if (takers.get(lockDir) === taker) takers.delete(lockDir)
     }
   }
+  const held: RunLockRelease = Object.assign(release, { path: lockDir })
   for (;;) {
-    if (opts.signal?.aborted === true) return async () => {}
+    if (opts.signal?.aborted === true) return Object.assign(async () => {}, { path: lockDir })
     const here = heldHere.get(lockDir) ?? 0
     if (here > 0) {
       heldHere.set(lockDir, here + 1)
-      return release
+      return held
     }
     let h: Holder | 'free' | null
     try {
@@ -379,7 +385,7 @@ export async function acquireRunLock(
         heldHere.set(lockDir, 1)
         takers.set(lockDir, entry)
         releaseOnExit()
-        return release
+        return held
       }
       h = await holder(lockDir)
       if (h === 'free') continue
@@ -402,7 +408,7 @@ export async function acquireRunLock(
       opts.log(
         `[vx] no run lock for this workspace (${(err as Error).message}${hint}) — another vx run on it at the same time may race this one`,
       )
-      return async () => {}
+      return Object.assign(async () => {}, { path: lockDir })
     }
     if (h !== null && !said && Date.now() - started >= SAY_AFTER_MS) {
       said = true