@vzn/vx-migrate 0.0.651 → 0.0.653

package/src/nx/nx-map.ts

@@ -17,6 +17,7 @@
 // default configuration is folded into the base task.
 
 import { existsSync } from 'node:fs'
+import { lstat } from 'node:fs/promises'
 import path from 'node:path'
 import { type Duration, type GeneratedProject, type GeneratedTask, UserError } from '@vzn/vx'
 import type { PackageMeta } from '../packages.js'
@@ -34,8 +35,9 @@ import {
   resolveSharedWorkspaceOutputs,
   wildcardOutput,
   wildcardTodo,
+  uncache,
 } from '../shared-outputs.js'
-import type { TrackedKinds } from '../tracked-outputs.js'
+import { gitIgnored, type TrackedKinds } from '../tracked-outputs.js'
 import { isRecord, packageScripts, relPosix } from '../paths.js'
 import { withLernaOrder } from './lerna.js'
 import { mapNxDeps, matchNxProjects, type TaskNameFor } from './nx-deps.js'
@@ -47,6 +49,7 @@ import {
   ownerTargetOf,
 } from './nx-dotenv.js'
 import { emptyNxInputs, expandNxInputs } from './nx-inputs.js'
+import { dotenvGlobsProbe } from '../dotenv-probe.js'
 import { planNxUpstream, type NxUpstream } from './nx-upstream.js'
 import { mapNxOutputs, nxDefaultOutputs, nxProjectOutputs } from './nx-outputs.js'
 
@@ -247,6 +250,13 @@ export interface MapNxOptions {
    * `nx-exec`. The live plugin's only: a migration writes no function.
    */
   readonly executors?: NxExecutors
+  /**
+   * The root lockfile when no plugin claims it (the live plugin's only):
+   * core keys no lockfile, so an `externalDependencies` input keys the
+   * file. Absent, a lockfile plugin keys the dependencies (a migration
+   * declares one).
+   */
+  readonly lockfile?: string
 }
 
 /** One target of a translated executor, as the graph resolved it. */
