@vzn/vx 0.0.637 → 0.0.639

package/src/graph/task-graph.ts

@@ -1,13 +1,18 @@
 import type { ProjectConfig, TaskConfig, WorkspaceRules } from '../config.js'
 import {
   asTrees,
+  checkIgnoreSync,
+  ignoreProbes,
   isLiteralPattern,
+  listedSync,
   normalizeGlob,
   relPosix,
   splitNegations,
   staticPrefix,
   taskGlob,
+  refusal,
   UserError,
+  wholeIgnored,
   wholeSubtreePrefixes,
 } from '../util/index.js'
 import type { PackageGraph, ProjectEntry } from '../workspace/index.js'
@@ -583,7 +588,7 @@ export function buildTaskGraph(options: BuildGraphOptions): Map<string, TaskNode
       // task behind it would fold no upstream either.
       if (!packageGraph.edgeSource) {
         throw new UserError(
-          `${id}: ^${spec.task} needs project edges; add pnpm()/bun()/npm()/yarn() or a plugin that returns \`deps\``,
+          `${id}: ^${spec.task} needs project edges; add pnpm()/bun()/npm()/yarn() and install so its lockfile exists, or a plugin that returns \`deps\``,
           'VX_E_DEPENDS_ON',
         )
       }
@@ -969,6 +974,19 @@ function witnessed(a: string, b: string): boolean {
       if (ga.match(candidate) && gb.match(candidate)) return true
     }
   }
+  // Each glob filled in whole, every wildcard a name and `**` one level or
+  // none: `**/dist/**` beside `**/*` meets at `x/dist/x`, a path neither
+  // last segment builds (solid, M 2026-10-15).
+  for (const glob of [a, b]) {
+    const segs = glob.split('/')
+    if (segs.some((s) => /[[\]{}()!+@]/.test(s))) continue
+    for (const drop of [false, true]) {
+      const candidate = segs
+        .flatMap((s) => (s === '**' ? (drop ? [] : ['x']) : [s.replace(/\*+|\?/g, 'x')]))
+        .join('/')
+      if (candidate !== '' && ga.match(candidate) && gb.match(candidate)) return true
+    }
+  }
   return false
 }
 
@@ -1114,6 +1132,15 @@ function detectOutputCollisions(
   }
 }
 
