@vzn/vx 0.0.21 → 0.0.23

package/README.md

@@ -67,7 +67,7 @@ export default defineProject({
 vx init                   # scaffold vx.workspace.ts + a vx.config.ts per package from scripts
 vx run build              # cwd project + its workspace deps
 vx run test --all         # every project that declares `test`
-vx run ci --affected      # only what changed since origin/HEAD
+vx run ci --affected      # changed since origin/HEAD, and what depends on it
 vx watch lint             # re-run on file changes
 vx run build --dry        # show the plan, don't execute
 ```
@@ -136,9 +136,11 @@ vx lock --check && vx run ci --frozen     # CI: audit, then run EXACTLY that gra
 | `vx lock --check` | full graph        | compares — catches env and import drift that byte hashes cannot |
 
 Env values read at lock time are frozen by design — cache keys become
-reproducible across machines. Bonus: `--frozen` runs skip config
-evaluation entirely (~120 ms back per 1,000 packages). No other
-runner has an equivalent.
+reproducible across machines. Take it for that, not for speed: measured
+on the 1,000-project bench, a plain warm run and a frozen one are a tie
+(177 ms against 165, 2026-09-12), because the config-evaluation cache
+already serves a pure config without evaluating it. No other runner has
+an equivalent.
 
 ## Everything you need, nothing to configure twice
 
@@ -201,17 +203,17 @@ distributed ships in this repo; the seams are how you build it.
 
 ## How it compares
 
-|                           | vx                                                         | Turborepo                      | Nx               |
-| ------------------------- | ---------------------------------------------------------- | ------------------------------ | ---------------- |
-| Fully cached, 100 pkgs¹   | **144 ms**                                                 | 279 ms                         | 583+ ms          |
-| Config                    | TypeScript, evaluated into the cache key                   | JSON (static)                  | JSON (static)    |
-| Output ownership          | **Strict** — wiped before exec AND restore                 | Additive (stale files survive) | Additive         |
-| Clean-tree hashing        | **Zero reads** (git index OIDs)                            | git OIDs                       | re-hash / daemon |
-| Daemon required for speed | **No**                                                     | Optional                       | Yes              |
-| Per-task sandbox          | **Yes** — kernel-level, opt-in                             | No                             | No               |
-| Plugin API                | **Yes** — executor / cache / telemetry seams               | No                             | Yes (TS-tied)    |
-| OTel CI/CD spans          | **Yes** — `otel()` plugin, zero OTel-SDK deps              | No                             | Paid             |
-| Install                   | **Single binary** — npm or 1 curl line, no Node/Bun needed | npm + Node                     | npm + Node       |
+|                           | vx                                                               | Turborepo                      | Nx               |
+| ------------------------- | ---------------------------------------------------------------- | ------------------------------ | ---------------- |
+| Fully cached, 100 pkgs¹   | **144 ms**                                                       | 279 ms                         | 583+ ms          |
+| Config                    | TypeScript, evaluated into the cache key                         | JSON (static)                  | JSON (static)    |
+| Output ownership          | **Strict** — wiped before exec AND restore                       | Additive (stale files survive) | Additive         |
+| Clean-tree hashing        | **Zero reads** (git index OIDs)                                  | git OIDs                       | re-hash / daemon |
+| Daemon required for speed | **No**                                                           | Optional                       | Yes              |
+| Per-task sandbox          | **Yes** — kernel-level, opt-in                                   | No                             | No               |
+| Plugin API                | **Yes** — executor / cache / telemetry seams                     | No                             | Yes (TS-tied)    |
+| OTel CI/CD spans          | **Yes** — `otel()` plugin, zero OTel-SDK deps                    | No                             | Paid             |
+| Install                   | **Single binary** — npm, or one release file; no Node/Bun needed | npm + Node                     | npm + Node       |
 
 ¹ Wall-clock, direct binaries, same machine and workspace — full
 methodology and more scenarios in
@@ -306,7 +308,8 @@ maintainers' handoff is [`packages/vx/docs/STATUS.md`](packages/vx/docs/STATUS.m
 ## Status
 
 **Pre-alpha.** The schema is settling; we bump `CACHE_VERSION` rather
-than maintain back-compat. **~2,500 core tests plus the package suites; CI green on every commit**;
+than maintain back-compat. What 1.0 will promise is in
+[`versioning-1.0.md`](packages/vx/docs/design/versioning-1.0.md). **~3,000 core tests plus the package suites; CI green on every commit**;
 the project dogfoods itself (`vx run ci`). Published on npm:
 [`@vzn/vx`](https://www.npmjs.com/package/@vzn/vx) (a prebuilt standalone
 binary).
@@ -318,8 +321,8 @@ build.
 
 | Surface                                            | Maturity             | Notes                                                                                                                                                             |
 | -------------------------------------------------- | -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Core task runner + caching                         | **production-ready** | dogfooded continuously; ~2,500 core tests + the package suites, green                                                                                             |
-| Plugin pipeline (9 hooks, `commands` included)     | **shippable**        | crash-isolated, re-validated; the local executor + cache are the floor under every plugin                                                                         |
+| Core task runner + caching                         | **production-ready** | dogfooded continuously; ~3,000 core tests + the package suites, green                                                                                             |
+| Plugin pipeline (13 hooks, `commands` included)    | **shippable**        | crash-isolated, re-validated; the local executor + cache are the floor under every plugin                                                                         |
 | `vx init` / `@vzn/vx-migrate` (scripts; Turbo, Nx) | **shippable**        | one config per package, TODOs where a source cannot say                                                                                                           |
 | REAPI remote cache + execution (`@vzn/vx-reapi`)   | **shippable**        | Bazel AC + CAS + Execute; NativeLink / BuildBuddy / Buildbarn / bazel-remote                                                                                      |
 | OTel export (`@vzn/vx-otel`)                       | **shippable**        | OTLP traces + metrics + logs, zero SDK deps                                                                                                                       |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vzn/vx",
-  "version": "0.0.21",
+  "version": "0.0.23",
   "description": "An open, extensible monorepo task runner.",
   "type": "module",
   "exports": {
@@ -17,13 +17,13 @@
     "node": ">=18"
   },
   "optionalDependencies": {
-    "@vzn/vx-linux-x64": "0.0.21",
-    "@vzn/vx-linux-arm64": "0.0.21",
-    "@vzn/vx-darwin-x64": "0.0.21",
-    "@vzn/vx-darwin-arm64": "0.0.21"
+    "@vzn/vx-linux-x64": "0.0.23",
+    "@vzn/vx-linux-arm64": "0.0.23",
+    "@vzn/vx-darwin-x64": "0.0.23",
+    "@vzn/vx-darwin-arm64": "0.0.23"
   },
   "dependencies": {
-    "@anthropic-ai/sandbox-runtime": "^0.0.75"
+    "@anthropic-ai/sandbox-runtime": "^0.0.76"
   },
   "files": [
     "index.ts",

package/src/bin.ts

@@ -1,6 +1,6 @@
 #!/usr/bin/env bun
 import { registerCoreAlias, run } from './cli/index.js'
-import { isUserError } from './util/index.js'
+import { fsRefusalHint, isFsRefusal, isUserError } from './util/index.js'
 
 // Every `import … from '@vzn/vx'` this process evaluates — a plugin
 // package, a workspace or project config — resolves to THIS core, not to
@@ -10,9 +10,23 @@ registerCoreAlias(() => import('./index.js') as Promise<Record<string, unknown>>
 
 // Wrapped in an explicit async main so `bun build --compile` accepts
 // the file. The compile target doesn't allow top-level await.
+let settled = false
+
 async function main(): Promise<void> {
   try {
-    process.exit(await run(process.argv.slice(2)))
+    const code = await run(process.argv.slice(2))
+    // NOTHING calls `process.exit` here, and that is the fix rather than a
+    // simplification. Bun drops what a pipe has not yet taken when
+    // `process.exit` follows a large write: 300 KB written then exit
+    // delivered 64 KiB (128 KiB after a tick), and `vx history --format
+    // json` on a 300-project workspace was cut mid-string (2026-09-15).
+    // `stdout.end(cb)` fixed that on 1.4.2 — and on 1.3.11 the callback
+    // still fires early: 2 MiB written, 214 KB delivered (2026-09-20).
+    // Setting the code and letting the loop drain is the one form that
+    // does not depend on when a runtime decides a pipe is flushed; it
+    // costs a hang if a verb leaves a handle open, which the suite's
+    // several hundred spawns of this binary would show at once.
+    process.exitCode = code
   } catch (err) {
     // UserError (workspace not found, cycle, config invalid, ...) —
     // print the message only; the stack is noise the user can't act
@@ -24,12 +38,47 @@ async function main(): Promise<void> {
       // it produced `vx: vx why: …` (walkthrough, 2026-09-04).
       const m = err.message
       process.stderr.write(m.startsWith('vx ') ? `${m}\n` : `vx: ${m}\n`)
+    } else if (isFsRefusal(err)) {
+      // The file system's refusal names the path; the stack would name
+      // the verb's write, which the reader cannot act on either.
+      process.stderr.write(`vx: ${err.message} — ${fsRefusalHint(err)}\n`)
     } else {
       const message = err instanceof Error ? (err.stack ?? err.message) : String(err)
       process.stderr.write(`vx: ${message}\n`)
     }
-    process.exit(1)
+    // Same reason as the success path above: a large stderr is truncated by
+    // `process.exit` too, and an error message cut in half is the one a
+    // reader most needs whole.
+    process.exitCode = 1
   }
+  settled = true
+}
+
+// The loop drained while the verb was still pending: something it awaits
+// can never settle (a plugin hook whose promise is never resolved), and
+// with no exit code set Bun exits 0 — a run whose task failed reported
+// green, and its task had not even run (item 921). An exit that no
+// verdict reached is a failure, and says so.
+process.on('beforeExit', () => {
+  if (settled) return
+  settled = true
+  process.stderr.write(
+    'vx: the run stopped before it finished: something it awaited can never settle (a plugin hook?)\n',
+  )
+  process.exitCode = 1
+})
+
+// A reader that leaves is not the run's failure. `vx run build | head -1`
+// closes the pipe after one line; every later write gets EPIPE, which Bun
+// raises as an `error` event on the stream, and an `error` nobody listens
+// for is an uncaught exception: the run died with a stack after its task
+// had succeeded, exit 1, its lock directory left behind (2026-09-16). With
+// a listener the write returns false, the run finishes, saves, releases,
+// and exits with its own verdict; what was going to the reader goes
+// nowhere. Same for stderr (`2>&1 | head`). Here and not in the logger:
+// an embedder's streams are the embedder's.
+for (const stream of [process.stdout, process.stderr]) {
+  stream.on('error', () => {})
 }
 
 void main()

