@vzn/vx 0.0.650 → 0.0.652

package/src/orchestrator/locked-digests.ts

@@ -0,0 +1,63 @@
+// A run keys a claimed file from what `vx lock` recorded of it in
+// `.vx/dependencies.lock.json`, as it takes configs from the config lock:
+// the digests are read, never derived, so no run parses a lockfile for
+// its key. The record holds only while the file's bytes hash to what was
+// recorded: one that moved (an install) refuses the run before any key is
+// folded, naming the file and `vx lock`. A present file with no record,
+// or no lock at all, refuses when a claimant asks for it: an absent record
+// is never read as "no dependencies". The other files the digests read
+// (`extras`: a `link:` directory, a patch) are handed to the claimant with
+// their recorded hashes: a linked directory is edited with no install, so
+// one that moved is the claimant's to digest anew, not a refusal.
+
+import {
+  DEPENDENCIES_LOCK_NAME,
+  type DependenciesLock,
+  lockKey,
+  parseDependenciesLock,
+  recordedDigests,
+} from '../workspace/index.js'
+import { UserError, xxh3hex } from '../util/index.js'
+import type { KeyHookContext, LockedFile } from './plugin.js'
+
+const refused = (message: string): UserError => new UserError(message, 'VX_E_LOCK')
+
+/**
+ * `KeyHookContext.locked` for one run, over the claimed files' bytes as
+ * the run read them (`readClaimedFiles`; absent ones are missing) and the
+ * lock's bytes (null when there is none). Each recorded claimed file is
+ * checked first: one whose bytes moved, or that is gone, throws here.
+ */
+export function lockedFiles(
+  workspaceRoot: string,
+  claimed: readonly string[],
+  bytes: ReadonlyMap<string, Uint8Array>,
+  lockBytes: Uint8Array | null,
+): KeyHookContext['locked'] {
+  const lock: DependenciesLock | null = parseDependenciesLock(lockBytes)
+  const records = new Map<string, LockedFile>()
+  for (const file of claimed) {
+    const rec = lock === null ? undefined : recordedDigests(lock, file)
+    if (rec === undefined) continue
+    const now = bytes.get(file)
+    if (now === undefined || xxh3hex(now) !== rec.hash) {
+      throw refused(`${file} changed since \`vx lock\`: run \`vx lock\``)
+    }
+    records.set(file, {
+      extras: rec.extras,
+      digest(projectDir) {
+        const dir = lockKey(workspaceRoot, projectDir)
+        if (!rec.has(dir))
+          throw refused(`${dir} is not in ${DEPENDENCIES_LOCK_NAME}: run \`vx lock\``)
+        return rec.of(dir)
+      },
+    })
+  }
+  return async (file) => {
+    const rec = records.get(file)
+    if (rec !== undefined || !bytes.has(file)) return rec
+    if (lockBytes === null) throw refused(`no ${DEPENDENCIES_LOCK_NAME}: run \`vx lock\``)
+    if (lock === null) throw refused(`${DEPENDENCIES_LOCK_NAME} is invalid, run \`vx lock\``)
+    throw refused(`${file} is not in ${DEPENDENCIES_LOCK_NAME}: run \`vx lock\``)
+  }
+}

package/src/orchestrator/lockfile-claim.ts

@@ -7,11 +7,18 @@
 // fallback for a project the file does not list and the `--affected`
 // diff are one implementation here, so a third lockfile is a parser.
 //
-// The digests are memoised in cache.db (`lockfile_memos`, one row per
-// lockfile and claimant) by the file's xxh3, so a warm run pays one read +
-// hash + one row read, never a parse; within one process (a run, a watch cycle) the file's size,
-// mtime, ctime and inode gate even the read; and per run the read happens once (a WeakMap
-// on the context core hands every `key` call of a run).
+// A run's key reads each project's digest from `.vx/dependencies.lock.json`
+// (`KeyHookContext.locked`), never the file: only `vx lock` and
+// `--affected` digest it, and a run whose extra file (a `link:` directory,
+// edited with no install) moved since the lock, as the record is stale
+// for it then. What the `discover` and `project` stages read
+// (the edges, the recorded names) is memoised in cache.db
+// (`lockfile_memos`, one row per lockfile and claimant) by the file's xxh3,
+// so a warm run pays one read + hash + one row read, never a parse; within
+// one process (a run, a watch cycle) the file's size, mtime, ctime and
+// inode gate even the read. A run's read leaves the digests out (most of a
+// parse: 9-25 ms on this repo's bun.lock, against 4-13 for the text), and
+// `vx lock` adds them to the memo.
 
 import path from 'node:path'
 import { stat } from 'node:fs/promises'
