rea-agents 6.4.0 → 6.5.0

package/dist/application/MacHopper.js

@@ -6,17 +6,21 @@ import { join } from "node:path";
 import { promisify } from "node:util";
 import { z } from "zod";
 import { homeDirectoryFromEnvironment } from "../config/homeDirectory.js";
+import { HOPPER_PUBLISHER } from "../domain/hopperPublisher.js";
+import { macDeveloperIdRequirement } from "../process/MacCodeSignature.js";
+import { macHopperUserApplicationPath } from "./MacHopperPaths.js";
 import { downloadHopperPackage, HOPPER_DOWNLOAD_BYTES, } from "./HopperDownload.js";
 const execFileAsync = promisify(execFile);
 const RELEASES_URL = "https://www.hopperapp.com/include/files-api.php?request=releases&public=true";
 const DOWNLOAD_PREFIX = "https://www.hopperapp.com:443/downloader/public/";
-const BUNDLE_IDENTIFIER = "com.cryptic-apps.hopper-web-4";
+const HOPPER_PUBLISHER_REQUIREMENT = macDeveloperIdRequirement(HOPPER_PUBLISHER.bundleIdentifier, HOPPER_PUBLISHER.teamIdentifier);
 /** Stable network and command effects disclosed before macOS Hopper setup. */
 export const macHopperInstallDisclosure = {
     networkOrigins: [RELEASES_URL, DOWNLOAD_PREFIX],
     commands: [
         "hdiutil attach -readonly -nobrowse -mountpoint <private-mount> <verified-hopper.dmg>",
         "codesign --verify --deep --strict <mounted-hopper.app>",
+        `codesign --verify --strict '-R${HOPPER_PUBLISHER_REQUIREMENT}' <mounted-hopper.app>`,
         "ditto <mounted-hopper.app> <user-Applications-stage>",
         "open <installed-hopper.app>",
     ],
@@ -55,8 +59,13 @@ export const installMacHopper = async (options = {}, host = systemMacHopperInsta
                 return { status: "failed", reason: "mount" };
             mounted = true;
             const source = await host.appBundle(mountPath);
-            if (source === undefined || !(await host.validBundle(source)))
+            if (source === undefined)
                 return { status: "failed", reason: "bundle" };
+            const verification = await host.validBundle(source);
+            if (verification === "invalid_signature")
+                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" };
@@ -122,20 +131,15 @@ export const systemMacHopperInstallHost = (homeDirectory, environment) => {
         },
         async validBundle(appPath) {
             if (!(await commandSucceeds("codesign", ["--verify", "--deep", "--strict", appPath], environment)))
-                return false;
-            try {
-                const identifier = (await execFileAsync("/usr/libexec/PlistBuddy", [
-                    "-c",
-                    "Print :CFBundleIdentifier",
-                    join(appPath, "Contents/Info.plist"),
-                ], { env: environment })).stdout.trim();
-                return identifier === BUNDLE_IDENTIFIER;
-            }
-            catch (cause) {
-                // best-effort cleanup: optional bundle probing; unreadable means invalid.
-                void cause;
-                return false;
-            }
+                return "invalid_signature";
+            if (!(await commandSucceeds("codesign", [
+                "--verify",
+                "--strict",
+                `-R${HOPPER_PUBLISHER_REQUIREMENT}`,
+                appPath,
+            ], environment)))
+                return "unverified_publisher";
+            return "verified";
         },
         async destinationExists(path) {
             try {
@@ -208,7 +212,7 @@ export const systemMacHopperInstallHost = (homeDirectory, environment) => {
             }
             return failure;
         },
-        destination: () => join(homeDirectory, "Applications/Hopper Disassembler.app"),
+        destination: () => macHopperUserApplicationPath(homeDirectory),
     };
 };
 const parseJson = (bytes) => JSON.parse(new TextDecoder().decode(bytes));

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/{MipsElfAbiFlags.js → MipsElfMetadata.js}

@@ -1,11 +1,15 @@
+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 declarations from the caller's already-open file.
+ * 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 readMipsElfAbiFlags = async (handle, metadata, checkCancelled) => {
+export const readMipsElfMetadata = async (handle, metadata, checkCancelled) => {
     checkCancelled();
     if (metadata.elfClass !== 32)
         return err("MIPS ABI record inspection currently supports ELF32 only");
@@ -34,17 +38,19 @@ export const readMipsElfAbiFlags = async (handle, metadata, checkCancelled) => {
     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 (bytes.toString("hex", 0, 4) !== "7f454c46" ||
-        bytes[4] !== 1 ||
-        bytes[5] !== (little ? 1 : 2) ||
+    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 (bytes[6] !== 1 || u32(bytes, 20) !== 1 || u16(bytes, 40) !== 52)
+    if (fixedHeader.value.headerSize !== 52)
         return err("invalid MIPS ELF32 version or header size");
     const tables = [
         {
@@ -77,7 +83,11 @@ export const readMipsElfAbiFlags = async (handle, metadata, checkCancelled) => {
     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)
@@ -98,11 +108,36 @@ export const readMipsElfAbiFlags = async (handle, metadata, checkCancelled) => {
         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;
-            if (u32(contents.value, position + table.typeOffset) !== table.recordType)
+            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}`);
@@ -119,8 +154,29 @@ export const readMipsElfAbiFlags = async (handle, metadata, checkCancelled) => {
             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, limitations });
+        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 = {
@@ -136,5 +192,10 @@ export const readMipsElfAbiFlags = async (handle, metadata, checkCancelled) => {
         flags1: u32(record, 16),
         flags2: u32(record, 20),
     };
-    return ok({ abiFlags, limitations });
+    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;