rea-agents 6.0.0 → 6.1.0

package/dist/process/ProcessOwnership.js

@@ -77,23 +77,35 @@ export const cleanupOwnedProcessGroup = async (ownership, host = systemHost) =>
         }
     }
     if (plan.unresolved.length > 0)
-        return cleanupValidationFailure(plan.unresolved);
-    return { cleaned: true, signaled };
+        return cleanupValidationFailure(plan.unresolved, plan.unverified);
+    return {
+        cleaned: true,
+        signaled,
+        ...(plan.unverified.length === 0 ? {} : { unverified: plan.unverified }),
+    };
 };
 /** Verify that no live process still carries an owned capture run token. */
-export const verifyNoTokenOwnedProcesses = async (runId, host = systemHost, captureBaseline) => {
+export const verifyNoTokenOwnedProcesses = async (runId, host = systemHost, captureBaseline, relation) => {
     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, captureBaseline);
+    const scan = await scanTokenOwnedProcesses(processTable.processes, runId, host, captureBaseline, relation);
     if (scan.failures.length > 0)
-        return cleanupValidationFailure(scan.failures);
-    return scan.owned.length === 0
-        ? { cleaned: true, signaled: false }
-        : { cleaned: false, reason: "token-owned process remained after cleanup" };
+        return cleanupValidationFailure(scan.failures, scan.unverified);
+    if (scan.owned.length > 0)
+        return {
+            cleaned: false,
+            reason: "token-owned process remained after cleanup",
+            ...(scan.unverified.length === 0 ? {} : { unverified: scan.unverified }),
+        };
+    return {
+        cleaned: true,
+        signaled: false,
+        ...(scan.unverified.length === 0 ? {} : { unverified: scan.unverified }),
+    };
 };
 const readLiveProcessTable = async (host) => {
     try {
@@ -109,8 +121,14 @@ 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, ownership.captureBaseline)
-        : { owned: [], failures: [], identities: new Map() };
+        ? await scanTokenOwnedProcesses(processes, ownership.runId, host, ownership.captureBaseline, {
+            leaderPid: ownership.leaderPid,
+            processGroupId: ownership.processGroupId,
+            ...(sampledProcessGroupIds.size === 0
+                ? {}
+                : { sampledProcessGroupIds: [...sampledProcessGroupIds] }),
+        })
+        : { owned: [], failures: [], unverified: [], 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);
@@ -123,8 +141,15 @@ const createOwnedCleanupPlan = async (ownership, processes, host) => {
                 signalOrder: [],
                 tokenOwnedIdentities: tokenOwned.identities,
                 unresolved: tokenOwned.failures,
+                unverified: tokenOwned.unverified,
             }
-            : { cleaned: true, signaled: false };
+            : {
+                cleaned: true,
+                signaled: false,
+                ...(tokenOwned.unverified.length === 0
+                    ? {}
+                    : { unverified: tokenOwned.unverified }),
+            };
     let descendants = [];
     if (launcher !== undefined) {
         const identityFailure = launcherIdentityFailure(launcher, ownership);
@@ -179,7 +204,7 @@ const createOwnedCleanupPlan = async (ownership, processes, host) => {
             signalableGroups.add(processGroupId);
     }
     if (ownership.sweepTokenOwnedProcesses !== true && unresolved.length > 0)
-        return cleanupValidationFailure(unresolved);
+        return cleanupValidationFailure(unresolved, tokenOwned.unverified);
     return {
         signalOrder: [...signalableGroups]
             .filter((groupId) => processGroupIds.has(groupId))
@@ -190,6 +215,7 @@ const createOwnedCleanupPlan = async (ownership, processes, host) => {
                 : left - right),
         tokenOwnedIdentities: tokenOwned.identities,
         unresolved,
+        unverified: tokenOwned.unverified,
     };
 };
 const revalidateOwnedProcessGroup = async (processGroupId, ownership, host, expectedIdentities) => {
@@ -224,19 +250,22 @@ const revalidateOwnedProcessGroup = async (processGroupId, ownership, host, expe
         };
     return { empty: members.length === 0 };
 };
-const cleanupValidationFailure = (failures) => {
+const cleanupValidationFailure = (failures, unverified = []) => {
+    const unverifiedEntry = unverified.length === 0 ? {} : { unverified };
     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,
+            ...unverifiedEntry,
         };
     if (failures.some(({ reason }) => reason === "process-identity-unavailable"))
         return {
             cleaned: false,
             reason: "process identity could not be revalidated",
             failures,
+            ...unverifiedEntry,
         };
     if (unreadable.length > 0) {
         const counts = new Map();
@@ -248,21 +277,28 @@ const cleanupValidationFailure = (failures) => {
             .sort(([left], [right]) => left.localeCompare(right))
             .map(([category, count]) => `${category}=${String(count)}`)
             .join(", ");
+        const candidates = unreadable
+            .map(({ pid, diagnostic }) => `${String(pid)}=${sanitizedTokenReadFailure(diagnostic)}`)
+            .sort((left, right) => left.localeCompare(right));
         return {
             cleaned: false,
-            reason: `process ownership token could not be read for ${String(unreadable.length)} live process(es): ${breakdown}`,
+            reason: `process ownership token could not be read for ${String(unreadable.length)} live process(es): ${breakdown}; live candidates ${candidates.join(", ")}`,
             failures,
+            ...unverifiedEntry,
         };
     }
     return {
         cleaned: false,
         reason: "process ownership could not be revalidated",
         failures,
+        ...unverifiedEntry,
     };
 };
 const sanitizedTokenReadFailure = (diagnostic) => {
     if (diagnostic === "environment_unavailable")
         return diagnostic;
+    if (diagnostic === "platform_binary_environment_withheld")
+        return diagnostic;
     const environmentErrno = /^(EACCES|EPERM|ENOENT|ESRCH):/u.exec(diagnostic ?? "");
     if (environmentErrno?.[1] !== undefined)
         return `environment_errno_${environmentErrno[1]}`;
@@ -360,7 +396,26 @@ const processOwnershipFailures = async (members, runId, host, expectedIdentities
     }
     return failures;
 };
-const scanTokenOwnedProcesses = async (processes, runId, host, captureBaseline) => {
+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";
+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.
+ */
+const environmentWithheldFromInspection = (entry, diagnostic) => {
+    const uid = currentProcessUid();
+    if (uid !== undefined && entry.uid !== undefined && entry.uid !== uid)
+        return true;
+    return diagnostic === PLATFORM_BINARY_ENVIRONMENT_WITHHELD;
+};
+const scanTokenOwnedProcesses = async (processes, runId, host, captureBaseline, relation) => {
     let candidates = processes;
     let candidateIdentities = new Map();
     if (host.processIdentities !== undefined) {
@@ -395,58 +450,89 @@ const scanTokenOwnedProcesses = async (processes, runId, host, captureBaseline)
         }
         candidates = stableCandidates;
     }
+    const owned = [];
+    const ownedIdentities = new Map();
+    const recordOwned = (process) => {
+        owned.push(process);
+        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 owned = [];
-    const ownedIdentities = new Map();
+    const unreadable = [];
     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);
-                }
+                if (bulkToken.runId === runId)
+                    recordOwned(process);
                 continue;
             }
-            if (!(await processIsGone(host, process.pid)))
-                failures.push({
-                    pid: process.pid,
-                    reason: "environment-unreadable",
-                    diagnostic: bulkToken.reason,
-                });
+            unreadable.push({ process, diagnostic: bulkToken.reason });
             continue;
         }
         try {
-            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);
-            }
+            if ((await host.environment(process.pid)).REA_PROCESS_RUN_ID === runId)
+                recordOwned(process);
         }
         catch (cause) {
-            try {
-                const live = liveProcesses(await host.listProcesses());
-                if (!live.some(({ pid }) => pid === process.pid))
-                    continue;
-            }
-            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),
-            });
+            unreadable.push({ process, diagnostic: errorMessage(cause) });
         }
     }
