rea-agents 6.3.0 → 6.5.0

package/dist/application/MacHopperPaths.js

@@ -0,0 +1,40 @@
+import { readdirSync } from "node:fs";
+import { join } from "node:path";
+export const MAC_HOPPER_APPLICATION_DIRECTORY = "/Applications";
+export const MAC_HOPPER_APPLICATION_NAME = "Hopper Disassembler.app";
+export const MAC_HOPPER_USER_APPLICATIONS_DIRECTORY = "Applications";
+export const MAC_HOPPER_SYSTEM_LAUNCHER = join(MAC_HOPPER_APPLICATION_DIRECTORY, MAC_HOPPER_APPLICATION_NAME, "Contents/MacOS/hopper");
+export const macHopperUserApplicationPath = (homeDirectory) => join(homeDirectory, MAC_HOPPER_USER_APPLICATIONS_DIRECTORY, MAC_HOPPER_APPLICATION_NAME);
+export const macHopperApplicationRoots = (homeDirectory) => [
+    MAC_HOPPER_APPLICATION_DIRECTORY,
+    join(homeDirectory, MAC_HOPPER_USER_APPLICATIONS_DIRECTORY),
+];
+export const macHopperCanonicalLauncherCandidates = (homeDirectory) => [
+    MAC_HOPPER_SYSTEM_LAUNCHER,
+    join(macHopperUserApplicationPath(homeDirectory), "Contents/MacOS/hopper"),
+];
+/** Build deterministic candidates from the discovered app bundle names. */
+export const macHopperRenamedLauncherCandidates = (homeDirectory, bundleNamesByRoot) => macHopperApplicationRoots(homeDirectory).flatMap((root) => [...new Set(bundleNamesByRoot.get(root) ?? [])]
+    .filter((name) => /^Hopper.*\.app$/iu.test(name) &&
+    name.toLocaleLowerCase("en-US") !==
+        MAC_HOPPER_APPLICATION_NAME.toLocaleLowerCase("en-US"))
+    .sort()
+    .map((name) => join(root, name, "Contents/MacOS/hopper")));
+const localBundleNames = (root) => {
+    try {
+        return readdirSync(root, { withFileTypes: true })
+            .filter((entry) => entry.isDirectory() && /^Hopper.*\.app$/iu.test(entry.name))
+            .map(({ name }) => name);
+    }
+    catch (cause) {
+        // Missing or unreadable optional app directories contain no candidates.
+        void cause;
+        return [];
+    }
+};
+/** Yield canonical paths first; enumerate renamed bundles only if needed. */
+export function* macHopperLauncherCandidates(homeDirectory) {
+    yield* macHopperCanonicalLauncherCandidates(homeDirectory);
+    for (const root of macHopperApplicationRoots(homeDirectory))
+        yield* macHopperRenamedLauncherCandidates(homeDirectory, new Map([[root, localBundleNames(root)]]));
+}

package/dist/application/MipsElfMetadata.js

