@vzn/vx 0.0.626 → 0.0.628

package/package.json

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

package/src/cache/key-fold.ts

@@ -103,7 +103,9 @@ import type { CacheKeyInput } from './layer.js'
 // bytes on disk, the filter since removed, holds the CRLF build (A-60).
 // v39: an entry saved while a gitlink without `.git` held files the key
 // never listed sits under the key of that directory empty (A-61).
-export const CACHE_VERSION = 'vx-cache-v41'
+// v42: the stored output is both streams in order (orchestrator/output-log.ts);
+// a v41 entry holds stdout alone and replays no stderr.
+export const CACHE_VERSION = 'vx-cache-v42'
 
 /**
  * The digest a key folds for an input gone between its enumeration and its

package/src/cache/layer.ts

@@ -147,7 +147,10 @@ export interface CacheEntry {
    * per hit (0.12 ms each across a warm 1000-project run before this).
    */
   outputDirRows?: OutputDirRow[]
-  /** Captured stdout, always present (may be empty). stderr is not cached. */
+  /**
+   * The task's output log, always present (may be empty): both streams in
+   * the order the run printed them (`orchestrator/output-log.ts`).
+   */
   stdout: string
   storedAt: string
   /**

package/src/exec/index.ts

@@ -19,6 +19,8 @@ export {
   type CaptureConfig,
   execWord,
   maskCaptured,
+  BoundedCapture,
+  type CapturedChunk,
 } from './runner.js'
 export {
   initSandbox,

package/src/exec/runner.ts

@@ -1125,56 +1125,73 @@ const DROPPED_LINE = /^\n\[vx\] [\d.]+ MiB of output not kept — /
 
 const isHighSurrogate = (code: number): boolean => code >= 0xd800 && code <= 0xdbff
 
+/** One piece of a task's output and the stream it came on. */
+export interface CapturedChunk {
+  text: string
+  /** True when the task wrote it to stderr. */
+  err: boolean
+}
+
 /**
  * A head-and-tail accumulator: the head fills once, the tail is a ring
  * of chunks trimmed from the front, so memory is bounded by the two
- * limits plus one chunk whatever the task prints.
+ * limits plus one chunk whatever the task prints. Each chunk keeps its
+ * stream, so one capture can hold both in the order they arrived.
  */
