@vzn/vx 0.0.21 → 0.0.22

package/src/orchestrator/failure-recap.ts

@@ -0,0 +1,121 @@
+// The end of each failed task's output, kept for the run's last lines
+// (item 706). A failure's frame prints when the task finishes, which in a
+// long CI log is thousands of lines above the end, and GitHub's API returns
+// only a job log's last 5,000 lines: the summary is the one place a reader
+// reliably looks, so the failure's own words are repeated there.
+//
+// The capture is a ring over the output's END: it keeps at most
+// RECAP_TASK_BYTES characters (and a newline) however much a task prints,
+// and counts what it evicts, so the recap can say how much it is not
+// showing.
+
+/** Lines of each failed task's output the recap repeats. */
+const RECAP_LINES = 30
+/** The byte cap on one task's repeated lines. */
+const RECAP_TASK_BYTES = 8 * 1024
+/**
+ * Tasks that get a tail; the rest are named by id. Five tails at the
+ * per-task cap is 40 KiB, so the recap stays under 64 KiB with no cap
+ * of its own.
+ */
+export const RECAP_TASKS = 5
+
+export interface RecapRing {
+  chunks: string[]
+  chars: number
+  /** Newlines evicted from the head. */
+  cutLines: number
+  /** Bytes evicted from the line the kept text starts with; 0 when it starts a line. */
+  cutPartialBytes: number
+}
+
+export interface RecapTail {
+  /** The last lines, at most RECAP_LINES of them and RECAP_TASK_BYTES bytes. */
+  text: string
+  /** Whole lines above `text`. */
+  earlierLines: number
+  /** Bytes cut from the start of `text`'s first line. */
+  cutBytes: number
+}
+
+export function createRecapRing(): RecapRing {
+  return { chunks: [], chars: 0, cutLines: 0, cutPartialBytes: 0 }
+}
+
+// The ring counts characters, the cap bytes: a UTF-16 unit is at least one
+// UTF-8 byte, so the last RECAP_TASK_BYTES characters always hold the last
+// RECAP_TASK_BYTES bytes. One more for the final newline the tail drops.
+const RING_CHARS = RECAP_TASK_BYTES + 1
+
+export function appendRecapRing(r: RecapRing, chunk: string): void {
+  if (chunk.length === 0) return
+  r.chunks.push(chunk)
+  r.chars += chunk.length
+  // A whole chunk goes only when what follows it still fills the ring:
+  // evicting past the cap would leave the recap fewer lines than it shows.
+  while (r.chunks.length > 1 && r.chars - r.chunks[0]!.length >= RING_CHARS) {
+    const gone = r.chunks.shift()!
+    r.chars -= gone.length
+    evict(r, gone, gone.length)
+  }
+  if (r.chars > RING_CHARS) {
+    const head = r.chunks[0]!
+    const at = r.chars - RING_CHARS
+    evict(r, head, at)
+    r.chunks[0] = head.slice(at)
+    r.chars = RING_CHARS
+  }
+}
+
+function evict(r: RecapRing, s: string, end: number): void {
+  const last = s.lastIndexOf('\n', end - 1)
+  const partial = Buffer.byteLength(s.slice(last + 1, end))
+  if (last < 0) {
+    r.cutPartialBytes += partial
+    return
+  }
+  r.cutLines += countNewlines(s, last + 1)
+  r.cutPartialBytes = partial
+}
+
+function countNewlines(s: string, end: number): number {
+  let n = 0
+  for (let i = s.indexOf('\n'); i !== -1 && i < end; i = s.indexOf('\n', i + 1)) n++
+  return n
+}
+
+/**
+ * The recap's view of what the ring kept: its last RECAP_LINES lines, then
+ * its last RECAP_TASK_BYTES bytes (cut on a character boundary). The text
+ * is a fresh copy, so it holds nothing of the chunks it came from.
+ */
+export function recapTail(r: RecapRing): RecapTail {
+  const t = r.chunks.join('')
+  const end = t.endsWith('\n') ? t.length - 1 : t.length
+  let start = 0
+  for (let pos = end, taken = 1; ; pos = start - 1, taken++) {
+    const nl = pos === 0 ? -1 : t.lastIndexOf('\n', pos - 1)
+    if (nl < 0) {
+      start = 0
+      break
+    }
+    start = nl + 1
+    if (taken === RECAP_LINES) break
+  }
+  let earlierLines = r.cutLines + countNewlines(t, start)
+  let cutBytes = start === 0 ? r.cutPartialBytes : 0
+  const bytes = Buffer.from(t.slice(start, end), 'utf8')
+  if (bytes.length <= RECAP_TASK_BYTES)
+    return { text: bytes.toString('utf8'), earlierLines, cutBytes }
+  let at = bytes.length - RECAP_TASK_BYTES
+  while ((bytes[at]! & 0xc0) === 0x80) at++
+  const lastNl = bytes.lastIndexOf(0x0a, at - 1)
+  if (lastNl < 0) cutBytes += at
+  else {
+    for (let i = bytes.indexOf(0x0a); i !== -1 && i <= lastNl; i = bytes.indexOf(0x0a, i + 1)) {
+      earlierLines++
+    }
+    cutBytes = at - lastNl - 1
+  }
+  return { text: bytes.subarray(at).toString('utf8'), earlierLines, cutBytes }
+}