@@ -0,0 +1,201 @@
+import { readElfFixedHeader } from "../domain/elfFixedHeader.js";
+import { err, ok } from "../domain/result.js";
+import { readMipsElfSharedLoad, } from "./MipsElfSharedLoad.js";
+import { MIPS_GNU_ATTRIBUTES_MAX_BYTES, parseMipsGnuAttributes, } from "./MipsGnuAttributes.js";
+const SHT_GNU_ATTRIBUTES = 0x6ffffff5;
+/**
+ * Read ELF32 MIPS ABI and shared-load declarations from the caller's already-open file.
+ * Inspect both typed tables (not section names), including records beyond the
+ * initial header probe. A missing record is unknown, not a default FP ABI.
+ * The caller supplies its cancellation check so its tagged error is preserved.
+ */
+export const readMipsElfMetadata = async (handle, metadata, checkCancelled) => {
+    checkCancelled();
+    if (metadata.elfClass !== 32)
+        return err("MIPS ABI record inspection currently supports ELF32 only");
+    const fileSize = (await handle.stat()).size;
+    checkCancelled();
+    const read = async (offset, length, label) => {
+        checkCancelled();
+        if (!Number.isSafeInteger(fileSize) ||
+            offset < 0 ||
+            length < 0 ||
+            offset > fileSize - length)
+            return err(`MIPS ${label} lies outside the file`);
+        const bytes = Buffer.alloc(length);
+        let total = 0;
+        while (total < length) {
+            checkCancelled();
+            const observed = await handle.read(bytes, total, length - total, offset + total);
+            checkCancelled();
+            if (observed.bytesRead === 0)
+                return err(`truncated MIPS ${label}`);
+            total += observed.bytesRead;
+        }
+        return ok(bytes);
+    };
+    const header = await read(0, 52, "ELF32 header");
+    if (!header.ok)
+        return header;
+    const bytes = header.value;
+    const fixedHeader = readElfFixedHeader(bytes, fileSize);
+    if (!fixedHeader.ok)
+        return fixedHeader;
+    const little = metadata.byteOrder === "little";
+    const u16 = (data, offset) => little ? data.readUInt16LE(offset) : data.readUInt16BE(offset);
+    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 ||
+        u16(bytes, 16) !== metadata.type ||
+        u32(bytes, 36) !== metadata.flags)
+        return err("MIPS ELF header no longer matches the resolved identity");
+    if (fixedHeader.value.headerSize !== 52)
+        return err("invalid MIPS ELF32 version or header size");
+    const tables = [
+        {
+            label: "program header table",
+            offset: u32(bytes, 28),
+            count: u16(bytes, 44),
+            stride: u16(bytes, 42),
+            entrySize: 32,
+            typeOffset: 0,
+            dataOffset: 4,
+            sizeOffset: 16,
+            recordType: 0x70000003, // PT_MIPS_ABIFLAGS
+            optional: false,
+        },
+        {
+            label: "section header table",
+            offset: u32(bytes, 32),
+            count: u16(bytes, 48),
+            stride: u16(bytes, 46),
+            entrySize: 40,
+            typeOffset: 4,
+            dataOffset: 16,
+            sizeOffset: 20,
+            recordType: 0x7000002a, // SHT_MIPS_ABIFLAGS
+            optional: true,
+        },
+    ];
+    // Extended numbering needs a separate section-zero reader. Refuse it rather
+    // than silently treating an unexamined table as having no ABI declarations.
+    if (u16(bytes, 44) === 0xffff || u16(bytes, 48) >= 0xff00)
+        return err("extended or reserved MIPS ELF table numbering is unsupported");
+    let record;
+    let sharedLoad;
+    let programHeaders;
+    const relocationSections = [];
+    const limitations = [];
+    let gnuAttributes = null;
+    for (const table of tables) {
+        if (table.count === 0) {
+            if (table.offset !== 0)
+                return err(`unsupported extended or inconsistent MIPS ${table.label}`);
+            continue;
+        }
+        if (table.offset < 52 || table.stride !== table.entrySize)
+            return err(`invalid MIPS ${table.label} offset or entry size`);
+        const count = table.optional
+            ? Math.min(table.count, Math.max(0, Math.floor((fileSize - table.offset) / table.entrySize)))
+            : table.count;
+        if (count < table.count)
+            limitations.push(`MIPS ${table.label} at file offset ${table.offset} extends beyond the captured file: examined ${count} of ${table.count} complete headers. ABI declarations in unavailable headers remain unknown.`);
+        if (count === 0)
+            continue;
+        // Counts are bounded by the ELF16 fields and strides by their exact ELF32
+        // structure sizes. Never allocate according to an untrusted section size.
+        const contents = await read(table.offset, count * table.entrySize, table.label);
+        if (!contents.ok)
+            return contents;
+        if (!table.optional && metadata.type === 3)
+            programHeaders = contents.value;
+        let found = false;
+        for (let i = 0; i < count; i += 1) {
+            checkCancelled();
+            const position = i * table.entrySize;
+            const type = u32(contents.value, position + table.typeOffset);
+            if (table.optional && type === SHT_GNU_ATTRIBUTES) {
+                if (gnuAttributes !== null)
+                    return err("duplicate MIPS GNU attribute sections");
+                const size = u32(contents.value, position + 20);
+                if (size === 0 || size > MIPS_GNU_ATTRIBUTES_MAX_BYTES)
+                    return err(`MIPS GNU attribute section size ${size} is outside REA's inspected bound of ${MIPS_GNU_ATTRIBUTES_MAX_BYTES} bytes`);
+                const section = await read(u32(contents.value, position + 16), size, "GNU attribute section");
+                if (!section.ok)
+                    return section;
+                const parsed = parseMipsGnuAttributes(section.value, little);
+                if (!parsed.ok)
+                    return parsed;
+                gnuAttributes = parsed.value;
+                continue;
+            }
+            if (metadata.type === 3 && table.optional && (type === 4 || type === 9))
+                relocationSections.push({
+                    type,
+                    offset: u32(contents.value, position + 16),
+                    size: u32(contents.value, position + 20),
+                    entrySize: u32(contents.value, position + 36),
+                });
+            if (type !== table.recordType)
+                continue;
+            if (found)
+                return err(`duplicate MIPS ABI records in ${table.label}`);
+            found = true;
+            const offset = u32(contents.value, position + table.dataOffset);
+            const size = u32(contents.value, position + table.sizeOffset);
+            if (size !== 24)
+                return err("unsupported MIPS ABI record size; expected 24 bytes");
+            const candidate = await read(offset, 24, "ABI record");
+            if (!candidate.ok)
+                return candidate;
+            if (record !== undefined && !record.equals(candidate.value))
+                return err("conflicting MIPS program/section ABI declarations");
+            record = candidate.value;
+        }
+    }
+    if (metadata.type === 3 && programHeaders !== undefined) {
+        if (limitations.length > 0)
+            sharedLoad = {
+                status: "unavailable",
+                reason: `MIPS shared-image relocation declaration sources are incomplete. ${limitations.join(" ")}`,
+            };
+        else {
+            const shared = await readMipsElfSharedLoad(programHeaders, little, fileSize, read, checkCancelled, relocationSections);
+            sharedLoad = shared.ok
+                ? shared.value
+                : { status: "unavailable", reason: shared.error };
+        }
+    }
+    const shared = metadata.type === 3
+        ? {
+            sharedLoad: sharedLoad ?? {
+                status: "unavailable",
+                reason: "MIPS shared image has no inspected program header table",
+            },
+        }
+        : {};
+    if (record === undefined)
+        return ok({ abiFlags: null, gnuAttributes, limitations, ...shared });
+    // Preserve declarations verbatim, including unknown versions/values. Provider
+    // admission, not parsing, decides which interpretations have been verified.
+    const abiFlags = {
+        version: u16(record, 0),
+        isaLevel: record.readUInt8(2),
+        isaRevision: record.readUInt8(3),
+        gprSize: record.readUInt8(4),
+        cpr1Size: record.readUInt8(5),
+        cpr2Size: record.readUInt8(6),
+        fpAbi: record.readUInt8(7),
+        isaExtension: u32(record, 8),
+        ases: u32(record, 12),
+        flags1: u32(record, 16),
+        flags2: u32(record, 20),
+    };
+    if (gnuAttributes !== null &&
+        gnuAttributes.fpAbi !== null &&
+        gnuAttributes.fpAbi !== 0 &&
+        gnuAttributes.fpAbi !== abiFlags.fpAbi)
+        return err("conflicting MIPS ABI flags and GNU floating-point ABI declarations");
+    return ok({ abiFlags, gnuAttributes, limitations, ...shared });
+};

