rea-agents 6.3.0 → 6.4.0

package/dist/process/ProcessOwnership.js

@@ -3,6 +3,7 @@ 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";
 const execFileAsync = promisify(execFile);
 /**
  * Terminate one Windows process tree through the platform utility.
@@ -115,7 +116,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 +181,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]);
@@ -218,7 +247,10 @@ const createOwnedCleanupPlan = async (ownership, processes, host) => {
 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 +261,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) &&
@@ -328,53 +352,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,17 +382,53 @@ 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 {
+        const live = new Set(liveProcesses(await host.listProcesses()).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. */
@@ -433,18 +469,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 +491,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 +556,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 +568,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 +602,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 +621,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;
-    }
-};

package/dist/process/ProcessOwnershipObservation.js

@@ -4,46 +4,65 @@ 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 observeOwnedProcessGroup = async (ownership, host = systemProcessOwnershipHost, signal) => {
+import { readProcessRunTokens } from "./ProcessRunTokenObservations.js";
+/** Observe multiple groups from one process snapshot and one token batch. */
+export const observeOwnedProcessGroups = async (runId, processGroupIds, host = systemProcessOwnershipHost, signal) => {
     signal?.throwIfAborted();
-    let members;
+    const groupIds = [...new Set(processGroupIds)];
+    if (groupIds.length === 0)
+        return new Map();
+    let processes;
     try {
-        members = (await host.listProcesses(signal)).filter(({ processGroupId }) => processGroupId === ownership.processGroupId);
+        processes = liveProcesses(await host.listProcesses(signal));
     }
     catch (cause) {
         signal?.throwIfAborted();
-        return {
+        const failure = {
             state: "unverifiable",
             reason: `process group could not be inspected: ${errorMessage(cause)}`,
         };
+        return new Map(groupIds.map((groupId) => [groupId, failure]));
     }
     signal?.throwIfAborted();
-    const liveMembers = liveProcesses(members);
-    if (liveMembers.length === 0)
-        return { state: "empty" };
-    for (const member of liveMembers) {
-        signal?.throwIfAborted();
-        try {
-            const runId = (await host.environment(member.pid)).REA_PROCESS_RUN_ID;
-            signal?.throwIfAborted();
-            if (runId !== ownership.runId)
-                return {
+    const membersByGroup = new Map(groupIds.map((groupId) => [groupId, []]));
+    for (const process of processes)
+        membersByGroup.get(process.processGroupId)?.push(process);
+    const observations = new Map(groupIds.map((groupId) => [
+        groupId,
+        (membersByGroup.get(groupId)?.length ?? 0) > 0
+            ? { state: "alive" }
+            : { state: "empty" },
+    ]));
+    const liveMembers = groupIds.flatMap((groupId) => membersByGroup.get(groupId) ?? []);
+    const pendingGroups = new Set(groupIds.filter((groupId) => (membersByGroup.get(groupId)?.length ?? 0) > 0));
+    for await (const { process: member, observation } of readProcessRunTokens(host, liveMembers, signal)) {
+        if (!pendingGroups.has(member.processGroupId))
+            continue;
+        if (observation.state === "readable") {
+            if (observation.runId !== runId) {
+                observations.set(member.processGroupId, {
                     state: "unverifiable",
                     reason: "process ownership did not match",
-                };
+                });
+                pendingGroups.delete(member.processGroupId);
+            }
         }
-        catch (cause) {
+        else {
+            const gone = await processIsGone(host, member.pid);
             signal?.throwIfAborted();
-            if (!(await processIsGone(host, member.pid))) {
-                return {
+            if (!gone) {
+                observations.set(member.processGroupId, {
                     state: "unverifiable",
-                    reason: `process ownership could not be revalidated for PID ${member.pid}: ${errorMessage(cause)}`,
-                };
+                    reason: `process ownership could not be revalidated for PID ${member.pid}: ${observation.reason}`,
+                });
+                pendingGroups.delete(member.processGroupId);
             }
         }
+        if (pendingGroups.size === 0)
+            break;
     }
-    return { state: "alive" };
+    signal?.throwIfAborted();
+    return observations;
 };
 /**
  * Record the live launcher and descendant lineage after run-token validation.
@@ -66,23 +85,22 @@ export const observeOwnedProcessLineage = async (ownership, host = systemProcess
     const identityFailure = launcherIdentityFailure(launcher, ownership);
     if (identityFailure !== null)
         return unavailableLineage(ownership, identityFailure);
-    const descendants = descendantsOf(launcher.pid, processes);
+    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)
+    for await (const { process: member, observation } of readProcessRunTokens(host, [launcher, ...descendants])) {
+        if (observation.state === "readable") {
+            if (observation.runId !== ownership.runId)
                 return unavailableLineage(ownership, "process lineage contains an unowned or PID-reused process");
             if (member.pid !== launcher.pid)
                 verifiedDescendants.push(member);
         }
-        catch (cause) {
+        else {
             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 unavailableLineage(ownership, `process ownership could not be revalidated for PID ${member.pid}: ${observation.reason}`);
         }
     }
     return {
@@ -251,14 +269,15 @@ export const createSystemProcessOwnershipHost = (platform = process.platform, ho
             }
         },
         listProcesses,
-        async environment(pid) {
+        async environment(pid, signal) {
+            signal?.throwIfAborted();
             if (platform === "linux")
-                return parseProcessEnvironment(await readFile(`/proc/${pid}/environ`, "utf8"));
+                return parseProcessEnvironment(await readFile(`/proc/${pid}/environ`, { encoding: "utf8", signal }));
             if (platform === "darwin") {
-                const process = (await listProcesses()).find((entry) => entry.pid === pid);
+                const process = (await listProcesses(signal)).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);
+                const observation = (await darwinTokens?.read([process], signal))?.get(pid);
                 if (observation === undefined || observation.state === "unavailable")
                     throw new Error(observation?.reason ?? "process run token could not be read");
                 return observation.runId === undefined
@@ -267,6 +286,7 @@ export const createSystemProcessOwnershipHost = (platform = process.platform, ho
             }
             const { stdout } = await execFileOutput("ps", ["eww", "-p", String(pid)], {
                 env: hostEnvironment,
+                ...(signal === undefined ? {} : { signal }),
             });
             const observedEnvironment = {};
             for (const match of stdout.matchAll(/(?:^|\s)([A-Za-z_][A-Za-z0-9_]*)=([^\s]*)/gu)) {
@@ -276,13 +296,16 @@ export const createSystemProcessOwnershipHost = (platform = process.platform, ho
             }
             return observedEnvironment;
         },
-        async runTokens(processes) {
+        async runTokens(processes, signal) {
+            signal?.throwIfAborted();
             if (platform !== "darwin" || processes.length === 0)
                 return new Map();
             try {
-                return (await darwinTokens?.read(processes)) ?? new Map();
+                return (await darwinTokens?.read(processes, signal)) ?? new Map();
             }
             catch (cause) {
+                if (isExpectedAbort(cause, signal))
+                    throw cause;
                 void cause;
                 return new Map(processes.map(({ pid }) => [
                     pid,
@@ -303,17 +326,51 @@ 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) => {
+/**
+ * Observe a live PID's start identity, optionally binding it to an owned run.
+ * Token validation is bracketed by identity reads so PID reuse cannot supply
+ * the first identity of a different process for an owned launch.
+ */
+export const observeProcessStartIdentity = async (pid, host = systemProcessOwnershipHost, expectedRunId) => {
     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) ?? {
+    const identity = (await host.processIdentities([process])).get(pid) ?? {
         state: "unavailable",
         reason: "process identity was not returned",
-    });
+    };
+    if (expectedRunId === undefined || identity.state !== "readable")
+        return identity;
+    let owned = false;
+    for await (const { observation } of readProcessRunTokens(host, [process])) {
+        if (observation.state === "unavailable")
+            return {
+                state: "unavailable",
+                reason: `process ownership token could not be read for PID ${String(pid)}: ${observation.reason}`,
+            };
+        if (observation.runId !== expectedRunId)
+            return {
+                state: "unavailable",
+                reason: `process ownership token did not match the captured run for PID ${String(pid)}`,
+            };
+        owned = true;
+    }
+    if (!owned)
+        return {
+            state: "unavailable",
+            reason: `process ownership token was not returned for PID ${String(pid)}`,
+        };
+    const confirmed = await observeProcessStartIdentity(pid, host);
+    if (confirmed === undefined || confirmed.state !== "readable")
+        return confirmed;
+    return confirmed.identity === identity.identity
+        ? identity
+        : {
+            state: "unavailable",
+            reason: `process identity changed while validating the captured run token for PID ${String(pid)}`,
+        };
 };
 /** Revalidate a launch-time start identity immediately before signaling a PID. */
 export const signalProcessWithStartIdentity = async (pid, expectedIdentity, signal, options = {}) => {

package/dist/process/ProcessOwnershipProcessTree.js

@@ -1,7 +1,7 @@
 /** Exclude process-table entries that the operating system has already reaped. */
 export const liveProcesses = (members) => members.filter(({ state }) => !state.startsWith("Z"));
-/** Return every live-table descendant of a launcher in breadth-first order. */
-export const descendantsOf = (launcherPid, processes) => {
+/** Return every live-table descendant of the selected roots in breadth-first order. */
+export const descendantsOf = (rootPids, processes) => {
     const childrenByParent = new Map();
     for (const process of processes) {
         const siblings = childrenByParent.get(process.parentPid) ?? [];
@@ -9,8 +9,8 @@ export const descendantsOf = (launcherPid, processes) => {
         childrenByParent.set(process.parentPid, siblings);
     }
     const descendants = [];
-    const pending = [...(childrenByParent.get(launcherPid) ?? [])];
-    const visited = new Set([launcherPid]);
+    const pending = rootPids.flatMap((pid) => childrenByParent.get(pid) ?? []);
+    const visited = new Set(rootPids);
     for (const process of pending) {
         if (visited.has(process.pid))
             continue;

package/dist/process/ProcessRunTokenObservations.js

@@ -0,0 +1,48 @@
+const errorMessage = (cause) => cause instanceof Error ? cause.message : String(cause);
+/** Read only ownership tokens, using per-process fallback for missing batch rows. */
+export async function* readProcessRunTokens(host, processes, signal) {
+    signal?.throwIfAborted();
+    if (processes.length === 0)
+        return;
+    let batch;
+    let batchFailure;
+    if (host.runTokens !== undefined) {
+        try {
+            batch =
+                signal === undefined
+                    ? await host.runTokens(processes)
+                    : await host.runTokens(processes, signal);
+        }
+        catch (cause) {
+            signal?.throwIfAborted();
+            batchFailure = errorMessage(cause);
+        }
+    }
+    for (const process of processes) {
+        signal?.throwIfAborted();
+        let observation = batch?.get(process.pid);
+        if (observation === undefined) {
+            try {
+                const environment = signal === undefined
+                    ? await host.environment(process.pid)
+                    : await host.environment(process.pid, signal);
+                observation = {
+                    state: "readable",
+                    runId: environment.REA_PROCESS_RUN_ID,
+                };
+            }
+            catch (cause) {
+                signal?.throwIfAborted();
+                const reason = errorMessage(cause);
+                observation = {
+                    state: "unavailable",
+                    reason: batchFailure === undefined
+                        ? reason
+                        : `${reason}; run-token batch failed: ${batchFailure}`,
+                };
+            }
+        }
+        signal?.throwIfAborted();
+        yield { process, observation };
+    }
+}

package/dist/process/ProviderDiagnosticRedaction.js

@@ -0,0 +1,17 @@
+/** Redact explicit transport credentials from complete and budget-cut output. */
+export const redactCapturedTransportCredential = (stream, token, replacement) => {
+    if (token === undefined || token.length === 0)
+        return stream.text;
+    const { text } = stream;
+    const cutOff = stream.observedBytes > stream.bytes;
+    if (cutOff && !text.endsWith(token)) {
+        const maximumPrefixLength = Math.min(text.length, token.length - 1);
+        for (let prefixLength = maximumPrefixLength; prefixLength > 0; prefixLength -= 1) {
+            if (text.endsWith(token.slice(0, prefixLength)))
+                return `${text
+                    .slice(0, text.length - prefixLength)
+                    .replaceAll(token, replacement)}${replacement}`;
+        }
+    }
+    return text.replaceAll(token, replacement);
+};