package/src/orchestrator/fingerprint-watch.ts

@@ -0,0 +1,89 @@
+// The workspace fingerprint is read once per run, before any task, and
+// every key folds it (and a lockfile plugin's per-project parts, taken from
+// the same files). A task in the root project may rewrite one of those
+// files — `pnpm install` without `--frozen-lockfile` — and every key taken
+// before it then names a lockfile the tree no longer holds: a save under
+// one filed bytes built against the new install under the old lockfile's
+// key, replayed whenever the tree went back (item 750). The watch answers
+// "has a fingerprinted file moved since the run read it", re-learning the
+// fact only after a task that may have written one ran (`wrote`), so a run
+// with no such task never touches the files again.
+
+import { readFileSync, statSync } from 'node:fs'
+import path from 'node:path'
+import { FILE_HASH_RACY_MS } from '../cache/index.js'
+import { WORKSPACE_FINGERPRINT_FILES, type WorkspaceFingerprints } from '../workspace/index.js'
+import type { Logger } from './logger.js'
+
+export class FingerprintWatch {
+  private pending = false
+  private movedFiles: string[] | undefined
+  private said = false
+
+  /** `at`: when the run started reading the files (ms since the epoch). */
+  constructor(
+    private readonly workspaceRoot: string,
+    private readonly read: WorkspaceFingerprints,
+    private readonly at: number,
+  ) {}
+
+  /** A task that may rewrite a fingerprinted file (`mayWriteFingerprint`) ran a command. */
+  wrote(): void {
+    this.pending = true
+  }
+
+  /**
+   * The fingerprinted files that no longer hold what the run read, or
+   * undefined. Once one has, the run stays moved: every key already taken
+   * folded the old bytes. One `stat` per table entry after each writer; a
+   * file written since the read (by ctime, with git's racy window) is read
+   * and compared. The stat follows a link as both reads do: a lockfile
+   * that is a symlink, rewritten through it, moves its target's ctime and
+   * never the link's, and an `lstat` here skipped it once the link had
+   * aged past the window — a stale hit on every later run (item 760).
+   */
+  moved(): readonly string[] | undefined {
+    if (this.movedFiles !== undefined || !this.pending) return this.movedFiles
+    this.pending = false
+    const moved: string[] = []
+    for (const f of WORKSPACE_FINGERPRINT_FILES) {
+      const abs = path.join(this.workspaceRoot, f)
+      const before = this.read.files.get(f)
+      let ctimeMs: number
+      try {
+        ctimeMs = statSync(abs).ctimeMs
+      } catch {
+        if (before !== undefined) moved.push(f)
+        continue
+      }
+      if (before !== undefined && ctimeMs < this.at - FILE_HASH_RACY_MS) continue
+      let now: Uint8Array | undefined
+      try {
+        now = readFileSync(abs)
+      } catch {
+        // Not a file (the run-start read skipped it the same way).
+      }
+      if (
+        now === undefined ? before !== undefined : before === undefined || !sameBytes(now, before)
+      ) {
+        moved.push(f)
+      }
+    }
+    if (moved.length > 0) this.movedFiles = moved
+    return this.movedFiles
+  }
+
+  /** The run's one line about it, however many tasks it withholds. */
+  say(log: Logger): void {
+    if (this.said || this.movedFiles === undefined) return
+    this.said = true
+    log.status(
+      `[vx] a task rewrote \`${this.movedFiles.join('`, `')}\` during the run, which every key ` +
+        `folds (the workspace fingerprint): nothing keyed before it is restored or saved from here on`,
+    )
+  }
+}
+
+function sameBytes(a: Uint8Array, b: Uint8Array): boolean {
+  return a.length === b.length && Buffer.compare(a, b) === 0
+}

