@vzn/vx 0.0.640 → 0.0.642

package/src/cli/docs.ts

@@ -1,12 +1,16 @@
 // `vx docs <query> [--limit N] [--format pretty|json]` — search vx's
-// reference offline, for an agent that cannot reach the site: each page is
+// reference as this version wrote it: packages/vx/docs at its git tag on
+// GitHub, read online (M, 2026-10-17: nothing is embedded). Each page is
 // cut at its headings, and the sections holding every query word print
 // whole, best first.
 
+import { VERSION } from '../version.js'
 import { flagHint, formatValue, refuse, refusedWord, seeHelp } from './help.js'
 
 const SITE = 'https://vznjs.github.io/vx/'
 const DEFAULT_LIMIT = 3
+const REPO = 'vznjs/vx'
+const DIR = 'packages/vx/docs'
 
 interface DocsArgs {
   terms: string[]
@@ -59,9 +63,55 @@ function anchor(heading: string): string {
     .replace(/ /g, '-')
 }
 
-/** A page's URL on the site; `features.md` is served as `all-features/`. */
+/** A page's URL on the site, as packages/vx-docs/scripts/import-docs.ts serves it. */
 function pageUrl(page: string): string {
-  return `${SITE}${page === 'features' ? 'all-features' : page}/`
+  const served: Record<string, string> = {
+    README: 'overview',
+    features: 'all-features',
+    'turbo-nx-support': 'compare/turbo-nx-support',
+  }
+  return `${SITE}${served[page] ?? page.toLowerCase()}/`
+}
+
+/** The git ref this vx's docs are at: its release tag; a source checkout (0.0.0) reads main. */
+export function docsRef(version: string = VERSION): string {
+  return version === '0.0.0' ? 'main' : `v${version}`
+}
+
+/**
+ * Every page of packages/vx/docs at `ref` (its own `.md` files, the
+ * maintainers' STATUS.md aside), page name → markdown. One listing, then
+ * the pages at once. Throws with what failed; a token in GITHUB_TOKEN or
+ * GH_TOKEN lifts GitHub's anonymous listing limit.
+ */
+export async function loadPages(
+  ref: string,
+  get: (url: string, init?: RequestInit) => Promise<Response> = fetch,
+  env: Record<string, string | undefined> = process.env,
+): Promise<Record<string, string>> {
+  const token = env['GITHUB_TOKEN'] ?? env['GH_TOKEN']
+  const listing = await get(
+    `https://api.github.com/repos/${REPO}/contents/${DIR}?ref=${encodeURIComponent(ref)}`,
+    {
+      headers: {
+        accept: 'application/vnd.github+json',
+        ...(token ? { authorization: `Bearer ${token}` } : {}),
+      },
+    },
+  )
+  if (!listing.ok) throw new Error(`GitHub answered ${listing.status} listing ${DIR} at ${ref}`)
+  const names = ((await listing.json()) as Array<{ name: string; type: string }>)
+    .filter((e) => e.type === 'file' && e.name.endsWith('.md') && e.name !== 'STATUS.md')
+    .map((e) => e.name)
+  const texts = await Promise.all(
+    names.map(async (name) => {
+      const url = `https://raw.githubusercontent.com/${REPO}/${ref}/${DIR}/${name}`
+      const r = await get(url)
+      if (!r.ok) throw new Error(`GitHub answered ${r.status} for ${url}`)
+      return r.text()
+    }),
+  )
+  return Object.fromEntries(names.map((n, i) => [n.slice(0, -3), texts[i]!]))
 }
 
 interface Section {
@@ -137,7 +187,10 @@ export function searchDocs(
   }))
 }
 
