rea-agents 6.5.0 → 6.7.0

package/dist/application/MacHopper.js

@@ -2,7 +2,7 @@ import { createHash } from "node:crypto";
 import { execFile } from "node:child_process";
 import { access, mkdir, mkdtemp, readdir, rename, rm, writeFile, } from "node:fs/promises";
 import { tmpdir } from "node:os";
-import { join } from "node:path";
+import { dirname, join } from "node:path";
 import { promisify } from "node:util";
 import { z } from "zod";
 import { homeDirectoryFromEnvironment } from "../config/homeDirectory.js";
@@ -29,6 +29,8 @@ export const macHopperInstallDisclosure = {
 export const installMacHopper = async (options = {}, host = systemMacHopperInstallHost(homeDirectoryFromEnvironment(process.env, process.platform), process.env)) => {
     let temporary;
     let mounted = false;
+    let bundleCleanupFailure;
+    let installStage = "release_metadata";
     let result;
     try {
         result = await (async () => {
@@ -41,15 +43,19 @@ export const installMacHopper = async (options = {}, host = systemMacHopperInsta
             const release = parsed.data["OS X"];
             if (!release.filename.startsWith(DOWNLOAD_PREFIX))
                 return { status: "failed", reason: "release_metadata" };
+            installStage = "download";
             const archive = await host.download(release.filename);
             if (!archive.ok)
                 return { status: "failed", reason: "download" };
+            installStage = "integrity";
             if (!integrityMatches(archive.bytes, release))
                 return { status: "failed", reason: "integrity" };
+            installStage = "destination_exists";
             const destination = host.destination();
             const destinationExists = await host.destinationExists(destination);
             if (destinationExists && options.replaceExisting !== true)
                 return { status: "failed", reason: "destination_exists" };
+            installStage = "mount";
             temporary = await host.createTemporaryDirectory();
             const packagePath = join(temporary, "hopper.dmg");
             const mountPath = join(temporary, "mounted");
@@ -58,6 +64,7 @@ export const installMacHopper = async (options = {}, host = systemMacHopperInsta
             if (!(await host.mount(packagePath, mountPath)))
                 return { status: "failed", reason: "mount" };
             mounted = true;
+            installStage = "bundle";
             const source = await host.appBundle(mountPath);
             if (source === undefined)
                 return { status: "failed", reason: "bundle" };
@@ -66,20 +73,39 @@ export const installMacHopper = async (options = {}, host = systemMacHopperInsta
                 return { status: "failed", reason: "bundle" };
             if (verification === "unverified_publisher")
                 return { status: "failed", reason: "publisher_verification_failed" };
-            const stage = `${destination}.rea-stage`;
-            if (!(await host.installBundle(source, destination, stage, destinationExists)))
-                return { status: "failed", reason: "copy" };
+            installStage = "copy";
+            const installation = await host.installBundle(source, destination, destinationExists);
+            if (installation.status === "failed")
+                return {
+                    status: "failed",
+                    reason: installation.reason,
+                    diagnostic: installation.diagnostic,
+                    ...(installation.cleanupFailure === undefined
+                        ? {}
+                        : { cleanupFailure: installation.cleanupFailure }),
+                };
+            bundleCleanupFailure = installation.cleanupFailure;
             const launcherPath = join(destination, "Contents/MacOS/hopper");
-            if (!(await host.launcherReady(launcherPath)))
-                return { status: "failed", reason: "launcher_missing" };
-            await host.openApplication(destination);
-            return { status: "installed", launcherPath };
+            let openFailure;
+            try {
+                await host.openApplication(destination);
+            }
+            catch (cause) {
+                openFailure = failureMessage(cause);
+            }
+            return {
+                status: "installed",
+                launcherPath,
+                ...(openFailure === undefined ? {} : { openFailure }),
+            };
         })();
     }
     catch (cause) {
-        // Install-stage failures share the download reason; the stage is cleaned below.
-        void cause;
-        result = { status: "failed", reason: "download" };
+        result = {
+            status: "failed",
+            reason: installStage,
+            diagnostic: failureMessage(cause),
+        };
     }
     let cleanupFailure;
     if (temporary !== undefined) {
@@ -100,7 +126,95 @@ export const installMacHopper = async (options = {}, host = systemMacHopperInsta
             host.retainCleanup?.(cleanup);
         }
     }
-    return cleanupFailure === undefined ? result : { ...result, cleanupFailure };
+    const retainedCleanupFailure = [
+        bundleCleanupFailure,
+        cleanupFailure,
+        result.cleanupFailure,
+    ]
+        .filter((failure) => failure !== undefined)
+        .join(" ");
+    return retainedCleanupFailure === ""
+        ? result
+        : { ...result, cleanupFailure: retainedCleanupFailure };
+};
+/** Replace a bundle through a fresh same-volume root owned by this transaction. */
+export const installMacHopperBundle = async (source, destination, replaceExisting, operations, retainCleanup) => {
+    const stagingRoot = await operations.createStagingRoot(dirname(destination));
+    const stagedBundle = join(stagingRoot, "new.app");
+    const previousBundle = join(stagingRoot, "previous.app");
+    let originalBackedUp = false;
+    let newCommitted = false;
+    let failureReason = "copy";
+    try {
+        await operations.copyBundle(source, stagedBundle);
+        failureReason = "launcher_missing";
+        await operations.requireLauncher(join(stagedBundle, "Contents/MacOS/hopper"));
+        failureReason = "copy";
+        if (replaceExisting) {
+            await operations.rename(destination, previousBundle);
+            originalBackedUp = true;
+        }
+        await operations.rename(stagedBundle, destination);
+        newCommitted = true;
+    }
+    catch (cause) {
+        const diagnostics = [failureMessage(cause)];
+        if (originalBackedUp && !newCommitted) {
+            try {
+                if (await operations.pathExists(destination))
+                    throw new Error("destination now contains another installation; preserving the previous bundle in its owned staging root");
+                await operations.rename(previousBundle, destination);
+                originalBackedUp = false;
+            }
+            catch (rollbackCause) {
+                diagnostics.push(`rollback failed: ${failureMessage(rollbackCause)}`);
+                const cleanupFailure = `The previous Hopper bundle remains owned at ${previousBundle}; cleanup will retry restoration only if the destination is empty.`;
+                retainCleanup(async () => {
+                    if (originalBackedUp) {
+                        if (await operations.pathExists(destination))
+                            throw new Error(`Hopper destination is occupied; preserving owned backup ${previousBundle}`);
+                        await operations.rename(previousBundle, destination);
+                        originalBackedUp = false;
+                    }
+                    await operations.removeStagingRoot(stagingRoot);
+                });
+                return {
+                    status: "failed",
+                    reason: failureReason,
+                    diagnostic: diagnostics.join("; "),
+                    cleanupFailure,
+                };
+            }
+        }
+        try {
+            await operations.removeStagingRoot(stagingRoot);
+        }
+        catch (cleanupCause) {
+            const cleanupFailure = `Hopper staging root cleanup failed: ${failureMessage(cleanupCause)}`;
+            retainCleanup(() => operations.removeStagingRoot(stagingRoot));
+            diagnostics.push(cleanupFailure);
+            return {
+                status: "failed",
+                reason: failureReason,
+                diagnostic: diagnostics.join("; "),
+                cleanupFailure,
+            };
+        }
+        return {
+            status: "failed",
+            reason: failureReason,
+            diagnostic: diagnostics.join("; "),
+        };
+    }
+    try {
+        await operations.removeStagingRoot(stagingRoot);
+        return { status: "installed" };
+    }
+    catch (cause) {
+        const cleanupFailure = `Hopper staging root cleanup failed after installation committed: ${failureMessage(cause)}`;
+        retainCleanup(() => operations.removeStagingRoot(stagingRoot));
+        return { status: "installed", cleanupFailure };
+    }
 };
 /** Compose installer paths and subprocesses from one selected caller context. */
 export const systemMacHopperInstallHost = (homeDirectory, environment) => {
@@ -111,18 +225,20 @@ export const systemMacHopperInstallHost = (homeDirectory, environment) => {
         createMountDirectory: (path) => mkdir(path),
         writePackage: (path, bytes) => writeFile(path, bytes, { mode: 0o600 }),
         async mount(packagePath, mountPath) {
-            return commandSucceeds("hdiutil", [
+            await execFileAsync("hdiutil", [
                 "attach",
                 "-readonly",
                 "-nobrowse",
                 "-mountpoint",
                 mountPath,
                 packagePath,
-            ], environment);
+            ], { env: environment });
+            return true;
         },
         async unmount(mountPath) {
-            if (!(await commandSucceeds("hdiutil", ["detach", mountPath, "-force"], environment)))
-                throw new Error(`hdiutil detach failed for ${JSON.stringify(mountPath)}`);
+            await execFileAsync("hdiutil", ["detach", mountPath, "-force"], {
+                env: environment,
+            });
         },
         async appBundle(mountPath) {
             const entries = await readdir(mountPath, { withFileTypes: true });
@@ -147,53 +263,26 @@ export const systemMacHopperInstallHost = (homeDirectory, environment) => {
                 return true;
             }
             catch (cause) {
-                // best-effort cleanup: optional existence probing; absence means missing.
-                void cause;
-                return false;
-            }
-        },
-        async installBundle(source, destination, stage, replaceExisting) {
-            const previous = `${stage}-previous`;
-            try {
-                await mkdir(join(homeDirectory, "Applications"), { recursive: true });
-                await rm(stage, { recursive: true, force: true });
-                await rm(previous, { recursive: true, force: true });
-                await execFileAsync("ditto", [source, stage], { env: environment });
-                await access(join(stage, "Contents/MacOS/hopper"));
-                if (replaceExisting)
-                    await rename(destination, previous);
-                await rename(stage, destination);
-                if (replaceExisting)
-                    await rm(previous, { recursive: true, force: true });
-                return true;
-            }
-            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 (rollbackCause) {
-                        // The original destination was not moved, or rollback is impossible.
-                        void rollbackCause;
-                    }
-                }
-                return false;
-            }
-        },
-        async launcherReady(path) {
-            try {
-                await access(path);
-                return true;
-            }
-            catch (cause) {
-                // best-effort cleanup: optional launcher probing; absence means not ready.
-                void cause;
-                return false;
+                if (isMissingPath(cause))
+                    return false;
+                throw cause;
             }
         },
+        installBundle: (source, destination, replaceExisting) => installMacHopperBundle(source, destination, replaceExisting, {
+            async createStagingRoot(parent) {
+                await mkdir(parent, { recursive: true });
+                return mkdtemp(join(parent, ".rea-hopper-stage-"));
+            },
+            copyBundle: async (bundle, staged) => {
+                await execFileAsync("ditto", [bundle, staged], {
+                    env: environment,
+                });
+            },
+            requireLauncher: (path) => access(path).then(() => undefined),
+            pathExists,
+            rename,
+            removeStagingRoot: (path) => rm(path, { recursive: true }),
+        }, (cleanup) => pendingCleanup.add(cleanup)),
         async openApplication(path) {
             await execFileAsync("open", [path], { env: environment });
         },
@@ -207,7 +296,7 @@ export const systemMacHopperInstallHost = (homeDirectory, environment) => {
                     pendingCleanup.delete(cleanup);
                 }
                 catch (cause) {
-                    failure ??= `Hopper DMG cleanup remains incomplete: ${failureMessage(cause)}`;
+                    failure ??= `Hopper installer cleanup remains incomplete: ${failureMessage(cause)}`;
                 }
             }
             return failure;
@@ -225,12 +314,39 @@ const commandSucceeds = async (command, args, environment) => {
         return true;
     }
     catch (cause) {
-        // best-effort cleanup: optional command probing; failure means unavailable.
-        void cause;
-        return false;
+        if (typeof cause === "object" &&
+            cause !== null &&
+            "code" in cause &&
+            typeof cause.code === "number")
+            return false;
+        throw cause;
+    }
+};
+const failureMessage = (cause) => cause instanceof Error
+    ? [
+        cause.message,
+        "stderr" in cause && typeof cause.stderr === "string"
+            ? cause.stderr.trim()
+            : "",
+    ]
+        .filter((value) => value !== "")
+        .join(": ")
+    : String(cause);
+const isMissingPath = (cause) => typeof cause === "object" &&
+    cause !== null &&
+    "code" in cause &&
+    cause.code === "ENOENT";
+const pathExists = async (path) => {
+    try {
+        await access(path);
+        return true;
+    }
+    catch (cause) {
+        if (isMissingPath(cause))
+            return false;
+        throw cause;
     }
 };
-const failureMessage = (cause) => cause instanceof Error ? cause.message : String(cause);
 const releaseSchema = z.object({
     filename: z.string().url(),
     file_length: z.string().regex(/^\d+$/u),

package/dist/application/MipsElfMetadata.js

@@ -46,7 +46,7 @@ export const readMipsElfMetadata = async (handle, metadata, checkCancelled) => {
     const u32 = (data, offset) => little ? data.readUInt32LE(offset) : data.readUInt32BE(offset);
     if (fixedHeader.value.elfClass !== 32 ||
         fixedHeader.value.byteOrder !== metadata.byteOrder ||
-        u16(bytes, 18) !== 8 ||
+        fixedHeader.value.machine !== 8 ||
         u16(bytes, 16) !== metadata.type ||
         u32(bytes, 36) !== metadata.flags)
         return err("MIPS ELF header no longer matches the resolved identity");

package/dist/application/MsixPackageStorage.js

@@ -4,8 +4,8 @@ import { basename, dirname, isAbsolute, join, relative, sep } from "node:path";
 import { err, ok } from "../domain/result.js";
 /** Windows' roaming and local application data roots; empty means unset. */
 export const windowsAppDataRoots = (home, env) => ({
-    roaming: env.APPDATA?.trim() || join(home, "AppData", "Roaming"),
-    local: env.LOCALAPPDATA?.trim() || join(home, "AppData", "Local"),
+    roaming: env.APPDATA || join(home, "AppData", "Roaming"),
+    local: env.LOCALAPPDATA || join(home, "AppData", "Local"),
 });
 /** The per-user root of MSIX package data containers. */
 export const msixPackagesDirectory = (home, env) => join(windowsAppDataRoots(home, env).local, "Packages");
@@ -120,14 +120,21 @@ export const redirectedWriteBlocker = (view, targets, operation, canonicalPath =
  */
 export const packageReadTargetChanged = async (view, configPath) => {
     if (configPath !== view.appDataConfigPath)
-        return false;
+        return ok(false);
     try {
         await lstat(view.privateConfigPath);
-        return true;
+        return ok(true);
     }
     catch (cause) {
-        return !(cause instanceof Error &&
+        if (cause instanceof Error &&
             "code" in cause &&
-            (cause.code === "ENOENT" || cause.code === "ENOTDIR"));
+            (cause.code === "ENOENT" || cause.code === "ENOTDIR"))
+            return ok(false);
+        return err({
+            _tag: "MsixReadTargetInspectionFailure",
+            path: view.privateConfigPath,
+            detail: cause instanceof Error ? cause.message : String(cause),
+            cause,
+        });
     }
 };

package/dist/application/ProviderOperationExecution.js

@@ -1,8 +1,7 @@
 import { z } from "zod";
 import { AnalysisCancelledError, AnalysisInputError, } from "../domain/analysisErrorCore.js";
-import { createEvidence } from "../domain/evidence.js";
-import { jsonObjectSchema } from "../domain/jsonValue.js";
 import { err, ok } from "../domain/result.js";
+import { createAnalysisExecutionEvidence, } from "./AnalysisProvider.js";
 /**
  * Shared CLI/MCP admission, execution, and Evidence composition for
  * single-request providers. The caller retains its operation vocabulary and
@@ -11,29 +10,23 @@ import { err, ok } from "../domain/result.js";
  */
 export const executeProviderOperation = async (operation, input, options, schema, provider, confidence) => {
     if (options?.signal?.aborted)
-        return err(new AnalysisCancelledError(operation));
+        return err(new AnalysisCancelledError(operation, { cause: options.signal.reason }));
     const request = schema.safeParse({ operation, input });
     if (!request.success)
         return err(new AnalysisInputError(operation, { cause: request.error }));
     const executed = await provider.execute(request.data, options);
     if (!executed.ok)
         return executed;
-    const execution = executed.value;
-    const evidence = createEvidence(execution.subject ?? undefined, execution.provider, {
-        operation,
-        parameters: jsonObjectSchema.parse(request.data.input),
-        result: execution.result,
-        rawResult: execution.rawResult,
-        limitations: execution.limitations,
-        locations: execution.locations,
-        confidence,
-    });
-    // A provider that cannot observe the signal may finish its work after the
-    // caller cancelled, so re-check rather than reporting a completed operation
-    // the caller no longer wants. The observation it completed is still this
-    // provider's Evidence, so the cancellation carries it as the partial
-    // observation instead of discarding a finished result.
-    if (options?.signal?.aborted)
-        return err(new AnalysisCancelledError(operation, { partialObservation: evidence }));
+    const evidence = createAnalysisExecutionEvidence(operation, request.data.input, executed.value, confidence);
+    return completeProviderEvidence(evidence, options?.signal);
+};
+/** Classify completion after Evidence assembly, preserving facts on late abort. */
+export const completeProviderEvidence = (evidence, signal, capturedOutput) => {
+    if (signal?.aborted)
+        return err(new AnalysisCancelledError(evidence.operation, {
+            cause: signal.reason,
+            partialObservation: evidence,
+            ...(capturedOutput === undefined ? {} : { capturedOutput }),
+        }));
     return ok(evidence);
 };

package/dist/application/ReconstructionObligationCandidates.js

@@ -5,6 +5,13 @@ import { parseProcessCapture } from "../domain/process/processCaptureParsing.js"
 import { parseApplicationGraphEvidence } from "./javascript/JavaScriptApplicationEvidenceGraph.js";
 import { applicationObligationPolicy, semanticObligationPolicy, } from "./ReconstructionObligationPolicies.js";
 import { compareUnicodeCodePoints } from "../domain/unicodeCodePointOrder.js";
+/** Caller input cites review Evidence that its bundle does not contain. */
+export class MissingReviewEvidenceError extends TypeError {
+    constructor(evidenceId) {
+        super(`Reviewed obligation Evidence is missing: ${evidenceId}`);
+        this.name = "MissingReviewEvidenceError";
+    }
+}
 /** Derive conservative candidates from graph, process, and reviewed inputs. */
 export const deriveReconstructionObligationCandidates = (bundleInput, reviewed) => {
     const bundle = parseEvidenceBundle(bundleInput);
@@ -203,7 +210,7 @@ const reviewedCandidate = (obligation, records) => {
         authority_references: reviewEvidenceIds.map((evidenceId) => {
             const evidence = records.get(evidenceId);
             if (evidence === undefined)
-                throw new TypeError(`Reviewed obligation Evidence is missing: ${evidenceId}`);
+                throw new MissingReviewEvidenceError(evidenceId);
             return {
                 evidence_id: evidenceId,
                 authority: evidence.authority,
@@ -263,7 +270,15 @@ const addCandidate = (candidates, candidate) => {
             ...current.authority_references,
             ...candidate.authority_references,
         ]),
-        definitionCount: current.definitionCount + candidate.definitionCount,
+        // Each observation keeps its own unresolved authority and next steps.
+        unavailable_authority: uniqueBy([...current.unavailable_authority, ...candidate.unavailable_authority], (item) => item),
+        required_next_evidence: uniqueBy([...current.required_next_evidence, ...candidate.required_next_evidence], (item) => item),
+        // A generated ID digests its derivation key, so two generated candidates
+        // with one ID are the same claim seen by several records. Only another
+        // reviewed definition can introduce a competing definition.
+        definitionCount: current.origin === "generated" && candidate.origin === "generated"
+            ? current.definitionCount
+            : current.definitionCount + candidate.definitionCount,
     });
 };
 const sourceState = (references) => {

package/dist/application/ReconstructionObligationLedgerEvaluation.js

@@ -132,6 +132,10 @@ const evaluateBinding = (candidate, binding, context, diagnostics) => {
             addDiagnostic(diagnostics, "missing-case", `Required ${caseKind} fixture is missing.`);
             continue;
         }
+        for (const fixture of fixtures)
+            for (const evidenceId of fixture.evidence_ids)
+                if (!context.evidence.has(evidenceId))
+                    addDiagnostic(diagnostics, "missing-case", `${caseKind} fixture ${fixture.fixture_id} references Evidence ${evidenceId}, which is absent from the bundle.`);
         if (!fixtures.some((fixture) => proofAuthoritySatisfies(fixture.authority, candidate.required_fixture_authority) &&
             fixture.evidence_ids.every((id) => {
                 const evidence = context.evidence.get(id);

package/dist/application/ReconstructionObligationLedgerService.js

@@ -1,13 +1,13 @@
 import { z } from "zod";
 import { AnalysisProtocolError } from "../domain/analysisErrorCore.js";
-import { NonCanonicalEvidenceBundleError } from "../domain/evidenceBundle.js";
+import { DuplicateEvidenceRecordError, NonCanonicalEvidenceBundleError, } from "../domain/evidenceBundle.js";
 import { createEvidence } from "../domain/evidence.js";
 import { jsonObjectSchema, jsonValueSchema } from "../domain/jsonValue.js";
 import { reconstructionObligationLedgerInputSchema, reconstructionObligationLedgerSchema, } from "../domain/reconstructionObligationLedgerSchemas.js";
 import { err, ok } from "../domain/result.js";
 import { requestInputError, workflowInputError } from "./workflowInputError.js";
 import { JAVASCRIPT_APPLICATION_WORKFLOW_PROVIDER } from "./InvestigationProviders.js";
-import { deriveReconstructionObligationCandidates } from "./ReconstructionObligationCandidates.js";
+import { deriveReconstructionObligationCandidates, MissingReviewEvidenceError, } from "./ReconstructionObligationCandidates.js";
 import { evaluateReconstructionObligationLedger } from "./ReconstructionObligationLedgerEvaluation.js";
 const OPERATION = "build_reconstruction_obligation_ledger";
 /** Parse one portable ledger request for both CLI and MCP adapters. */
@@ -30,7 +30,9 @@ export const buildReconstructionObligationLedgerEvidenceValidated = (input) => {
         return ok(createLedgerEvidence(input, ledger));
     }
     catch (cause) {
-        if (cause instanceof NonCanonicalEvidenceBundleError)
+        if (cause instanceof NonCanonicalEvidenceBundleError ||
+            cause instanceof DuplicateEvidenceRecordError ||
+            cause instanceof MissingReviewEvidenceError)
             return err(workflowInputError(OPERATION, cause));
         if (cause instanceof z.ZodError)
             return err(workflowInputError(OPERATION, cause));

package/dist/application/ReconstructionObligationOriginalCases.js

@@ -20,6 +20,14 @@ export const originalCaseDiagnostics = (candidate, binding, evidenceById) => {
             });
             continue;
         }
+        // A valid entry for this case kind does not resolve another entry's
+        // reference; every referenced Evidence ID must be in the bundle.
+        for (const { evidence_id: evidenceId } of cases)
+            if (!evidenceById.has(evidenceId))
+                diagnostics.push({
+                    code: "missing-original-case",
+                    detail: `Original ${caseKind} case references Evidence ${evidenceId}, which is absent from the bundle.`,
+                });
         if (!cases.some(({ evidence_id: evidenceId }) => {
             const evidence = evidenceById.get(evidenceId);
             return (evidence !== undefined &&