+/**
+ * What a task's `!` output entries take back (A-44). A glob of the other
+ * task's that one takes back whole is a path this task never cleans or
+ * captures, so the pair cannot collide there.
+ */
+function takenBackOf(n: TaskNode, field: 'files' | 'workspaceFiles'): string[] {
+  return splitNegations(n.config.cache?.outputs[field] ?? []).negative
+}
+
 /**
  * `collide` for a root-anchored output against another project's `files`
  * output rebased to the root. With an edge the dependant adds to its
@@ -1132,9 +1159,12 @@ function collideAcross(
   exclusive: boolean,
 ): void {
   if (neverWritesLocally(ws) || neverWritesLocally(files)) return
+  const wsBack = takenBackOf(ws, 'workspaceFiles')
+  const filesBack = takenBackOf(files, 'files').map((g) => (rel === '' ? g : `${rel}/${g}`))
   for (const ga of wsGlobs) {
     for (const gb of rebased) {
-      if (!outputsOverlap(ga, gb)) continue
+      if (!outputsOverlap(ga, gb) || outputTakenBack(gb, wsBack) || outputTakenBack(ga, filesBack))
+        continue
       const head =
         `${ws.id} declares the output ${JSON.stringify(ga)} in cache.outputs.workspaceFiles, ` +
         `inside ${files.id}'s ${JSON.stringify(gb.slice(rel === '' ? 0 : rel.length + 1))} in ` +
@@ -1391,9 +1421,12 @@ function collide(
   exclusive: boolean,
 ): void {
   if (neverWritesLocally(a) || neverWritesLocally(b)) return
+  const aBack = takenBackOf(a, field)
+  const bBack = takenBackOf(b, field)
   for (const ga of aGlobs ?? []) {
     for (const gb of bGlobs ?? []) {
-      if (!outputsOverlap(ga, gb)) continue
+      if (!outputsOverlap(ga, gb) || outputTakenBack(gb, aBack) || outputTakenBack(ga, bBack))
+        continue
       const head =
         `${a.id} and ${b.id} both declare the output ${JSON.stringify(ga)}` +
         (ga === gb ? '' : ` / ${JSON.stringify(gb)}`) +
@@ -1407,8 +1440,19 @@ function collide(
       // `run.rules.exclusiveOutputs` is off (X-53). Without an edge the two run
       // in either order, and the refusal below stands.
       const [up, down] = reaches(b.id, a.id) ? [a, b] : reaches(a.id, b.id) ? [b, a] : []
+      const parts = {
+        headline: `${a.id} and ${b.id} both write ${ga === gb ? ga : `${ga} / ${gb}`}`,
+        ...(field === 'files' ? {} : { what: ['in cache.outputs.workspaceFiles'] }),
+        why: "vx clears a task's outputs before it runs, so one deletes the other's",
+      }
       if (up !== undefined && exclusive)
-        throw new UserError(`${head}. ${EXCLUSIVE_OUTPUTS_FIX}`, 'VX_E_OUTPUT_OVERLAP')
+        throw refusal(
+          {
+            ...parts,
+            fix: 'give each task its own output path, or set run.rules.exclusiveOutputs: false in .vx/workspace.ts',
+          },
+          { code: 'VX_E_OUTPUT_OVERLAP', message: `${head}. ${EXCLUSIVE_OUTPUTS_FIX}` },
+        )
       if (up !== undefined && down !== undefined) {
         const downGlobs = splitNegations(
           (field === 'files'
@@ -1419,9 +1463,12 @@ function collide(
         ;(up.outputsAddedToBy ??= []).push(...(downGlobs ?? []))
         return
       }
-      throw new UserError(
-        `${head} and the run still reports success. Give each task its own output path.`,
-        'VX_E_OUTPUT_OVERLAP',
+      throw refusal(
+        { ...parts, fix: 'give each task its own output path' },
+        {
+          code: 'VX_E_OUTPUT_OVERLAP',
+          message: `${head} and the run still reports success. Give each task its own output path.`,
+        },
       )
     }
   }
@@ -1522,6 +1569,8 @@ interface Side {
   reads: boolean
   /** The project's root-relative dir for rebased `files` globs. */
   rel?: string
