@vibe-agent-toolkit/utils 0.2.0-rc.7 → 0.2.0-rc.8

package/README.md

@@ -24,12 +24,12 @@ The last two columns are the ones that matter when choosing. **"Resolves with ze
 
 | Subpath | Contents | Node builtins reached | Third-party | Resolves with zero deps installed? |
 |---|---|---|---|---|
-| `./path` | `safePath`, `toForwardSlash`, `toNfc`, `isAbsolutePath`, `isAbsoluteAnyPlatform`, `hasParentTraversalSegment`, `toAbsolutePath`, `getRelativePath`, `issueLocation` | `path` only | — | **yes** |
+| `./path` | `safePath`, `toForwardSlash`, `toNfc`, `isAbsolutePath`, `isAbsoluteAnyPlatform`, `hasParentTraversalSegment`, `relativeEscapesRoot`, `isSingleFsSegment`, `toAbsolutePath`, `getRelativePath`, `issueLocation` | `path` only | — | **yes** |
 | `./text` | `decodeTextContent` — the one bytes-to-text seam: BOM-announced UTF-8/UTF-16LE/UTF-16BE/UTF-32LE/UTF-32BE, BOM stripped, UTF-8 assumed otherwise; reports the encoding, whether it was a BOM fact or an assumption, and how many U+FFFD the decode substituted | **none** | — | **yes** |
 | `./zod` | `ZodTypeNames`, `getZodTypeName`, `isZodType`, `unwrapZodType`, `isZodOptional`, `isZodNullable` | **none** | — | **yes** |
 | `./glob` | `isGlob`, static base extraction, magic remainder | `path` only | — | **yes** |
 | `./fs` | `normalizePath`, `normalizedTmpdir`, `mkdirSyncReal`, `resolveFromImportMeta`, `dynamicImportPath`, `copyDirectory`, `fillPathSpellings`, `pathSpellingFrom`, `DirectorySpellingIndex`, `spellingWalkRoot`, `fillRealpaths`, `realpathFrom`, `FsLookupCache`, `readTextContent`, `readTextContentSync` | `fs`, `fs/promises`, `os`, `path`, `url`, `util` | — | **yes** |
-| `./testing` | `getTestOutputDir`, `getTestOutputBase`, `setupAsyncTempDirSuite`, `setupSyncTempDirSuite`, `removeScratchDir`, `symlinkCapability`, `createSymlink`, `createSymlinkAsync` | `crypto`, `fs`, `fs/promises`, `os`, `path`, `url` | — | **yes** |
+| `./testing` | `getTestOutputDir`, `getTestOutputBase`, `setupAsyncTempDirSuite`, `setupSyncTempDirSuite`, `removeScratchDir`, `createTempDir`, `removeTempDir`, `tempDirTracker`, `CANNOT_DENY_READS`, `buildHostileTree`, `HOSTILE_NAMES`, `symlinkCapability`, `createSymlink`, `createSymlinkAsync` | `crypto`, `fs`, `fs/promises`, `os`, `path`, `url` | — | **yes** |
 | `./asset` | `resolveAssetReference` — paths and npm bare specifiers | `fs`, `module`, `os`, `path`, `url` | — | **yes** |
 | `./yaml` | `updateYamlIn`, `verifyConfinedYamlEdit` — byte-surgical YAML edits | **none** | `yaml` | no — needs `yaml` |
 | `./process` | `safeExecSync`, `safeExecResult`, `safeExecFromString`, `isToolAvailable`, `getToolVersion`, `hasShellSyntax`, `CommandExecutionError`, `spawnHardened`, `shouldUseShell`, `windowsShellQuote`, `buildWindowsShellLine`, `resolveShellCommandToken`, `isPathLike`, `makeStdioBlocking`, `describeStdioBlocking` | `child_process`, `path` | `@vibe-validate/git`, `which` | no — needs both |
@@ -134,6 +134,8 @@ These always return forward slashes on every platform, so they are safe for comp
 - `getRelativePath()` - relative path between two absolute paths
 - `isAbsolutePath()` / `isAbsoluteAnyPlatform()` - absolute-path predicates
 - `hasParentTraversalSegment()` - detect `..` segments before using a caller-supplied path
+- `relativeEscapesRoot()` - classify a root-relative path (`safePath.relative(root, p)`) as escaping the root: `..`, `../x`, or an absolute answer (Windows cross-drive). Lexical, for identities and reports; a sink asks `isUnderRoot()` instead
+- `isSingleFsSegment()` - true when a caller-supplied NAME can only ever be one entry directly under whatever it is joined to (no separators, not `.`/`..`, no NUL, no drive spelling). `..cache` passes; `../victim` does not
 - `issueLocation()` - format a `file:line`-style location relative to a project root
 
 ⚠️ **`toNfc()` produces a comparison key, never a path to open.** The same visible filename has two
@@ -158,7 +160,11 @@ These return **OS-native** separators, because they resolve real filesystem iden
 - `mkdirSyncReal()` - create a directory and return its real path
 - `resolveFromImportMeta()` - resolve paths relative to an `import.meta.url`
 - `dynamicImportPath()` - `import()` an absolute path (works on Windows, which rejects bare absolute paths)