package/dist/application/MipsElfSharedLoad.js

@@ -0,0 +1,164 @@
+import { err, ok } from "../domain/result.js";
+/** Source ELF facts only; the provider owns interpretation and admission. */
+export const readMipsElfSharedLoad = async (programHeaders, little, fileSize, read, checkCancelled, sections) => {
+    const u32 = (bytes, offset) => little ? bytes.readUInt32LE(offset) : bytes.readUInt32BE(offset);
+    const loads = [];
+    let dynamic;
+    for (let position = 0; position < programHeaders.length; position += 32) {
+        checkCancelled();
+        const type = u32(programHeaders, position);
+        const offset = u32(programHeaders, position + 4);
+        const size = u32(programHeaders, position + 16);
+        if (type === 1) {
+            const address = u32(programHeaders, position + 8);
+            const memorySize = u32(programHeaders, position + 20);
+            if (offset > fileSize - size ||
+                size > memorySize ||
+                address + memorySize > 0x100000000)
+                return err("invalid or incomplete MIPS PT_LOAD range");
+            loads.push({ offset, address, size, memorySize });
+        }
+        if (type === 2) {
+            if (dynamic !== undefined)
+                return err("duplicate MIPS PT_DYNAMIC tables");
+            dynamic = { offset, address: u32(programHeaders, position + 8), size };
+        }
+    }
+    if (dynamic === undefined)
+        return err("MIPS shared image has no PT_DYNAMIC table");
+    if (dynamic.size === 0 || dynamic.size % 8 !== 0)
+        return err("invalid MIPS ELF32 dynamic table size");
+    if (dynamic.offset > fileSize - dynamic.size)
+        return err("MIPS PT_DYNAMIC range extends beyond the file");
+    const ranges = loads
+        .filter((load) => load.memorySize > 0)
+        .sort((left, right) => left.address - right.address);
+    for (let i = 1; i < ranges.length; i += 1) {
+        checkCancelled();
+        const previous = ranges[i - 1];
+        if (ranges[i].address < previous.address + previous.memorySize)
+            return err("overlapping MIPS PT_LOAD memory ranges require separate mapping verification");
+    }
+    // One normalized index prevents relocation count * program-header count work.
+    const mapped = (address, length, fileBacked) => {
+        let low = 0;
+        let high = ranges.length;
+        while (low < high) {
+            const middle = Math.floor((low + high) / 2);
+            if (ranges[middle].address <= address)
+                low = middle + 1;
+            else
+                high = middle;
+        }
+        const range = ranges[low - 1];
+        return range !== undefined &&
+            address - range.address <=
+                (fileBacked ? range.size : range.memorySize) - length
+            ? range
+            : undefined;
+    };
+    const dynamicMapping = mapped(dynamic.address, dynamic.size, true);
+    if (dynamicMapping === undefined ||
+        dynamicMapping.offset + dynamic.address - dynamicMapping.address !==
+            dynamic.offset)
+        return err("MIPS PT_DYNAMIC has no unique matching file-backed PT_LOAD range");
+    // Bound temporary storage, not admitted artifact size. ELF32 records are
+    // exact eight-byte structures; every declared record is examined or refused.
+    const chunkBytes = 64 * 1024;
+    const relevant = new Set([2, 7, 8, 9, 17, 18, 19, 20, 23]);
+    const tags = new Map();
+    let terminated = false;
+    for (let offset = 0; offset < dynamic.size && !terminated; offset += chunkBytes) {
+        const chunk = await read(dynamic.offset + offset, Math.min(chunkBytes, dynamic.size - offset), "dynamic table");
+        if (!chunk.ok)
+            return chunk;
+        for (let position = 0; position < chunk.value.length; position += 8) {
+            checkCancelled();
+            const tag = u32(chunk.value, position);
+            if (tag === 0) {
+                terminated = true;
+                break;
+            }
+            if (!relevant.has(tag))
+                continue;
+            if (tags.has(tag))
+                return err(`duplicate MIPS dynamic tag ${tag}`);
+            tags.set(tag, u32(chunk.value, position + 4));
+        }
+    }
+    if (!terminated)
+        return err("MIPS dynamic table has no DT_NULL terminator");
+    if ([2, 7, 8, 9, 23].some((tag) => (tags.get(tag) ?? 0) !== 0))
+        return err("MIPS shared RELA or PLT relocation declarations require separate verification");
+    const address = tags.get(17);
+    const size = tags.get(18);
+    const stride = tags.get(19);
+    const checkSections = (offset, length) => {
+        let observed = 0;
+        for (const section of sections) {
+            checkCancelled();
+            if (section.size === 0)
+                continue;
+            if (section.type !== 9 ||
+                section.entrySize !== 8 ||
+                section.offset !== offset ||
+                section.size !== length)
+                return "MIPS section relocation declarations outside the dynamic REL table require separate verification";
+            observed += 1;
+        }
+        return observed > 1
+            ? "duplicate MIPS section relocation declarations require separate verification"
+            : undefined;
+    };
+    const emptyRelocations = () => {
+        const reason = checkSections(0, 0);
+        return reason === undefined
+            ? ok({
+                status: "complete",
+                relocationCount: 0,
+                relocationTypes: [],
+                symbolRelativeCount: 0,
+            })
+            : err(reason);
+    };
+    if (address === undefined && size === undefined && stride === undefined)
+        return emptyRelocations();
+    if (address === undefined ||
+        size === undefined ||
+        stride !== 8 ||
+        size % 8 !== 0)
+        return err("incomplete or invalid MIPS DT_REL/DT_RELSZ/DT_RELENT declaration");
+    if (size === 0)
+        return emptyRelocations();
+    const mapping = mapped(address, size, true);
+    if (mapping === undefined)
+        return err("MIPS DT_REL range has no unique complete file-backed PT_LOAD mapping");
+    const fileOffset = mapping.offset + address - mapping.address;
+    const sectionReason = checkSections(fileOffset, size);
+    if (sectionReason !== undefined)
+        return err(sectionReason);
+    let symbolRelativeCount = 0;
+    const types = new Set();
+    for (let offset = 0; offset < size; offset += chunkBytes) {
+        const chunk = await read(fileOffset + offset, Math.min(chunkBytes, size - offset), "dynamic REL records");
+        if (!chunk.ok)
+            return chunk;
+        for (let position = 0; position < chunk.value.length; position += 8) {
+            checkCancelled();
+            const info = u32(chunk.value, position + 4);
+            const type = info & 0xff;
+            const relocationAddress = u32(chunk.value, position);
+            if (type === 3 && mapped(relocationAddress, 4, false) === undefined)
+                return err("MIPS REL32 destination has no unique complete PT_LOAD memory range");
+            types.add(type);
+            if (type === 3 && info >>> 8 !== 0)
+                symbolRelativeCount += 1;
+        }
+    }
+    return ok({
+        status: "complete",
+        relocationCount: size / 8,
+        relocationTypes: [...types].sort((left, right) => left - right),
+        symbolRelativeCount,
+    });
+};