-export async function docsCmd(args: readonly string[]): Promise<number> {
+export async function docsCmd(
+  args: readonly string[],
+  load: (ref: string) => Promise<Record<string, string>> = loadPages,
+): Promise<number> {
   const parsed = parseDocsArgs(args)
   if (parsed.error) return refuse('docs', args, parsed.error, 'VX_E_USAGE')
   if (parsed.terms.length === 0) {
@@ -148,8 +201,19 @@ export async function docsCmd(args: readonly string[]): Promise<number> {
       'VX_E_USAGE',
     )
   }
-  const { PAGES } = await import('./docs-corpus.js')
-  const hits = searchDocs(PAGES, parsed.terms, parsed.limit)
+  const ref = docsRef()
+  let pages: Record<string, string>
+  try {
+    pages = await load(ref)
+  } catch (err) {
+    return refuse(
+      'docs',
+      args,
+      `cannot read the docs at ${ref} from GitHub (${err instanceof Error ? err.message : String(err)}); they are on the site, ${SITE}`,
+      'VX_E_NETWORK',
+    )
+  }
+  const hits = searchDocs(pages, parsed.terms, parsed.limit)
   const query = parsed.terms.join(' ')
   if (parsed.json) {
     process.stdout.write(`${JSON.stringify({ query, hits })}\n`)
@@ -157,7 +221,7 @@ export async function docsCmd(args: readonly string[]): Promise<number> {
   }
   if (hits.length === 0) {
     process.stdout.write(
-      `vx docs: no section of ${Object.keys(PAGES).join(', ')} holds every word of "${query}"; try fewer words, or ${SITE}llms.txt\n`,
+      `vx docs: no section of the docs at ${ref} holds every word of "${query}"; try fewer words, or ${SITE}llms.txt\n`,
     )
     return 0
   }

package/src/cli/help.ts

@@ -117,7 +117,7 @@ export function helpText(pluginCommands: readonly string[] = []): string {
     '  vx cache clean [--older-than <duration>] [--max-size <size>] [--global] [--dry-run] [--format pretty|json] [--cache-dir <path>]',
     '  vx lock [--check] [--format pretty|json]',
     '  vx init [--dry [--format pretty|json]] [--force] [--mjs] [--native|--keep] [--plugin <seam>]',
-    '  vx upgrade [TAG]',
+    '  vx upgrade [TAG] [-g|--global]',
     '  vx show [PROJECT[#TASK] | TASK] [--filter <pattern>] [--affected[=<ref>]] [--format pretty|json]',
     '  vx info [--format pretty|json] [--cache-dir <path>]',
     '  vx why (TASK | PKG#TASK) [--run RUNID] [--format pretty|json] [--cache-dir <path>]',
@@ -274,6 +274,12 @@ export function helpText(pluginCommands: readonly string[] = []): string {
     '                       test (executor, cache, telemetry, schedule, admit, commands,',
     '                       project, graph, key).',
     '',
+    'Upgrade:',
+    '  vx upgrade [TAG]     Bring vx to TAG (default: latest) the way it was installed.',
+    "                       In a project: the project's vx, its @vzn/vx-* plugins and",
+    '                       the global vx that ran it, to one release.',
+    '      -g, --global     Only the global vx: no project, no plugin.',
+    '',
     'Shell completions:',
     '  vx completions <shell>   Print a completion script for bash, zsh or fish: the',
     '                           verbs (plugin verbs of this workspace included) and',
@@ -281,10 +287,10 @@ export function helpText(pluginCommands: readonly string[] = []): string {
     '                           or write it where the shell loads completions from.',
     '',
     'Docs:',
-    '  vx docs <query>      Search the reference offline (cli, schema, caching, execution,',
-    '                       patterns, security, features): the sections holding every',
-    '                       word of the query print whole, best first, with their URL;',
-    '                       an error code (vx docs VX_E_CYCLE) prints its fix alone.',
+    "  vx docs <query>      Search the reference at this version's tag on GitHub (online):",
+    '                       the sections holding every word of the query print whole,',
+    '                       best first, with their URL; an error code',
+    '                       (vx docs VX_E_CYCLE) prints its fix alone.',
     '      --limit N        How many sections (default 3).',
     '      --format json    {query, hits: [{page, heading, url, text}]}.',
     '',

package/src/cli/plan-format.ts

@@ -148,7 +148,10 @@ export interface PlanTaskJson {
 }
 
 /** `affectedBase`: the ref a bare `--affected` guessed (or was given), so a reader knows what the diff was against. */
-export function formatPlanJson(plan: RunPlan, affectedBase?: string): string {
+export function formatPlanJson(
+  plan: Pick<RunPlan, 'tasks' | 'predicted' | 'downloadDowngrades'>,
+  affectedBase?: string,
+): string {
   return (
     JSON.stringify(
       {

package/src/cli/run.ts

@@ -595,9 +595,16 @@ export async function runCmd(args: readonly string[]): Promise<number> {
   const scopeOut: { affectedBase?: string } = {}
   const resolved = await resolveRunOptions(parsed, cwd, tasks, 'run', scopeOut)
   if ('error' in resolved) return refuse('run', args, resolved.error, resolved.code ?? 'VX_E_USAGE')
+  // `--dry=json` prints a plan even when there is nothing to run: a script
+  // reading stdout broke exactly then (Growth, 2026-10-16).
+  const nothingToRun = (): 0 => {
+    if (parsed.dry === 'json')
+      process.stdout.write(formatPlanJson({ tasks: [] }, scopeOut.affectedBase))
+    return 0
+  }
   if ('nothingSelected' in resolved) {
     sayNotice('info', 'vx run', resolved.nothingSelected)
-    return 0
+    return nothingToRun()
   }
   const opts = resolved
   // The raw invocation, recorded on the `invocations` row so dashboards
@@ -628,11 +635,11 @@ export async function runCmd(args: readonly string[]): Promise<number> {
       // said no affected project declared a task one did (X-141).
       if (plan.noneAffected !== undefined) {
         sayLine('info', plan.noneAffected, 'vx run')
-        return 0
+        return nothingToRun()
       }
       if (opts.selectedByDiff === true) {
         sayNotice('info', 'vx run', `no affected project declares task(s): ${tasks.join(', ')}`)
-        return 0
+        return nothingToRun()
       }
       return refuse(
         'run',

package/src/cli/select.ts

@@ -36,6 +36,7 @@ import {
 } from '../util/index.js'
 import {
   claimedAffected,
+  claimedExtraFiles,
   fingerprintClaims,
   gitOfDiscovery,
   hasHook,
@@ -123,6 +124,7 @@ async function workspaceFingerprintClaims(
   return {
     files: new Set(claims.keys()),
     affected: (change) => claimedAffected(claims.get(change.file)!, change, ctx),
+    extraFiles: (file, bytes) => claimedExtraFiles(claims.get(file)!, file, bytes),
   }
 }
 

package/src/cli/upgrade.ts

@@ -712,6 +712,31 @@ export async function upgradeGlobal(
   })
 }
 
+/**
+ * `vx upgrade -g`: bring this vx, the global one, to `version` and nothing
+ * else (owner, 2026-10-16) — no project's package.json, no plugin. The
+ * project's own vx refuses: no global ran.
+ */
+export async function upgradeOnlyGlobal(
+  self: string,
+  version: string,
+  current = VERSION,
+): Promise<void> {
+  if (current === version) {
+    ui.print('out', ui.status('info', 'vx upgrade', `global already at ${current}`))
+    return
+  }
+  // Read from the binary's own directory, not cwd: a project there is not this install's.
+  const install = managedInstall(self, path.dirname(self))
+  if (install?.scope === 'project') {
+    throw new UserError(
+      `vx upgrade -g: no global vx ran — ${self} is the project's own. Install one (npm install -g ${PACKAGE}), or run \`vx upgrade\` to move the project's`,
+    )
+  }
+  if (install === null) await upgradeBinary(self, version, current, 'global ')
+  else await upgradeManaged(install, version, current, 'global ')
+}
+
 /** `run`, its refusal naming `what` after the verb: a run that moves two installs says which failed. */
 async function named(what: string, run: () => Promise<void>): Promise<void> {
   try {
@@ -722,7 +747,9 @@ async function named(what: string, run: () => Promise<void>): Promise<void> {
   }
 }
 
-export async function upgradeCmd(args: readonly string[]): Promise<number> {
+export async function upgradeCmd(argv: readonly string[]): Promise<number> {
+  const global = argv.some((a) => a === '-g' || a === '--global')
+  const args = argv.filter((a) => a !== '-g' && a !== '--global')
   const unknown = args.find((a) => a.startsWith('-'))
   if (unknown !== undefined) {
     sayNotice(
@@ -746,10 +773,18 @@ export async function upgradeCmd(args: readonly string[]): Promise<number> {
     )
   }
   const dest = process.execPath
+  const handedOffFrom = process.env['VX_HANDED_OFF']
+  if (global) {
+    // A launcher from before -g handed the call over: the global is the one that did.
+    const version = await targetVersion(tag)
+    if (handedOffFrom !== undefined) await upgradeGlobal(handedOffFrom, version)
+    else await upgradeOnlyGlobal(dest, version)
+    return 0
+  }
   const install = managedInstall(dest, process.cwd())
   // A global vx handed this run to the project's own: both move, to one
   // version, the project first (owner, 2026-10-15).
-  const from = process.env['VX_HANDED_OFF']
+  const from = handedOffFrom
   if (from !== undefined) {
     const version = await targetVersion(tag)
     await named('project vx', () =>

package/src/cli/watch-filter.ts

@@ -33,13 +33,8 @@ export function isIgnoredWatchPath(rel: string): boolean {
   const segments = rel.split(path.sep)
   for (let i = 1; i <= segments.length; i++) if (isIgnoredDir(segments.slice(0, i))) return true
   if (IGNORED_SUFFIXES.some((suf) => rel.endsWith(suf))) return true
-  const name = segments[segments.length - 1]!
-  // A restore's own temporary file, never an input (`ALWAYS_IGNORE`):
-  // renamed away before the judgement, it read as a deletion and ran one
-  // more cycle where an uncached task makes ignored paths count.
-  if (name.startsWith('.vx-tmp-')) return true
   // `vx lock`'s review copy: no input, so a re-lock is no cycle.
-  return name === 'vx.lock.json'
+  return segments[segments.length - 1] === 'vx.lock.json'
 }
 
 /**

package/src/cli/watch-fs.ts

@@ -16,7 +16,8 @@ export const IGNORED_SEGMENTS = ['node_modules', '.git']
 export function isIgnoredDir(segments: readonly string[]): boolean {
   const last = segments.length - 1
   if (IGNORED_SEGMENTS.includes(segments[last]!)) return true
-  return segments[last] === 'cache' && segments[last - 1] === '.vx'
+  // vx's cache, and where its restores stage (archive.ts).
+  return (segments[last] === 'cache' || segments[last] === 'tmp') && segments[last - 1] === '.vx'
 }
 
 /**

package/src/exec/runner.ts

@@ -50,6 +50,10 @@ export interface RunResult {
   /** `Bun.spawn` threw: no shell ran, so its 127 is vx's and says nothing
    *  about the command (A-41). */
   spawnFailed?: true
+  /** The shell exited while a process it started still held its
+   *  stdout/stderr past the drain bound (`POST_EXIT_CUT_LINE`): that process
+   *  may still write the task's outputs, so the result is not saved. */
+  leftRunning?: true
 }
 
 /**
@@ -1034,6 +1038,7 @@ export async function runCommand(opts: RunOptions): Promise<RunResult> {
     stderr,
     ...(proc.signalCode ? { signal: proc.signalCode } : {}),
     ...(timeout.timedOut() ? { timedOut: true } : {}),
+    ...(cut ? { leftRunning: true } : {}),
     ...resourceUsageToCpuRss(proc.resourceUsage(), rssFloorFor),
   }
 }

package/src/exec/sandbox-runtime.ts

@@ -1344,7 +1344,7 @@ async function wrapIn(
   if (process.platform === 'darwin') {
     const rules = [
       ...macProfileRules(args.config),
-      ...darwinWallRules(args.config, baselines.allowRead),
+      ...darwinGrantRules(args.config, baselines.allowRead, baselines.denyRead),
     ]
     try {
       if (rules.length > 0) wrapped = injectProfileRules(wrapped, rules)
@@ -2270,6 +2270,7 @@ async function runSandboxedOnce(
     violations,
     ...(proc.signalCode ? { signal: proc.signalCode } : {}),
     ...(timeout.timedOut() ? { timedOut: true } : {}),
+    ...(cut ? { leftRunning: true } : {}),
     // Linux: the task's CPU and peak never reach this wait. bwrap runs it
     // in a pid namespace (`--unshare-pid`), and what the namespace's
     // processes used is not folded into bwrap's usage: a 500 ms busy loop
@@ -2570,6 +2571,85 @@ export function wallsGlobsReach(grants: readonly string[], walls: readonly strin
   return walls.filter((w) => heads.some((h) => atOrUnder(w, h)))
 }
 
+/**
+ * macOS: the grant rules vx appends. The listings come first so a wall's
+ * deny, later, wins: SBPL is last-match-wins.
+ */
+export function darwinGrantRules(
+  c: Pick<ResolvedSandboxConfig, 'wallsReached' | 'allowRead' | 'allowWrite'>,
+  baseAllowRead: readonly string[],
+  anchors: readonly string[],
+): string[] {
+  return [...darwinAncestorRules(c, anchors), ...darwinWallRules(c, baseAllowRead)]
+}
+
+/**
+ * macOS: each directory above a grant may be listed, as on Linux. bwrap
+ * makes every directory above a mount, so a task granted
+ * `../vx-*\/package.json` could glob it from `..`; seatbelt matches paths
+ * and refused the listing (EPERM), so `@vzn/vx-docs#import` failed on
+ * every Mac (2026-10-17). Above the glob that is each literal directory
+ * strictly inside a deny anchor (outside one, all is readable already);
+ * a directory the glob itself names (`vx-a/`) is matched as a regex, and
+ * under a `**` any directory is. The rules grant directories only, never
+ * a file, and come before the wall denies, which still win.
+ *
+ * A listing shows every name in the directory, where Linux's scaffold
+ * shows only what it mounted: names, never a file's data. Not the anchor
+ * itself: Bun, shown the workspace root's `package.json` it
+ * may not read, failed with "Cannot read file" (EPERM).
+ */
+export function darwinAncestorRules(
+  c: Pick<ResolvedSandboxConfig, 'allowRead' | 'allowWrite'>,
+  anchors: readonly string[],
+): string[] {
+  const literals = new Set<string>()
+  const patterns = new Set<string>()
+  // Grants are canonical already (`resolveSandboxConfig`), and so is each
+  // directory above one: no realpath here, at every spawn.
+  const inside = (d: string): boolean => anchors.some((a) => d !== a && atOrUnder(d, a))
+  for (const g of [...c.allowRead, ...c.allowWrite]) {
+    const named = namedPath(g)
+    const head = g.slice(0, g.search(MOUNT_WILDCARDS))
+    const cut = head.lastIndexOf('/')
+    const top = named !== undefined ? path.dirname(named) : head.slice(0, cut) || '/'
+    for (let d = top; inside(d); d = path.dirname(d)) literals.add(d)
+    if (named !== undefined || g.includes('\\')) continue
+    let re = top === '/' ? '' : regexLiteral(top)
+    for (const part of g
+      .slice(cut + 1)
+      .split('/')
+      .slice(0, -1)) {
+      if (part === '**') {
+        patterns.add(`^${re}(/.*)?$`)
+        break
+      }
+      re += `/${part
+        .replace(/[.^$+{}()|]/g, '[$&]')
+        .replaceAll('*', '[^/]*')
+        .replaceAll('?', '[^/]')}`
+      patterns.add(`^${re}$`)
+    }
+  }
+  // A name seatbelt's quoted string cannot hold keeps today's refusal
+  // rather than failing the task (`sbplResolvedPath` would throw).
+  const spellable = (p: string): boolean => !UNSPELLABLE.test(p)
+  return [
+    ...[...literals].filter(spellable).map((d) => `(allow file-read-data (literal "${d}"))`),
+    ...[...patterns]
+      .filter(spellable)
+      .map((r) => `(allow file-read-data (require-all (vnode-type DIRECTORY) (regex #"${r}")))`),
+  ]
+}
+
+// eslint-disable-next-line no-control-regex -- the control range is the point
+const UNSPELLABLE = /["'\\\x00-\x1f\x7f]/
+
+/** A real path as a regex matching only itself: each special in a class of one. */
+function regexLiteral(p: string): string {
+  return p.replace(/[.^$+{}()|*?[\]]/g, (ch) => `[${ch}]`)
+}
+
 /**
  * macOS: the walls a glob grant reaches, denied at the profile's tail
  * (SBPL is last-match-wins). SRT re-emits a wall's deny after the allows

package/src/graph/priorities.ts

@@ -23,7 +23,20 @@ export function tieredReverseDepCount(
   restoreTier: ReadonlySet<string>,
 ): Map<string, number> {
   const exec = new Map<string, TaskNode>()
-  for (const [id, node] of nodes) if (!restoreTier.has(id)) exec.set(id, node)
+  let runsAny = false
+  for (const [id, node] of nodes) {
+    if (restoreTier.has(id)) continue
+    exec.set(id, node)
+    if (node.config.exec !== undefined) runsAny = true
+  }
+  // Nothing outside the restore tier runs a command (a warm run: restores
+  // and groups), so no order finishes any work sooner: everything ranks 0.
+  // The weights below were 10 ms of a 1,000-project warm run.
+  if (!runsAny) {
+    const zeros = new Map<string, number>()
+    for (const id of nodes.keys()) zeros.set(id, 0)
+    return zeros
+  }
   // An exec tier with no edge inside it (a warm run's groups) counts 0
   // everywhere: no closure to build.
   let linked = false

package/src/handoff.ts

@@ -5,6 +5,11 @@
 // walk runs before anything else loads, through `Bun.file(…).exists()`:
 // importing `node:fs` alone was ~1.1 ms of a 4 ms start (2026-10-13).
 
+/** `vx upgrade -g`: moves only the global vx, so it never hands off (owner, 2026-10-16). */
+export function upgradesOnlyItself(argv: readonly string[]): boolean {
+  return argv[0] === 'upgrade' && argv.some((a) => a === '-g' || a === '--global')
+}
+
 /**
  * The project-local vx to run instead of this one, or null: the workspace
  * root's ({@link workspaceFile}) `node_modules/@vzn/vx`, run through its

package/src/history/history.ts

@@ -263,56 +263,66 @@ export class LocalHistoryProvider implements HistoryProvider {
    * 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.
+   * run. One statement per tier, an index probe per task on `(project,
+   * task, source, id)` inside it: 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>()
     this.lackedBranchHistory = false
     if (wanted.size === 0) return out
-    // Tiers, first answer wins.
-    type Tier = (project: string, task: string) => Array<{ ms: number }>
+    // Tiers, first answer wins: a WHERE over `task_durations`, its params,
+    // and how many of the newest rows it reads.
+    type Tier = { where: string; params: string[]; limit: 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}`,
-      )
     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 }>)
+      tiers.push({ where: 'source = ?', params: [branchSource(this.branch)], limit: FORECAST_RUNS })
     }
     // One probe on the partial index first: a store with no import costs
-    // no query per task.
+    // no tier.
     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 }>)
+      tiers.push({ where: `source = 'remote'`, params: [], limit: 1 })
     }
-    const any = newest(`source LIKE 'branch:%'`)
-    tiers.push((p, t) => any.all(p, t) as Array<{ ms: number }>)
+    tiers.push({ where: `source LIKE 'branch:%'`, params: [], limit: FORECAST_RUNS })
     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)
+    let pending = [...wanted]
+    let ownAnswered = 0
+    for (const tier of tiers) {
+      if (pending.length === 0) break
+      // One statement per tier over every task it is asked for: an index
+      // probe per task inside SQLite, where a query per task from here was
+      // 31-40 ms of 2,000 tasks against 5-8.
+      const rows = this.db
+        .query(
+          `SELECT j.key AS i, (SELECT group_concat(ms) FROM (
+             SELECT duration_ms AS ms FROM task_durations
+             WHERE project = j.value ->> 0 AND task = j.value ->> 1 AND ${tier.where}
+             ORDER BY id DESC LIMIT ${tier.limit})) AS ds
+           FROM json_each(?) AS j`,
+        )
+        .all(...tier.params, JSON.stringify(pending.map(splitTaskId))) as {
+        i: number
+        ds: string | null
+      }[]
+      const left: string[] = []
+      for (const r of rows) {
+        const id = pending[r.i]!
+        if (r.ds === null) {
+          left.push(id)
+          continue
+        }
+        const durations = r.ds
+          .split(',')
+          .map(Number)
+          .sort((x, y) => x - y)
         out.set(id, pickPercentile(durations, 0.5))
-        answered = tier
-        break
+        if (tier === own) ownAnswered++
       }
-      if (answered !== own) lacked = true
+      pending = left
     }
-    this.lackedBranchHistory = lacked
+    this.lackedBranchHistory = ownAnswered < wanted.size
     return out
   }
 

package/src/index.ts

@@ -22,7 +22,7 @@ export { machineMemoryBytes, machineParallelism } from './util/index.js'
 // How core reads a task glob — its spelling, and which characters are
 // wildcards (`[` `]` are not; item 667) — for a plugin that turns declared
 // outputs into something else (`@vzn/vx-reapi`'s literal `output_paths`).
-export { isLiteralPattern, normalizeGlob } from './util/index.js'
+export { isLiteralPattern, normalizeGlob, restorableOutput } from './util/index.js'
 
 // Schema types and helpers (used by user vx.config files and presets).
 export type {
@@ -83,9 +83,19 @@ export type {
   CacheLayer,
   PluginCache,
   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'
+export type {
+  PluginSecrets,
+  SecretRequest,
+  SecretUnavailable,
+  SecretUnavailableReason,
+} from './util/index.js'
 
 // Workspace discovery + the project/config catalog surface — an
 // out-of-process service/CLI needs these. `loadProjectConfig` is the RAW

package/src/orchestrator/deferred-outputs.ts

@@ -15,7 +15,7 @@
 import {
   cleanOutputs,
   committedFiles,
-  resolveOutputs,
+  resolveOutputTree,
   type CacheLayer,
   type GitFilesCache,
 } from '../cache/index.js'
@@ -144,7 +144,7 @@ export class DeferredOutputs {
         `could not fetch deferred outputs of ${taskId}: ${msg} — re-run it with --force, or use --cache-download=all`,
       )
     }
-    const outputFiles = await resolveOutputs(cleanArgs)
+    const { files: outputFiles, emptyDirs } = await resolveOutputTree(cleanArgs)
     this.args.gitFilesCache?.markOutputsChanged(
       producer.projectDir,
       outputFiles.map((f) => f.slice(producer.projectDir.length + 1)),
@@ -157,6 +157,7 @@ export class DeferredOutputs {
         hash: entry.hash,
         projectDir: producer.projectDir,
         outputFiles,
+        ...(emptyDirs.length > 0 ? { outputDirs: emptyDirs } : {}),
         entry: entry.entry,
       })
     }