package/src/orchestrator/framed-output.ts

@@ -28,7 +28,8 @@
 import { isGroupTask, type TaskNode, type TaskOutcome } from '../graph/index.js'
 import { paint, type ColorSupport } from './colors.js'
 import { formatDuration } from './summary.js'
-import { outcomeLabel } from './events.js'
+import { outcomeLabel, skippedReason } from './events.js'
+import type { RecapTail } from './failure-recap.js'
 
 const NO_COLOR: ColorSupport = { enabled: false }
 
@@ -205,7 +206,7 @@ function paintTaskId(node: TaskNode, colors: ColorSupport, opts: { bold?: boolea
 
 // ── Reported-line grid: glyph · time · status · cache · name ────────
 // glyph SHAPE encodes the cache axis (⏺ miss · ► fresh · ⇢ local · ⇣
-// remote; ◼ failed · ⊘ skipped · ⦿ running), glyph COLOR encodes the
+// remote; ◼ failed · ⊘ skipped), glyph COLOR encodes the
 // task axis (green/red/yellow/cyan). The status and cache WORDS spell
 // the two axes out, each in its own color. Time is right-aligned in a
 // fixed cell so durations line up and a ticking elapsed never shifts
@@ -350,17 +351,29 @@ function formatOutcomeRow(
   )
 }
 
-/** Compact one-liner for a skipped task — it never ran (blank time). */
-export function formatTaskSkippedLine(node: TaskNode, colors: ColorSupport = NO_COLOR): string {
-  return formatTaskRow(
-    paint(WARN, '\u2298', colors),
-    null,
-    'skipped',
-    WARN,
-    '',
-    '',
-    paintTaskId(node, colors),
-    colors,
+/**
+ * Compact one-liner for a skipped task — it never ran (blank time). The
+ * blocker rides the row (`• blocked by lib#build`): the footer's Skipped
+ * section groups the same fact, but the row is where the reader's eye is.
+ */
+export function formatTaskSkippedLine(
+  node: TaskNode,
+  colors: ColorSupport = NO_COLOR,
+  blockedBy?: string,
+): string {
+  const why = skippedReason(blockedBy)
+  const suffix = why === '' ? '' : ` ${paint('', `• ${why}`, colors, { dim: true })}`
+  return (
+    formatTaskRow(
+      paint(WARN, '\u2298', colors),
+      null,
+      'skipped',
+      WARN,
+      '',
+      '',
+      paintTaskId(node, colors),
+      colors,
+    ) + suffix
   )
 }
 
@@ -467,6 +480,60 @@ export function formatPersistentList(
   )
 }
 
+/** One failed task's section of the end-of-run recap. */
+export interface RecapEntry {
+  node: TaskNode
+  outcome: TaskOutcome
+  tail: RecapTail
+  /** Characters a bounded capture (a persistent task's) dropped before the tail saw them. */
+  droppedChars: number
+}
+
+/**
+ * The run's last block: each failed task's last lines, under the failure's
+ * label, then the ids of the failures past the tail limit. The lines are
+ * raw, like a frame's, and `fence` wraps them where a task's text could be
+ * read as something other than text (GitHub Actions' workflow commands).
+ */
+export function formatFailureRecap(
+  entries: readonly RecapEntry[],
+  more: readonly string[],
+  colors: ColorSupport = NO_COLOR,
+  fence: (lines: string[]) => string[] = (lines) => lines,
+): string[] {
+  const total = entries.length + more.length
+  const dim = (s: string) => paint('', s, colors, { dim: true })
+  const lines = [
+    '',
+    `  Failed:   ${total} task${total === 1 ? '' : 's'} — the last lines ${total === 1 ? 'it' : 'each one'} printed`,
+  ]
+  for (const e of entries) {
+    lines.push(
+      '',
+      `  ${paint(ERROR, '◼︎', colors)} ${paintTaskId(e.node, colors, { bold: true })} ${dim('—')} ${paint(ERROR, outcomeLabel(e.outcome), colors, { bold: true })}`,
+    )
+    const cut: string[] = []
+    const { earlierLines, cutBytes } = e.tail
+    if (earlierLines > 0)
+      cut.push(`${count(earlierLines)} earlier line${earlierLines === 1 ? '' : 's'}`)
+    if (cutBytes > 0) cut.push(`${count(cutBytes)} bytes cut from the start of the line below`)
+    if (e.droppedChars > 0) {
+      cut.push(`the capture dropped ${count(e.droppedChars)} characters of the task's output`)
+    }
+    if (cut.length > 0) lines.push(dim(`  … ${cut.join(', and ')}`))
+    if (e.tail.text.length === 0) lines.push(dim('  (no output)'))
+    else lines.push(...fence(e.tail.text.split('\n')))
+  }
+  if (more.length > 0) {
+    lines.push('', `  … and ${more.length} more failed: ${more.join(', ')}`)
+  }
+  return lines
+}
+
+function count(n: number): string {
+  return n.toLocaleString('en-US')
+}
+
 function formatBlockHeader(o: TaskOutcome, colors: ColorSupport): string {
   const shortHash = o.hash ? o.hash.slice(0, 8) : ''
   const dim = (s: string) => paint('', s, colors, { dim: true })
@@ -482,7 +549,7 @@ function formatBlockHeader(o: TaskOutcome, colors: ColorSupport): string {
       // carries the outcome like every other status.
       return paint(ERROR, word, colors, { bold: true })
     case 'skipped':
-      return paint(WARN, 'skipped (upstream failed)', colors)
+      return paint(WARN, word, colors)
     default:
       return dim(word)
   }

package/src/orchestrator/history.ts

@@ -1,5 +1,6 @@
-// HistoryTable + HistoryProvider — historical run data the scheduler
-// uses for predictive priority and `vx info --history` surfaces.
+// HistoryTable + HistoryProvider — historical run data the `schedule`
+// plugin (`@vzn/vx-schedule-history`, and its `vx history` verb) and
+// `--dry`'s time prediction read.
 //
 // The data has been in cache.db.runs since schema v11; what's new is
 // surfacing it. One SQL statement per call pulls the last N executed rows
@@ -7,10 +8,8 @@
 // result becomes a read-only snapshot for the run's lifetime. Loaded once
 // by the `schedule` stage (or `--dry`); never mutated mid-run.
 //
-// Two providers:
-//   LocalHistoryProvider  — reads cache.db directly (zero-config).
-//   RemoteHistoryProvider — would call a service RPC; deferred to
-//                            when such an RPC actually exists.
+// One provider ships, `LocalHistoryProvider`, reading cache.db directly
+// (zero-config); the interface is the seam a plugin fills for any other.
 
 import type { Database } from 'bun:sqlite'
 import { EXECUTED_RUNS_SQL } from '../cache/index.js'
@@ -94,7 +93,7 @@ export class LocalHistoryProvider implements HistoryProvider {
     const floorRow = this.db
       .query(
         `SELECT MIN(id) AS id FROM runs WHERE run_id =
-           (SELECT run_id FROM invocations ORDER BY started_at DESC LIMIT 1 OFFSET ?)`,
+           (SELECT run_id FROM invocations ORDER BY rowid DESC LIMIT 1 OFFSET ?)`,
       )
       .get(this.recent - 1) as { id: number | null }
     // Fewer invocations than the window (or none): the whole table is the window.

package/src/orchestrator/hit-restore.ts

@@ -12,6 +12,7 @@ import path from 'node:path'
 import type { CacheConfig } from '../config.js'
 import {
   type CacheEntry,
+  cleanOutputPaths,
   cleanOutputs,
   cleanWorkspaceOutputs,
   resolveOutputs,
@@ -19,7 +20,7 @@ import {
   WORKSPACE_OUTPUT_PREFIX,
 } from '../cache/index.js'
 import type { TaskOutcome } from '../graph/index.js'
-import { span, wholeSubtreePrefixes } from '../util/index.js'
+import { asTrees, span, taskGlob, wholeSubtreePrefixes } from '../util/index.js'
 import type { ExecuteArgs } from './execute-task.js'
 
 export interface RestoreHitArgs {
@@ -56,6 +57,18 @@ export async function restoreHit(restore: RestoreHitArgs): Promise<TaskOutcome>
     nestedProjectDirs: args.nestedProjectDirs,
   }
   const wsCleanArgs = { workspaceRoot: args.workspaceRoot, outputs: wsOutputs }
+  // The two sides of an overlapping pair (item 588). An ADDITIVE task owns
+  // only its recorded rows: its glob also selects the upstream's files it
+  // adds beside, so "no strays" is not a claim it can make, and its clean
+  // takes the rows, never the glob. The UPSTREAM ignores what its
+  // dependants declare they add when it judges its own tree current — an
+  // addition below is not a stray — while its glob clean still takes them:
+  // the dependant restores or runs after it, by the edge.
+  const additive = (node.addsToOutputsOf?.length ?? 0) > 0
+  const addedGlobs = (node.outputsAddedToBy ?? [])
+    .flatMap((g) => asTrees([g]))
+    .map((g) => taskGlob(g))
+  const isAddition = (rel: string): boolean => addedGlobs.some((g) => g.match(rel))
 
   // "Tree is already current" short-circuit — skip cleanOutputs
   // + restoreOutputs when the on-disk state matches what this
@@ -100,6 +113,11 @@ export async function restoreHit(restore: RestoreHitArgs): Promise<TaskOutcome>
         const endDirs = span('output dirs')
         // Loaded with the entry (batched by getMany, or with the lazy get).
         const dirRows = hit.outputDirRows ?? []
+        // Rows are recorded for these same prefixes under this same key
+        // (the outputs are folded into it), so `covers` cannot be false
+        // today — deleting it reddens nothing (item 638). Kept: a row
+        // set that shrank would otherwise vouch for a tree it never saw,
+        // and the failure it would let through is a skipped restore.
         const covers = dirPrefixes.every((pre) => dirRows.some((r) => r.path === pre))
         setKnown = covers && (await args.cache.outputDirsCurrent!(node.projectDir, dirRows))
         endDirs()
@@ -129,13 +147,28 @@ export async function restoreHit(restore: RestoreHitArgs): Promise<TaskOutcome>
         const expSet = new Set(exp.map((e) => e.path))
         return actual.length === expSet.size && actual.every((r) => expSet.has(r))
       }
-      const actualRels = actualAbs.map((p) =>
-        path.relative(node.projectDir, p).split(path.sep).join('/'),
-      )
-      const actualWsRels = actualWsAbs.map((p) =>
-        path.relative(args.workspaceRoot, p).split(path.sep).join('/'),
-      )
-      if (setsMatch(actualRels, projExpected) && setsMatch(actualWsRels, wsExpected)) {
+      // A stray a dependant's glob could have added is not a stray; a path
+      // this entry recorded is never dropped, even where that glob covers
+      // the whole tree (strapi's shape: both on `dist`).
+      const expectedRels = new Set(projExpected.map((e) => e.path))
+      const expectedWsRels = new Set(wsExpected.map((e) => e.path))
+      const actualRels = actualAbs
+        .map((p) => path.relative(node.projectDir, p).split(path.sep).join('/'))
+        .filter((rel) => expectedRels.has(rel) || !isAddition(rel))
+      const actualWsRels = actualWsAbs
+        .map((p) => path.relative(args.workspaceRoot, p).split(path.sep).join('/'))
+        .filter((rel) => expectedWsRels.has(rel) || !isAddition(rel))
+      const rowsPresent = (
+        actual: readonly string[],
+        exp: ReadonlyArray<{ path: string }>,
+      ): boolean => {
+        const have = new Set(actual)
+        return exp.every((e) => have.has(e.path))
+      }
+      const treeMatches = additive
+        ? rowsPresent(actualRels, projExpected) && rowsPresent(actualWsRels, wsExpected)
+        : setsMatch(actualRels, projExpected) && setsMatch(actualWsRels, wsExpected)
+      if (treeMatches) {
         const endStat = span('output stat')
         skipRestore =
           (await args.cache.isOutputsCurrent(node.projectDir, projExpected)) &&
@@ -150,25 +183,56 @@ export async function restoreHit(restore: RestoreHitArgs): Promise<TaskOutcome>
       }
     }
   }
+  // An entry with NO rows (its declared outputs matched nothing at save
+  // time, the warned case) is current exactly when the globs still match
+  // nothing: then the empty artifact has nothing to put back and the read
+  // of the tar is spared. A stray under the glob still falls through to
+  // the clean, as strict ownership requires (item 589).
+  if (anyOutputs && !skipRestore) {
+    const expected = hit.outputRows ?? args.cache.loadOutputFilesBatch([hash]).get(hash) ?? []
+    if (expected.length === 0) {
+      const endGlob = span('output glob')
+      const actual = await resolveOutputs({
+        projectDir: node.projectDir,
+        outputs,
+        nestedProjectDirs: args.nestedProjectDirs,
+      })
+      const actualWs = await resolveWorkspaceOutputs({
+        workspaceRoot: args.workspaceRoot,
+        outputs: wsOutputs,
+      })
+      endGlob()
+      skipRestore = actual.length === 0 && actualWs.length === 0
+    }
+  }
   if (!skipRestore) {
     let cleanedRels: string[] = []
     let cleanedWsRels: string[] = []
-    if (outputs.length > 0) cleanedRels = await cleanOutputs(cleanArgs)
-    if (wsOutputs.length > 0) cleanedWsRels = await cleanWorkspaceOutputs(wsCleanArgs)
+    if (additive) {
+      cleanedRels = hit.outputFiles.filter((p) => !p.startsWith(WORKSPACE_OUTPUT_PREFIX))
+      await cleanOutputPaths({ projectDir: node.projectDir, rels: cleanedRels })
+      cleanedWsRels = hit.outputFiles
+        .filter((p) => p.startsWith(WORKSPACE_OUTPUT_PREFIX))
+        .map((p) => p.slice(WORKSPACE_OUTPUT_PREFIX.length))
+      await cleanOutputPaths({ projectDir: args.workspaceRoot, rels: cleanedWsRels })
+    } else {
+      if (outputs.length > 0) cleanedRels = await cleanOutputs(cleanArgs)
+      if (wsOutputs.length > 0) cleanedWsRels = await cleanWorkspaceOutputs(wsCleanArgs)
+    }
     await args.cache.restoreOutputs(hash, node.projectDir, args.workspaceRoot)
+    // The tree now holds this entry's bytes: stamp them for the next hit
+    // (item 886).
+    args.cache.recordOutputStamps?.(hash, node.projectDir, args.workspaceRoot)
     // The directory snapshot behind the NEXT hit's skip-restore, taken at
-    // run end when the run keeps a list (as the miss path does, see
+    // run end from the run's list (as the miss path does, see
     // miss-save.ts): the restore renamed into these directories
     // microseconds ago, inside the snapshot's racy window, so a snapshot
     // taken here was refused and the first warm run after every restore
     // walked its output trees — 41 of payload's 45 tasks, 14,430 files,
-    // ~75 ms of the no-op's CPU (2026-09-11).
-    if (dirPrefixes !== null) {
-      if (args.outputDirSnapshots !== undefined) {
-        args.outputDirSnapshots.push({ hash, projectDir: node.projectDir, prefixes: dirPrefixes })
-      } else {
-        await args.cache.recordOutputDirs?.(hash, node.projectDir, dirPrefixes)
-      }
+    // ~75 ms of the no-op's CPU (2026-09-11). A caller with no list gets
+    // no snapshot (item 637: recording here was that same refusal).
+    if (dirPrefixes !== null && args.outputDirSnapshots !== undefined) {
+      args.outputDirSnapshots.push({ hash, projectDir: node.projectDir, prefixes: dirPrefixes })
     }
     // Restored outputs changed the project's tree — but on this
     // path we know the EXACT changed paths (wiped declared

package/src/orchestrator/index.ts

@@ -11,11 +11,16 @@ export {
   type LoadProjectsArgs,
 } from './projects.js'
 export { computeTaskHash, createHashCache, type HashCache } from './task-hash.js'
-export type { RunOptions, RunSummary } from './options.js'
+export type { HeldPersistent, RunOptions, RunSummary } from './options.js'
 // Re-surface the cache policy contract (defined in the cache module) so
 // embedders constructing RunOptions.cache and the package façade can
 // reach it without importing the cache module directly.
 export { type CachePolicy, FULL_CACHE_POLICY, parseCachePolicy } from '../cache/index.js'
+// The CLI reads a recorded exit code; the runner's convention decodes it.
+export { exitSignal } from '../exec/index.js'
+export { forwardedSignal } from './signals.js'
+// `vx cache prune` waits for a run on the workspace before it evicts.
+export { acquireRunLock } from './run-lock.js'
 export { defaultLogger, resolveOutputView } from './logger.js'
 export type { Logger, OutputView } from './logger.js'
 export type { RunPlan, PlannedTask, PlanPrediction, CacheStatus } from './plan.js'
@@ -138,6 +143,7 @@ export {
   explainCacheKey as explainCacheKeyQuery,
   getInvocation,
   getRun,
+  latestRunId,
   listInvocations,
   listRuns,
   whyDidThisRerun as whyDidThisRerunQuery,

package/src/orchestrator/keyed-projects.ts

@@ -0,0 +1,89 @@
+// The projects a task's cache key answers for: K(T) in
+// docs/design/linked-sibling-reads-2026-09.md. A sandboxed task that
+// declares `cache` is granted a sibling's `node_modules` link only when its
+// key already moves with that sibling's files, and this is where "already"
+// is decided — on the graph, before any hash exists, through the same
+// selection the hash path applies (`selectFoldedDeps`).
+
+import { isGroupTask, type TaskNode } from '../graph/index.js'
+import { selectFoldedDeps, type FoldCandidate } from './upstream.js'
+
+/**
+ * A run's keyed-set lookup: for a task, the directories of every project
+ * holding an exec task whose key the task's key folds, transitively. The
+ * task itself is not counted.
+ *
+ * The fold relation is the hash path's, computed on the graph:
+ *   - an exec task folds its dependencies as its own `cache.inputs.tasks`
+ *     selects them (absent, or no `cache` at all, means all);
+ *   - a group folds every dependency (`computeGroupHash`) and folds no
+ *     files of its own;
+ *   - a persistent task has no hash on the live path, so it is folded by
+ *     no one and its own dependencies reach no key through it. (The local
+ *     classify pass does give it one — stable-keys.ts — so a key there can
+ *     move with more than this set names; never with less.)
+ *
+ * Every exec task reached contributes its project, cached or not: a key
+ * folds the task's own project files, and a task with no `cache` declares
+ * no `inputs.files`, so it folds every file of its project (inputs.ts's
+ * `DEFAULT_FILE_GLOBS`). `tests/keyed-projects.test.ts` holds that to the
+ * key itself.
+ *
+ * Lazy and memoized by task id: only a sandboxed task that executes asks,
+ * so a run of hits walks nothing, and a shared subgraph is walked once.
+ */
+export function keyedProjects(
+  nodes: ReadonlyMap<string, TaskNode>,
+): (node: TaskNode) => ReadonlySet<string> {
+  const below = new Map<string, ReadonlySet<string>>()
+  // Post-order on an explicit stack: a fold is as deep as the graph, and a
+  // recursion per edge threw `RangeError` at the 50,000 the builder takes
+  // (item 737). A frame's folded dependencies are listed when it is first
+  // reached and combined once each has its set.
+  return (root) => {
+    const stack: Array<[node: TaskNode, deps: FoldCandidate[] | undefined]> = [[root, undefined]]
+    while (stack.length > 0) {
+      const frame = stack[stack.length - 1]!
+      const [node, deps] = frame
+      if (below.has(node.id)) {
+        stack.pop()
+        continue
+      }
+      if (deps === undefined) {
+        frame[1] = folded(node, nodes)
+        for (const { node: dep } of frame[1]) if (!below.has(dep.id)) stack.push([dep, undefined])
+        continue
+      }
+      stack.pop()
+      const out = new Set<string>()
+      for (const { node: dep } of deps) {
+        if (!isGroupTask(dep)) out.add(dep.projectDir)
+        for (const dir of below.get(dep.id)!) out.add(dir)
+      }
+      below.set(node.id, out)
+    }
+    return below.get(root.id)!
+  }
+}
+
+/** The dependencies `node`'s key folds, per the hash path's rules above. */
+function folded(node: TaskNode, nodes: ReadonlyMap<string, TaskNode>): FoldCandidate[] {
+  const candidates: FoldCandidate[] = []
+  for (const id of node.deps) {
+    const dep = nodes.get(id)!
+    if (dep.config.exec?.persistent !== undefined) continue
+    candidates.push({ node: dep, unit: foldUnit(dep) })
+  }
+  if (isGroupTask(node)) return candidates
+  return selectFoldedDeps(candidates, node.config.cache?.inputs?.tasks, node.projectName, node.id)
+}
+
+/**
+ * What stands in for a dependency's hash in the dedup: equal exactly when
+ * the hashes are. An exec task's key folds its own id (`task:<id>`), so its
+ * id is enough; a group's hash is a roll-up of its members' ids and hashes
+ * with no id of its own, so two groups over the same members hash alike.
+ */
+function foldUnit(node: TaskNode): string {
+  return isGroupTask(node) ? `group|${[...node.deps].sort().join('|')}` : `task|${node.id}`
+}