package/dist/application/MipsGnuAttributes.js

@@ -0,0 +1,90 @@
+import { err, ok } from "../domain/result.js";
+/** Bound the section read before its declared size can drive allocation. */
+export const MIPS_GNU_ATTRIBUTES_MAX_BYTES = 4096;
+const FORMAT_VERSION = 0x41;
+const TAG_FILE = 1;
+const TAG_GNU_MIPS_ABI_FP = 4;
+const TAG_GNU_MIPS_ABI_MSA = 8;
+/**
+ * Read only GNU file-scope MIPS ABI attributes REA understands. Unknown
+ * vendors, scopes and tags fail closed; their declarations are not skipped.
+ */
+export const parseMipsGnuAttributes = (bytes, littleEndian) => {
+    if (bytes.length === 0 || bytes[0] !== FORMAT_VERSION)
+        return err("unsupported MIPS GNU attribute section format version");
+    const readU32 = (offset) => littleEndian ? bytes.readUInt32LE(offset) : bytes.readUInt32BE(offset);
+    const readUleb = (offset, end) => {
+        let value = 0;
+        for (let index = 0; index < 5 && offset + index < end; index += 1) {
+            const byte = bytes[offset + index];
+            value += (byte & 0x7f) * 2 ** (7 * index);
+            if ((byte & 0x80) === 0)
+                return value <= 0xffffffff
+                    ? { value, next: offset + index + 1 }
+                    : undefined;
+        }
+        return undefined;
+    };
+    let fpAbi = null;
+    let msa = null;
+    let vendorSeen = false;
+    let position = 1;
+    while (position < bytes.length) {
+        if (bytes.length - position < 4)
+            return err("truncated MIPS GNU attribute subsection length");
+        const length = readU32(position);
+        if (length < 4 || length > bytes.length - position)
+            return err("MIPS GNU attribute subsection length does not fit the section");
+        const end = position + length;
+        const vendorEnd = bytes.indexOf(0, position + 4);
+        if (vendorEnd < 0 || vendorEnd >= end)
+            return err("unterminated MIPS GNU attribute vendor name");
+        if (bytes.toString("latin1", position + 4, vendorEnd) !== "gnu")
+            return err("MIPS ELF declares non-GNU vendor attributes that REA does not inspect");
+        if (vendorSeen)
+            return err("duplicate MIPS GNU attribute vendor subsections");
+        vendorSeen = true;
+        let cursor = vendorEnd + 1;
+        while (cursor < end) {
+            const scopeStart = cursor;
+            const scope = readUleb(cursor, end);
+            if (scope === undefined)
+                return err("malformed MIPS GNU attribute scope tag");
+            if (scope.value !== TAG_FILE)
+                return err("MIPS GNU attributes scoped to sections or symbols are not inspected by REA");
+            if (end - scope.next < 4)
+                return err("truncated MIPS GNU attribute scope length");
+            const scopeLength = readU32(scope.next);
+            if (scopeLength < scope.next + 4 - scopeStart ||
+                scopeLength > end - scopeStart)
+                return err("MIPS GNU attribute scope length does not fit its subsection");
+            const scopeEnd = scopeStart + scopeLength;
+            cursor = scope.next + 4;
+            while (cursor < scopeEnd) {
+                const tag = readUleb(cursor, scopeEnd);
+                if (tag === undefined)
+                    return err("malformed MIPS GNU attribute tag");
+                if (tag.value !== TAG_GNU_MIPS_ABI_FP &&
+                    tag.value !== TAG_GNU_MIPS_ABI_MSA)
+                    return err(`MIPS ELF declares GNU attribute tag ${tag.value}, which REA does not inspect`);
+                const value = readUleb(tag.next, scopeEnd);
+                if (value === undefined)
+                    return err("malformed MIPS GNU attribute value");
+                if (tag.value === TAG_GNU_MIPS_ABI_FP) {
+                    if (fpAbi !== null)
+                        return err("duplicate MIPS GNU floating-point ABI attributes");
+                    fpAbi = value.value;
+                }
+                else {
+                    if (msa !== null)
+                        return err("duplicate MIPS GNU MSA ABI attributes");
+                    msa = value.value;
+                }
+                cursor = value.next;
+            }
+            cursor = scopeEnd;
+        }
+        position = end;
+    }
+    return ok({ fpAbi, msa });
+};

