@vzn/vx 0.0.636 → 0.0.637

package/src/cache/inputs.ts

@@ -58,7 +58,7 @@ export {
   type GitEnumeration,
 } from './git-inputs.js'
 
-// vx-lock.json is committed (so git enumerates it) but it's vx's own
+// .vx/projects.lock.json is committed (so git enumerates it) but it's vx's own
 // frozen-config metadata — never a task input. Excluded globally so a
 // re-lock can't bust every cache key the way a tracked source file
 // would. (Literal pattern, not the workspace `LOCKFILE_NAME` constant:
@@ -79,9 +79,17 @@ const ALWAYS_IGNORE = [
   // it. Kept: the day an enumeration stops going through git, this is
   // what keeps a repository's object store out of a cache key.
   '**/.git/**',
-  '**/.vx/**',
+  // vx's machine-local state; the workspace config beside it is a source.
+  '**/.vx/cache/**',
   '**/*.tsbuildinfo',
-  '**/vx-lock.json',
+  '**/.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.
+  '**/vx.lock.json',
+  // What `vx lock` and `vx init` write beside the lock: a re-lock or init
+  // must not select every `**` reader under --affected.
+  '**/.vx/.gitattributes',
+  '**/.vx/.gitignore',
   // `bun build --compile` writes a transient `.<hash>-<n>.bun-build` intermediate
   // in the cwd. It never rests on disk, so it can't be a real input — but a
   // broad `inputs.files: ['**/*']` on a compile task would try to hash the temp
@@ -313,7 +321,13 @@ function resolveWorkspaceFiles(args: {
   let isPositive: ((rel: string) => boolean) | undefined
   const excludedByDeclaration = (rel: string): boolean =>
     (isExcluded ??= anyTaskGlob([...ALWAYS_IGNORE, ...asTrees(negative)]))(rel)
-  const own = (rel: string): boolean => ownOutput(rel) || ownProject(rel)
+  // A committed file stays an input whatever output reaches it (`committedFiles`).
+  let committed: ((abs: string) => boolean) | undefined
+  const own = (rel: string): boolean =>
+    (ownOutput(rel) || ownProject(rel)) &&
+    !(committed ??= committedFiles(args.gitFilesCache, args.workspaceRoot))(
+      path.join(args.workspaceRoot, rel),
+    )
   const listing: InputListing = {
     root: args.workspaceRoot,
     listed: gitFiles,
@@ -667,11 +681,13 @@ async function resolveRuntimeValues(
 /**
  * What no output glob reaches. An output is otherwise taken as written —
  * `node_modules/**` IS an install task's output, so `ALWAYS_IGNORE` does not
- * apply here — but these two directories no task produces, and a root
- * project declaring `**` would otherwise wipe its repository and the cache
- * it is restoring from (2026-09-16).
+ * apply here — but no task produces these, and a root project declaring
+ * `**` would otherwise wipe its repository and the cache it is restoring
+ * from (2026-09-16). `.vx` whole and each `vx.lock.json` are vx's own: as
+ * outputs, the clean deleted an uncommitted workspace config and a hit
+ * restored a lock or ignore file the key does not see over the current one.
  */
-const OUTPUT_NEVER = ['**/.git/**', '**/.vx/**']
+const OUTPUT_NEVER = ['**/.git/**', '**/.vx/**', '**/vx.lock.json']
 
 /**
  * What a set of output globs may not reach: `OUTPUT_NEVER`, and every
@@ -719,6 +735,20 @@ export async function resolveOutputs(args: {
   return containedIn(args.projectDir, scanned).sort()
 }
 
+/**
+ * Whether git tracks a file under `dir`. No clean deletes a committed (or
+ * `git add`ed) file an output glob reaches (owner, 2026-10-14: "never
+ * delete committed file"); the task may rewrite it and a restore writes the
+ * bytes it left. It stays in the task's key, so those bytes follow from
+ * the key. Turbo and Nx never clean an output at all.
+ */
+export function committedFiles(
+  cache: GitFilesCache | undefined,
+  dir: string,
+): (abs: string) => boolean {
+  return (cache ?? new GitFilesCache()).committedIn(dir)
+}
+
 /**
  * The literal head of each output glob, walked: the scan follows a link
  * there (`dist -> ../elsewhere` for `dist/**`) and only there. A link to a
@@ -838,6 +868,7 @@ export async function cleanOutputs(args: {
   projectDir: string
   outputs: readonly string[]
   nestedProjectDirs: string[]
+  committed?: (abs: string) => boolean
   /**
    * What `resolveOutputs` returned for these same arguments, when the
    * caller walked the tree with no await since: a hit that found its tree
@@ -846,15 +877,20 @@ export async function cleanOutputs(args: {
    */
   resolved?: readonly string[] | undefined
 }): Promise<string[]> {
-  const files = args.resolved ?? (await resolveOutputs(args))
+  const committed = args.committed ?? committedFiles(undefined, args.projectDir)
+  const matched = args.resolved ?? (await resolveOutputs(args))
   // `force: true` makes rm tolerate ENOENT (e.g. when two output
   // globs overlap and a sibling already deleted a path mid-iteration).
   // A symlink is unlinked, never followed.
-  const removed = await removeAll(files, args.projectDir)
+  const removed = await removeAll(
+    matched.filter((f) => !committed(f)),
+    args.projectDir,
+  )
   await pruneEmptiedDirs(args.projectDir, removed, pruneScope(args.projectDir, args.outputs))
-  // Project-relative posix paths of what was removed — the caller
-  // feeds these to GitFilesCache.markOutputsChanged after a restore.
-  return files.map((f) => relPosix(args.projectDir, f))
+  // Project-relative posix paths the outputs reach, for the caller's
+  // GitFilesCache.markOutputsChanged: a committed one kept here is the
+  // task's to rewrite or remove, so its index OID no longer vouches for it.
+  return matched.map((f) => relPosix(args.projectDir, f))
 }
 
 /**
@@ -868,8 +904,10 @@ export async function cleanOutputPaths(args: {
   projectDir: string
   rels: readonly string[]
   outputs: readonly string[]
+  committed?: (abs: string) => boolean
 }): Promise<void> {
-  const files = args.rels.map((r) => path.resolve(args.projectDir, r))
+  const committed = args.committed ?? committedFiles(undefined, args.projectDir)
+  const files = args.rels.map((r) => path.resolve(args.projectDir, r)).filter((f) => !committed(f))
   await pruneEmptiedDirs(
     args.projectDir,
     await removeAll(files, args.projectDir),
@@ -980,6 +1018,29 @@ 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
@@ -1179,16 +1240,21 @@ export async function resolveWorkspaceOutputs(args: {
 export async function cleanWorkspaceOutputs(args: {
   workspaceRoot: string
   outputs: readonly string[]
+  committed?: (abs: string) => boolean
   /** `cleanOutputs`'s `resolved`, from `resolveWorkspaceOutputs`. */
   resolved?: readonly string[] | undefined
 }): Promise<string[]> {
-  const files = args.resolved ?? (await resolveWorkspaceOutputs(args))
+  const committed = args.committed ?? committedFiles(undefined, args.workspaceRoot)
+  const matched = args.resolved ?? (await resolveWorkspaceOutputs(args))
   await pruneEmptiedDirs(
     args.workspaceRoot,
-    await removeAll(files, args.workspaceRoot),
+    await removeAll(
+      matched.filter((f) => !committed(f)),
+      args.workspaceRoot,
+    ),
     pruneScope(args.workspaceRoot, args.outputs),
   )
-  return files.map((f) => relPosix(args.workspaceRoot, f))
+  return matched.map((f) => relPosix(args.workspaceRoot, f))
 }
 
 function realOrNull(p: string): string | null {
@@ -1380,6 +1446,12 @@ interface FilesPlan {
    * `package.json`), so each is matched once per plan.
    */
   verdicts: Map<string, boolean>
+  /**
+   * Whether a path is an input but for the task's own outputs: one git
+   * tracks stays an input (`committedFiles`), so the key sees an edit to a
+   * committed file an output glob reaches.
+   */
+  ownOnly: Map<string, boolean>
 }
 
 /**
@@ -1423,6 +1495,7 @@ function filesPlan(
           isPositive: anyTaskGlob(asTrees(positive)),
           ...reachOf(positive),
           verdicts: new Map<string, boolean>(),
+          ownOnly: new Map<string, boolean>(),
         }
   filesPlans.set(key, plan)
   return plan
@@ -1432,8 +1505,8 @@ function filesPlan(
  * Whether a changed path is one of a cached task's declared file inputs:
  * `projectRel` (the path relative to the project that owns it) against
  * `files`, `workspaceRel` (relative to the workspace root) against
- * `workspaceFiles`; null skips that half, by the globs, `!` exclusions and own-output takebacks
- * the key resolves. `--affected` seeds a task with it (owner, 2026-10-04).
+ * `workspaceFiles`; null skips that half, by the globs and `!` exclusions (a path under
+ * the task's own outputs counts: a committed one is keyed). `--affected` seeds a task with it (owner, 2026-10-04).
  */
 export function declaresInput(
   cache: CacheConfig,
@@ -1441,13 +1514,15 @@ export function declaresInput(
   workspaceRel: string | null,
 ): boolean {
   if (projectRel !== null) {
+    // A changed path under the task's own outputs is a committed file
+    // (`git diff` lists only what git tracks) or a stray `git status`
+    // lists: either way it may be an input, so it counts.
     const plan = filesPlan(cache.inputs.files, cache.outputs.files)
-    if (plan !== null && inPlan(plan, projectRel)) return true
+    if (plan !== null && (inPlan(plan, projectRel) || ownOnly(plan, projectRel))) return true
   }
   const ws = cache.inputs.workspaceFiles
   if (workspaceRel === null || ws === undefined || ws.length === 0) return false
-  const matcher = workspaceMatcher(ws, cache.outputs.workspaceFiles ?? [])
-  return matcher(workspaceRel)
+  return workspaceMatcher(ws)(workspaceRel)
 }
 
 /**
@@ -1471,20 +1546,26 @@ function inPlan(plan: FilesPlan, rel: string): boolean {
   return input
 }
 
+/** `FilesPlan.ownOnly`, memoised: asked only of a path `inPlan` refused. */
+function ownOnly(plan: FilesPlan, rel: string): boolean {
+  let own = plan.ownOnly.get(rel)
+  if (own === undefined) {
+    own = plan.ownOutput(rel) && plan.isPositive(rel) && !plan.isExcluded(rel)
+    plan.ownOnly.set(rel, own)
+  }
+  return own
+}
+
 const workspaceMatchers = new Map<string, (rel: string) => boolean>()
 
-function workspaceMatcher(
-  decl: readonly string[],
-  ownOutputs: readonly string[],
-): (rel: string) => boolean {
-  const key = JSON.stringify([decl, ownOutputs])
+function workspaceMatcher(decl: readonly string[]): (rel: string) => boolean {
+  const key = JSON.stringify(decl)
   let m = workspaceMatchers.get(key)
   if (m !== undefined) return m
   const { positive, negative } = splitNegations(decl)
   const isPositive = anyTaskGlob(asTrees(positive))
   const isExcluded = anyTaskGlob([...ALWAYS_IGNORE, ...asTrees(negative)])
-  const ownOutput = outputMatcher(ownOutputs)
-  m = (rel) => isPositive(rel) && !isExcluded(rel) && !ownOutput(rel)
+  m = (rel) => isPositive(rel) && !isExcluded(rel)
   workspaceMatchers.set(key, m)
   return m
 }
@@ -1521,7 +1602,7 @@ async function resolveFiles(
     if (memo !== undefined && memo.snapshot === gitFiles) {
       return {
         files: [...memo.result],
-        listing: listingFor(args.projectDir, gitFiles, plan, nested, ownWsOutput),
+        listing: listingFor(args, gitFiles, plan, nested, ownWsOutput),
       }
     }
   }
@@ -1566,14 +1647,17 @@ async function resolveFiles(
       : undefined
   const candidates: string[] = []
   const verdicts = plan.verdicts
+  const committed = committedFiles(args.gitFilesCache, args.projectDir)
   for (const rel of gitFiles) {
     let input = verdicts.get(rel)
     if (input === undefined) {
       input = isPositive(rel) && !isExcluded(rel) && !ownOutput(rel)
       verdicts.set(rel, input)
     }
-    if (!input || nested(rel) || ownWsOutput(rel)) continue
-    candidates.push(base === undefined ? path.resolve(args.projectDir, rel) : base + rel)
+    if ((!input && !ownOnly(plan, rel)) || nested(rel) || ownWsOutput(rel)) continue
+    const abs = base === undefined ? path.resolve(args.projectDir, rel) : base + rel
+    if (!input && !committed(abs)) continue
+    candidates.push(abs)
   }
   const unmatchedLiterals = unanswered(plan.literals, gitFiles)
   if (unmatchedLiterals.size > 0) {
@@ -1601,21 +1685,27 @@ async function resolveFiles(
   args.projectFilesCache?.set(memoKey, { snapshot: gitFiles, result: resolved })
   return {
     files: [...resolved],
-    listing: listingFor(args.projectDir, gitFiles, plan, nested, ownWsOutput),
+    listing: listingFor(args, gitFiles, plan, nested, ownWsOutput),
   }
 }
 
 function listingFor(
-  root: string,
+  args: { projectDir: string; gitFilesCache?: GitFilesCache | undefined },
   listed: readonly string[],
   plan: FilesPlan,
   nested: (rel: string) => boolean,
   ownWsOutput: (rel: string) => boolean,
 ): InputListing {
+  const root = args.projectDir
+  let committed: ((abs: string) => boolean) | undefined
   return {
     root,
     listed,
-    isInput: (rel) => inPlan(plan, rel) && !ownWsOutput(rel),
+    isInput: (rel) =>
+      (inPlan(plan, rel) ||
+        (ownOnly(plan, rel) &&
+          (committed ??= committedFiles(args.gitFilesCache, root))(path.join(root, rel)))) &&
+      !ownWsOutput(rel),
     nested,
     prefixes: plan.prefixes,
     literals: plan.literals,

package/src/cache/key-fold.ts

@@ -31,9 +31,9 @@ import type { CacheKeyInput } from './layer.js'
 // v23: fold cache.inputs.runtime / workspaceRuntime command output into
 // the key (two namespaced sections after env-values). Command strings
 // live in the resolved config (frozen by `vx lock`); the OUTPUT is
-// resolved live every run, so it stays correct under --frozen. No
+// resolved live every run, so it stays correct under the lock. No
 // SCHEMA bump — only Cache.key derivation changed.
-// v24: vx-lock.json added to the always-ignored input set (cache/
+// v24: .vx/projects.lock.json added to the always-ignored input set (cache/
 // inputs.ts ALWAYS_IGNORE). A task whose globs matched the root
 // lockfile (broad `**/*` on the root project) drops it from the hashed
 // file set, so those keys change; tasks that never matched it are
@@ -105,7 +105,12 @@ import type { CacheKeyInput } from './layer.js'
 // never listed sits under the key of that directory empty (A-61).
 // v42: the stored output is both streams in order (orchestrator/output-log.ts);
 // a v41 entry holds stdout alone and replays no stderr.
-export const CACHE_VERSION = 'vx-cache-v42'
+// v43: a scoped run stores under the scope's key locally too (F4,
+// 2026-10-14); a v42 entry a scoped run left locally sits under the default key.
+// v43 stays when core stopped folding package files (2026-10-14): the
+// `workspace:` and `pkg:` parts left the chain, so every key moved and no
+// unchanged key holds wrong bytes.
+export const CACHE_VERSION = 'vx-cache-v43'
 
 /**
  * The digest a key folds for an input gone between its enumeration and its
@@ -151,16 +156,12 @@ export async function foldKey(
   const cap = input.captureInto
   let h = xxh3(CACHE_VERSION)
   h = xxh3(`task:${input.taskId}`, h)
-  h = xxh3(`workspace:${input.workspaceFingerprint}`, h)
-  h = xxh3(`pkg:${input.projectPackageJsonHash}`, h)
   h = xxh3(`config:${input.taskConfigHash}`, h)
   if (cap) {
     // Recorded so `vx why` can name a key that moved only because vx
     // keys differently now (an upgrade): unrecorded, every task's miss
     // read as "inputs differ" with no input changed (X-142).
     cap.push({ kind: 'format', name: 'cache-version', hash: CACHE_VERSION })
-    cap.push({ kind: 'workspace', name: 'fingerprint', hash: input.workspaceFingerprint })
-    cap.push({ kind: 'package', name: 'package.json', hash: input.projectPackageJsonHash })
     cap.push({ kind: 'config', name: 'config', hash: input.taskConfigHash })
   }
 

package/src/cache/layer.ts

@@ -65,27 +65,12 @@ export interface CacheKeyInput {
     readonly hash: string
     readonly projectDir: string
   }>
-  /**
-   * Workspace-level fingerprint — typically a hash of `pnpm-lock.yaml` +
-   * `pnpm-workspace.yaml`. Folds resolved dep versions and workspace shape
-   * into every task's key, so a lockfile bump invalidates everything.
-   */
-  workspaceFingerprint: string
   /**
    * CLI args forwarded to the task (after `--`). Folded into the key so that
    * the same command with different forwarded args is treated as a distinct
    * run, never a spurious cache hit.
    */
   forwardArgs?: readonly string[]
-  /**
-   * Hash of the project's `package.json` bytes. Folded into the key
-   * implicitly (Turbo / Nx parity) so dep changes invalidate every
-   * task in that project, even when `cache.inputs.files` doesn't
-   * cover package.json. Empty string when the project has no
-   * package.json (impossible in practice — workspace discovery
-   * requires one — but we don't fail-loud here).
-   */
-  projectPackageJsonHash: string
   /**
    * Precomputed content hashes (git blob OIDs) keyed by absolute
    * path — typically the trusted-index OID map harvested by the
@@ -190,7 +175,7 @@ export interface RunRecord {
   endedAt: number // ms-epoch wall clock
   /**
    * Optional analytics columns. Populated by the orchestrator/runner;
-   * stored as NULL on rows from older runs. Surfaced via `vx stats`
+   * stored as NULL on rows from older runs. Surfaced via `vx info`
    * and consumable from CI by reading cache.db directly.
    */
   runId?: string // ULID shared across every task in one `vx run` invocation
@@ -495,7 +480,7 @@ export class CorruptArtifactError extends Error {
 
 /**
  * `restoreOutputs` found no artifact where the probe found one: it was
- * removed in between — a `vx cache prune` in another shell, or the
+ * removed in between — a `vx cache clean` in another shell, or the
  * `cacheRetention` of another workspace sharing the cache directory. The
  * bytes are not wrong, they are gone, so the entry is a MISS and the task
  * runs (execute-task.ts); nothing about the cache needs throwing away.
@@ -702,6 +687,12 @@ export interface CacheLayer {
      * Only computed on the miss/save path — never on a hit.
      */
     inputComponents?: readonly TaskInputRow[]
+    /**
+     * For a sandboxed task: whether it could read a canonical path. A
+     * symlinked output is packed as its target's bytes, outside the
+     * sandbox, so one whose target the task could not read is refused.
+     */
+    readable?: ((real: string) => boolean) | undefined
   }): Promise<void>
   /**
    * Adopt an artifact produced elsewhere — the remote-hit path. Streams

package/src/cache/layered-cache.ts

@@ -33,12 +33,11 @@ import type {
   SaveArgs,
 } from './cache.js'
 import { FULL_CACHE_POLICY, type OutputDirRow } from './cache.js'
-import { xxh3hex } from '../util/index.js'
 
 /**
  * What a remote cache layer must provide — THE plugin seam for remote
- * caching. Core ships no wire client; a plugin's `cache` capability (or an
- * embedder via `RunOptions.remoteCache`) supplies an implementation speaking
+ * caching. Core ships no wire client; a plugin's `cache` hook returns one
+ * (or an embedder passes one as `RunOptions.remoteCache`), speaking
  * whatever protocol it wants, and `LayeredCache` owns everything else:
  * policy gating, in-flight dedup, remote provenance, and the never-fail
  * contract (implementations THROW on failure; LayeredCache degrades every
@@ -60,6 +59,11 @@ export interface RemoteCacheLayer {
    * dropped before it is printed.
    */
   readonly endpoint?: string
+  /**
+   * What the wire's credential allows, when less than both (a read-only
+   * token): core clears the run's remote axis it lacks. Omitted → both.
+   */
+  readonly access?: { readonly read?: boolean; readonly write?: boolean }
   /** Existence probe (drives the plan path's `--dry` remote prediction). */
   has(hash: string): Promise<boolean>
   /**
@@ -161,91 +165,6 @@ function batchOf(hashes: readonly string[]): { batch: string } {
   return { batch: `of ${hashes.length} artifact${hashes.length === 1 ? '' : 's'}` }
 }
 
-/**
- * The remote as an untrusted scope sees it: reads try the scope's key,
- * where a PR's own earlier runs left it, then the trusted one; writes go to the scope's key only. A scope's key is
- * derived from the task key, so every wire stores it unchanged and the
- * trusted keyspace never holds a scoped write. What a scoped read
- * returns is ingested under the TASK key, and ingest refuses an artifact
- * recording another key, so a derived-key collision degrades to a miss.
- */
-class ScopedRemote implements RemoteCacheLayer {
-  readonly endpoint?: string
-  readonly hasMany?: (hashes: readonly string[]) => Promise<Set<string> | null>
-  /** Task keys a batch probe found under the trusted key alone: their GET skips the scope's. */
-  private readonly trustedOnly = new Set<string>()
-
-  constructor(
-    private readonly remote: RemoteCacheLayer,
-    private readonly scope: string,
-  ) {
-    if (remote.endpoint !== undefined) this.endpoint = remote.endpoint
-    if (remote.hasMany !== undefined) this.hasMany = (hashes) => this.scopedHasMany(hashes)
-  }
-
-  private scoped(hash: string): string {
-    return scopedKey(this.scope, hash)
-  }
-
-  async has(hash: string): Promise<boolean> {
-    return this.fallThrough(
-      () => this.remote.has(this.scoped(hash)),
-      () => this.remote.has(hash),
-    )
-  }
-
-  /**
-   * The scope's answer, else the trusted one. A scope lookup that fails
-   * still asks the trusted key, so a hit there is not lost; its error is
-   * rethrown (and warned) when the trusted key fails or has nothing too.
-   */
-  private async fallThrough<T>(own: () => Promise<T>, trusted: () => Promise<T>): Promise<T> {
-    let found: T
-    try {
-      found = await own()
-    } catch (err) {
-      const fallback = await trusted().catch(() => undefined)
-      if (!fallback) throw err
-      return fallback
-    }
-    return found || trusted()
-  }
-
-  private async scopedHasMany(hashes: readonly string[]): Promise<Set<string> | null> {
-    const scoped = hashes.map((h) => this.scoped(h))
-    const [trusted, own] = await Promise.all([
-      this.remote.hasMany!(hashes),
-      this.remote.hasMany!(scoped),
-    ])
-    if (trusted == null || own == null) return null
-    const found = new Set(trusted)
-    for (let i = 0; i < hashes.length; i++) {
-      if (own.has(scoped[i]!)) found.add(hashes[i]!)
-      else if (trusted.has(hashes[i]!)) this.trustedOnly.add(hashes[i]!)
-    }
-    return found
-  }
-
-  async get(
-    hash: string,
-  ): Promise<{ body: Blob | Response; durationMs: number | undefined } | null> {
-    if (this.trustedOnly.has(hash)) return this.remote.get(hash)
-    return this.fallThrough(
-      () => this.remote.get(this.scoped(hash)),
-      () => this.remote.get(hash),
-    )
-  }
-
-  put(hash: string, body: Blob, meta: { durationMs: number }): Promise<void> {
-    return this.remote.put(this.scoped(hash), body, meta)
-  }
-}
-
-/** The key an untrusted scope stores `hash` under: task-key shaped, 16 hex. */
-function scopedKey(scope: string, hash: string): string {
-  return xxh3hex(`vx-cache-scope\0${scope}\0${hash}`)
-}
-
 export interface LayeredCacheOptions {
   /**
    * Called for the remote failures the layer degrades to a miss, once per
@@ -312,17 +231,12 @@ export class LayeredCache implements CacheLayer {
    */
   private readonly reported = new Map<string, { cause: string; repeats: number }>()
 
-  /** The remote as this run's scope sees it: `remote` itself when trusted. */
-  private readonly wire: RemoteCacheLayer
-
   constructor(
     readonly local: Cache,
     private readonly remote: RemoteCacheLayer,
     private readonly options: LayeredCacheOptions = {},
   ) {
     this.policy = options.policy ?? FULL_CACHE_POLICY
-    const scope = this.policy.remoteScope
-    this.wire = scope === undefined ? remote : new ScopedRemote(remote, scope)
     this.endpoint = printableEndpoint(remote.endpoint)
   }
 
@@ -349,11 +263,11 @@ export class LayeredCache implements CacheLayer {
    * degrades to "no batch info" and the caller falls back to per-hash.
    */
   async remoteHasMany(hashes: readonly string[]): Promise<Set<string> | null> {
-    if (!this.policy.remoteRead || this.wire.hasMany === undefined) return null
+    if (!this.policy.remoteRead || this.remote.hasMany === undefined) return null
     try {
       // `return await`, deliberately: the catch below is the never-fail
       // contract, and a returned promise's rejection would sail past it.
-      const found: unknown = await this.wire.hasMany(hashes)
+      const found: unknown = await this.remote.hasMany(hashes)
       if (found !== null && found !== undefined && !(found instanceof Set)) {
         this.reportRemoteError(
           'probe',
@@ -394,7 +308,7 @@ export class LayeredCache implements CacheLayer {
       return this.asRemote(hash, localHit)
     }
 
-    // Remote reads disabled (e.g. `--cache=remote:`): a local miss is a
+    // Remote reads disabled (e.g. `--cache-policy=remote:`): a local miss is a
     // real miss; never touch the remote layer.
     if (!this.policy.remoteRead) return null
 
@@ -410,7 +324,7 @@ export class LayeredCache implements CacheLayer {
     // the artifact + index row this pull just wrote exist regardless of
     // policy, and the gate ("don't serve hits from the pre-existing local
     // cache") must not discard them. Going through the gated `get` here
-    // made `--cache=local:,remote:rw` download the artifact, throw the hit
+    // made `--cache-policy=local:,remote:rw` download the artifact, throw the hit
     // away, re-execute and re-upload — on every run, forever.
     const materialized = await this.local.getIngested(hash)
     if (!materialized) return null
@@ -437,7 +351,7 @@ export class LayeredCache implements CacheLayer {
     if ((await this.local.has(hash)) === 'local') return 'local'
     if (!this.policy.remoteRead) return null
     try {
-      return (await this.wire.has(hash)) ? 'remote' : null
+      return (await this.remote.has(hash)) ? 'remote' : null
     } catch (err) {
       this.reportRemoteError('probe', hash, err)
       return null
@@ -474,7 +388,7 @@ export class LayeredCache implements CacheLayer {
     const fetchStart = performance.now()
     let remoteResult: unknown
     try {
-      remoteResult = await this.wire.get(hash)
+      remoteResult = await this.remote.get(hash)
     } catch (err) {
       this.reportRemoteError('download', hash, err)
       return false
@@ -560,11 +474,11 @@ export class LayeredCache implements CacheLayer {
     // queued job holds a path, not a buffer, a plugin that streams the Blob
     // never holds it whole, and every read of it sees the same bytes though
     // a re-save of the key renames others over the live name. If a
-    // concurrent `vx cache prune` removed the artifact first the pin throws
+    // concurrent `vx cache clean` removed the artifact first the pin throws
     // and this upload is skipped — the never-fail contract.
     const hash = args.hash
     const durationMs = args.entry.durationMs
-    // Local writes disabled (`--cache=local:,remote:rw`): there is no
+    // Local writes disabled (`--cache-policy=local:,remote:rw`): there is no
     // on-disk artifact to read later, so the bytes must be packed NOW,
     // while this task's output files are still on disk. Deferring THIS
     // read would pack whatever the tree happens to hold when the job
@@ -587,7 +501,7 @@ export class LayeredCache implements CacheLayer {
         let body: Blob
         if (packed !== undefined) body = new Blob([packed])
         else ({ body, release } = this.local.pinArtifact(hash))
-        await this.wire.put(hash, body, { durationMs })
+        await this.remote.put(hash, body, { durationMs })
         tally.count++
         tally.bytes += body.size
         tally.ms += Math.round(performance.now() - start)