+    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))
+            relatedPids.add(descendant.pid);
+        relatedGroupIds.add(relation.processGroupId);
+        for (const processGroupId of relation.sampledProcessGroupIds ?? [])
+            if (Number.isSafeInteger(processGroupId) && processGroupId > 0)
+                relatedGroupIds.add(processGroupId);
+        for (const process of owned)
+            relatedGroupIds.add(process.processGroupId);
+    }
+    const unverified = [];
+    const strict = [];
+    const withheld = [];
+    for (const candidate of remaining) {
+        const isRelated = relation === undefined ||
+            relatedPids.has(candidate.process.pid) ||
+            relatedGroupIds.has(candidate.process.processGroupId);
+        if (!isRelated &&
+            environmentWithheldFromInspection(candidate.process, candidate.diagnostic)) {
+            withheld.push(candidate);
+            continue;
+        }
+        strict.push(candidate);
+    }
+    let finalLive;
+    try {
+        finalLive = new Set(liveProcesses(await host.listProcesses()).map(({ pid }) => pid));
+    }
+    catch (cause) {
+        void cause;
+        finalLive = undefined;
+    }
+    for (const candidate of strict) {
+        if (finalLive !== undefined && !finalLive.has(candidate.process.pid))
+            continue;
+        failures.push({
+            pid: candidate.process.pid,
+            reason: "environment-unreadable",
+            diagnostic: candidate.diagnostic,
+        });
+    }
+    for (const candidate of withheld) {
+        if (finalLive !== undefined && !finalLive.has(candidate.process.pid))
+            continue;
+        unverified.push({
+            pid: candidate.process.pid,
+            diagnostic: candidate.diagnostic,
+        });
+    }
     if (candidates.length > 0 && host.processIdentities !== undefined) {
         const afterRead = await host.processIdentities(candidates);
         const stillOwned = [];
@@ -469,9 +555,73 @@ const scanTokenOwnedProcesses = async (processes, runId, host, captureBaseline)
                 diagnostic: "process identity changed or became unavailable during token validation",
             });
         }