package/src/cache/archive.ts

@@ -38,7 +38,7 @@
 // otherwise silently loses the claim rather than acting on it.
 
 import { chmodSync, renameSync, statSync, utimesSync } from 'node:fs'
-import { mkdir, realpath, rmdir, stat, unlink, writeFile } from 'node:fs/promises'
+import { mkdir, readlink, realpath, rmdir, stat, unlink, writeFile } from 'node:fs/promises'
 import path from 'node:path'
 import { UserError } from '../util/index.js'
 import { TarFormatError, type TarInput, tarEntries, tarPack, tarSize } from './tar-stream.js'
@@ -47,7 +47,7 @@ import { TarFormatError, type TarInput, tarEntries, tarPack, tarSize } from './t
 const META_ENTRY = '.vx-meta.json'
 
 /** Archive entry name of the always-present stdout record. */
-export const STDOUT_ENTRY = 'stdout'
+const STDOUT_ENTRY = 'stdout'
 
 /**
  * Sidecar shape. `files` maps an entry name to `[mode, mtimeMs]` — a
@@ -59,6 +59,14 @@ interface MetaFile {
   /** Bumped only if the sidecar's own shape changes; the artifact
    *  container is versioned by CACHE_VERSION, which gates reads. */
   version: 1
+  /**
+   * The cache key the artifact was packed under (v35, item 943). Ingest
+   * refuses bytes whose key is not the one it asked for: nothing else ties
+   * an artifact to its key, so a remote layer that answered one key with
+   * another's bytes (a truncated or colliding mapping) replayed the other
+   * task's outputs under a green `cache-hit-remote`.
+   */
+  key?: string
   files: Record<string, [mode: number, mtimeMs: number]>
   /**
    * What the PRODUCING execution used (2026-09-12, additive: an artifact
@@ -102,6 +110,8 @@ export class ArchiveSecurityError extends Error {
 
 /** What `packArtifactStream` packs: stdout plus archive name → absolute source path. */
 export interface PackArgs {
+  /** The cache key, recorded in the sidecar (item 943); ingest refuses an artifact without it. */
+  key?: string
   stdout: string
   outputs: ReadonlyMap<string, string>
   /** The producing execution's usage, when the runner reported it. */
@@ -124,6 +134,7 @@ export interface ArtifactPlan {
  */
 export async function planArtifact(args: PackArgs): Promise<ArtifactPlan> {
   const meta: MetaFile = { version: 1, files: {} }
+  if (args.key !== undefined) meta.key = args.key
   const exec = usageOf(args.exec)
   if (exec !== undefined) meta.exec = exec
   const files = await Promise.all(
@@ -136,14 +147,14 @@ export async function planArtifact(args: PackArgs): Promise<ArtifactPlan> {
       const st = await stat(abs).catch((err: NodeJS.ErrnoException) => {
         if (err.code === 'ENOENT') {
           throw new UserError(
-            `output ${shown} is a dangling symlink: vx stores regular files only — emit a file, or exclude it from cache.outputs`,
+            `output ${shown} is a dangling symlink: vx stores regular files only — emit a file there, or narrow cache.outputs.files to the files the task produces (output globs take no '!')`,
           )
         }
         throw err
       })
       if (!st.isFile()) {
         throw new UserError(
-          `output ${shown} is not a regular file (a symlink to a directory?): vx stores regular files only — emit a file, or exclude it from cache.outputs`,
+          `output ${shown} is not a regular file (a symlink to a directory?): vx stores regular files only — emit a file there, or narrow cache.outputs.files to the files the task produces (output globs take no '!')`,
         )
       }
       meta.files[name] = [st.mode & 0o777, Math.floor(st.mtimeMs)]
@@ -224,12 +235,16 @@ function streamOf(gen: AsyncGenerator<Uint8Array>): ReadableStream<Uint8Array> {
  * name is unsafe — a partial reading of a poisoned artifact is the
  * outcome the traversal defense exists to prevent.
  */
-export async function scanArtifact(
-  tar: ReadableStream<Uint8Array>,
-): Promise<{ entries: ArchiveEntry[]; stdout: string | null; exec: ExecUsage | undefined }> {
+export async function scanArtifact(tar: ReadableStream<Uint8Array>): Promise<{
+  entries: ArchiveEntry[]
+  stdout: string | null
+  exec: ExecUsage | undefined
+  key: string | undefined
+}> {
   const seen: Array<{ name: string; size: number; mtimeMs: number }> = []
   let meta: MetaFile['files'] = {}
   let exec: ExecUsage | undefined
+  let key: string | undefined
   let stdout: string | null = null
   for await (const e of tarEntries(tar)) {
     if (e.type !== '0') continue
@@ -239,6 +254,7 @@ export async function scanArtifact(
       // The ingest side is the untrusted boundary: a foreign sidecar's
       // usage is taken only when it is a plain non-negative number.
       exec = usageOf(parsed.exec)
+      if (typeof parsed.key === 'string') key = parsed.key
       continue
     }
     assertSafeName(e.name)
@@ -255,6 +271,7 @@ export async function scanArtifact(
     }),
     stdout,
     exec,
+    key,
   }
 }
 
@@ -286,7 +303,10 @@ export async function extractArtifactStream(
   workspaceDest: string | undefined,
   verify?: (provided: ReadonlySet<string>) => void,
 ): Promise<Set<string>> {
-  await mkdir(destDir, { recursive: true })
+  // No `mkdir -p` of the destination here: `stage` creates each entry's
+  // directory chain, the destination included, and the cache restores
+  // into a project directory that exists. The eager one cost every
+  // restore a thread-pool round trip for an EEXIST and a stat (item 627).
   const x = new Extractor(destDir, workspaceDest)
   const provided = new Set<string>()
   const headerMtime = new Map<string, number>()
@@ -305,7 +325,12 @@ export async function extractArtifactStream(
       await x.assertContained(dest.base, target, e.name)
       provided.add(e.name)
       headerMtime.set(e.name, e.mtimeMs)
-      await x.stage(e.name, target, e.size <= SMALL_ENTRY ? await bytesOf(e.body) : e.body)
+      await x.stage(
+        e.name,
+        dest.base,
+        target,
+        e.size <= SMALL_ENTRY ? await bytesOf(e.body) : e.body,
+      )
     }
     verify?.(provided)
     await x.commit((name) => {
@@ -448,22 +473,21 @@ class Extractor {
     }
     const parentResolved = path.dirname(targetResolved)
     if (this.containedDirs.has(parentResolved)) return
-    await this.assertParentContained(base, targetResolved, name)
+    await this.assertParentContained(base, targetResolved)
     this.containedDirs.add(parentResolved)
   }
 
-  private async assertParentContained(
-    base: string,
-    targetResolved: string,
-    name: string,
-  ): Promise<void> {
+  private async assertParentContained(base: string, targetResolved: string): Promise<void> {
     const baseResolved = path.resolve(base)
-    const realBase = await this.realBaseOf(base)
     // Only ancestors strictly BELOW the base are candidates — those are the
     // ones a poisoned entry could follow out of the tree. The walk must never
     // climb past the base: when the base itself does not exist yet (the
     // workspace-outputs anchor is created lazily), its parent legitimately
     // resolves outside and comparing against it would reject every entry.
+    // The base's own real path is resolved only once an ancestor EXISTS to
+    // compare it with: after a clean pruned the output directories (the
+    // common restore) nothing below the base is there, and the memoised
+    // resolve was a round trip spent on a comparison never made (item 627).
     let probe = path.dirname(targetResolved)
     while (probe.startsWith(baseResolved + path.sep)) {
       const real = await realpath(probe).then(
@@ -471,10 +495,9 @@ class Extractor {
         () => null,
       )
       if (real !== null) {
+        const realBase = await this.realBaseOf(base)
         if (real !== realBase && !real.startsWith(realBase + path.sep)) {
-          throw new ArchiveSecurityError(
-            `archive entry escapes destDir via a symlinked parent: ${name}`,
-          )
+          throw await linkOutError(baseResolved, probe, realBase)
         }
         return
       }
@@ -484,6 +507,33 @@ class Extractor {
     // pre-existing symlink to follow — the chain will be created fresh.
   }
 
+  /**
+   * `mkdir -p` does not follow a DANGLING link: it fails EEXIST at the link,
+   * ENOENT below it, ELOOP in a cycle — and the containment walk passed it,
+   * finding nothing that resolves between it and the base. A live link that
+   * stays inside the base is written through, so a dangling one is too: the
+   * directory it names is created and the entry lands through the link,
+   * which stays the user's (never replaced, nx#37061). One that leads out of
+   * the base is the refusal a live link out gets. Only the failure pays for
+   * the walk; a clean tree never reaches it.
+   */
+  private async mkdirThroughLink(
+    base: string,
+    dir: string,
+    err: NodeJS.ErrnoException,
+  ): Promise<string | undefined> {
+    if (err.code !== 'EEXIST' && err.code !== 'ENOENT' && err.code !== 'ELOOP') throw err
+    const real = await resolveThrough(dir)
+    const realBase = await this.realBaseOf(base)
+    if (real !== realBase && !real.startsWith(realBase + path.sep)) {
+      throw await linkOutError(path.resolve(base), dir, realBase)
+    }
+    // What stands there without a link on the way (a file named like the
+    // directory) fails this mkdir as it failed the first: the caller names
+    // it as a stray.
+    return mkdir(real, { recursive: true })
+  }
+
   /**
    * Write the entry beside its target. A buffer is written without
    * waiting, bounded by `INFLIGHT_BYTES`; a chunk stream goes to a file
@@ -491,13 +541,18 @@ class Extractor {
    */
   async stage(
     name: string,
+    base: string,
     target: string,
     body: Uint8Array | AsyncIterable<Uint8Array>,
   ): Promise<void> {
     const dir = path.dirname(target)
     let created: string | undefined
     if (!this.ensuredDirs.has(dir)) {
-      created = await mkdir(dir, { recursive: true })
+      try {
+        created = await mkdir(dir, { recursive: true })
+      } catch (err) {
+        created = await this.mkdirThroughLink(base, dir, err as NodeJS.ErrnoException)
+      }
       this.ensuredDirs.add(dir)
     }
     // Write beside the target and RENAME into place. rename(2) replaces
@@ -517,7 +572,13 @@ class Extractor {
     //
     // A directory at the target makes the rename fail — the same
     // fail-closed outcome the plain write had.
-    const tmp = `${target}.vx-tmp-${process.pid.toString(36)}-${(tmpSeq++).toString(36)}`
+    // The temp is a sibling with its own short name, never `<target>.suffix`:
+    // a suffix pushed a legal name of 242–255 bytes past NAME_MAX, and the
+    // restore of a valid artifact failed with ENAMETOOLONG (item 666).
+    const tmp = path.join(
+      path.dirname(target),
+      `.vx-tmp-${process.pid.toString(36)}-${(tmpSeq++).toString(36)}`,
+    )
     this.staged.push({ name, tmp, target, created })
     if (body instanceof Uint8Array) {
       this.inflightBytes += body.byteLength
@@ -594,6 +655,9 @@ class Extractor {
       if (s.created === undefined) continue
       let dir = path.dirname(s.target)
       const top = path.resolve(s.created)
+      // Created at a dangling link's resolved target (`mkdirThroughLink`),
+      // so the chain is pruned from where the link leads.
+      if (!dir.startsWith(top)) dir = await realpath(dir).catch(() => dir)
       while (dir.startsWith(top)) {
         if (
           !(await rmdir(dir).then(
@@ -618,6 +682,65 @@ let tmpSeq = 0
 
 const WORKSPACE_PREFIX = 'workspace-outputs/'
 
+/**
+ * The on-disk half of containment failed: `probe`, a directory under
+ * `base`, resolves outside it, so a directory between them is a link out.
+ * That is the tree, not the artifact — an output directory made a link
+ * after the entry was saved (upstream survey, nx#37061) — so it is the
+ * user's to fix, and the refusal names the link and where it leads. The
+ * restore never writes through it and never replaces it: the link is the
+ * user's, and replacing it is the bug nx#37061 reports.
+ */
+async function linkOutError(base: string, probe: string, realBase: string): Promise<UserError> {
+  let dir = base
+  let real = realBase
+  for (const part of path.relative(base, probe).split(path.sep)) {
+    dir = path.join(dir, part)
+    real = await resolveThrough(dir)
+    if (real !== realBase && !real.startsWith(realBase + path.sep)) break
+  }
+  return new UserError(
+    `${dir} is a symbolic link to ${real}, outside ${base} — a cache restore never writes ` +
+      'through a link that leaves its directory. Remove the link and re-run (the restore ' +
+      'puts a real directory there), or stop declaring outputs under it.',
+  )
+}
+
+/**
+ * Where `p` leads, every link on the way followed, a dangling one included:
+ * `realpath` for the part that exists, and past the first missing name the
+ * rest as written — where `mkdir -p` would create it if it followed links.
+ * A cycle is the user's tree, not the artifact, so it is refused by name.
+ */
+async function resolveThrough(p: string): Promise<string> {
+  const pending = path.resolve(p).split(path.sep).filter(Boolean).reverse()
+  let at: string = path.sep
+  let hops = 0
+  while (pending.length > 0) {
+    const next = path.join(at, pending.pop()!)
+    const link = await readlink(next).catch((err: NodeJS.ErrnoException) => {
+      if (err.code === 'EINVAL') return null
+      if (err.code === 'ENOENT' || err.code === 'ENOTDIR') return undefined
+      throw err
+    })
+    if (link === undefined) return path.join(next, ...pending.reverse())
+    if (link === null) {
+      at = next
+      continue
+    }
+    // Linux's own bound on links followed in one lookup (MAXSYMLINKS).
+    if (++hops > 40) {
+      throw new UserError(
+        `${p} goes through a cycle of symbolic links (at ${next}) — a cache restore cannot ` +
+          'write through it. Remove the link and re-run.',
+      )
+    }
+    if (path.isAbsolute(link)) at = path.sep
+    pending.push(...link.split(path.sep).filter(Boolean).reverse())
+  }
+  return at
+}
+
 /**
  * Path-traversal defense, applied to every entry name at read time.
  * Mirrors Turbo's `restore.rs:check_path` normalization: an artifact is
@@ -651,8 +774,34 @@ function assertSafeName(name: string): void {
   if (name.includes('\0')) {
     throw new ArchiveSecurityError(`archive entry name contains a null byte (unsafe): ${name}`)
   }
+  // Only a pax `path` record can carry a name this long. Left to the file
+  // system it is a raw ENAMETOOLONG, which the restore reports as an
+  // internal error rather than a refused artifact. A UTF-16 unit is at most
+  // three UTF-8 bytes, so the common short name never pays for the count.
+  if (name.length * 3 >= PATH_MAX && Buffer.byteLength(name) >= PATH_MAX) {
+    throw new ArchiveSecurityError(
+      `archive entry name is ${Buffer.byteLength(name)} bytes, past PATH_MAX (${PATH_MAX}) (unsafe): ${name.slice(0, 64)}…`,
+    )
+  }
+  // The same raw ENAMETOOLONG for one component past NAME_MAX, the same on
+  // Linux and macOS. Same cheap bound: a name under 86 units cannot hold one.
+  if (name.length * 3 > NAME_MAX) {
+    for (const part of name.split('/')) {
+      if (part.length * 3 > NAME_MAX && Buffer.byteLength(part) > NAME_MAX) {
+        throw new ArchiveSecurityError(
+          `archive entry has a ${Buffer.byteLength(part)}-byte component, past NAME_MAX (${NAME_MAX}) (unsafe): ${part.slice(0, 64)}…`,
+        )
+      }
+    }
+  }
 }
 
+/** Bytes one path component may hold (limits.h), on Linux and macOS alike. */
+const NAME_MAX = 255
+
+/** Bytes a path may hold, its terminating NUL included (limits.h). */
+const PATH_MAX = process.platform === 'darwin' ? 1024 : 4096
+
 function hasParentSegment(p: string): boolean {
   if (p === '..' || p.startsWith('../') || p.endsWith('/..')) return true
   return p.includes('/../')