@vzn/vx 0.0.636 → 0.0.638

package/src/orchestrator/fingerprint-watch.ts

@@ -1,18 +1,17 @@
-// 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
+// The files the plugins claim (`VxPlugin.fingerprint`) are read once per
+// run, before any task, and every key folds what their claimant takes
+// from them (a lockfile plugin's per-project parts). 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
+// "has a claimed 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, racyWindowMs } from '../cache/index.js'
-import { WORKSPACE_FINGERPRINT_FILES, type WorkspaceFingerprints } from '../workspace/index.js'
 import type { Logger } from './logger.js'
 
 export class FingerprintWatch {
@@ -20,22 +19,26 @@ export class FingerprintWatch {
   private movedFiles: string[] | undefined
   private said = false
 
-  /** `at`: when the run started reading the files (ms since the epoch). */
+  /**
+   * `names`: the claimed files; `read`: the bytes of those that existed;
+   * `at`: when the run started reading them (ms since the epoch).
+   */
   constructor(
     private readonly workspaceRoot: string,
-    private readonly read: WorkspaceFingerprints,
+    readonly names: readonly string[],
+    private readonly read: ReadonlyMap<string, Uint8Array>,
     private readonly at: number,
   ) {}
 
-  /** A task that may rewrite a fingerprinted file (`mayWriteFingerprint`) ran a command. */
+  /** A task that may rewrite a claimed file (`mayWriteFingerprint`) ran a command. */
   wrote(): void {
     this.pending = true
   }
 
   /**
-   * The fingerprinted files that no longer hold what the run read, or
+   * The claimed 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
+   * folded the old bytes. One `stat` per claimed file 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
@@ -46,9 +49,9 @@ export class FingerprintWatch {
     if (this.movedFiles !== undefined || !this.pending) return this.movedFiles
     this.pending = false
     const moved: string[] = []
-    for (const f of WORKSPACE_FINGERPRINT_FILES) {
+    for (const f of this.names) {
       const abs = path.join(this.workspaceRoot, f)
-      const before = this.read.files.get(f)
+      const before = this.read.get(f)
       let ctimeMs: number
       try {
         ctimeMs = statSync(abs).ctimeMs
@@ -81,8 +84,8 @@ export class FingerprintWatch {
     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`,
+      `[vx] a task rewrote \`${this.movedFiles.join('`, `')}\` during the run, which a plugin ` +
+        `folds into every key: nothing keyed before it is restored or saved from here on`,
     )
   }
 }

package/src/orchestrator/forecast.ts

@@ -12,6 +12,8 @@ export interface LiveForecast {
   critical?: string
   /** Each running task's unfinished dependents, direct and transitive. */
   blocks: ReadonlyMap<string, number>
+  /** Each running task's p50, where history knows it: the row's expected duration. */
+  expected?: ReadonlyMap<string, number>
 }
 
 export type Forecast = (
@@ -90,7 +92,12 @@ export function createForecast(
 
   return (finished, running, nowMs) => {
     const blocks = new Map<string, number>()
-    for (const id of running.keys()) blocks.set(id, blocked(id, finished))
+    const expected = new Map<string, number>()
+    for (const id of running.keys()) {
+      blocks.set(id, blocked(id, finished))
+      const p = cost.get(id)
+      if (p !== undefined) expected.set(id, p)
+    }
     const end = new Map<string, number>()
     // The running task each node's longest chain waits on.
     const head = new Map<string, string>()
@@ -128,12 +135,13 @@ export function createForecast(
       }
       work += own
     }
-    if (!known || overrun) return { blocks }
+    if (!known || overrun) return { blocks, expected }
     const critical = chainEnd === undefined ? undefined : head.get(chainEnd)
     return {
       etaMs: Math.max(chain, work / workers),
       ...(critical !== undefined ? { critical } : {}),
       blocks,
+      expected,
     }
   }
 }

package/src/orchestrator/framed-output.ts

@@ -27,8 +27,7 @@
 
 import { withForwardArgs } from '../exec/index.js'
 import { isGroupTask, type TaskNode, type TaskOutcome } from '../graph/index.js'
-import { formatElapsed, maskedCommand } from '../util/index.js'
-import { paint, type ColorSupport } from './colors.js'
+import { formatElapsed, maskedCommand, paint, type ColorSupport } from '../util/index.js'
 import { neverStarted } from './summary.js'
 import { outcomeLabel, ranNoCache, skippedReason } from './events.js'
 import { fileMemo, linkPaths } from './path-links.js'
@@ -532,7 +531,8 @@ function violationSection(outcome: TaskOutcome, colors: ColorSupport): string[]
   // Red, not amber: a violation fails the task, so it reads as a failure.
   // vx's note, after the evidence: the grants that would have allowed it.
   // A read the output depends on is a key input too; the sandbox never
-  // adds one (owner, 2026-10-09).
+  // adds one (owner, 2026-10-09), so the note names the reads no input
+  // glob matches and the user decides.
   const fix = outcome.sandboxFix
   const line = fix === undefined ? undefined : sandboxFixLine(fix)
   const dim = (text: string): string => paint('', text, colors, { dim: true })
@@ -541,8 +541,12 @@ function violationSection(outcome: TaskOutcome, colors: ColorSupport): string[]
       ? []
       : [
           ...(line !== undefined ? [dim(`fix: ${line}`)] : []),
-          ...(fix.read !== undefined
-            ? [dim('a read the output depends on belongs in cache.inputs.files too')]
+          ...(fix.inputs !== undefined
+            ? [
+                dim(
+                  `and, if the output depends on them, cache.inputs.files: [${fix.inputs.map((p) => `'${p}'`).join(', ')}]`,
+                ),
+              ]
             : []),
           ...(fix.withheld !== undefined
             ? [dim(`credential path, grant it only on purpose: ${fix.withheld.join(', ')}`)]

package/src/orchestrator/graph-stage.ts

@@ -2,8 +2,7 @@
 // CLI's `--affected` task selection (`vx show <task> --affected`), so both
 // select over the graph the hooks leave.
 
-import type { WorkspaceRules } from '../config.js'
-import type { TaskNode } from '../graph/index.js'
+import type { GraphRules, TaskNode } from '../graph/index.js'
 import { type ProjectMeta, validateProjectConfig } from '../workspace/index.js'
 import { applyGraphHooks } from './plugin-host.js'
 import type { VxPlugin } from './plugin.js'
@@ -17,7 +16,7 @@ export async function applyGraphStage(
     cacheDir: string
     projectMetas: readonly ProjectMeta[]
     warn: (message: string) => void
-    rules?: WorkspaceRules | undefined
+    rules?: GraphRules | undefined
   },
 ): Promise<void> {
   // A hook edits each node's config in place, as `project` does, so the
@@ -36,10 +35,11 @@ export async function applyGraphStage(
     (plugin) => {
       for (const n of nodes.values()) {
         if (isDefaultBuild(n.config)) continue
-        const where = configPaths.get(n.projectName) ?? `${n.projectName} (no config file)`
+        const own = configPaths.get(n.projectName) ?? null
         validateProjectConfig(
           { tasks: { [n.taskName]: n.config } },
-          `${where} (after plugin '${plugin.name}')`,
+          `${own ?? `${n.projectName} (no config file)`} (after plugin '${plugin.name}')`,
+          own,
         )
       }
     },

package/src/orchestrator/history.ts

@@ -12,13 +12,17 @@
 // (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'
+import { branchSource, EXECUTED_RUNS_SQL } from '../cache/index.js'
+import { splitTaskId } from '../util/index.js'
 import { failureModeOf, mixedOutcomeKeysSql } from './failure-mode.js'
 import type { FailureMode } from './failure-mode.js'
 import { isPassStatus, TASK_STATUSES } from './telemetry.js'
 
 const DEFAULT_RECENT = 50
 
+/** A task's forecast is the median of this many of its newest timings. */
+const FORECAST_RUNS = 5
+
 // A hit is recorded as `cache-hit` / `cache-hit-remote` and replays a
 // success; the list is derived so a new status cannot miss it.
 /** The pass set as SQL, `(…)`: one definition, `isPassStatus`. */
@@ -86,7 +90,9 @@ export class EmptyHistoryProvider implements HistoryProvider {
 export class LocalHistoryProvider implements HistoryProvider {
   constructor(
     private readonly db: Database,
-    private readonly recent: number = DEFAULT_RECENT,
+    readonly recent: number = DEFAULT_RECENT,
+    /** The run's branch (`currentBranch`); undefined: a forecast reads every branch's timings. */
+    private readonly branch?: string | null,
   ) {}
 
   /**
@@ -107,8 +113,17 @@ export class LocalHistoryProvider implements HistoryProvider {
    * read by `run_id` and stay exact.
    */
   async loadFor(taskIds: readonly string[]): Promise<HistoryTable> {
+    if (taskIds.length === 0) return new Map()
+    return this.load(new Set(taskIds))
+  }
+
+  /** Every task the window holds, as `loadFor` answers each (`vx last --stats`). */
+  async loadAll(): Promise<HistoryTable> {
+    return this.load(null)
+  }
+
+  private load(wanted: ReadonlySet<string> | null): HistoryTable {
     const out = new Map<string, TaskHistory>()
-    if (taskIds.length === 0) return out
     const floor = this.floor()
 
     // `skipped` rows are excluded: a skip is a task the run never executed,
@@ -160,15 +175,15 @@ export class LocalHistoryProvider implements HistoryProvider {
     // Every pair in the slice is grouped (the slice is bounded, so this is
     // cheap) and the asked-for ones are picked out here — a per-row IN-list
     // probe in SQL cost more than the grouping it would have saved.
-    const wanted = new Set(taskIds)
-    const rows = (this.db.query(sql).all(floor) as Row[]).filter((r) =>
-      wanted.has(`${r.project}#${r.task}`),
+    const rows = (this.db.query(sql).all(floor) as Row[]).filter(
+      (r) => wanted === null || wanted.has(`${r.project}#${r.task}`),
     )
 
     // The flakiness signal needs per-key outcomes, which the aggregate above
     // folded away — one more pass over the slice, only for the pairs whose
     // verdict actually depends on it (failed, and no retry already proving
     // nondeterminism); a green history never pays for it.
+    const p50s = this.forecasts(new Set(rows.map((r) => `${r.project}#${r.task}`)))
     const mixed = this.mixedOutcomeKeys(
       floor,
       rows.filter((r) => r.failures > 0 && r.retried === 0),
@@ -182,7 +197,7 @@ export class LocalHistoryProvider implements HistoryProvider {
       if (durations !== undefined) durations.sort((a, b) => a - b)
       out.set(key, {
         runs: total,
-        p50DurationMs: durations ? pickPercentile(durations, 0.5) : undefined,
+        p50DurationMs: p50s.get(key),
         p99DurationMs: durations ? pickPercentile(durations, 0.99) : undefined,
         successRate: row.successes / total,
         hitRate: row.hits / total,
@@ -195,28 +210,109 @@ export class LocalHistoryProvider implements HistoryProvider {
   }
 
   /**
-   * The same window's p50s alone. `loadFor`'s rates and resource maxima
-   * read every row of the window and join each hit to its entry: 38 ms at
-   * 27,000 rows against 4 for the executed successes' durations alone.
+   * The forecasts alone. `loadFor`'s rates and resource maxima read every
+   * row of the window and join each hit to its entry: 38 ms at 27,000 rows
+   * against 4 for the executed successes' durations alone.
    */
   async p50sFor(taskIds: readonly string[]): Promise<ReadonlyMap<string, number>> {
+    if (taskIds.length === 0) return new Map()
+    return this.forecasts(new Set(taskIds))
+  }
+
+  /**
+   * Whether the last forecast read found some task with no timing on this
+   * branch (on any branch when the provider has none): what a
+   * default-branch import is for. Learned by the read itself, so asking
+   * costs nothing (a query per task was 70 ms at 8,002 tasks).
+   */
+  lackedBranchHistory = false
+
+  /** Whether timings of default-branch commit `sha` were imported. */
+  hasImported(sha: string): boolean {
+    return (
+      this.db
+        .query(`SELECT 1 FROM task_durations WHERE source = 'remote' AND sha = ? LIMIT 1`)
+        .get(sha) !== null
+    )
+  }
+
+  /**
+   * Keep default-branch commit `sha`'s timings (task id → ms) as forecast
+   * rows: one per task, so a repeat import, by this worktree or another
+   * at once, adds nothing.
+   */
+  importTimings(sha: string, timings: ReadonlyMap<string, number>): void {
+    const insert = this.db.query(
+      `INSERT OR IGNORE INTO task_durations(project, task, source, sha, duration_ms, recorded_at)
+       VALUES (?, ?, 'remote', ?, ?, ?)`,
+    )
+    const now = Date.now()
+    this.db
+      .transaction(() => {
+        for (const [id, ms] of timings) {
+          const [project, task] = splitTaskId(id)
+          insert.run(project, task, sha, Math.round(ms), now)
+        }
+      })
+      .immediate()
+  }
+
+  /**
+   * Each task's duration forecast (owner, 2026-10-14): the median of its
+   * last `FORECAST_RUNS` timings on this branch, else the default branch's
+   * newest imported timing (`importTimings`), else the median on any
+   * branch, else none. The timings are the shared store's `task_durations`, so every
+   * worktree of the repo reads them and a new one forecasts on its first
+   * run. A point read per task on `(project, task, source, id)`: exact
+   * however old the rows, where the runs window holds only the newest
+   * invocations.
+   */
+  private forecasts(wanted: ReadonlySet<string>): Map<string, number> {
     const out = new Map<string, number>()
-    if (taskIds.length === 0) return out
-    const rows = this.db
-      .query(
-        `SELECT project, task, GROUP_CONCAT(duration_ms) AS ds FROM runs
-         WHERE id >= ? AND status = 'success' AND (cache_hit IS NULL OR cache_hit = 0)
-         GROUP BY project, task`,
+    this.lackedBranchHistory = false
+    if (wanted.size === 0) return out
+    // Tiers, first answer wins.
+    type Tier = (project: string, task: string) => Array<{ ms: number }>
+    const tiers: Tier[] = []
+    const newest = (where: string) =>
+      this.db.query(
+        `SELECT duration_ms AS ms FROM task_durations WHERE project = ? AND task = ? AND ${where}
+         ORDER BY id DESC LIMIT ${FORECAST_RUNS}`,
       )
-      .all(this.floor()) as Array<{ project: string; task: string; ds: string }>
-    const wanted = new Set(taskIds)
-    for (const row of rows) {
-      const key = `${row.project}#${row.task}`
-      if (!wanted.has(key)) continue
-      const durations = row.ds.split(',').map(Number)
-      durations.sort((a, b) => a - b)
-      out.set(key, pickPercentile(durations, 0.5))
+    if (this.branch !== undefined) {
+      const source = branchSource(this.branch)
+      const q = newest('source = ?')
+      tiers.push((p, t) => q.all(p, t, source) as Array<{ ms: number }>)
+    }
+    // One probe on the partial index first: a store with no import costs
+    // no query per task.
+    if (
+      this.db.query(`SELECT 1 FROM task_durations WHERE source = 'remote' LIMIT 1`).get() !== null
+    ) {
+      const remote = this.db.query(
+        `SELECT duration_ms AS ms FROM task_durations WHERE project = ? AND task = ? AND source = 'remote'
+         ORDER BY id DESC LIMIT 1`,
+      )
+      tiers.push((p, t) => remote.all(p, t) as Array<{ ms: number }>)
+    }
+    const any = newest(`source LIKE 'branch:%'`)
+    tiers.push((p, t) => any.all(p, t) as Array<{ ms: number }>)
+    const own = this.branch !== undefined ? tiers[0] : tiers.at(-1)
+    let lacked = false
+    for (const id of wanted) {
+      const [project, task] = splitTaskId(id)
+      let answered: Tier | undefined
+      for (const tier of tiers) {
+        const rows = tier(project, task)
+        if (rows.length === 0) continue
+        const durations = rows.map((r) => r.ms).sort((x, y) => x - y)
+        out.set(id, pickPercentile(durations, 0.5))
+        answered = tier
+        break
+      }
+      if (answered !== own) lacked = true
     }
+    this.lackedBranchHistory = lacked
     return out
   }
 
@@ -236,13 +332,12 @@ export class LocalHistoryProvider implements HistoryProvider {
     type Executed = {
       project: string
       task: string
-      ds: string
       rss: number | null
       cpu: number | null
     }
     const executed = this.db
       .query(
-        `SELECT project, task, GROUP_CONCAT(duration_ms) AS ds, MAX(peak_rss_bytes) AS rss,
+        `SELECT project, task, MAX(peak_rss_bytes) AS rss,
            MAX(CASE WHEN cpu_ms IS NOT NULL AND duration_ms > 0
                     THEN cpu_ms * 1.0 / duration_ms END) AS cpu
          FROM runs
@@ -250,13 +345,12 @@ export class LocalHistoryProvider implements HistoryProvider {
          GROUP BY project, task`,
       )
       .all(floor) as Executed[]
+    const p50s = this.forecasts(wanted)
     for (const row of executed) {
       const key = `${row.project}#${row.task}`
       if (!wanted.has(key)) continue
-      const durations = row.ds.split(',').map(Number)
-      durations.sort((a, b) => a - b)
       out.set(key, {
-        p50DurationMs: pickPercentile(durations, 0.5),
+        p50DurationMs: p50s.get(key),
         ...(row.rss !== null ? { maxPeakRssBytes: row.rss } : {}),
         ...(row.cpu !== null ? { maxCpuParallelism: row.cpu } : {}),
       })
@@ -279,11 +373,13 @@ export class LocalHistoryProvider implements HistoryProvider {
       const rss = Math.max(had?.maxPeakRssBytes ?? -Infinity, row.rss ?? -Infinity)
       const cpu = Math.max(had?.maxCpuParallelism ?? -Infinity, row.cpu ?? -Infinity)
       out.set(key, {
-        p50DurationMs: had?.p50DurationMs,
+        p50DurationMs: p50s.get(key),
         ...(rss !== -Infinity ? { maxPeakRssBytes: rss } : {}),
         ...(cpu !== -Infinity ? { maxCpuParallelism: cpu } : {}),
       })
     }
+    // A forecast reads past the window: a task with none in it still has one.
+    for (const [key, p50] of p50s) if (!out.has(key)) out.set(key, { p50DurationMs: p50 })
     return out
   }
 

package/src/orchestrator/hit-restore.ts

@@ -14,6 +14,7 @@ import {
   cleanOutputPaths,
   cleanOutputs,
   cleanWorkspaceOutputs,
+  committedFiles,
   resolveOutputs,
   resolveWorkspaceOutputs,
   WORKSPACE_OUTPUT_PREFIX,
@@ -67,8 +68,13 @@ export async function restoreHit(restore: RestoreHitArgs): Promise<TaskOutcome>
     projectDir: node.projectDir,
     outputs,
     nestedProjectDirs: args.nestedProjectDirs,
+    committed: committedFiles(args.gitFilesCache, node.projectDir),
+  }
+  const wsCleanArgs = {
+    workspaceRoot: args.workspaceRoot,
+    outputs: wsOutputs,
+    committed: committedFiles(args.gitFilesCache, args.workspaceRoot),
   }
-  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
@@ -101,7 +107,7 @@ export async function restoreHit(restore: RestoreHitArgs): Promise<TaskOutcome>
   // output replays from the row (`hit.stdout`), and its artifact holds
   // only logs. Extracting it anyway cost an `exists` + a tar read per hit
   // — 1.7 ms each on a four-task real repo whose `link` and `element`
-  // tasks declare `outputs: []` (2026-09-10, VX_TIMING).
+  // tasks declare `outputs: []` (2026-09-10, `VX_DEBUG_TIMING`).
   let skipRestore = !anyOutputs
   // The walk that found the tree stale, handed to the clean when nothing
   // was awaited between them: the clean's own walk would only repeat it
@@ -230,7 +236,12 @@ export async function restoreHit(restore: RestoreHitArgs): Promise<TaskOutcome>
     let cleanedWsRels: string[] = []
     if (additive) {
       cleanedRels = hit.outputFiles.filter((p) => !p.startsWith(WORKSPACE_OUTPUT_PREFIX))
-      await cleanOutputPaths({ projectDir: node.projectDir, rels: cleanedRels, outputs })
+      await cleanOutputPaths({
+        projectDir: node.projectDir,
+        rels: cleanedRels,
+        outputs,
+        committed: cleanArgs.committed,
+      })
       cleanedWsRels = hit.outputFiles
         .filter((p) => p.startsWith(WORKSPACE_OUTPUT_PREFIX))
         .map((p) => p.slice(WORKSPACE_OUTPUT_PREFIX.length))
@@ -238,6 +249,7 @@ export async function restoreHit(restore: RestoreHitArgs): Promise<TaskOutcome>
         projectDir: args.workspaceRoot,
         rels: cleanedWsRels,
         outputs: wsOutputs,
+        committed: wsCleanArgs.committed,
       })
     } else {
       if (outputs.length > 0) {

package/src/orchestrator/index.ts

@@ -4,6 +4,7 @@
 export { run, planRun, nxProjectTarget, projectNamed } from './run.js'
 export { prepareRun, type PreparedRun } from './prepare.js'
 export { affectedTaskProjects } from './affected-tasks.js'
+export { applyGraphStage } from './graph-stage.js'
 export type { AffectedReason } from './affected-tasks.js'
 export {
   discoverProjects,
@@ -13,6 +14,8 @@ export {
   loadProjects,
   loadResolvedProjects,
   loadWorkspacePlugins,
+  lockOfDiscovery,
+  lockReader,
   type LoadedProjects,
   type LoadProjectsArgs,
 } from './projects.js'
@@ -21,15 +24,19 @@ 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'
+export {
+  type CacheFlags,
+  type CachePolicy,
+  FULL_CACHE_POLICY,
+  parseCachePolicy,
+} from '../cache/index.js'
 // The CLI reads a recorded exit code; the runner's convention decodes it.
 // It records its own argv quoted as the runner quotes forwarded args.
 export { exitSignal, shellQuote } from '../exec/index.js'
 export { forwardedSignal } from './signals.js'
-// `vx cache prune` waits for a run on the workspace before it evicts.
+// `vx cache clean` waits for a run on the workspace before it evicts.
 export { acquireRunLock } from './run-lock.js'
 export { defaultLogger, resolveOutputView } from './logger.js'
-export { detectColors, paint, type ColorSupport } from './colors.js'
 export type { Logger, OutputView } from './logger.js'
 export type { RunPlan, PlannedTask, PlanPrediction, CacheStatus } from './plan.js'
 export {
@@ -70,6 +77,7 @@ export {
   installPlugins,
   type CacheContext,
   type ExecutorContext,
+  type OutputContext,
   type CommandContext,
   type GraphHookContext,
   type KeyHookContext,
@@ -79,13 +87,15 @@ export {
   type AdmitContext,
   type WorkspaceHookContext,
   type DiscoverContext,
-  type NamedProject,
+  type DiscoveredProject,
   type InstallPluginsArgs,
   type Plugin,
   type PluginContext,
   type PluginHookHandlers,
   type PluginHookName,
   type PluginSetupContext,
+  type RunReport,
+  type RunReportTask,
   type FingerprintChange,
   type FingerprintClaim,
   type FingerprintContext,
@@ -105,8 +115,9 @@ export {
   claimedAffected,
   fingerprintClaims,
   hasHook,
-  CACHE_LAYER_METHODS,
+  REMOTE_CACHE_METHODS,
   resolveCache,
+  type CacheHost,
   resolveExecutors,
 } from './plugin-host.js'
 export {
@@ -114,6 +125,7 @@ export {
   reachDigests,
   type LockfileClaimHooks,
   type LockfileClaimOptions,
+  type LockfileImporter,
   type ReachGraph,
 } from './lockfile-claim.js'
 export { subscribeTelemetry, type TelemetryHandle } from './telemetry-host.js'
@@ -147,6 +159,7 @@ export {
   captureGitContext,
   captureHostContext,
   captureWorkspaceIdentity,
+  currentBranch,
   detectCi,
 } from './run-context.js'
 export type { CiContext, GitContext, HostContext, WorkspaceIdentity } from './run-context.js'
@@ -158,6 +171,7 @@ export {
   latestRunId,
   listInvocations,
   listRuns,
+  inputWriters,
   rootCauses,
   whyDidThisRerun as whyDidThisRerunQuery,
 } from './metrics.js'
@@ -173,6 +187,7 @@ export { resolveRunId, shortRunId } from './run-id.js'
 export type {
   CacheEntryRow,
   CacheKeyDiff,
+  InputWriter,
   RootCause,
   CacheKeyExplanation,
   InputDiffEntry,

package/src/orchestrator/local-shortcircuit.ts

@@ -52,7 +52,8 @@ export interface ShortCircuitArgs {
   nodes: Map<string, TaskNode>
   cache: CacheLayer
   workspaceRoot: string
-  workspaceFingerprint: string
+  /** The root files the plugins claim (`DeriveStableKeysArgs.claimedFiles`). */
+  claimedFiles: readonly string[]
   forwardArgs?: readonly string[] | undefined
   nestedDirsByProject: Map<string, string[]>
   gitFilesCache: GitFilesCache