+  /** The root-relative dir project-relative `globs` sit in, for git. */
+  anchor?: string | undefined
 }
 
 /**
@@ -1555,6 +1604,7 @@ function detectInputOverlaps(nodes: Map<string, TaskNode>, workspaceRoot?: strin
   let projectReaders = false
   let rootReaders = false
   const memo: TakeBackMemo = { bySide: new Map(), byList: new Map() }
+  const found: Found = new Map()
   const bucket = (name: string): Side[] => {
     let list = byProject.get(name)
     if (list === undefined) byProject.set(name, (list = []))
@@ -1566,7 +1616,8 @@ function detectInputOverlaps(nodes: Map<string, TaskNode>, workspaceRoot?: strin
     const outFiles = positives(cache.outputs.files)
     const outWs = positives(cache.outputs.workspaceFiles ?? [])
     if (outFiles.length > 0) {
-      bucket(n.projectName).push({ node: n, globs: outFiles, reads: false })
+      const anchor = workspaceRoot === undefined ? undefined : relPosix(workspaceRoot, n.projectDir)
+      bucket(n.projectName).push({ node: n, globs: outFiles, reads: false, anchor })
       filesWriters.push(n)
     }
     if (outWs.length > 0) {
@@ -1595,7 +1646,7 @@ function detectInputOverlaps(nodes: Map<string, TaskNode>, workspaceRoot?: strin
         (s) => s.globs,
         (s) => s.reads,
       )) {
-        readsOutputs(memo, sides[i]!, sides[j]!, 'files')
+        readsOutputs(memo, found, sides[i]!, sides[j]!, 'files')
       }
     }
   }
@@ -1613,10 +1664,20 @@ function detectInputOverlaps(nodes: Map<string, TaskNode>, workspaceRoot?: strin
       (s) => s.globs,
       (s) => s.reads,
     )) {
-      readsOutputs(memo, sides[i]!, sides[j]!, 'files')
+      readsOutputs(memo, found, sides[i]!, sides[j]!, 'files')
     }
   }
-  if (!rootReaders) return
+  if (rootReaders) readsRootedOutputs(memo, found, rooted, filesWriters, workspaceRoot)
+  refuseUnlessIgnored(found, workspaceRoot)
+}
+
+function readsRootedOutputs(
+  memo: TakeBackMemo,
+  found: Found,
+  rooted: Side[],
+  filesWriters: readonly TaskNode[],
+  workspaceRoot: string | undefined,
+): void {
   if (workspaceRoot !== undefined) {
     for (const node of filesWriters) {
       const rel = relPosix(workspaceRoot, node.projectDir)
@@ -1631,8 +1692,37 @@ function detectInputOverlaps(nodes: Map<string, TaskNode>, workspaceRoot?: strin
     (s) => s.globs,
     (s) => s.reads,
   )) {
-    readsOutputs(memo, rooted[i]!, rooted[j]!, 'workspaceFiles')
+    readsOutputs(memo, found, rooted[i]!, rooted[j]!, 'workspaceFiles')
+  }
+}
+
+/** Each overlapped output, root-relative, and the refusal it meets; the first pair found per output. */
+type Found = Map<string, () => UserError>
+
+/**
+ * An output git ignores is no overlap (M, 2026-10-15): a key reads only what
+ * git lists, so such an output never reaches it. Asked of git once, for
+ * every overlapped output together; an output git cannot speak for (no work
+ * tree, a glob no few paths stand for) is refused as before. The answer
+ * holds for the lock; a run's stability gate asks git again for itself.
+ */
+function refuseUnlessIgnored(found: Found, workspaceRoot: string | undefined): void {
+  if (found.size === 0) return
+  if (workspaceRoot !== undefined) {
+    const asks = [...found.keys()].map(ignoreProbes)
+    const paths = asks.flatMap((a) => a?.paths ?? [])
+    const ignored = checkIgnoreSync(workspaceRoot, paths)
+    let listed: string[] | null | undefined
+    const pass = wholeIgnored(found.keys(), ignored, (g) => {
+      listed ??= listedSync(workspaceRoot, [
+        ...new Set(asks.flatMap((a) => (a?.deep === true ? [a.dir] : []))),
+      ])
+      return listed === null || listed.some((f) => taskGlob(g).match(f))
+    })
+    for (const [g, refuse] of found) if (!pass.has(g)) throw refuse()
+    return
   }
+  throw found.values().next().value!()
 }
 
 /**
@@ -1679,6 +1769,7 @@ function takenBack(
 
 function readsOutputs(
   memo: TakeBackMemo,
+  found: Found,
   x: Side,
   y: Side,
   field: 'files' | 'workspaceFiles',
@@ -1687,21 +1778,28 @@ function readsOutputs(
   const [reader, writer] = x.reads ? [x, y] : [y, x]
   const at = reader.rel === undefined || reader.rel === '' ? '' : `${reader.rel}/`
   for (const go of writer.globs) {
-    if (takenBack(memo, reader, field, go)) continue
+    const rooted =
+      writer.anchor === undefined || writer.anchor === '' ? go : `${writer.anchor}/${go}`
+    if (found.has(rooted) || takenBack(memo, reader, field, go)) continue
     for (const gi of reader.globs) {
       if (!outputsOverlap(gi, go)) continue
       const shown =
         writer.rel === undefined || writer.rel === '' ? go : go.slice(writer.rel.length + 1)
       const out = at !== '' && go.startsWith(at) ? go.slice(at.length) : go
-      throw new UserError(
-        `${reader.node.id} reads ${JSON.stringify(gi.slice(at.length))} in cache.inputs.${field}, which matches ` +
-          `${writer.node.id}'s output ${JSON.stringify(shown)} — a task's key must not read ` +
-          `another task's outputs (the dependency's key already cascades through dependsOn). ` +
-          `Exclude it: add ${JSON.stringify(`!${out}`)} to ${reader.node.id}'s ` +
-          `cache.inputs.${field}, or set run.rules.upfrontKeys: false in .vx/workspace.ts to ` +
-          `let it wait for its producer.`,
-        'VX_E_INPUT_IS_OUTPUT',
+      found.set(
+        rooted,
+        () =>
+          new UserError(
+            `${reader.node.id} reads ${JSON.stringify(gi.slice(at.length))} in cache.inputs.${field}, which matches ` +
+              `${writer.node.id}'s output ${JSON.stringify(shown)} — a task's key must not read ` +
+              `another task's outputs (the dependency's key already cascades through dependsOn). ` +
+              `Exclude it: add ${JSON.stringify(`!${out}`)} to ${reader.node.id}'s ` +
+              `cache.inputs.${field}, or set run.rules.upfrontKeys: false in .vx/workspace.ts to ` +
+              `let it wait for its producer.`,
+            'VX_E_INPUT_IS_OUTPUT',
+          ),
       )
+      break
     }
   }
 }

package/src/graph/task-status.ts

@@ -0,0 +1,95 @@
+// A task's terminal status and what each one means: a pass, a hit, where
+// its result came from. One vocabulary every reader (the run verdict, the
+// logger, the history queries, telemetry, plugins) asks, so none re-lists
+// the statuses.
+
+export type TaskStatus =
+  | 'success'
+  | 'cache-hit'
+  | 'cache-hit-remote'
+  | 'failed'
+  | 'skipped'
+  // A child killed by a shutdown signal (SIGINT/SIGTERM — e.g. Ctrl-C):
+  // the task never finished on its own terms, so it reverts to aborted —
+  // excluded from the tally and the run history. It still PROPAGATES like
+  // a failure (see `willSkip`): the child died mid-write, so its outputs
+  // are partial.
+  | 'aborted'
+
+/** Where a task's result came from, derived ONCE in core from the status. */
+export type CacheSource = 'miss' | 'local' | 'remote' | 'none'
+
+/**
+ * Map a task outcome status to its cache source. `success`/`failed` ran
+ * (a miss as far as the cache read is concerned); the two cache-hit
+ * statuses restored from local/remote; `skipped`/`aborted` never engaged
+ * the cache. Pure function — the single place this mapping is decided;
+ * `isCacheHit` below is derived from it rather than re-listing the two
+ * hit statuses, so there is one decision, not two that can disagree.
+ */
+export function deriveCacheSource(status: TaskStatus): CacheSource {
+  switch (status) {
+    case 'cache-hit':
+      return 'local'
+    case 'cache-hit-remote':
+      return 'remote'
+    case 'success':
+    case 'failed':
+      return 'miss'
+    case 'skipped':
+    case 'aborted':
+      return 'none'
+  }
+}
+
+/**
+ * Whether each status counts as a PASS. Written as a `Record<TaskStatus, …>`
+ * rather than a `new Set([...])` on purpose: a Record must name every member,
+ * so adding a status to the union is a COMPILE error HERE and the omission
+ * cannot ship. A Set of string literals has no such tripwire — it silently
+ * answers `false` for the new member, which is how ten hand-rolled copies of
+ * this vocabulary accumulated across core, cloud and the dashboard.
+ */
+const PASSES: Record<TaskStatus, boolean> = {
+  success: true,
+  'cache-hit': true,
+  'cache-hit-remote': true,
+  failed: false,
+  skipped: false,
+  aborted: false,
+}
+
+/**
+ * Every `TaskStatus`, at runtime. Read off `PASSES`'s keys, which the
+ * `Record<TaskStatus, …>` type guarantees is exactly the union — so this is
+ * derived, not a second list that can fall behind. Exported so a consumer that
+ * cannot import the type (a test asserting a copy of this vocabulary in
+ * another package agrees) can still enumerate the real set.
+ */
+export const TASK_STATUSES: readonly TaskStatus[] = Object.keys(PASSES) as TaskStatus[]
+
+/**
+ * Did the task pass? A cache hit counts — it produced the same result without
+ * spending the time, which is the whole point. `skipped` and `aborted` do NOT:
+ * neither finished on its own terms, so neither can vouch for anything.
+ *
+ * Takes `string`, not `TaskStatus`, because most callers hold a status that
+ * arrived over a wire or out of a database column. An unrecognised string
+ * reads as NOT passing — the safe direction, since the alternative is calling
+ * a run green on a status this build has never heard of.
+ */
+export function isPassStatus(status: string): boolean {
+  return PASSES[status as TaskStatus] === true
+}
+
+/**
+ * Did the task's result come out of the cache (either layer)? Derived from
+ * `deriveCacheSource` rather than re-listing the two hit statuses, so the two
+ * cannot disagree about what a hit is. Unknown strings read as not-a-hit.
+ */
+export function isCacheHit(status: string): boolean {
+  // No known-status guard: an unknown string falls through the switch to
+  // undefined, which is neither hit source (the guard survived item 654).
+  const source = deriveCacheSource(status as TaskStatus)
+  return source === 'local' || source === 'remote'
+}

