@vzn/vx 0.0.645 → 0.0.646

package/src/orchestrator/run-keys.ts

@@ -0,0 +1,164 @@
+// 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>
+}
+
+/**
+ * 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): { id: string; token: string } | 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'),
+  ]
+  const ids: string[] = []
+  const envNames = new Set<string>()
+  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 token = taskFilesToken({
+          node,
+          workspaceRoot: args.workspaceRoot,
+          nestedProjectDirs: args.nestedDirsByProject.get(node.projectName) ?? [],
+          gitFilesCache: args.gitFilesCache,
+          hashCache: args.hashCache,
+        })
+        if (token === undefined) return undefined
+        files = token
+      }
+      for (const name of inputs.env ?? []) envNames.add(name)
+    }
+    ids.push(node.id)
+    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 ?? []),
+      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}`)
+  }
+  return { id: `\0run\0${xxh3hex(ids.join('\0'))}`, token: xxh3hex(parts.join('\0')) }
+}
+
+/** 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) }
+}
+
+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.
+ */
+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).
+  if (Bun.main.startsWith('/$bunfs/')) {
+    const st = statSync(process.execPath)
+    return (identity = `${process.execPath}:${st.size}:${st.mtimeMs}:${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}`)
+  }
+  return (identity = xxh3hex(stamps.join('\0')))
+}

package/src/orchestrator/run-records.ts

@@ -113,6 +113,11 @@ export function assembleRunRecords(input: RunRecordsInput): RunRecords {
       runId,
       ...(o.cpuMs !== undefined ? { cpuMs: o.cpuMs } : {}),
       ...(o.peakRssBytes !== undefined ? { peakRssBytes: o.peakRssBytes } : {}),
+      ...(o.peakCores !== undefined ? { peakCores: o.peakCores } : {}),
+      ...(o.avgRssBytes !== undefined ? { avgRssBytes: o.avgRssBytes } : {}),
+      ...(o.where !== undefined ? { placement: o.where } : {}),
+      ...(o.whereCores !== undefined ? { placementCores: o.whereCores } : {}),
+      ...(o.whereMemoryBytes !== undefined ? { placementMemoryBytes: o.whereMemoryBytes } : {}),
       ...(o.wallclockStartNs !== undefined ? { wallclockStartNs: o.wallclockStartNs } : {}),
       ...(o.wallclockEndNs !== undefined ? { wallclockEndNs: o.wallclockEndNs } : {}),
       cacheHit: isCacheHit(o.status),
@@ -126,6 +131,7 @@ export function assembleRunRecords(input: RunRecordsInput): RunRecords {
       ...(o.sandboxViolations !== undefined ? { sandboxViolations: o.sandboxViolations } : {}),
       ...(o.notReady !== undefined ? { notReady: o.notReady } : {}),
       ...(remoteError !== undefined ? { remoteError } : {}),
+      ...(o.keylessBy !== undefined ? { keylessBy: o.keylessBy } : {}),
     })
     if (o.status === 'failed') failedCount++
     if (o.status === 'cache-hit') hitLocalCount++

package/src/orchestrator/run.ts

@@ -24,7 +24,7 @@ import {
 } from '../exec/index.js'
 import { DeferredOutputs } from './deferred-outputs.js'
 import { resolveDownloadModes } from './download-policy.js'