@@ -104,21 +111,27 @@ export interface LockfileClaimHooks {
 }
 
 interface Digests {
-  /** xxh3 of the lockfile bytes; '' when the file is absent. */
+  /** xxh3 of the lockfile bytes and the extra files' hashes; '' when the file is absent. */
   readonly lock: string
-  readonly importers: ReadonlyMap<string, string>
+  /** xxh3 of the lockfile bytes alone. */
+  readonly bytes: string
+  /** The extra files the digests read. */
+  readonly extras: readonly string[]
+  /** Each importer's digest; undefined when the read that made this left them out. */
+  readonly importers: ReadonlyMap<string, string> | undefined
   readonly edges: ReadonlyMap<string, LockfileImporter>
   readonly recorded: ReadonlyMap<string, ReadonlySet<string>> | undefined
 }
 
 /**
- * A root-relative extra file's content hash, '' when absent; a path leaving
- * the root is never read. One there but unreadable (EACCES, a symlink loop)
- * refuses, as a settings file does: folded as '', it keyed as no file at all.
+ * A root-relative extra file's content hash, '' when absent. A path above
+ * the root is read too: a `file:` or `link:` directory beside the checkout
+ * is what a task imports, and left unread an edit in it moved no key. One
+ * there but unreadable (EACCES, a symlink loop) refuses, as a settings file
+ * does: folded as '', it keyed as no file at all.
  */
