@vzn/vx 0.0.645 → 0.0.648

package/src/history/metrics.ts

@@ -44,6 +44,12 @@ export interface RunSummaryRow {
   hash: string
   cpuMs: number | null
   peakRssBytes: number | null
+  /** The most cores one sampling interval burned (v43); null when nothing sampled. */
+  peakCores: number | null
+  /** The mean resident memory over the samples, in bytes (v43); null when nothing sampled. */
+  avgRssBytes: number | null
+  /** Where an executor ran it (`small#1`, v44); null = here. */
+  placement: string | null
   // High-precision spans relative to run start. Decimal strings on the wire
   // (bigints aren't JSON-safe); use BigInt or Number on the client.
   wallclockStartNs: string | null
@@ -57,6 +63,8 @@ export interface RunSummaryRow {
   forwarded: boolean
   /** Each remote read or write of its key that failed, `upload: <message>`, `; `-joined (v40). */
   remoteError: string | null
+  /** The attempts a retried task took (>1, v23); null when it ran once. */
+  attempts: number | null
 }
 
 export interface ListRunsArgs {
@@ -114,10 +122,11 @@ export function listRuns(db: Database, args: ListRunsArgs = {}): RunSummaryRow[]
               duration_ms AS durationMs, started_at AS startedAt, ended_at AS endedAt,
               cache_hit AS cacheHit, restored, cached, hash,
               cpu_ms AS cpuMs, peak_rss_bytes AS peakRssBytes,
+              peak_cores AS peakCores, avg_rss_bytes AS avgRssBytes, placement,
               wallclock_start_ns AS wallclockStartNs, wallclock_end_ns AS wallclockEndNs,
               blocked_by AS blockedBy, timed_out AS timedOut,
               sandbox_violations AS sandboxViolations, not_ready AS notReady,
-              forward_args IS NOT NULL AS forwarded, remote_error AS remoteError
+              forward_args IS NOT NULL AS forwarded, remote_error AS remoteError, attempts
        FROM runs ${clause} ORDER BY id DESC LIMIT ?`,
     )
     .all(...params, limit) as RawRow[]
@@ -285,7 +294,9 @@ export interface RunDetail {
 }
 
 export function getRun(db: Database, runId: string): RunDetail | null {
-  const tasks = listRuns(db, { runId, limit: 100_000 })
+  // In the order the run recorded them, as it printed them: `listRuns` is
+  // newest first, and the replay listed a dependency below its dependant.
+  const tasks = listRuns(db, { runId, limit: 100_000 }).reverse()
   if (tasks.length === 0) return null
   const startedAt = Math.min(...tasks.map((t) => t.startedAt))
   const endedAt = Math.max(...tasks.map((t) => t.endedAt))
@@ -378,6 +389,18 @@ export interface WhyDidThisRerun {
   note: string
 }
 
+/**
+ * Failed tasks in a run that wrote the cache: a passing task beside one
+ * ran past a failed dependency (--continue) and was never saved.
+ */
+function failedWithWrites(db: Database, id: string | null): number {
+  if (id === null) return 0
+  const row = db
+    .query('SELECT cache_policy AS p, failed_count AS f FROM invocations WHERE run_id = ?')
+    .get(id) as { p: string; f: number } | null
+  return row !== null && writesCache(row.p) ? row.f : 0
+}
+
 /**
  * The endings an UNCHANGED cache key can have. A re-execution is told apart
  * by the evidence the index holds: every one used to blame `--no-cache` /
@@ -389,7 +412,7 @@ function unchangedKeyNote(
   db: Database,
   runId: string,
   this_: { hash: string; status: string; cacheHit: number | null; startedAt: number },
-  prev: { status: string; cacheHit: number | null; runId: string | null },
+  prev: { status: string; cacheHit: number | null; runId: string | null; blockedBy: string | null },
 ): string {
   if (this_.cacheHit === null) {
     return 'cache key unchanged — this run recorded no cache outcome, so whether it re-ran is unknown'
@@ -403,8 +426,12 @@ function unchangedKeyNote(
       p: string
     } | null
   )?.p
+  // `--no-cache` reads and writes nothing, `--force` writes: each named
+  // apart, or a `--no-cache` run was told it had passed `--force`.
   if (policy !== undefined && !readsCache(policy)) {
-    return 'cache key unchanged — re-executed because this run did not read the cache (--force, or a --cache-policy without read)'
+    return writesCache(policy)
+      ? 'cache key unchanged — re-executed because this run did not read the cache (--force, or a --cache-policy without read)'
+      : 'cache key unchanged — re-executed because this run did not use the cache (--no-cache, or a --cache-policy without read or write)'
   }
   // `get` answers null, not undefined, for no row.
   const createdAt = (
@@ -424,17 +451,9 @@ function unchangedKeyNote(
     prev.status === 'success' &&
     prev.cacheHit === 0
   ) {
-    const failedWithWrites = (id: string | null): number => {
-      if (id === null) return 0
-      const row = db
-        .query('SELECT cache_policy AS p, failed_count AS f FROM invocations WHERE run_id = ?')
-        .get(id) as { p: string; f: number } | null
-      const writes = row !== null && writesCache(row.p)
-      return writes ? (row?.f ?? 0) : 0
-    }
-    const before = failedWithWrites(prev.runId)
+    const before = failedWithWrites(db, prev.runId)
     if (before > 0) {
-      const now = failedWithWrites(runId)
+      const now = failedWithWrites(db, runId)
       if (createdAt === undefined && now > 0) {
         return `cache key unchanged — neither run saved it: each ran beside a failed task (${now} failed in this one), and a task run past a failed dependency (--continue) is never cached`
       }
@@ -466,6 +485,18 @@ function unchangedKeyNote(
     if (prevPolicy !== undefined && !writesCache(prevPolicy)) {
       return 'cache key unchanged — the previous run on this key did not write the cache (--no-cache, or a --cache-policy without write), so there was nothing to hit'
     }
+    // A task that passed behind a dependency its run never recorded: the
+    // one `--exclude-dependencies` left out, keyed but not run, so nothing
+    // built on it was saved (excluded-keys.ts).
+    if (
+      prev.blockedBy !== null &&
+      prev.runId !== null &&
+      db
+        .query('SELECT 1 FROM runs WHERE run_id = ? AND project = ? AND task = ?')
+        .get(prev.runId, ...splitTaskId(prev.blockedBy)) === null
+    ) {
+      return `cache key unchanged — the previous run on this key built on a dependency it left out (${prev.blockedBy}, --exclude-dependencies), so it saved nothing and there was nothing to hit`
+    }
     return 'cache key unchanged — the previous run on this key executed but no entry for it is in the cache (its save failed, or it was pruned since), so there was nothing to hit'
   }
   return 'cache key unchanged — re-executed on the same key though this run read the cache; vx cannot name the cause'
@@ -486,11 +517,19 @@ export function latestRunId(db: Database, taskId: string): string | null {
   return row?.runId ?? null
 }
 
+/** Why a key that folds a task with no `inputs` never hits, and the fix. */
+function keylessNote(taskId: string, keylessBy: string): string {
+  return keylessBy === taskId
+    ? 'never cached: this task declares no `inputs`, so each run derives a new key; declare its `inputs`'
+    : `never cached: its key includes ${keylessBy}, which declares no \`inputs\`, so each run derives a new key; declare inputs on ${keylessBy}`
+}
+
 export function whyDidThisRerun(db: Database, runId: string, taskId: string): WhyDidThisRerun {
   const [project, task] = splitTaskId(taskId)
   const this_ = db
     .query(
-      `SELECT id, hash, status, cache_hit AS cacheHit, restored, cached, started_at AS startedAt
+      `SELECT id, hash, status, cache_hit AS cacheHit, restored, cached, started_at AS startedAt,
+              keyless_by AS keylessBy
        FROM runs WHERE run_id = ? AND project = ? AND task = ?`,
     )
     .get(runId, project, task) as
@@ -502,6 +541,7 @@ export function whyDidThisRerun(db: Database, runId: string, taskId: string): Wh
         restored: number | null
         cached: number | null
         startedAt: number
+        keylessBy: string | null
       }
     | undefined
   if (!this_) {
@@ -519,7 +559,7 @@ export function whyDidThisRerun(db: Database, runId: string, taskId: string): Wh
   const prev = db
     .query(
       `SELECT hash, status, cache_hit AS cacheHit, restored, started_at AS startedAt,
-              run_id AS runId
+              run_id AS runId, blocked_by AS blockedBy
        FROM runs WHERE project = ? AND task = ? AND id < ? AND ${KEYED_RUNS_SQL}
        ORDER BY id DESC LIMIT 1`,
     )
@@ -531,6 +571,7 @@ export function whyDidThisRerun(db: Database, runId: string, taskId: string): Wh
         restored: number | null
         startedAt: number
         runId: string | null
+        blockedBy: string | null
       }
     | undefined
   // …and this run must have one too, or there is nothing to compare.
@@ -561,19 +602,27 @@ export function whyDidThisRerun(db: Database, runId: string, taskId: string): Wh
       ? 'this task recorded no cache key (skipped, or a persistent task) — nothing to compare'
       : this_.cached === 0
         ? // Not a cache decision at all: the task runs every time by design,
-          // and its key is derived only so dependents can fold it.
-          'this task declares no `cache` block — it runs on every invocation; its key is folded by dependents only'
-        : prev && prev.hash !== this_.hash
-          ? 'cache key changed between the previous run and this one (inputs differ)'
-          : prev
-            ? // An unchanged key has two very different endings, and calling
-              // both a "re-run" answered the question wrong: a cache HIT did not
-              // re-run at all, so blaming `--no-cache` named a cause that cannot
-              // have applied. Only a run that EXECUTED on an unchanged key is
-              // the case this verb exists to explain. A row with no recorded
-              // cacheHit (older rows) is neither — say that, do not guess.
-              unchangedKeyNote(db, runId, this_, prev)
-            : 'no prior run for this (project, task)',
+          // and its key is derived only so dependents can fold it. A keyless
+          // one's is new each run, so every dependent misses: "folded by
+          // dependents" read as if they could hit.
+          this_.keylessBy === null
+          ? 'this task declares no `cache` block — it runs on every invocation; its key is folded by dependents only'
+          : this_.keylessBy === taskId
+            ? 'this task declares no `cache` block — it runs on every invocation; it declares no `inputs` either, so each run derives a new key and every task that depends on it misses; declare its `inputs`'
+            : `this task declares no \`cache\` block — it runs on every invocation; its key includes ${this_.keylessBy}, which declares no \`inputs\`, so each run derives a new key and every task that depends on it misses; declare inputs on ${this_.keylessBy}`
+        : this_.keylessBy !== null
+          ? keylessNote(taskId, this_.keylessBy)
+          : prev && prev.hash !== this_.hash
+            ? 'cache key changed between the previous run and this one (inputs differ)'
+            : prev
+              ? // An unchanged key has two very different endings, and calling
+                // both a "re-run" answered the question wrong: a cache HIT did not
+                // re-run at all, so blaming `--no-cache` named a cause that cannot
+                // have applied. Only a run that EXECUTED on an unchanged key is
+                // the case this verb exists to explain. A row with no recorded
+                // cacheHit (older rows) is neither — say that, do not guess.
+                unchangedKeyNote(db, runId, this_, prev)
+              : 'no prior run for this (project, task)',
   }
 }
 
@@ -617,7 +666,7 @@ export function loadEntryInputs(db: Database, entryHash: string): TaskInputCompo
 }
 
 /**
- * The rule `vx why` and the site's playground both name a moved key by: join
+ * The rule `vx why` names a moved key by: join
  * two keys' components over `(kind, name)`. A component in both with a
  * different hash is `changed`, one only in `after` is `added`, one only in
  * `before` is `removed`, and an equal one is counted. Entries are ordered by
@@ -659,8 +708,7 @@ export function diffKeyComponents(
     }
   }
   // Code-unit order, not `localeCompare`: collation follows the machine's
-  // locale, and the playground runs this same join in the reader's browser,
-  // so the CLI and the page could list one diff in two orders. Code units
+  // locale, so two machines could list one diff in two orders. Code units
   // are also SQLite's BINARY order, the `entry_inputs` scan's own.
   const byCodeUnit = (a: string, b: string): number => (a < b ? -1 : a > b ? 1 : 0)
   entries.sort((x, y) => byCodeUnit(x.kind, y.kind) || byCodeUnit(x.name, y.name))
@@ -688,10 +736,17 @@ export function cacheKeyDiff(db: Database, runId: string, taskId: string): Cache
   const [project, task] = splitTaskId(taskId)
   const this_ = db
     .query(
-      'SELECT id, hash, cached, status, started_at AS startedAt FROM runs WHERE run_id = ? AND project = ? AND task = ?',
+      'SELECT id, hash, cached, status, started_at AS startedAt, keyless_by AS keylessBy FROM runs WHERE run_id = ? AND project = ? AND task = ?',
     )
     .get(runId, project, task) as
-    | { id: number; hash: string; cached: number | null; status: string; startedAt: number }
+    | {
+        id: number
+        hash: string
+        cached: number | null
+        status: string
+        startedAt: number
+        keylessBy: string | null
+      }
     | undefined
   if (!this_) {
     return {
@@ -720,6 +775,18 @@ export function cacheKeyDiff(db: Database, runId: string, taskId: string): Cache
     }
   }
 
+  if (this_.keylessBy !== null) {
+    return {
+      runId,
+      taskId,
+      found: true,
+      previousRunId: null,
+      entries: [],
+      unchangedCount: 0,
+      note: `${this_.keylessBy} declares no \`inputs\`, so no fingerprints are kept to diff`,
+    }
+  }
+
   const prev = db
     .query(
       `SELECT run_id AS runId, hash, status FROM runs
@@ -760,7 +827,9 @@ export function cacheKeyDiff(db: Database, runId: string, taskId: string): Cache
   // A failed previous run kept no fingerprints; the last run that saved an
   // entry still names what moved since then (the edit an agent made to fix
   // the failure, or the one that broke it).
-  if (cur.length > 0 && old.length === 0 && !isPassStatus(prev.status)) {
+  // So did one that passed beside a failed task (--continue).
+  const tainted = isPassStatus(prev.status) && failedWithWrites(db, prev.runId) > 0
+  if (cur.length > 0 && old.length === 0 && (!isPassStatus(prev.status) || tainted)) {
     const saved = db
       .query(
         `SELECT run_id AS runId, hash FROM runs
@@ -771,7 +840,7 @@ export function cacheKeyDiff(db: Database, runId: string, taskId: string): Cache
       .get(project, task, this_.id) as { runId: string | null; hash: string } | undefined
     if (saved) {
       const { entries, unchangedCount } = diffKeyComponents(loadEntryInputs(db, saved.hash), cur)
-      const since = `run ${saved.runId}, the last that saved an entry (the previous run ended ${prev.status})`
+      const since = `run ${saved.runId}, the last that saved an entry (${tainted ? 'the previous run ran beside a failed task, so it was not saved' : `the previous run ended ${prev.status}`})`
       return {
         runId,
         taskId,
@@ -798,7 +867,9 @@ export function cacheKeyDiff(db: Database, runId: string, taskId: string): Cache
         ? `this run ended ${this_.status}`
         : old.length === 0 && !isPassStatus(prev.status)
           ? `the previous run ended ${prev.status}`
-          : null
+          : old.length === 0 && tainted
+            ? 'the previous run ran beside a failed task'
+            : null
     return {
       runId,
       taskId,
@@ -809,8 +880,8 @@ export function cacheKeyDiff(db: Database, runId: string, taskId: string): Cache
       note:
         this_.cached === 0
           ? // The verdict already says the task is uncached; this line says
-            // what moved a key that declares nothing.
-            'no `cache` block declares its inputs, so its key folds every file in its project — a file it wrote, or any untracked file, moves it — and no fingerprints are kept to say which'
+            // why no input can be named.
+            'with no `cache` block it saves no entry, so no input fingerprints are kept to say which of its `inputs` moved its key; with no `inputs`, every run gives it a new key'
           : unsaved !== null
             ? `cache key changed but input fingerprints are unavailable — ${unsaved} and saved no entry; only the key change is known`
             : 'cache key changed but input fingerprints are unavailable — the entry was pruned (or the row predates the `cached` column); only the key change is known',
@@ -833,6 +904,18 @@ export function cacheKeyDiff(db: Database, runId: string, taskId: string): Cache
   }
 }
 
+/**
+ * Joins a group and a task under it in an `upstream` row's name: a group
+ * records no run, so its dependant's key names its members through it.
+ */
+export const GROUP_VIA = ' \u2190 '
+
+/** The task an `upstream` row names: the last one, past any group it came through. */
+export function upstreamTask(name: string): string {
+  const i = name.lastIndexOf(GROUP_VIA)
+  return i < 0 ? name : name.slice(i + GROUP_VIA.length)
+}
+
 export interface RootCause {
   /** From the asked task down to the one whose own inputs moved. */
   chain: string[]
@@ -842,23 +925,37 @@ export interface RootCause {
 /**
  * The tasks under `taskId`'s moved upstreams whose OWN key components
  * moved in the same run, each with the chain that carried it up. A task
- * visited once is not walked again (a diamond names its root once).
+ * visited once is not walked again (a diamond names its root once). A
+ * group records no run, so `groups` (group id → the tasks it gathers)
+ * carries the walk through it.
  */
 export function rootCauses(
   db: Database,
   runId: string,
   taskId: string,
   entries: CacheKeyDiff['entries'],
+  groups: ReadonlyMap<string, readonly string[]> = new Map(),
 ): RootCause[] {
   const roots: RootCause[] = []
   const seen = new Set([taskId])
   const walk = (chain: string[], moved: CacheKeyDiff['entries']): void => {
     for (const e of moved) {
-      if (e.kind !== 'upstream' || seen.has(e.name)) continue
-      seen.add(e.name)
-      const next = [...chain, e.name]
-      const d = cacheKeyDiff(db, runId, e.name)
-      if (!d.found) continue
+      if (e.kind !== 'upstream') continue
+      const task = upstreamTask(e.name)
+      if (seen.has(task)) continue
+      seen.add(task)
+      const next = [...chain, ...e.name.split(GROUP_VIA)]
+      const d = cacheKeyDiff(db, runId, task)
+      // A group: its members carry the walk, named in the key through it
+      // (`group ← task`) or, in a row that names the group alone, by the graph.
+      if (!d.found) {
+        const members = groups.get(task) ?? []
+        walk(
+          next,
+          members.map((name) => ({ ...e, name })),
+        )
+        continue
+      }
       const own = d.entries.filter((x) => x.kind !== 'upstream')
       if (own.length > 0) roots.push({ chain: next, entries: own })
       walk(next, d.entries)

package/src/index.ts

@@ -16,13 +16,18 @@ export { UserError, isUserError } from './util/index.js'
 export { PLUGIN_HOOKS, type PluginHook } from './config.js'
 // The machine as this process may use it — cores and memory capped by the
 // cgroup a container runs under. Core's default worker count reads the
-// first; a policy that budgets memory (`@vzn/vx-schedule-history`) reads
+// first; a policy that budgets memory (`@vzn/vx-history`) reads
 // the second, so the cgroup walk has one implementation.
 export { machineMemoryBytes, machineParallelism } from './util/index.js'
 // How core reads a task glob — its spelling, and which characters are
 // wildcards (`[` `]` and an escape are) — for a plugin that turns declared
 // outputs into something else (`@vzn/vx-reapi`'s literal `output_paths`).
-export { isLiteralPattern, normalizeGlob, restorableOutput } from './util/index.js'
+export {
+  isLiteralPattern,
+  normalizeGlob,
+  outputDirPrefixes,
+  restorableOutput,
+} from './util/index.js'
 
 // Schema types and helpers (used by user vx.config files and presets).
 export type {
@@ -43,10 +48,13 @@ export type {
   SandboxConfig,
   SandboxGrants,
   SandboxDenials,
+  Platform,
 } from './config.js'
-export { defineProject, defineWorkspace } from './config.js'
+export { defineProject, defineWorkspace, PLATFORMS } from './config.js'
 export { definePlugin, refuseUnknownOptions } from './orchestrator/index.js'
 export { branchCacheScope } from './workspace/index.js'
+// A plugin reading the base branch's history: a shallow clone fetches it.
+export { mergeBaseWith } from './workspace/index.js'
 
 // Programmatic engine API: run / plan / prepare (docs/cli.md § Programmatic
 // API). The graph primitives, the cache-key hashing seam and the git / host
@@ -55,7 +63,7 @@ export { branchCacheScope } from './workspace/index.js'
 // consumer is re-added when one appears, shaped by its use.
 export { run, planRun, prepareRun } from './orchestrator/index.js'
 // The per-task duration history a `schedule` plugin learns from
-// (`@vzn/vx-schedule-history` does; a plugin package reaches core only
+// (`@vzn/vx-history` does; a plugin package reaches core only
 // through this façade, which is what put these here).
 export { currentBranch } from './orchestrator/index.js'
 export { LocalHistoryProvider } from './history/index.js'
@@ -75,7 +83,7 @@ export type { Logger, OutputView } from './report/index.js'
 // with only `taskId()` to JOIN an id and nothing exported to SPLIT one,
 // consumers roll their own `split('#', 2)` and drift from the graph, which
 // splits on the FIRST '#'.
-export { outputsOverlap, splitTaskId } from './graph/index.js'
+export { criticalPath, outputsOverlap, splitTaskId, taskDefinitions } from './graph/index.js'
 export type { TaskNode, TaskOutcome, TaskStatus } from './graph/index.js'
 
 // Cache classes + the layer interface (the `cache` capability's currency).
@@ -84,14 +92,16 @@ export type {
   CacheLayer,
   PluginCache,
   ArtifactInfo,
+  LentAccess,
   RemoteCacheLayer,
   RemoteOpenContext,
   RunRecord,
   InvocationRecord,
 } from './cache/index.js'
-// A plugin's keychain (`ctx.secret` on `setup` and a remote's `open`), and
-// the guard that tells a missing secret from a fault.
-export { isSecretUnavailable } from './util/index.js'
+// A plugin's keychain (`ctx.secret` on `setup` and a remote's `open`), the
+// guard that tells a missing secret from a fault, and the names whose values
+// vx masks, for a plugin that must not send one where it is shown.
+export { isSecretUnavailable, secretNamed } from './util/index.js'
 export type {
   PluginSecrets,
   SecretRequest,
@@ -110,7 +120,7 @@ export { loadProjectConfig } from './workspace/index.js'
 export type { ProjectMeta } from './workspace/index.js'
 // The run path's RESOLVED view — plugin `config` and `project` stages
 // applied — for a reader outside the CLI
-// (`@vzn/vx-schedule-history`, an embedder's task catalog). What `vx show`
+// (`@vzn/vx-history`, an embedder's task catalog). What `vx show`
 // prints.
 export { loadResolvedProjects } from './orchestrator/index.js'
 export type { ProjectEntry } from './workspace/index.js'
@@ -121,6 +131,7 @@ export type { ProjectEntry } from './workspace/index.js'
 export {
   applyMigration,
   foldScriptHooks,
+  isStarterConfig,
   PERSISTENT_TODO,
   pruneOrphanPersistentNotes,
   quoteTsLiteral,
@@ -163,6 +174,10 @@ export type {
   ExecutorContext,
   OutputContext,
   CommandContext,
+  ArtifactRun,
+  ArtifactTask,
+  CacheFacts,
+  TaskArtifacts,
   FingerprintChange,
   FingerprintClaim,
   FingerprintContext,
@@ -190,18 +205,35 @@ export type { RunStartInfo } from './report/index.js'
 // speaks a wire — and a seam with no consumer is a special case in waiting.)
 // A remote executor gives a task back to the local floor by rejecting with
 // this (B-100): core runs it here and says why once.
-export { executorFallback } from './exec/index.js'
+export { executorFallback, hostPlatform, sampleTrees, type TreeUsage } from './exec/index.js'
 // How the local executor puts the args after `--` on a command, for an
 // executor that runs `ExecuteRequest.command` itself: `@vzn/vx-reapi` and
 // the `vx init --plugin executor` example each joined their own, and a
 // trailing comment or a template literal's closing newline lost the args
 // there while the local floor kept them (X-112).
 export { withForwardArgs } from './exec/index.js'
+// The `npm_execpath` core gives a local task: a `@vzn/vx-dte` worker gives
+// its tasks the same, its own machine's, not what launched it.
+export { packageManagerPath } from './exec/index.js'
+// A task's output both streams in the order written, bounded as core's
+// capture is: what a worker saves through `TaskArtifacts` (`@vzn/vx-dte`).
+export { BoundedCapture, type CapturedChunk } from './exec/index.js'
+// Core's local executor, sandbox included, for a plugin that runs tasks
+// itself: `@vzn/vx-dte`'s orchestrator and its workers.
+export { localFloor, type LocalFloor } from './orchestrator/index.js'
+// A task's sandbox request built where a worker runs it: the paths and the
+// walls are that machine's (`@vzn/vx-dte`, an orchestrator of another OS).
+// Its sweep takes back each placeholder the task never wrote, as core does.
+export { sandboxRequestFor, sweepPlaceholders, type SandboxRequest } from './orchestrator/index.js'
+// A runtime probe answered where a `runtime` executor runs the task.
+export { answerRuntime } from './cache/index.js'
 export type {
   ExecuteRequest,
   ExecuteResult,
   ExecuteSandbox,
+  MachineReport,
   ResolvedSandboxConfig,
+  ServerSpec,
   TaskExecutor,
   TaskPlacement,
 } from './exec/index.js'

package/src/orchestrator/admission.ts

@@ -212,12 +212,16 @@ export function admitTasks(
       upstream,
       nestedProjectDirs: nestedDirsByProject.get(node.projectName) ?? [],
     })
-    const existing = inflight.get(hash)
-    if (existing !== undefined) {
-      // Join a sibling already computing this exact task: wait, then
-      // executeTask cache-hits on the artifact it just saved.
+    // Join a sibling already computing this exact task: wait, then
+    // executeTask cache-hits on the artifact it just saved. A sibling that
+    // saved nothing (it failed) leaves this task to run, so the joiners
+    // released together take the barrier in turn: each returning straight
+    // to executeTask ran the task side by side in one directory.
+    let joined = false
+    for (let existing = inflight.get(hash); existing !== undefined;) {
+      joined = true
       await existing.catch(() => {})
-      return executeTask(buildExecuteArgs(node, upstream, false))
+      existing = inflight.get(hash)
     }
     // Become the executor: register a barrier siblings await. get→set has
     // no await between, so registration is atomic — at most one executor
@@ -229,7 +233,7 @@ export function admitTasks(
         release = resolve
       }),
     )
-    const execArgs = buildExecuteArgs(node, upstream)
+    const execArgs = buildExecuteArgs(node, upstream, !joined)
     try {
       // `return await`, deliberately: the finally must run after the task
       // settles, not when its promise is handed back.

package/src/orchestrator/affected-tasks.ts

@@ -1,4 +1,4 @@
-// `--affected` per task (owner, 2026-10-04). The diff seeds the tasks it
+// `--affected` per task (2026-10-04). The diff seeds the tasks it
 // reaches; a requested task runs when its `dependsOn` closure holds one.
 // So a change reaches another project only along a task edge: `web#test`
 // behind `^build` runs when `ui#build` (or what it depends on) is reached,
@@ -26,7 +26,7 @@ import {
 import { applyGraphStage } from './graph-stage.js'
 import { hasHook } from './plugin-host.js'
 import type { VxPlugin } from './plugin.js'
-import { isDefaultBuild } from './projects.js'
+import { isDefaultBuild } from '../graph/index.js'
 
 /** Every file in this set re-keys each of its project's tasks, whatever their inputs. */
 const KEYED_BY_EVERY_TASK: ReadonlySet<string> = new Set(PROJECT_CONFIG_FILENAMES)
@@ -50,8 +50,10 @@ function wholeProjects(
     const keyed = Object.values(projects.get(name)?.config.tasks ?? {}).filter(
       (t) => t.exec !== undefined && t.inputs !== undefined,
     )
+    const links = changes.dirLinksIn?.get(name)
     const unclaimed = (rel: string): boolean =>
-      KEYED_BY_EVERY_TASK.has(rel) || (!byKeys && !keyed.some((t) => declaresInput(t, rel, null)))
+      KEYED_BY_EVERY_TASK.has(rel) ||
+      (!byKeys && !keyed.some((t) => declaresInput(t, rel, null, links?.has(rel))))
     const rel = rels.find(unclaimed)
     if (rel !== undefined) whole.set(name, rel)
   }
@@ -118,7 +120,7 @@ export function affectedRoots(
   // it passes through: a holder's own node is already in `deps`.
   const passesChanged = (n: TaskNode): boolean => {
     for (const raw of n.config.dependsOn ?? []) {
-      const spec = parseDependencySpec(raw)
+      const spec = parseDependencySpec(raw, 'dependsOn')
       if (spec.kind !== 'deps' || spec.negated) continue
       const re = isTaskPattern(spec.task) ? compileTaskPattern(spec.task) : null
       const holds = (name: string): boolean => {
@@ -147,7 +149,9 @@ export function affectedRoots(
     // Asked of every node, not only the changed projects' (the
     // `workspaceFiles` owners): a `graph` hook may have given the glob.
     if (keyed) {
-      const file = changes.changed.find((rel) => declaresInput(task, null, rel))
+      const file = changes.changed.find((rel) =>
+        declaresInput(task, null, rel, changes.dirLinks?.has(rel)),
+      )
       const dir =
         file === undefined
           ? (changes.nested ?? []).find((d) => workspaceFilesReachInto(task, d))
@@ -171,7 +175,8 @@ export function affectedRoots(
       seeds?.set(n.id, inProject(n.projectName, whole.get(n.projectName)))
       return true
     }
-    const rel = rels.find((r) => declaresInput(task, r, null))
+    const links = changes.dirLinksIn?.get(n.projectName)
+    const rel = rels.find((r) => declaresInput(task, r, null, links?.has(r)))
     if (rel === undefined) return false
     if (seeds !== null) seeds.set(n.id, { ...inProject(n.projectName, rel), kind: 'input' })
     return true

package/src/orchestrator/deferred-outputs.ts

@@ -156,6 +156,8 @@ export class DeferredOutputs {
       await this.args.cache.save({
         hash: entry.hash,
         projectDir: producer.projectDir,
+        // As saveMiss: a link is bounded by the workspace, not the project.
+        workspaceRoot: this.args.workspaceRoot,
         outputFiles,
         ...(emptyDirs.length > 0 ? { outputDirs: emptyDirs } : {}),
         entry: entry.entry,