@vzn/vx 0.0.637 → 0.0.638

package/docs/schema.md

@@ -881,7 +881,7 @@ lockfile change when a lockfile plugin (`@vzn/vx-lockfile`) is declared.
 Always applied to every glob pass (regardless of what you wrote):
 
 - **gitignore filter** — workspace-root + project `.gitignore`.
-- **Always-ignored** — `.git/**`, `.vx/cache/**`, `*.tsbuildinfo`,
+- **Always-ignored** — `.git/**`, `.vx/cache/**`,
   `.vx/projects.lock.json`, `vx.lock.json`, `*.bun-build`, and Bun's cross-compile extraction
   directory `.<16 hex>-<8 hex>.tmp/**`, and vx's own restore temp
   `.vx-tmp-*`, at any depth.
@@ -937,7 +937,7 @@ backslash separator (`src\**`, `src\*.ts`) or a drive (`C:\src\**`,
 backslash stays an escape.
 
 Still applied: the always-ignored set (`.git/**`, `.vx/cache/**`,
-`*.tsbuildinfo`, `.vx/projects.lock.json`, `vx.lock.json`, `*.bun-build`, `.<16 hex>-<8 hex>.tmp/**`, `.vx-tmp-*`),
+`.vx/projects.lock.json`, `vx.lock.json`, `*.bun-build`, `.<16 hex>-<8 hex>.tmp/**`, `.vx-tmp-*`),
 untracked files under `node_modules/`, and the task's own declared
 outputs, `outputs.workspaceFiles` and the `outputs.files` its globs reach
 in its own project (a task never invalidates itself).
@@ -1186,10 +1186,10 @@ run is a no-op too.
 
 **`clean: false`** keeps the outputs on a miss instead of wiping them
 first, for a tool that reads its own last output (tsc's
-`.tsbuildinfo`). An entry still holds only what a clean run would
-leave: if the run leaves any old file unchanged, nothing is cached, and
-the next run executes again. A retry still starts clean, and a hit
-still restores bit-identically. Omitted → the workspace's
+`.tsbuildinfo`). It opts out of the clean-tree guarantee: the save
+stores every file the outputs match after the run, so a file an older
+build left behind is cached and restored on every machine. A retry
+still starts clean, and a hit still restores bit-identically. Omitted → the workspace's
 `cache.outputs.clean`, else `true`.
 
 A **`!` entry takes a path back** from what the positive globs select
@@ -1259,7 +1259,9 @@ and so are `dist//**` and `dist/./app.js` (item 441) — and a literal
 entry is read as the file OR its whole tree, the same rule the resolver
 uses, so `dist` collides with `dist/app.js` (item 442). A whole subtree
 collides with any glob whose literal head lies inside it: `dist/**` with
-`dist/extra/**` or `dist/*.js` (item 941). Globs that only _might_
+`dist/extra/**` or `dist/*.js` (item 941). Two globs a path built from
+either one matches are one too: `**/*` and `**/dist/**` both match
+`x/dist/x`. Globs that only _might_
 overlap (`dist/*` and `dist/sub/**`) are let through; there, last
 restore wins. A workspace output is also compared with every other
 project's `files` outputs, read from the root: `packages/b/dist/a.txt`
@@ -1676,7 +1678,7 @@ task's value over all of them; the input-stability variables are the one
 exception, overriding every task for the run. A duration carries its
 unit (`'500ms'`, `'30s'`, `'10m'`, `'2h'`, `'30d'`), and a bare number is
 refused naming the forms with units; a size carries one too (`'10GB'`).
-`debug.timing`, `debug.dumpable`, `config.workerTimeout` and `run.outputLogs` are read
+`debug.timing`, `debug.watch`, `debug.dumpable`, `config.workerTimeout` and `run.outputLogs` are read
 before the workspace loads, so they have a variable (and a flag) only.
 None is folded into a cache key. `vx info` lists every setting not at its
 default and where it came from.