package/src/{orchestrator → history}/failure-mode.ts

@@ -4,11 +4,13 @@
 // drift into opposite verdicts on identical data. Both build on
 // `mixedOutcomeKeysSql` + `failureModeOf`, so the rule cannot fork again.
 // The per-run detector (`detectFlaky`) and the doctor's list (`flakyTasks`)
-// read the same per-key projection (`keyOutcomesSql`).
+// read the same per-key projection (`keyOutcomesSql`) over the shared
+// store's flaky record (`task_outcomes`, v38), so every worktree of a repo
+// judges a key on what all of them saw.
 
 import type { Database } from 'bun:sqlite'
 import { KEYED_RUNS_SQL } from '../cache/index.js'
-import { isCacheHit, TASK_STATUSES } from './telemetry.js'
+import { isCacheHit, TASK_STATUSES } from '../graph/index.js'
 
 // SQL hit set derived from the predicate — never a hand-typed list and never
 // a prefix LIKE (a prefix counts any status merely NAMED cache-hit-*). The
@@ -17,6 +19,9 @@ const HIT_STATUSES = `(${TASK_STATUSES.filter(isCacheHit)
   .map((s) => `'${s}'`)
   .join(', ')})`
 
+/** The shared store's flaky record: what `detectFlaky` and `flakyTasks` read. */
+const OUTCOMES = 'task_outcomes'
+
 export type FailureMode = 'stable' | 'flaky-recoverable' | 'flaky-fatal'
 
 /**
@@ -33,6 +38,10 @@ export type FailureMode = 'stable' | 'flaky-recoverable' | 'flaky-fatal'
  * projection.
  */
 function keyOutcomesSql(source: string, where = ''): string {
+  // The flaky record keeps only rows that observed their key (run-history.ts
+  // `observesKey`), so it carries none of the filter's columns.
+  const keyed =
+    source === OUTCOMES ? '1' : `${KEYED_RUNS_SQL} AND cached IS NOT 0 AND blocked_by IS NULL`
   return `SELECT project, task, hash, SUM(failed) AS failures, SUM(passed) AS passes,
        SUM(retried) AS retried_failures,
        SUM(CASE WHEN failed = 1 AND id > first_pass THEN 1 ELSE 0 END) AS relapses
@@ -41,10 +50,10 @@ function keyOutcomesSql(source: string, where = ''): string {
          FROM (SELECT project, task, hash, id,
              CASE WHEN status = 'failed' THEN 1 ELSE 0 END AS failed,
              CASE WHEN status = 'success' AND attempts > 1 THEN attempts - 1 ELSE 0 END AS retried,
-             CASE WHEN status = 'success' OR status IN ${HIT_STATUSES} OR cache_hit = 1
+             CASE WHEN status = 'success' OR status IN ${HIT_STATUSES}${source === OUTCOMES ? '' : ' OR cache_hit = 1'}
                THEN 1 ELSE 0 END AS passed
            FROM ${source}
-           WHERE ${KEYED_RUNS_SQL} AND cached IS NOT 0 AND blocked_by IS NULL${where}))
+           WHERE ${keyed}${where}))
        GROUP BY project, task, hash`
 }
 