package/dist/application/MsixPackageStorage.js

@@ -0,0 +1,133 @@
+import { lstat } from "node:fs/promises";
+import { realpathSync } from "node:fs";
+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"),
+});
+/** The per-user root of MSIX package data containers. */
+export const msixPackagesDirectory = (home, env) => join(windowsAppDataRoots(home, env).local, "Packages");
+/** Whether `path` is `root` or inside it, using the host's path comparison. */
+const pathWithin = (path, root) => {
+    const inner = relative(root, path);
+    return (inner === "" ||
+        (inner !== ".." && !inner.startsWith(`..${sep}`) && !isAbsolute(inner)));
+};
+/**
+ * Name the package whose private `LocalCache` holds a canonical path. Its
+ * processes see those files at virtual AppData locations; other processes do
+ * not, and Windows removes them with the package.
+ */
+export const packagePrivateStorageFamily = (canonicalPath, packagesDirectory) => {
+    if (!pathWithin(canonicalPath, packagesDirectory))
+        return undefined;
+    const [family, storage] = relative(packagesDirectory, canonicalPath).split(/[\\/]/u);
+    return family !== undefined &&
+        family !== "" &&
+        storage?.toLowerCase() === "localcache"
+        ? family
+        : undefined;
+};
+/**
+ * Explain why setup must not register a launcher that exists only in one
+ * package's private storage. Other clients could not start it, and doctor
+ * outside that package could not verify it.
+ */
+export const packagePrivateLauncherBlocker = (command, packagesDirectory, canonicalPath = realpathSync.native) => {
+    // Compare canonical forms: a short-name, junctioned or substituted profile
+    // spells the same directory differently.
+    let packages = packagesDirectory;
+    try {
+        packages = canonicalPath(packagesDirectory);
+    }
+    catch (cause) {
+        // Without package storage, the spelled path is the only comparison.
+        void cause;
+    }
+    for (const part of command) {
+        if (!isAbsolute(part))
+            continue;
+        let resolved;
+        try {
+            resolved = canonicalPath(part);
+        }
+        catch (cause) {
+            // A launcher that cannot be resolved is not evidence of package storage.
+            void cause;
+            continue;
+        }
+        const family = packagePrivateStorageFamily(resolved, packages);
+        if (family !== undefined)
+            return `The REA launcher ${part} is stored at ${resolved}, inside the private storage of MSIX package ${family}. Only processes started by that app can see it at ${part}, and Windows removes it with the package, so other clients could not start this registration. Install REA from a terminal that the app did not start (for example with \`npm install -g rea-agents\`), then rerun setup from that terminal.`;
+    }
+    return undefined;
+};
+/**
+ * Explain why this process must not write `targets`: the running package
+ * started it, so writes under its virtualized roots land in that package's
+ * private storage, which the targets' owners never read.
+ */
+const canonicalDestination = (path, canonicalPath) => {
+    let ancestor = path;
+    const missing = [];
+    while (true) {
+        try {
+            return ok(join(canonicalPath(ancestor), ...missing));
+        }
+        catch (cause) {
+            if (cause instanceof Error &&
+                "code" in cause &&
+                (cause.code === "ENOENT" || cause.code === "ENOTDIR") &&
+                dirname(ancestor) !== ancestor) {
+                missing.unshift(basename(ancestor));
+                ancestor = dirname(ancestor);
+                continue;
+            }
+            return err({
+                path,
+                detail: cause instanceof Error ? cause.message : String(cause),
+            });
+        }
+    }
+};
+export const redirectedWriteBlocker = (view, targets, operation, canonicalPath = realpathSync.native) => {
+    if (view?.processView !== "redirected" || targets.length === 0)
+        return undefined;
+    const roots = [];
+    const redirected = [];
+    for (const root of view.virtualizedRoots) {
+        const resolved = canonicalDestination(root, canonicalPath);
+        if (!resolved.ok)
+            return `Cannot establish the MSIX write location for ${resolved.error.path}: ${resolved.error.detail}. Rerun ${operation} from a terminal that this app did not start.`;
+        roots.push(resolved.value);
+    }
+    for (const target of targets) {
+        const resolved = canonicalDestination(target, canonicalPath);
+        if (!resolved.ok)
+            return `Cannot establish the MSIX write location for ${resolved.error.path}: ${resolved.error.detail}. Rerun ${operation} from a terminal that this app did not start.`;
+        if (roots.some((root) => pathWithin(resolved.value, root)))
+            redirected.push(target);
+    }
+    if (redirected.length === 0)
+        return undefined;
+    return `This process was started by MSIX package ${view.packageFamilyName}, which redirects its writes under ${view.virtualizedRoots.join(" and ")} into the package's private storage. Changes to ${redirected.join(", ")} would not reach the files other apps read. Rerun ${operation} from a terminal that this app did not start.`;
+};
+/**
+ * Whether the package began reading its private copy after the AppData file
+ * was chosen, for example by saving its settings when it quit.
+ */
+export const packageReadTargetChanged = async (view, configPath) => {
+    if (configPath !== view.appDataConfigPath)
+        return false;
+    try {
+        await lstat(view.privateConfigPath);
+        return true;
+    }
+    catch (cause) {
+        return !(cause instanceof Error &&
+            "code" in cause &&
+            (cause.code === "ENOENT" || cause.code === "ENOTDIR"));
+    }
+};

package/dist/application/ProgressReporter.js

@@ -1,7 +1,7 @@
 /** Create a monotonic, rate-bounded reporter around a surface-specific sink. */
 export const createProgressReporter = (sink, options = {}) => {
     const minimumIntervalMs = options.minimumIntervalMs ?? 100;
-    const now = options.now ?? Date.now;
+    const now = options.now ?? (() => performance.now());
     let lastCompleted = -1;
     let lastSentAt = Number.NEGATIVE_INFINITY;
     let sequence = 0;

package/dist/application/ProviderOperationExecution.js

@@ -0,0 +1,39 @@
+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";
+/**
+ * Shared CLI/MCP admission, execution, and Evidence composition for
+ * single-request providers. The caller retains its operation vocabulary and
+ * confidence; this normalizes cancellation, input validation, and Evidence
+ * assembly once instead of per provider.
+ */
+export const executeProviderOperation = async (operation, input, options, schema, provider, confidence) => {
+    if (options?.signal?.aborted)
+        return err(new AnalysisCancelledError(operation));
+    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 }));
+    return ok(evidence);
+};