@vzn/vx 0.0.643 → 0.0.645

package/src/orchestrator/prepare.ts

@@ -26,20 +26,18 @@ import {
   writesRunStore,
   type PluginCache,
   type ResolvedRemote,
-  BranchScope,
   applyGitEnumeration,
   gitPathspecs,
   MAX_SCOPED_PATHSPECS,
   startGitEnumeration,
   lazyGitEnumeration,
   measureFsClockLag,
+  DEFAULT_STORE,
 } from '../cache/index.js'
 import {
   buildPackageGraph,
   computeNestedProjectDirs,
   findWorkspaceRoot,
-  type AffectedChanges,
-  branchChanges,
   configuredBaseBranch,
   type LoadReads,
   PROJECT_CONFIG_FILENAMES,
@@ -79,17 +77,17 @@ import {
   lockReader,
   type LoadedProjects,
 } from './projects.js'
-import { keptByAffected, keyedByChange } from './affected-tasks.js'
+import { keptByAffected } from './affected-tasks.js'
 import { applyGraphStage } from './graph-stage.js'
 import { keyExcludedDependencies } from './excluded-keys.js'
 import { FingerprintWatch } from './fingerprint-watch.js'
 import type { VxPlugin } from './plugin.js'
 import { askIgnoredOutputs, gatedOutputs } from './stable-keys.js'
-import { currentBranch, resolveCacheScope } from './run-context.js'
+import { cacheRefs, currentBranch, resolveCacheScope } from './run-context.js'
 import { createHashCache, type HashCache } from './task-hash.js'
 import { type Logger, warnOf } from '../report/index.js'
 import type { RunOptions } from './options.js'
-import { runRules } from '../settings.js'
+import { resolveSetting, runRules } from '../settings.js'
 
 export interface PreparedRun {
   workspaceRoot: string
@@ -263,7 +261,7 @@ export async function prepareRun(options: RunOptions, log: Logger): Promise<Prep
     options.cacheScope ??
     resolveCacheScope(
       workspaceRoot,
-      branchFacts.scope,
+      branchFacts.trusted === true ? null : branchFacts.scope,
       plugins.some((p) => p.cache !== undefined),
       baseBranch,
     )
@@ -289,33 +287,6 @@ export async function prepareRun(options: RunOptions, log: Logger): Promise<Prep
     reused !== undefined
       ? Promise.resolve(reused.projects)
       : discoverProjects(workspaceRoot, readLock, plugins, cacheDir, warnOf(log), git)
-  // What the branch changed decides which tasks read the scope (owner,
-  // 2026-10-17). Only a scoped run's first remote call asks git: a run the
-  // local cache answers makes no remote call, and diffing beside discovery
-  // cost it 20-60 ms at 1k-5k projects.
-  const scopeChanges: (() => Promise<AffectedChanges>) | undefined =
-    cacheScope === undefined
-      ? undefined
-      : options.scopeChanges !== undefined
-        ? async () => options.scopeChanges!
-        : () =>
-            branchChanges(
-              workspaceRoot,
-              options.scopeBase ?? branchFacts.base,
-              baseBranch,
-              discovering,
-              {
-                untracked: async () => (await git.start()).untracked,
-                // A scoped enumeration lists only its projects: null asks git.
-                links: async () => {
-                  const g = await git.start()
-                  if (!g.scopes.includes('.')) return null
-                  const out: string[] = []
-                  for (const [rel, oid] of g.trusted) if (oid.startsWith('120000:')) out.push(rel)
-                  return out
-                },
-              },
-            )
   const projectMetas = await discovering
   mark('discover projects')
 
@@ -376,6 +347,12 @@ export async function prepareRun(options: RunOptions, log: Logger): Promise<Prep
     options.artifactCeiling,
     'open',
     await storeRoot,
+    {
+      embeddings: (resolveSetting('cache.store.embeddings', workspaceConfig).value ??
+        DEFAULT_STORE.embeddings) as number,
+      decompress: (resolveSetting('cache.store.decompress', workspaceConfig).value ??
+        DEFAULT_STORE.decompress) as boolean,
+    },
   )
   const unwritable = localCache.readOnlyNotice()
   if (unwritable !== null) warnOf(log)(`[vx] ${unwritable}`)
@@ -509,9 +486,6 @@ export async function prepareRun(options: RunOptions, log: Logger): Promise<Prep
   // cache plugin.
   let cache: CacheLayer
   const remotes: ResolvedRemote[] = []
-  // A scope only picks remote keys (owner, 2026-10-17): the local store
-  // keeps every branch's entries under the task keys.
-  const branchScope = cacheScope === undefined ? undefined : new BranchScope(cacheScope)
   if (options.remoteCache) {
     remotes.push({
       remote: options.remoteCache,
@@ -522,16 +496,19 @@ export async function prepareRun(options: RunOptions, log: Logger): Promise<Prep
   }
   try {
     cache = options.remoteCache
-      ? new LayeredCache(localCache, remotes, branchScope)
+      ? new LayeredCache(localCache, remotes, options.uploadConcurrency)
       : await resolveCache(plugins, {
           workspaceRoot,
           cacheDir,
           warn: warnOf(log),
           scope: cacheScope,
+          refs: cacheRefs(workspaceRoot, baseBranch),
           localCache,
           policy,
           remotes,
-          ...(branchScope !== undefined ? { branch: branchScope } : {}),
+          ...(options.uploadConcurrency !== undefined
+            ? { uploadConcurrency: options.uploadConcurrency }
+            : {}),
         })
   } catch (err) {
     // A cache plugin that throws or returns something off-contract is
@@ -763,13 +740,6 @@ export async function prepareRun(options: RunOptions, log: Logger): Promise<Prep
     if (hasHook(plugins, 'key')) {
       await applyKeyHooks(plugins, nodes, { workspaceRoot, cacheDir, warn: warnOf(log) })
     }
-    // The final inputs decide which tasks the branch changed: they read
-    // the scope, every other task the default key.
-    if (branchScope !== undefined && scopeChanges !== undefined) {
-      branchScope.routeTasks(async () =>
-        keyedByChange(nodes, await scopeChanges(), projects, packageGraph),
-      )
-    }
     refuseFiltersThroughGroups(nodes)
     const exclude = options.excludeDependencies
     let keyOnly: ReadonlyMap<string, TaskNode> = new Map()

package/src/orchestrator/projects.ts

@@ -71,7 +71,14 @@ export async function loadWorkspacePlugins(
   const setBranch = (facts: BranchFacts): void => {
     if (facts.scope !== undefined && !isCacheScope(facts.scope))
       throw new UserError(`setBranch: ${cacheScopeError('scope')}`)
-    if (facts.scope !== undefined) branch.scope = facts.scope
+    if (facts.trusted === true) {
+      delete branch.scope
+      branch.trusted = true
+    }
+    if (facts.scope !== undefined) {
+      branch.scope = facts.scope
+      delete branch.trusted
+    }
     if (facts.base !== undefined) branch.base = facts.base
   }
   await applyConfigHooks(plugins, workspaceConfig, { workspaceRoot, warn, setBranch }, (plugin) =>

package/src/orchestrator/remote-prefetch.ts

@@ -37,7 +37,7 @@ export interface PrefetchArgs {
   nestedDirsByProject: Map<string, string[]>
   gitFilesCache: GitFilesCache
   hashCache: HashCache
-  /** Cap on concurrent in-flight prefetches — the run's concurrency. */
+  /** Cap on concurrent in-flight prefetches (`cache.concurrency.download`). */
   concurrency: number
   /** When false (remote reads disabled), no prefetch fires. */
   remoteRead: boolean
@@ -75,10 +75,14 @@ export function startRemotePrefetch(args: PrefetchArgs): Promise<void> {
   // a still-in-flight prefetch can never ingest into a closed DB. Errors
   // degrade inside LayeredCache.prefetch; the catch keeps the handle
   // from ever rejecting.
-  return runPrefetch(args).catch(() => {})
+  const started = Promise.withResolvers<void>()
+  args.cache.probeFirst?.(started.promise)
+  return runPrefetch(args, started.resolve)
+    .catch(() => {})
+    .finally(started.resolve)
 }
 
-async function runPrefetch(args: PrefetchArgs): Promise<void> {
+async function runPrefetch(args: PrefetchArgs, probing: () => void): Promise<void> {
   const stableKeys = await deriveStableKeys(args)
   if (stableKeys.length === 0) return
 
@@ -94,7 +98,10 @@ async function runPrefetch(args: PrefetchArgs): Promise<void> {
   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
+  const asked = args.cache.remoteHasMany?.(uniqueHashes)
+  // Every lookup that waited on the probe now finds its hash in it.
+  probing()
+  const present = (await asked) ?? null
   if (present !== null) {
     args.cache.markRemoteAbsent?.(uniqueHashes.filter((h) => !present.has(h)))
     // The pre-mark above already answers a pull for an absent hash from

package/src/orchestrator/run-context.ts

@@ -553,10 +553,51 @@ export function localBranchScope(
   return branchCacheScope(repo, name)
 }
 
-/** `owner/repo` from a remote URL (its last two path segments); undefined for a local path. */
+/**
+ * The refs a remote reads, in order (2026-10-20): the run's own branch,
+ * then the branch it merges into, then the default branch, each once. On
+ * CI from its env (a GitHub pull request's head branch, a merge queue's
+ * queue ref, a GitLab pipeline's ref), else from git: the checked-out
+ * branch, then the default (`origin/HEAD`). A remote plugin keys or scopes
+ * its entries by them (`scope` on turboCache/nxCache); core keys nothing
+ * by them.
+ */
+export function cacheRefs(
+  workspaceRoot: string,
+  baseBranch: string | undefined,
+  env: NodeJS.ProcessEnv = process.env,
+): string[] {
+  const set = (v: string | undefined): string | undefined =>
+    v !== undefined && v.trim() !== '' ? v.trim() : undefined
+  const head = (b: string | undefined) => (b === undefined ? undefined : `refs/heads/${b}`)
+  let own: string | undefined
+  let base: string | undefined
+  if (env['GITHUB_ACTIONS'] === 'true') {
+    own = head(set(env['GITHUB_HEAD_REF'])) ?? set(env['GITHUB_REF'])
+    base = head(set(env['GITHUB_BASE_REF']))
+    const queue = /^refs\/heads\/gh-readonly-queue\/(.+)\/pr-\d+-[0-9a-f]+$/.exec(own ?? '')
+    if (queue !== null) base = head(queue[1])
+  } else if (env['GITLAB_CI'] === 'true') {
+    const tag = set(env['CI_COMMIT_TAG'])
+    own = tag !== undefined ? `refs/tags/${tag}` : head(set(env['CI_COMMIT_REF_NAME']))
+    base = head(set(env['CI_MERGE_REQUEST_TARGET_BRANCH_NAME']))
+  } else {
+    own = head(
+      (readHeadDirect(workspaceRoot) ?? captureGitContext(workspaceRoot, null, env)).branch ??
+        undefined,
+    )
+  }
+  const trunk = head(baseBranch ?? captureDefaultBranch(env, workspaceRoot) ?? undefined)
+  return [...new Set([own, base, trunk].filter((r): r is string => r !== undefined))]
+}
+
+/**
+ * The repository's path on its host (`owner/repo`; a GitLab subgroup's
+ * `group/sub/repo` whole, as `gitlab()` names it); undefined for a local path.
+ */
 function repoOfUrl(url: string): string | undefined {
   const parts = normalizeRemoteUrl(url).split('/')
-  return parts.length < 3 ? undefined : parts.slice(-2).join('/')
+  return parts.length < 3 ? undefined : parts.slice(1).join('/')
 }
 
 /** `.git/config`'s sections, each a key → value map (last wins); empty when it cannot be read. */
@@ -586,12 +627,13 @@ function gitConfigSections(workspaceRoot: string): Map<string, Map<string, strin
 
 /**
  * The run's cache scope (owner, 2026-10-17): `VX_CACHE_SCOPE` (empty: none),
- * else a plugin's (`setBranch`, `github()` on Actions), else, with a cache
- * plugin to share it, the branch's from git. Undefined: the default keys.
+ * else a plugin's (`setBranch`, `github()` on Actions; null: the plugin
+ * named the run trusted), else, with a cache plugin to share it, the
+ * branch's from git. Undefined: no scope. It keys plugin entries only.
  */
 export function resolveCacheScope(
   workspaceRoot: string,
-  pluginScope: string | undefined,
+  pluginScope: string | null | undefined,
   hasRemote: boolean,
   baseBranch: string | undefined,
   env: NodeJS.ProcessEnv = process.env,
@@ -602,6 +644,7 @@ export function resolveCacheScope(
     if (!isCacheScope(named)) throw cacheScopeEnvError()
     return named
   }
+  if (pluginScope === null) return undefined
   return pluginScope ?? (hasRemote ? localBranchScope(workspaceRoot, baseBranch, env) : undefined)
 }
 

package/src/orchestrator/run-settings.ts

@@ -14,6 +14,9 @@ const FROM_OPTIONS = {
   retries: 'run.retries',
   continueMode: 'run.continue',
   download: 'cache.download',
+  downloadConcurrency: 'cache.concurrency.download',
+  uploadConcurrency: 'cache.concurrency.upload',
+  restoreConcurrency: 'cache.concurrency.restore',
 } as const satisfies Partial<Record<keyof RunOptions, string>>
 
 /**

package/src/orchestrator/run.ts

@@ -11,6 +11,7 @@ import {
   type CachePolicy,
   cachesNothing,
   formatCachePolicy,
+  networkConcurrency,
   stopRuntimeProbes,
   sweepStaging,
 } from '../cache/index.js'
@@ -259,6 +260,10 @@ function refuseRunOptions(options: RunOptions): void {
   const { concurrency, retries, timeout } = options
   if (concurrency !== undefined && !(Number.isInteger(concurrency) && concurrency > 0))
     refuse('concurrency', concurrency, 'a positive integer')
+  for (const field of ['downloadConcurrency', 'uploadConcurrency', 'restoreConcurrency'] as const) {
+    const v = options[field]
+    if (v !== undefined && !(Number.isInteger(v) && v > 0)) refuse(field, v, 'a positive integer')
+  }
   if (retries !== undefined && !(Number.isInteger(retries) && retries >= 0))
     refuse('retries', retries, 'a non-negative integer')
   if (
@@ -618,7 +623,7 @@ async function runOnBus(
   // `vx cache clean` can evict entries the run just hit. Once-only
   // because the normal path closes before the persistent-task wait —
   // holding the handle open for a dev server's whole lifetime would be
-  // worse — and because close() re-runs its retention DELETEs.
+  // worse.
   let cacheClosed = false
   const closeCache = async (): Promise<void> => {
     if (cacheClosed) return
@@ -805,6 +810,8 @@ async function runOnBus(
         localWrite: policy.localWrite,
         remote: remoteCacheEnabled && (policy.remoteRead || policy.remoteWrite),
         traffic: prepared.localCache.traffic,
+        downloads: prepared.localCache.downloads,
+        uploads: prepared.localCache.uploads,
         notDownloaded: () => deferredOutputs.pending().length,
       },
       concurrency,
@@ -871,7 +878,7 @@ async function runOnBus(
           nestedDirsByProject,
           gitFilesCache,
           hashCache,
-          concurrency,
+          concurrency: options.downloadConcurrency ?? networkConcurrency(),
           remoteRead: policy.remoteRead,
           remoteWrite: policy.remoteWrite,
         }),
@@ -1088,6 +1095,7 @@ async function runOnBus(
     const outcomes = await runGraph({
       nodes,
       concurrency,
+      restoreConcurrency: options.restoreConcurrency ?? 2 * concurrency,
       settledOf: (o) => deferredSaves.get(o.node.id),
       ...(hasPooledExecutor(executors) ? { poolOf: poolOfPlacement(placements) } : {}),
       ...(admit !== undefined ? { admit } : {}),
@@ -1349,9 +1357,6 @@ async function runOnBus(
     // The miss path's output-directory snapshots first (miss-save.ts).
     await step('vx:snapshots', () => recordOutputDirSnapshots(cache, outputDirSnapshots))
     mark('output dir snapshots')
-    // Not on a stopped run: one stopped while it waited on another run's
-    // lock never held it, and its prune evicted under that run (item 858).
-    if (!stop.signal.aborted) await step('vx:retention', () => applyCacheRetention(prepared))
     // A plugin hears the run until its teardown and nothing after: released
     // only in the finally, its handlers heard a kept server through the
     // whole keep-alive wait below (C-66). Idempotent; the finally's stay.
@@ -1488,27 +1493,6 @@ async function runOnBus(
   }
 }
 
-/**
- * `cache.retention`, after every save and upload of this run
- * has landed (so nothing this run wrote is mid-flight) and before the cache
- * closes. Housekeeping, not the run's work: silent, and a failure is never
- * a failed run. Declared nowhere → one property read.
- */
-async function applyCacheRetention(prepared: PreparedRun): Promise<void> {
-  const ws = prepared.workspaceConfig
-  const maxAgeMs = resolveSetting('cache.retention.olderThan', ws).value as number | undefined
-  const maxBytes = resolveSetting('cache.retention.maxSize', ws).value as number | undefined
-  if (maxAgeMs === undefined && maxBytes === undefined) return
-  try {
-    await prepared.localCache.evictIfDue({
-      ...(maxAgeMs !== undefined ? { maxAgeMs } : {}),
-      ...(maxBytes !== undefined ? { maxBytes } : {}),
-    })
-  } catch {
-    // Housekeeping says nothing (owner): the next due run tries again.
-  }
-}
-
 /** Why an `--affected` run has nothing to run, said alike by the run and its `--dry` plan. */
 function noneAffected(prepared: PreparedRun, options: RunOptions): string {
   // A changed project declares the task, so `--affected`'s task walk is

package/src/orchestrator/task-hash.ts

@@ -97,9 +97,7 @@ export interface ComputeHashArgs {
  */
 export async function computeTaskHash(args: ComputeHashArgs): Promise<string> {
   if (isKeyless(args.node.config)) return keylessHash(args.node.id)
-  const key = await taskHash(args)
-  args.cache.noteKey?.(args.node.id, key)
-  return key
+  return taskHash(args)
 }
 
 async function taskHash(args: ComputeHashArgs): Promise<string> {

package/src/report/logger.ts

@@ -382,7 +382,6 @@ export function defaultLogger(
   let saved = 0
   let notSaved = 0
   let skippedCount = 0
-  let savedMs = 0
   // Each finished task's cache bucket by its key: its remote traffic moves it.
   const buckets = new Map<string, CacheBucket>()
   // The graph is done and vx's own closing steps run: the region stays,
@@ -530,7 +529,6 @@ export function defaultLogger(
               notSaved,
               miss: succeeded + failed - noCache,
               noCache,
-              savedMs,
               left: total - done - stopped - notRun,
               ...(etaMs !== undefined && !tail && !stopping ? { etaMs } : {}),
               buckets,
@@ -1028,12 +1026,10 @@ export function defaultLogger(
           case 'cache-hit':
             if (outcome.restored === false) upToDate++
             else restoredLocal++
-            savedMs += outcome.storedDurationMs ?? 0
             break
           case 'cache-hit-remote':
             if (outcome.restored === false) upToDate++
             else restoredRemote++
-            savedMs += outcome.storedDurationMs ?? 0
             break
           case 'skipped':
             skippedCount++

package/src/report/summary.ts

@@ -5,12 +5,12 @@
 
 import type { TaskOutcome } from '../graph/index.js'
 import { tallyOutcomes } from './tally.js'
-import { isCacheHit } from '../graph/index.js'
 import { outcomeLabel, projectOutcome, ranNoCache } from './events.js'
 import { isGroupTask } from '../graph/index.js'
 import {
   barWidth,
   ERROR,
+  formatBytes,
   formatElapsed,
   gradientRule,
   paint,
@@ -106,8 +106,6 @@ export interface SummaryStats {
   held?: { count: number; sumMs: number }
   /** Live section only: the forecast of what is left, from history. */
   etaMs?: number
-  /** The hits' stored exec times summed: the work the cache skipped. */
-  savedMs?: number
   /** A run of groups only: their names, so `0 tasks` says why. */
   emptyGroups?: readonly string[]
   /** Each finished task's cache bucket by its key and its id (its run bytes), so its remote traffic can move it. */
@@ -206,6 +204,9 @@ export interface RunContext {
       readonly inFlight: number
       readonly keys: ReadonlyMap<string, { uploading: number; failures: readonly string[] }>
     }
+    /** Bytes the run's remote hits pulled, and its landed uploads pushed (live refs). */
+    downloads?: { readonly bytes: number }
+    uploads?: { readonly bytes: number }
     /** Tasks whose outputs are still in the remote store. */
     notDownloaded: () => number
   }
@@ -338,9 +339,17 @@ export function formatSummarySection(
       ]
       // The layer words are dim; only the counts carry colour (M, 2026-10-15).
       if (local.length > 0) cacheParts.push(`${dim('local')} ${local.join(' ')}`)
+      // Each transfer count is followed by its bytes, dim: what the
+      // remote moved is the cost a hit or an upload paid.
+      const sized = (count: number, glyph: string, bytes: number | undefined): string[] =>
+        count === 0
+          ? []
+          : bytes === undefined || bytes === 0
+            ? n(count, glyph, REMOTE)
+            : [...n(count, glyph, REMOTE), dim(formatBytes(bytes))]
       const remote = [
-        ...n(b.restoredRemote, '\u2193', REMOTE),
-        ...n(b.uploaded, '\u2191', REMOTE),
+        ...sized(b.restoredRemote, '\u2193', layers.downloads?.bytes),
+        ...sized(b.uploaded, '\u2191', layers.uploads?.bytes),
         ...n(b.remoteFailed, '\u2717', ERROR),
         ...n(b.uploading, '\u21e1', ACCENT),
       ]
@@ -392,10 +401,6 @@ export function formatSummarySection(
     }
   }
   const timeParts = [total]
-  // What the cache paid back, beside what the run cost: the stored exec
-  // time of every hit, never the restore this run spent on it.
-  if ((stats.savedMs ?? 0) >= 1)
-    timeParts.push(paint(SUCCESS, `${formatElapsed(stats.savedMs!)} saved`, colors))
   // The live run's forecast leads the spread: the one number on the row
   // that is about the future.
   if (stats.etaMs !== undefined)
@@ -492,9 +497,6 @@ export function formatRunSummary(
   const durations = outcomes
     .filter((o) => (o.status === 'success' || o.status === 'failed') && !isGroupTask(o.node))
     .map((o) => o.durationMs)
-  let savedMs = 0
-  for (const o of outcomes)
-    if (isCacheHit(o.status) && !isGroupTask(o.node)) savedMs += o.storedDurationMs ?? 0
   const heldOutcomes = outcomes.filter((o) => o.admissionHeldMs !== undefined)
   const notRun = outcomes.filter((o) => neverStarted(o) && !isGroupTask(o.node)).length
   const emptyGroups = outcomes.every((o) => isGroupTask(o.node))
@@ -515,7 +517,6 @@ export function formatRunSummary(
       notSaved: outcomes.filter((o) => !isGroupTask(o.node) && ranUnsaved(o)).length,
       miss: t.total - t.skipped - (t.cachedLocal + t.cachedRemote) - noCache,
       noCache,
-      savedMs,
       spread:
         durations.length > 0
           ? {

package/src/settings.ts

@@ -17,7 +17,8 @@ export type SettingKind =
   | { readonly type: 'concurrency' }
   // `zero`: 0 is a value ("wait for nothing not already done"), not a typo.
   | { readonly type: 'duration'; readonly timer?: true; readonly zero?: true }
-  | { readonly type: 'size' }
+  // `off`: `false` is a value, 0 bytes (the thing the size bounds is off).
+  | { readonly type: 'size'; readonly off?: true }
   | { readonly type: 'bool' }
   | { readonly type: 'enum'; readonly values: readonly string[] }
   | { readonly type: 'string' }
@@ -115,18 +116,6 @@ export const SETTINGS: readonly Setting[] = [
     doc: 'Where the cache lives, relative to the workspace root; named, it holds the whole cache.',
     flag: { verb: 'run', name: '--cache-dir' },
   },
-  {
-    path: 'cache.retention.maxSize',
-    kind: { type: 'size' },
-    default: 'none',
-    doc: "Evict least-recently-used entries at each run's end until the cache is under this (`'10GB'`).",
-  },
-  {
-    path: 'cache.retention.olderThan',
-    kind: { type: 'duration' },
-    default: 'none',
-    doc: "Evict entries unused for this long at each run's end (`'30d'`).",
-  },
   {
     path: 'cache.policy',
     kind: { type: 'string' },
@@ -138,9 +127,30 @@ export const SETTINGS: readonly Setting[] = [
     path: 'cache.scope',
     kind: { type: 'string' },
     default: "the branch's, `<owner>/<repo>:<branch>`, with a remote cache off `baseBranch`",
-    doc: "A branch's remote entries (`'vznjs/vx:feat-x'`): tasks the branch changed read the scope's key, the rest the default key; the local cache never uses it. Empty: no scope.",
+    doc: "The branch scope plugin entries are keyed under (`'vznjs/vx:feat-x'`); task keys never carry it. Empty: no scope.",
     config: false,
   },
+  {
+    path: 'cache.concurrency.download',
+    kind: { type: 'int', min: 1 },
+    default: 'min(96, max(cores × 3, 64))',
+    doc: 'Remote downloads at once.',
+    flag: { verb: 'run', name: '--cache-concurrency-download' },
+  },
+  {
+    path: 'cache.concurrency.upload',
+    kind: { type: 'int', min: 1 },
+    default: 'min(96, max(cores × 3, 64))',
+    doc: 'Uploads at once, per remote.',
+    flag: { verb: 'run', name: '--cache-concurrency-upload' },
+  },
+  {
+    path: 'cache.concurrency.restore',
+    kind: { type: 'int', min: 1 },
+    default: 'twice `run.concurrency`',
+    doc: 'Local hits restoring outputs at once.',
+    flag: { verb: 'run', name: '--cache-concurrency-restore' },
+  },
   {
     path: 'cache.download',
     kind: { type: 'enum', values: ['all', 'toplevel', 'none'] },
@@ -170,6 +180,18 @@ export const SETTINGS: readonly Setting[] = [
     task: 'cache.outputs.clean',
     env: false,
   },
+  {
+    path: 'cache.store.embeddings',
+    kind: { type: 'size', off: true },
+    default: "'32KiB'",
+    doc: 'Keep an entry up to this size inside the cache index, one zstd tar, rather than as files; `false` keeps none.',
+  },
+  {
+    path: 'cache.store.decompress',
+    kind: { type: 'bool' },
+    default: 'true',
+    doc: 'Keep a larger entry as its plain files, which a hit copies or clones out; off, as one `.tar.zst`.',
+  },
   {
     path: 'cache.upload.failures',
     kind: { type: 'enum', values: ['ci', 'local', 'always'] },
@@ -250,7 +272,7 @@ export function kindHint(kind: SettingKind): string {
         ? "a duration like '500ms', '30s' or '5m', at most 24 days"
         : "a duration like '45s', '12h' or '30d'"
     case 'size':
-      return "a size like '500MB' or '10GB'"
+      return kind.off === true ? "false, or a size like '32KiB'" : "a size like '500MB' or '10GB'"
     case 'bool':
       return 'true or false'
     case 'enum':
@@ -298,6 +320,7 @@ export function parseSettingValue(kind: SettingKind, raw: unknown): unknown {
       return kind.timer === true && n > MAX_TIMEOUT_MS ? null : n
     }
     case 'size':
+      if (kind.off === true && (raw === false || raw === 'false')) return 0
       return typeof raw === 'string' ? parseSize(raw) : null
     case 'bool':
       if (typeof raw === 'boolean') return raw

package/src/util/index.ts

@@ -55,6 +55,7 @@ export {
   EXTGLOB,
   grantPrefix,
   isLiteralPattern,
+  literalPath,
   GLOB_WILDCARDS,
   normalizeBunGlob,
   normalizeGlob,