rea-agents 5.0.0 → 6.0.0

package/dist/process/ProcessOwnership.js

@@ -1,6 +1,6 @@
 import { execFile } from "node:child_process";
 import { promisify } from "node:util";
-import { createSystemProcessOwnershipHost, errorMessage, } from "./ProcessOwnershipObservation.js";
+import { errorMessage, systemProcessOwnershipHost as systemHost, } from "./ProcessOwnershipObservation.js";
 import { launcherIdentityFailure } from "./ProcessOwnershipIdentity.js";
 import { descendantsOf, liveProcesses } from "./ProcessOwnershipProcessTree.js";
 const execFileAsync = promisify(execFile);
@@ -28,7 +28,6 @@ export const cleanupWindowsProcessTree = async (rootPid, host = systemWindowsPro
         };
     }
 };
-const systemHost = createSystemProcessOwnershipHost();
 const systemWindowsProcessTreeHost = {
     async terminateTree(rootPid) {
         try {
@@ -59,7 +58,7 @@ export const cleanupOwnedProcessGroup = async (ownership, host = systemHost) =>
         return plan;
     let signaled = false;
     for (const processGroupId of plan.signalOrder) {
-        const revalidation = await revalidateOwnedProcessGroup(processGroupId, ownership, host);
+        const revalidation = await revalidateOwnedProcessGroup(processGroupId, ownership, host, plan.tokenOwnedIdentities);
         if ("cleaned" in revalidation)
             return revalidation;
         if (revalidation.empty)
@@ -77,17 +76,19 @@ export const cleanupOwnedProcessGroup = async (ownership, host = systemHost) =>
                 };
         }
     }
+    if (plan.unresolved.length > 0)
+        return cleanupValidationFailure(plan.unresolved);
     return { cleaned: true, signaled };
 };
 /** Verify that no live process still carries an owned capture run token. */
