@vzn/vx 0.0.651 → 0.0.652

package/README.md

@@ -47,9 +47,8 @@ export default defineProject({
       exec: { command: 'tsc -b' },
       dependsOn: ['^build'], // dependencies build first
       inputs: { files: ['src/**', 'tsconfig.json'] },
-      cache: {
-        outputs: { files: ['dist/**'] },
-      },
+      outputs: { files: ['dist/**'] },
+      cache: true,
     },
   },
 })

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vzn/vx",
-  "version": "0.0.651",
+  "version": "0.0.652",
   "description": "Task orchestration you own: correct, sandboxed, extensible, with a content-addressed build cache.",
   "type": "module",
   "exports": {
@@ -21,10 +21,10 @@
     "node": ">=18"
   },
   "optionalDependencies": {
-    "@vzn/vx-linux-x64": "0.0.651",
-    "@vzn/vx-linux-arm64": "0.0.651",
-    "@vzn/vx-darwin-x64": "0.0.651",
-    "@vzn/vx-darwin-arm64": "0.0.651"
+    "@vzn/vx-linux-x64": "0.0.652",
+    "@vzn/vx-linux-arm64": "0.0.652",
+    "@vzn/vx-darwin-x64": "0.0.652",
+    "@vzn/vx-darwin-arm64": "0.0.652"
   },
   "dependencies": {
     "@anthropic-ai/sandbox-runtime": "^0.0.76"

package/schemas/show.json

@@ -109,25 +109,8 @@
             "env": { "$ref": "#/$defs/stringList" },
             "tasks": { "$ref": "#/$defs/stringList" },
             "runtime": { "$ref": "#/$defs/stringList" },
-            "workspaceRuntime": { "$ref": "#/$defs/stringList" }
-          }
-        },
-        "cache": {
-          "type": "object",
-          "additionalProperties": false,
-          "required": ["outputs"],
-          "properties": {
-            "outputs": {
-              "type": "object",
-              "additionalProperties": false,
-              "required": ["files"],
-              "properties": {
-                "files": { "$ref": "#/$defs/stringList" },
-                "workspaceFiles": { "$ref": "#/$defs/stringList" },
-                "clean": { "type": "boolean" }
-              }
-            },
-            "inputStability": {
+            "workspaceRuntime": { "$ref": "#/$defs/stringList" },
+            "stability": {
               "type": "object",
               "additionalProperties": false,
               "properties": {
@@ -136,7 +119,18 @@
               }
             }
           }
-        }
+        },
+        "outputs": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["files"],
+          "properties": {
+            "files": { "$ref": "#/$defs/stringList" },
+            "workspaceFiles": { "$ref": "#/$defs/stringList" },
+            "clean": { "type": "boolean" }
+          }
+        },
+        "cache": { "type": "boolean" }
       }
     }
   }

package/src/bin.ts

@@ -79,6 +79,10 @@ async function main(): Promise<void> {
         err.parts,
       )
       ui.data('err', maskedLine(ui.render([block], ui.colorsOf('err'))))