@@ -136,9 +145,9 @@ const keyOf = (c: { project: string; task: string; hash: string }): string =>
  * failures is a recovery, not a flake. The counts fold this run in.
  *
  * The cost follows the run's colour. No candidate (every task a hit or a
- * skip): no query. A green miss: one probe of the `runs_failed` partial
- * index for the keys that ever failed — failures are the rare rows, so the
- * probe is microseconds however long the history. Only a key that DID fail
+ * skip): no query. A green miss: one probe of the `task_outcomes_hash`
+ * index for the keys that ever failed — a key holds a handful of rows, so
+ * the probe is microseconds however long the history. Only a key that DID fail
  * before, or a task failing now, pays the projection scan over its own
  * keys, and a run that is failing has more to look at than a scan.
  */
@@ -149,8 +158,8 @@ export function detectFlaky(db: Database, candidates: readonly FlakyCandidate[])
   chunked(passedNow, (chunk) => {
     const rows = db
       .query(
-        `SELECT DISTINCT project, task, hash FROM runs
-         WHERE status = 'failed' AND blocked_by IS NULL AND hash IN (${chunk.map(() => '?').join(', ')})`,
+        `SELECT DISTINCT project, task, hash FROM ${OUTCOMES}
+         WHERE status = 'failed' AND hash IN (${chunk.map(() => '?').join(', ')})`,
       )
       .all(...chunk.map((c) => c.hash)) as { project: string; task: string; hash: string }[]
     for (const r of rows) everFailed.add(keyOf(r))
@@ -162,7 +171,7 @@ export function detectFlaky(db: Database, candidates: readonly FlakyCandidate[])
   const counts = new Map<string, { passes: number; failures: number; relapses: number }>()
   chunked(suspects, (chunk) => {
     const rows = db
-      .query(keyOutcomesSql('runs', ` AND hash IN (${chunk.map(() => '?').join(', ')})`))
+      .query(keyOutcomesSql(OUTCOMES, ` AND hash IN (${chunk.map(() => '?').join(', ')})`))
       .all(...chunk.map((c) => c.hash)) as {
       project: string
       task: string
@@ -212,7 +221,7 @@ export function flakyTasks(db: Database): FlakyTask[] {
     .query(
       `SELECT project, task, COUNT(*) AS keys, SUM(passes) AS passes, SUM(failures) AS failures
        FROM (SELECT project, task, passes, failures + retried_failures AS failures
-             FROM (${keyOutcomesSql('runs')})
+             FROM (${keyOutcomesSql(OUTCOMES)})
              WHERE relapses > 0 OR retried_failures > 0)
        GROUP BY project, task
        ORDER BY failures DESC, passes DESC, project, task`,

package/src/{orchestrator → history}/history.ts

@@ -16,7 +16,7 @@ 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'
+import { isPassStatus, TASK_STATUSES } from '../graph/index.js'
 
 const DEFAULT_RECENT = 50
 
@@ -219,10 +219,49 @@ export class LocalHistoryProvider implements HistoryProvider {
     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 on any branch, else
-   * none. The timings are the shared store's `task_durations`, so every
+   * 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
@@ -230,9 +269,9 @@ export class LocalHistoryProvider implements HistoryProvider {
    */
   private forecasts(wanted: ReadonlySet<string>): Map<string, number> {
     const out = new Map<string, number>()
+    this.lackedBranchHistory = false
     if (wanted.size === 0) return out
-    // Tiers, first answer wins. The remote cache's default-branch timings
-    // (#3563) slot in between the two.
+    // Tiers, first answer wins.
     type Tier = (project: string, task: string) => Array<{ ms: number }>
     const tiers: Tier[] = []
     const newest = (where: string) =>
@@ -245,18 +284,35 @@ export class LocalHistoryProvider implements HistoryProvider {
       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
   }
 

package/src/history/index.ts

@@ -0,0 +1,48 @@
+// What runs leave behind, read back: the duration table a schedule learns
+// from, the flakiness verdict, the queries behind `vx last` / `vx why`, and
+// what a miss's key changed. Read-only SQL over the cache's database; it
+// never runs, renders or writes a run.
+export {
+  EmptyHistoryProvider,
+  type HistoryProvider,
+  type HistoryTable,
+  LocalHistoryProvider,
+  PASS_STATUSES,
+  type TaskHistory,
+  type TaskResources,
+} from './history.js'
+export {
+  detectFlaky,
+  type FailureMode,
+  type FlakyCandidate,
+  type FlakyFinding,
+  type FlakyTask,
+  flakyTasks,
+} from './failure-mode.js'
+export {
+  cacheKeyDiff,
+  explainCacheKey,
+  getInvocation,
+  getRun,
+  inputWriters,
+  latestRunId,
+  listInvocations,
+  listRuns,
+  rootCauses,
+  whyDidThisRerun,
+} from './metrics.js'
+export type {
+  CacheEntryRow,
+  CacheKeyDiff,
+  CacheKeyExplanation,
+  InputDiffEntry,
+  InputWriter,
+  InvocationDetail,
+  ListInvocationsArgs,
+  ListRunsArgs,
+  RootCause,
+  RunDetail,
+  RunSummaryRow,
+  WhyDidThisRerun,
+} from './metrics.js'
+export { createMissExplainer, type MissExplainer } from './miss-reason.js'