-export const verifyNoTokenOwnedProcesses = async (runId, host = systemHost) => {
+export const verifyNoTokenOwnedProcesses = async (runId, host = systemHost, captureBaseline) => {
     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);
+    const scan = await scanTokenOwnedProcesses(processTable.processes, runId, host, captureBaseline);
     if (scan.failures.length > 0)
         return cleanupValidationFailure(scan.failures);
     return scan.owned.length === 0
@@ -106,18 +107,24 @@ const readLiveProcessTable = async (host) => {
     }
 };
 const createOwnedCleanupPlan = async (ownership, processes, host) => {
+    const sampledProcessGroupIds = new Set((ownership.sampledProcessGroupIds ?? []).filter((processGroupId) => Number.isSafeInteger(processGroupId) && processGroupId > 0));
     const tokenOwned = ownership.sweepTokenOwnedProcesses === true
-        ? await scanTokenOwnedProcesses(processes, ownership.runId, host)
-        : { owned: [], failures: [] };
-    if (tokenOwned.failures.length > 0)
-        return cleanupValidationFailure(tokenOwned.failures);
+        ? await scanTokenOwnedProcesses(processes, ownership.runId, host, ownership.captureBaseline)
+        : { owned: [], failures: [], identities: new Map() };
     const tokenOwnedGroupIds = new Set(tokenOwned.owned.map(({ processGroupId }) => processGroupId));
     const launcher = processes.find(({ pid }) => pid === ownership.leaderPid);
     const rootMembers = processes.filter(({ processGroupId }) => processGroupId === ownership.processGroupId);
     if (launcher === undefined &&
         rootMembers.length === 0 &&
-        tokenOwned.owned.length === 0)
-        return { cleaned: true, signaled: false };
+        tokenOwned.owned.length === 0 &&
+        !processes.some(({ processGroupId }) => sampledProcessGroupIds.has(processGroupId)))
+        return tokenOwned.failures.length > 0
+            ? {
+                signalOrder: [],
+                tokenOwnedIdentities: tokenOwned.identities,
+                unresolved: tokenOwned.failures,
+            }
+            : { cleaned: true, signaled: false };
     let descendants = [];
     if (launcher !== undefined) {
         const identityFailure = launcherIdentityFailure(launcher, ownership);
@@ -131,28 +138,61 @@ const createOwnedCleanupPlan = async (ownership, processes, host) => {
         processGroupIds.add(descendant.processGroupId);
     for (const process of tokenOwned.owned)
         processGroupIds.add(process.processGroupId);
+    for (const processGroupId of sampledProcessGroupIds)
+        processGroupIds.add(processGroupId);
+    const signalableGroups = new Set();
+    const unresolved = [...tokenOwned.failures];
+    const unverifiableSampledGroups = new Set();
     for (const processGroupId of processGroupIds) {
         if (processGroupId === ownership.processGroupId)
             continue;
         const groupLeader = processes.find(({ pid, processGroupId: observedGroupId }) => pid === processGroupId && observedGroupId === processGroupId);
         if ((groupLeader === undefined || !descendantPids.has(groupLeader.pid)) &&
-            !tokenOwnedGroupIds.has(processGroupId))
+            !tokenOwnedGroupIds.has(processGroupId) &&
+            !sampledProcessGroupIds.has(processGroupId))
             return {
                 cleaned: false,
                 reason: "descendant process-group leader identity could not be verified",
             };
+        if ((groupLeader === undefined || !descendantPids.has(groupLeader.pid)) &&
+            !tokenOwnedGroupIds.has(processGroupId))
+            unverifiableSampledGroups.add(processGroupId);
     }
     const liveMembers = processes.filter(({ processGroupId }) => processGroupIds.has(processGroupId));
-    const failures = await processOwnershipFailures(liveMembers, ownership.runId, host);
-    if (failures.length > 0)
-        return cleanupValidationFailure(failures);
+    for (const processGroupId of processGroupIds) {
+        const members = liveMembers.filter(({ processGroupId: observedGroupId }) => observedGroupId === processGroupId);
+        if (members.length === 0)
+            continue;
+        const failures = await processOwnershipFailures(members, ownership.runId, host, tokenOwned.identities);
+        if (failures.length === 0 && unverifiableSampledGroups.has(processGroupId))
+            unresolved.push(...members.map(({ pid }) => ({
+                pid,
+                reason: "process-identity-unavailable",
+                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);
+        if (failures.length === 0 &&
+            scanFailures.length === 0 &&
+            !unverifiableSampledGroups.has(processGroupId))
+            signalableGroups.add(processGroupId);
+    }
+    if (ownership.sweepTokenOwnedProcesses !== true && unresolved.length > 0)
+        return cleanupValidationFailure(unresolved);
     return {
-        signalOrder: [ownership.processGroupId].concat([...processGroupIds]
-            .filter((processGroupId) => processGroupId !== ownership.processGroupId)
-            .sort((left, right) => left - right)),
+        signalOrder: [...signalableGroups]
+            .filter((groupId) => processGroupIds.has(groupId))
+            .sort((left, right) => left === ownership.processGroupId
+            ? -1
+            : right === ownership.processGroupId
+                ? 1
+                : left - right),
+        tokenOwnedIdentities: tokenOwned.identities,
+        unresolved,
     };
 };
-const revalidateOwnedProcessGroup = async (processGroupId, ownership, host) => {
+const revalidateOwnedProcessGroup = async (processGroupId, ownership, host, expectedIdentities) => {
     let members;
     try {
         members = liveProcesses(await host.listProcesses()).filter(({ processGroupId: observedGroupId }) => observedGroupId === processGroupId);
@@ -163,7 +203,7 @@ const revalidateOwnedProcessGroup = async (processGroupId, ownership, host) => {
             reason: `process ownership could not be revalidated: ${errorMessage(cause)}`,
         };
     }
-    const failures = await processOwnershipFailures(members, ownership.runId, host);
+    const failures = await processOwnershipFailures(members, ownership.runId, host, expectedIdentities);
     if (failures.length > 0)
         return cleanupValidationFailure(failures);
     if (processGroupId === ownership.processGroupId) {
@@ -184,15 +224,93 @@ const revalidateOwnedProcessGroup = async (processGroupId, ownership, host) => {
         };
     return { empty: members.length === 0 };
 };
-const cleanupValidationFailure = (failures) => ({
-    cleaned: false,
-    reason: failures.some(({ reason }) => reason === "run-token-mismatch")
-        ? "process tree contains an unowned or PID-reused process"
-        : "process ownership could not be revalidated",
-    failures,
-});
-const processOwnershipFailures = async (members, runId, host) => {
+const cleanupValidationFailure = (failures) => {
+    const unreadable = failures.filter(({ reason }) => reason === "environment-unreadable");
+    if (failures.some(({ reason }) => reason === "run-token-mismatch"))
+        return {
+            cleaned: false,
+            reason: "process tree contains an unowned or PID-reused process",
+            failures,
+        };
+    if (failures.some(({ reason }) => reason === "process-identity-unavailable"))
+        return {
+            cleaned: false,
+            reason: "process identity could not be revalidated",
+            failures,
+        };
+    if (unreadable.length > 0) {
+        const counts = new Map();
+        for (const { diagnostic } of unreadable) {
+            const category = sanitizedTokenReadFailure(diagnostic);
+            counts.set(category, (counts.get(category) ?? 0) + 1);
+        }
+        const breakdown = [...counts]
+            .sort(([left], [right]) => left.localeCompare(right))
+            .map(([category, count]) => `${category}=${String(count)}`)
+            .join(", ");
+        return {
+            cleaned: false,
+            reason: `process ownership token could not be read for ${String(unreadable.length)} live process(es): ${breakdown}`,
+            failures,
+        };
+    }
+    return {
+        cleaned: false,
+        reason: "process ownership could not be revalidated",
+        failures,
+    };
+};
+const sanitizedTokenReadFailure = (diagnostic) => {
+    if (diagnostic === "environment_unavailable")
+        return diagnostic;
+    const environmentErrno = /^(EACCES|EPERM|ENOENT|ESRCH):/u.exec(diagnostic ?? "");
+    if (environmentErrno?.[1] !== undefined)
+        return `environment_errno_${environmentErrno[1]}`;
+    if (diagnostic === "apple_vector_unavailable")
+        return diagnostic;
+    if (diagnostic === "ambiguous_environment_boundary")
+        return diagnostic;
+    if (diagnostic === "malformed_procargs")
+        return diagnostic;
+    if (diagnostic === "process_identity_changed_during_token_read")
+        return diagnostic;
+    if (diagnostic === "process_not_in_snapshot")
+        return diagnostic;
+    const processTableFailure = /^process_table_failed_(\d+)$/u.exec(diagnostic ?? "");
+    if (processTableFailure?.[1] !== undefined)
+        return `process_table_errno_${processTableFailure[1]}`;
+    const sysctlFailure = /^sysctl_failed_(\d+)$/u.exec(diagnostic ?? "");
+    if (sysctlFailure?.[1] !== undefined)
+        return `sysctl_errno_${sysctlFailure[1]}`;
+    if (diagnostic === "reader_failure")
+        return diagnostic;
+    if (diagnostic === "duplicate_run_token")
+        return diagnostic;
+    if (diagnostic === "invalid_run_token_encoding")
+        return diagnostic;
+    return "other_unavailable";
+};
+const processOwnershipFailures = async (members, runId, host, expectedIdentities = new Map()) => {
     const failures = [];
+    if (expectedIdentities.size > 0 && host.processIdentities !== undefined) {
+        const expectedMembers = members.filter(({ pid }) => expectedIdentities.has(pid));
+        const observed = await host.processIdentities(expectedMembers);
+        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({
+                    pid: member.pid,
+                    reason: "process-identity-unavailable",
+                    diagnostic: "process identity changed or became unavailable before signal",
+                });
+            }
+        }
+    }
     for (const member of members) {
         try {
             if ((await host.environment(member.pid)).REA_PROCESS_RUN_ID !== runId)
@@ -219,15 +337,94 @@ const processOwnershipFailures = async (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);
+        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)
+                continue;
+            if (await processIsGone(host, member.pid))
+                continue;
+            failures.push({
+                pid: member.pid,
+                reason: "process-identity-unavailable",
+                diagnostic: "process identity changed or became unavailable during token validation",
+            });
+        }
+    }
     return failures;
 };
-const scanTokenOwnedProcesses = async (processes, runId, host) => {
-    const owned = [];
+const scanTokenOwnedProcesses = async (processes, runId, host, captureBaseline) => {
+    let candidates = processes;
+    let candidateIdentities = new Map();
+    if (host.processIdentities !== undefined) {
+        const current = await host.processIdentities(processes);
+        candidateIdentities = current;
+        if (captureBaseline !== undefined) {
+            const baseline = new Map(captureBaseline.map(({ pid, identity }) => [pid, identity]));
+            candidates = processes.filter((process) => {
+                const before = baseline.get(process.pid);
+                const now = current.get(process.pid);
+                return !(before !== undefined &&
+                    before !== null &&
+                    now?.state === "readable" &&
+                    now.identity === before);
+            });
+        }
+    }
     const failures = [];
-    for (const process of processes) {
+    if (captureBaseline !== undefined && host.processIdentities !== undefined) {
+        const stableCandidates = [];
+        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",
+                });
+        }
+        candidates = stableCandidates;
+    }
+    let bulkTokens;
+    if (host.runTokens !== undefined)
+        bulkTokens = await host.runTokens(candidates);
+    const owned = [];
+    const ownedIdentities = new Map();
+    for (const process of candidates) {
+        const bulkToken = bulkTokens?.get(process.pid);
+        if (bulkToken !== undefined) {
+            if (bulkToken.state === "readable") {
+                if (bulkToken.runId === runId) {
+                    owned.push(process);
+                    const identity = candidateIdentities.get(process.pid);
+                    ownedIdentities.set(process.pid, identity?.state === "readable" ? identity.identity : null);
+                }
+                continue;
+            }
+            if (!(await processIsGone(host, process.pid)))
+                failures.push({
+                    pid: process.pid,
+                    reason: "environment-unreadable",
+                    diagnostic: bulkToken.reason,
+                });
+            continue;
+        }
         try {
-            if ((await host.environment(process.pid)).REA_PROCESS_RUN_ID === runId)
+            if ((await host.environment(process.pid)).REA_PROCESS_RUN_ID === runId) {
                 owned.push(process);
+                const identity = candidateIdentities.get(process.pid);
+                ownedIdentities.set(process.pid, identity?.state === "readable" ? identity.identity : null);
+            }
         }
         catch (cause) {
             try {
@@ -250,5 +447,38 @@ const scanTokenOwnedProcesses = async (processes, runId, host) => {
             });
         }
     }
-    return { owned, failures };
+    if (candidates.length > 0 && host.processIdentities !== undefined) {
+        const afterRead = await host.processIdentities(candidates);
+        const stillOwned = [];
+        const ownedPids = new Set(owned.map(({ pid }) => pid));
+        for (const process of candidates) {
+            const before = candidateIdentities.get(process.pid);
+            const current = afterRead.get(process.pid);
+            if (before?.state === "readable" &&
+                current?.state === "readable" &&
+                current.identity === before.identity) {
+                if (ownedPids.has(process.pid))
+                    stillOwned.push(process);
+                continue;
+            }
+            if (await processIsGone(host, process.pid))
+                continue;
+            failures.push({
+                pid: process.pid,
+                reason: "process-identity-unavailable",
+                diagnostic: "process identity changed or became unavailable during token validation",
+            });
+        }
+        return { owned: stillOwned, failures, identities: ownedIdentities };
+    }
+    return { owned, failures, identities: ownedIdentities };
+};
+const processIsGone = async (host, pid) => {
+    try {
+        return !liveProcesses(await host.listProcesses()).some((process) => process.pid === pid);
+    }
+    catch (cause) {
+        void cause;
+        return false;
+    }
 };

package/dist/process/ProcessOwnershipObservation.js

@@ -2,6 +2,7 @@ import { readFile } from "node:fs/promises";
 import { launcherIdentityFailure } from "./ProcessOwnershipIdentity.js";
 import { descendantsOf, liveProcesses } from "./ProcessOwnershipProcessTree.js";
 import { execFileOutput } from "./ExecFileOutput.js";
+import { createDarwinProcessRunTokenReader } from "./DarwinProcessRunTokenReader.js";
 /** Observe one group without signaling it, failing closed on identity doubt. */
 export const observeOwnedProcessGroupWithHost = async (ownership, host) => {
     let members;
@@ -105,13 +106,34 @@ export const parseProcessEnvironment = (value) => Object.fromEntries(value
     const separator = entry.indexOf("=");
     return [entry.slice(0, separator), entry.slice(separator + 1)];
 }));
+/** Read Linux stat field 22, tolerating spaces and closing parentheses in comm. */
+export const parseLinuxProcessStartTime = (value) => {
+    const commandEnd = value.lastIndexOf(")");
+    if (commandEnd < 0)
+        return undefined;
+    const fields = value
+        .slice(commandEnd + 1)
+        .trim()
+        .split(/\s+/u);
+    const startTime = fields[19];
+    return startTime !== undefined && /^\d+$/u.test(startTime)
+        ? startTime
+        : undefined;
+};
+const isExpectedAbort = (cause, signal) => signal?.aborted === true &&
+    (cause === signal.reason ||
+        (cause instanceof Error && cause.name === "AbortError"));
 /** Create the operating-system process inspector for an explicit host context. */
-export const createSystemProcessOwnershipHost = (platform = process.platform, hostEnvironment = process.env) => ({
-    platform,
-    async listProcesses() {
+export const createSystemProcessOwnershipHost = (platform = process.platform, hostEnvironment = process.env, options = {}) => {
+    const darwinTokens = platform === "darwin"
+        ? createDarwinProcessRunTokenReader(options.darwinXcrun === undefined
+            ? {}
+            : { xcrun: options.darwinXcrun })
+        : undefined;
+    const listProcesses = async (signal) => {
         if (platform === "win32")
             return [];
-        const { stdout } = await execFileOutput("ps", ["-axo", "pid=,ppid=,pgid=,stat=,command="], { env: hostEnvironment });
+        const { stdout } = await execFileOutput("ps", ["-axo", "pid=,ppid=,pgid=,stat=,command="], { env: hostEnvironment, ...(signal === undefined ? {} : { signal }) });
         return stdout
             .split("\n")
             .map((line) => /\s*(\d+)\s+(\d+)\s+(\d+)\s+(\S+)\s+(.*)/u.exec(line))
@@ -123,28 +145,143 @@ export const createSystemProcessOwnershipHost = (platform = process.platform, ho
             state: match[4] ?? "",
             command: match[5] ?? "",
         }));
-    },
-    async environment(pid) {
+    };
+    const processIdentities = async (processes, signal) => {
+        if (processes.length === 0)
+            return new Map();
         if (platform === "linux")
-            return parseProcessEnvironment(await readFile(`/proc/${pid}/environ`, "utf8"));
-        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)
-                observedEnvironment[name] = match[2] ?? "";
+            return new Map(await Promise.all(processes.map(async ({ pid }) => {
+                try {
+                    const stat = await readFile(`/proc/${String(pid)}/stat`, {
+                        encoding: "utf8",
+                        ...(signal === undefined ? {} : { signal }),
+                    });
+                    const identity = parseLinuxProcessStartTime(stat);
+                    return [
+                        pid,
+                        identity === undefined
+                            ? {
+                                state: "unavailable",
+                                reason: "malformed_proc_stat",
+                            }
+                            : {
+                                state: "readable",
+                                identity: `linux-starttime:${identity}`,
+                            },
+                    ];
+                }
+                catch (cause) {
+                    if (isExpectedAbort(cause, signal))
+                        throw cause;
+                    return [
+                        pid,
+                        { state: "unavailable", reason: errorMessage(cause) },
+                    ];
+                }
+            })));
+        if (darwinTokens === undefined)
+            return new Map();
+        try {
+            return await darwinTokens.identities(processes, signal);
         }
-        return observedEnvironment;
-    },
-    signalGroup(processGroupId, signal) {
-        process.kill(-processGroupId, signal);
-    },
-});
-const systemHost = createSystemProcessOwnershipHost();
+        catch (cause) {
+            if (isExpectedAbort(cause, signal))
+                throw cause;
+            const reason = errorMessage(cause);
+            return new Map(processes.map(({ pid }) => [
+                pid,
+                { state: "unavailable", reason },
+            ]));
+        }
+    };
+    const captureBaseline = async (signal) => {
+        if (platform !== "linux" && darwinTokens === undefined)
+            return [];
+        const processes = liveProcesses(await listProcesses(signal));
+        let identities = await processIdentities(processes, signal);
+        const unreadable = processes.filter(({ pid }) => identities.get(pid)?.state !== "readable");
+        if (unreadable.length > 0) {
+            const stillLive = liveProcesses(await listProcesses(signal)).filter(({ pid }) => unreadable.some((entry) => entry.pid === pid));
+            const retried = await processIdentities(stillLive, signal);
+            identities = new Map([...identities, ...retried]);
+            const unresolved = stillLive.filter(({ pid }) => identities.get(pid)?.state !== "readable");
+            const liveAfterRetry = liveProcesses(await listProcesses(signal));
+            const stillUnresolved = unresolved.filter(({ pid }) => liveAfterRetry.some((entry) => entry.pid === pid));
+            if (stillUnresolved.length > 0)
+                throw new Error(`process identity snapshot is unavailable for ${String(stillUnresolved.length)} live processes`);
+        }
+        return processes.map(({ pid }) => {
+            const observation = identities.get(pid);
+            return {
+                pid,
+                identity: observation?.state === "readable" ? observation.identity : null,
+            };
+        });
+    };
+    return {
+        platform,
+        prepare: async (signal) => {
+            await darwinTokens?.prepare(signal);
+        },
+        listProcesses,
+        async environment(pid) {
+            if (platform === "linux")
+                return parseProcessEnvironment(await readFile(`/proc/${pid}/environ`, "utf8"));
+            if (platform === "darwin") {
+                const process = (await listProcesses()).find((entry) => entry.pid === pid);
+                if (process === undefined)
+                    throw new Error(`process ${String(pid)} is not live`);
+                const observation = (await darwinTokens?.read([process]))?.get(pid);
+                if (observation === undefined || observation.state === "unavailable")
+                    throw new Error(observation?.reason ?? "process run token could not be read");
+                return observation.runId === undefined
+                    ? {}
+                    : { REA_PROCESS_RUN_ID: observation.runId };
+            }
+            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)
+                    observedEnvironment[name] = match[2] ?? "";
+            }
+            return observedEnvironment;
+        },
+        async runTokens(processes) {
+            if (platform !== "darwin" || processes.length === 0)
+                return new Map();
+            try {
+                return (await darwinTokens?.read(processes)) ?? new Map();
+            }
+            catch (cause) {
+                void cause;
+                return new Map(processes.map(({ pid }) => [
+                    pid,
+                    { state: "unavailable", reason: "reader_failure" },
+                ]));
+            }
+        },
+        ...(platform !== "linux" && darwinTokens === undefined
+            ? {}
+            : {
+                processIdentities,
+                captureBaseline,
+                ...(darwinTokens === undefined ? {} : { close: darwinTokens.close }),
+            }),
+        signalGroup(processGroupId, signal) {
+            process.kill(-processGroupId, signal);
+        },
+    };
+};
+export const systemProcessOwnershipHost = createSystemProcessOwnershipHost();
+/** Prepare native token inspection before REA launches a captured child. */
+export const prepareProcessOwnershipInspection = async (signal) => {
+    await systemProcessOwnershipHost.prepare?.(signal);
+};
 /** Observe one group without signaling it, failing closed on identity doubt. */
-export const observeOwnedProcessGroup = async (ownership, host = systemHost) => observeOwnedProcessGroupWithHost(ownership, host);
+export const observeOwnedProcessGroup = async (ownership, host = systemProcessOwnershipHost) => observeOwnedProcessGroupWithHost(ownership, host);
 /**
  * Record the live launcher and descendant lineage after run-token validation.
  *
@@ -152,7 +289,7 @@ export const observeOwnedProcessGroup = async (ownership, host = systemHost) =>
  * list means no descendants were live during this observation, not that the
  * run never created a short-lived child.
  */
-export const observeOwnedProcessLineage = async (ownership, host = systemHost) => observeOwnedProcessLineageWithHost(ownership, host);
+export const observeOwnedProcessLineage = async (ownership, host = systemProcessOwnershipHost) => observeOwnedProcessLineageWithHost(ownership, host);
 const processIsGone = async (host, pid) => {
     try {
         return !liveProcesses(await host.listProcesses()).some((process) => process.pid === pid);