rea-agents 3.2.0 → 4.0.0

package/dist/native/parsers/lipo.js

@@ -52,7 +52,7 @@ export const parseLipoArchitectures = (output) => {
     return architectures;
 };
 const integer = (value) => {
-    if (value === undefined)
+    if (value === undefined || !/^\d+$/u.test(value))
         return null;
     const parsed = Number.parseInt(value, 10);
     return Number.isSafeInteger(parsed) && parsed >= 0 ? parsed : null;
@@ -60,8 +60,17 @@ const integer = (value) => {
 const alignment = (value) => {
     if (value === undefined)
         return null;
-    const exponent = /2\^(\d+)/u.exec(value)?.[1];
-    if (exponent !== undefined)
-        return 2 ** Number.parseInt(exponent, 10);
+    const exponent = /^2\^(\d+)(?: \((\d+)\))?$/u.exec(value);
+    const powerText = exponent?.[1];
+    if (powerText !== undefined) {
+        const power = Number.parseInt(powerText, 10);
+        if (power > 52)
+            return null;
+        const alignment = 2 ** power;
+        const reported = exponent?.[2];
+        return reported === undefined || integer(reported) === alignment
+            ? alignment
+            : null;
+    }
     return integer(value);
 };

package/dist/native/parsers/otool.js

@@ -1,11 +1,20 @@
+/**
+ * otool emits LF, but a capture replayed from another host or toolchain can
+ * carry CRLF. The section/command boundaries below match a bare `\n`, so a
+ * stray `\r` would swallow the terminator and silently empty `sections` while
+ * leaking section fields into the command. Normalizing once at the boundary
+ * keeps every parser below working on one line ending.
+ */
+const normalizeLineEndings = (output) => output.replaceAll("\r\n", "\n");
 /** Parse stable fields from `otool -l`, preserving unknown command fields. */
-export const parseOtoolLoadCommands = (output) => {
-    const headerTokens = parseHeaderTokens(output);
-    const state = createLoadCommandState(headerTokens);
+export const parseOtoolLoadCommands = (raw) => {
+    const output = normalizeLineEndings(raw);
+    const header = parseHeader(output);
+    const state = createLoadCommandState(header?.flags);
     for (const block of output.split(/(?=Load command \d+)/u))
         parseLoadCommand(block, state);
     return {
-        fileType: headerTokens?.[4] ?? null,
+        fileType: header?.fileType ?? null,
         flags: [...state.flags].sort(),
         uuid: state.uuid,
         commands: state.commands,
@@ -15,19 +24,42 @@ export const parseOtoolLoadCommands = (output) => {
         builds: state.builds,
     };
 };
-const parseHeaderTokens = (output) => output
-    .split(/\r?\n/u)
-    .map((line) => line.trim())
-    .find((line) => /^0x[a-fA-F0-9]+\s/u.test(line))
-    ?.split(/\s+/u);
-const createLoadCommandState = (headerTokens) => ({
+const parseHeader = (output) => {
+    const lines = output.split(/\r?\n/u).map((line) => line.trim());
+    const columnsLine = lines.findIndex((line) => /(?:^|\s)magic\s/u.test(line));
+    if (columnsLine < 0)
+        return undefined;
+    const columns = lines[columnsLine]?.split(/\s+/u);
+    const dataLine = lines.slice(columnsLine + 1).find((line) => line.length > 0);
+    const values = dataLine?.split(/\s+/u);
+    if (columns === undefined || values === undefined)
+        return undefined;
+    const fileTypeIndex = columns.indexOf("filetype");
+    const flagsIndex = columns.indexOf("flags");
+    const complete = values.length >= columns.length;
+    const fileTypeValueIndex = flagsIndex >= 0 && fileTypeIndex > flagsIndex
+        ? values.length - (columns.length - fileTypeIndex)
+        : fileTypeIndex;
+    const flagsEnd = flagsIndex >= 0 ? values.length - (columns.length - flagsIndex - 1) : 0;
+    return {
+        fileType: complete && fileTypeValueIndex >= 0 && fileTypeValueIndex < values.length
+            ? (values[fileTypeValueIndex] ?? null)
+            : null,
+        flags: !complete || flagsIndex < 0 || flagsIndex >= flagsEnd
+            ? []
+            : values
+                .slice(flagsIndex, flagsEnd)
+                .filter((value) => value.length > 0),
+    };
+};
+const createLoadCommandState = (headerFlags) => ({
     commands: [],
     segments: [],
     dependencies: [],
     entrypoints: [],
     builds: [],
     uuid: null,
-    flags: new Set(headerTokens?.slice(7) ?? []),
+    flags: new Set(headerFlags ?? []),
 });
 const parseLoadCommand = (block, state) => {
     const indexText = /^Load command (\d+)/u.exec(block)?.[1];
@@ -39,7 +71,6 @@ const parseLoadCommand = (block, state) => {
     state.commands.push({
         index: Number.parseInt(indexText, 10),
         kind,
-        file_offset: null,
         fields,
     });
     collectUuid(kind, fields, state);
@@ -47,7 +78,6 @@ const parseLoadCommand = (block, state) => {
     collectBuild(kind, block, fields, state);
     collectDependency(kind, fields, state);
     collectSegment(kind, block, fields, state);
-    collectFlags(fields, state.flags);
 };
 const collectUuid = (kind, fields, state) => {
     if (kind === "LC_UUID")
@@ -61,17 +91,28 @@ const collectEntrypoint = (kind, fields, state) => {
         state.entrypoints.push({ file_offset: entry });
 };
 const collectBuild = (kind, block, fields, state) => {
-    if (kind !== "LC_BUILD_VERSION")
+    if (kind === "LC_BUILD_VERSION") {
+        state.builds.push({
+            platform: stringField(fields, "platform"),
+            minimum_os: stringField(fields, "minos"),
+            sdk: stringField(fields, "sdk"),
+            tools: parseBuildTools(block),
+        });
         return;
-    state.builds.push({
-        platform: stringField(fields, "platform"),
-        minimum_os: stringField(fields, "minos"),
-        sdk: stringField(fields, "sdk"),
-        tools: parseBuildTools(block),
-    });
+    }
+    if (kind.startsWith("LC_VERSION_MIN_"))
+        state.builds.push({
+            platform: kind.slice("LC_VERSION_MIN_".length) || null,
+            minimum_os: stringField(fields, "version"),
+            sdk: stringField(fields, "sdk"),
+            tools: [],
+        });
 };
 const collectDependency = (kind, fields, state) => {
-    if (!kind.startsWith("LC_LOAD_") && kind !== "LC_ID_DYLIB")
+    if (!kind.startsWith("LC_LOAD_") &&
+        kind !== "LC_ID_DYLIB" &&
+        kind !== "LC_REEXPORT_DYLIB" &&
+        kind !== "LC_LAZY_LOAD_DYLIB")
         return;
     state.dependencies.push({
         path: stripOffsetSuffix(stringField(fields, "name")),
@@ -84,19 +125,15 @@ const collectSegment = (kind, block, fields, state) => {
     if (kind === "LC_SEGMENT" || kind === "LC_SEGMENT_64")
         state.segments.push(parseSegment(block, fields));
 };
-const collectFlags = (fields, flags) => {
-    const rawFlags = stringField(fields, "flags");
-    if (rawFlags === null)
-        return;
-    for (const flag of rawFlags.split(/\s+/u))
-        if (flag.length > 0)
-            flags.add(flag);
-};
 const parseFields = (block) => {
     const fields = {};
     for (const rawLine of block.split(/\r?\n/u).slice(1)) {
         const line = rawLine.trim();
-        const match = /^(\S+(?:\s+version)?)\s+(.+)$/u.exec(line);
+        // Keys are `token` or a compound `token version`. `time stamp` is the one
+        // other real key, and it must be matched as a whole: treating `stamp` as a
+        // generic suffix would swallow an install name such as
+        // `name stamp plugin.dylib`, hiding the dependency path behind `unknown`.
+        const match = /^((?:time stamp)|\S+(?:\s+version)?)\s+(.+)$/u.exec(line);
         if (match?.[1] === undefined || match[2] === undefined)
             continue;
         const value = match[2].trim();
@@ -125,7 +162,7 @@ const parseSections = (block) => block
         address: hexField(fields, "addr"),
         size: numberField(fields, "size"),
         file_offset: numberField(fields, "offset"),
-        alignment: sectionAlignment(numberField(fields, "align")),
+        alignment: sectionAlignment(stringField(fields, "align")),
         flags: (stringField(fields, "flags") ?? "")
             .split(/\s+/u)
             .filter((flag) => flag.length > 0),
@@ -148,9 +185,9 @@ const permissions = (raw) => {
     const numericValue = numeric(raw);
     if (numericValue !== null)
         return {
-            read: (numericValue & 4) !== 0,
+            read: (numericValue & 1) !== 0,
             write: (numericValue & 2) !== 0,
-            execute: (numericValue & 1) !== 0,
+            execute: (numericValue & 4) !== 0,
             raw,
         };
     if (/^[r-][w-][x-]$/u.test(raw))
@@ -162,11 +199,12 @@ const permissions = (raw) => {
         };
     return { read: null, write: null, execute: null, raw };
 };
+/** A whole decimal or hexadecimal integer literal, with no surrounding text. */
+const NUMERIC_PATTERN = /^(?:0x[a-fA-F0-9]+|\d+)$/u;
 const numeric = (value) => {
-    const token = value.split(/\s+/u)[0];
-    if (token === undefined || !/^(?:0x[a-fA-F0-9]+|\d+)$/u.test(token))
+    if (!NUMERIC_PATTERN.test(value))
         return null;
-    const parsed = Number.parseInt(token, token.startsWith("0x") ? 16 : 10);
+    const parsed = Number.parseInt(value, value.startsWith("0x") ? 16 : 10);
     return Number.isSafeInteger(parsed) && parsed >= 0 ? parsed : null;
 };
 const stringField = (fields, name) => {
@@ -186,8 +224,15 @@ const numberField = (fields, name) => {
             : null;
 };
 const hexField = (fields, name) => {
-    const value = numberField(fields, name);
-    return value === null ? null : `0x${value.toString(16)}`;
+    const value = stringField(fields, name);
+    if (value === null || !NUMERIC_PATTERN.test(value))
+        return null;
+    return `0x${BigInt(value).toString(16)}`;
 };
 const stripOffsetSuffix = (value) => value?.replace(/\s+\(offset\s+\d+\)$/u, "") ?? "unknown";
-const sectionAlignment = (exponent) => exponent === null || exponent > 52 ? null : 2 ** exponent;
+const sectionAlignment = (raw) => {
+    if (raw === null)
+        return null;
+    const exponent = numeric(/^2\^(\d+)(?:\s+\(\d+\))?$/u.exec(raw)?.[1] ?? raw);
+    return exponent === null || exponent > 52 ? null : 2 ** exponent;
+};

package/dist/native/parsers/plist.js

@@ -2,7 +2,8 @@ import { z } from "zod";
 const plistObject = z.record(z.string(), z.unknown());
 /** Parse plutil JSON output and project stable bundle metadata. */
 export const parsePlistJson = (output) => {
-    const value = JSON.parse(output);
+    // plutil output can carry a UTF-8 BOM, which JSON.parse rejects outright.
+    const value = JSON.parse(output.replace(/^\uFEFF/u, ""));
     const object = plistObject.safeParse(value);
     const field = (name) => {
         if (!object.success)

package/dist/process/ExecFileOutput.js

@@ -1,7 +1,11 @@
 import { execFile, } from "node:child_process";
 /** Run a shell-free command while capturing its complete UTF-8 output. */
 export const execFileOutput = (command, arguments_, options = {}) => new Promise((resolve, reject) => {
-    execFile(command, [...arguments_], { ...options, encoding: "utf8", maxBuffer: Number.POSITIVE_INFINITY }, (error, stdout, stderr) => {
+    execFile(command, [...arguments_], {
+        ...options,
+        encoding: "utf8",
+        maxBuffer: options.maxBuffer ?? Number.POSITIVE_INFINITY,
+    }, (error, stdout, stderr) => {
         if (error !== null) {
             reject(error);
             return;

package/dist/process/ProcessOwnership.js

@@ -48,14 +48,13 @@ export const parseProcessEnvironment = (value) => Object.fromEntries(value
     const separator = entry.indexOf("=");
     return [entry.slice(0, separator), entry.slice(separator + 1)];
 }));
-const systemHost = {
+/** Create the operating-system process inspector for an explicit host context. */
+export const createSystemProcessOwnershipHost = (platform = process.platform, hostEnvironment = process.env) => ({
+    platform,
     async listProcesses() {
-        if (process.platform === "win32")
+        if (platform === "win32")
             return [];
-        const { stdout } = await execFileOutput("ps", [
-            "-axo",
-            "pid=,ppid=,pgid=,stat=,command=",
-        ]);
+        const { stdout } = await execFileOutput("ps", ["-axo", "pid=,ppid=,pgid=,stat=,command="], { env: hostEnvironment });
         return stdout
             .split("\n")
             .map((line) => /\s*(\d+)\s+(\d+)\s+(\d+)\s+(\S+)\s+(.*)/u.exec(line))
@@ -69,22 +68,24 @@ const systemHost = {
         }));
     },
     async environment(pid) {
-        if (process.platform === "linux") {
+        if (platform === "linux")
             return parseProcessEnvironment(await readFile(`/proc/${pid}/environ`, "utf8"));
-        }
-        const { stdout } = await execFileOutput("ps", ["eww", "-p", String(pid)]);
-        const environment = {};
+        const { stdout } = await execFileOutput("ps", ["eww", "-p", String(pid)], {
+            env: hostEnvironment,
+        });
+        const observedEnvironment = {};
         for (const match of stdout.matchAll(/(?:^|\s)([A-Za-z_][A-Za-z0-9_]*)=([^\s]*)/gu)) {
             const name = match[1];
             if (name !== undefined)
-                environment[name] = match[2] ?? "";
+                observedEnvironment[name] = match[2] ?? "";
         }
-        return environment;
+        return observedEnvironment;
     },
     signalGroup(processGroupId, signal) {
         process.kill(-processGroupId, signal);
     },
-};
+});
+const systemHost = createSystemProcessOwnershipHost();
 const systemWindowsProcessTreeHost = {
     async terminateTree(rootPid) {
         try {
@@ -104,10 +105,13 @@ const systemWindowsProcessTreeHost = {
 export const readProcessRunId = async (pid, host = systemHost) => (await host.environment(pid)).REA_PROCESS_RUN_ID;
 /** Token-validate every rooted POSIX process group before signaling any. */
 export const cleanupOwnedProcessGroup = async (ownership, host = systemHost) => {
-    const processes = await readLiveProcessTable(host);
-    if (processes === undefined)
-        return { cleaned: false, reason: "process table could not be inspected" };
-    const plan = await createOwnedCleanupPlan(ownership, processes, host);
+    const processTable = await readLiveProcessTable(host);
+    if (!processTable.available)
+        return {
+            cleaned: false,
+            reason: `process table could not be inspected: ${processTable.reason}`,
+        };
+    const plan = await createOwnedCleanupPlan(ownership, processTable.processes, host);
     if ("cleaned" in plan)
         return plan;
     let signaled = false;
@@ -124,17 +128,23 @@ export const cleanupOwnedProcessGroup = async (ownership, host = systemHost) =>
         catch (cause) {
             const code = cause instanceof Error && "code" in cause ? cause.code : undefined;
             if (code !== "ESRCH")
-                return { cleaned: false, reason: "owned process group signal failed" };
+                return {
+                    cleaned: false,
+                    reason: `owned process group signal failed: ${errorMessage(cause)}`,
+                };
         }
     }
     return { cleaned: true, signaled };
 };
 /** Verify that no live process still carries an owned capture run token. */
 export const verifyNoTokenOwnedProcesses = async (runId, host = systemHost) => {
-    const processes = await readLiveProcessTable(host);
-    if (processes === undefined)
-        return { cleaned: false, reason: "process table could not be inspected" };
-    const scan = await scanTokenOwnedProcesses(processes, runId, host);
+    const processTable = await readLiveProcessTable(host);
+    if (!processTable.available)
+        return {
+            cleaned: false,
+            reason: `process table could not be inspected: ${processTable.reason}`,
+        };
+    const scan = await scanTokenOwnedProcesses(processTable.processes, runId, host);
     if (scan.failures.length > 0)
         return cleanupValidationFailure(scan.failures);
     return scan.owned.length === 0
@@ -143,10 +153,13 @@ export const verifyNoTokenOwnedProcesses = async (runId, host = systemHost) => {
 };
 const readLiveProcessTable = async (host) => {
     try {
-        return liveProcesses(await host.listProcesses());
+        return {
+            available: true,
+            processes: liveProcesses(await host.listProcesses()),
+        };
     }
-    catch {
-        return undefined;
+    catch (cause) {
+        return { available: false, reason: errorMessage(cause) };
     }
 };
 const createOwnedCleanupPlan = async (ownership, processes, host) => {
@@ -201,10 +214,10 @@ const revalidateOwnedProcessGroup = async (processGroupId, ownership, host) => {
     try {
         members = liveProcesses(await host.listProcesses()).filter(({ processGroupId: observedGroupId }) => observedGroupId === processGroupId);
     }
-    catch {
+    catch (cause) {
         return {
             cleaned: false,
-            reason: "process ownership could not be revalidated",
+            reason: `process ownership could not be revalidated: ${errorMessage(cause)}`,
         };
     }
     const failures = await processOwnershipFailures(members, ownership.runId, host);
@@ -242,14 +255,25 @@ const processOwnershipFailures = async (members, runId, host) => {
             if ((await host.environment(member.pid)).REA_PROCESS_RUN_ID !== runId)
                 failures.push({ pid: member.pid, reason: "run-token-mismatch" });
         }
-        catch {
+        catch (cause) {
             try {
                 const live = liveProcesses(await host.listProcesses());
                 if (!live.some(({ pid }) => pid === member.pid))
                     continue;
             }
-            catch { }
-            failures.push({ pid: member.pid, reason: "environment-unreadable" });
+            catch (recheckCause) {
+                failures.push({
+                    pid: member.pid,
+                    reason: "environment-unreadable",
+                    diagnostic: `${errorMessage(cause)}; process liveness recheck failed: ${errorMessage(recheckCause)}`,
+                });
+                continue;
+            }
+            failures.push({
+                pid: member.pid,
+                reason: "environment-unreadable",
+                diagnostic: errorMessage(cause),
+            });
         }
     }
     return failures;
@@ -262,18 +286,30 @@ const scanTokenOwnedProcesses = async (processes, runId, host) => {
             if ((await host.environment(process.pid)).REA_PROCESS_RUN_ID === runId)
                 owned.push(process);
         }
-        catch {
+        catch (cause) {
             try {
                 const live = liveProcesses(await host.listProcesses());
                 if (!live.some(({ pid }) => pid === process.pid))
                     continue;
             }
-            catch { }
-            failures.push({ pid: process.pid, reason: "environment-unreadable" });
+            catch (recheckCause) {
+                failures.push({
+                    pid: process.pid,
+                    reason: "environment-unreadable",
+                    diagnostic: `${errorMessage(cause)}; process liveness recheck failed: ${errorMessage(recheckCause)}`,
+                });
+                continue;
+            }
+            failures.push({
+                pid: process.pid,
+                reason: "environment-unreadable",
+                diagnostic: errorMessage(cause),
+            });
         }
     }
     return { owned, failures };
 };
+const errorMessage = (cause) => cause instanceof Error ? cause.message : String(cause);
 /** Observe one group without signaling it, failing closed on identity doubt. */
 export const observeOwnedProcessGroup = async (ownership, host = systemHost) => observeOwnedProcessGroupWithHost(ownership, host);
 /**

package/dist/process/ProcessOwnershipObservation.js

@@ -6,10 +6,10 @@ export const observeOwnedProcessGroupWithHost = async (ownership, host) => {
     try {
         members = (await host.listProcesses()).filter(({ processGroupId }) => processGroupId === ownership.processGroupId);
     }
-    catch {
+    catch (cause) {
         return {
             state: "unverifiable",
-            reason: "process group could not be inspected",
+            reason: `process group could not be inspected: ${errorMessage(cause)}`,
         };
     }
     const liveMembers = liveProcesses(members);
@@ -24,11 +24,13 @@ export const observeOwnedProcessGroupWithHost = async (ownership, host) => {
                     reason: "process ownership did not match",
                 };
         }
-        catch {
-            return {
-                state: "unverifiable",
-                reason: "process ownership could not be revalidated",
-            };
+        catch (cause) {
+            if (!(await processIsGone(host, member.pid))) {
+                return {
+                    state: "unverifiable",
+                    reason: `process ownership could not be revalidated for PID ${member.pid}: ${errorMessage(cause)}`,
+                };
+            }
         }
     }
     return { state: "alive" };
@@ -39,8 +41,8 @@ export const observeOwnedProcessLineageWithHost = async (ownership, host) => {
     try {
         processes = liveProcesses(await host.listProcesses());
     }
-    catch {
-        return unavailableLineage(ownership, "process table could not be inspected");
+    catch (cause) {
+        return unavailableLineage(ownership, `process table could not be inspected: ${errorMessage(cause)}`);
     }
     const launcher = processes.find(({ pid }) => pid === ownership.leaderPid);
     if (launcher === undefined)
@@ -49,14 +51,22 @@ export const observeOwnedProcessLineageWithHost = async (ownership, host) => {
     if (identityFailure !== null)
         return unavailableLineage(ownership, identityFailure);
     const descendants = descendantsOf(launcher.pid, processes);
+    const verifiedDescendants = [];
     for (const member of [launcher, ...descendants]) {
         try {
             if ((await host.environment(member.pid)).REA_PROCESS_RUN_ID !==
                 ownership.runId)
                 return unavailableLineage(ownership, "process lineage contains an unowned or PID-reused process");
+            if (member.pid !== launcher.pid)
+                verifiedDescendants.push(member);
         }
-        catch {
-            return unavailableLineage(ownership, "process ownership could not be revalidated");
+        catch (cause) {
+            if (await processIsGone(host, member.pid)) {
+                if (member.pid === launcher.pid)
+                    return unavailableLineage(ownership, "owned launcher exited during lineage validation");
+                continue;
+            }
+            return unavailableLineage(ownership, `process ownership could not be revalidated for PID ${member.pid}: ${errorMessage(cause)}`);
         }
     }
     return {
@@ -67,7 +77,7 @@ export const observeOwnedProcessLineageWithHost = async (ownership, host) => {
             launcherPid: launcher.pid,
             launcherParentPid: launcher.parentPid,
             processGroupId: launcher.processGroupId,
-            descendants: descendants
+            descendants: verifiedDescendants
                 .sort((left, right) => left.pid - right.pid)
                 .map(({ pid, parentPid, processGroupId }) => ({
                 pid,
@@ -85,3 +95,12 @@ const unavailableLineage = (ownership, reason) => ({
     processGroupId: ownership.processGroupId,
     reason,
 });
+const processIsGone = async (host, pid) => {
+    try {
+        return !liveProcesses(await host.listProcesses()).some((process) => process.pid === pid);
+    }
+    catch {
+        return false;
+    }
+};
+const errorMessage = (cause) => cause instanceof Error ? cause.message : String(cause);

package/dist/process/ProviderProcess.js

@@ -8,14 +8,16 @@ const DEFAULT_KILL_GRACE_MS = 1_000;
  * selecting provider-specific command arguments or environment values.
  */
 export const spawnOwnedProviderProcess = async (options) => {
+    const platform = options.platform ?? process.platform;
+    const hostEnvironment = options.hostEnvironment ?? process.env;
     const child = spawn(options.command, [...options.arguments], {
         shell: false,
         windowsHide: true,
         stdio: ["ignore", "pipe", "pipe"],
-        detached: process.platform !== "win32",
+        detached: platform !== "win32",
         windowsVerbatimArguments: options.windowsVerbatimArguments ?? false,
         env: {
-            ...process.env,
+            ...hostEnvironment,
             ...options.env,
             REA_PROCESS_RUN_ID: options.runId,
         },