@@ -294,6 +304,8 @@ type MapOpts = MapNxOptions & {
   readonly hooks: (dir: string) => boolean
   /** Tasks per `syncGenerators` list, said once in the notes. */
   readonly syncTasks: Map<string, number>
+  /** Root-relative outputs git ignores (`ignoredOutputs`); unknown without git. */
+  readonly ignoredOutputs: ReadonlySet<string> | undefined
 }
 
 export interface NxMapping {
@@ -319,6 +331,46 @@ function nxTags(node: NxNode | undefined): string[] {
     : []
 }
 
+/**
+ * The outputs of every project whose input Nx never hashes: git tracks
+ * nothing under it and ignores it, as Nx's file map skips gitignored files
+ * (a changed `dist` file is a hit under Nx 23.3, YL-1). One untracked but
+ * not ignored is in Nx's file map, so an input under it is hashed: taken
+ * for ignored, `build` keyed on no file and a generated source's edit
+ * replayed (stale hit). One `git check-ignore` per mapping.
+ */
+async function ignoredOutputs(
+  root: string,
+  nodes: Readonly<Record<string, NxNode>>,
+  tracked: (rel: string) => TrackedKinds,
+): Promise<ReadonlySet<string>> {
+  const untracked = new Set<string>()
+  for (const [nodeName, node] of Object.entries(nodes)) {
+    const rel = normRel(node?.data?.root ?? '')
+    for (const o of nxProjectOutputs(node?.data?.targets, rel || '.', node?.name ?? nodeName)) {
+      const dir = path.posix.dirname(o)
+      if (
+        tracked(o).files.length === 0 &&
+        !tracked(dir).files.includes(dir === '.' ? o : o.slice(dir.length + 1))
+      )
+        untracked.add(o)
+    }
+  }
+  // A missing `dist` matches a `dist/` rule only spelled as a directory;
+  // an existing file never does.
+  const hit = await gitIgnored(
+    root,
+    [...untracked].flatMap((o) => [o, `${o}/`]),
+  )
+  const out = new Set<string>()
+  for (const o of untracked) {
+    if (hit.has(o)) out.add(o)
+    else if (hit.has(`${o}/`) && !(await lstat(path.join(root, o)).catch(() => null))?.isFile())
+      out.add(o)
+  }
+  return out
+}
+
 function normRel(p: string): string {
   return p === '' || p === '.' ? '.' : p.replace(/\/$/, '')
 }
@@ -354,6 +406,8 @@ export async function mapNxWorkspace(
     pnp: yarnPnp(root),
     hooks: (dir) => runsScriptHooks(dir, hookMemo) !== null,
     syncTasks: new Map(),
+    ignoredOutputs:
+      opts.tracked === undefined ? undefined : await ignoredOutputs(root, nodeMap, opts.tracked),
   }
 
   const metaByRel = new Map<string, PackageMeta>()
@@ -408,7 +462,13 @@ export async function mapNxWorkspace(
     nodeNameOf.set(synthetic, nodeName)
   }
 
-  const upstream = planNxUpstream(nodeMap, g.dependencies, namedInputs, metaByNode, opts.tracked)
+  const upstream = planNxUpstream(
+    nodeMap,
+    g.dependencies,
+    namedInputs,
+    metaByNode,
+    mapOpts.ignoredOutputs,
+  )
 
   const taskNameFor: TaskNameFor = (project, target, configuration) => {
     const t = nodeMap[project]?.data?.targets?.[target]
@@ -595,8 +655,15 @@ export async function mapNxWorkspace(
       }
       dropUnheldDeps(t, meta.name, emitted, emittedIds)
       const reader = dependentReaders.get(t)
-      if (reader !== undefined && !reachesProducer(t, meta.name, emittedIds, reached)) {
-        delete t.task!['cache']
+      if (
+        reader !== undefined &&
+        !reachesProducer(t, meta.name, emittedIds, reached, (target) =>
+          nodeName === undefined
+            ? undefined
+            : nxEdges(nodeName, target).map((n) => metaByNode.get(n)?.name),
+        )
+      ) {
+        uncache(t.task!)
         t.todos.push(orphanReaderTodo(reader.globs, reader.dependsOn))
       }
     }
@@ -612,6 +679,7 @@ export async function mapNxWorkspace(
 
   resolveAtomizedWorkspaceOutputs(root, projects, split)
   excludeWorkspaceOutputs(root, projects)
+  keyUncachedProducerOutputs(projects, reached)
   // A migration leaves Nx behind, so `nx sync` is no advice there: what a
   // generator keeps (the TypeScript one's tsconfig `references`) is the
   // user's to keep. `nx()` runs with Nx installed.
@@ -663,10 +731,7 @@ function resolveAtomizedWorkspaceOutputs(
   const cached = (ps: readonly { name: string; dir: string; tasks: GeneratedTask[] }[]): number => {
     const copy = structuredClone(ps.map((p) => ({ name: p.name, dir: p.dir, tasks: p.tasks })))
     resolveSharedWorkspaceOutputs(root, copy)
-    return copy.reduce(
-      (n, p) => n + p.tasks.filter((t) => t.task?.['cache'] !== undefined).length,
-      0,
-    )
+    return copy.reduce((n, p) => n + p.tasks.filter((t) => t.task?.['cache'] === true).length, 0)
   }
   const better = split.size > 0 && cached(last) > cached(projects)
   resolveSharedWorkspaceOutputs(root, better ? last : projects)
@@ -865,8 +930,9 @@ function buildTask(
     rel: projectRel,
     name: projectName,
     outputs: nxProjectOutputs(nodeMap[nodeName]?.data?.targets, projectRel, projectName),
-    ...(opts.tracked === undefined ? {} : { tracked: opts.tracked }),
+    ...(opts.ignoredOutputs === undefined ? {} : { ignoredOutputs: opts.ignoredOutputs }),
     rootDeps: opts.rootDeps,
+    ...(opts.lockfile === undefined ? {} : { lockfile: opts.lockfile }),
   }
   expandNxInputs(target.inputs ?? [], upstream.namedOf(nodeName), at, inputs, todos)
   const cacheWanted =
@@ -1061,42 +1127,160 @@ function buildTask(
   if (cacheEnabled) {
     const outputs: Record<string, unknown> = { files: takingBack(outFiles) }
     if (wsOutFiles.length > 0) outputs.workspaceFiles = takingBack(wsOutFiles)
-    task.cache = { outputs }
+    task.outputs = outputs
+    task.cache = true
   }
 
   const generated: GeneratedTask = { name: variant.name, todos, task }
   if (cacheEnabled && inputs.dependentOutputs.length > 0)
-    dependentReaders.set(generated, { globs: inputs.dependentOutputs, dependsOn: target.dependsOn })
+    dependentReaders.set(generated, {
+      globs: inputs.dependentOutputs,
+      transitive: inputs.transitiveOutputs,
+      dependsOn: target.dependsOn,
+    })
+  const produced = [
+    ...outFiles.filter((o) => !o.startsWith('!')).map((o) => path.posix.join(projectRel, o)),
+    ...wsOutFiles.filter((o) => !o.startsWith('!')),
+  ]
+  if (produced.length > 0) producedPaths.set(generated, produced)
   return generated
 }
 
+/** Each task's Nx outputs, workspace-relative, cached or not: what a reader of them probes. */
+const producedPaths = new WeakMap<GeneratedTask, string[]>()
+
 /**
- * The cached readers of `dependentTasksOutputFiles`, judged again once the
- * graph has its final edges: a `^build` kept because another project builds
- * reached no producer of this one (nx-examples' codegen, its .NET
- * ProductsApi no node once @nx/dotnet failed to load), and the key saw
- * nothing the task reads (Growth, nx-codegen-dropped-producer.sh).
+ * Nx hashes the files a `dependentTasksOutputFiles` reader names in its
+ * producers' outputs; vx folds each producer's key, which covers what a
+ * cached producer writes and not what an uncached one fetched from outside
+ * (a `cache: false` `fetch` writing a gitignored schema): the reader hit
+ * and replayed the old schema's code. Those files are keyed by a probe at
+ * the root, as `turbo()` keys a `dependencyOutputs` input of an uncached
+ * producer, and the producer is left out of the fold (`inputs.tasks`), so
+ * core answers the probe after it ran.
  */
-const dependentReaders = new WeakMap<GeneratedTask, { globs: string[]; dependsOn: unknown }>()
+function keyUncachedProducerOutputs(
+  projects: readonly GeneratedProject[],
+  reached: (name: string) => ReadonlySet<string>,
+): void {
+  const byId = new Map<string, { project: string; task: GeneratedTask }>()
+  for (const p of projects)
+    for (const t of p.tasks) byId.set(`${p.name}#${t.name}`, { project: p.name, task: t })
+  const edgesOf = (project: string, deps: unknown): [id: string, filter: string][] =>
+    (Array.isArray(deps) ? deps : []).flatMap((d): [string, string][] => {
+      if (typeof d !== 'string' || d.includes('*') || d.includes('#inputs:')) return []
+      return d.startsWith('^')
+        ? [...reached(project)].map((q) => [`${q}#${d.slice(1)}`, `${q}#${d.slice(1)}`])
+        : [[d.includes('#') ? d : `${project}#${d}`, d]]
+    })
+  for (const p of projects) {
+    for (const t of p.tasks) {
+      const reader = dependentReaders.get(t)
+      if (reader === undefined || t.task?.['cache'] !== true) continue
+      const rels: string[] = []
+      const unfold: string[] = []
+      const keyOutputs = (producer: GeneratedTask, globs: readonly string[]): void => {
+        for (const o of producedPaths.get(producer) ?? [])
+          // A glob output (`dist/**/*.{js,d.ts}{,.map}`): every file under
+          // its literal head, which the probe can walk.
+          if (/[*?[{]/.test(o)) rels.push(`${globHead(o)}/**/*`)
+          else
+            for (const g of globs)
+              // `**/<name>` is a find under the output; any other glob (a brace, a
+              // class), every file there.
+              rels.push(/^\*\*\/[^/*?[{]*\*?[^/*?[{]*$/.test(g) ? `${o}/${g}` : `${o}/**/*`)
+      }
+      const uncachedWriter = (producer: GeneratedTask | undefined): producer is GeneratedTask =>
+        producer?.task?.['exec'] !== undefined &&
+        producer.task['cache'] !== true &&
+        (producedPaths.get(producer)?.length ?? 0) > 0
+      for (const [id, filter] of edgesOf(p.name, t.task['dependsOn'])) {
+        const producer = byId.get(id)?.task
+        if (producer === undefined) continue
+        // `transitive: true` reads the outputs of every task below, not
+        // only the direct ones: an uncached `fetch` behind an `nx:noop`
+        // `prep` hid its schema, and the reader replayed the old one (hunt,
+        // 2026-11-08). A key folding the edge answers the probe before the
+        // fetch ran, so the edge is left out and every output below it,
+        // cached or not, is keyed by the probe.
+        const below: GeneratedTask[] = []
+        if (reader.transitive.length > 0) {
+          const seen = new Set<string>([id])
+          const stack = edgesOf(byId.get(id)!.project, producer.task?.['dependsOn'])
+          while (stack.length > 0) {
+            const [next] = stack.pop()!
+            const node = byId.get(next)
+            if (seen.has(next) || node === undefined) continue
+            seen.add(next)
+            below.push(node.task)
+            stack.push(...edgesOf(node.project, node.task.task?.['dependsOn']))
+          }
+        }
+        if (!uncachedWriter(producer) && !below.some(uncachedWriter)) continue
+        unfold.push(`!${filter}`)
+        keyOutputs(producer, reader.globs)
+        for (const b of below) keyOutputs(b, reader.transitive)
+      }
+      if (rels.length === 0) continue
+      const probe = dotenvGlobsProbe([...new Set(rels)])
+      if (probe === null) {
+        uncache(t.task)
+        t.todos.push(
+          `reads ${reader.globs.map((g) => `\`${g}\``).join(', ')} from the outputs of an uncached task it depends on, ` +
+            'which vx cannot key by a probe — uncached here; key it in a vx.config to cache it',
+        )
+        continue
+      }
+      const inputs = t.task['inputs'] as Record<string, unknown>
+      inputs['workspaceRuntime'] = [...((inputs['workspaceRuntime'] as unknown[]) ?? []), probe]
+      inputs['tasks'] = ['*', '^*', ...unfold]
+    }
+  }
+}
+
+function globHead(glob: string): string {
+  const segs = glob.split('/')
+  const i = segs.findIndex((s) => /[*?[{]/.test(s))
+  return segs.slice(0, i).join('/')
+}
+
+const dependentReaders = new WeakMap<
+  GeneratedTask,
+  { globs: string[]; transitive: string[]; dependsOn: unknown }
+>()
 
 function orphanReaderTodo(globs: readonly string[], dependsOn: unknown): string {
   return `reads ${globs.map((g) => `\`${g}\``).join(', ')} from the outputs of the tasks it depends on, and no task it depends on is migrated (dependsOn ${JSON.stringify(dependsOn ?? [])}) — uncached here, so it never replays output generated from an older input; migrate the producer and depend on it to cache this task`
 }
 
-/** Whether one of `t`'s final edges reaches a task vx runs. */
+/**
+ * Whether a cached reader of `dependentTasksOutputFiles` still reaches a
+ * producer once the graph has its final edges: one of them reaches a task
+ * vx runs, or is a `^` edge every project Nx links (`nxLinked`: their vx
+ * names) runs it on. A `^build` kept because another project builds, while
+ * Nx links a producer vx carries no task for, keyed nothing the task reads
+ * (Growth, nx-codegen-dropped-producer.sh). With none linked, Nx hashes
+ * nothing there either: a leaf library's inferred `build` (`^build`,
+ * @nx/js/typescript) ran uncached every time where Nx caches it (hunt,
+ * 2026-11-08).
+ */
 function reachesProducer(
   t: GeneratedTask,
   project: string,
   emittedIds: ReadonlySet<string>,
   reached: (name: string) => ReadonlySet<string>,
+  nxLinked: (target: string) => ReadonlyArray<string | undefined> | undefined,
 ): boolean {
   const deps = t.task?.['dependsOn']
   if (!Array.isArray(deps)) return false
   return deps.some((d) => {
     if (typeof d !== 'string' || d.includes('*')) return true
     if (d.includes('#inputs:')) return false
-    if (d.startsWith('^'))
-      return [...reached(project)].some((p) => emittedIds.has(`${p}#${d.slice(1)}`))
+    if (d.startsWith('^')) {
+      const target = d.slice(1)
+      if ([...reached(project)].some((p) => emittedIds.has(`${p}#${target}`))) return true
+      return nxLinked(target)?.every((p) => emittedIds.has(`${p}#${target}`)) === true
+    }
     return d.includes('#') || emittedIds.has(`${project}#${d}`)
   })
 }

package/src/nx/nx-outputs.ts

@@ -189,6 +189,8 @@ export function mapNxOutputs(
       )
       continue
     }
+    const rootWide =
+      (projectRel === '' || projectRel === '.') && o.slice(neg.length).startsWith('{workspaceRoot}')
     const globs = vxOutputGlobs(neg + s)
     if (globs === null) {
       todos.push(`output ${JSON.stringify(o)} has a glob form vx cannot spell — dropped`)
@@ -197,7 +199,10 @@ export function mapNxOutputs(
     for (const g of globs) {
       const gn = g.startsWith('!') ? '!' : ''
       const gs = g.slice(gn.length)
-      const own = underProject(gs, projectRel)
+      // As the root project's inputs map (nx-inputs.ts): a `{workspaceRoot}`
+      // output names a workspace path, which may lie in a nested project a
+      // project glob never reaches (core refuses one there).
+      const own = rootWide ? null : underProject(gs, projectRel)
       if (own !== null) {
         outFiles.push(gn + (own === '' ? '**' : withProjectDir(own, projectRel, true)))
         continue

package/src/nx/nx-upstream.ts

@@ -18,11 +18,10 @@
 // and edges only out of the cycle.
 import type { GeneratedTask } from '@vzn/vx'
 import type { PackageMeta } from '../packages.js'
-import type { TrackedKinds } from '../tracked-outputs.js'
 import { emptyNxInputs, expandNxInputs, type NxInputs } from './nx-inputs.js'
 import { nxProjectOutputs } from './nx-outputs.js'
 import { matchNxProjects } from './nx-deps.js'
-import { literalGlob } from '../glob-grammar.js'
+import { apartTakeBacks, literalGlob } from '../glob-grammar.js'
 
 interface GraphNode {
   name?: string
@@ -73,7 +72,7 @@ export function planNxUpstream(
   dependencies: unknown,
   workspaceNamed: Readonly<Record<string, unknown[]>> | null,
   metaByNode: ReadonlyMap<string, PackageMeta>,
-  tracked?: (rel: string) => TrackedKinds,
+  ignoredOutputs?: ReadonlySet<string>,
 ): NxUpstream {
   const isProject = (n: string): boolean => typeof nodes[n]?.data?.root === 'string'
   const projectTags = Object.entries(nodes).map(([name, n]) => ({
@@ -194,13 +193,12 @@ export function planNxUpstream(
     expandOwn(node, name, own, todos)
     const rel = normRel(nodes[node]?.data?.root ?? '')
     const inputs = emptyNxInputs()
-    for (const g of own.files) {
+    const files = own.files.map((g) => {
       const neg = g.startsWith('!') ? '!' : ''
-      inputs.wsFiles.push(
-        rel === '' ? g : `${neg}${literalGlob(rel)}/${neg === '' ? g : g.slice(1)}`,
-      )
-    }
-    inputs.wsFiles.push(...own.wsFiles)
+      return rel === '' ? g : `${neg}${literalGlob(rel)}/${neg === '' ? g : g.slice(1)}`
+    })
+    // Two of Nx's sets in one list, as in `expandNxInputs`.
+    inputs.wsFiles.push(...apartTakeBacks(files, own.wsFiles).flat())
     inputs.envNames.push(...own.envNames)
     inputs.runtimeCmds.push(...own.runtimeCmds)
     inputs.upstream.push(...own.upstream)
@@ -223,13 +221,15 @@ export function planNxUpstream(
       rel,
       name: nm,
       outputs: nxProjectOutputs(nodes[node]?.data?.targets, rel || '.', nm),
-      ...(tracked === undefined ? {} : { tracked }),
+      ...(ignoredOutputs === undefined ? {} : { ignoredOutputs }),
     }
     expandNxInputs([name], namedOf(node), at, into, todos)
   }
 
   const merge = (from: NxInputs, into: NxInputs): void => {
-    into.wsFiles.push(...from.wsFiles)
+    // A node's sets meet the reader's in one list: a `!` reaching another
+    // set's entry goes, as in `expandNxInputs`.
+    into.wsFiles.splice(0, Infinity, ...apartTakeBacks(into.wsFiles, from.wsFiles).flat())
     for (const n of from.envNames) if (!into.envNames.includes(n)) into.envNames.push(n)
     for (const c of from.runtimeCmds) if (!into.runtimeCmds.includes(c)) into.runtimeCmds.push(c)
   }

package/src/nx-cache/index.ts

@@ -22,7 +22,7 @@ import {
 } from '@vzn/vx'
 import { deadline, MAX_TIMER_MS } from '../remote-deadline.js'
 import { checkRemoteUrl } from '../remote-url.js'
-import { refusal } from '../remote-refusal.js'
+import { hideTokens, hidingErrors, refusal } from '../remote-refusal.js'
 import { OutageBreaker } from '../remote-breaker.js'
 import { Cooldown, withRetry } from '../remote-retry.js'
 import {
@@ -112,6 +112,8 @@ export class NxRemoteCache implements RemoteCacheLayer {
   private token: string | undefined
   /** Set by `open` when the token came from the keychain: a refusal deletes it. */
   private forget: (() => Promise<void>) | undefined
+  /** The token as a refusal that quotes it says it: `***`. */
+  private readonly hidden = (text: string): string => hideTokens(text, [this.token])
   private readonly keychainRemote: KeychainRemote
   constructor(
     private readonly config: NxCacheConfig,
@@ -156,21 +158,24 @@ export class NxRemoteCache implements RemoteCacheLayer {
       // every hit read as a corrupt artifact (nx#33092).
       headers['Accept'] = 'application/octet-stream'
     }
-    const res = await this.breaker.send(
-      () =>
-        withRetry(
-          () =>
-            this.fetchImpl(`${this.config.url}/v1/cache/${hash}`, {
-              method,
-              headers,
-              ...(body === undefined ? {} : { body }),
-              signal: deadline(this.config.timeoutMs),
-            }),
-          this.config.retries,
-          this.wait,
-          this.cooldown,
-        ),
-      method === 'GET',
+    const res = await hidingErrors(
+      this.breaker.send(
+        () =>
+          withRetry(
+            () =>
+              this.fetchImpl(`${this.config.url}/v1/cache/${hash}`, {
+                method,
+                headers,
+                ...(body === undefined ? {} : { body }),
+                signal: deadline(this.config.timeoutMs),
+              }),
+            this.config.retries,
+            this.wait,
+            this.cooldown,
+          ),
+        method === 'GET',
+      ),
+      this.hidden,
     )
     if (method === 'PUT' && res.status === 403) {
       const first = !this.writesRefused
@@ -178,14 +183,14 @@ export class NxRemoteCache implements RemoteCacheLayer {
       if (!first) return undefined
       // The status and the server's own words, as turboCache() says them.
       throw new Error(
-        `${(await refusal(res)).message}: access forbidden (a read-only token cannot write); uploads off for this run, reads go on`,
+        `${(await refusal(res, this.hidden)).message}: access forbidden (a read-only token cannot write); uploads off for this run, reads go on`,
       )
     }
     if (res.status === 401 || res.status === 403) {
       const first = !this.disabled
       this.disabled = true
       if (!first) return undefined
-      const said = (await refusal(res)).message
+      const said = (await refusal(res, this.hidden)).message
       const why =
         res.status === 401
           ? 'missing or invalid token'
@@ -200,43 +205,52 @@ export class NxRemoteCache implements RemoteCacheLayer {
     return res
   }
 
-  async get(hash: string): Promise<{ body: Response; durationMs: number | undefined } | null> {
+  async get(
+    hash: string,
+  ): Promise<{ body: Response; durationMs: number | undefined } | null | undefined> {
     const res = await this.fetch(hash)
     // The Nx wire carries no producing-task duration.
-    return res === null ? null : { body: res, durationMs: undefined }
+    return res === null || res === undefined ? res : { body: res, durationMs: undefined }
   }
 
-  private async fetch(hash: string): Promise<Response | null> {
-    if (this.disabled) return null
+  /** The record; null when the server holds none, undefined when off or refused (no answer). */
+  private async fetch(hash: string): Promise<Response | null | undefined> {
+    if (this.disabled) return undefined
     const res = await this.request('GET', hash)
-    if (res === undefined) return null
+    if (res === undefined) return undefined
     if (res.status !== 200) {
       if (res.status === 404) {
         await res.body?.cancel()
         return null
       }
-      throw await refusal(res)
+      throw await refusal(res, this.hidden)
     }
     return res
   }
 
   async has(hash: string): Promise<{ size?: number } | null> {
     const res = await this.fetch(hash)
-    if (res === null) return null
+    if (res === null || res === undefined) return null
     await res.body?.cancel()
     const size = Number(res.headers.get('content-length') ?? NaN)
     return Number.isFinite(size) ? { size } : {}
   }
 
   // Nx's record carries no duration.
-  async put(hash: string, body: Blob): Promise<void | false> {
+  async put(hash: string, body: Blob, meta?: { replace?: true }): Promise<void | false> {
     // Nothing sent, so no upload is counted.
     if (this.disabled || this.writesRefused) return false
     const res = await this.request('PUT', hash, body)
     if (res === undefined) return false
     // The spec answers 200; a store behind it may say 201 or 204.
-    if (res.ok || res.status === 409) return
-    throw await refusal(res)
+    if (res.ok) return
+    // The spec's 409 keeps the held record: fine for a fresh put, but a
+    // `replace` came to write over a copy that did not read back.
+    if (res.status === 409) {
+      await res.body?.cancel()
+      return meta?.replace === true ? false : undefined
+    }
+    throw await refusal(res, this.hidden)
   }
 }
 

package/src/packages.ts

@@ -3,7 +3,8 @@
 // `.vx/workspace.ts` at. Core reads neither (2026-10-14): a project is a
 // directory holding a vx.config.
 import { constants, existsSync, type Dirent } from 'node:fs'
-import { access, readdir, realpath, stat } from 'node:fs/promises'
+import { access, lstat, readdir, realpath, stat } from 'node:fs/promises'
+import { isUtf8 } from 'node:buffer'
 import path from 'node:path'
 import { PROJECT_CONFIG_FILENAMES, ui, UserError } from '@vzn/vx'
 import {
@@ -483,6 +484,55 @@ export async function reachesManifest(workspace: PackageWorkspace): Promise<bool
   return false
 }
 
+/**
+ * The member directories the globs reach whose names are not valid UTF-8,
+ * root-relative, each such byte shown as `\xNN`: a name decodes lossily to
+ * one no directory has, so its package.json reads as absent. Asked only
+ * when the globs reach none, to say why.
+ */
+export async function undecodableMembers(workspace: PackageWorkspace): Promise<string[]> {
+  const { positive } = splitPackageGlobs(workspace.packageGlobs)
+  const parents = new Set<string>()
+  for (const pattern of positive) {
+    for (const dir of await memberDirs(workspace.root, pattern)) {
+      // A valid name may hold U+FFFD itself; a lossy one names nothing.
+      if (!relPosix(workspace.root, dir).includes('\uFFFD')) continue
+      let at = dir
+      while ((await lstat(at).catch((err: unknown) => absent(err, null))) === null)
+        at = path.dirname(at)
+      parents.add(at)
+    }
+  }
+  const out: string[] = []
+  for (const parent of parents) {
+    for (const name of await readdir(Buffer.from(parent), { encoding: 'buffer' })) {
+      if (isUtf8(name)) continue
+      const rel = relPosix(workspace.root, parent)
+      out.push(`${rel === '' ? '' : `${rel}/`}${escapeNotUtf8(name)}`)
+    }
+  }
+  return out.sort()
+}
+
+/** `name` with each byte that is not part of a valid UTF-8 sequence shown as `\xNN`. */
+function escapeNotUtf8(name: Uint8Array): string {
+  let shown = ''
+  for (let i = 0; i < name.length;) {
+    const lead = name[i]!
+    const n =
+      lead < 0x80 ? 1 : lead < 0xc2 ? 0 : lead < 0xe0 ? 2 : lead < 0xf0 ? 3 : lead < 0xf5 ? 4 : 0
+    const seq = name.subarray(i, i + n)
+    if (n > 0 && seq.length === n && isUtf8(seq)) {
+      shown += Buffer.from(seq).toString()
+      i += n
+    } else {
+      shown += `\\x${lead.toString(16).padStart(2, '0')}`
+      i++
+    }
+  }
+  return shown
+}
+
 /**
  * The directories a workspace glob names. For the `<dir>/*` shape this is
  * one readdir of `<dir>` — the same answer `Bun.Glob` gives, at a third of