-        return { owned: stillOwned, failures, identities: ownedIdentities };
+        return {
+            owned: stillOwned,
+            failures,
+            unverified,
+            identities: ownedIdentities,
+        };
+    }
+    return { owned, failures, unverified, identities: ownedIdentities };
+};
+/**
+ * Re-read run tokens for unresolved sweep candidates so transient exec and
+ * exit states settle before classification. Each attempt revalidates
+ * liveness, refreshes the diagnostic, and is bounded by a fixed attempt
+ * budget; a still-unreadable candidate keeps its latest diagnostic.
+ */
+const settleUnreadableTokenCandidates = async (pending, runId, host, recordOwned) => {
+    let remaining = pending;
+    for (let attempt = 0; attempt < TOKEN_READ_RETRY_ATTEMPTS && remaining.length > 0; attempt += 1) {
+        await new Promise((resolve) => setTimeout(resolve, TOKEN_READ_RETRY_DELAY_MS));
+        let live;
+        try {
+            live = new Set(liveProcesses(await host.listProcesses()).map(({ pid }) => pid));
+        }
+        catch (cause) {
+            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));
+            if (observation.state === "readable") {
+                if (observation.runId === runId)
+                    recordOwned(candidate.process);
+                continue;
+            }
+            stillUnreadable.push({
+                process: candidate.process,
+                diagnostic: observation.reason,
+            });
+        }
+        remaining = stillUnreadable;
+    }
+    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) };
     }
