@vzn/vx 0.0.639 → 0.0.641

package/src/orchestrator/task-hash.ts

@@ -1,6 +1,6 @@
 import { lstatSync } from 'node:fs'
 import path from 'node:path'
-import type { TaskConfig, CacheConfig } from '../config.js'
+import type { TaskConfig } from '../config.js'
 import type { ProjectFilesCache, WorkspaceFilesCache } from '../cache/index.js'
 import {
   ABSENT_INPUT,
@@ -85,11 +85,12 @@ export interface ComputeHashArgs {
  * previews.
  *
  * Caller is responsible for handling the group-task case before
- * calling this — groups have no `exec` and no `cache.inputs`, so the
+ * calling this — an unkeyed group has no `exec` and no `inputs`, so the
  * key-derivation steps below would all fall back to defaults.
  * `computeGroupKey` is exported for that purpose.
  */
 export async function computeTaskHash(args: ComputeHashArgs): Promise<string> {
+  if (isKeyless(args.node.config)) return keylessHash(args.node.id)
   const end = span('task hash')
   try {
     return await args.cache.key((await resolveKeyInput(args)).input)
@@ -98,6 +99,27 @@ export async function computeTaskHash(args: ComputeHashArgs): Promise<string> {
   }
 }
 
+/**
+ * A task that runs a command and declares no `inputs`: nothing says what
+ * it read, so no key can stand for its outputs, and a key that folds it
+ * would replay a stale entry (owner, 2026-10-16).
+ */
+export function isKeyless(task: TaskConfig): boolean {
+  return task.exec !== undefined && task.inputs === undefined
+}
+
+/**
+ * Drawn once per process, so no run derives another run's keyless keys;
+ * on first use, as the browser playground loads this module with no `crypto`.
+ */
+let keylessSalt: string | undefined
+
+/** A keyless task's key: this run's alone, so every key folding it misses. */
+function keylessHash(taskId: string): string {
+  keylessSalt ??= crypto.randomUUID()
+  return xxh3hex(`keyless\0${keylessSalt}\0${taskId}`)
+}
+
 /**
  * One file the key folded: the digest it folded, and since when (ms since
  * the epoch) that digest is known to be the file's content — the
@@ -250,14 +272,14 @@ async function resolveKeyInput(
   args: ComputeHashArgs,
 ): Promise<{ input: CacheKeyInput; listings: InputListing[] }> {
   const cfg = args.node.config
-  const cacheCfg: CacheConfig | undefined = cfg.cache
+  const cacheCfg = cfg.cache
   const outputs = cacheCfg?.outputs.files ?? []
 
   const resolved = await resolveInputs({
     projectDir: args.node.projectDir,
     workspaceRoot: args.workspaceRoot,
     envSource: process.env,
-    inputs: cacheCfg?.inputs,
+    inputs: cfg.inputs,
     ownOutputs: outputs,
     ownWorkspaceOutputs: cacheCfg?.outputs.workspaceFiles ?? [],
     nestedProjectDirs: args.nestedProjectDirs,
@@ -282,7 +304,7 @@ async function resolveKeyInput(
 
   const upstreamPairs = filterUpstreamHashes(
     args.upstream,
-    cacheCfg?.inputs?.tasks,
+    cfg.inputs?.tasks,
     args.node.projectName,
     args.node.id,
   )
@@ -290,7 +312,7 @@ async function resolveKeyInput(
   // hash → upstream task id, for capture-row naming only (not folded).
   const upstreamIds = new Map(upstreamPairs.map(([id, hash]) => [hash, id]))
   // The DEPENDENCY closure, groups expanded — for the executor's input root.
-  // Deliberately NOT the filtered set above: `cache.inputs.tasks` says which
+  // Deliberately NOT the filtered set above: `inputs.tasks` says which
   // upstream KEYS this task's key folds, and what a task may READ is
   // `dependsOn`. Locally every dependency's outputs are on disk before the
   // command runs however the filter is written, so an executor that ships the
@@ -306,7 +328,7 @@ async function resolveKeyInput(
   // also merge the workspace-wide partition's OIDs (keyed by abs
   // path, so the two maps agree wherever they overlap).
   let fileHashes = args.gitFilesCache?.oidsFor(args.node.projectDir)
-  if ((cacheCfg?.inputs.workspaceFiles?.length ?? 0) > 0) {
+  if ((cfg.inputs?.workspaceFiles?.length ?? 0) > 0) {
     const wsOids = args.gitFilesCache?.oidsFor(args.workspaceRoot)
     if (wsOids !== undefined && wsOids !== fileHashes) {
       fileHashes = fileHashes === undefined ? wsOids : new Map([...wsOids, ...fileHashes])
@@ -390,12 +412,12 @@ function hashableConfig(cfg: TaskConfig): unknown {
 }
 
 /**
- * A group's key: its upstream, and for a keyed group — one with `cache`,
+ * A group's key: its upstream, and for a keyed group — one with `inputs`,
  * the default `build` (projects.ts) or a config's — its own inputs too,
  * the way a task's key folds them.
  */
 export async function computeGroupKey(args: ComputeHashArgs): Promise<string> {
-  if (args.node.config.cache === undefined) return computeGroupHash(args.upstream)
+  if (args.node.config.inputs === undefined) return computeGroupHash(args.upstream)
   return computeTaskHash(args)
 }
 

package/src/orchestrator/telemetry-host.ts

@@ -27,8 +27,8 @@ import type { VxPlugin } from './plugin.js'
 export interface TelemetryHandle {
   /** Emit the per-run summary to every sink (crash-isolated). */
   emitSummary(summary: RunSummaryRecord): void
-  /** Await every sink's flush (crash-isolated, time-bounded by the sink). */
-  flush(): Promise<void>
+  /** Await every sink's flush (crash-isolated, time-bounded by the sink), each as a `<plugin>:telemetry` step. */
+  flush(step?: <T>(id: string, work: () => Promise<T>) => Promise<T>): Promise<void>
   /** Remove the bus subscription. Idempotent. */
   dispose(): void
   /** Sample a running task's process tree; see `TelemetrySource.track`. */
@@ -125,7 +125,7 @@ export async function subscribeTelemetry(
   const dispose = bus.subscribe(source.subscriber)
   return {
     emitSummary: (summary) => source.emitSummary(summary),
-    flush: () => source.flush(),
+    flush: (step) => source.flush(step),
     dispose,
     ...(source.track !== undefined ? { track: source.track } : {}),
   }

package/src/orchestrator/telemetry.ts

@@ -391,8 +391,11 @@ export interface TelemetrySource {
   readonly subscriber: RunEventSubscriber
   /** Fan the per-run summary to every sink's `onRunSummary` (crash-isolated). */
   emitSummary(summary: RunSummaryRecord): void
-  /** Await every sink's `flush()` (each crash-isolated, all time-bounded). */
-  flush(): Promise<void>
+  /**
+   * Await every sink's `flush()` (each crash-isolated, all time-bounded),
+   * each as the step `<plugin>:telemetry` through `step`.
+   */
+  flush(step?: <T>(id: string, work: () => Promise<T>) => Promise<T>): Promise<void>
   /**
    * Sample this task's process tree every `SAMPLE_MS` until the returned
    * function is called, the root exits, or the run ends. Present only when
@@ -625,7 +628,7 @@ export function createTelemetrySource(args: {
         }
       }
     },
-    async flush(): Promise<void> {
+    async flush(step = <T>(_id: string, work: () => Promise<T>): Promise<T> => work()) {
       const ms = teardownTimeoutMs()
       // Bounded, for the same reason plugin teardown is bounded in
       // plugin-host.ts: run() awaits this BEFORE closeCache() and before it
@@ -641,7 +644,9 @@ export function createTelemetrySource(args: {
           sinks.map(async (sink) => {
             if (disabled.has(sink) || sink.flush === undefined) return
             try {
-              await sink.flush(deadline.signal)
+              await step(`${args.owners?.get(sink) ?? label(sink)}:telemetry`, () =>
+                sink.flush!(deadline.signal),
+              )
             } catch (err) {
               // A flush failure can never break the run — but it still costs
               // this sink its export, so say so rather than dropping it.

package/src/orchestrator/upstream.ts

@@ -1,14 +1,9 @@
 import {
-  DependencySpecError,
-  compileTaskPattern,
-  isGroupTask,
-  isTaskPattern,
-  parseDependencySpec,
-  type DependencySpec,
+  selectFoldedDeps,
+  type FoldCandidate,
   type TaskNode,
   type TaskOutcome,
 } from '../graph/index.js'
-import { UserError } from '../util/index.js'
 
 /**
  * A task's upstream as its KEY reads it: the live outcomes of its scheduled
@@ -36,15 +31,9 @@ export function keyedOutcome(node: TaskNode, hash: string | undefined): TaskOutc
   return o
 }
 
-/** `node.deps` less its ordering-only edges: the dependencies a key may fold. */
-export function keyedDeps(node: TaskNode): readonly string[] {
-  const order = node.orderOnly
-  return order === undefined ? node.deps : node.deps.filter((d) => !order.includes(d))
-}
-
 /**
  * Pick which upstream task hashes participate in the current task's
- * cache key, filtered by `cache.inputs.tasks`. The folded value is the
+ * cache key, filtered by `inputs.tasks`. The folded value is the
  * upstream's own cache key (its input-based task hash) — pure-input
  * transitive hashing, like Turbo/Nx. An upstream change propagates
  * through its key into every dependent's key. There is deliberately NO
@@ -77,135 +66,6 @@ export function filterUpstreamHashes(
   ])
 }
 
-/**
- * A filter selects among the task's own dependencies, never through a
- * group: `dependsOn: ['build']` over a group `build` of `build.a` and
- * `build.b` offers the filter `build`, not its members. A pattern that
- * matches only a member (`build.*`) therefore selected nothing, and the key stopped moving
- * with that member's inputs: a stale hit under a green run. Such a spec
- * is refused, once, over the graph every key site reads. One that matches
- * nothing anywhere stays legal (a preset's pattern needn't match in every
- * project). An exact name is refused earlier, at load, unless `dependsOn`
- * names it (`assertFilterNamesDeclaredDeps`).
- */
-export function refuseFiltersThroughGroups(nodes: ReadonlyMap<string, TaskNode>): void {
-  for (const node of nodes.values()) {
-    const filter = node.config.cache?.inputs?.tasks
-    if (filter === undefined || filter.length === 0) continue
-    const deps = keyedDeps(node).flatMap((id) => nodes.get(id) ?? [])
-    const groups = deps.filter(isGroupTask)
-    if (groups.length === 0) continue
-    for (const raw of filter) {
-      const spec = parseSpec(raw, node.id)
-      if (spec.negated) continue
-      const matches = specMatcher(spec)
-      const hit = (n: TaskNode): boolean => matches(n, n.projectName === node.projectName)
-      if (deps.some(hit)) continue
-      for (const group of groups) {
-        const member = groupMembers(group, nodes).find(hit)
-        if (member === undefined) continue
-        throw new UserError(
-          `${node.id}: cache.inputs.tasks: '${raw}' matches ${member.id} only through the group ${group.id}, so it selects nothing; name '${group.taskName}' or depend on ${member.id} directly`,
-        )
-      }
-    }
-  }
-}
-
-function parseSpec(raw: string, selfTaskId: string): DependencySpec {
-  try {
-    return parseDependencySpec(raw)
-  } catch (err) {
-    if (err instanceof DependencySpecError) {
-      throw new UserError(`${selfTaskId}: cache.inputs.tasks: ${err.message}`)
-    }
-    throw err
-  }
-}
-
-/** Every task a group stands for, through nested groups, each once. */
-function groupMembers(group: TaskNode, nodes: ReadonlyMap<string, TaskNode>): TaskNode[] {
-  const out: TaskNode[] = []
-  const seen = new Set<string>([group.id])
-  const stack = group.deps.toReversed()
-  while (stack.length > 0) {
-    const id = stack.pop()!
-    if (seen.has(id)) continue
-    seen.add(id)
-    const n = nodes.get(id)
-    if (n === undefined) continue
-    out.push(n)
-    if (isGroupTask(n)) stack.push(...n.deps.toReversed())
-  }
-  return out
-}
-
-/**
- * One dependency as the key fold sees it: the task, and the value the
- * fold dedups by — its hash on the hash path, a structural stand-in for
- * the hash on the graph (`foldUnit` in keyed-projects.ts).
- */
-export interface FoldCandidate {
-  node: TaskNode
-  unit: string
-}
-
-/**
- * The dependencies a task's key folds, per its `cache.inputs.tasks`.
- *
- * Patterns (Turbo/Nx micro-syntax + filter extensions):
- *   '*'         all same-project upstream
- *   '^*'        all dep-workspace upstream
- *   'name'      same-project task `name`
- *   '^name'     `name` task in every dep workspace
- *   'pkg#name'  specific package's `name` task
- *   'name.*'    patterns — EITHER half of any form above may contain `*`
- *               (same glob as dependsOn patterns), including the project
- *               half of `pkg#name`. A filter that matched literally here
- *               would silently select ZERO upstream hashes and decouple the
- *               task from its dependencies — a stale-hit trap, so every
- *               name is matched through the shared glob.
- *   '!<form>'   exclude — any of the above with a leading `!`
- *
- * Patterns are applied in order; last write wins, so
- * `['*', '^*', '!^noisy']` reads as "all minus deps' noisy".
- *
- * Defaults:
- *   - `filter === undefined` → every candidate, as given.
- *   - `filter === []`        → none (fully decoupled).
- *
- * Otherwise deduped by `unit`, first candidate kept. The unit is the
- * fold's own identity, not the task's: two groups over the same members
- * share one hash, so excluding either excludes both, and a selection by
- * task id would keep the other while the key folded neither.
- */
-export function selectFoldedDeps(
-  deps: readonly FoldCandidate[],
-  filter: readonly string[] | undefined,
-  selfProjectName: string,
-  selfTaskId: string,
-): FoldCandidate[] {
-  if (filter === undefined) return [...deps]
-
-  const specs: DependencySpec[] = filter.map((raw) => parseSpec(raw, selfTaskId))
-
-  // Per-spec predicate, compiled once (exact compares + patterns).
-  const matchers = specs.map((spec) => specMatcher(spec))
-
-  const selected = new Map<string, FoldCandidate>()
-  for (let i = 0; i < specs.length; i++) {
-    const spec = specs[i]!
-    const matches = matchers[i]!
-    for (const d of deps) {
-      const isSelf = d.node.projectName === selfProjectName
-      if (!matches(d.node, isSelf)) continue
-      if (spec.negated) selected.delete(d.unit)
-      else if (!selected.has(d.unit)) selected.set(d.unit, d)
-    }
-  }
-  return [...selected.values()]
-}
-
 /**
  * Expand any GROUP among these outcomes into the real tasks it stands for,
  * transitively, preserving order and de-duplicating by task id.
@@ -223,7 +83,7 @@ export function selectFoldedDeps(
  * along two paths (a group `build` whose `^build` meets a package diamond)
  * is expanded once, or the walk doubles per layer. Only what the FILTER
  * already selected is passed in, so a group excluded from a task's
- * `cache.inputs.tasks` brings no members with it.
+ * `inputs.tasks` brings no members with it.
  */
 export function expandGroupUpstream(upstream: readonly TaskOutcome[]): TaskOutcome[] {
   const out: TaskOutcome[] = []
@@ -245,40 +105,3 @@ export function expandGroupUpstream(upstream: readonly TaskOutcome[]): TaskOutco
   }
   return out
 }
-
-/** Exact-name compare, or the shared `*`-glob when the name is a pattern. */
-function nameMatcher(name: string): (candidate: string) => boolean {
-  if (isTaskPattern(name)) {
-    const re = compileTaskPattern(name)
-    return (candidate) => re.test(candidate)
-  }
-  return (candidate) => candidate === name
-}
-
-/**
- * Compile one spec into an upstream predicate. BOTH halves of a `pkg#task`
- * form glob: a filter only ever selects from upstreams that already exist,
- * so a package pattern is unambiguous here — unlike dependsOn, which must
- * materialize concrete edges and therefore rejects it.
- */
-function specMatcher(spec: DependencySpec): (n: TaskNode, isSelf: boolean) => boolean {
-  switch (spec.kind) {
-    case 'wildcardSelf':
-      return (_n, isSelf) => isSelf
-    case 'wildcardDeps':
-      return (_n, isSelf) => !isSelf
-    case 'self': {
-      const task = nameMatcher(spec.task)
-      return (n, isSelf) => isSelf && task(n.taskName)
-    }
-    case 'deps': {
-      const task = nameMatcher(spec.task)
-      return (n, isSelf) => !isSelf && task(n.taskName)
-    }
-    case 'cross': {
-      const project = nameMatcher(spec.project)
-      const task = nameMatcher(spec.task)
-      return (n) => project(n.projectName) && task(n.taskName)
-    }
-  }
-}

package/src/report/framed-output.ts

@@ -532,7 +532,7 @@ function violationSection(outcome: TaskOutcome, colors: ColorSupport): string[]
           ...(fix.inputs !== undefined
             ? [
                 dim(
-                  `and, if the output depends on them, cache.inputs.files: [${fix.inputs.map((p) => `'${p}'`).join(', ')}]`,
+                  `and, if the output depends on them, inputs.files: [${fix.inputs.map((p) => `'${p}'`).join(', ')}]`,
                 ),
               ]
             : []),

package/src/report/logger.ts

@@ -973,8 +973,11 @@ export function defaultLogger(
           const qi = slotQueue.findIndex((s) => s.id === node.id)
           if (qi >= 0) slotQueue.splice(qi, 1)
         }
-        const bucket = outcome.hash === undefined ? undefined : cacheBucketOf(outcome)
-        if (bucket !== undefined) buckets.set(outcome.hash!, bucket)
+        const bucket = cacheBucketOf(outcome)
+        if (bucket !== undefined) {
+          if (outcome.hash !== undefined) buckets.set(outcome.hash, bucket)
+          buckets.set(node.id, bucket)
+        }
         switch (outcome.status) {
           case 'success':
             succeeded++

package/src/report/status-line.ts

@@ -361,9 +361,13 @@ export function formatFailureLine(
   )
 }
 
+/** A step's cache column, dim as `no-cache` is. */
+const INTERNAL = 'internal'
+
 /**
  * The list row of one of vx's own steps (`vx:uploads`), on the task grid
- * with no cache column: a step is no task and caches nothing.
+ * with `internal` in the cache column: a step is no task and caches
+ * nothing (M, 2026-10-16: `4.60s success internal vx:keep-run`).
  */
 export function formatStepLine(
   id: string,
@@ -376,7 +380,7 @@ export function formatStepLine(
     durationMs,
     ok ? 'success' : 'failed',
     ok ? SUCCESS : ERROR,
-    '',
+    INTERNAL,
     '',
     paintPinnedId(id, colors),
     colors,
@@ -464,7 +468,7 @@ export function formatStatusRegion(
         Math.max(0, s.nowMs - step.startedMs),
         'running',
         ACCENT,
-        '',
+        INTERNAL,
         '',
         paintPinnedId(step.id, colors),
         colors,

package/src/report/summary.ts

@@ -110,7 +110,7 @@ export interface SummaryStats {
   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, so its remote traffic can move it. */
+  /** Each finished task's cache bucket by its key and its id (its run bytes), so its remote traffic can move it. */
   buckets?: ReadonlyMap<string, CacheBucket>
 }
 
@@ -536,12 +536,14 @@ export function formatRunSummary(
   )
 }
 
-/** Each finished task's cache bucket by its key. */
+/** Each finished task's cache bucket by its key and by its id. */
 function bucketsOf(outcomes: readonly TaskOutcome[]): Map<string, CacheBucket> {
   const out = new Map<string, CacheBucket>()
   for (const o of outcomes) {
-    const bucket = o.hash === undefined ? undefined : cacheBucketOf(o)
-    if (bucket !== undefined) out.set(o.hash!, bucket)
+    const bucket = cacheBucketOf(o)
+    if (bucket === undefined) continue
+    if (o.hash !== undefined) out.set(o.hash, bucket)
+    out.set(o.node.id, bucket)
   }
   return out
 }

package/src/settings.ts

@@ -108,12 +108,6 @@ export const SETTINGS: readonly Setting[] = [
     default: 'true',
     doc: 'Refuse two tasks whose outputs overlap even when an edge orders them.',
   },
-  {
-    path: 'run.rules.upfrontKeys',
-    kind: { type: 'bool' },
-    default: 'true',
-    doc: "Refuse a task whose inputs can match another task's outputs.",
-  },
   {
     path: 'cache.dir',
     kind: { type: 'string' },
@@ -176,6 +170,13 @@ export const SETTINGS: readonly Setting[] = [
     task: 'cache.outputs.clean',
     env: false,
   },
+  {
+    path: 'cache.upload.failures',
+    kind: { type: 'enum', values: ['ci', 'local', 'always'] },
+    default: 'ci',
+    doc: "Where a failed task's log and outputs are kept in the remote: CI runs, local runs, or both.",
+    env: false,
+  },
   {
     path: 'lock.reviewFiles',
     kind: { type: 'bool' },
@@ -393,15 +394,8 @@ export function resolveSetting(
   return { value: undefined, source: 'default' }
 }
 
-/** `run.rules`, each from its variable, else the workspace; unset ones stay on. */
-export function runRules(workspace: unknown): {
-  exclusiveOutputs?: boolean
-  upfrontKeys?: boolean
-} {
-  const out: { exclusiveOutputs?: boolean; upfrontKeys?: boolean } = {}
-  for (const rule of ['exclusiveOutputs', 'upfrontKeys'] as const) {
-    const { value } = resolveSetting(`run.rules.${rule}`, workspace)
-    if (value !== undefined) out[rule] = value as boolean
-  }
-  return out
+/** `run.rules`, from its variable, else the workspace; unset stays on. */
+export function runRules(workspace: unknown): { exclusiveOutputs?: boolean } {
+  const { value } = resolveSetting('run.rules.exclusiveOutputs', workspace)
+  return value === undefined ? {} : { exclusiveOutputs: value as boolean }
 }

package/src/util/index.ts

@@ -58,7 +58,10 @@ export {
   GLOB_WILDCARDS,
   normalizeBunGlob,
   normalizeGlob,
+  namesNodeModules,
+  OUTPUT_NEVER,
   outputMatcher,
+  restorableOutput,
   printable,
   relPosix,
   DOT_VX_GITATTRIBUTES,

package/src/util/paths.ts

@@ -12,11 +12,12 @@ export function toPosix(p: string): string {
 }
 
 /**
- * `.vx/.gitignore`: git ignores the machine-local `.vx/cache` and nothing
- * else in `.vx`, so the workspace config and the lock beside it are
- * committed. `vx init` and the cache write it when missing.
+ * `.vx/.gitignore`: git ignores the machine-local `.vx/cache`, `.vx/tmp`
+ * (where restores stage) and nothing else in `.vx`, so the workspace
+ * config and the lock beside it are committed. `vx init` and the cache
+ * write it when missing.
  */
-export const DOT_VX_GITIGNORE = '/cache\n'
+export const DOT_VX_GITIGNORE = '/cache\n/tmp\n'
 
 /** `.vx/.gitattributes`' text: GitHub collapses the machine lock in a diff. */
 export const DOT_VX_GITATTRIBUTES = 'projects.lock.json linguist-generated=true\n'
@@ -163,7 +164,7 @@ export function isLiteralPattern(glob: string): boolean {
 }
 
 /**
- * The alphabet of a TASK glob (`cache.inputs.files`, `cache.outputs.files`,
+ * The alphabet of a TASK glob (`inputs.files`, `cache.outputs.files`,
  * `workspaceFiles`), behind {@link isLiteralPattern}, for the callers that
  * need the POSITION of the first wildcard rather than a verdict. Every site
  * that asks "must this declaration be matched?" reads this one regex: item
@@ -385,6 +386,39 @@ export function outputMatcher(globs: readonly string[]): (rel: string) => boolea
   return (rel) => pos(rel) && !neg(rel)
 }
 
+/**
+ * What no output glob reaches. An output is otherwise taken as written —
+ * `node_modules/**` IS an install task's output — 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.
+ */
+export const OUTPUT_NEVER = ['**/.git/**', '**/.vx/**', '**/vx.lock.json']
+
+/** Whether a positive glob in `globs` names a `node_modules` directory. */
+export function namesNodeModules(globs: readonly string[]): boolean {
+  return globs.some(
+    (g) => !g.startsWith('!') && normalizeGlob(g).split('/').includes('node_modules'),
+  )
+}
+
+/**
+ * Whether a restore may write `rel`: one of the outputs `globs` declare,
+ * never under `OUTPUT_NEVER`, and under `node_modules` only where a glob
+ * names it — what the save side could have packed (`resolveOutputs`). An
+ * artifact naming anything else was not written by this task's save, and
+ * none of it is restored (2026-10-16).
+ */
+export function restorableOutput(globs: readonly string[]): (rel: string) => boolean {
+  const isOutput = outputMatcher(globs)
+  const never = anyTaskGlob(
+    namesNodeModules(globs) ? OUTPUT_NEVER : [...OUTPUT_NEVER, '**/node_modules/**'],
+  )
+  return (rel) => isOutput(rel) && !never(rel)
+}
+
 /**
  * `pattern` with its first brace group expanded, recursively, while that
  * group holds a `/`; any other pattern as itself, since `Bun.Glob`