-async function hashExtra(workspaceRoot: string, rel: string): Promise<string> {
-  if (path.isAbsolute(rel) || rel.split(/[\\/]/).includes('..')) return 'outside-root'
-  const abs = path.join(workspaceRoot, rel)
+export async function hashExtra(workspaceRoot: string, rel: string): Promise<string> {
+  const abs = path.resolve(workspaceRoot, rel)
   try {
     return xxh3hex(await Bun.file(abs).bytes())
   } catch (err) {
@@ -168,7 +181,7 @@ function identityOf(st: { size: number; mtimeMs: number; ctimeMs: number; ino: n
 async function statsOf(workspaceRoot: string, rels: readonly string[]): Promise<string[]> {
   return Promise.all(
     rels.map((rel) =>
-      stat(path.join(workspaceRoot, rel)).then(
+      stat(path.resolve(workspaceRoot, rel)).then(
         (st) => (st.isDirectory() ? hashExtra(workspaceRoot, rel) : identityOf(st)),
         () => 'gone',
       ),
@@ -234,8 +247,17 @@ export function lockfileClaim(options: LockfileClaimOptions): LockfileClaimHooks
   }
   // Per run: every `key` call of one run gets the same context object.
   const perRun = new WeakMap<object, Promise<Digests>>()
+  const lockedPerRun = new WeakMap<
+    object,
+    Promise<((dir: string) => string | undefined) | undefined>
+  >()
 
-  const load = async (workspaceRoot: string, cacheDir: string): Promise<Digests> => {
+  /** `withDigests`: each importer's digest too, which only `vx lock` and `--affected` read. */
+  const load = async (
+    workspaceRoot: string,
+    cacheDir: string,
+    withDigests: boolean,
+  ): Promise<Digests> => {
     const full = path.join(workspaceRoot, file)
     let identity: string
     try {
@@ -243,6 +265,8 @@ export function lockfileClaim(options: LockfileClaimOptions): LockfileClaimHooks
     } catch {
       const digests: Digests = {
         lock: '',
+        bytes: '',
+        extras: [],
         importers: new Map(),
         edges: new Map(),
         recorded: undefined,
@@ -251,7 +275,11 @@ export function lockfileClaim(options: LockfileClaimOptions): LockfileClaimHooks
       return digests
     }
     const last = seen.get(workspaceRoot)
-    if (last !== undefined && last.identity === identity) {
+    if (
+      last !== undefined &&
+      last.identity === identity &&
+      (!withDigests || last.digests.importers !== undefined)
+    ) {
       const now = await statsOf(workspaceRoot, last.extras)
       if (now.every((s, i) => s === last.extraStats[last.extras[i]!])) {
         if (last.unsaved !== undefined && writeLockfileMemo(cacheDir, file, claimant, last.unsaved))
@@ -270,17 +298,19 @@ export function lockfileClaim(options: LockfileClaimOptions): LockfileClaimHooks
     let edges: ReadonlyMap<string, LockfileImporter> = new Map()
     let recorded: ReadonlyMap<string, readonly string[]> | undefined
     let unsaved: LockfileMemo | undefined
-    if (memo !== undefined) {
+    let served = false
+    if (memo !== undefined && (!withDigests || memo.importers !== null)) {
       const now = await hashExtras(workspaceRoot, Object.keys(memo.extras))
       if (Object.entries(memo.extras).every(([rel, h]) => now.hashes[rel] === h)) {
+        served = true
         extras = memo.extras
         extraStats = now.stats
-        importers = new Map(Object.entries(memo.importers))
+        importers = memo.importers === null ? undefined : new Map(Object.entries(memo.importers))
         edges = new Map(Object.entries(memo.edges as Record<string, LockfileImporter>))
         recorded = memo.recorded === undefined ? undefined : new Map(Object.entries(memo.recorded))
       }
     }
-    if (importers === undefined) {
+    if (!served) {
       const text = decode(bytes)
       const rels = [...new Set(options.extraFiles?.(text) ?? [])].sort()
       const now = await hashExtras(workspaceRoot, rels)
@@ -289,7 +319,9 @@ export function lockfileClaim(options: LockfileClaimOptions): LockfileClaimHooks
       importers =
         scope === 'workspace'
           ? new Map<string, string>()
-          : digest(text, new Map(Object.entries(extras)))
+          : withDigests
+            ? digest(text, new Map(Object.entries(extras)))
+            : undefined
       edges = options.importers?.(text) ?? new Map()
       recorded = options.recorded?.(text)
       if (memoises) {
@@ -297,7 +329,7 @@ export function lockfileClaim(options: LockfileClaimOptions): LockfileClaimHooks
           version,
           lock: lockHash,
           extras,
-          importers: Object.fromEntries(importers),
+          importers: importers === undefined ? null : Object.fromEntries(importers),
           edges: Object.fromEntries(edges),
           ...(recorded !== undefined ? { recorded: Object.fromEntries(recorded) } : {}),
         }
@@ -311,6 +343,8 @@ export function lockfileClaim(options: LockfileClaimOptions): LockfileClaimHooks
         : xxh3hex([lockHash, ...rels.map((r) => `${r}\0${extras[r]}`)].join('\0'))
     const digests: Digests = {
       lock,
+      bytes: lockHash,
+      extras: rels,
       importers,
       edges,
       recorded:
@@ -327,10 +361,36 @@ export function lockfileClaim(options: LockfileClaimOptions): LockfileClaimHooks
     })
     return digests
   }
+  /**
+   * Each project's digest for this run: the lock's, unless an extra file
+   * it records moved since (then a digest of the file as it is now, as
+   * `vx lock` would record it); undefined when the file is absent.
+   */
+  const lockedOnce = (
+    ctx: KeyHookContext,
+  ): Promise<((dir: string) => string | undefined) | undefined> => {
+    let p = lockedPerRun.get(ctx)
+    if (p === undefined) {
+      p = (async () => {
+        const rec = await ctx.locked(file)
+        if (rec === undefined) return undefined
+        const rels = Object.keys(rec.extras)
+        const now = await Promise.all(rels.map((rel) => hashExtra(ctx.workspaceRoot, rel)))
+        if (now.every((h, i) => h === rec.extras[rels[i]!])) {
+          return (dir: string) => rec.digest(dir)
+        }
+        const digests = await load(ctx.workspaceRoot, ctx.cacheDir, true)
+        const importers = digests.importers!
+        return (dir: string) => digestFor(importers, importerOf(ctx.workspaceRoot, dir))
+      })()
+      lockedPerRun.set(ctx, p)
+    }
+    return p
+  }
   const loadOnce = (ctx: KeyHookContext): Promise<Digests> => {
     let p = perRun.get(ctx)
     if (p === undefined) {
-      p = load(ctx.workspaceRoot, ctx.cacheDir)
+      p = load(ctx.workspaceRoot, ctx.cacheDir, false)
       perRun.set(ctx, p)
     }
     return p
@@ -378,6 +438,24 @@ export function lockfileClaim(options: LockfileClaimOptions): LockfileClaimHooks
         }
         return names
       },
+      // What `vx lock` commits, so `--affected` reads the base's digests
+      // instead of parsing the base's file.
+      async digests(_file: string, ctx: FingerprintContext) {
+        if (scope === 'workspace') return undefined
+        const digests = await load(ctx.workspaceRoot, ctx.cacheDir, true)
+        if (digests.lock === '') return undefined
+        const importers = digests.importers!
+        return {
+          hash: digests.bytes,
+          projects: Object.fromEntries(
+            ctx.projects.map((p) => [
+              p.name,
+              digestFor(importers, importerOf(ctx.workspaceRoot, p.dir)),
+            ]),
+          ),
+          ...(digests.extras.length > 0 ? { extras: digests.extras } : {}),
+        }
+      },
       ...(options.extraFiles !== undefined
         ? {
             // The memo records which files these exact bytes name, for this
@@ -393,19 +471,20 @@ export function lockfileClaim(options: LockfileClaimOptions): LockfileClaimHooks
         : {}),
     },
     async key(task, ctx) {
-      const digests = await loadOnce(ctx)
-      if (digests.lock === '') return undefined
-      if (scope === 'workspace') return { [part]: digests.lock }
-      return {
-        [part]: digestFor(digests.importers, importerOf(ctx.workspaceRoot, task.projectDir)),
+      if (scope === 'project') {
+        const digestOf = await lockedOnce(ctx)
+        const digest = digestOf?.(task.projectDir)
+        return digest === undefined ? undefined : { [part]: digest }
       }
+      const digests = await loadOnce(ctx)
+      return digests.lock === '' ? undefined : { [part]: digests.lock }
     },
     async importers(ctx) {
-      const digests = await load(ctx.workspaceRoot, ctx.cacheDir)
+      const digests = await load(ctx.workspaceRoot, ctx.cacheDir, false)
       return digests.lock === '' ? undefined : digests.edges
     },
     async recorded(ctx) {
-      const digests = await load(ctx.workspaceRoot, ctx.cacheDir)
+      const digests = await load(ctx.workspaceRoot, ctx.cacheDir, false)
       return digests.lock === '' ? undefined : digests.recorded
     },
   }

package/src/orchestrator/miss-save.ts

@@ -109,7 +109,7 @@ export interface SaveMissArgs {
   workspaceRoot: string
   nestedProjectDirs: string[]
   gitFilesCache?: GitFilesCache | undefined
-  /** Declared `cache.outputs.files` / `.workspaceFiles`. */
+  /** Declared `outputs.files` / `.workspaceFiles`. */
   outputs: readonly string[]
   wsOutputs: readonly string[]
   /**
@@ -119,7 +119,7 @@ export interface SaveMissArgs {
    * would also take the upstream's files the task adds beside.
    */
   ownOutputFiles?: string[] | undefined
-  /** `ownOutputFiles` for `cache.outputs.workspaceFiles` (A-43). */
+  /** `ownOutputFiles` for `outputs.workspaceFiles` (A-43). */
   ownWsOutputFiles?: string[] | undefined
   /** The Tier-3 input fingerprint rows captured by the pre-exec describe. */
   captured: readonly TaskInputComponent[]
@@ -146,6 +146,8 @@ export interface SaveMissArgs {
 export interface SaveFacts {
   saveMs?: number
   artifactBytes?: number
+  /** The saved files' bytes, as a hit's `outputBytes` counts them: the row's `outputs`. */
+  outputBytes?: number
   /** The entry landed: the outcome's `saved`, set only once it has. */
   saved?: true
 }
@@ -160,19 +162,38 @@ export async function saveMiss(a: SaveMissArgs): Promise<{ landed: Promise<SaveF
   // An additive task owns only the files it wrote (item 588), no directory.
   const tree =
     a.ownOutputFiles !== undefined
-      ? { files: a.ownOutputFiles, emptyDirs: [] }
+      ? { files: a.ownOutputFiles, emptyDirs: [], special: [] }
       : await resolveOutputTree({
           projectDir: node.projectDir,
           outputs: a.outputs,
           nestedProjectDirs: a.nestedProjectDirs,
+          special: true,
         })
   const outputFiles = tree.files
   const wsTree =
     a.ownWsOutputFiles !== undefined
-      ? { files: a.ownWsOutputFiles, emptyDirs: [] }
-      : await resolveWorkspaceOutputTree({ workspaceRoot: a.workspaceRoot, outputs: a.wsOutputs })
+      ? { files: a.ownWsOutputFiles, emptyDirs: [], special: [] }
+      : await resolveWorkspaceOutputTree({
+          workspaceRoot: a.workspaceRoot,
+          outputs: a.wsOutputs,
+          special: true,
+        })
   const wsOutputFiles = wsTree.files
   endResolve()
+  // A FIFO, socket or device holds no bytes to store (opening a FIFO waits
+  // for a writer, nx#35228), so it stays out of the entry; said, because a
+  // hit restores the tree without it.
+  const special = [
+    ...tree.special.map((p) => relPosix(node.projectDir, p)),
+    ...wsTree.special.map((p) => relPosix(a.workspaceRoot, p)),
+  ]
+  if (special.length > 0) {
+    warnOf(log)(
+      `[vx] ${node.id}: ${special.join(', ')} ${special.length === 1 ? 'is' : 'are'} not a regular file or symlink ` +
+        `(a FIFO, socket or device): vx does not cache ${special.length === 1 ? 'it' : 'them'}, so a hit restores the outputs without ${special.length === 1 ? 'it' : 'them'} ` +
+        `— emit a file there, or take ${special.length === 1 ? 'it' : 'them'} back with a '!' entry`,
+    )
+  }
   // The mirror of the input warning: declared outputs that resolve to
   // nothing save an empty artifact, and the next hit "restores" it —
   // the build that ran nowhere looks like a build that ran. `files: []`
@@ -189,14 +210,14 @@ export async function saveMiss(a: SaveMissArgs): Promise<{ landed: Promise<SaveF
     // (project dir === workspace root) the write SUCCEEDS into that
     // scratch and the task exits 0, so this warning is the only thing that
     // says the build produced nothing (item 444). A declared
-    // `cache.outputs` is not a write grant; `exec.sandbox.allow.write` is.
+    // `outputs` is not a write grant; `exec.sandbox.allow.write` is.
     const sandboxed = node.config.exec?.sandbox !== undefined
     const grantsWrite = (node.config.exec?.sandbox?.allow?.write?.length ?? 0) > 0
     // A `workspaceFiles` directory linked out of the workspace drops every
     // file (M-65); a project one is refused by the resolver (X-88).
     const linkedOut = outputDirLinkedOut(a.workspaceRoot, a.wsOutputs)
     warnOf(log)(
-      `[vx] ${node.id}: cache.outputs matched no files (${[...a.outputs, ...a.wsOutputs].join(', ')}) — ` +
+      `[vx] ${node.id}: outputs matched no files (${[...a.outputs, ...a.wsOutputs].join(', ')}) — ` +
         `an empty artifact is saved; a later hit restores nothing` +
         (linkedOut !== undefined
           ? ` — ${linkedOut.dir} is a symlink to ${linkedOut.target}, outside ${linkedOut.base}, and vx keeps only outputs inside it: make ${linkedOut.dir} a directory`
@@ -239,6 +260,8 @@ export async function saveMiss(a: SaveMissArgs): Promise<{ landed: Promise<SaveF
       },
     })
     endSave()
+    const bytes = cache.outputBytes?.(a.hash)
+    if (bytes !== undefined) facts.outputBytes = bytes
     if (a.measure === true) {
       facts.saveMs = Math.round(performance.now() - saveStart)
       // No local artifact (local writes off): no size to say.
@@ -294,9 +317,26 @@ export type UnsavedArgs = Pick<
  * A miss that ran here and saves nothing (it failed, the policy writes
  * nothing, an upstream failed, its key no longer held) still wrote its
  * outputs, and a same-project reader after it must see them as it sees a
- * save's: resolved and marked the same way.
+ * save's: resolved and marked the same way. Returns their bytes, the
+ * row's `outputs`: blank, an unsaved miss read as one that wrote nothing.
  */
-export async function markUnsaved(a: UnsavedArgs): Promise<void> {
+export async function markUnsaved(a: UnsavedArgs): Promise<number> {
+  const { outputFiles, wsOutputFiles } = await resolveUnsaved(a)
+  markWritten(a, outputFiles, wsOutputFiles)
+  return sizeOf(a.node.projectDir, outputFiles) + sizeOf(a.workspaceRoot, wsOutputFiles)
+}
+
+/** An unsaved miss nothing reads after: only the bytes of its outputs, its row's `outputs`. */
+export async function unsavedOutputBytes(
+  a: Pick<UnsavedArgs, 'node' | 'workspaceRoot' | 'nestedProjectDirs' | 'outputs' | 'wsOutputs'>,
+): Promise<number> {
+  const { outputFiles, wsOutputFiles } = await resolveUnsaved(a)
+  return sizeOf(a.node.projectDir, outputFiles) + sizeOf(a.workspaceRoot, wsOutputFiles)
+}
+
+async function resolveUnsaved(
+  a: Pick<UnsavedArgs, 'node' | 'workspaceRoot' | 'nestedProjectDirs' | 'outputs' | 'wsOutputs'>,
+): Promise<{ outputFiles: string[]; wsOutputFiles: string[] }> {
   const endResolve = span('miss: resolve outputs')
   const outputFiles = await resolveOutputs({
     projectDir: a.node.projectDir,
@@ -308,7 +348,14 @@ export async function markUnsaved(a: UnsavedArgs): Promise<void> {
     outputs: a.wsOutputs,
   })
   endResolve()
-  markWritten(a, outputFiles, wsOutputFiles)
+  return { outputFiles, wsOutputFiles }
+}
+
+/** The bytes of `files` (absolute, or under `base`); one gone since it was listed counts none. */
+function sizeOf(base: string, files: readonly string[]): number {
+  let n = 0
+  for (const f of files) n += statSync(path.resolve(base, f), { throwIfNoEntry: false })?.size ?? 0
+  return n
 }
 
 /**
@@ -319,7 +366,7 @@ export async function markUnsaved(a: UnsavedArgs): Promise<void> {
  * these paths. On a 1000-package cold run this removes ~one synchronous
  * `git ls-files` spawn per project (the single largest cold-run cost —
  * 22% of CPU in profiling). Contract: outputs must be declared — an
- * executed task that writes files outside `cache.outputs.files` which a
+ * executed task that writes files outside `outputs.files` which a
  * same-project downstream task reads is undeclared behavior (the restore
  * path already assumes it).
  */

package/src/orchestrator/persistent-task.ts

@@ -19,6 +19,7 @@ import { warnOf } from '../report/index.js'
 import type { ExecuteArgs } from './execute-task.js'
 import {
   commandWriteReach,
+  dependencyReads,
   mayWriteFingerprint,
   type Placeholder,
   placeholderSweeper,
@@ -135,6 +136,7 @@ export async function executePersistentTask(args: ExecuteArgs): Promise<TaskOutc
       undefined,
       args.nestedProjectDirs,
       args.cacheDir,
+      await dependencyReads(args.readableDeps?.(node) ?? [], args.workspaceRoot),
     )
     placeholders = sb.placeholders
     serverSandbox = sb.sandbox
@@ -283,7 +285,9 @@ export async function executePersistentTask(args: ExecuteArgs): Promise<TaskOutc
     const message = err instanceof Error ? err.message : String(err)
     // The task's OWN stream, not the process's: the frame is where a
     // reader looks for why a task failed, and a run with a custom logger
-    // (an embedder) never saw a bare stderr write at all.
+    // (an embedder) never saw a bare stderr write at all. What waited on
+    // an open line goes first.
+    ends.end()
     log.taskStderr(
       node,
       ends.own(`[vx] ${node.id}: persistent task failed to become ready: ${message}\n`),

package/src/orchestrator/placement.ts

@@ -337,7 +337,7 @@ export function placeTasks(
         projectDir: node.projectDir,
         command: node.config.exec!.command,
         pinnedLocal: pinned.has(node.id),
-        cacheable: node.config.cache !== undefined,
+        cacheable: node.config.cache === true,
       },
       executorLabel,
       (e) => pinsOf(e).has(node.id) || !routes(e),

package/src/orchestrator/plan.ts

@@ -25,7 +25,7 @@ export type CacheStatus =
   | 'hit-local' // entry exists in local cache
   | 'hit-remote' // entry exists in the remote layer (would be fetched)
   | 'miss' // caching enabled but no entry — would execute
-  | 'no-cache' // task opts out of caching (no `cache` block) or --no-cache
+  | 'no-cache' // task opts out of caching (no `cache: true`) or --no-cache
   | 'group' // no `exec`; just an aggregator
   | 'not-started' // a server every dependant of which restores early: the run never spawns it
   | 'skipped' // `exec.platforms` leave this machine out, or a task it depends on is skipped
@@ -186,7 +186,7 @@ export async function plan(args: PlanArgs): Promise<RunPlan> {
       // so nothing is probed. Whether that run is a miss or no cache at all
       // is the WRITE axes': `--force` and `--cache-policy=local:w` save what they
       // run, and the plan called them `no-cache`, the label a task with no
-      // `cache` block gets (item 991). The probe below routes through the
+      // `cache: true` gets (item 991). The probe below routes through the
       // policy-aware cache layer, which itself respects read gating.
       const policy = args.cachePolicy ?? FULL_CACHE_POLICY
       const reads = policy.localRead || policy.remoteRead
@@ -225,7 +225,11 @@ export async function plan(args: PlanArgs): Promise<RunPlan> {
     )
     const dependents = new Map<string, string[]>()
     for (const node of args.nodes.values())
-      for (const dep of node.deps) dependents.set(dep, [...(dependents.get(dep) ?? []), node.id])
+      for (const dep of node.deps) {
+        const ds = dependents.get(dep)
+        if (ds === undefined) dependents.set(dep, [node.id])
+        else ds.push(node.id)
+      }
     for (const id of idleServers(args.nodes, dependents, restoreTier))
       cacheStatusById.set(id, 'not-started')
   }

package/src/orchestrator/plugin-host.ts

@@ -33,6 +33,7 @@ import type {
   DiscoverContext,
   ExecutorContext,
   FingerprintChange,
+  FingerprintDigests,
   FingerprintContext,
   GraphHookContext,
   KeyHookContext,
@@ -44,6 +45,7 @@ import type {
   ConfigContext,
 } from './plugin.js'
 import type { ProjectMeta } from '../workspace/index.js'
+import { hashExtra } from './lockfile-claim.js'
 
 /** `a string`, `an array`, `null`, `a number` — for a refusal that names what came back. */
 function describeValue(v: unknown): string {
@@ -392,6 +394,65 @@ export async function claimedAffected(
   ctx: FingerprintContext,
 ): Promise<Set<string> | undefined> {
   const answer = await safe(plugin, 'fingerprint', () => plugin.fingerprint!.affected(change, ctx))
+  return projectNames(plugin, answer, ctx)
+}
+
+/**
+ * `FingerprintClaim.digests`' answer for `file`, each extra file it names
+ * with its hash now (`hashExtra`, as a run checks it); `undefined` when the
+ * plugin has none. A digest of a name no project carries, or a value that
+ * is not a string, is refused by name: `vx lock` would commit it.
+ */
+export async function claimedDigests(
+  plugin: VxPlugin,
+  file: string,
+  ctx: FingerprintContext,
+): Promise<
+  | {
+      hash: string
+      projects: FingerprintDigests['projects']
+      extras?: Readonly<Record<string, string>>
+    }
+  | undefined
+> {
+  const digests = plugin.fingerprint?.digests
+  if (digests === undefined) return undefined
+  const answer: unknown = await safe(plugin, 'fingerprint', () =>
+    digests.call(plugin.fingerprint, file, ctx),
+  )
+  if (answer === undefined) return undefined
+  const { hash, projects, extras } = (answer ?? {}) as Partial<FingerprintDigests>
+  if (
+    typeof hash !== 'string' ||
+    typeof projects !== 'object' ||
+    projects === null ||
+    Object.values(projects).some((d) => typeof d !== 'string') ||
+    (extras !== undefined &&
+      (!Array.isArray(extras) || extras.some((rel) => typeof rel !== 'string')))
+  ) {
+    throw new UserError(
+      `plugin '${plugin.name}' failed in fingerprint: digests returned ${describeValue(answer)}, not { hash, projects: { name: digest }, extras?: [path] }`,
+    )
+  }
+  const known = new Set(ctx.projects.map((p) => p.name))
+  const stray = Object.keys(projects).find((n) => !known.has(n))
+  if (stray !== undefined) {
+    throw new UserError(
+      `plugin '${plugin.name}' failed in fingerprint: digest of ${JSON.stringify(stray)}, which is not a project in this workspace`,
+    )
+  }
+  if (extras === undefined || extras.length === 0) return { hash, projects }
+  const hashed = await Promise.all(
+    extras.map(async (rel) => [rel, await hashExtra(ctx.workspaceRoot, rel)] as const),
+  )
+  return { hash, projects, extras: Object.fromEntries(hashed) }
+}
+
+async function projectNames(
+  plugin: VxPlugin,
+  answer: unknown,
+  ctx: FingerprintContext,
+): Promise<Set<string> | undefined> {
   if (answer === undefined) return undefined
   // A plain object is no list: `for…of` threw "is not iterable", naming
   // neither the plugin nor the hook.
@@ -460,6 +521,8 @@ export async function claimedExtraFiles(
 export interface ScheduleRun {
   readonly step?: <T>(id: string, work: () => Promise<T>) => Promise<T>
   readonly refined?: (merged: ReadonlyMap<string, number>) => void
+  /** Where `ctx.flaky` names go; none in a plan. */
+  readonly flaky?: (taskIds: Iterable<string>) => void
 }
 
 /**
@@ -472,7 +535,7 @@ export interface ScheduleRun {
 export async function applyScheduleHooks(
   plugins: readonly VxPlugin[],
   nodes: ReadonlyMap<string, TaskNode>,
-  ctx: Omit<ScheduleHookContext, 'cache' | 'refine' | 'onRefine' | 'refining'>,
+  ctx: Omit<ScheduleHookContext, 'cache' | 'refine' | 'onRefine' | 'refining' | 'flaky'>,
   cacheFor: (plugin: string) => PluginCache = () => absentPluginCache,
   run: ScheduleRun = {},
 ): Promise<ReadonlyMap<string, number>> {
@@ -525,7 +588,8 @@ export async function applyScheduleHooks(
     const onRefine = (listener: () => void): void => {
       if (run.refined !== undefined) listeners.push({ plugin, i, listener })
     }
-    const own = { ...ctx, cache: cacheFor(plugin.name), refine, onRefine, refining }
+    const flaky = (taskIds: Iterable<string>): void => run.flaky?.(taskIds)
+    const own = { ...ctx, cache: cacheFor(plugin.name), refine, onRefine, refining, flaky }
     const call = (): Promise<ReadonlyMap<string, number> | undefined> =>
       safe(plugin, 'schedule', () => plugin.schedule!(nodes, own))
     const weights = await (run.step === undefined
@@ -827,6 +891,7 @@ const EXECUTOR_HOOKS = [
   'footer',
   'machines',
   'idealMs',
+  'advice',
   'profile',
   'running',
 ] as const