-    return { owned, failures, identities: ownedIdentities };
 };
 const processIsGone = async (host, pid) => {
     try {

package/dist/process/ProcessOwnershipObservation.js

@@ -1,4 +1,5 @@
 import { readFile } from "node:fs/promises";
+import { AnalysisCapabilityUnavailableError } from "../domain/analysisErrorCore.js";
 import { launcherIdentityFailure } from "./ProcessOwnershipIdentity.js";
 import { descendantsOf, liveProcesses } from "./ProcessOwnershipProcessTree.js";
 import { execFileOutput } from "./ExecFileOutput.js";
@@ -133,17 +134,18 @@ export const createSystemProcessOwnershipHost = (platform = process.platform, ho
     const listProcesses = async (signal) => {
         if (platform === "win32")
             return [];
-        const { stdout } = await execFileOutput("ps", ["-axo", "pid=,ppid=,pgid=,stat=,command="], { env: hostEnvironment, ...(signal === undefined ? {} : { signal }) });
+        const { stdout } = await execFileOutput("ps", ["-axo", "pid=,ppid=,pgid=,uid=,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))
+            .map((line) => /\s*(\d+)\s+(\d+)\s+(\d+)\s+(\d+)\s+(\S+)\s+(.*)/u.exec(line))
             .filter((match) => match !== null)
             .map((match) => ({
             pid: Number(match[1]),
             parentPid: Number(match[2]),
             processGroupId: Number(match[3]),
-            state: match[4] ?? "",
-            command: match[5] ?? "",
+            uid: Number(match[4]),
+            state: match[5] ?? "",
+            command: match[6] ?? "",
         }));
     };
     const processIdentities = async (processes, signal) => {
@@ -222,6 +224,19 @@ export const createSystemProcessOwnershipHost = (platform = process.platform, ho
         platform,
         prepare: async (signal) => {
             await darwinTokens?.prepare(signal);
+            if (platform === "linux") {
+                try {
+                    const processes = await listProcesses(signal);
+                    if (!processes.some(({ pid }) => pid === process.pid))
+                        throw new Error("ps did not report REA's current process");
+                }
+                catch (cause) {
+                    if (isExpectedAbort(cause, signal))
+                        throw cause;
+                    const reason = `Linux process ownership inspection requires a procps-compatible ps on REA's PATH before launching a child: ${errorMessage(cause)}`;
+                    throw new AnalysisCapabilityUnavailableError("process-ownership", "prepare_owned_process", reason, { cause, userMessage: reason });
+                }
+            }
         },
         listProcesses,
         async environment(pid) {
@@ -276,6 +291,36 @@ export const createSystemProcessOwnershipHost = (platform = process.platform, ho
     };
 };
 export const systemProcessOwnershipHost = createSystemProcessOwnershipHost();
+/** Observe the current OS start identity for one live PID, when supported. */
+export const observeProcessStartIdentity = async (pid, host = systemProcessOwnershipHost) => {
+    const process = (await host.listProcesses()).find((entry) => entry.pid === pid);
+    if (process === undefined || liveProcesses([process]).length === 0)
+        return undefined;
+    if (host.processIdentities === undefined)
+        return { state: "unavailable", reason: "process identity is unsupported" };
+    return ((await host.processIdentities([process])).get(pid) ?? {
+        state: "unavailable",
+        reason: "process identity was not returned",
+    });
+};
+/** Revalidate a launch-time start identity immediately before signaling a PID. */
+export const signalProcessWithStartIdentity = async (pid, expectedIdentity, signal, options = {}) => {
+    const host = options.host ?? systemProcessOwnershipHost;
+    try {
+        const observed = await observeProcessStartIdentity(pid, host);
+        if (observed === undefined)
+            return "gone";
+        if (observed.state !== "readable")
+            return "unverified";
+        if (observed.identity !== expectedIdentity)
+            return "identity-changed";
+        (options.sendSignal ?? process.kill)(pid, signal);
+        return "signaled";
+    }
+    catch {
+        return "unverified";
+    }
+};
 /** Prepare native token inspection before REA launches a captured child. */
 export const prepareProcessOwnershipInspection = async (signal) => {
     await systemProcessOwnershipHost.prepare?.(signal);

package/dist/process/ProviderProcess.js

@@ -83,6 +83,12 @@ export class ProviderProcessSupervisor {
     #onStderr = (chunk) => {
         this.#capture("stderr", this.#stderr, chunk);
     };
+    #onStdoutError = (cause) => {
+        this.#recordStreamError("stdout", cause);
+    };
+    #onStderrError = (cause) => {
+        this.#recordStreamError("stderr", cause);
+    };
     #onExit = (code, signal) => {
         this.#recordExit(code, signal);
     };
@@ -135,9 +141,13 @@ export class ProviderProcessSupervisor {
     async waitForOutputClose(timeoutMs) {
         return waitForProcessEvent(this.#outputClosed, this.#outputClose.promise, timeoutMs);
     }
-    /** Stop an owned process once; concurrent callers share the same escalation. */
+    /** Share each stop attempt; incomplete cleanup retains ownership and permits retry. */
     stop(options = {}) {
-        this.#stopPromise ??= this.#stop(options);
+        this.#stopPromise ??= this.#stop(options).then((result) => {
+            if (result.status === "incomplete")
+                this.#stopPromise = undefined;
+            return result;
+        });
         return this.#stopPromise;
     }
     /** Detach capture and process listeners after an adapter releases ownership. */
@@ -146,12 +156,26 @@ export class ProviderProcessSupervisor {
             return;
         this.#disposed = true;
         this.launch.process.stdout?.off("data", this.#onStdout);
+        this.launch.process.stdout?.off("error", this.#onStdoutError);
         this.launch.process.stderr?.off("data", this.#onStderr);
+        this.launch.process.stderr?.off("error", this.#onStderrError);
         this.launch.process.off("exit", this.#onExit);
         this.launch.process.off("close", this.#onClose);
         this.launch.process.off("error", this.#onError);
     }
     async #stop(options) {
+        let completed = false;
+        try {
+            const result = await this.#stopWithin(options);
+            completed = result.status !== "incomplete";
+            return result;
+        }
+        finally {
+            if (completed)
+                this.dispose();
+        }
+    }
+    async #stopWithin(options) {
         try {
             if (!this.launch.ownsProcessLifetime)
                 return { status: "not-owned" };
@@ -193,9 +217,6 @@ export class ProviderProcessSupervisor {
                     : "owned provider process cleanup failed",
             };
         }
-        finally {
-            this.dispose();
-        }
     }
     #ownedCleanup(supplied) {
         if (supplied !== undefined)
@@ -214,10 +235,20 @@ export class ProviderProcessSupervisor {
         this.launch.process.kill(signal);
     }
     #attach(stream, name) {
-        if (name === "stdout")
+        if (name === "stdout") {
             stream?.on("data", this.#onStdout);
-        else
+            stream?.on("error", this.#onStdoutError);
+        }
+        else {
             stream?.on("data", this.#onStderr);
+            stream?.on("error", this.#onStderrError);
+        }
+    }
+    #recordStreamError(stream, cause) {
+        this.#options.onDiagnostic?.({
+            type: "error",
+            message: `${stream} stream failed: ${cause.message}`,
+        });
     }
     #capture(stream, capture, chunk) {
         const bytes = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);

package/dist/process/capture/ProcessCaptureError.js

@@ -12,14 +12,14 @@ export class ProcessCaptureError extends AnalysisError {
     cleanupReport;
     constructor(message, options) {
         super(message, options);
-        this.userMessage = options?.userMessage;
+        this.userMessage = options?.userMessage ?? message;
         this.userCategory = options?.userCategory;
         this.reason =
             options?.reason ??
                 (options?.userCategory === "cancelled" ? "cancelled" : "capture_failed");
         this.cleanupIncomplete = this.reason === "cleanup_incomplete";
         this.cleanupResources = options?.cleanupResources ?? [];
-        this.executionFailure = options?.executionFailure;
+        this.executionFailure = options?.executionFailure ?? message;
         this.partialObservation = options?.partialObservation;
         this.cleanupReport = options?.cleanupReport;
     }