-- `copyDirectory()`
+- `copyDirectory()` - recursive copy that follows a symlinked directory into the tree it points at — contained: a link whose target is outside the source throws `CopyLinkEscapesSourceError`, and a link back into the tree throws `DirectoryWalkRevisitedError`
+- `isUnderRoot(root, candidate)` - the containment verdict a delete/copy/uninstall sink asks, answered by the filesystem: `'inside'` (a strict descendant, realpath-judged), `'outside'` (including the root itself and any symlink that leaves it), or `'absent'` (nothing there yet, and creating it would land inside). Both sides are canonicalized from their deepest existing ancestor, so a root reached through a symlink still contains its members; a refused path throws rather than reading as absent
+- `direntKind(entry)` - what a `Dirent` itself is: `'file' | 'directory' | 'symlink' | 'other'` — the link question asked first, for walks that must not follow (a delete, a size count)
+- `direntKindFollowing(dir, entry)` / `direntKindFollowingSync()` - what a `Dirent` resolves to, one `stat` for a link: `'file' | 'directory' | 'dangling' | 'other'` — for walks over a trusted tree where a link is how the entry got there. Both exist because `isFile()` and `isDirectory()` are BOTH false for a symlink, so a walk that tests only those drops every link silently (`local/dirent-type-needs-symlink-check` refuses that shape)
+- `FollowedWalk` - the cycle guard every following walk holds: `enter(dir)` on the root and each directory recursed into; a directory reached again under a second spelling (a link back into the tree) throws `DirectoryWalkRevisitedError` instead of recursing until the path length runs out
 - `fillPathSpellings(requests, fsCache)` - pass 1 of the case-exact existence check: walk each
   `{ referrer, target }` from the deepest directory the two share, listing every directory on the way
   down exactly once. The only I/O in the pair
@@ -199,6 +205,10 @@ These return **OS-native** separators, because they resolve real filesystem iden
 ### Test helpers — `@vibe-agent-toolkit/utils/testing`
 
 - `setupAsyncTempDirSuite()` / `setupSyncTempDirSuite()` - per-suite temp directories with cleanup
