rea-agents 6.3.0 → 6.4.0

package/dist/application/ReferenceSourceImport.js

@@ -5,13 +5,16 @@ import { readReferenceSource } from "../reference/ReferenceSourceReader.js";
 import { parseReferenceSourceEntries } from "./ReferenceSourceImportEntries.js";
 import { readReferenceSourceVcs } from "./ReferenceSourceVcsAdapter.js";
 import {} from "./ReferenceSourceImportTypes.js";
-import { prepareReferenceSourceImport } from "./ReferenceSourceImportPolicy.js";
+import { prepareReferenceSourceImport, } from "./ReferenceSourceImportPolicy.js";
 const failure = (code, message) => ({
     tag: "reference-source-import",
     code,
     message,
 });
-const cancelled = () => failure("cancelled", "Reference source import cancelled");
+const cancelled = (partial) => ({
+    ...failure("cancelled", "Reference source import cancelled"),
+    ...(partial === undefined ? {} : { partial }),
+});
 const isAborted = (signal) => signal?.aborted === true;
 const relationshipKey = (relationship) => `${relationship.from_path}\u0000${relationship.to}\u0000${relationship.kind}\u0000${relationship.resolution}\u0000${relationship.parse_state}`;
 const deduplicateRelationships = (relationships) => {
@@ -65,8 +68,37 @@ const sortExclusions = (exclusions) => [...exclusions].sort((left, right) => {
     const byPath = compareUnicodeCodePoints(left.path, right.path);
     if (byPath !== 0)
         return byPath;
-    return compareUnicodeCodePoints(left.reason, right.reason);
+    const byReason = compareUnicodeCodePoints(left.reason, right.reason);
+    if (byReason !== 0)
+        return byReason;
+    return compareUnicodeCodePoints("pattern" in left ? left.pattern : "", "pattern" in right ? right.pattern : "");
 });
+const createShouldExclude = (exclusions, secrets, ignored) => (path, kind) => {
+    const patternPath = kind === "directory" ? `${path}/` : path;
+    const secretMatch = secrets.test(patternPath);
+    if (secretMatch.ignored) {
+        if (!secretMatch.rule)
+            throw new Error(`Ignored secret path has no matching rule: ${path}`);
+        exclusions.push({
+            path,
+            reason: "configured-secret",
+            pattern: secretMatch.rule.pattern,
+        });
+        return true;
+    }
+    const match = ignored.test(patternPath);
+    if (!match.ignored)
+        return false;
+    if (!match.rule)
+        throw new Error(`Ignored path has no matching rule: ${path}`);
+    const reason = match.rule.mark;
+    if (reason !== "project-ignored" &&
+        reason !== "default-ignored" &&
+        reason !== "caller-excluded")
+        throw new Error(`Ignored path has unknown rule origin: ${path}`);
+    exclusions.push({ path, reason, pattern: match.rule.pattern });
+    return true;
+};
 /**
  * Import a reference source directory into a committed historical source graph.
  *
@@ -74,51 +106,38 @@ const sortExclusions = (exclusions) => [...exclusions].sort((left, right) => {
  * git subprocesses, or network requests. Paths explicitly excluded by the
  * caller's reference-source policy are omitted from the graph.
  */
-export const importReferenceSource = async (options) => {
+export const importReferenceSource = async (options, resources) => {
     if (isAborted(options.signal))
         return err(cancelled());
-    const prepared = await prepareReferenceSourceImport(options);
+    const prepared = await prepareReferenceSourceImport(options, resources);
     if (!prepared.ok)
         return prepared;
     const { ignored, root, secrets } = prepared.value;
     if (isAborted(options.signal))
         return err(cancelled());
     const exclusions = [];
-    const shouldExclude = (path) => {
-        if (secrets.ignores(path)) {
-            exclusions.push({ path, reason: "configured-secret" });
-            return true;
-        }
-        if (ignored.ignores(path)) {
-            exclusions.push({ path, reason: "caller-excluded" });
-            return true;
-        }
-        return false;
-    };
-    const [readResult, vcs] = await Promise.all([
-        readReferenceSource(root, {
+    const shouldExclude = createShouldExclude(exclusions, secrets, ignored);
+    const [readResult, vcsResult] = await Promise.all([
+        readReferenceSource(root, resources, {
             ...(options.signal === undefined ? {} : { signal: options.signal }),
             shouldExclude,
         }),
-        readReferenceSourceVcs(root, options.signal),
+        readReferenceSourceVcs(root, resources, options.signal),
     ]);
-    if (!readResult.ok) {
-        const error = readResult.error;
-        if (error.code === "cancelled")
-            return err(cancelled());
-        if (error.code === "unsupported")
-            return err(failure("unsupported", error.message));
-        return err(failure("io", error.message));
-    }
+    if (!readResult.ok)
+        return err(combineReadFailures(readResult.error, vcsResult.ok ? undefined : vcsResult.error, readResult.error.partial));
+    if (!vcsResult.ok)
+        return err(combineReadFailures(vcsResult.error, undefined, readResult.value));
+    const vcs = vcsResult.value;
     if (isAborted(options.signal))
-        return err(cancelled());
+        return err(cancelled(readResult.value));
     const read = readResult.value;
     const filePaths = new Set(read.entries
         .filter((entry) => entry.status === "read" && entry.kind === "file")
         .map((entry) => entry.path));
     const { entries, relationships, parseFailures, limitations } = parseReferenceSourceEntries(read, filePaths, options.signal);
     if (isAborted(options.signal))
-        return err(cancelled());
+        return err(cancelled(read));
     const uniqueRelationships = deduplicateRelationships(relationships);
     const uniqueFailures = normalizeHistoricalSourceParseFailures(parseFailures);
     const sortedEntries = [...entries].sort((left, right) => compareUnicodeCodePoints(left.path, right.path));
@@ -152,3 +171,31 @@ export const importReferenceSource = async (options) => {
         return err(failure("parse", cause instanceof Error ? cause.message : "Graph failed validation"));
     }
 };
+const combineReadFailures = (primary, other, partial) => {
+    const code = primary.code === "cancelled" || other?.code === "cancelled"
+        ? "cancelled"
+        : primary.code;
+    const cleanup = mergeCleanup(primary.cleanup, other?.cleanup);
+    const message = other === undefined
+        ? primary.message
+        : `${primary.message}; additional reference metadata failure: ${other.message}`;
+    const cause = other === undefined
+        ? primary.cause
+        : new AggregateError([primary, other], "Reference source inventory and metadata both failed", { cause: primary });
+    return {
+        ...failure(code, message),
+        ...(cleanup === undefined ? {} : { cleanup }),
+        ...(partial === undefined ? {} : { partial }),
+        ...(cause === undefined ? {} : { cause }),
+    };
+};
+const mergeCleanup = (first, second) => {
+    if (first === undefined)
+        return second;
+    if (second === undefined)
+        return first;
+    return {
+        reason: `${first.reason}; ${second.reason}`,
+        resources: [...new Set([...first.resources, ...second.resources])],
+    };
+};

package/dist/application/ReferenceSourceImportEntries.js

@@ -1,5 +1,7 @@
 import { createHash } from "node:crypto";
 import { posix } from "node:path";
+import { logicalPathEscapesRoot } from "../domain/artifactIdentity.js";
+import { createReferenceSourcePathLookup, isPortableAbsoluteReferenceTarget, } from "../domain/referenceSourcePathIdentity.js";
 import { classifyReferenceSourcePath, detectReferenceSourceLanguage, } from "../domain/referenceSourceClassification.js";
 import { parseReferenceSourceImports } from "../domain/referenceSourceImportParsing.js";
 import { PARSEABLE_REFERENCE_SOURCE_LANGUAGES } from "./ReferenceSourceImportTypes.js";
@@ -48,11 +50,11 @@ const failedEntry = (entry) => {
         limitations: [limitation],
     };
 };
-const resolveInternalSpecifier = (fromPath, specifier, filePaths) => {
+const resolveInternalSpecifier = (fromPath, specifier, lookupPath) => {
     if (posix.isAbsolute(specifier))
         return { to: specifier, resolution: "unresolved" };
     const normalized = posix.normalize(posix.join(posix.dirname(fromPath), specifier));
-    if (normalized.startsWith("../") || normalized === "..")
+    if (logicalPathEscapesRoot(normalized))
         return { to: normalized, resolution: "unresolved" };
     const suffixes = ["", ".ts", ".js", ".mjs", ".cjs", ".tsx", ".jsx"];
     const candidates = suffixes.flatMap((suffix) => [
@@ -75,12 +77,12 @@ const resolveInternalSpecifier = (fromPath, specifier, filePaths) => {
         const stem = normalized.slice(0, -posix.extname(normalized).length);
         candidates.push(...sourceSuffixes.map((suffix) => `${stem}${suffix}`));
     }
-    const match = candidates.find((candidate) => filePaths.has(candidate));
+    const match = lookupPath.resolveCandidates(candidates);
     return match === undefined
         ? { to: normalized, resolution: "unresolved" }
         : { to: match, resolution: "internal" };
 };
-const appendFile = (entry, filePaths, output) => {
+const appendFile = (entry, lookupPath, output) => {
     const language = detectReferenceSourceLanguage(entry.path);
     output.entries.push({
         path: entry.path,
@@ -100,7 +102,7 @@ const appendFile = (entry, filePaths, output) => {
             output.relationships.push(relationship);
             continue;
         }
-        const resolved = resolveInternalSpecifier(relationship.from_path, relationship.to, filePaths);
+        const resolved = resolveInternalSpecifier(relationship.from_path, relationship.to, lookupPath);
         output.relationships.push({
             ...relationship,
             to: resolved.to,
@@ -109,9 +111,9 @@ const appendFile = (entry, filePaths, output) => {
     }
     output.parseFailures.push(...parsed.parse_failures);
 };
-const appendReadEntry = (entry, filePaths, output) => {
+const appendReadEntry = (entry, lookupPath, output) => {
     if (entry.kind === "file") {
-        appendFile(entry, filePaths, output);
+        appendFile(entry, lookupPath, output);
         return;
     }
     const classifications = classifyReferenceSourcePath(entry.path);
@@ -128,7 +130,13 @@ const appendReadEntry = (entry, filePaths, output) => {
     output.entries.push({
         path: entry.path,
         kind: "symlink",
-        target: entry.target,
+        // The reader resolves inventory identities from its root; the persisted
+        // graph represents relative symlink targets from the link's directory.
+        target: entry.targetState === "internal" ||
+            (entry.targetState === "missing" &&
+                !isPortableAbsoluteReferenceTarget(entry.target))
+            ? posix.relative(posix.dirname(entry.path), entry.target) || "."
+            : entry.target,
         target_state: entry.targetState,
         classifications,
         limitations: [],
@@ -142,13 +150,14 @@ export const parseReferenceSourceEntries = (read, filePaths, signal) => {
         parseFailures: [],
         limitations: [...read.limitations],
     };
+    const lookupPath = createReferenceSourcePathLookup(filePaths);
     for (const entry of read.entries) {
         if (signal?.aborted === true)
             break;
         if (entry.status === "failed")
             output.entries.push(failedEntry(entry));
         else
-            appendReadEntry(entry, filePaths, output);
+            appendReadEntry(entry, lookupPath, output);
     }
     return output;
 };

package/dist/application/ReferenceSourceImportPolicy.js

@@ -1,49 +1,125 @@
-import { readFile, realpath, stat } from "node:fs/promises";
+import { lstat, realpath, stat } from "node:fs/promises";
 import { join, resolve } from "node:path";
 import ignore from "ignore";
+import { readRegularFileText, RegularFileCleanupFailure, retryRegularFileCleanup, } from "./RegularFileRead.js";
 import { err, ok } from "../domain/result.js";
+import { ArtifactReaderFailure } from "../artifacts/ArtifactReader.js";
 import { DEFAULT_REFERENCE_SOURCE_IGNORE_PATTERNS, } from "./ReferenceSourceImportTypes.js";
+import { rootFilesystemFailure } from "../reference/ReferenceSourceReaderErrors.js";
 const failure = (code, message) => ({
     tag: "reference-source-import",
     code,
     message,
 });
-const resolveRoot = async (requestedRoot) => {
+const isAborted = (signal) => signal?.aborted === true;
+const addMarkedPatterns = (matcher, patterns, mark) => {
+    for (const pattern of patterns)
+        for (const line of pattern.split(/\r?\n/u))
+            matcher.add({ pattern: line, mark });
+};
+const resolveRoot = async (requestedRoot, signal) => {
+    if (isAborted(signal))
+        return err(failure("cancelled", "Reference source import cancelled"));
     try {
-        if (!(await stat(requestedRoot)).isDirectory())
-            return err(failure("invalid-root", "Reference source root is not a directory"));
+        const metadata = await stat(requestedRoot);
+        if (isAborted(signal))
+            return err(failure("cancelled", "Reference source import cancelled"));
+        if (!metadata.isDirectory())
+            return err(failure("invalid-root", `Reference source root is not a directory: ${requestedRoot}`));
         const canonicalRoot = await realpath(resolve(requestedRoot));
+        if (isAborted(signal))
+            return err(failure("cancelled", "Reference source import cancelled"));
         return ok(canonicalRoot);
     }
     catch (cause) {
-        void cause;
-        return err(failure("invalid-root", "Reference source root could not be resolved"));
+        if (isAborted(signal))
+            return err(failure("cancelled", "Reference source import cancelled"));
+        const rootFailure = rootFilesystemFailure(cause, "Reference source root could not be resolved");
+        if (rootFailure === undefined)
+            throw cause;
+        return err({ ...failure(rootFailure.code, rootFailure.message), cause });
     }
 };
-const buildIgnored = async (root, excludePaths) => {
+const buildIgnored = async (root, excludePaths, resources, signal) => {
     const ignored = ignore();
+    const policyPath = join(root, ".gitignore");
+    let present = true;
     try {
-        ignored.add(await readFile(join(root, ".gitignore"), "utf8"));
+        await lstat(policyPath);
     }
     catch (cause) {
-        // Missing or unreadable ignore file does not authorize broader access.
-        void cause;
+        if (!(typeof cause === "object" &&
+            cause !== null &&
+            "code" in cause &&
+            cause.code === "ENOENT"))
+            throw cause;
+        present = false;
+    }
+    signal?.throwIfAborted();
+    if (present) {
+        let text;
+        try {
+            text = await readRegularFileText(policyPath, { signal });
+        }
+        catch (cause) {
+            if (!(cause instanceof RegularFileCleanupFailure))
+                throw cause;
+            const retry = await retryRegularFileCleanup(cause, resources);
+            if (retry.cleanup !== undefined) {
+                const primary = cause.outcome.kind === "failed"
+                    ? cause.outcome.cause
+                    : cause.cleanupCause;
+                return err({
+                    ...failure(signal?.aborted === true ? "cancelled" : "io", `Reference source ignore policy could not be read at ${policyPath}: ${errorMessage(primary)}`),
+                    cleanup: retry.cleanup,
+                    cause: primary,
+                });
+            }
+            if (retry.outcome.kind === "failed")
+                throw retry.outcome.cause;
+            text = retry.outcome.value;
+        }
+        addMarkedPatterns(ignored, [text], "project-ignored");
     }
-    ignored.add([...DEFAULT_REFERENCE_SOURCE_IGNORE_PATTERNS]);
+    addMarkedPatterns(ignored, DEFAULT_REFERENCE_SOURCE_IGNORE_PATTERNS, "default-ignored");
     for (const path of excludePaths) {
-        ignored.add(path);
-        ignored.add(`${path}/`);
+        addMarkedPatterns(ignored, [path, `${path}/`], "caller-excluded");
     }
-    return ignored;
+    return ok(ignored);
 };
 /** Resolve the caller-selected directory and build path filters. */
-export const prepareReferenceSourceImport = async (options) => {
-    const root = await resolveRoot(options.root);
-    if (!root.ok)
-        return root;
-    return ok({
-        root: root.value,
-        ignored: await buildIgnored(root.value, options.excludePaths ?? []),
-        secrets: ignore().add([...options.policy.secretPatterns]),
-    });
+export const prepareReferenceSourceImport = async (options, resources) => {
+    try {
+        return await resources.run(async () => {
+            const root = await resolveRoot(options.root, options.signal);
+            if (!root.ok)
+                return root;
+            try {
+                const ignored = await buildIgnored(root.value, options.excludePaths ?? [], resources, options.signal);
+                if (!ignored.ok)
+                    return ignored;
+                return ok({
+                    root: root.value,
+                    ignored: ignored.value,
+                    secrets: ignore().add([...options.policy.secretPatterns]),
+                });
+            }
+            catch (cause) {
+                return err({
+                    ...failure(options.signal?.aborted === true ? "cancelled" : "io", `Reference source ignore policy could not be read at ${join(root.value, ".gitignore")}: ${errorMessage(cause)}`),
+                    cause,
+                });
+            }
+        });
+    }
+    catch (cause) {
+        if (!(cause instanceof ArtifactReaderFailure))
+            throw cause;
+        return err({
+            ...failure(cause.reason === "cancelled" ? "cancelled" : "io", cause.message),
+            ...(cause.cleanup === undefined ? {} : { cleanup: cause.cleanup }),
+            cause,
+        });
+    }
 };
+const errorMessage = (cause) => cause instanceof Error ? cause.message : String(cause);

package/dist/application/ReferenceSourceImportTypes.js

@@ -1,28 +1,36 @@
+const IMPORT_FAILURE_GUIDANCE = {
+    cancelled: {
+        category: "cancelled",
+        message: "Reference source import was cancelled. Start it again when ready.",
+    },
+    "invalid-root": {
+        category: "invalid_input",
+        message: "Reference source directory could not be opened. Check that the path exists, is readable, and points to a directory.",
+    },
+    unsupported: {
+        category: "unsupported_host",
+        message: "Safe no-follow file opens are unavailable on this host. Import the source tree with REA on Linux (including WSL) or macOS.",
+    },
+    io: {
+        category: "execution_failure",
+        message: "Reference source files could not be read. Check directory permissions and try again.",
+    },
+    parse: {
+        category: "execution_failure",
+        message: "Reference source could not be indexed. Check that the source tree is readable, then try again.",
+    },
+};
 /** Safe CLI projection for a historical-source import failure. */
 export const projectReferenceSourceImportError = (error) => {
-    if (error.code === "cancelled")
-        return {
-            category: "cancelled",
-            message: "Reference source import was cancelled. Start it again when ready.",
-        };
-    if (error.code === "invalid-root")
-        return {
-            category: "invalid_input",
-            message: "Reference source directory could not be opened. Check that the path exists, is readable, and points to a directory.",
-        };
-    if (error.code === "unsupported")
-        return {
-            category: "unsupported_host",
-            message: "Safe no-follow file opens are unavailable on this host. Import the source tree with REA on Linux (including WSL) or macOS.",
-        };
-    if (error.code === "io")
-        return {
-            category: "execution_failure",
-            message: "Reference source files could not be read. Check directory permissions and try again.",
-        };
+    const primary = IMPORT_FAILURE_GUIDANCE[error.code];
+    const cleanupMessage = error.cleanup === undefined
+        ? ""
+        : ` Cleanup failed during import for ${error.cleanup.resources.join(", ")}: ${error.cleanup.reason}.`;
     return {
-        category: "execution_failure",
-        message: "Reference source could not be indexed. Check that the source tree is readable, then try again.",
+        category: primary.category,
+        message: `${error.message} ${primary.message}${cleanupMessage}`,
+        ...(error.cleanup === undefined ? {} : { cleanup: error.cleanup }),
+        ...(error.partial === undefined ? {} : { partial: error.partial }),
     };
 };
 export const DEFAULT_REFERENCE_SOURCE_IGNORE_PATTERNS = [

package/dist/application/ReferenceSourceVcsAdapter.js

@@ -1,60 +1,174 @@
 import fs from "node:fs";
-import { lstat, readFile } from "node:fs/promises";
+import { lstat } from "node:fs/promises";
 import { join, resolve } from "node:path";
-import { resolveRef } from "isomorphic-git";
+import { err, ok } from "../domain/result.js";
+import { ArtifactReaderFailure } from "../artifacts/ArtifactReader.js";
+import { readRegularFile, RegularFileCleanupFailure, retryRegularFileCleanup, } from "./RegularFileRead.js";
 /**
  * Read Git metadata for a directory using isomorphic-git.
  *
  * No git subprocess or network is used; only the local `.git` object store is read.
  */
-export const readReferenceSourceVcs = async (root, signal) => {
-    if (isAborted(signal))
-        return { kind: "unknown", head: null, dirty: null };
+export const readReferenceSourceVcs = async (root, resources, signal) => {
     try {
-        await lstat(join(root, ".git"));
+        return await resources.run(async () => {
+            if (isAborted(signal))
+                return ok(unknownVcs());
+            try {
+                await lstat(join(root, ".git"));
+            }
+            catch (cause) {
+                return ok(errorCode(cause) === "ENOENT"
+                    ? { kind: "none", head: null, dirty: null }
+                    : unknownVcs());
+            }
+            try {
+                const head = await resolveSourceHead(root, resources, signal);
+                if (isAborted(signal))
+                    return ok(unknownVcs());
+                return ok({ kind: "git", head, dirty: null });
+            }
+            catch (cause) {
+                if (cause instanceof ArtifactReaderFailure)
+                    throw cause;
+                return ok(unknownVcs());
+            }
+        });
     }
     catch (cause) {
-        return errorCode(cause) === "ENOENT"
-            ? { kind: "none", head: null, dirty: null }
-            : { kind: "unknown", head: null, dirty: null };
-    }
-    try {
-        const head = await resolveSourceHead(root);
-        if (isAborted(signal))
-            return { kind: "unknown", head: null, dirty: null };
-        return { kind: "git", head, dirty: null };
-    }
-    catch (cause) {
-        // Unresolvable refs mean VCS state is unknown, not absent.
-        void cause;
-        return { kind: "unknown", head: null, dirty: null };
+        if (!(cause instanceof ArtifactReaderFailure))
+            throw cause;
+        return err({
+            tag: "reference-source-reader",
+            code: cause.reason === "cancelled" ? "cancelled" : "io",
+            message: cause.message,
+            ...(cause.cleanup === undefined ? {} : { cleanup: cause.cleanup }),
+            cause,
+        });
     }
 };
-const resolveSourceHead = async (root) => {
+const unknownVcs = () => ({
+    kind: "unknown",
+    head: null,
+    dirty: null,
+});
+const resolveSourceHead = async (root, resources, signal) => {
+    // isomorphic-git is loaded on first use so CLI and MCP startup skip it.
+    const { resolveRef } = await import("isomorphic-git");
+    let failedRead;
+    const cleanupFailures = [];
+    const readMetadataBytes = async (path) => {
+        try {
+            return await readRegularFile(path, { signal });
+        }
+        catch (cause) {
+            if (!(cause instanceof RegularFileCleanupFailure))
+                throw cause;
+            const retry = await retryRegularFileCleanup(cause, resources);
+            if (retry.outcome.kind === "failed" &&
+                errorCode(retry.outcome.cause) !== "ENOENT")
+                failedRead ??= { cause: retry.outcome.cause };
+            if (retry.cleanup === undefined &&
+                retry.outcome.kind === "failed" &&
+                !isAborted(signal))
+                throw retry.outcome.cause;
+            const primary = retry.outcome.kind === "failed"
+                ? retry.outcome.cause
+                : cause.cleanupCause;
+            throw new ArtifactReaderFailure(isAborted(signal) ? "cancelled" : "io", `Git metadata could not be read safely: ${errorMessage(primary)}`, {
+                cause: primary,
+                ...(retry.cleanup === undefined ? {} : { cleanup: retry.cleanup }),
+            });
+        }
+    };
+    const readMetadataText = async (path) => (await readMetadataBytes(path)).toString("utf8");
+    const throwCleanupFailures = (primary) => {
+        const observations = cleanupFailures.flatMap((failure) => failure.cleanup === undefined ? [] : [failure.cleanup]);
+        throw new ArtifactReaderFailure(isAborted(signal) ? "cancelled" : "io", `Git metadata could not be read safely: ${errorMessage(primary)}`, {
+            cause: new AggregateError([primary, ...cleanupFailures], "Git metadata reads and cleanup failed", { cause: primary }),
+            ...(observations.length === 0
+                ? {}
+                : {
+                    cleanup: {
+                        reason: observations.map(({ reason }) => reason).join("; "),
+                        resources: [
+                            ...new Set(observations.flatMap(({ resources }) => resources)),
+                        ],
+                    },
+                }),
+        });
+    };
+    const referenceFs = {
+        ...fs,
+        promises: {
+            ...fs.promises,
+            // Let isomorphic-git continue from a failed loose ref to packed-refs,
+            // then report the original read failure after resolution. This preserves
+            // both observations when packed metadata also fails cleanup.
+            readFile: async (path, options = null) => {
+                // The library probes readFile() without a path to detect promise APIs.
+                // Reject that invocation without attributing it to a source read.
+                if (path === undefined)
+                    throw new TypeError("Git filesystem read requires a path");
+                try {
+                    const bytes = await readMetadataBytes(path);
+                    const encoding = typeof options === "string" ? options : options?.encoding;
+                    return encoding === undefined || encoding === null
+                        ? bytes
+                        : bytes.toString(encoding);
+                }
+                catch (cause) {
+                    if (cause instanceof ArtifactReaderFailure) {
+                        cleanupFailures.push(cause);
+                    }
+                    else if (errorCode(cause) !== "ENOENT")
+                        failedRead ??= { cause };
+                    throw cause;
+                }
+            },
+        },
+    };
+    const readRef = async (options) => {
+        let head;
+        try {
+            head = await resolveRef({ fs: referenceFs, dir: root, ...options });
+        }
+        catch (cause) {
+            if (cleanupFailures.length > 0)
+                throwCleanupFailures(failedRead?.cause ?? cause);
+            if (failedRead !== undefined)
+                throw failedRead.cause;
+            throw cause;
+        }
+        if (cleanupFailures.length > 0)
+            throwCleanupFailures(failedRead?.cause ?? cleanupFailures[0]?.cause);
+        signal?.throwIfAborted();
+        if (failedRead !== undefined)
+            throw failedRead.cause;
+        return head;
+    };
     const dotgit = join(root, ".git");
     if (!(await lstat(dotgit)).isFile())
-        return resolveRef({ fs, dir: root, ref: "HEAD" });
-    const pointer = (await readFile(dotgit, "utf8")).replace(/\r?\n$/u, "");
+        return readRef({ ref: "HEAD" });
+    const pointer = (await readMetadataText(dotgit)).replace(/\r?\n$/u, "");
     if (!pointer.startsWith("gitdir: ") || pointer.length === 8)
         throw new Error("Invalid Git directory pointer");
     const gitdir = resolve(root, pointer.slice(8));
     let commonDirectory;
     try {
-        commonDirectory = resolve(gitdir, (await readFile(join(gitdir, "commondir"), "utf8")).replace(/\r?\n$/u, ""));
+        commonDirectory = resolve(gitdir, (await readMetadataText(join(gitdir, "commondir"))).replace(/\r?\n$/u, ""));
     }
     catch (cause) {
         if (errorCode(cause) !== "ENOENT")
             throw cause;
-        return resolveRef({ fs, dir: root, gitdir, ref: "HEAD" });
+        return readRef({ gitdir, ref: "HEAD" });
     }
-    const head = (await readFile(join(gitdir, "HEAD"), "utf8")).trim();
+    const head = (await readMetadataText(join(gitdir, "HEAD"))).trim();
     if (!head.startsWith("ref: "))
-        return resolveRef({ fs, dir: root, gitdir, ref: "HEAD" });
+        return readRef({ gitdir, ref: "HEAD" });
     const ref = head.slice(5);
     const privateRef = ["refs/bisect/", "refs/rewritten/", "refs/worktree/"].some((prefix) => ref.startsWith(prefix));
-    return resolveRef({
-        fs,
-        dir: root,
+    return readRef({
         gitdir: privateRef ? gitdir : commonDirectory,
         ref,
     });
@@ -62,4 +176,5 @@ const resolveSourceHead = async (root) => {
 const errorCode = (cause) => typeof cause === "object" && cause !== null && "code" in cause
     ? String(cause.code)
     : undefined;
+const errorMessage = (cause) => cause instanceof Error ? cause.message : String(cause);
 const isAborted = (signal) => signal?.aborted === true;