-import type { TaskExecutor } from '../exec/index.js'
+import type { MachineReport, TaskExecutor } from '../exec/index.js'
 import {
   deadServerBehind,
   declaredTask,
@@ -51,6 +51,7 @@ import {
   detectColors,
   type ColorSupport,
   SecretBroker,
+  type ui,
 } from '../util/index.js'
 import { keyedProjects } from './keyed-projects.js'
 import { isDefaultBuild } from './projects.js'
@@ -114,6 +115,7 @@ import {
   type ShortCircuit,
 } from './local-shortcircuit.js'
 import { deriveStableKeys, probesAfterWrites } from './stable-keys.js'
+import { askRemote, serversToHold } from './held-servers.js'
 
 import { writeRunFailures } from './run-failures.js'
 import { assembleRunRecords, recordLateRemoteErrors } from './run-records.js'
@@ -136,6 +138,7 @@ import {
 } from '../history/index.js'
 import type { RunOptions, RunSummary } from './options.js'
 import { withRunSettings } from './run-settings.js'
+import { cacheFacts, taskArtifacts } from './task-artifacts.js'
 import { resolveSetting } from '../settings.js'
 
 // Per run, never shared: a `vx watch` process runs many, and a shared map
@@ -145,6 +148,7 @@ const emptyShortCircuit = (): ShortCircuit => ({
   restoreTier: new Set(),
   uncachedKeys: new Map(),
   groupKeys: new Map(),
+  remoteAsk: new Map(),
 })
 
 /**
@@ -547,6 +551,8 @@ async function runOnBus(
       cacheDir: prepared.cacheDir,
       warn: warnOf(log),
       concurrency,
+      artifacts: taskArtifacts(prepared.cache, prepared.workspaceRoot),
+      cacheFacts: () => cacheFacts(prepared.remotes, prepared.cacheRefs),
     }),
   )
   // Placement: decided ONCE per task, before scheduling, so the scheduler
@@ -744,10 +750,19 @@ async function runOnBus(
       n.config.exec?.persistent !== undefined ||
       n.config.cache === undefined ||
       !(policy.localRead || policy.remoteRead)
+    // Only what runs here arms this machine's sandbox: a `sandbox` executor
+    // enforces it where it runs the task, so a distributed run's
+    // orchestrator needs none (owner, 2026-10-22).
     const sandboxed =
       sandboxArmer === null
         ? []
-        : [...nodes.values()].filter((n) => n.config.exec?.sandbox !== undefined)
+        : [...nodes.values()].filter(
+            (n) =>
+              n.config.exec?.sandbox !== undefined &&
+              (n.config.exec.persistent === undefined
+                ? localPlaced.has(n.id)
+                : !placements.carried.has(n.id)),
+          )
     let prewarming: Promise<void> | undefined
     const prewarm = (): void => {
       prewarming ??= sandboxArmer?.arm().catch(() => {})
@@ -800,7 +815,16 @@ async function runOnBus(
 
     // Run context for the footer. The top-of-run header is gone — the
     // banner now lives in the summary, where the eye lands at the end.
+    const footers = executors.filter((e) => e.footer !== undefined)
+    const placers = executors.filter((e) => e.running !== undefined)
     const runContext = {
+      ...(footers.length > 0 ? { executorRows: () => footers.flatMap(executorFooter) } : {}),
+      ...(placers.length > 0
+        ? {
+            whereRunning: (id: string) =>
+              placers.map((e) => executorWhere(e, id)).find((w) => w !== undefined),
+          }
+        : {}),
       version: VERSION,
       packageCount: packagesInScope.size,
       remoteCacheEnabled,
@@ -816,7 +840,8 @@ async function runOnBus(
       },
       concurrency,
       workspaceProjectCount,
-      runId: undefined as string | undefined,
+      // Live too: a long run is read while it runs (M, 2026-10-21).
+      runId,
     }
 
     // Asked only when a plugin declares `output`: a plain run pays nothing.
@@ -902,10 +927,19 @@ async function runOnBus(
       shouldShortCircuit(nodes, policy) && (remote || cache === prepared.localCache)
         ? prepared.localCache.holdsNothing()
         : false
+    // Behind a remote, a server's dependants need their keys up front even
+    // on an empty store: the remote may hold them all, and then the server
+    // never starts (`held-servers.ts`).
+    const askForServers =
+      remote &&
+      policy.remoteRead &&
+      [...nodes.values()].some(
+        (n) => n.config.exec?.persistent !== undefined && !n.requested && n.surfaced !== true,
+      )
     // A remote may still hold what an empty local store does not: the
     // prefetch asks it, and no confirmed miss warms the sandbox early.
-    if (coldLocal && !remote) prewarm()
-    else if (!coldLocal && shouldShortCircuit(nodes, policy)) {
+    if (coldLocal && !remote && sandboxed.length > 0) prewarm()
+    else if ((!coldLocal || askForServers) && shouldShortCircuit(nodes, policy)) {
       shortCircuit = await step('vx:keys', () =>
         startLocalShortCircuit({
           nodes,
@@ -1158,6 +1192,16 @@ async function runOnBus(
       // runs ahead of their deps as low-priority worker-slot backfill.
       // Empty when the short-circuit didn't fire → byte-identical.
       restoreTier: shortCircuit.restoreTier,
+      ...(askForServers
+        ? {
+            heldServers: askRemote(
+              serversToHold(nodes, shortCircuit.restoreTier, shortCircuit.remoteAsk),
+              nodes,
+              shortCircuit,
+              cache,
+            ),
+          }
+        : {}),
     })
     stop.graphDone()
     reprioritize = undefined
@@ -1297,9 +1341,15 @@ async function runOnBus(
         recordHistory(() => cache.recordRunBundle(records))
         recordFailures(list)
       })
+    } else if (stop.stoppedBy !== undefined) {
+      // Stopped: not a run `vx last` lists (item 854), but what finished is
+      // measured, or the next run knows none of it (M, 2026-10-21).
+      const ended = list.filter((o) => o.status !== 'aborted' && o.status !== 'skipped')
+      stepSync('vx:history', () =>
+        recordHistory(() => prepared.localCache.recordRuns(recordsOf(ended, false).runs)),
+      )
     }
     mark('record history')
-    runContext.runId = runId
     // Drain any still-in-flight background prefetches before closing the
     // cache handle — a prefetch ingesting into a closed SQLite DB would
     // throw. Tasks that resolved as local hits never awaited their
@@ -1345,6 +1395,7 @@ async function runOnBus(
         abortedCount: list.filter((o) => o.status === 'aborted' && !isGroupTask(o.node)).length,
         stages: stageTimes(),
         uploads: prepared.localCache.uploads,
+        machines: executors.flatMap(executorMachines),
       })
       telemetry.emitSummary(summary)
       const sinks = telemetry
@@ -1816,3 +1867,39 @@ function canonical(dir: string): string {
     return path.resolve(dir)
   }
 }
+
+/** An executor's footer rows; a plugin's throw or bad shape shows none. */
+function executorFooter(e: TaskExecutor): (readonly [string, ui.Inline])[] {
+  try {
+    const rows = e.footer?.()
+    if (!Array.isArray(rows)) return []
+    return rows.filter(
+      (r): r is readonly [string, ui.Inline] =>
+        Array.isArray(r) &&
+        typeof r[0] === 'string' &&
+        (typeof r[1] === 'string' || (typeof r[1] === 'object' && r[1] !== null)),
+    )
+  } catch {
+    return []
+  }
+}
+
+function executorMachines(e: TaskExecutor): readonly MachineReport[] {
+  try {
+    const m = e.machines?.()
+    return Array.isArray(m) ? m : []
+  } catch {
+    return []
+  }
+}
+
+/** Where `e` says a task runs, or `null` while it waits; a throw or anything else says nothing. */
+function executorWhere(e: TaskExecutor, id: string): string | null | undefined {
+  try {
+    const w = e.running?.(id)
+    if (w === null) return null
+    return typeof w === 'string' && w !== '' ? w : undefined
+  } catch {
+    return undefined
+  }
+}

package/src/orchestrator/sandbox-request.ts

@@ -45,6 +45,11 @@ export interface SandboxArmer {
   readonly armed: boolean
 }
 
+/** What the run's sandbox union reads of a task: a `TaskNode`, or an agent's order. */
+export interface SandboxedNode {
+  readonly config: { readonly exec?: { readonly sandbox?: ExecConfig['sandbox'] } }
+}
+
 /**
  * What SRT's run-wide `initialize()` is armed with, folded from every
  * sandboxed task in the graph — or `null` when the run has none.
@@ -71,7 +76,7 @@ export interface SandboxRunUnion {
   weakerNested: boolean
 }
 
-export function sandboxRunUnion(nodes: Iterable<TaskNode>): SandboxRunUnion | null {
+export function sandboxRunUnion(nodes: Iterable<SandboxedNode>): SandboxRunUnion | null {
   const sandboxed = [...nodes].filter((n) => n.config.exec?.sandbox !== undefined)
   if (sandboxed.length === 0) return null
   const weakerNested = sandboxed.every((n) => n.config.exec?.sandbox?.weakerWhenNested === true)
@@ -119,7 +124,7 @@ export function sandboxRunUnion(nodes: Iterable<TaskNode>): SandboxRunUnion | nu
  * port list (its bridge is a unix socket the task's side creates), lifts
  * it for the run. macOS keeps per-task precision through vx's own rules.
  */
-export function prepareSandbox(nodes: Iterable<TaskNode>): SandboxArmer | null {
+export function prepareSandbox(nodes: Iterable<SandboxedNode>): SandboxArmer | null {
   const union = sandboxRunUnion(nodes)
   if (union === null) return null
   const { domains, deniedDomains, unixSockets, gitConfig, weakerNested } = union
@@ -180,7 +185,7 @@ export function prepareSandbox(nodes: Iterable<TaskNode>): SandboxArmer | null {
  * with no `cache`, which has no key to be stale.
  */
 export async function sandboxRequestFor(
-  node: TaskNode,
+  node: Pick<TaskNode, 'projectDir'>,
   sandbox: NonNullable<ExecConfig['sandbox']>,
   workspaceRoot: string,
   keyed: ReadonlySet<string> | undefined,
@@ -285,6 +290,7 @@ export async function sandboxRequestFor(
     // withholding exists to stop, not the wall.
     reportLinked: links.withheld.map((w) => w.dir),
     config,
+    ...(keyed === undefined ? {} : { keyed: [...keyed] }),
   }
   return { sandbox: request, placeholders, withheld: links.withheld }
 }

package/src/orchestrator/task-artifacts.ts

@@ -0,0 +1,142 @@
+// Task entries by key for an executor that runs a task on another machine
+// (`ExecutorContext.artifacts`, `CommandContext.artifacts`): the machine
+// that ran it saves its outputs and output under the key the order named,
+// and the one that needs them restores them, through the workspace's own
+// cache (design packages/vx/docs/design/dte-2026-10.md, "Files").
+
+import {
+  type CacheLayer,
+  type ResolvedRemote,
+  resolveOutputTree,
+  resolveWorkspaceOutputs,
+} from '../cache/index.js'
+import { secretMask } from '../util/index.js'
+import { decodeOutputLog, encodeOutputLog } from './output-log.js'
+
+/** The task a `TaskArtifacts` call names: where its outputs are and what ran. */
+export interface ArtifactTask {
+  /** `project#task`. */
+  readonly id: string
+  /** Absolute. */
+  readonly projectDir: string
+  readonly command: string
+  /** Its `cache.outputs`: project-relative `files`, root-relative `workspaceFiles`. */
+  readonly outputs: {
+    readonly files: readonly string[]
+    readonly workspaceFiles: readonly string[]
+  }
+  /** The projects inside `projectDir` (absolute), whose files are not its outputs. */
+  readonly nestedProjectDirs?: readonly string[]
+}
+
+/** What a task's run left besides its files: its output, and its time and usage. */
+export interface ArtifactRun {
+  readonly stdout: string
+  readonly stderr: string
+  readonly durationMs: number
+  readonly cpuMs?: number
+  readonly peakRssBytes?: number
+  /** Its environment: a secret value in it is masked out of the stored output. */
+  readonly env?: Readonly<Record<string, string | undefined>>
+}
+
+export interface TaskArtifacts {
+  /**
+   * Keeps the files `task`'s outputs match, and its output, as entry
+   * `key`: here, and on each remote the workspace writes. Resolves once
+   * every upload has settled; a remote that fails degrades as a run's
+   * upload does.
+   */
+  save(key: string, task: ArtifactTask, run: ArtifactRun): Promise<void>
+  /**
+   * Lays entry `key`'s files into the workspace, from the local store or
+   * else the first remote holding it, and resolves its output; null when
+   * none holds it. A key restored here and then saved is not uploaded
+   * again.
+   */
+  restore(key: string, task: ArtifactTask): Promise<{ stdout: string; stderr: string } | null>
+}
+
+export function taskArtifacts(cache: CacheLayer, workspaceRoot: string): TaskArtifacts {
+  return {
+    async save(key, task, run) {
+      const [tree, wsFiles] = await Promise.all([
+        resolveOutputTree({
+          projectDir: task.projectDir,
+          outputs: task.outputs.files,
+          nestedProjectDirs: [...(task.nestedProjectDirs ?? [])],
+        }),
+        resolveWorkspaceOutputs({ workspaceRoot, outputs: task.outputs.workspaceFiles }),
+      ])
+      const mask = secretMask([process.env, run.env ?? {}])
+      const log = encodeOutputLog([
+        { text: run.stdout, err: false },
+        { text: run.stderr, err: true },
+      ])
+      await cache.save({
+        hash: key,
+        projectDir: task.projectDir,
+        outputFiles: tree.files,
+        ...(tree.emptyDirs.length > 0 ? { outputDirs: tree.emptyDirs } : {}),
+        workspaceRoot,
+        ...(wsFiles.length > 0 ? { workspaceOutputFiles: wsFiles } : {}),
+        entry: {
+          taskId: task.id,
+          command: mask?.mask(task.command) ?? task.command,
+          durationMs: run.durationMs,
+          stdout: mask?.mask(log) ?? log,
+          ...(run.cpuMs !== undefined ? { cpuMs: run.cpuMs } : {}),
+          ...(run.peakRssBytes !== undefined ? { peakRssBytes: run.peakRssBytes } : {}),
+        },
+      })
+      await cache.drainUploads?.()
+    },
+
+    async restore(key, task) {
+      const entry = await (cache.getSaved ? cache.getSaved(key) : cache.get(key))
+      if (entry === null) return null
+      await cache.restoreOutputs(key, task.projectDir, workspaceRoot, task.outputs)
+      let stdout = ''
+      let stderr = ''
+      for (const c of decodeOutputLog(entry.stdout)) {
+        if (c.err) stderr += c.text
+        else stdout += c.text
+      }
+      return { stdout, stderr }
+    },
+  }
+}
+
+/**
+ * What a run's cache is read under, for a machine that runs its tasks
+ * (`ExecutorContext.cacheFacts`, `CommandContext.artifactsFor`): the
+ * refs the run worked out, so that machine reads as the run would, and
+ * the access each remote lent, by plugin.
+ */
+export interface CacheFacts {
+  /** `CacheContext.refs`. */
+  readonly refs: readonly string[]
+  /** Plugin name → the token its remote's `lend` gave. */
+  readonly lent: Readonly<Record<string, string>>
+  /** Epoch ms: the first lent token's end, before which to ask again. */
+  readonly expiresAt?: number
+}
+
+/** The run's `CacheFacts`: each readable remote's `lend`, asked now; one that throws lends nothing. */
+export async function cacheFacts(
+  remotes: readonly ResolvedRemote[],
+  refs: readonly string[],
+): Promise<CacheFacts> {
+  const lent: Record<string, string> = {}
+  let expiresAt: number | undefined
+  await Promise.all(
+    remotes.map(async (r) => {
+      if (r.plugin === undefined || r.remote.lend === undefined || !r.read) return
+      const got = await r.remote.lend().catch(() => undefined)
+      if (got === undefined) return
+      lent[r.plugin] = got.token
+      if (got.expiresAt !== undefined) expiresAt = Math.min(expiresAt ?? Infinity, got.expiresAt)
+    }),
+  )
+  return { refs, lent, ...(expiresAt === undefined ? {} : { expiresAt }) }
+}

package/src/orchestrator/task-hash.ts

@@ -297,6 +297,16 @@ export async function movedInput(
   return undefined
 }
 
+/** A task's `filesToken`, as its key's fold memo probe takes it. */
+export function taskFilesToken(
+  args: Pick<
+    ComputeHashArgs,
+    'node' | 'workspaceRoot' | 'nestedProjectDirs' | 'gitFilesCache' | 'hashCache'
+  >,
+): string | undefined {
+  return filesToken(inputsArgs({ ...args, upstream: [], cache: undefined as never }))
+}
+
 /** What `resolveInputs` is asked for a task's key. */
 function inputsArgs(args: ComputeHashArgs): ResolveInputsArgs {
   const cfg = args.node.config
@@ -411,7 +421,7 @@ async function resolveKeyInput(
  * each task's config object is created once per run, so a hit there
  * skips the JSON.stringify + xxh3 entirely.
  */
-function hashTaskConfig(cfg: TaskConfig, hashCache?: HashCache): string {
+export function hashTaskConfig(cfg: TaskConfig, hashCache?: HashCache): string {
   if (hashCache) {
     const cached = hashCache.taskConfig.get(cfg)
     if (cached !== undefined) return cached

package/src/orchestrator/task-process.ts

@@ -11,6 +11,7 @@ import {
   PM_EXEC_ENV,
   VX_RUN_TASK_ENV,
   VX_RUN_WORKSPACE_ENV,
+  type ServerSpec,
 } from '../exec/index.js'
 import type { TaskNode } from '../graph/index.js'
 import { parseDuration } from '../util/index.js'
@@ -89,6 +90,21 @@ export function taskTimeoutMs(step: ExecConfig): number | undefined {
   return step.timeout === undefined ? undefined : parseDuration(step.timeout)!
 }
 
+/** Persistent task `node` as a `servers` executor starts it: no forwarded args, which a dependency never gets. */
+export function serverSpec(node: TaskNode, workspaceRoot: string): ServerSpec {
+  const step = node.config.exec!
+  const timeoutMs = taskTimeoutMs(step)
+  const readyWhen = step.persistent?.readyWhen
+  return {
+    taskId: node.id,
+    command: step.command,
+    cwd: node.projectDir,
+    env: taskEnv(node, step, workspaceRoot),
+    ...(readyWhen === undefined ? {} : { readyWhen }),
+    ...(timeoutMs === undefined ? {} : { timeoutMs }),
+  }
+}
+
 export function isAborted(signal: AbortSignal | undefined): boolean {
   return signal?.aborted === true
 }

package/src/orchestrator/telemetry-host.ts

@@ -18,6 +18,7 @@ import type {
   RunSummaryRecord,
   TelemetryContext,
   TelemetrySink,
+  TreeLoad,
 } from './telemetry.js'
 import { settleWithin, teardownTimeoutMs } from '../util/index.js'
 import { createTelemetrySource } from './telemetry.js'
@@ -32,7 +33,7 @@ export interface TelemetryHandle {
   /** Remove the bus subscription. Idempotent. */
   dispose(): void
   /** Sample a running task's process tree; see `TelemetrySource.track`. */
-  readonly track?: (taskId: string, pid: number) => () => void
+  readonly track?: (taskId: string, pid: number) => () => TreeLoad | undefined
 }
 
 /** Reject anything that is not sink-shaped, naming what arrived. */