@vzn/vx 0.0.637 → 0.0.638

package/src/orchestrator/plugin-host.ts

@@ -14,6 +14,9 @@ import {
   type CacheLayer,
   type CachePolicy,
   LayeredCache,
+  absentPluginCache,
+  type PluginCache,
+  type PluginCacheRemote,
 } from '../cache/index.js'
 import { localExecutor, type TaskExecutor } from '../exec/index.js'
 import { maskedLine, settleWithin, teardownTimeoutMs, UserError } from '../util/index.js'
@@ -29,6 +32,7 @@ import type {
   KeyHookContext,
   DiscoveredProject,
   ProjectHookContext,
+  RunReport,
   ScheduleHookContext,
   VxPlugin,
   WorkspaceHookContext,
@@ -385,12 +389,14 @@ export async function claimedAffected(
 export async function applyScheduleHooks(
   plugins: readonly VxPlugin[],
   nodes: ReadonlyMap<string, TaskNode>,
-  ctx: ScheduleHookContext,
+  ctx: Omit<ScheduleHookContext, 'cache'>,
+  cacheFor: (plugin: string) => PluginCache = () => absentPluginCache,
 ): Promise<ReadonlyMap<string, number>> {
   const merged = new Map<string, number>()
   for (const plugin of plugins) {
     if (plugin.schedule === undefined) continue
-    const weights = await safe(plugin, 'schedule', () => plugin.schedule!(nodes, ctx))
+    const own = { ...ctx, cache: cacheFor(plugin.name) }
+    const weights = await safe(plugin, 'schedule', () => plugin.schedule!(nodes, own))
     if (weights === undefined) continue
     // Iterating a string destructures its characters into `[id, w]` pairs
     // that match no task — a plugin returning `'fast'` used to be a no-op
@@ -478,6 +484,8 @@ export function buildAdmission(
 export interface CacheHost extends CacheContext {
   readonly localCache: Cache
   readonly policy: CachePolicy
+  /** Filled with each remote and what its policy lets it do, for the plugins' `ctx.cache`. */
+  readonly remotes?: PluginCacheRemote[]
 }
 
 /**
@@ -492,7 +500,7 @@ export async function resolveCache(
   plugins: readonly VxPlugin[],
   host: CacheHost,
 ): Promise<CacheLayer> {
-  const { localCache, policy, ...ctx } = host
+  const { localCache, policy, remotes, ...ctx } = host
   const layers: CacheLayer[] = []
   const owners: string[] = []
   for (const plugin of plugins) {
@@ -515,6 +523,7 @@ export async function resolveCache(
       remoteRead: policy.remoteRead && access?.read !== false,
       remoteWrite: policy.remoteWrite && access?.write !== false,
     }
+    remotes?.push({ remote, read: own.remoteRead, write: own.remoteWrite })
     layers.push(
       new LayeredCache(localCache, remote, {
         policy: own,
@@ -628,12 +637,13 @@ export async function resolveExecutors(
 export async function teardownPlugins(
   plugins: readonly VxPlugin[],
   warn: (message: string) => void,
+  report?: RunReport,
 ): Promise<void> {
   for (const plugin of plugins) {
     if (plugin.teardown === undefined) continue
     const ms = teardownTimeoutMs()
     try {
-      const settled = await settleWithin(Promise.resolve(plugin.teardown()), ms)
+      const settled = await settleWithin(Promise.resolve(plugin.teardown(report)), ms)
       // Same rule as the flush above. A teardown that never settles has left
       // whatever it owns un-released, and the run exits anyway — silence would
       // present that as a clean shutdown.

package/src/orchestrator/plugin.ts

@@ -11,13 +11,19 @@
 import { readFileSync } from 'node:fs'
 import path from 'node:path'
 import { fileURLToPath } from 'node:url'
-import type { Cache, RemoteCacheLayer } from '../cache/index.js'
+import {
+  absentPluginCache,
+  type Cache,
+  type PluginCache,
+  type RemoteCacheLayer,
+} from '../cache/index.js'
 import { PLUGIN_PACKAGE, type ProjectConfig, type WorkspaceConfig } from '../config.js'
 import type { TaskExecutor } from '../exec/index.js'
-import type { TaskNode, TaskOutcome } from '../graph/index.js'
+import type { TaskNode, TaskOutcome, TaskStatus } from '../graph/index.js'
 import { maskedLine, nearest, UserError } from '../util/index.js'
 import type { ProjectMeta } from '../workspace/index.js'
 import type { EventBus, RunStartInfo } from './events.js'
+import type { CiContext } from './run-context.js'
 import type { TelemetryContext, TelemetrySink } from './telemetry.js'
 import type { Logger } from './logger.js'
 
@@ -221,15 +227,51 @@ export interface VxPlugin {
    * Optional one-time setup per run (validate the workspace, open a
    * connection, read a token). Throwing aborts the run with a clean
    * UserError naming the plugin. It is not a guard over the pipeline: the
-   * config, project, cache, graph, key and schedule stages have run by the
-   * time it is called, and a plan (`--dry`, `planRun`) never calls it. It
-   * precedes the executors, the telemetry sinks, admission and the first
-   * task (tests/plugin-e2e.test.ts).
+   * config, project, cache, graph and key stages have run by the time it
+   * is called, and a plan (`--dry`, `planRun`) never calls it. It
+   * precedes the schedule stage, the executors, the telemetry sinks,
+   * admission and the first task (tests/plugin-e2e.test.ts).
    */
   setup?(ctx: PluginSetupContext): void | Promise<void>
 
-  /** Optional teardown at end-of-run (flush a sink, close a socket). Errors are logged, never thrown. */
-  teardown?(): void | Promise<void>
+  /**
+   * Optional teardown at end-of-run (flush a sink, close a socket). Errors
+   * are logged, never thrown. A run that ran to its end passes its
+   * `RunReport`; every other exit (a refused setup, a stop) passes none.
+   */
+  teardown?(run?: RunReport): void | Promise<void>
+}
+
+/**
+ * What a finished run hands each plugin's `teardown`: its facts and every
+ * task, with the names core kept the task's bytes under. Core keeps them
+ * only when a remote takes the run's writes (CI by default): a failed
+ * task's log and the files its outputs left, an uncached task's log. Read
+ * them with `ctx.cache.getRun(name)`. Core keeps no manifest of its own; a
+ * plugin that wants one writes it from here (`ctx.cache.put`).
+ */
+export interface RunReport {
+  /** The `run_id` the run's history rows and telemetry carry. */
+  readonly runId: string
+  /** `HEAD`'s commit, null outside a git worktree. */
+  readonly commit: string | null
+  /** What the CI provider says about this run: provider, run URL, pipeline, job, attempt. */
+  readonly ciRun: CiContext
+  readonly ok: boolean
+  /** Every task the run decided, in completion order; group tasks are left out. */
+  readonly tasks: readonly RunReportTask[]
+}
+
+export interface RunReportTask {
+  readonly id: string
+  readonly status: TaskStatus
+  readonly durationMs: number
+  /** The task's cache key, when one was computed. */
+  readonly key?: string
+  /** Its output (both streams, secrets masked), when core kept it: `ctx.cache.getRun(log)`. */
+  readonly log?: string
+  /** A tar of the files its declared outputs left, when core kept it: `ctx.cache.getRun(outputs)`. */
+  readonly outputs?: string
 }
 
 /** Shared, read-only context every capability factory receives. */
@@ -242,6 +284,12 @@ interface BaseContext {
 
 /** What `setup` receives: the run's lifecycle, observe-only. */
 export interface PluginSetupContext extends BaseContext {
+  /** This plugin's entries in the workspace's cache (`PluginCache`). */
+  readonly cache: PluginCache
+  /** The run is on CI (`CI` set, or a provider core detects). */
+  readonly ci: boolean
+  /** The run's branch (`currentBranch`): `run.branch`, else git's, else the CI provider's. */
+  readonly branch: string | null
   /**
    * Subscribe a lifecycle handler; it leaves with the run. A throw or a
    * rejection warns once and switches the plugin's handlers off for the run.
@@ -271,6 +319,12 @@ export interface CommandContext extends BaseContext {
    * which `vx` a PATH holds.
    */
   readonly vx: readonly string[]
+  /**
+   * This plugin's entries in the workspace's cache, as `setup` reaches them
+   * (`PluginCache`), read-only: the local store, then each remote the
+   * workspace's cache plugins supply, under the run's scope. Opened on first use.
+   */
+  readonly cache: PluginCache
 }
 
 /** `config` runs before the cache dir is known — it may be what the hook changes. */
@@ -327,6 +381,13 @@ export interface ProjectHookContext extends BaseContext {
    * process.
    */
   readonly projects: readonly ProjectMeta[]
+  /**
+   * True when `vx lock` (or `--check`) visits: the one pass that checks the
+   * configs, so the place to report what a plugin's mapping could not say.
+   * A run checks nothing (the lock model), so such a report there repeats
+   * on every run.
+   */
+  readonly lock: boolean
 }
 
 export interface GraphHookContext extends BaseContext {
@@ -386,6 +447,8 @@ export interface ScheduleHookContext extends BaseContext {
   readonly localCache: Cache
   /** The run's branch (`currentBranch`), the timings a forecast reads first: pass it to `LocalHistoryProvider`. */
   readonly branch: string | null
+  /** This plugin's entries in the workspace's cache, as `setup` has them. */
+  readonly cache: PluginCache
 }
 
 /** A `cache` hook's context: the workspace and the run's scope, never the local store or the policy, which core owns. */
@@ -619,6 +682,12 @@ export interface InstallPluginsArgs {
    * `run:status` channel.
    */
   warn?: (message: string) => void
+  /** Each plugin's `ctx.cache`, by plugin name. Default: a cache with no layer. */
+  cache?: (plugin: string) => PluginCache
+  /** Default false. */
+  ci?: boolean
+  /** Default null. */
+  branch?: string | null
 }
 
 /**
@@ -675,6 +744,9 @@ export async function installPlugins(args: InstallPluginsArgs): Promise<() => vo
       workspaceRoot,
       cacheDir,
       warn,
+      cache: args.cache?.(plugin.name) ?? absentPluginCache,
+      ci: args.ci ?? false,
+      branch: args.branch ?? null,
       // A subscription made past the hooks leaves with the run like a
       // hook's does: the bus can outlive the run (`RunOptions.bus`), and
       // one left behind hears every later run on it (item 635).

package/src/orchestrator/prepare.ts

@@ -19,6 +19,12 @@ import {
   parseCachePolicy,
   GitFilesCache,
   LayeredCache,
+  absentPluginCache,
+  pluginCache,
+  putRunEntry,
+  writesRunStore,
+  type PluginCache,
+  type PluginCacheRemote,
   ScopedCache,
   applyGitEnumeration,
   gitPathspecs,
@@ -116,6 +122,13 @@ export interface PreparedRun {
    * Learned on first ask, once per run.
    */
   branch: () => string | null
+  /** Each plugin's `ctx.cache`: the run's local store and remotes, under its policy and scope. */
+  cacheFor: (plugin: string) => PluginCache
+  /**
+   * Keep `bytes` of this run under `name` (run-store.ts); undefined when no
+   * remote takes the run's writes, and so core keeps nothing.
+   */
+  keepRunEntry: ((name: string, bytes: Uint8Array) => Promise<boolean>) | undefined
   nodes: Map<string, TaskNode>
   /**
    * The tasks `--exclude-dependencies` took out of the schedule: keyed as a
@@ -451,6 +464,11 @@ export async function prepareRun(options: RunOptions, log: Logger): Promise<Prep
   // winning prevents double-wrapping when the workspace also declares a
   // cache plugin.
   let cache: CacheLayer
+  const remotes: PluginCacheRemote[] = []
+  if (options.remoteCache) {
+    const { remoteCache } = options
+    remotes.push({ remote: remoteCache, read: policy.remoteRead, write: policy.remoteWrite })
+  }
   try {
     cache = options.remoteCache
       ? new LayeredCache(localCache, options.remoteCache, {
@@ -464,6 +482,7 @@ export async function prepareRun(options: RunOptions, log: Logger): Promise<Prep
           scope: cacheScope,
           localCache,
           policy,
+          remotes,
         })
   } catch (err) {
     // A cache plugin that throws or returns something off-contract is
@@ -509,8 +528,10 @@ export async function prepareRun(options: RunOptions, log: Logger): Promise<Prep
       localCache,
       hasRemoteLayer,
       cachePolicy: policy,
+      keepRunEntry: undefined,
       priorities: () => Promise.resolve(new Map()),
       branch,
+      cacheFor: () => absentPluginCache,
       nodes: new Map(),
       keyOnly: new Map(),
       unresolvedTasks,
@@ -708,16 +729,35 @@ export async function prepareRun(options: RunOptions, log: Logger): Promise<Prep
         })
       }
     }
+    const pluginCaches = new Map<string, PluginCache>()
+    const cacheFor = (plugin: string): PluginCache => {
+      let own = pluginCaches.get(plugin)
+      if (own === undefined) {
+        own = pluginCache(plugin, {
+          db: localCache.dbHandle(),
+          policy,
+          remotes,
+          scope: cacheScope,
+        })
+        pluginCaches.set(plugin, own)
+      }
+      return own
+    }
     let scheduled: Promise<ReadonlyMap<string, number>> | undefined
     const priorities = (): Promise<ReadonlyMap<string, number>> =>
       (scheduled ??= hasHook(plugins, 'schedule')
-        ? applyScheduleHooks(plugins, nodes, {
-            workspaceRoot,
-            cacheDir,
-            warn: (m) => log.status(m),
-            localCache,
-            branch: branch(),
-          })
+        ? applyScheduleHooks(
+            plugins,
+            nodes,
+            {
+              workspaceRoot,
+              cacheDir,
+              warn: (m) => log.status(m),
+              localCache,
+              branch: branch(),
+            },
+            cacheFor,
+          )
         : Promise.resolve(new Map()))
 
     return {
@@ -731,6 +771,10 @@ export async function prepareRun(options: RunOptions, log: Logger): Promise<Prep
       cachePolicy: policy,
       priorities,
       branch,
+      cacheFor,
+      keepRunEntry: writesRunStore(remotes)
+        ? (name, bytes) => putRunEntry(remotes, cacheScope, name, bytes)
+        : undefined,
       nodes,
       keyOnly,
       unresolvedTasks,

package/src/orchestrator/projects.ts

@@ -163,6 +163,8 @@ interface LoadProjectsBase {
    */
   configs: () => Promise<Lockfile>
   warn: (message: string) => void
+  /** `vx lock`'s audit: the `project` stage's `ctx.lock`. */
+  lock?: boolean
   /**
    * Entries a load in this same process already produced with the same
    * cache dir and lock (the CLI's selection pass, which stages every
@@ -323,6 +325,7 @@ export async function loadProjects(args: LoadProjectsArgs): Promise<LoadedProjec
             name: meta.name,
             dir: meta.dir,
             projects: args.projectMetas,
+            lock: args.lock === true,
           },
           (plugin) =>
             validateProjectConfig(

package/src/orchestrator/remote-prefetch.ts

@@ -12,8 +12,9 @@
 // GET per key.
 //
 // HARD SCOPE: this runs ONLY when a remote layer is configured. It
-// NEVER touches the local cache (no local get / no isOutputsCurrent /
-// no stat pass) — it derives keys and probes REMOTE only. Local-only
+// asks the local index only which keys it holds (no local get / no
+// isOutputsCurrent), and probes the remote for the rest: a run the local
+// cache answers makes no remote call (M, 2026-10-15). Local-only
 // runs are byte-identical to before; the caller gates on the layer's
 // own `hasRemote`, so a third-party remote layer gets the overlap too.
 // The two batch-probe hooks are OPTIONAL on the contract: a remote layer
@@ -75,8 +76,11 @@ async function runPrefetch(args: PrefetchArgs): Promise<void> {
   // would 404. When the remote can't batch (`null` — an older remote, reads
   // disabled, or a layer that doesn't implement the hook at all), fall back to
   // prefetching every stable key, exactly as before.
-  let toPrefetch = stableKeys
-  const uniqueHashes = [...new Set(stableKeys.map((k) => k.hash))]
+  const held =
+    (await args.cache.localHasMany?.([...new Set(stableKeys.map((k) => k.hash))])) ?? null
+  let toPrefetch = held === null ? stableKeys : stableKeys.filter((k) => !held.has(k.hash))
+  if (toPrefetch.length === 0) return
+  const uniqueHashes = [...new Set(toPrefetch.map((k) => k.hash))]
   const present = (await args.cache.remoteHasMany?.(uniqueHashes)) ?? null
   if (present !== null) {
     args.cache.markRemoteAbsent?.(uniqueHashes.filter((h) => !present.has(h)))
@@ -85,7 +89,7 @@ async function runPrefetch(args: PrefetchArgs): Promise<void> {
     // economy: deleting it alone GETs nothing extra, deleting both GETs
     // every absent key. What it decides is which hashes the pump asks
     // the layer for, and that is what the row pins (item 643, 645).
-    toPrefetch = stableKeys.filter((k) => present.has(k.hash))
+    toPrefetch = toPrefetch.filter((k) => present.has(k.hash))
     if (toPrefetch.length === 0) return
   }
 

package/src/orchestrator/run-records.ts

@@ -27,7 +27,7 @@ export interface RunRecordsInput {
   ok: boolean
   command: string
   requestedTasks: readonly string[]
-  /** Already compacted (`compactCachePolicy`), the form the header row stores. */
+  /** Already formatted (`formatCachePolicy`), the form the header row stores. */
   cachePolicy: string
   concurrency: number
   flow: InvocationRecord['flow']