@@ -1708,11 +1710,12 @@ default and where it came from.
 | `cache.download`                               | `VX_CACHE_DOWNLOAD`                 | `--cache-download`   | one of 'all', 'toplevel', 'none'                                        | all                                        | Which remote hits land on disk: every one, only the requested tasks, or none.                                                                       |
 | `cache.inputStability.strategy`                | `VX_CACHE_INPUT_STABILITY_STRATEGY` | —                    | one of 'immutable', 'mutable', 'unchecked'                              | immutable                                  | What a write to an input during the command means for the save, for tasks without their own. A task's own `cache.inputStability.strategy` beats it. |
 | `cache.inputStability.severity`                | `VX_CACHE_INPUT_STABILITY_SEVERITY` | —                    | one of 'warn', 'error'                                                  | warn                                       | Whether a skipped save warns or fails the task, for tasks without their own. A task's own `cache.inputStability.severity` beats it.                 |
-| `cache.outputs.clean`                          | `VX_CACHE_OUTPUTS_CLEAN`            | —                    | true or false                                                           | true                                       | Remove a task's declared outputs before it runs on a miss, for tasks without their own. A task's own `cache.outputs.clean` beats it.                |
+| `cache.outputs.clean`                          | —                                   | —                    | true or false                                                           | true                                       | Remove a task's declared outputs before it runs on a miss, for tasks without their own. A task's own `cache.outputs.clean` beats it.                |
 | `lock.reviewFiles`                             | `VX_LOCK_REVIEW_FILES`              | —                    | true or false                                                           | true                                       | `vx lock` writes each project's resolved config, pretty, to `vx.lock.json` beside its `vx.config`, for review; vx never reads it.                   |
 | `watch.poll`                                   | `VX_WATCH_POLL`                     | `vx watch --poll`    | true or false                                                           | false                                      | Poll for changes from the start instead of the OS watcher.                                                                                          |
 | `config.workerTimeout` (variable or flag only) | `VX_CONFIG_WORKER_TIMEOUT`          | —                    | a duration like '500ms', '30s' or '5m', at most 24 days                 | 30s                                        | How long one config evaluation may take.                                                                                                            |
 | `debug.timing` (variable or flag only)         | `VX_DEBUG_TIMING`                   | —                    | true or false                                                           | false                                      | Print the run's stage timings to stderr.                                                                                                            |
+| `debug.watch` (variable or flag only)          | `VX_DEBUG_WATCH`                    | —                    | true or false                                                           | false                                      | `vx watch`: say on stderr each time the loop arms, with the projects it watches.                                                                    |
 | `debug.dumpable` (variable or flag only)       | `VX_DEBUG_DUMPABLE`                 | —                    | true or false                                                           | false                                      | Linux: keep vx dumpable, so strace or a debugger can read its memory and `/proc/<pid>/fd`, and an unsandboxed task its env.                         |
 
 <!-- /settings table -->
@@ -2263,16 +2266,22 @@ opens it on click), and the lines up to it with a caret under the field
 (`util/config-frame.ts`):
 
 ```
-vx: packages/b/vx.config.ts:4:15: tasks.build.exec has unknown field "comand" (allowed: …) — did you mean command?
+✗ vx lock  lock not written
 
-  2 |   tasks: {
-  3 |     build: {
-> 4 |       exec: { comand: 'mkdir -p dist' },
-    |               ^
+  packages/b/vx.config.ts:4:15
+  tasks.build.exec has unknown field "comand"
+  allowed: …
+
+    2 |   tasks: {
+    3 |     build: {
+  > 4 |       exec: { comand: 'mkdir -p dist' },
+      |               ^
+
+  fix  use command
 ```
 
 A field the file does not hold (a required one missing, or one a plugin
-set) prints the one line as before. The table below lists the messages
+set) prints without the frame. The table below lists the messages
 a user meets most:
 
 | Symptom                                                                                                                               | Cause                                                                                                                                                                                                                          |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vzn/vx",
