rea-agents 4.0.1 → 5.0.0

package/dist/application/LinuxHopper.js

@@ -9,7 +9,10 @@ import { execFileOutput } from "../process/ExecFileOutput.js";
 const execFileAsync = promisify(execFile);
 const DOWNLOAD_PREFIX = "https://www.hopperapp.com:443/downloader/public/";
 const MAX_PACKAGE_BYTES = 100_000_000;
-const SUPPORTED_HOPPER_SHA256 = "0294ced141cc373468ee22d8343e7dac41980cb05a937994ca81c9f09afe7ded";
+const SUPPORTED_HOPPER_SHA256 = new Set([
+    "0294ced141cc373468ee22d8343e7dac41980cb05a937994ca81c9f09afe7ded",
+    "1339f9e58377442b0c6fcb0dfc3cec20d593cc557408521fad9a00dbc6b8da13",
+]);
 const SUPPORTED_RELEASES = {
     deb: {
         filename: `${DOWNLOAD_PREFIX}Hopper-6.4.2-Linux-demo.deb`,
@@ -58,6 +61,7 @@ export const parseLinuxDistribution = (text) => {
     const packageFamily = packageFamilyFor(id, fields.get("ID_LIKE"));
     const supported = packageFamily !== undefined &&
         (id === "arch" ||
+            id === "cachyos" ||
             (id === "ubuntu" && versionAtLeast(versionId, 24)) ||
             (id === "fedora" && versionAtLeast(versionId, 41)));
     const identity = {
@@ -73,7 +77,9 @@ export const readLinuxDistribution = async () => {
     try {
         return parseLinuxDistribution(await readFile("/etc/os-release", "utf8"));
     }
-    catch {
+    catch (cause) {
+        // best-effort cleanup: optional host probing; unknown distribution means unsupported.
+        void cause;
         return undefined;
     }
 };
@@ -143,7 +149,9 @@ const systemLinuxHopperInstallHost = () => ({
                 ? "ready"
                 : "unsupported_hopper_build";
         }
-        catch {
+        catch (cause) {
+            // best-effort cleanup: optional launcher probing; unreadable means missing.
+            void cause;
             return "missing";
         }
     },
@@ -155,12 +163,16 @@ export const linuxHopperBinarySupported = async (path) => {
         const hash = createHash("sha256");
         for await (const chunk of createReadStream(path))
             hash.update(chunk);
-        return hash.digest("hex") === SUPPORTED_HOPPER_SHA256;
+        return linuxHopperLauncherDigestSupported(hash.digest("hex"));
     }
-    catch {
+    catch (cause) {
+        // best-effort cleanup: optional build probing; unreadable means unsupported.
+        void cause;
         return false;
     }
 };
+/** Match a launcher extracted from one of the pinned official Linux packages. */
+export const linuxHopperLauncherDigestSupported = (digest) => SUPPORTED_HOPPER_SHA256.has(digest);
 /** Interpret ldd output conservatively so a present but broken launcher is unhealthy. */
 export const linuxSharedLibrariesAvailable = (output) => !/(?:=>\s+not found|error while loading shared libraries)/iu.test(output);
 const installSystemPackage = async (family, archive) => {
@@ -169,7 +181,9 @@ const installSystemPackage = async (family, archive) => {
             await execFileAsync(command.executable, command.args);
         return true;
     }
-    catch {
+    catch (cause) {
+        // Package-manager failure is reported by the false return.
+        void cause;
         return false;
     }
 };

package/dist/application/MacHopper.js

@@ -63,7 +63,9 @@ export const installMacHopper = async (options = {}, host = systemMacHopperInsta
         await host.openApplication(destination);
         return { status: "installed", launcherPath };
     }
-    catch {
+    catch (cause) {
+        // Install-stage failures share the download reason; the stage is cleaned below.
+        void cause;
         return { status: "failed", reason: "download" };
     }
     finally {
@@ -114,7 +116,9 @@ const systemMacHopperInstallHost = () => ({
             ])).stdout.trim();
             return identifier === BUNDLE_IDENTIFIER;
         }
-        catch {
+        catch (cause) {
+            // best-effort cleanup: optional bundle probing; unreadable means invalid.
+            void cause;
             return false;
         }
     },
@@ -123,7 +127,9 @@ const systemMacHopperInstallHost = () => ({
             await access(path);
             return true;
         }
-        catch {
+        catch (cause) {
+            // best-effort cleanup: optional existence probing; absence means missing.
+            void cause;
             return false;
         }
     },
@@ -142,14 +148,17 @@ const systemMacHopperInstallHost = () => ({
                 await rm(previous, { recursive: true, force: true });
             return true;
         }
-        catch {
+        catch (cause) {
+            // Install failure rolls back below; the false return reports it.
+            void cause;
             await rm(stage, { recursive: true, force: true });
             if (replaceExisting) {
                 try {
                     await rename(previous, destination);
                 }
-                catch {
+                catch (rollbackCause) {
                     // The original destination was not moved, or rollback is impossible.
+                    void rollbackCause;
                 }
             }
             return false;
@@ -160,7 +169,9 @@ const systemMacHopperInstallHost = () => ({
             await access(path);
             return true;
         }
-        catch {
+        catch (cause) {
+            // best-effort cleanup: optional launcher probing; absence means not ready.
+            void cause;
             return false;
         }
     },
@@ -190,7 +201,9 @@ const commandSucceeds = async (command, args) => {
         await execFileAsync(command, args);
         return true;
     }
-    catch {
+    catch (cause) {
+        // best-effort cleanup: optional command probing; failure means unavailable.
+        void cause;
         return false;
     }
 };

package/dist/application/OptionalObservationProviders.js

@@ -0,0 +1,3 @@
+import { AnalysisCapabilityUnavailableError } from "../domain/analysisErrorCore.js";
+/** Preserve the module's failure reason through the existing tool error algebra. */
+export const optionalProviderUnavailable = (failure, operation) => new AnalysisCapabilityUnavailableError(failure.providerId, operation, `Adapter could not load: ${failure.reason}`);

package/dist/application/ProcessCaptureCapability.js

@@ -1,7 +1,7 @@
 import { tmpdir } from "node:os";
 /** Explain why process capture cannot claim owned-process cleanup on a host. */
 export const processCaptureOwnershipUnavailableReason = (platform) => platform === "win32"
-    ? "Windows process-tree ownership and cleanup are unavailable; REA cannot verify that descendants have stopped."
+    ? "Windows PTY process capture is unavailable because this adapter does not yet verify descendant cleanup. Use Linux (including WSL for Linux commands) or macOS. Reinstalling the PTY backend does not enable native Windows capture."
     : undefined;
 /** Probe the native PTY seam and explain loader failures at their source. */
 export const processCaptureProbeFailureReason = (cause) => {

package/dist/application/ProcessCaptureError.js

@@ -1,4 +1,4 @@
-import { AnalysisError } from "../domain/errors.js";
+import { AnalysisError } from "../domain/analysisErrorBase.js";
 /** Typed application failure produced by controlled process capture. */
 export class ProcessCaptureError extends AnalysisError {
     _tag = "ProcessCaptureError";

package/dist/application/ProcessCaptureJournal.js

@@ -33,7 +33,9 @@ export const scheduleScenarioInteractions = (options) => {
                     else
                         terminal.kill(event.signal);
                 }
-                catch {
+                catch (cause) {
+                    // Terminal dispatch failures are recorded as failed outcomes.
+                    void cause;
                     outcome = "failed";
                 }
             }

package/dist/application/ProcessCaptureLifecycle.js

@@ -7,7 +7,8 @@ import { digestProcessCommitment, processComparisonContract, processScenarioComm
 import { PRODUCT_IDENTITY } from "../identity.js";
 import { snapshotRoots } from "./FilesystemSnapshot.js";
 import { classifyFilesystemEffects } from "./ProcessFilesystemEffects.js";
-import { cleanupOwnedProcessGroup, observeOwnedProcessGroup, } from "../process/ProcessOwnership.js";
+import { cleanupOwnedProcessGroup } from "../process/ProcessOwnership.js";
+import { observeOwnedProcessGroup } from "../process/ProcessOwnershipObservation.js";
 import { ProcessCaptureError } from "./ProcessCaptureError.js";
 import { assertNotCancelled } from "./ProcessScenarioRuntimeValidation.js";
 import { normalizeProcessElapsedTime, normalizeProcessSamples, normalizeProcessText, } from "./ProcessNormalization.js";
@@ -216,7 +217,8 @@ export const releaseProcessResources = async (options) => {
     try {
         await options.renderer?.dispose();
     }
-    catch {
+    catch (cause) {
+        void cause;
         failure ??= "terminal renderer cleanup failed";
     }
     if (options.terminal !== undefined && host.platform !== "win32") {
@@ -233,7 +235,8 @@ export const releaseProcessResources = async (options) => {
     try {
         await host.removeTemporaryRoot(options.temporaryRoot);
     }
-    catch {
+    catch (cause) {
+        void cause;
         failure ??= "temporary process root cleanup failed";
     }
     return failure;
@@ -277,9 +280,9 @@ export const resolveProcessResult = (capture, executionFailure, cleanupFailure)
         throw new ProcessCaptureError("process capture produced no result");
     return capture;
 };
-export const prepareProcessCapture = async (scenario, signal, host = systemProcessPreparationHost) => {
+export const prepareProcessCapture = async (scenario, signal, captureSnapshot = snapshotRoots, host = systemProcessPreparationHost) => {
     assertNotCancelled(signal);
-    const before = await snapshotRoots(scenario, signal);
+    const before = await captureSnapshot(scenario, signal);
     const temporaryRoot = await host.createTemporaryRoot();
     try {
         const runId = randomUUID();

package/dist/application/ProcessCli.js

@@ -1,5 +1,7 @@
 import { readFile } from "node:fs/promises";
-import { AnalysisError, AnalysisInputError, projectAnalysisError, } from "../domain/errors.js";
+import { AnalysisError } from "../domain/analysisErrorBase.js";
+import { AnalysisInputError } from "../domain/analysisErrorCore.js";
+import { projectAnalysisError } from "../domain/analysisErrorProjection.js";
 import { createEvidence, parseEvidence } from "../domain/evidence.js";
 import { jsonValueSchema } from "../domain/jsonValue.js";
 import { projectInputIssues } from "../domain/inputIssueProjection.js";
@@ -75,7 +77,7 @@ const parseCaptureEvidence = (input) => {
     try {
         evidence = parseEvidence(input);
     }
-    catch {
+    catch (cause) {
         throw invalidCaptureEvidence();
     }
     if (evidence.operation !== "capture_process_scenario" ||
@@ -91,7 +93,7 @@ const parseCaptureEvidence = (input) => {
             locations: evidence.locations,
         };
     }
-    catch {
+    catch (cause) {
         throw invalidCaptureEvidence();
     }
 };
@@ -107,14 +109,20 @@ const readJson = async (path) => {
     try {
         bytes = await readFile(path);
     }
-    catch {
+    catch (cause) {
+        void cause;
         throw new ProcessCliFailure("invalid_input", "Process input file could not be read. Check that the path exists and is readable.");
     }
     try {
-        const parsed = JSON.parse(bytes.toString("utf8"));
+        const text = new TextDecoder("utf-8", {
+            fatal: true,
+            ignoreBOM: true,
+        }).decode(bytes);
+        const parsed = JSON.parse(text);
         return parsed;
     }
-    catch {
+    catch (cause) {
+        void cause;
         throw new ProcessCliFailure("invalid_input", "Process input file is not valid JSON. Repair the file, then try again.");
     }
 };

package/dist/application/ProcessEvidence.js

@@ -1,11 +1,7 @@
 import { createEvidence } from "../domain/evidence.js";
+import { PROCESS_PROVIDER } from "../domain/processEvidenceProvider.js";
 import { jsonValueSchema } from "../domain/jsonValue.js";
-/** Provider identity for controlled process capture evidence. */
-export const PROCESS_PROVIDER = {
-    id: "rea-process",
-    name: "REA process capture",
-    version: "3",
-};
+export { PROCESS_PROVIDER } from "../domain/processEvidenceProvider.js";
 /** Project one process scenario into secret-free Evidence parameters. */
 const processEvidenceParameters = (scenario) => ({
     executable_name: scenario.executable.split("/").at(-1) ?? scenario.executable,

package/dist/application/ProcessHarness.js

@@ -1,13 +1,14 @@
 import { parseProcessCapture } from "../domain/processCapture.js";
 import { err, ok } from "../domain/result.js";
-import { AnalysisCapabilityUnavailableError, } from "../domain/errors.js";
+import { AnalysisCapabilityUnavailableError } from "../domain/analysisErrorCore.js";
+import {} from "../domain/analysisErrorBase.js";
 import { ProcessCaptureError, processCaptureCancelled, } from "./ProcessCaptureError.js";
 export { ProcessCaptureError } from "./ProcessCaptureError.js";
 import { startProcessSampler } from "./ProcessSampling.js";
 import { snapshotRoots } from "./FilesystemSnapshot.js";
 import { TerminalRenderer } from "./TerminalRenderer.js";
 import { normalizeProcessText } from "./ProcessNormalization.js";
-import { selectCapturedProcessGroupIds } from "../process/ProcessOwnership.js";
+import { selectCapturedProcessGroupIds } from "../process/ProcessOwnershipProcessTree.js";
 import { awaitTerminalExit, buildCaptureResult, captureTerminalFrames, createRunManifest, observeSettlement, prepareProcessCapture, releaseProcessResources, resolveProcessResult, settleProcessCaptureJournal, } from "./ProcessCaptureLifecycle.js";
 import { assertNotCancelled, resolveProcessScenarioRuntimePaths, } from "./ProcessScenarioRuntimeValidation.js";
 import { createProcessCaptureJournal, scheduleScenarioInteractions, } from "./ProcessCaptureJournal.js";
@@ -130,6 +131,15 @@ const finishProcessRun = async (options) => {
     }
     return resolveProcessResult(verifiedCapture, executionFailure, cleanupFailure);
 };
+const normalizeCaptureFailure = (cause, signal) => {
+    if (cause instanceof ProcessCaptureError)
+        return cause;
+    if (signal?.aborted === true &&
+        (cause === signal.reason ||
+            (cause instanceof Error && cause.name === "AbortError")))
+        return processCaptureCancelled();
+    return cause;
+};
 const completeCapture = async (options) => {
     const { runtime, scenario } = options;
     const { reason } = options.exit;
@@ -139,7 +149,7 @@ const completeCapture = async (options) => {
     const samplingPartial = (await runtime.stopSampler()).partial;
     await settleProcessCaptureJournal(options.eventJournal);
     assertNotCancelled(options.signal);
-    const after = await snapshotRoots(scenario, options.signal);
+    const after = await options.captureSnapshot(scenario, options.signal);
     options.recordEvent("filesystem_checkpoints", 1);
     const renderedFrames = await runtime.renderer.frames();
     const checkpoints = [
@@ -184,8 +194,8 @@ const completeCapture = async (options) => {
     });
 };
 /** Execute one caller-selected scenario and return bounded observations. */
-const runProcessScenario = async (scenario, signal, hostEnvironment = process.env, hostPlatform = process.platform) => {
-    const { temporaryRoot, runId, before } = await prepareProcessCapture(scenario, signal);
+const runProcessScenario = async (scenario, signal, hostEnvironment = process.env, hostPlatform = process.platform, captureSnapshot = snapshotRoots) => {
+    const { temporaryRoot, runId, before } = await prepareProcessCapture(scenario, signal, captureSnapshot);
     const frames = [];
     const samples = [];
     const journal = createProcessCaptureJournal();
@@ -238,12 +248,13 @@ const runProcessScenario = async (scenario, signal, hostEnvironment = process.en
             initiallyTruncated: before.truncated,
             eventJournal,
             recordEvent,
+            captureSnapshot,
             ...(signal === undefined ? {} : { signal }),
         });
     }
     catch (cause) {
         runtime?.terminal.kill("SIGKILL");
-        executionFailure = cause;
+        executionFailure = normalizeCaptureFailure(cause, signal);
     }
     return finishProcessRun({
         runtime,
@@ -257,18 +268,19 @@ const runProcessScenario = async (scenario, signal, hostEnvironment = process.en
     });
 };
 /** Execute one scenario through a typed expected-failure channel. */
-export const captureProcessScenario = async (scenario, signal, platform = process.platform, environment = process.env) => {
+export const captureProcessScenario = async (scenario, signal, platform = process.platform, environment = process.env, captureSnapshot = snapshotRoots) => {
     const ownershipReason = processCaptureOwnershipUnavailableReason(platform);
     if (ownershipReason !== undefined)
-        return err(new AnalysisCapabilityUnavailableError("rea-process", "capture_process_scenario", ownershipReason));
+        return err(new AnalysisCapabilityUnavailableError("rea-process", "capture_process_scenario", ownershipReason, { userMessage: ownershipReason }));
     try {
         assertNotCancelled(signal);
         const resolvedScenario = await resolveProcessScenarioRuntimePaths(scenario, environment);
-        return ok(await runProcessScenario(resolvedScenario, signal, environment, platform));
+        return ok(await runProcessScenario(resolvedScenario, signal, environment, platform, captureSnapshot));
     }
     catch (cause) {
-        return err(cause instanceof ProcessCaptureError
-            ? cause
+        const failure = normalizeCaptureFailure(cause, signal);
+        return err(failure instanceof ProcessCaptureError
+            ? failure
             : new ProcessCaptureError("process capture failed", { cause }));
     }
 };

package/dist/application/ProcessNormalization.js

@@ -18,6 +18,7 @@ export const normalizeProcessText = (value, scenario, temporaryRoot, pid) => {
         normalized = normalized.replaceAll(pattern.pattern, pattern.replacement);
     return normalized;
 };
+/** Project sampled observations under the caller-selected normalization rules. */
 export const normalizeProcessSamples = (samples, scenario, rootPid) => {
     const identifiers = [
         rootPid,
@@ -41,12 +42,18 @@ export const normalizeProcessSamples = (samples, scenario, rootPid) => {
     };
     return samples.map((sample) => ({
         at_ms: normalizeProcessElapsedTime(sample.at_ms, scenario.normalization.time_bucket_ms),
-        pid: mapping.get(sample.pid) ?? 1,
-        parent_pid: mapping.get(sample.parent_pid) ?? 0,
-        process_group_id: sample.process_group_id === null
-            ? null
+        pid: scenario.normalization.pids
+            ? (mapping.get(sample.pid) ?? 1)
+            : sample.pid,
+        parent_pid: scenario.normalization.pids
+            ? (mapping.get(sample.parent_pid) ?? 0)
+            : sample.parent_pid,
+        process_group_id: !scenario.normalization.pids || sample.process_group_id === null
+            ? sample.process_group_id
             : (mapping.get(sample.process_group_id) ?? 0),
-        session_id: sample.session_id === null ? null : (mapping.get(sample.session_id) ?? 0),
+        session_id: !scenario.normalization.pids || sample.session_id === null
+            ? sample.session_id
+            : (mapping.get(sample.session_id) ?? 0),
         command: normalizeCommand(sample.command),
     }));
 };

package/dist/application/ProcessSampling.js

@@ -240,7 +240,9 @@ const inspectInitializedPtyRoot = async (rootPid, runId, signal) => {
     try {
         observedRunId = await readProcessRunId(rootPid);
     }
-    catch {
+    catch (cause) {
+        // Unreadable run identity means the root cannot be attributed.
+        void cause;
         return undefined;
     }
     const after = await readRootIdentity(rootPid, signal);

package/dist/application/ReconstructionCoverageService.js

@@ -1,12 +1,9 @@
-import { z } from "zod";
-import { AnalysisInputError } from "../domain/errors.js";
-import { evaluateReconstructionClosure, reconstructionCoverageDataSchema, } from "../domain/reconstructionCoverage.js";
+import { reconstructionCoverageEvaluationInputSchema } from "../domain/reconstructionCoverageInput.js";
+import { AnalysisInputError } from "../domain/analysisErrorCore.js";
+import {} from "../domain/analysisErrorBase.js";
+import { evaluateReconstructionClosure } from "../domain/reconstructionCoverage.js";
 import { jsonValueSchema } from "../domain/jsonValue.js";
 import { err, ok } from "../domain/result.js";
-export const reconstructionCoverageEvaluationInputSchema = z.strictObject({
-    coverage: reconstructionCoverageDataSchema,
-    boundary_id: z.string().min(1),
-});
 /** Evaluate inline reconstruction coverage against a named boundary. */
 export const evaluateReconstructionCoverage = (rawInput, nowEpochMs = Date.now()) => {
     const parsed = reconstructionCoverageEvaluationInputSchema.safeParse(rawInput);

package/dist/application/ReconstructionObligationCandidates.js

@@ -2,7 +2,7 @@ import { createHash } from "node:crypto";
 import canonicalize from "canonicalize";
 import { parseEvidenceBundle, } from "../domain/evidenceBundle.js";
 import { parseProcessCapture } from "../domain/processCapture.js";
-import { parseApplicationGraphEvidence } from "./JavaScriptApplicationEvidenceGraph.js";
+import { parseApplicationGraphEvidence } from "./javascript/JavaScriptApplicationEvidenceGraph.js";
 import { applicationObligationPolicy, semanticObligationPolicy, } from "./ReconstructionObligationPolicies.js";
 /** Derive conservative candidates from graph, process, and reviewed inputs. */
 export const deriveReconstructionObligationCandidates = (bundleInput, reviewed) => {
@@ -32,8 +32,11 @@ const deriveApplicationCandidates = (evidence, records, candidates, limitations)
         const source = parseApplicationGraphEvidence(evidence);
         for (const node of source.graph.nodes) {
             const candidatePolicy = applicationObligationPolicy(node.kind);
-            if (candidatePolicy === undefined)
+            if (candidatePolicy === undefined) {
+                if (node.kind === "unknown")
+                    limitations.add(`Application graph ${source.graph.graph_id} contains unresolved node ${node.node_id}; reconstruction obligations remain unknown.`);
                 continue;
+            }
             const reference = node.observations.map((observation) => graphReference(evidence, records, observation.evidence, `${source.graph.graph_id}/node/${node.node_id}/observation/${observation.observation_id}`));
             addCandidate(candidates, generatedCandidate({
                 key: `application:${node.node_id}:${candidatePolicy.family}`,

package/dist/application/ReconstructionObligationLedgerService.js

@@ -1,5 +1,6 @@
 import { z } from "zod";
-import { AnalysisInputError, AnalysisProtocolError, } from "../domain/errors.js";
+import { AnalysisInputError, AnalysisProtocolError, } from "../domain/analysisErrorCore.js";
+import {} from "../domain/analysisErrorBase.js";
 import { createEvidence } from "../domain/evidence.js";
 import { jsonObjectSchema, jsonValueSchema } from "../domain/jsonValue.js";
 import { reconstructionObligationLedgerInputSchema, reconstructionObligationLedgerSchema, } from "../domain/reconstructionObligationLedgerSchemas.js";

package/dist/application/ReferenceSourceImport.js

@@ -106,6 +106,8 @@ export const importReferenceSource = async (options) => {
         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 (isAborted(options.signal))

package/dist/application/ReferenceSourceImportEntries.js

@@ -3,12 +3,13 @@ import { posix } from "node:path";
 import { classifyReferenceSourcePath, detectReferenceSourceLanguage, } from "../domain/referenceSourceClassification.js";
 import { parseReferenceSourceImports } from "../domain/referenceSourceImportParsing.js";
 import { PARSEABLE_REFERENCE_SOURCE_LANGUAGES } from "./ReferenceSourceImportTypes.js";
-/** Project a low-level entry failure into safe import guidance. */
-export const projectReferenceSourceEntryFailure = (entry) => {
+/** Preserve the observed reader failure and add entry-specific recovery guidance. */
+export const projectReferenceSourceEntryFailure = (entry) => `${entry.message} ${entryRecoveryGuidance(entry)}`;
+const entryRecoveryGuidance = (entry) => {
     if (entry.code === "cancelled")
         return "This entry was not read because the import was cancelled. Start the import again when ready.";
     if (entry.code === "unsupported")
-        return "This entry cannot be read safely on this system. Exclude it or import the directory on a supported system.";
+        return "Exclude this entry or replace it with a regular file.";
     if (entry.kind === "directory")
         return "This directory could not be read. Check its permissions, then try again.";
     if (entry.kind === "symlink")
@@ -48,6 +49,8 @@ const failedEntry = (entry) => {
     };
 };
 const resolveInternalSpecifier = (fromPath, specifier, filePaths) => {
+    if (posix.isAbsolute(specifier))
+        return { to: specifier, resolution: "unresolved" };
     const normalized = posix.normalize(posix.join(posix.dirname(fromPath), specifier));
     if (normalized.startsWith("../") || normalized === "..")
         return { to: normalized, resolution: "unresolved" };
@@ -56,6 +59,22 @@ const resolveInternalSpecifier = (fromPath, specifier, filePaths) => {
         `${normalized}${suffix}`,
         `${normalized}/index${suffix}`,
     ]);
+    // TypeScript source commonly names the extension emitted for NodeNext.
+    // Retain present runtime files first; substitute only a missing counterpart.
+    // Counterparts cover explicit filenames, not directory/index resolution.
+    if (/\.(?:ts|tsx|mts|cts)$/u.test(fromPath)) {
+        const sourceSuffixes = normalized.endsWith(".js")
+            ? [".ts", ".tsx", ".d.ts"]
+            : normalized.endsWith(".mjs")
+                ? [".mts", ".d.mts"]
+                : normalized.endsWith(".cjs")
+                    ? [".cts", ".d.cts"]
+                    : normalized.endsWith(".jsx")
+                        ? [".tsx", ".d.ts"]
+                        : [];
+        const stem = normalized.slice(0, -posix.extname(normalized).length);
+        candidates.push(...sourceSuffixes.map((suffix) => `${stem}${suffix}`));
+    }
     const match = candidates.find((candidate) => filePaths.has(candidate));
     return match === undefined
         ? { to: normalized, resolution: "unresolved" }

package/dist/application/ReferenceSourceImportPolicy.js

@@ -15,7 +15,8 @@ const resolveRoot = async (requestedRoot) => {
         const canonicalRoot = await realpath(resolve(requestedRoot));
         return ok(canonicalRoot);
     }
-    catch {
+    catch (cause) {
+        void cause;
         return err(failure("invalid-root", "Reference source root could not be resolved"));
     }
 };
@@ -24,8 +25,9 @@ const buildIgnored = async (root, excludePaths) => {
     try {
         ignored.add(await readFile(join(root, ".gitignore"), "utf8"));
     }
-    catch {
+    catch (cause) {
         // Missing or unreadable ignore file does not authorize broader access.
+        void cause;
     }
     ignored.add([...DEFAULT_REFERENCE_SOURCE_IGNORE_PATTERNS]);
     for (const path of excludePaths) {

package/dist/application/ReferenceSourceImportTypes.js

@@ -10,6 +10,11 @@ export const projectReferenceSourceImportError = (error) => {
             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",

package/dist/application/ReferenceSourceVcsAdapter.js

@@ -1,6 +1,6 @@
 import fs from "node:fs";
-import { lstat } from "node:fs/promises";
-import { join } from "node:path";
+import { lstat, readFile } from "node:fs/promises";
+import { join, resolve } from "node:path";
 import { resolveRef } from "isomorphic-git";
 /**
  * Read Git metadata for a directory using isomorphic-git.
@@ -19,15 +19,46 @@ export const readReferenceSourceVcs = async (root, signal) => {
             : { kind: "unknown", head: null, dirty: null };
     }
     try {
-        const head = await resolveRef({ fs, dir: root, ref: "HEAD" });
+        const head = await resolveSourceHead(root);
         if (isAborted(signal))
             return { kind: "unknown", head: null, dirty: null };
         return { kind: "git", head, dirty: null };
     }
-    catch {
+    catch (cause) {
+        // Unresolvable refs mean VCS state is unknown, not absent.
+        void cause;
         return { kind: "unknown", head: null, dirty: null };
     }
 };
+const resolveSourceHead = async (root) => {
+    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, "");
+    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, ""));
+    }
+    catch (cause) {
+        if (errorCode(cause) !== "ENOENT")
+            throw cause;
+        return resolveRef({ fs, dir: root, gitdir, ref: "HEAD" });
+    }
+    const head = (await readFile(join(gitdir, "HEAD"), "utf8")).trim();
+    if (!head.startsWith("ref: "))
+        return resolveRef({ fs, dir: root, 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,
+        gitdir: privateRef ? gitdir : commonDirectory,
+        ref,
+    });
+};
 const errorCode = (cause) => typeof cause === "object" && cause !== null && "code" in cause
     ? String(cause.code)
     : undefined;