+- `createTempDir()` / `createTempDirAsync()` / `removeTempDir()` / `tempDirTracker()` - the per-call temp-directory primitives; `removeTempDir` refuses, by name, anything not inside the host tmpdir as the filesystem sees it
+- `CANNOT_DENY_READS` / `PERMISSIONS_ENFORCED` - whether a `chmod 000` denies anything on this host (Windows and uid 0 read everything); route through `skip()` so the skip is visible
+- `NODE_EXECUTABLE` / `gitExecutable()` / `resolveExecutable(name)` / `executableCandidates(name, platform, pathext)` - absolute paths for the binaries a fixture spawns: the running node, and `git` found by walking `PATH` once for the first regular executable file (`PATHEXT` names on Windows) and cached. A fixture spawns these instead of a bare `'git'` or `'node'`, so no writable directory on `PATH` decides what runs.
+- `buildHostileTree(base)` / `hostileTreePerTest(prefix)` / `HOSTILE_NAMES` - the one hostile fixture every sink is tested against: a root with a member, a `..`-named member, a symlink pointing out, one pointing in, a dangling one, an alias link to the root, an unreadable directory, a 200-character name, plus a sibling `victim/secret.txt` outside the root; and the table of names (`../victim`, `..`, `.`, `''`, `/victim`, `C:\victim`, a NUL byte, …) a sink must refuse. Fields the host cannot build are `null`
 - `getTestOutputDir()` / `getTestOutputBase()` - isolated test output paths
 - `symlinkCapability()` - probes once (memoized per process) whether this host can create symlinks (Windows needs Developer Mode or `SeCreateSymbolicLinkPrivilege`), returning a `SymlinkCapability` token or `null`
 - `createSymlink()` / `createSymlinkAsync()` - the sanctioned way to create a symlink in test code; both require a `SymlinkCapability` from `symlinkCapability()`, so a test cannot reach the raw syscall without first proving the host supports it (or explicitly skipping via vitest's `skip()`)
@@ -215,6 +225,15 @@ These are CLI-boundary functions: inner libraries should take a root as a parame
 
 They are nonetheless on their own [`./project`](#import-narrowly) entry rather than the barrel alone. The entry was briefly withdrawn on the grounds that the functions fit few repos — which is true, and is what the paragraph above says — but that answered the wrong question. What decides whether an *entry* exists is how heavy the only remaining door is, and barrel-only these four once cost five third-party packages to reach while their own code imports nothing but `node:fs` and `node:path`. Publishing the entry is not a claim that the ladder fits you — only that finding out shouldn't cost a dependency graph. The barrel is dependency-free now, which is that same rule applied everywhere rather than a reason to fold `./project` back in.
 
+### Errors — `@vibe-agent-toolkit/utils` (barrel only)
+
+- `VatError` - the base of every error VAT throws on purpose: `new VatError(code, message, { cause })`. `code` is a stable `SCREAMING_SNAKE` identity a catch block dispatches on; `name` is taken from the subclass.
+- `isVatError(error, code?)` - the dispatch predicate. Reads a `Symbol.for('vat.error')` brand plus `code`, never the prototype chain, so a `dist` copy of a class still matches a `src` instance. A foreign error carrying a `code` (every `node:fs` errno) answers `false`.
+- `prefixMessageOnce(error, prefix)` - prefix a message in place, once per error object — for a seam a retried item passes through more than once, without re-reading the message to find out.
+- `PathEscapesRootError` (on `./path` too) - what `safePath.joinUnderRoot` throws; recognise it with `isVatError(error, PathEscapesRootError.code)`.
+
+Never dispatch on `error.message` — the repo's ESLint config refuses `.message.includes(…)` and friends under `packages/*/src`. Prose is for humans and changes when it is improved; a code changes only when the meaning does.
+
 ### Directory crawling — `@vibe-agent-toolkit/utils/crawl`
 
 - `crawlDirectory()` / `crawlDirectorySync()` - gitignore-aware directory walks

package/dist/asset-reference.js

@@ -74,8 +74,9 @@ function formatActionableError(specifier, baseDir, cause) {
     // but a build step in the target package didn't run (or produced different
     // output). Name the missing file explicitly and point at the publisher.
     if (code === 'MODULE_NOT_FOUND' && missingPath && missingPath !== specifier && isAbsolutePath(missingPath)) {
-        const fileExists = safeExistsSync(missingPath);
-        if (!fileExists) {
+        // `existsSync` answers false for every failure and never throws, so no
+        // guard around it: the question here is only whether the file is there.
+        if (!existsSync(missingPath)) {
             return (`Failed to resolve asset reference '${specifier}': ` +
                 `the package's "exports" map points to '${missingPath}', but that file does not exist on disk.\n` +
                 `Hint: the target package was found, but a build step did not produce this file. ` +
@@ -108,15 +109,6 @@ function extractMissingModulePath(cause) {
     const match = CANNOT_FIND_MODULE_RE.exec(cause.message);
     return match?.[1];
 }
-function safeExistsSync(filePath) {
-    try {
-        // eslint-disable-next-line security/detect-non-literal-fs-filename -- filePath is a Node-resolved exports target, used only to refine the error message
-        return existsSync(filePath);
-    }
-    catch {
-        return false;
-    }
-}
 function isBareSpecifier(value) {
     return BARE_SPECIFIER_RE.test(value);
 }

package/dist/asset-reference.js.map

@@ -1 +1 @@
-{"version":3,"file":"asset-reference.js","sourceRoot":"","sources":["../src/asset-reference.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"asset-reference.js","sourceRoot":"","sources":["../src/asset-reference.ts"],"names":[],"mappings":"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"}

package/dist/crawl-timing.d.ts

@@ -115,7 +115,7 @@
  *
  * ⚠️ A rollup that sums a stratum's rows without regard to pass double-counts
  * every nested bracket. That is a real reading hazard, not a hypothetical: it is
- * what `packages/lab/src/facets/crawl/dump.ts` did until 2026-08-15, and it
+ * what `packages/lab/src/facets/crawl/dump.ts` used to do, and it
  * inflated the two arms by DIFFERENT factors, because they nest to different
  * depths. That reader now implements the rule above — `crawlRowRole` there is
  * the executable copy of it — so anyone adding a bracket to this seam should
@@ -204,8 +204,8 @@
  * It carries the process's own wall and CPU lifetime, like the parse dump, and
  * for the same reason: these brackets are wall-timed, so a reader has to be able
  * to see that the process spent its life waiting. It does **not** invite that
- * figure to be summed across processes. `parse-timing.ts`'s review finding of
- * 2026-08-14 records that the lab sums `process.wallMs` across dumps, which
+ * figure to be summed across processes. `parse-timing.ts`'s review finding
+ * records that the lab sums `process.wallMs` across dumps, which
  * double-counts real time under a multi-process verb because the parent
  * orchestrator's lifetime contains every child's. The reader for THIS dump
  * publishes one lifetime per process and never a total — see

package/dist/crawl-timing.js

@@ -115,7 +115,7 @@
  *
  * ⚠️ A rollup that sums a stratum's rows without regard to pass double-counts
  * every nested bracket. That is a real reading hazard, not a hypothetical: it is
- * what `packages/lab/src/facets/crawl/dump.ts` did until 2026-08-15, and it
+ * what `packages/lab/src/facets/crawl/dump.ts` used to do, and it
  * inflated the two arms by DIFFERENT factors, because they nest to different
  * depths. That reader now implements the rule above — `crawlRowRole` there is
  * the executable copy of it — so anyone adding a bracket to this seam should
@@ -204,8 +204,8 @@
  * It carries the process's own wall and CPU lifetime, like the parse dump, and
  * for the same reason: these brackets are wall-timed, so a reader has to be able
  * to see that the process spent its life waiting. It does **not** invite that
- * figure to be summed across processes. `parse-timing.ts`'s review finding of
- * 2026-08-14 records that the lab sums `process.wallMs` across dumps, which
+ * figure to be summed across processes. `parse-timing.ts`'s review finding
+ * records that the lab sums `process.wallMs` across dumps, which
  * double-counts real time under a multi-process verb because the parent
  * orchestrator's lifetime contains every child's. The reader for THIS dump
  * publishes one lifetime per process and never a total — see

package/dist/dirent-kind.d.ts

@@ -0,0 +1,83 @@
+/**
+ * What a directory entry IS — with the symlink question asked first.
+ *
+ * A `Dirent` from `readdir(…, { withFileTypes: true })` describes the entry
+ * itself, so for a symlink BOTH `isFile()` and `isDirectory()` are false. A
+ * walk written `if (e.isDirectory()) recurse(); else if (e.isFile()) read();`
+ * therefore neither refuses a link nor follows it: it drops the entry on the
+ * floor without a word. The sweep found staged skill trees, size accounting
+ * and packaging walks with exactly that shape, every one reporting a tree
+ * with a symlink in it as clean. `local/dirent-type-needs-symlink-check`
+ * refuses that shape; these two helpers are what a walk says instead, and
+ * each makes the caller pick a policy by name.
+ *
+ * - {@link direntKind} — lstat semantics. A link is `'symlink'`, never what it
+ *   points at. For a walk that must NOT follow (a delete, a size count of
+ *   what `rm -rf` will remove, a bundle that travels as a tarball).
+ * - {@link direntKindFollowing} — stat semantics. A link is answered by its
+ *   target: `'file'`, `'directory'`, or `'dangling'`. For a walk over a tree
+ *   the caller trusts (its own build output, a dev-mode install, a fixture),
+ *   where a link is simply how the entry got there.
+ *
+ * Neither helper decides for the caller. A `'symlink'` or `'dangling'` that
+ * the caller ignores is still ignored — but it is ignored in a `case` the
+ * reader can see, which is the whole difference.
+ */
+import type { Dirent } from 'node:fs';
+import { VatError } from './errors/vat-error.js';
+/** What the entry itself is. A link is a link. */
+export type DirentKind = 'file' | 'directory' | 'symlink' | 'other';
+/** What the entry resolves to. A link is answered by its target, or is `dangling`. */
+export type FollowedKind = 'file' | 'directory' | 'dangling' | 'other';
+/**
+ * Classify an entry WITHOUT following it.
+ *
+ * @param entry - A `Dirent` from a `withFileTypes` listing
+ * @returns `'symlink'` for any link, else the entry's own type
+ */
+export declare function direntKind(entry: Dirent): DirentKind;
+/**
+ * Classify an entry by what it resolves to, following a link with one `stat`.
+ *
+ * A non-link entry costs no syscall. A link whose target is absent is
+ * `'dangling'`; a link the OS refuses to resolve (`ELOOP`, `EACCES`) is a
+ * refusal, not an absence, and stays loud.
+ *
+ * @param dir - The directory `entry` was listed from
+ * @param entry - A `Dirent` from a `withFileTypes` listing of `dir`
+ * @returns The target's kind, or `'dangling'`
+ */
+export declare function direntKindFollowingSync(dir: string, entry: Dirent): FollowedKind;
+/** The async counterpart of {@link direntKindFollowingSync}. */
+export declare function direntKindFollowing(dir: string, entry: Dirent): Promise<FollowedKind>;
+/** Thrown when a following walk is led back into a directory it has already entered. */
+export declare class DirectoryWalkRevisitedError extends VatError {
+    constructor(dir: string, enteredAs: string);
+}
+/**
+ * The directories a FOLLOWING walk has entered, by realpath, so a link that
+ * leads back into the walk is refused instead of recursed until
+ * `ENAMETOOLONG`.
+ *
+ * A walk that follows links (`direntKindFollowing`) has no cycle guard by
+ * construction: `scripts/loop -> .` makes a copy create `dest/loop/loop/…`,
+ * writing every file at every level first, and a hashing walk do the same in
+ * memory. Every following walk holds one of these and calls {@link enter}
+ * on every directory it recurses into — the root included. A REVISIT is
+ * refused, not just a cycle: two links to one directory make the walk's
+ * output ambiguous (which spelling is the file's path?), and a refusal that
+ * names both spellings is the answer the author can act on.
+ */
+export declare class FollowedWalk {
+    #private;
+    /**
+     * Record that the walk is entering `dir`. Synchronous on purpose — one
+     * realpath per directory entered is nothing beside the listing itself, and
+     * the sync and async walkers then share one guard.
+     *
+     * @param dir - A directory the walk is about to list, in any spelling
+     * @throws {DirectoryWalkRevisitedError} When its realpath was entered before
+     */
+    enter(dir: string): void;
+}
+//# sourceMappingURL=dirent-kind.d.ts.map

package/dist/dirent-kind.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dirent-kind.d.ts","sourceRoot":"","sources":["../src/dirent-kind.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,SAAS,CAAC;AAKtC,OAAO,EAAE,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AAIjD,kDAAkD;AAClD,MAAM,MAAM,UAAU,GAAG,MAAM,GAAG,WAAW,GAAG,SAAS,GAAG,OAAO,CAAC;AAEpE,sFAAsF;AACtF,MAAM,MAAM,YAAY,GAAG,MAAM,GAAG,WAAW,GAAG,UAAU,GAAG,OAAO,CAAC;AAEvE;;;;;GAKG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,UAAU,CAKpD;AASD;;;;;;;;;;GAUG;AACH,wBAAgB,uBAAuB,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,YAAY,CAQhF;AAED,gEAAgE;AAChE,wBAAsB,mBAAmB,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC,CAQ3F;AAED,wFAAwF;AACxF,qBAAa,2BAA4B,SAAQ,QAAQ;gBAC3C,GAAG,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM;CAM3C;AAED;;;;;;;;;;;;;GAaG;AACH,qBAAa,YAAY;;IAGvB;;;;;;;OAOG;IACH,KAAK,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI;CAMzB"}

package/dist/dirent-kind.js

@@ -0,0 +1,129 @@
+/**
+ * What a directory entry IS — with the symlink question asked first.
+ *
+ * A `Dirent` from `readdir(…, { withFileTypes: true })` describes the entry
+ * itself, so for a symlink BOTH `isFile()` and `isDirectory()` are false. A
+ * walk written `if (e.isDirectory()) recurse(); else if (e.isFile()) read();`
+ * therefore neither refuses a link nor follows it: it drops the entry on the
+ * floor without a word. The sweep found staged skill trees, size accounting
+ * and packaging walks with exactly that shape, every one reporting a tree
+ * with a symlink in it as clean. `local/dirent-type-needs-symlink-check`
+ * refuses that shape; these two helpers are what a walk says instead, and
+ * each makes the caller pick a policy by name.
+ *
+ * - {@link direntKind} — lstat semantics. A link is `'symlink'`, never what it
+ *   points at. For a walk that must NOT follow (a delete, a size count of
+ *   what `rm -rf` will remove, a bundle that travels as a tarball).
+ * - {@link direntKindFollowing} — stat semantics. A link is answered by its
+ *   target: `'file'`, `'directory'`, or `'dangling'`. For a walk over a tree
+ *   the caller trusts (its own build output, a dev-mode install, a fixture),
+ *   where a link is simply how the entry got there.
+ *
+ * Neither helper decides for the caller. A `'symlink'` or `'dangling'` that
+ * the caller ignores is still ignored — but it is ignored in a `case` the
+ * reader can see, which is the whole difference.
+ */
+import { statSync } from 'node:fs';
+import fs from 'node:fs/promises';
+import { isPathAbsentError } from './errors/errno.js';
+import { VatError } from './errors/vat-error.js';
+import { toForwardSlash } from './path-core.js';
+import { normalizePath, safePath } from './path-utils.js';
+/**
+ * Classify an entry WITHOUT following it.
+ *
+ * @param entry - A `Dirent` from a `withFileTypes` listing
+ * @returns `'symlink'` for any link, else the entry's own type
+ */
+export function direntKind(entry) {
+    if (entry.isSymbolicLink())
+        return 'symlink';
+    if (entry.isDirectory())
+        return 'directory';
+    if (entry.isFile())
+        return 'file';
+    return 'other';
+}
+/** The kind a `stat` result reports. */
+function kindOfStats(stats) {
+    if (stats.isDirectory())
+        return 'directory';
+    if (stats.isFile())
+        return 'file';
+    return 'other';
+}
+/**
+ * Classify an entry by what it resolves to, following a link with one `stat`.
+ *
+ * A non-link entry costs no syscall. A link whose target is absent is
+ * `'dangling'`; a link the OS refuses to resolve (`ELOOP`, `EACCES`) is a
+ * refusal, not an absence, and stays loud.
+ *
+ * @param dir - The directory `entry` was listed from
+ * @param entry - A `Dirent` from a `withFileTypes` listing of `dir`
+ * @returns The target's kind, or `'dangling'`
+ */
+export function direntKindFollowingSync(dir, entry) {
+    if (!entry.isSymbolicLink())
+        return kindOfStats(entry);
+    try {
+        return kindOfStats(statSync(safePath.join(dir, entry.name)));
+    }
+    catch (error) {
+        if (isPathAbsentError(error))
+            return 'dangling';
+        throw error;
+    }
+}
+/** The async counterpart of {@link direntKindFollowingSync}. */
+export async function direntKindFollowing(dir, entry) {
+    if (!entry.isSymbolicLink())
+        return kindOfStats(entry);
+    try {
+        return kindOfStats(await fs.stat(safePath.join(dir, entry.name)));
+    }
+    catch (error) {
+        if (isPathAbsentError(error))
+            return 'dangling';
+        throw error;
+    }
+}
+/** Thrown when a following walk is led back into a directory it has already entered. */
+export class DirectoryWalkRevisitedError extends VatError {
+    constructor(dir, enteredAs) {
+        super('DIRECTORY_WALK_REVISITED', `Refusing to enter ${dir}: it is the directory already walked as ${enteredAs} — a symlink leads the walk back into itself.`);
+    }
+}
+/**
+ * The directories a FOLLOWING walk has entered, by realpath, so a link that
+ * leads back into the walk is refused instead of recursed until
+ * `ENAMETOOLONG`.
+ *
+ * A walk that follows links (`direntKindFollowing`) has no cycle guard by
+ * construction: `scripts/loop -> .` makes a copy create `dest/loop/loop/…`,
+ * writing every file at every level first, and a hashing walk do the same in
+ * memory. Every following walk holds one of these and calls {@link enter}
+ * on every directory it recurses into — the root included. A REVISIT is
+ * refused, not just a cycle: two links to one directory make the walk's
+ * output ambiguous (which spelling is the file's path?), and a refusal that
+ * names both spellings is the answer the author can act on.
+ */
+export class FollowedWalk {
+    #entered = new Map();
+    /**
+     * Record that the walk is entering `dir`. Synchronous on purpose — one
+     * realpath per directory entered is nothing beside the listing itself, and
+     * the sync and async walkers then share one guard.
+     *
+     * @param dir - A directory the walk is about to list, in any spelling
+     * @throws {DirectoryWalkRevisitedError} When its realpath was entered before
+     */
+    enter(dir) {
+        const real = toForwardSlash(normalizePath(dir));
+        const before = this.#entered.get(real);
+        if (before !== undefined)
+            throw new DirectoryWalkRevisitedError(dir, before);
+        this.#entered.set(real, dir);
+    }
+}
+//# sourceMappingURL=dirent-kind.js.map

package/dist/dirent-kind.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"dirent-kind.js","sourceRoot":"","sources":["../src/dirent-kind.ts"],"names":[],"mappings":"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"}

package/dist/errors/errno.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Errno predicates — the two questions every catch site asks of an OS error,
+ * answered by the `code` on the error or down its `cause` chain.
+ *
+ * ⚠️ This module imports NOTHING. It is the leaf that `fs-utils.ts`,
+ * `path-utils.ts`, `dirent-kind.ts`, `path-containment.ts` and the rest of the
+ * package share; it lived in `fs-utils.ts` until that put three of them in an
+ * import cycle (`fs-utils → path-utils → fs-utils` and two more), and a leaf
+ * is the one place a shared predicate cannot re-open one. (The cycle was once
+ * blamed for a platform-dependent knip verdict on these two names; breaking it
+ * changed nothing there — the cause was a missing knip entry, see
+ * `docs/contributing/traps.md`, "A subpath module's re-exports flap by platform".)
+ */
+/**
+ * Whether `error` is the filesystem refusing a path rather than a bug.
+ *
+ * Deliberately NOT `error instanceof Error`: the point of every caller is to
+ * degrade on a hostile tree, and a `TypeError` from a validator is not that.
+ * Treating one as environmental turns a real defect into a warning about
+ * whichever file it happened on — which makes a tool quietest exactly when it is
+ * most wrong.
+ *
+ * Walks `cause`, because the errno is routinely re-wrapped on its way up. The CLI
+ * config loader turns a read failure into `new Error('Failed to load config: …')`;
+ * without following the chain the predicate answered "not a filesystem error" for
+ * a plain `EACCES`, and an unreadable config aborted a whole `vat audit` run. Any
+ * layer that adds context to an OS error defeats a `code`-only check, so the check
+ * cannot be `code`-only.
+ */
+export declare function isFilesystemAccessError(error: unknown): boolean;
+/**
+ * Whether `error` means **there is nothing at this path** — `ENOENT`, or
+ * `ENOTDIR` for a path whose component turned out to be a file — and nothing
+ * else.
+ *
+ * This is the narrowing a `try { stat(p) } catch { return null }` is rewritten
+ * to under the `no-blind-catch` lint rule: the sentinel stands for *absent*,
+ * so only an absence may produce it; a refusal (`EACCES`, `EPERM`, `ELOOP`) or
+ * a bug (`TypeError`) is rethrown and stays loud.
+ *
+ * ⚠️ Deliberately NOT {@link isFilesystemAccessError}. That predicate answers
+ * "is this the environment's fault?" and to answer it groups `ENOENT` with
+ * `EACCES` — the exact conflation that once turned an unreadable directory
+ * into an empty one. The two questions have two predicates on purpose; see
+ * also {@link listingFailure}, which makes the same split for `readdir`.
+ *
+ * Walks `cause` for the same reason its sibling does: the errno is routinely
+ * re-wrapped on its way up.
+ */
+export declare function isPathAbsentError(error: unknown): boolean;
+//# sourceMappingURL=errno.d.ts.map

package/dist/errors/errno.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errno.d.ts","sourceRoot":"","sources":["../../src/errors/errno.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAwCH;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAE/D;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAEzD"}

package/dist/errors/errno.js

@@ -0,0 +1,112 @@
+/**
+ * Errno predicates — the two questions every catch site asks of an OS error,
+ * answered by the `code` on the error or down its `cause` chain.
+ *
+ * ⚠️ This module imports NOTHING. It is the leaf that `fs-utils.ts`,
+ * `path-utils.ts`, `dirent-kind.ts`, `path-containment.ts` and the rest of the
+ * package share; it lived in `fs-utils.ts` until that put three of them in an
+ * import cycle (`fs-utils → path-utils → fs-utils` and two more), and a leaf
+ * is the one place a shared predicate cannot re-open one. (The cycle was once
+ * blamed for a platform-dependent knip verdict on these two names; breaking it
+ * changed nothing there — the cause was a missing knip entry, see
+ * `docs/contributing/traps.md`, "A subpath module's re-exports flap by platform".)
+ */
+/**
+ * Errno codes meaning "the filesystem refused this path", as opposed to a defect
+ * in our own code.
+ *
+ * Shared because two lanes need the same answer and must not drift: `vat audit`
+ * decides whether to degrade a scan over a tree it does not own, and the skill
+ * packager decides whether a `files:` match is copyable. A second, independently
+ * written list is how those two come to disagree about what counts as the
+ * environment's fault.
+ *
+ * The set is deliberately broad. An earlier, "conservative" version omitted
+ * `ENOTSUP` — the errno of the very issue this was written for — along with
+ * `EEXIST`, which an ordinary two-entry `files:` config reaches with no
+ * permissions involved at all. Both escaped raw. Every code here means the OS
+ * refused a syscall on a path; none of them can be produced by a type error or a
+ * logic bug in our own code, which is the only distinction the callers need.
+ *
+ * `EIO` and `EBUSY` are included even though they can indicate failing hardware:
+ * neither caller *swallows* anything, each reports the path and the OS message,
+ * so a dying disk surfaces once per affected path. Aborting the run instead would
+ * report less. `ENOENT` is included because a bulk scan races real filesystems —
+ * an entry listed by `readdir` can be gone by the time it is opened.
+ */
+const FILESYSTEM_ACCESS_ERRNOS = new Set([
+    // Permission and ownership
+    'EACCES', 'EPERM', 'EROFS',
+    // Presence and shape
+    'ENOENT', 'EEXIST', 'ENOTDIR', 'EISDIR', 'ENOTEMPTY', 'ELOOP', 'ENAMETOOLONG',
+    // Capability of the object or filesystem
+    'ENOTSUP', 'EOPNOTSUPP', 'EXDEV', 'ETXTBSY', 'EINVAL',
+    // Resource exhaustion and transient device state
+    'ENOSPC', 'EDQUOT', 'EMFILE', 'ENFILE', 'EIO', 'EBUSY', 'EAGAIN',
+    // Network filesystems
+    'ESTALE', 'ETIMEDOUT', 'EHOSTDOWN', 'ENETDOWN',
+    // Windows surfaces this for reparse points and some network paths
+    'UNKNOWN',
+]);
+/**
+ * Whether `error` is the filesystem refusing a path rather than a bug.
+ *
+ * Deliberately NOT `error instanceof Error`: the point of every caller is to
+ * degrade on a hostile tree, and a `TypeError` from a validator is not that.
+ * Treating one as environmental turns a real defect into a warning about
+ * whichever file it happened on — which makes a tool quietest exactly when it is
+ * most wrong.
+ *
+ * Walks `cause`, because the errno is routinely re-wrapped on its way up. The CLI
+ * config loader turns a read failure into `new Error('Failed to load config: …')`;
+ * without following the chain the predicate answered "not a filesystem error" for
+ * a plain `EACCES`, and an unreadable config aborted a whole `vat audit` run. Any
+ * layer that adds context to an OS error defeats a `code`-only check, so the check
+ * cannot be `code`-only.
+ */
+export function isFilesystemAccessError(error) {
+    return hasErrnoCode(error, (code) => FILESYSTEM_ACCESS_ERRNOS.has(code));
+}
+/**
+ * Whether `error` means **there is nothing at this path** — `ENOENT`, or
+ * `ENOTDIR` for a path whose component turned out to be a file — and nothing
+ * else.
+ *
+ * This is the narrowing a `try { stat(p) } catch { return null }` is rewritten
+ * to under the `no-blind-catch` lint rule: the sentinel stands for *absent*,
+ * so only an absence may produce it; a refusal (`EACCES`, `EPERM`, `ELOOP`) or
+ * a bug (`TypeError`) is rethrown and stays loud.
+ *
+ * ⚠️ Deliberately NOT {@link isFilesystemAccessError}. That predicate answers
+ * "is this the environment's fault?" and to answer it groups `ENOENT` with
+ * `EACCES` — the exact conflation that once turned an unreadable directory
+ * into an empty one. The two questions have two predicates on purpose; see
+ * also {@link listingFailure}, which makes the same split for `readdir`.
+ *
+ * Walks `cause` for the same reason its sibling does: the errno is routinely
+ * re-wrapped on its way up.
+ */
+export function isPathAbsentError(error) {
+    return hasErrnoCode(error, (code) => code === 'ENOENT' || code === 'ENOTDIR');
+}
+/**
+ * Whether any string `code` on `error` or down its `cause` chain satisfies
+ * `accept`. Bounded: a malformed `cause` chain must not become an infinite
+ * loop inside an error path, which is the worst place to hang.
+ */
+function hasErrnoCode(error, accept) {
+    for (let current = error, depth = 0; depth < 10; depth++) {
+        if (typeof current !== 'object' || current === null)
+            return false;
+        if ('code' in current) {
+            const { code } = current;
+            if (typeof code === 'string' && accept(code))
+                return true;
+        }
+        if (!('cause' in current))
+            return false;
+        current = current.cause;
+    }
+    return false;
+}
+//# sourceMappingURL=errno.js.map

package/dist/errors/errno.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errno.js","sourceRoot":"","sources":["../../src/errors/errno.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,MAAM,wBAAwB,GAAwB,IAAI,GAAG,CAAC;IAC5D,2BAA2B;IAC3B,QAAQ,EAAE,OAAO,EAAE,OAAO;IAC1B,qBAAqB;IACrB,QAAQ,EAAE,QAAQ,EAAE,SAAS,EAAE,QAAQ,EAAE,WAAW,EAAE,OAAO,EAAE,cAAc;IAC7E,yCAAyC;IACzC,SAAS,EAAE,YAAY,EAAE,OAAO,EAAE,SAAS,EAAE,QAAQ;IACrD,iDAAiD;IACjD,QAAQ,EAAE,QAAQ,EAAE,QAAQ,EAAE,QAAQ,EAAE,KAAK,EAAE,OAAO,EAAE,QAAQ;IAChE,sBAAsB;IACtB,QAAQ,EAAE,WAAW,EAAE,WAAW,EAAE,UAAU;IAC9C,kEAAkE;IAClE,SAAS;CACV,CAAC,CAAC;AAEH;;;;;;;;;;;;;;;GAeG;AACH,MAAM,UAAU,uBAAuB,CAAC,KAAc;IACpD,OAAO,YAAY,CAAC,KAAK,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,wBAAwB,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC;AAC3E,CAAC;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,UAAU,iBAAiB,CAAC,KAAc;IAC9C,OAAO,YAAY,CAAC,KAAK,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,KAAK,QAAQ,IAAI,IAAI,KAAK,SAAS,CAAC,CAAC;AAChF,CAAC;AAED;;;;GAIG;AACH,SAAS,YAAY,CAAC,KAAc,EAAE,MAAiC;IACrE,KAAK,IAAI,OAAO,GAAY,KAAK,EAAE,KAAK,GAAG,CAAC,EAAE,KAAK,GAAG,EAAE,EAAE,KAAK,EAAE,EAAE,CAAC;QAClE,IAAI,OAAO,OAAO,KAAK,QAAQ,IAAI,OAAO,KAAK,IAAI;YAAE,OAAO,KAAK,CAAC;QAClE,IAAI,MAAM,IAAI,OAAO,EAAE,CAAC;YACtB,MAAM,EAAE,IAAI,EAAE,GAAG,OAA4B,CAAC;YAC9C,IAAI,OAAO,IAAI,KAAK,QAAQ,IAAI,MAAM,CAAC,IAAI,CAAC;gBAAE,OAAO,IAAI,CAAC;QAC5D,CAAC;QACD,IAAI,CAAC,CAAC,OAAO,IAAI,OAAO,CAAC;YAAE,OAAO,KAAK,CAAC;QACxC,OAAO,GAAI,OAA8B,CAAC,KAAK,CAAC;IAClD,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC"}

package/dist/errors/vat-error.d.ts

@@ -0,0 +1,60 @@
+/**
+ * The base class of every error VAT throws on purpose.
+ *
+ * `code` is the one field a catch block may dispatch on. A message is prose
+ * for a human and changes whenever the prose improves; a code is a contract
+ * and changes only when the meaning does. Three packages used to recognise a
+ * root-escape by `error.message.startsWith('safePath.joinUnderRoot:')`, which
+ * held exactly until someone reworded the sentence — the ESLint restriction
+ * on `.message.includes(…)` exists so nobody writes the fourth.
+ *
+ * The brand is a registry symbol rather than the class identity because the
+ * class identity is not stable across the one boundary VAT crosses every day:
+ * a `dist` copy of a class never `instanceof`-matches a `src` instance, and
+ * `packages/cli` imports the same modules from both during tests.
+ * `Symbol.for` is realm-global, so {@link isVatError} answers the same on both
+ * sides.
+ */
+declare const VAT_ERROR_BRAND: unique symbol;
+/** An error VAT threw on purpose, with a stable machine-readable `code`. */
+export declare class VatError extends Error {
+    /** Stable identity for dispatch — `SCREAMING_SNAKE`, never read from prose. */
+    readonly code: string;
+    readonly [VAT_ERROR_BRAND] = true;
+    /**
+     * @param code - The stable identity a catch block dispatches on
+     * @param message - What went wrong, for a human
+     * @param options - `cause`, as on a native Error
+     */
+    constructor(code: string, message: string, options?: ErrorOptions);
+    toString(): string;
+}
+/**
+ * Whether `error` is a VAT error — optionally one carrying exactly `code`.
+ *
+ * Reads the brand and the `code` field, never the prototype chain, so an
+ * instance produced by another copy of this module (a `dist` build beside a
+ * `src` import) still answers yes. A foreign error that happens to carry a
+ * `code` — every `node:fs` errno does — answers no: the brand is the claim.
+ *
+ * @param error - Anything a catch block received
+ * @param code - When given, the exact code required
+ */
+export declare function isVatError(error: unknown, code?: string): error is VatError;
+/**
+ * Prefix an error's message IN PLACE, exactly once per error object.
+ *
+ * In place rather than re-wrapped because the error's class is what its
+ * catch blocks dispatch on (`GradingNonceError`, `RateLimitSignal`, …), and a
+ * wrapper would flatten every class into one. Once, because a retried item or
+ * a cached error object passes through the same seam more than once and must
+ * not accumulate prefixes. "Once" is remembered per object, not detected by
+ * re-reading the message — the previous check was `message.startsWith(prefix)`,
+ * which is a dispatch on prose by another name.
+ *
+ * @param error - Anything a catch block received; a non-Error is left alone
+ * @param prefix - Text to put before the message
+ */
+export declare function prefixMessageOnce(error: unknown, prefix: string): void;
+export {};
+//# sourceMappingURL=vat-error.d.ts.map

package/dist/errors/vat-error.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"vat-error.d.ts","sourceRoot":"","sources":["../../src/errors/vat-error.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,QAAA,MAAM,eAAe,EAAE,OAAO,MAAgC,CAAC;AAE/D,4EAA4E;AAC5E,qBAAa,QAAS,SAAQ,KAAK;IACjC,+EAA+E;IAC/E,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,CAAC,eAAe,CAAC,QAAQ;IAElC;;;;OAIG;gBACS,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,YAAY;IAMxD,QAAQ,IAAI,MAAM;CAG5B;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,OAAO,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,KAAK,IAAI,QAAQ,CAM3E;AAUD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI,CAItE"}