+    } else if (cwdGone(err)) {
+      // Removed under the shell (a checkout of another branch, `rm -rf` in
+      // another): every verb starts from the cwd.
+      say('vx: the current directory no longer exists — cd into the workspace again and re-run\n')
     } else if (isOutOfFds(err)) {
       say(`vx: ${err.message} — ${OUT_OF_FDS_HINT}\n`)
     } else if (isFsRefusal(err)) {
@@ -159,6 +163,14 @@ process.on('beforeExit', () => {
   process.exitCode = 1
 })
 
+/** `process.cwd()`'s refusal of a directory removed under the process. */
+function cwdGone(err: unknown): boolean {
+  return (
+    (err as NodeJS.ErrnoException | null)?.code === 'ENOENT' &&
+    /\buv_cwd\b/.test((err as Error).message)
+  )
+}
+
 // A reader that leaves is not the run's failure. `vx run build | head -1`
 // closes the pipe after one line; every later write gets EPIPE, which Bun
 // raises as an `error` event on the stream, and an `error` nobody listens

package/src/cache/archive.ts

@@ -350,7 +350,7 @@ export async function planArtifact(args: PackArgs): Promise<ArtifactPlan> {
       }
       if (!st.isFile()) {
         throw new UserError(
-          `${shown} is not a regular file: vx stores regular files and symlinks only — emit a file there, or narrow cache.outputs.files to the files the task produces, or take it back with a '!' entry`,
+          `${shown} is not a regular file: vx stores regular files and symlinks only — emit a file there, or narrow outputs.files to the files the task produces, or take it back with a '!' entry`,
         )
       }
       const mode = st.mode & 0o777

package/src/cache/cache.ts

@@ -51,7 +51,13 @@ import {
 } from 'node:fs'
 import { chmod, lstat, mkdir, readdir, rm, stat, unlink, utimes, writeFile } from 'node:fs/promises'
 import path from 'node:path'
-import { createArtifactTables, createTables, inHashes, lazyStatement } from './schema.js'
+import {
+  createArtifactTables,
+  createTables,
+  inHashes,
+  lazyStatement,
+  SQLITE_FCNTL_PERSIST_WAL,
+} from './schema.js'
 import {
   UserError,
   DOT_VX_GITIGNORE,
@@ -275,7 +281,7 @@ function cantOpenIndex(dbFile: string, err: unknown): UserError | undefined {
 //        the memo simply stops answering wrongly, so an affected task's
 //        key moves from a WRONG value to the right one: it misses once,
 //        re-runs, re-caches. Self-healing, never a wrong hit.
-//   v25: runs.cached — whether the task declared a `cache` block. An
+//   v25: runs.cached — whether the task declared `cache: true`. An
 //        uncached task's row looked like any executed miss, so `vx why`
 //        headlined "cache key changed (inputs differ)" for a task that
 //        runs every time by design, and `vx last` could not mark it the
@@ -2851,7 +2857,7 @@ export class Cache implements CacheLayer {
     if (plan.size > this.artifactCeiling) {
       throw new Error(
         `${args.entry.taskId} is not cached: its outputs pack to ${formatBytes(plan.size)}, past the ` +
-          `${formatBytes(this.artifactCeiling)} artifact ceiling a restore enforces — narrow cache.outputs.files`,
+          `${formatBytes(this.artifactCeiling)} artifact ceiling a restore enforces — narrow outputs.files`,
       )
     }
     return plan
@@ -3727,8 +3733,16 @@ export class Cache implements CacheLayer {
   }
 }
 
-/** SQLite's file-control opcode (sqlite3.h). */
-export const SQLITE_FCNTL_PERSIST_WAL = 10
+/**
+ * The files a second connection writes a run's hits through
+ * (history-stream.ts); undefined when the store keeps no history on disk.
+ * A function, as `indexDb` is: no plugin writes the history.
+ */
+export function historyFiles(cache: Cache): { index: string; store?: string } | undefined {
+  if (cache['empty'] || cache['writeBlocked'] !== null || cache['inspecting']) return undefined
+  if (cache.storeDir === undefined) return { index: cache['dbFile'] }
+  return { index: cache['dbFile'], store: path.join(cache.storeDir, 'store.db') }
+}
 
 /**
  * The cache's `bun:sqlite` handle, for core's own readers (`vx last`, `vx

package/src/cache/history-stream.ts

@@ -0,0 +1,134 @@
+// A run's hits written to the history while the graph still runs, on a
+// thread of their own (history-writer.ts). A warm run's rows were the
+// main thread's last ~65 ms at 8,002 hits, after the graph; here they land
+// while it runs. What does not land (no thread, a refused batch) is
+// handed back and goes in the run's own bundle, as before.
+
+import type { RunRecord } from './layer.js'
+import type { HistoryWriterIn, HistoryWriterOut } from './history-writer.js'
+
+/**
+ * Rows per batch, and the hits a run has before it starts a thread: a
+ * run with fewer writes them in its bundle, as cheap as a thread's start.
+ */
+const BATCH = 512
+
+/** A record of `T` whose row the stream holds. */
+export interface Streamed<T> {
+  item: T
+  record: RunRecord
+}
+
+export class HistoryStream<T> {
+  private worker: Worker | undefined
+  private buffer: Streamed<T>[] = []
+  private readonly sent = new Map<number, Streamed<T>[]>()
+  private readonly landed: Streamed<T>[] = []
+  private seq = 0
+  /** A batch was refused or the thread died: nothing more is sent. */
+  private dead = false
+  /** The thread died: no batch answers any more. */
+  private gone = false
+  private readonly refused = new Set<number>()
+  private settle: (() => void) | undefined
+  private ended: (() => void) | undefined
+
+  constructor(private readonly files: { index: string; store?: string }) {}
+
+  add(item: T, record: RunRecord): void {
+    this.buffer.push({ item, record })
+    if (this.buffer.length >= BATCH && !this.dead) this.send()
+  }
+
+  /**
+   * Waits for every batch sent, closes the thread, and returns what landed
+   * and what did not (the run's bundle writes those).
+   */
+  async finish(): Promise<{ landed: Streamed<T>[]; unlanded: Streamed<T>[] }> {
+    const w = this.worker
+    if (w !== undefined && !this.gone) {
+      // Unreferenced, its answers alone left the loop with nothing to
+      // wait on: the run ended "awaited can never settle".
+      w.ref()
+      await new Promise<void>((resolve) => {
+        this.settle = resolve
+        this.settled()
+      })
+      if (!this.gone) {
+        await new Promise<void>((resolve) => {
+          this.ended = resolve
+          w.postMessage({ end: true } satisfies HistoryWriterIn)
+        })
+      }
+    }
+    w?.terminate()
+    const unlanded = [...this.sent.values()].flat().concat(this.buffer)
+    this.sent.clear()
+    this.buffer = []
+    return { landed: this.landed, unlanded }
+  }
+
+  private send(): void {
+    const w = (this.worker ??= this.start())
+    const batch = this.buffer
+    this.buffer = []
+    const seq = this.seq++
+    this.sent.set(seq, batch)
+    // A record's spans are bigint, which JSON cannot carry: as numbers, exact
+    // below 2^53 ns (104 days into a run). A replacer function cost 20 ms
+    // of 8,002 rows, the copies 4.
+    const hits = JSON.stringify(
+      batch.map(({ record: r }) => ({
+        ...r,
+        wallclockStartNs: r.wallclockStartNs === undefined ? undefined : Number(r.wallclockStartNs),
+        wallclockEndNs: r.wallclockEndNs === undefined ? undefined : Number(r.wallclockEndNs),
+      })),
+    )
+    w.postMessage({ seq, hits } satisfies HistoryWriterIn)
+  }
+
+  private start(): Worker {
+    const w = new Worker(new URL('./history-writer.ts', import.meta.url).href)
+    // A run that throws before `finish` must still exit; a batch cut off
+    // mid-write rolls back whole.
+    w.unref()
+    w.onmessage = (e: MessageEvent<HistoryWriterOut>) => {
+      const m = e.data
+      if ('ended' in m) {
+        this.ended?.()
+        return
+      }
+      const batch = this.sent.get(m.seq)
+      if (batch === undefined) return
+      if (m.error === undefined) {
+        this.sent.delete(m.seq)
+        for (const b of batch) this.landed.push(b)
+      } else {
+        // Kept in `sent`, so the bundle writes it; no later batch is sent.
+        this.refused.add(m.seq)
+        this.dead = true
+      }
+      this.settled()
+    }
+    // A thread that cannot start or dies: what it did not answer for is
+    // the bundle's.
+    w.onerror = (e) => {
+      e.preventDefault()
+      this.dead = true
+      this.gone = true
+      this.settled()
+      this.ended?.()
+    }
+    w.postMessage({ open: this.files } satisfies HistoryWriterIn)
+    return w
+  }
+
+  /** Resolves `finish`'s wait once every batch sent has answered, or the thread is gone. */
+  private settled(): void {
+    if (this.settle === undefined) return
+    if (!this.gone && [...this.sent.keys()].some((seq) => !this.refused.has(seq))) return
+    const s = this.settle
+    this.settle = undefined
+    s()
+  }
+}

package/src/cache/history-writer.ts

@@ -0,0 +1,76 @@
+// The thread that writes a run's hits to the history while the run goes on
+// (history-stream.ts). A connection of its own on the run's cache files,
+// opened as `Cache` opens them; each batch is one IMMEDIATE transaction,
+// answered by its sequence number so the run knows which landed.
+// A separate entry point: `bun build --compile` embeds it beside bin.ts.
+
+import { Database } from 'bun:sqlite'
+import type { RunRecord } from './layer.js'
+import { RunHistory } from './run-history.js'
+import { SQLITE_FCNTL_PERSIST_WAL } from './schema.js'
+
+export type HistoryWriterIn =
+  | { open: { index: string; store?: string } }
+  | { seq: number; hits: string }
+  | { end: true }
+
+export type HistoryWriterOut = { seq: number; error?: string } | { ended: true }
+
+declare const self: Worker
+
+let db: Database | undefined
+let history: RunHistory | undefined
+let refused: string | undefined
+
+function open(files: { index: string; store?: string }): void {
+  // The timeout first, as `Cache` sets it: every later pragma waits under it.
+  db = new Database(files.index)
+  db.exec('PRAGMA busy_timeout = 5000')
+  db.fileControl(SQLITE_FCNTL_PERSIST_WAL, 1)
+  db.exec('PRAGMA journal_size_limit = 67108864')
+  db.exec('PRAGMA synchronous = NORMAL')
+  if (files.store !== undefined) {
+    db.prepare('ATTACH DATABASE ? AS store').run(files.store)
+    db.fileControl('store', SQLITE_FCNTL_PERSIST_WAL, 1)
+    db.exec('PRAGMA store.journal_size_limit = 67108864')
+    db.exec('PRAGMA store.synchronous = NORMAL')
+  }
+  // A streamed hit carries no forward args (history-stream.ts): nothing digests.
+  history = new RunHistory(db, () => {
+    throw new Error('a streamed hit has no value to digest')
+  })
+}
+
+self.onmessage = (e: MessageEvent<HistoryWriterIn>) => {
+  const m = e.data
+  if ('open' in m) {
+    try {
+      open(m.open)
+    } catch (err) {
+      refused = err instanceof Error ? err.message : String(err)
+    }
+    return
+  }
+  if ('end' in m) {
+    try {
+      db?.close()
+    } catch {
+      // The rows are in; a close that fails leaves the WAL to the next opener.
+    }
+    postMessage({ ended: true } satisfies HistoryWriterOut)
+    return
+  }
+  if (history === undefined) {
+    postMessage({ seq: m.seq, error: refused ?? 'not open' } satisfies HistoryWriterOut)
+    return
+  }
+  try {
+    history.recordHits(JSON.parse(m.hits) as RunRecord[])
+    postMessage({ seq: m.seq } satisfies HistoryWriterOut)
+  } catch (err) {
+    postMessage({
+      seq: m.seq,
+      error: err instanceof Error ? err.message : String(err),
+    } satisfies HistoryWriterOut)
+  }
+}

package/src/cache/index.ts

@@ -18,6 +18,7 @@ export {
   type CachePolicy,
   cachesNothing,
   EXECUTED_RUNS_SQL,
+  historyFiles,
   indexDb,
   formatCachePolicy,
   FULL_CACHE_POLICY,
@@ -104,6 +105,7 @@ export {
 } from './plugin-cache.js'
 export { packRunOutputs, putRunEntry, runEntryName, writesRunStore } from './run-store.js'
 export { branchSource } from './run-history.js'
+export { HistoryStream } from './history-stream.js'
 export {
   type KeptFailure,
   keepRunNotes,

package/src/cache/inputs.ts

@@ -17,7 +17,15 @@
 // be a git work tree; non-git environments are not supported.
 
 import path from 'node:path'
-import { lstatSync, readdirSync, realpathSync, rmdirSync, rmSync, statSync } from 'node:fs'
+import {
+  type Dirent,
+  lstatSync,
+  readdirSync,
+  realpathSync,
+  rmdirSync,
+  rmSync,
+  statSync,
+} from 'node:fs'
 import { rm, rmdir } from 'node:fs/promises'
 import type { InputsConfig, TaskConfig } from '../config.js'
 import {
@@ -837,15 +845,23 @@ export async function resolveOutputTree(args: {
   projectDir: string
   outputs: readonly string[]
   nestedProjectDirs: string[]
-}): Promise<{ files: string[]; emptyDirs: string[] }> {
+  /** Also list the FIFOs, sockets and devices the globs name (a save refuses them). */
+  special?: boolean
+}): Promise<{ files: string[]; emptyDirs: string[]; special: string[] }> {
   const emptyDirs = new Set<string>()
-  const { files } = await scanOutputs(args, emptyDirs)
-  return { files, emptyDirs: containedIn(args.projectDir, [...emptyDirs]).sort() }
+  const special = args.special === true ? new Set<string>() : undefined
+  const { files } = await scanOutputs(args, emptyDirs, special)
+  return {
+    files,
+    emptyDirs: containedIn(args.projectDir, [...emptyDirs]).sort(),
+    special: special === undefined ? [] : containedIn(args.projectDir, [...special]).sort(),
+  }
 }
 
 async function scanOutputs(
   args: { projectDir: string; outputs: readonly string[]; nestedProjectDirs: string[] },
   emptyDirs?: Set<string>,
+  special?: Set<string>,
 ): Promise<{ files: string[] }> {
   const { positive, negative } = splitNegations(args.outputs)
   if (positive.length === 0) return { files: [] }
@@ -859,6 +875,7 @@ async function scanOutputs(
       args.projectDir,
       inNestedProject(args.projectDir, args.nestedProjectDirs),
       emptyDirs,
+      special,
     )),
   ]
   // Containment, enforced HERE and not only at the loader. `cleanOutputs`
@@ -1258,7 +1275,7 @@ export async function stampOutputs(args: {
   return stampFiles(await resolveOutputs(args))
 }
 
-/** `stampOutputs` for root-anchored `cache.outputs.workspaceFiles` (A-43). */
+/** `stampOutputs` for root-anchored `outputs.workspaceFiles` (A-43). */
 export async function stampWorkspaceOutputs(args: {
   workspaceRoot: string
   outputs: readonly string[]
@@ -1298,7 +1315,7 @@ export async function ownOutputsSince(
   return changedSince(await resolveOutputs(args), before)
 }
 
-/** `ownOutputsSince` for root-anchored `cache.outputs.workspaceFiles` (A-43). */
+/** `ownOutputsSince` for root-anchored `outputs.workspaceFiles` (A-43). */
 export async function ownWorkspaceOutputsSince(
   args: { workspaceRoot: string; outputs: readonly string[] },
   before: ReadonlyMap<string, OutputStamp>,
@@ -1527,6 +1544,7 @@ export async function resolveWorkspaceOutputs(
     outputs: readonly string[]
   },
   emptyDirs?: Set<string>,
+  special?: Set<string>,
 ): Promise<string[]> {
   const { positive, negative } = splitNegations(args.outputs)
   if (positive.length === 0) return []
@@ -1534,7 +1552,7 @@ export async function resolveWorkspaceOutputs(
   const trees = asTrees(positive)
   refuseDirLinkedOut(args.workspaceRoot, trees, 'workspace')
   const scanned = [
-    ...(await scanUnion(trees, excludeGlobs, args.workspaceRoot, undefined, emptyDirs)),
+    ...(await scanUnion(trees, excludeGlobs, args.workspaceRoot, undefined, emptyDirs, special)),
   ]
   // Same containment as the project twin, anchored one level out. These globs
   // deliberately ignore PROJECT boundaries — that is the escape hatch — but
@@ -1547,10 +1565,17 @@ export async function resolveWorkspaceOutputs(
 export async function resolveWorkspaceOutputTree(args: {
   workspaceRoot: string
   outputs: readonly string[]
-}): Promise<{ files: string[]; emptyDirs: string[] }> {
+  /** As `resolveOutputTree`'s. */
+  special?: boolean
+}): Promise<{ files: string[]; emptyDirs: string[]; special: string[] }> {
   const emptyDirs = new Set<string>()
-  const files = await resolveWorkspaceOutputs(args, emptyDirs)
-  return { files, emptyDirs: containedIn(args.workspaceRoot, [...emptyDirs]).sort() }
+  const special = args.special === true ? new Set<string>() : undefined
+  const files = await resolveWorkspaceOutputs(args, emptyDirs, special)
+  return {
+    files,
+    emptyDirs: containedIn(args.workspaceRoot, [...emptyDirs]).sort(),
+    special: special === undefined ? [] : containedIn(args.workspaceRoot, [...special]).sort(),
+  }
 }
 
 /**
@@ -1965,7 +1990,7 @@ export function declaresInput(
     // A changed path under the task's own outputs is a committed file
     // (`git diff` lists only what git tracks) or a stray `git status`
     // lists: either way it may be an input, so it counts.
-    const plan = filesPlan(inputs.files, task.cache?.outputs.files ?? [])
+    const plan = filesPlan(inputs.files, task.outputs?.files ?? [])
     if (plan !== null && (inPlan(plan, projectRel) || ownOnly(plan, projectRel))) return true
     if (plan !== null && dirLink && plan.mayHold(projectRel) && !plan.isExcluded(projectRel)) {
       return true
@@ -1995,8 +2020,7 @@ export function workspaceFilesReachInto(task: TaskConfig, dir: string): boolean
  */
 export function namedOutright(task: TaskConfig): { files: string[]; workspaceFiles: string[] } {
   const inputs = task.inputs
-  const plan =
-    inputs === undefined ? null : filesPlan(inputs.files, task.cache?.outputs.files ?? [])
+  const plan = inputs === undefined ? null : filesPlan(inputs.files, task.outputs?.files ?? [])
   const ws = inputs?.workspaceFiles ?? []
   return {
     files: plan === null ? [] : outright(plan),
@@ -2242,7 +2266,7 @@ function listingFor(
 function refuseUndecodableOutput(abs: string): void {
   if (!undecodableOnDisk(abs)) return
   throw new UserError(
-    `cache.outputs matched ${JSON.stringify(abs)}: the name is not valid UTF-8 (shown with ` +
+    `outputs matched ${JSON.stringify(abs)}: the name is not valid UTF-8 (shown with ` +
       `\ufffd), and vx cannot save a file by it. Rename it, or keep it out of the outputs.`,
   )
 }
@@ -2456,13 +2480,19 @@ async function scanUnion(
   cwd: string,
   nested: (rel: string) => boolean = () => false,
   emptyDirs?: Set<string>,
+  special?: Set<string>,
 ): Promise<Set<string>> {
   const matches = new Set<string>()
   const links: string[] = []
+  // Directories the walk entered: Bun's scan skips a FIFO, socket or
+  // device outright, so `special` is found by listing them.
+  const walked = special === undefined ? undefined : new Set<string>()
   const take = (rel: string): void => {
     if (nested(rel) || excludeGlobs.some((g) => g.match(rel))) return
     const abs = path.resolve(cwd, rel)
+    walked?.add(path.dirname(abs))
     const st = lstatSync(abs, { throwIfNoEntry: false })
+    if (walked !== undefined && st?.isDirectory() === true) walked.add(abs)
     if (st !== undefined && (st.isFile() || st.isSymbolicLink())) {
       matches.add(abs)
       if (st.isSymbolicLink()) links.push(abs)
@@ -2487,17 +2517,22 @@ async function scanUnion(
   ) {
     const any = anyTaskGlob(patterns)
     for (const rel of WHOLE_TREE.scanSync(opts)) if (any(rel)) take(rel)
+    if (special !== undefined) findSpecial(walked!, cwd, any, excludeGlobs, nested, special)
     return matches
   }
   for (const pattern of patterns) {
     if (absentPrefix(cwd, pattern)) continue
     const from = scanRoot(cwd, pattern)
     if (from === null) continue
+    walked?.add(from === undefined ? cwd : from.dir)
     if (from === undefined) for (const rel of globFor(pattern).scanSync(opts)) take(rel)
     else
       for (const rel of globFor(from.rest).scanSync({ ...opts, cwd: from.dir }))
         take(`${from.prefix}/${rel}`)
   }
+  if (special !== undefined) {
+    findSpecial(walked!, cwd, anyTaskGlob(patterns), excludeGlobs, nested, special)
+  }
   // A literal names the path and its tree (`dist`, `dist/**`), and a tree
   // whose head is a directory link is walked through it: the link and the
   // files under it were one artifact holding `dist` as a file and a
@@ -2513,6 +2548,31 @@ async function scanUnion(
   return matches
 }
 
+/** The FIFOs, sockets and devices in `dirs` that the output globs name. */
+function findSpecial(
+  dirs: ReadonlySet<string>,
+  cwd: string,
+  any: (rel: string) => boolean,
+  excludeGlobs: readonly Bun.Glob[],
+  nested: (rel: string) => boolean,
+  into: Set<string>,
+): void {
+  for (const dir of dirs) {
+    let entries: Dirent[]
+    try {
+      entries = readdirSync(dir, { withFileTypes: true })
+    } catch {
+      continue
+    }
+    for (const e of entries) {
+      if (e.isFile() || e.isDirectory() || e.isSymbolicLink()) continue
+      const abs = path.join(dir, e.name)
+      const rel = path.relative(cwd, abs).split(path.sep).join('/')
+      if (any(rel) && !nested(rel) && !excludeGlobs.some((g) => g.match(rel))) into.add(abs)
+    }
+  }
+}
+
 /** `pattern`'s static directory passes through a symlink under `cwd`. */
 function headLinked(cwd: string, pattern: string): boolean {
   const prefix = staticPrefix(pattern)

package/src/cache/layer.ts

@@ -199,7 +199,7 @@ export interface RunRecord {
   restored?: boolean
   attempts?: number // >1 when the task retried; the direct within-run flaky signal
   /**
-   * Whether the task declared a `cache` block. An uncached task executes
+   * Whether the task declared `cache: true`. An uncached task executes
    * on every run and its key exists only for dependents to fold, so a
    * reader (`vx why`, `vx last`) must not present its re-run as a cache
    * decision. Absent on rows written before the column existed.
@@ -358,7 +358,7 @@ export interface PruneResult {
 
 /**
  * Artifact + `output_files` namespace prefix for workspace-root-
- * anchored outputs (`cache.outputs.workspaceFiles`). Project outputs
+ * anchored outputs (`outputs.workspaceFiles`). Project outputs
  * keep their bare project-relative `path` rows; workspace rows store
  * the full `workspace-outputs/<rel-to-root>` tar entry name as the
  * discriminator — least-invasive row format, no schema change. A
@@ -467,7 +467,7 @@ export interface CacheGetContext {
   taskId: string
   command: string
   /**
-   * The task's declared `cache.outputs`. A remote artifact is ingested
+   * The task's declared `outputs`. A remote artifact is ingested
    * only when every file it carries is one of them: bytes off the network
    * named `outputs/src/in.txt` or `workspace-outputs/.git/hooks/…` wrote
    * an input and a git hook on a green `cache-hit-remote` (item 942).
@@ -804,9 +804,9 @@ export interface CacheLayer {
    */
   ingest(hash: string, body: Blob | Response, meta: IngestMeta): Promise<void>
   /**
-   * The ONE run-history write: a whole `vx run` atomically, the per-task
-   * `runs` rows and the one `invocations` header row — in a SINGLE
-   * transaction (one fsync). Input-fingerprint rows are NOT written here — they
+   * The run-history write at a run's end, atomically: the per-task `runs`
+   * rows (less the hits a `HistoryStream` already wrote) and the one
+   * `invocations` header row — in a SINGLE transaction (one fsync). Input-fingerprint rows are NOT written here — they
    * ride the entry-save transaction (`save`/`ingest`) so a warm
    * all-cache-hit run writes nothing.
    */

package/src/cache/lockfile-memo.ts

@@ -11,7 +11,8 @@
 import { Database } from 'bun:sqlite'
 import { existsSync } from 'node:fs'
 import path from 'node:path'
-import { closeDb, SCHEMA_VERSION, SQLITE_FCNTL_PERSIST_WAL } from './cache.js'
+import { closeDb, SCHEMA_VERSION } from './cache.js'
+import { SQLITE_FCNTL_PERSIST_WAL } from './schema.js'
 
 /** One claimant's parse of one lockfile's content. */
 export interface LockfileMemo {