-  "version": "0.0.637",
+  "version": "0.0.638",
   "description": "Task orchestration you own: correct, sandboxed, extensible, with a content-addressed build cache.",
   "type": "module",
   "exports": {
@@ -21,10 +21,10 @@
     "node": ">=18"
   },
   "optionalDependencies": {
-    "@vzn/vx-linux-x64": "0.0.637",
-    "@vzn/vx-linux-arm64": "0.0.637",
-    "@vzn/vx-darwin-x64": "0.0.637",
-    "@vzn/vx-darwin-arm64": "0.0.637"
+    "@vzn/vx-linux-x64": "0.0.638",
+    "@vzn/vx-linux-arm64": "0.0.638",
+    "@vzn/vx-darwin-x64": "0.0.638",
+    "@vzn/vx-darwin-arm64": "0.0.638"
   },
   "dependencies": {
     "@anthropic-ai/sandbox-runtime": "^0.0.76"

package/schemas/plan.json

@@ -45,8 +45,8 @@
             "required": ["kind"],
             "properties": {
               "kind": {
-                "enum": ["input", "project", "package", "named", "selected"],
-                "description": "input: a changed file is a declared input; project: its project changed and the task reads it whole; package: a ^ edge passes a changed package; named: asked as pkg#task; selected: another filter selected its project"
+                "enum": ["input", "project", "workspace", "package", "named", "selected"],
+                "description": "input: a changed file is a declared input; project: its project changed and the task reads it whole; workspace: a workspace-wide file (the workspace config, a root file a plugin claims) changed; package: a ^ edge passes a changed package; named: asked as pkg#task; selected: another filter selected its project"
               },
               "file": { "type": "string", "description": "the changed file, workspace-relative" },
               "project": { "type": "string", "description": "the changed package (kind package)" },

package/skills/vx/SKILL.md

@@ -27,10 +27,21 @@ A refusal under `--format json` is one line on stdout,
 Without a TTY a missing task name never prompts: vx exits 1 and lists the
 tasks it found.
 
+## After editing a config
+
+```sh
+vx lock   # after any edit to a vx.config.ts or .vx/workspace.ts
+```
+
+A run reads every config from `.vx/projects.lock.json`, never the files:
+a task you add, or an edit to one, does nothing until `vx lock`. Commit
+the lock with the config.
+
 ## Look before running
 
 ```sh
-vx show --format json                          # projects, their tasks and dependencies
+vx show --format json                          # projects and their tasks
+vx show app --format json                      # one project's tasks as a run reads them
 vx run test --affected=origin/main --dry=json  # what would run, cache hit or miss, and why
 ```
 
@@ -94,6 +105,6 @@ vx info --format json   # vx and Bun versions, projects, config errors, plugins,
 
 ## Install
 
-`npx skills add vznjs/vx/packages/vx/skills/vx` installs this skill. To match the vx a workspace
+`npx skills add vznjs/vx` installs this skill. To match the vx a workspace
 has installed, copy it from there instead:
 `cp node_modules/@vzn/vx/skills/vx/SKILL.md .claude/skills/vx/`.

package/src/bin.ts

@@ -46,7 +46,7 @@ async function main(): Promise<void> {
     process.exitCode = code
   } catch (err) {
     const {
-      configErrorFrame,
+      detectColors,
       errorCode,
       errorDocument,
       fsRefusalHint,
@@ -55,6 +55,8 @@ async function main(): Promise<void> {
       isUserError,
       maskedLine,
       OUT_OF_FDS_HINT,
+      refusalNotice,
+      ui,
       wantsJson,
     } = await import('./util/index.js')
     // A plugin's failure quotes what it was told (a remote's reply, a
@@ -66,12 +68,16 @@ async function main(): Promise<void> {
     // on. Everything else gets the full stack so internal bugs are
     // debuggable.
     if (isUserError(err)) {
-      // A message that already names the tool (`vx why: …`, thrown by a verb
-      // that wants its own name in the line) is printed as it is; prefixing
-      // it produced `vx: vx why: …` (walkthrough, 2026-09-04).
-      // A config refusal names its line and shows it.
-      const m = configErrorFrame(err.message, process.cwd()) ?? err.message
-      say(m.startsWith('vx ') ? `${m}\n` : `vx: ${m}\n`)
+      // A message that names its verb (`vx why: …`) is that verb's; any
+      // other is the verb typed. A config refusal shows its line.
+      const named = /^(vx [a-z][\w-]*): /.exec(err.message)
+      const typed = /^[a-z][\w-]*$/.test(argv[0] ?? '') ? `vx ${argv[0]}` : 'vx'
+      const block = refusalNotice(
+        named?.[1] ?? typed,
+        named === null ? err.message : err.message.slice(named[0].length),
+        err.parts,
+      )
+      process.stderr.write(maskedLine(ui.render([block], detectColors(process.stderr))))
     } else if (isOutOfFds(err)) {
       say(`vx: ${err.message} — ${OUT_OF_FDS_HINT}\n`)
     } else if (isFsRefusal(err)) {

package/src/cache/cache.ts

@@ -303,7 +303,13 @@ function outOfFdsAtOpen(dbFile: string, err: unknown): UserError | undefined {
 //        unchanged.
 //   v36: the store's task_durations: each executed success's time, tagged
 //        by branch, read by the forecast. The cache KEY is unchanged.
-export const SCHEMA_VERSION = 'v36'
+//   v37: the store's plugin_blobs (a plugin's `ctx.cache`) and one
+//        'remote' task_durations row per (sha, task). The cache KEY is
+//        unchanged.
+//   v38: blob_sizes moved to the store, and the store's task_outcomes
+//        holds the flaky record, so worktrees share both. The cache KEY is
+//        unchanged.
+export const SCHEMA_VERSION = 'v38'
 
 /**
  * An entry's key components as its one `entry_inputs` row (v34): JSON
@@ -333,6 +339,9 @@ const STORE_TABLES = [
   'output_files',
   'entry_stdout',
   'task_durations',
+  'task_outcomes',
+  'blob_sizes',
+  'plugin_blobs',
   'store_meta',
   'entries',
 ]
@@ -1030,7 +1039,7 @@ export class Cache implements CacheLayer {
             // keeps it so).
             if (found !== undefined) {
               this.db.exec(
-                'DROP TABLE IF EXISTS main.entries; DROP TABLE IF EXISTS main.runs; DROP TABLE IF EXISTS main.file_hashes; DROP TABLE IF EXISTS main.blob_sizes; DROP TABLE IF EXISTS main.blob_verdicts; DROP TABLE IF EXISTS main.output_files; DROP TABLE IF EXISTS main.output_stamps; DROP TABLE IF EXISTS main.invocations; DROP TABLE IF EXISTS main.run_task_inputs; DROP TABLE IF EXISTS main.entry_inputs; DROP TABLE IF EXISTS main.config_evals; DROP TABLE IF EXISTS main.config_closures; DROP TABLE IF EXISTS main.output_dirs; DROP TABLE IF EXISTS main.entry_stdout; DROP TABLE IF EXISTS main.task_durations; DROP TABLE IF EXISTS main.store_meta;',
+                'DROP TABLE IF EXISTS main.entries; DROP TABLE IF EXISTS main.runs; DROP TABLE IF EXISTS main.file_hashes; DROP TABLE IF EXISTS main.blob_sizes; DROP TABLE IF EXISTS main.blob_verdicts; DROP TABLE IF EXISTS main.output_files; DROP TABLE IF EXISTS main.output_stamps; DROP TABLE IF EXISTS main.invocations; DROP TABLE IF EXISTS main.run_task_inputs; DROP TABLE IF EXISTS main.entry_inputs; DROP TABLE IF EXISTS main.config_evals; DROP TABLE IF EXISTS main.config_closures; DROP TABLE IF EXISTS main.output_dirs; DROP TABLE IF EXISTS main.entry_stdout; DROP TABLE IF EXISTS main.task_durations; DROP TABLE IF EXISTS main.plugin_blobs; DROP TABLE IF EXISTS main.task_outcomes; DROP TABLE IF EXISTS main.store_meta;',
               )
             }
             // The tables land under the same write lock as the stamp: made
@@ -1737,6 +1746,16 @@ export class Cache implements CacheLayer {
     return this.guard(() => this.hasEntry(hash))
   }
 
+  /**
+   * The subset of `hashes` this store holds, `has` for each: the prefetch
+   * pass asks the remote only about the rest (M, 2026-10-15).
+   */
+  async localHasMany(hashes: readonly string[]): Promise<Set<string>> {
+    const out = new Set<string>()
+    for (const hash of hashes) if ((await this.has(hash)) === 'local') out.add(hash)
+    return out
+  }
+
   private async hasEntry(hash: string): Promise<'local' | 'remote' | null> {
     if (!this.read) return null
     const row = this.entryExists.get(hash) as { inline_at: number | null } | null

package/src/cache/chained-cache.ts

@@ -108,6 +108,10 @@ export class ChainedCache implements CacheLayer {
     return false
   }
 
+  localHasMany(hashes: readonly string[]): Promise<Set<string>> {
+    return this.layers[0]!.localHasMany?.(hashes) ?? Promise.resolve(new Set())
+  }
+
   async remoteHasMany(hashes: readonly string[]): Promise<Set<string> | null> {
     // The caller (remote-prefetch) treats a non-null answer as authoritative
     // for the WHOLE chain: complement = absent, broadcast. That is sound only

package/src/cache/index.ts

@@ -15,6 +15,7 @@ export {
   type CachePolicy,
   cachesNothing,
   EXECUTED_RUNS_SQL,
+  formatCachePolicy,
   FULL_CACHE_POLICY,
   type InvocationRecord,
   KEYED_RUNS_SQL,
@@ -47,7 +48,6 @@ export {
   type ProjectFilesCache,
   type WorkspaceFilesCache,
   cleanOutputPaths,
-  anyUntouched,
   ownOutputsSince,
   ownWorkspaceOutputsSince,
   stampOutputs,
@@ -70,5 +70,13 @@ export {
 } from './git-inputs.js'
 export { LayeredCache, type RemoteCacheLayer } from './layered-cache.js'
 export { ScopedCache } from './scoped-cache.js'
+export {
+  absentPluginCache,
+  pluginCache,
+  PLUGIN_ENTRY_MAX_BYTES,
+  type PluginCache,
+  type PluginCacheRemote,
+} from './plugin-cache.js'
+export { packRunOutputs, putRunEntry, runEntryName, writesRunStore } from './run-store.js'
 export { ChainedCache } from './chained-cache.js'
 export { branchSource } from './run-history.js'

package/src/cache/inputs.ts

@@ -81,7 +81,6 @@ const ALWAYS_IGNORE = [
   '**/.git/**',
   // vx's machine-local state; the workspace config beside it is a source.
   '**/.vx/cache/**',
-  '**/*.tsbuildinfo',
   '**/.vx/projects.lock.json',
   // `vx lock`'s review copy of a project's resolved config: the config is
   // keyed already, and a re-lock must not move every `**` reader's key.
@@ -1018,29 +1017,6 @@ function changedSince(
   return kept < before.size ? undefined : own
 }
 
-/**
- * Is any file `before` stamped still there, unchanged? Under
- * `cache.outputs.clean: false` such a file is one the run found and never
- * wrote, so no entry may claim it as the run's output.
- */
-export function anyUntouched(before: ReadonlyMap<string, OutputStamp>): boolean {
-  for (const [f, was] of before) {
-    try {
-      const st = lstatSync(f)
-      if (
-        st.size === was.size &&
-        st.mtimeMs === was.mtimeMs &&
-        st.ino === was.ino &&
-        st.ctimeMs === was.ctimeMs
-      )
-        return true
-    } catch {
-      // Removed by the run: nothing of it is left to claim.
-    }
-  }
-  return false
-}
-
 /**
  * Up to this many paths, a clean removes synchronously: the threadpool round
  * trip per `rm`/`rmdir` cost more than the unlink itself, 0.30 ms against

package/src/cache/layer.ts

@@ -221,7 +221,7 @@ export interface InvocationRecord {
   command: string
   /** JSON-serialized `string[]` of the requested task names. */
   requestedTasks: string
-  /** Compact policy flags, e.g. `'lR,lW,rR,rW'` (an axis omitted = off). */
+  /** The `--cache-policy` spec, e.g. `'local:rw,remote:r'` (a flag omitted = off). */
   cachePolicy: string
   concurrency: number
   flow: 'focused' | 'broad' | null
@@ -544,6 +544,12 @@ export interface CacheLayer {
    * batch omits it and the prefetch pass falls back to per-hash GETs.
    */
   remoteHasMany?(hashes: readonly string[]): Promise<Set<string> | null>
+  /**
+   * The subset of `hashes` the local store already holds. The prefetch
+   * pass probes the remote only for the rest, so a run the local cache
+   * answers makes no remote call. Absent reads as "none held".
+   */
+  localHasMany?(hashes: readonly string[]): Promise<Set<string>>
   /**
    * Record that the remote has NO artifact for each of `hashes` (from a
    * batch probe), so a later `get`/`prefetch` short-circuits to a miss with

package/src/cache/layered-cache.ts

@@ -254,6 +254,10 @@ export class LayeredCache implements CacheLayer {
     return this.pullFromRemote(hash, ctx)
   }
 
+  localHasMany(hashes: readonly string[]): Promise<Set<string>> {
+    return this.local.localHasMany(hashes)
+  }
+
   /**
    * Batch existence probe over the remote layer — the subset of `hashes`
    * present remotely, in one round-trip, or `null` when the remote can't

package/src/cache/plugin-cache.ts

@@ -0,0 +1,248 @@
+// A plugin's own entries in the cache the workspace declares (`ctx.cache`,
+// owner 2026-10-14): the local store first, then each remote in declared
+// order, under the run's policy and scope. The plugin speaks names; core
+// derives the key, so no plugin reaches another's entries or a task's. An
+// entry is written once and never replaced (the cache is immutable). Every
+// failure is an absent answer, never a warning (M: no extra runtime
+// warnings): what a plugin keeps here is a hint.
+
+import type { Database } from 'bun:sqlite'
+import { xxh3hex } from '../util/index.js'
+import type { CachePolicy } from './policy.js'
+import type { RemoteCacheLayer } from './layered-cache.js'
+import { scopedKey } from './scoped-cache.js'
+import { runReadKeys } from './run-store.js'
+
+/** The largest entry kept or read, in bytes: a remote's larger body is a miss, read no further. */
+export const PLUGIN_ENTRY_MAX_BYTES = 1024 * 1024
+
+/** What a plugin's `ctx.cache` offers. Keys are the plugin's own names. */
+export interface PluginCache {
+  /** The bytes stored under `key`, from the first layer holding them; null when none does. */
+  get(key: string): Promise<Uint8Array | null>
+  /** Store `bytes` under `key` in every layer the policy writes, where it is not already; empty bytes store nothing. */
+  put(key: string, bytes: Uint8Array): Promise<void>
+  /** Whether some layer holds `key`; null when no layer could answer. */
+  has(key: string): Promise<boolean | null>
+  /**
+   * The subset of `keys` some layer holds, in one probe per layer; null
+   * when a readable remote has no batch probe: ask `get` one at a time.
+   */
+  hasMany(keys: readonly string[]): Promise<Set<string> | null>
+  /**
+   * What core kept of a run under `name` (a `log` or `outputs` name its
+   * `RunReport` hands `teardown`), from the first readable remote holding
+   * it; null when none does. Uncapped: core wrote it.
+   */
+  getRun(name: string): Promise<Uint8Array | null>
+}
+
+/** One remote as the plugin cache reaches it: its wire and what the policy lets it do. */
+export interface PluginCacheRemote {
+  readonly remote: RemoteCacheLayer
+  readonly read: boolean
+  readonly write: boolean
+}
+
+export interface PluginCacheHost {
+  /** The run's index; its store holds `plugin_blobs`. */
+  readonly db: Database
+  readonly policy: CachePolicy
+  readonly remotes: readonly PluginCacheRemote[]
+  readonly scope: string | undefined
+}
+
+/** The key `name` stores under for `plugin`: task-key shaped, so every wire stores it unchanged. */
+function entryKey(plugin: string, name: string): string {
+  return xxh3hex(`vx-plugin\0${plugin}\0${name}`)
+}
+
+/**
+ * A remote body's bytes; null past the cap (read no further than it) and for
+ * an empty or odd body, which kept would hide every later good one: an entry
+ * is written once (Security, #3580).
+ */
+async function capped(body: unknown, max = PLUGIN_ENTRY_MAX_BYTES): Promise<Uint8Array | null> {
+  if (body instanceof Blob) {
+    if (body.size === 0 || body.size > max) return null
+    return new Uint8Array(await body.arrayBuffer())
+  }
+  if (!(body instanceof Response) || body.body === null) return null
+  const reader = body.body.getReader()
+  const chunks: Uint8Array[] = []
+  let size = 0
+  for (;;) {
+    const { done, value } = await reader.read()
+    if (done) break
+    size += value.byteLength
+    if (size > max) {
+      await reader.cancel().catch(() => {})
+      return null
+    }
+    chunks.push(value)
+  }
+  if (size === 0) return null
+  const out = new Uint8Array(size)
+  let at = 0
+  for (const c of chunks) {
+    out.set(c, at)
+    at += c.byteLength
+  }
+  return out
+}
+
+/**
+ * `plugin`'s view of the cache. A scoped run reads the default key, then
+ * the scope's, and writes only the scope's, as tasks do (`ScopedCache`).
+ */
+export function pluginCache(plugin: string, host: PluginCacheHost): PluginCache {
+  const { db, policy, scope } = host
+  const readers = host.remotes.filter((r) => r.read)
+  const writers = host.remotes.filter((r) => r.write)
+  const reads = (name: string): string[] => {
+    const key = entryKey(plugin, name)
+    return scope === undefined ? [key] : [key, scopedKey(scope, key)]
+  }
+  const writeKey = (name: string): string => {
+    const key = entryKey(plugin, name)
+    return scope === undefined ? key : scopedKey(scope, key)
+  }
+
+  const localGet = (key: string): Uint8Array | null => {
+    if (!policy.localRead) return null
+    try {
+      const row = db.query('SELECT bytes FROM plugin_blobs WHERE key = ?').get(key) as {
+        bytes: Uint8Array
+      } | null
+      return row === null ? null : new Uint8Array(row.bytes)
+    } catch {
+      return null
+    }
+  }
+  const localHas = (keys: readonly string[]): Set<string> => {
+    const found = new Set<string>()
+    if (!policy.localRead || keys.length === 0) return found
+    try {
+      const rows = db
+        .query(`SELECT key FROM plugin_blobs WHERE key IN (${keys.map(() => '?').join(', ')})`)
+        .all(...keys) as Array<{ key: string }>
+      for (const r of rows) found.add(r.key)
+    } catch {
+      // an unreadable index holds nothing
+    }
+    return found
+  }
+  const localPut = (key: string, bytes: Uint8Array): void => {
+    try {
+      db.query('INSERT OR IGNORE INTO plugin_blobs(key, bytes, at) VALUES (?, ?, ?)').run(
+        key,
+        bytes,
+        Date.now(),
+      )
+    } catch {
+      // a read-only or busy index keeps nothing
+    }
+  }
+
+  return {
+    async get(name) {
+      const keys = reads(name)
+      for (const key of keys) {
+        const hit = localGet(key)
+        if (hit !== null) return hit
+      }
+      for (const { remote } of readers) {
+        for (const key of keys) {
+          try {
+            const got = await remote.get(key)
+            if (got === null) continue
+            const bytes = await capped(got.body)
+            if (bytes === null) continue
+            if (policy.localWrite) localPut(key, bytes)
+            return bytes
+          } catch {
+            // a failing remote is a miss there
+          }
+        }
+      }
+      return null
+    },
+
+    async put(name, bytes) {
+      if (bytes.byteLength === 0 || bytes.byteLength > PLUGIN_ENTRY_MAX_BYTES) return
+      const key = writeKey(name)
+      if (policy.localWrite) localPut(key, bytes)
+      for (const { remote } of writers) {
+        try {
+          if (await remote.has(key)) continue
+          await remote.put(key, new Blob([bytes]), { durationMs: 0 })
+        } catch {
+          // the other layers still keep it
+        }
+      }
+    },
+
+    async has(name) {
+      const keys = reads(name)
+      if (localHas(keys).size > 0) return true
+      let answered = policy.localRead
+      for (const { remote } of readers) {
+        for (const key of keys) {
+          try {
+            if (await remote.has(key)) return true
+            answered = true
+          } catch {
+            // no answer from this remote
+          }
+        }
+      }
+      return answered ? false : null
+    },
+
+    async hasMany(names) {
+      const byKey = new Map<string, string>()
+      for (const name of names) for (const key of reads(name)) byKey.set(key, name)
+      const keys = [...byKey.keys()]
+      const found = new Set<string>()
+      for (const key of localHas(keys)) found.add(byKey.get(key)!)
+      for (const { remote } of readers) {
+        const ask = keys.filter((k) => !found.has(byKey.get(k)!))
+        if (ask.length === 0) break
+        if (remote.hasMany === undefined) return null
+        try {
+          const got: unknown = await remote.hasMany(ask)
+          if (!(got instanceof Set)) return null
+          for (const key of got) if (byKey.has(key as string)) found.add(byKey.get(key as string)!)
+        } catch {
+          return null
+        }
+      }
+      return found
+    },
+
+    async getRun(name) {
+      for (const { remote } of readers) {
+        for (const key of runReadKeys(name, scope)) {
+          try {
+            const got = await remote.get(key)
+            if (got === null) continue
+            const bytes = await capped(got.body, Infinity)
+            if (bytes !== null) return bytes
+          } catch {
+            // a failing remote is a miss there
+          }
+        }
+      }
+      return null
+    },
+  }
+}
+
+/** A cache with no layer: every answer absent. What a context built outside a run holds. */
+export const absentPluginCache: PluginCache = {
+  get: async () => null,
+  put: async () => {},
+  has: async () => null,
+  hasMany: async () => null,
+  getRun: async () => null,
+}

package/src/cache/policy.ts

@@ -90,6 +90,15 @@ export function parseCachePolicy(spec: string, base: CachePolicy = FULL_CACHE_PO
   return out
 }
 
+/**
+ * The `--cache-policy` spec for `p`, both layers named, so the line
+ * `vx last` shows pastes back as the flag: `local:rw,remote:r`.
+ */
+export function formatCachePolicy(p: CachePolicy): string {
+  const flags = (r: boolean, w: boolean): string => `${r ? 'r' : ''}${w ? 'w' : ''}`
+  return `local:${flags(p.localRead, p.localWrite)},remote:${flags(p.remoteRead, p.remoteWrite)}`
+}
+
 /** `--no-cache` and `--force`, which still apply over whichever spec set the base. */
 export interface CacheFlags {
   /** `--no-cache`: every axis off. Beats `force`. */