-class BoundedCapture {
-  private head = ''
-  private readonly tail: string[] = []
+export class BoundedCapture {
+  private readonly head: CapturedChunk[] = []
+  private headLen = 0
+  private readonly tail: CapturedChunk[] = []
   private tailLen = 0
   private dropped = 0
 
-  push(chunk: string): void {
+  push(text: string, err = false): void {
     // Once the tail has begun the head is closed, even a unit short of its
     // bound (the surrogate case below): a later short chunk fit there and
     // was retained ahead of the chunk before it.
-    if (this.tailLen === 0 && this.head.length < CAPTURE_HEAD_CHARS) {
-      let room = CAPTURE_HEAD_CHARS - this.head.length
-      if (chunk.length <= room) {
-        this.head += chunk
+    if (this.tailLen === 0 && this.headLen < CAPTURE_HEAD_CHARS) {
+      let room = CAPTURE_HEAD_CHARS - this.headLen
+      if (text.length <= room) {
+        this.head.push({ text, err })
+        this.headLen += text.length
         return
       }
       // Never between a surrogate pair's halves: the bounds count UTF-16
       // units, and a halved character read U+FFFD in the replay.
-      if (isHighSurrogate(chunk.charCodeAt(room - 1))) room--
-      this.head += chunk.slice(0, room)
-      chunk = chunk.slice(room)
+      if (isHighSurrogate(text.charCodeAt(room - 1))) room--
+      this.head.push({ text: text.slice(0, room), err })
+      this.headLen += room
+      text = text.slice(room)
     }
-    this.tail.push(chunk)
-    this.tailLen += chunk.length
+    this.tail.push({ text, err })
+    this.tailLen += text.length
     while (this.tailLen > CAPTURE_TAIL_CHARS) {
       const first = this.tail[0]!
       const excess = this.tailLen - CAPTURE_TAIL_CHARS
-      if (first.length <= excess) {
+      if (first.text.length <= excess) {
         this.tail.shift()
-        this.tailLen -= first.length
-        this.dropped += first.length
+        this.tailLen -= first.text.length
+        this.dropped += first.text.length
       } else {
-        const cut = isHighSurrogate(first.charCodeAt(excess - 1)) ? excess + 1 : excess
-        this.tail[0] = first.slice(cut)
+        const cut = isHighSurrogate(first.text.charCodeAt(excess - 1)) ? excess + 1 : excess
+        this.tail[0] = { text: first.text.slice(cut), err: first.err }
         this.tailLen -= cut
         this.dropped += cut
       }
     }
   }
 
-  text(): string {
-    const tail = this.tail.join('')
+  /** The kept chunks in arrival order, the dropped middle named on stdout. */
+  chunks(): CapturedChunk[] {
     return this.dropped === 0
-      ? this.head + tail
-      : this.head + droppedOutputLine(this.dropped) + tail
+      ? [...this.head, ...this.tail]
+      : [...this.head, { text: droppedOutputLine(this.dropped), err: false }, ...this.tail]
+  }
+
+  text(): string {
+    return this.chunks()
+      .map((c) => c.text)
+      .join('')
   }
 }
 

package/src/orchestrator/execute-task.ts

@@ -39,7 +39,9 @@ import {
   PersistentReadyError,
   sandboxReads,
   maskCaptured,
+  BoundedCapture,
 } from '../exec/index.js'
+import { encodeOutputLog } from './output-log.js'
 import { isGroupTask, RestoreDemoted, type TaskNode, type TaskOutcome } from '../graph/index.js'
 import {
   killGraceMs,
@@ -644,17 +646,14 @@ async function executeCachedTask(args: ExecuteArgs): Promise<TaskOutcome> {
   let unkeyed = unkeyedUpstream !== undefined
   const willSave = willWrite && args.taintedUpstream !== true && !unkeyed
 
-  // Retain only what is read back. `cache.save` below is the single consumer
-  // of `result.stdout`, and it runs only when this task will WRITE an entry;
-  // `result.stderr` has no consumer at all (a failing task's stderr reaches
-  // the user through the live `onStderr` callback, and the cache has never
-  // stored stderr — see the v17 artifact format). Both streams are still
-  // drained and still stream chunk-by-chunk to the logger; only the retained
-  // copy is dropped, which for a chatty task is its full byte size in heap.
+  // The executor retains nothing: the entry's output is the attempt's
+  // `output` log, both streams in the order they reached the logger, kept
+  // only when this task will WRITE an entry. Both streams are still drained
+  // and still stream chunk-by-chunk to the logger.
   // Deferral is decided at plan time and only ever set for a remote-placed,
   // eligibility-cleared task; it suppresses this machine's clean AND save.
   const deferralRequested = args.download === 'deferred'
-  const capture: CaptureConfig = { stdout: willSave, stderr: false }
+  const capture: CaptureConfig = { stdout: false, stderr: false }
 
   const outputs = cacheCfg?.outputs.files ?? []
   const wsOutputs = cacheCfg?.outputs.workspaceFiles ?? []
@@ -1199,6 +1198,9 @@ async function executeCachedTask(args: ExecuteArgs): Promise<TaskOutcome> {
   // and what the cache keeps of it (L-11); null when there are none.
   const secrets = secretMask([process.env, env, step.env?.define], step.env?.secret)
   let flushMasked = (): void => {}
+  // The attempt's output as the logger got it (masked), for the entry.
+  let output: BoundedCapture | undefined
+  const storedOutput = (): string => encodeOutputLog(output?.chunks() ?? [])
   const failedAttempts: { endedAt: number; exitCode: number; timedOut?: true }[] = []
   // The sampling of the attempt's process tree, stopped once it settles.
   let untrack: (() => void) | undefined
@@ -1288,8 +1290,18 @@ async function executeCachedTask(args: ExecuteArgs): Promise<TaskOutcome> {
   }
 
   async function buildRequest(local: boolean): Promise<ExecuteRequest> {
-    const out = secrets && maskedEmitter(secrets, (t) => log.taskStdout(node, t))
-    const err = secrets && maskedEmitter(secrets, (t) => log.taskStderr(node, t))
+    const kept = willSave ? new BoundedCapture() : undefined
+    output = kept
+    const toOut = (t: string): void => {
+      kept?.push(t)
+      log.taskStdout(node, t)
+    }
+    const toErr = (t: string): void => {
+      kept?.push(t, true)
+      log.taskStderr(node, t)
+    }
+    const out = secrets && maskedEmitter(secrets, toOut)
+    const err = secrets && maskedEmitter(secrets, toErr)
     flushMasked = () => {
       out?.end()
       err?.end()
@@ -1303,8 +1315,8 @@ async function executeCachedTask(args: ExecuteArgs): Promise<TaskOutcome> {
       env,
       envDefine: step.env?.define ?? {},
       capture,
-      onStdout: out ? (chunk) => out.push(chunk) : (chunk) => log.taskStdout(node, chunk),
-      onStderr: err ? (chunk) => err.push(chunk) : (chunk) => log.taskStderr(node, chunk),
+      onStdout: out ? (chunk) => out.push(chunk) : toOut,
+      onStderr: err ? (chunk) => err.push(chunk) : toErr,
       ...(args.liveChildren !== undefined ? { liveChildren: args.liveChildren } : {}),
       ...(args.track !== undefined
         ? {
@@ -1364,7 +1376,7 @@ async function executeCachedTask(args: ExecuteArgs): Promise<TaskOutcome> {
           taskId: node.id,
           command: storedCommand,
           durationMs: result.durationMs,
-          stdout: result.stdout,
+          stdout: storedOutput(),
           ...(result.cpuMs !== undefined ? { cpuMs: result.cpuMs } : {}),
           ...(result.peakRssBytes !== undefined ? { peakRssBytes: result.peakRssBytes } : {}),
         },
@@ -1390,7 +1402,7 @@ async function executeCachedTask(args: ExecuteArgs): Promise<TaskOutcome> {
       captured,
       command: storedCommand,
       durationMs: result.durationMs,
-      stdout: result.stdout,
+      stdout: storedOutput(),
       ...(result.cpuMs !== undefined ? { cpuMs: result.cpuMs } : {}),
       ...(result.peakRssBytes !== undefined ? { peakRssBytes: result.peakRssBytes } : {}),
       outputDirSnapshots: args.outputDirSnapshots,

package/src/orchestrator/hit-restore.ts

@@ -30,6 +30,7 @@ import {
 } from '../util/index.js'
 import type { ExecuteArgs } from './execute-task.js'
 import { entryHolds } from './miss-save.js'
+import { decodeOutputLog } from './output-log.js'
 
 export interface RestoreHitArgs {
   args: ExecuteArgs
@@ -45,7 +46,7 @@ export interface RestoreHitArgs {
 /**
  * Materialize a confirmed cache hit: decide skip-restore, clean +
  * restore declared outputs, mark the exact changed paths so downstream
- * same-project tasks needn't re-spawn git, replay stored stdout, and
+ * same-project tasks needn't re-spawn git, replay stored output, and
  * build the cache-hit `TaskOutcome`. Extracted from `executeCachedTask`
  * so the local short-circuit can restore a stable-key hit ahead of the
  * schedule using the IDENTICAL logic — there is one restore path, not
@@ -97,7 +98,7 @@ export async function restoreHit(restore: RestoreHitArgs): Promise<TaskOutcome>
   // path pays one SELECT here. Either beats reading the manifest from
   // the tar (decompress + parse) at the same point.
   // A task with no declared outputs has nothing to clean or restore: its
-  // stdout replays from the row (`hit.stdout`), and its artifact holds
+  // output replays from the row (`hit.stdout`), and its artifact holds
   // only logs. Extracting it anyway cost an `exists` + a tar read per hit
   // — 1.7 ms each on a four-task real repo whose `link` and `element`
   // tasks declare `outputs: []` (2026-09-10, VX_TIMING).
@@ -296,7 +297,12 @@ export async function restoreHit(restore: RestoreHitArgs): Promise<TaskOutcome>
       [process.env, node.config.exec?.env?.define],
       node.config.exec?.env?.secret,
     )
-    log.taskStdout(node, secrets === null ? hit.stdout : secrets.mask(hit.stdout))
+    // The stored log holds both streams in the order the run printed them.
+    for (const c of decodeOutputLog(hit.stdout)) {
+      const text = secrets === null ? c.text : secrets.mask(c.text)
+      if (c.err) log.taskStderr(node, text)
+      else log.taskStdout(node, text)
+    }
   }
   const status =
     hit.exitCode !== 0 ? 'failed' : hit.source === 'remote' ? 'cache-hit-remote' : 'cache-hit'

package/src/orchestrator/output-log.ts

@@ -0,0 +1,53 @@
+// A task's output as a cache entry stores it: both streams in the order
+// vx read them, so a hit replays what the run showed. One string, so every
+// cache layer carries it as it carried stdout: the text as written, with
+// RS (U+001E) + `e` / `o` where the stream switches to stderr / stdout, and
+// a literal RS doubled. Output that never touched stderr is its own text.
+
+import type { CapturedChunk } from '../exec/index.js'
+
+const RS = '\x1e'
+
+/** `chunks` as one stored string; it starts on stdout. */
+export function encodeOutputLog(chunks: readonly CapturedChunk[]): string {
+  let out = ''
+  let err = false
+  for (const c of chunks) {
+    if (c.text.length === 0) continue
+    if (c.err !== err) {
+      out += RS + (c.err ? 'e' : 'o')
+      err = c.err
+    }
+    out += c.text.replaceAll(RS, RS + RS)
+  }
+  return out
+}
+
+/** The chunks `encodeOutputLog` wrote, adjacent same-stream text joined. */
+export function decodeOutputLog(log: string): CapturedChunk[] {
+  if (!log.includes(RS)) return log.length === 0 ? [] : [{ text: log, err: false }]
+  const chunks: CapturedChunk[] = []
+  let err = false
+  let text = ''
+  const flush = (): void => {
+    if (text.length > 0) chunks.push({ text, err })
+    text = ''
+  }
+  let from = 0
+  for (let at = log.indexOf(RS); at !== -1; at = log.indexOf(RS, from)) {
+    text += log.slice(from, at)
+    const next = log[at + 1]
+    from = at + 2
+    if (next === 'e' || next === 'o') {
+      flush()
+      err = next === 'e'
+      continue
+    }
+    text += RS
+    // A lone RS (at the end, or before any other character) is the text's own.
+    if (next !== RS) from = at + 1
+  }
+  text += log.slice(from)
+  flush()
+  return chunks
+}