rea-agents 6.3.0 → 6.5.0

package/dist/process/ProcessOwnership.js

@@ -3,6 +3,8 @@ import { promisify } from "node:util";
 import { errorMessage, systemProcessOwnershipHost as systemHost, } from "./ProcessOwnershipObservation.js";
 import { launcherIdentityFailure } from "./ProcessOwnershipIdentity.js";
 import { descendantsOf, liveProcesses } from "./ProcessOwnershipProcessTree.js";
+import { readProcessRunTokens } from "./ProcessRunTokenObservations.js";
+import { compareUnicodeCodePoints } from "../domain/unicodeCodePointOrder.js";
 const execFileAsync = promisify(execFile);
 /**
  * Terminate one Windows process tree through the platform utility.
@@ -41,7 +43,11 @@ const systemWindowsProcessTreeHost = {
     },
 };
 /** Read the capture run token currently exposed by one live process. */
-export const readProcessRunId = async (pid, host = systemHost) => (await host.environment(pid)).REA_PROCESS_RUN_ID;
+export const readProcessRunId = async (pid, host = systemHost, signal) => (await host.environment(pid, signal)).REA_PROCESS_RUN_ID;
+/** Keep unrelated-process uncertainty attached to every outcome of this cleanup attempt. */
+const withUnverifiedObservations = (result, unverified) => unverified.length === 0 || (result.unverified?.length ?? 0) > 0
+    ? result
+    : { ...result, unverified };
 /** Token-validate every rooted POSIX process group before signaling any. */
 export const cleanupOwnedProcessGroup = async (ownership, host = systemHost) => {
     const processTable = await readLiveProcessTable(host);
@@ -56,8 +62,16 @@ export const cleanupOwnedProcessGroup = async (ownership, host = systemHost) =>
     let signaled = false;
     for (const processGroupId of plan.signalOrder) {
         const revalidation = await revalidateOwnedProcessGroup(processGroupId, ownership, host, plan.tokenOwnedIdentities);
-        if ("cleaned" in revalidation)
-            return revalidation;
+        if ("cleaned" in revalidation) {
+            if (!revalidation.cleaned)
+                return withUnverifiedObservations(revalidation, plan.unverified);
+            return {
+                ...revalidation,
+                ...(revalidation.unverified?.length || plan.unverified.length === 0
+                    ? {}
+                    : { unverified: plan.unverified }),
+            };
+        }
         if (revalidation.empty)
             continue;
         try {
@@ -67,10 +81,10 @@ export const cleanupOwnedProcessGroup = async (ownership, host = systemHost) =>
         catch (cause) {
             const code = cause instanceof Error && "code" in cause ? cause.code : undefined;
             if (code !== "ESRCH")
-                return {
+                return withUnverifiedObservations({
                     cleaned: false,
                     reason: `owned process group signal failed: ${errorMessage(cause)}`,
-                };
+                }, plan.unverified);
         }
     }
     if (plan.unresolved.length > 0)
@@ -115,7 +129,38 @@ const readLiveProcessTable = async (host) => {
         return { available: false, reason: errorMessage(cause) };
     }
 };
-const createOwnedCleanupPlan = async (ownership, processes, host) => {
+// A process-table read can race exit and retain the old state with an altered
+// command. Only a fresh table proving that PID is no longer live can settle
+// that mismatch; surviving group members still require normal token checks.
+const settleLauncherExit = async (ownership, processes, host) => {
+    const launcher = processes.find(({ pid }) => pid === ownership.leaderPid);
+    if (launcher === undefined)
+        return processes;
+    const reason = launcherIdentityFailure(launcher, ownership);
+    if (reason === null)
+        return processes;
+    const refreshed = await readLiveProcessTable(host);
+    if (refreshed.available &&
+        !refreshed.processes.some(({ pid }) => pid === launcher.pid)) {
+        // Refreshing must not discard a surviving detached descendant's lineage,
+        // including a child that changed groups while the launcher exited.
+        const descendants = descendantsOf([launcher.pid], processes);
+        const descendantPids = new Set(descendants.map(({ pid }) => pid));
+        const descendantGroupIds = new Set(descendants.map(({ processGroupId }) => processGroupId));
+        const refreshedDescendantPids = new Set(descendantsOf(descendants.map(({ pid }) => pid), refreshed.processes).map(({ pid }) => pid));
+        if (refreshed.processes.some((process) => process.processGroupId !== ownership.processGroupId &&
+            (refreshedDescendantPids.has(process.pid) ||
+                descendantPids.has(process.pid) ||
+                descendantGroupIds.has(process.processGroupId))))
+            return { cleaned: false, reason };
+        return refreshed.processes;
+    }
+    return { cleaned: false, reason };
+};
+const createOwnedCleanupPlan = async (ownership, initialProcesses, host) => {
+    const processes = await settleLauncherExit(ownership, initialProcesses, host);
+    if ("cleaned" in processes)
+        return processes;
     const sampledProcessGroupIds = new Set((ownership.sampledProcessGroupIds ?? []).filter((processGroupId) => Number.isSafeInteger(processGroupId) && processGroupId > 0));
     const tokenOwned = ownership.sweepTokenOwnedProcesses === true
         ? await scanTokenOwnedProcesses(processes, ownership.runId, host, ownership.captureBaseline, {
@@ -149,10 +194,7 @@ const createOwnedCleanupPlan = async (ownership, processes, host) => {
             };
     let descendants = [];
     if (launcher !== undefined) {
-        const identityFailure = launcherIdentityFailure(launcher, ownership);
-        if (identityFailure !== null)
-            return { cleaned: false, reason: identityFailure };
-        descendants = descendantsOf(launcher.pid, processes);
+        descendants = descendantsOf([launcher.pid], processes);
     }
     const descendantPids = new Set(descendants.map(({ pid }) => pid));
     const processGroupIds = new Set([ownership.processGroupId]);
@@ -193,8 +235,8 @@ const createOwnedCleanupPlan = async (ownership, processes, host) => {
                 diagnostic: "sampled process-group leader identity could not be verified",
             })));
         const scanFailures = tokenOwned.failures.filter(({ pid }) => members.some((member) => member.pid === pid));
-        if (failures.length > 0)
-            unresolved.push(...failures);
+        for (const failure of failures)
+            mergeProcessOwnershipFailure(unresolved, failure);
         if (failures.length === 0 &&
             scanFailures.length === 0 &&
             !unverifiableSampledGroups.has(processGroupId))
@@ -215,10 +257,33 @@ const createOwnedCleanupPlan = async (ownership, processes, host) => {
         unverified: tokenOwned.unverified,
     };
 };
+/** Keep one current, most useful ownership diagnosis for each live PID. */
+const mergeProcessOwnershipFailure = (failures, next) => {
+    const index = failures.findIndex(({ pid }) => pid === next.pid);
+    if (index < 0) {
+        failures.push(next);
+        return;
+    }
+    const previous = failures[index];
+    if (previous !== undefined &&
+        ownershipFailurePriority(next.reason) >=
+            ownershipFailurePriority(previous.reason))
+        failures[index] = next;
+};
+const ownershipFailurePriority = (reason) => reason === "run-token-mismatch"
+    ? 3
+    : reason === "process-identity-unavailable"
+        ? 2
+        : reason === "environment-unreadable"
+            ? 1
+            : 0;
 const revalidateOwnedProcessGroup = async (processGroupId, ownership, host, expectedIdentities) => {
     let members;
     try {
-        members = liveProcesses(await host.listProcesses()).filter(({ processGroupId: observedGroupId }) => observedGroupId === processGroupId);
+        const processes = await settleLauncherExit(ownership, liveProcesses(await host.listProcesses()), host);
+        if ("cleaned" in processes)
+            return processes;
+        members = processes.filter(({ processGroupId: observedGroupId }) => observedGroupId === processGroupId);
     }
     catch (cause) {
         return {
@@ -229,14 +294,6 @@ const revalidateOwnedProcessGroup = async (processGroupId, ownership, host, expe
     const failures = await processOwnershipFailures(members, ownership.runId, host, expectedIdentities);
     if (failures.length > 0)
         return cleanupValidationFailure(failures);
-    if (processGroupId === ownership.processGroupId) {
-        const launcher = members.find(({ pid }) => pid === ownership.leaderPid);
-        if (launcher !== undefined) {
-            const identityFailure = launcherIdentityFailure(launcher, ownership);
-            if (identityFailure !== null)
-                return { cleaned: false, reason: identityFailure };
-        }
-    }
     if (processGroupId !== ownership.processGroupId &&
         members.length > 0 &&
         !members.some(({ pid }) => pid === processGroupId) &&
@@ -253,7 +310,13 @@ const cleanupValidationFailure = (failures, unverified = []) => {
     if (failures.some(({ reason }) => reason === "run-token-mismatch"))
         return {
             cleaned: false,
-            reason: "process tree contains an unowned or PID-reused process",
+            reason: `process ownership token mismatch for PID(s): ${[
+                ...new Set(failures
+                    .filter(({ reason }) => reason === "run-token-mismatch")
+                    .map(({ pid }) => pid)),
+            ]
+                .sort((left, right) => left - right)
+                .join(", ")}`,
             failures,
             ...unverifiedEntry,
         };
@@ -271,12 +334,12 @@ const cleanupValidationFailure = (failures, unverified = []) => {
             counts.set(category, (counts.get(category) ?? 0) + 1);
         }
         const breakdown = [...counts]
-            .sort(([left], [right]) => left.localeCompare(right))
+            .sort(([left], [right]) => compareUnicodeCodePoints(left, right))
             .map(([category, count]) => `${category}=${String(count)}`)
             .join(", ");
         const candidates = unreadable
             .map(({ pid, diagnostic }) => `${String(pid)}=${sanitizedTokenReadFailure(diagnostic)}`)
-            .sort((left, right) => left.localeCompare(right));
+            .sort((left, right) => compareUnicodeCodePoints(left, right));
         return {
             cleaned: false,
             reason: `process ownership token could not be read for ${String(unreadable.length)} live process(es): ${breakdown}; live candidates ${candidates.join(", ")}`,
@@ -296,6 +359,8 @@ const sanitizedTokenReadFailure = (diagnostic) => {
         return diagnostic;
     if (diagnostic === "platform_binary_environment_withheld")
         return diagnostic;
+    if (diagnostic === "restricted_process_environment_withheld")
+        return diagnostic;
     const environmentErrno = /^(EACCES|EPERM|ENOENT|ESRCH):/u.exec(diagnostic ?? "");
     if (environmentErrno?.[1] !== undefined)
         return `environment_errno_${environmentErrno[1]}`;
@@ -328,53 +393,29 @@ const processOwnershipFailures = async (members, runId, host, expectedIdentities
     if (expectedIdentities.size > 0 && host.processIdentities !== undefined) {
         const expectedMembers = members.filter(({ pid }) => expectedIdentities.has(pid));
         const observed = await host.processIdentities(expectedMembers);
+        const identityFailures = [];
         for (const member of expectedMembers) {
             const expected = expectedIdentities.get(member.pid);
             const current = observed.get(member.pid);
             if (expected === null ||
                 current?.state !== "readable" ||
                 current.identity !== expected) {
-                if (await processIsGone(host, member.pid))
-                    continue;
-                failures.push({
+                identityFailures.push({
                     pid: member.pid,
                     reason: "process-identity-unavailable",
                     diagnostic: "process identity changed or became unavailable before signal",
                 });
             }
         }
+        failures.push(...(await recheckOwnershipFailures(identityFailures, host)));
     }
-    for (const member of members) {
-        try {
-            if ((await host.environment(member.pid)).REA_PROCESS_RUN_ID !== runId)
-                failures.push({ pid: member.pid, reason: "run-token-mismatch" });
-        }
-        catch (cause) {
-            try {
-                const live = liveProcesses(await host.listProcesses());
-                if (!live.some(({ pid }) => pid === member.pid))
-                    continue;
-            }
-            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),
-            });
-        }
-    }
+    failures.push(...(await processRunTokenFailures(members, runId, host)));
     if (failures.length === 0 &&
         expectedIdentities.size > 0 &&
         host.processIdentities !== undefined) {
         const expectedMembers = members.filter(({ pid }) => expectedIdentities.has(pid));
         const observed = await host.processIdentities(expectedMembers);
+        const identityFailures = [];
         for (const member of expectedMembers) {
             const expected = expectedIdentities.get(member.pid);
             const current = observed.get(member.pid);
@@ -382,35 +423,83 @@ const processOwnershipFailures = async (members, runId, host, expectedIdentities
                 current?.state === "readable" &&
                 current.identity === expected)
                 continue;
-            if (await processIsGone(host, member.pid))
-                continue;
-            failures.push({
+            identityFailures.push({
                 pid: member.pid,
                 reason: "process-identity-unavailable",
                 diagnostic: "process identity changed or became unavailable during token validation",
             });
         }
+        failures.push(...(await recheckOwnershipFailures(identityFailures, host)));
     }
     return failures;
 };
+const processRunTokenFailures = async (members, runId, host) => {
+    const failures = [];
+    for await (const { process: member, observation } of readProcessRunTokens(host, members)) {
+        if (observation.state === "readable") {
+            if (observation.runId !== runId)
+                failures.push({ pid: member.pid, reason: "run-token-mismatch" });
+            continue;
+        }
+        failures.push({
+            pid: member.pid,
+            reason: "environment-unreadable",
+            diagnostic: observation.reason,
+        });
+    }
+    return recheckOwnershipFailures(failures, host);
+};
+/**
+ * Take a fresh liveness snapshot after each ownership-read phase. Only an
+ * absent PID resolves an unreadable observation; a readable token mismatch
+ * remains a failure. Never reuse this snapshot across identity/token reads.
+ */
+const recheckOwnershipFailures = async (failures, host) => {
+    if (!failures.some(({ reason }) => reason !== "run-token-mismatch"))
+        return failures;
+    try {
+        let processes = await host.listProcesses();
+        const isDarwin = (host.platform ?? process.platform) === "darwin";
+        for (let attempt = 0; isDarwin &&
+            attempt < TOKEN_READ_RETRY_ATTEMPTS &&
+            processes.some(({ pid, state }) => failures.some((failure) => failure.pid === pid && failure.reason !== "run-token-mismatch") && state.slice(1).includes("E")); attempt += 1) {
+            await new Promise((resolve) => setTimeout(resolve, TOKEN_READ_RETRY_DELAY_MS));
+            processes = await host.listProcesses();
+        }
+        const live = new Set(liveProcesses(processes).map(({ pid }) => pid));
+        return failures.filter(({ pid, reason }) => reason === "run-token-mismatch" || live.has(pid));
+    }
+    catch (cause) {
+        return failures.map((failure) => failure.reason === "run-token-mismatch"
+            ? failure
+            : {
+                ...failure,
+                diagnostic: `${failure.diagnostic}; process liveness recheck failed: ${errorMessage(cause)}`,
+            });
+    }
+};
 const TOKEN_READ_RETRY_ATTEMPTS = 3;
 const TOKEN_READ_RETRY_DELAY_MS = 40;
 /** Darwin reports this when the kernel withholds a platform binary's environment. */
 const PLATFORM_BINARY_ENVIRONMENT_WITHHELD = "platform_binary_environment_withheld";
+/** Darwin reports this when the kernel withholds a restricted process environment. */
+const RESTRICTED_PROCESS_ENVIRONMENT_WITHHELD = "restricted_process_environment_withheld";
 const currentProcessUid = () => typeof process.getuid === "function" ? process.getuid() : undefined;
 /**
  * Whether the operating system provably withheld this candidate's run token:
- * current macOS omits the environment of Apple platform binaries from
- * KERN_PROCARGS2 and fails with EINVAL for processes owned by another
- * account, and neither class can be token-verified by any caller. Such a
- * candidate is recorded as unverified instead of failing an otherwise clean
- * capture; every other unreadable candidate stays fail-closed.
+ * current macOS omits the environment of Apple platform binaries and
+ * CS_RESTRICT processes from KERN_PROCARGS2, and fails with EINVAL for
+ * processes owned by another account. These classes cannot be token-verified
+ * by this caller. An unrelated candidate is recorded as unverified instead
+ * of failing an otherwise clean capture; every related or otherwise
+ * unreadable candidate stays fail-closed.
  */
 const environmentWithheldFromInspection = (entry, diagnostic) => {
     const uid = currentProcessUid();
     if (uid !== undefined && entry.uid !== undefined && entry.uid !== uid)
         return true;
-    return diagnostic === PLATFORM_BINARY_ENVIRONMENT_WITHHELD;
+    return (diagnostic === PLATFORM_BINARY_ENVIRONMENT_WITHHELD ||
+        diagnostic === RESTRICTED_PROCESS_ENVIRONMENT_WITHHELD);
 };
 const scanTokenOwnedProcesses = async (processes, runId, host, captureBaseline, relation) => {
     let candidates = processes;
@@ -433,18 +522,19 @@ const scanTokenOwnedProcesses = async (processes, runId, host, captureBaseline,
     const failures = [];
     if (captureBaseline !== undefined && host.processIdentities !== undefined) {
         const stableCandidates = [];
+        const identityFailures = [];
         for (const process of candidates) {
             if (candidateIdentities.get(process.pid)?.state === "readable") {
                 stableCandidates.push(process);
                 continue;
             }
-            if (!(await processIsGone(host, process.pid)))
-                failures.push({
-                    pid: process.pid,
-                    reason: "process-identity-unavailable",
-                    diagnostic: "process identity was unavailable during token scan",
-                });
+            identityFailures.push({
+                pid: process.pid,
+                reason: "process-identity-unavailable",
+                diagnostic: "process identity was unavailable during token scan",
+            });
         }
+        failures.push(...(await recheckOwnershipFailures(identityFailures, host)));
         candidates = stableCandidates;
     }
     const owned = [];
@@ -454,35 +544,21 @@ const scanTokenOwnedProcesses = async (processes, runId, host, captureBaseline,
         const identity = candidateIdentities.get(process.pid);
         ownedIdentities.set(process.pid, identity?.state === "readable" ? identity.identity : null);
     };
-    let bulkTokens;
-    if (host.runTokens !== undefined)
-        bulkTokens = await host.runTokens(candidates);
     const unreadable = [];
-    for (const process of candidates) {
-        const bulkToken = bulkTokens?.get(process.pid);
-        if (bulkToken !== undefined) {
-            if (bulkToken.state === "readable") {
-                if (bulkToken.runId === runId)
-                    recordOwned(process);
-                continue;
-            }
-            unreadable.push({ process, diagnostic: bulkToken.reason });
-            continue;
-        }
-        try {
-            if ((await host.environment(process.pid)).REA_PROCESS_RUN_ID === runId)
+    for await (const { process, observation } of readProcessRunTokens(host, candidates)) {
+        if (observation.state === "readable") {
+            if (observation.runId === runId)
                 recordOwned(process);
         }
-        catch (cause) {
-            unreadable.push({ process, diagnostic: errorMessage(cause) });
-        }
+        else
+            unreadable.push({ process, diagnostic: observation.reason });
     }
     const remaining = await settleUnreadableTokenCandidates(unreadable, runId, host, recordOwned);
     const relatedPids = new Set();
     const relatedGroupIds = new Set();
     if (relation !== undefined) {
         relatedPids.add(relation.leaderPid);
-        for (const descendant of descendantsOf(relation.leaderPid, processes))
+        for (const descendant of descendantsOf([relation.leaderPid], processes))
             relatedPids.add(descendant.pid);
         relatedGroupIds.add(relation.processGroupId);
         for (const processGroupId of relation.sampledProcessGroupIds ?? [])
@@ -533,6 +609,7 @@ const scanTokenOwnedProcesses = async (processes, runId, host, captureBaseline,
     if (candidates.length > 0 && host.processIdentities !== undefined) {
         const afterRead = await host.processIdentities(candidates);
         const stillOwned = [];
+        const identityFailures = [];
         const ownedPids = new Set(owned.map(({ pid }) => pid));
         for (const process of candidates) {
             const before = candidateIdentities.get(process.pid);
@@ -544,14 +621,13 @@ const scanTokenOwnedProcesses = async (processes, runId, host, captureBaseline,
                     stillOwned.push(process);
                 continue;
             }
-            if (await processIsGone(host, process.pid))
-                continue;
-            failures.push({
+            identityFailures.push({
                 pid: process.pid,
                 reason: "process-identity-unavailable",
                 diagnostic: "process identity changed or became unavailable during token validation",
             });
         }
+        failures.push(...(await recheckOwnershipFailures(identityFailures, host)));
         return {
             owned: stillOwned,
             failures,
@@ -579,29 +655,18 @@ const settleUnreadableTokenCandidates = async (pending, runId, host, recordOwned
             void cause;
             live = undefined;
         }
-        let observations;
-        if (host.runTokens !== undefined) {
-            try {
-                observations = await host.runTokens(remaining.map(({ process }) => process));
-            }
-            catch (cause) {
-                void cause;
-                observations = undefined;
-            }
-        }
         const stillUnreadable = [];
-        for (const candidate of remaining) {
-            const pid = candidate.process.pid;
-            if (live !== undefined && !live.has(pid))
-                continue;
-            const observation = observations?.get(pid) ?? (await readEnvironmentRunToken(host, pid));
+        const candidates = remaining
+            .map(({ process }) => process)
+            .filter(({ pid }) => live === undefined || live.has(pid));
+        for await (const { process, observation } of readProcessRunTokens(host, candidates)) {
             if (observation.state === "readable") {
                 if (observation.runId === runId)
-                    recordOwned(candidate.process);
+                    recordOwned(process);
                 continue;
             }
             stillUnreadable.push({
-                process: candidate.process,
+                process,
                 diagnostic: observation.reason,
             });
         }
@@ -609,23 +674,3 @@ const settleUnreadableTokenCandidates = async (pending, runId, host, recordOwned
     }
     return remaining;
 };
-const readEnvironmentRunToken = async (host, pid) => {
-    try {
-        return {
-            state: "readable",
-            runId: (await host.environment(pid)).REA_PROCESS_RUN_ID,
-        };
-    }
-    catch (cause) {
-        return { state: "unavailable", reason: errorMessage(cause) };
-    }
-};
-const processIsGone = async (host, pid) => {
-    try {
-        return !liveProcesses(await host.listProcesses()).some((process) => process.pid === pid);
-    }
-    catch (cause) {
-        void cause;
-        return false;
-    }
-};