rea-agents 1.4.0 → 1.6.0

package/dist/application/ElectronEvidence.js

@@ -0,0 +1,35 @@
+import { createEvidence, } from "../domain/evidence.js";
+import { jsonValueSchema } from "../domain/jsonValue.js";
+/** Create Evidence v2 for one root-confined Electron observation. */
+export const createElectronEvidence = (operation, input, result, provider) => createEvidence(undefined, provider, {
+    predicateType: operation === "list_electron_targets"
+        ? "rea.electron-target-list/v1"
+        : "rea.electron-page-inspection/v1",
+    operation,
+    parameters: parameters(input),
+    result: jsonValueSchema.parse(result),
+    confidence: "observed",
+    authority: "external-service",
+    environment: "target" in result
+        ? {
+            id: `${result.browser.product}@${result.browser.revision}`,
+            platform: process.platform,
+            architecture: process.arch,
+            isolation: "none",
+        }
+        : null,
+    limitations: result.limitations,
+});
+const parameters = (input) => ({
+    cdp_endpoint: input.cdp_endpoint,
+    allowed_file_roots: input.allowed_file_roots,
+    ...("target_id" in input
+        ? {
+            target_id: input.target_id,
+            observation_ms: input.observation_ms,
+            include_script_sources: input.include_script_sources,
+            source_capture_approved: input.source_capture_approved,
+            limits: input.limits,
+        }
+        : { offset: input.offset, limit: input.limit }),
+});

package/dist/application/ElectronObservationPort.js

@@ -0,0 +1 @@
+export {};

package/dist/application/ElectronObservationService.js

@@ -0,0 +1,46 @@
+import { AnalysisCapabilityUnavailableError, AnalysisProtocolError, PermissionRequiredError, } from "../domain/errors.js";
+import { err, ok } from "../domain/result.js";
+import { createElectronEvidence } from "./ElectronEvidence.js";
+/** Authorize and list root-confined Electron page targets. */
+export const listElectronTargets = async (provider, authority, input, options = {}) => {
+    const ready = await prepare(provider, authority, input, "list_electron_targets");
+    if (!ready.ok)
+        return ready;
+    const result = await ready.value.listTargets(input, options);
+    return result.ok
+        ? ok(createElectronEvidence("list_electron_targets", input, result.value, ready.value.identity()))
+        : result;
+};
+/** Authorize and inspect one root-confined Electron page. */
+export const inspectElectronPage = async (provider, authority, input, options = {}) => {
+    const ready = await prepare(provider, authority, input, "inspect_electron_page");
+    if (!ready.ok)
+        return ready;
+    const result = await ready.value.inspectPage(input, options);
+    return result.ok
+        ? ok(createElectronEvidence("inspect_electron_page", input, result.value, ready.value.identity()))
+        : result;
+};
+const prepare = async (provider, authority, input, operation) => {
+    if (authority === undefined)
+        return err(new AnalysisCapabilityUnavailableError("rea-cdp-electron", operation, "Electron observation permission policy is not configured"));
+    const authorized = await authority.authorize({
+        capability: "electron_observe",
+        roots: input.allowed_file_roots,
+        executables: [],
+        environment_names: [],
+        origins: [input.cdp_endpoint],
+        network: "loopback",
+        mount: false,
+        operation_identity: `${operation}:${"target_id" in input ? input.target_id : input.cdp_endpoint}`,
+    }, "read");
+    if (!authorized.ok)
+        return err(authorized.error instanceof PermissionRequiredError
+            ? authorized.error
+            : new AnalysisProtocolError(authorized.error.message, {
+                cause: authorized.error,
+            }));
+    return provider === undefined
+        ? err(new AnalysisCapabilityUnavailableError("rea-cdp-electron", operation, "Electron observation provider is not configured"))
+        : ok(provider);
+};

package/dist/application/EvidenceLedger.js

@@ -35,7 +35,7 @@ export class EvidenceLedger {
                 ? ok("duplicate")
                 : err(new EvidenceIntegrityError("Conflicting evidence record"));
         }
-        if (this.#records.size >= this.limits.maxRecords)
+        if (this.#exceedsRecordLimit(this.#records.size + 1, this.#unknownRevisions.size))
             return err(new EvidenceLimitError("records", this.limits.maxRecords));
         const bytes = serializedBytes(evidence);
         if (this.#bytes + bytes > this.limits.maxBytes)
@@ -85,7 +85,7 @@ export class EvidenceLedger {
     }
     /** Export records in deterministic, semantically irrelevant ID order. */
     export() {
-        return createEvidenceBundle([...this.#records.values()], [...this.#unknownRevisions.values()]);
+        return structuredClone(createEvidenceBundle([...this.#records.values()], [...this.#unknownRevisions.values()]));
     }
     /** Check whether one immutable Evidence ID is present in this ledger. */
     has(evidenceId) {
@@ -162,7 +162,7 @@ export class EvidenceLedger {
         if (!checked.ok)
             return checked;
         this.#commit(pendingRecords, pendingUnknowns, checked.value);
-        return ok(unknown);
+        return ok(structuredClone(unknown));
     }
     /** Apply one approved full-state update using optimistic revision matching. */
     updateUnknown(input, mutationEvidence) {
@@ -187,7 +187,8 @@ export class EvidenceLedger {
             (filters.severity === undefined ||
                 unknown.severity === filters.severity) &&
             (filters.domain === undefined || unknown.domain === filters.domain))
-            .sort((left, right) => left.unknown_id.localeCompare(right.unknown_id));
+            .sort((left, right) => left.unknown_id.localeCompare(right.unknown_id))
+            .map((unknown) => structuredClone(unknown));
     }
     /** Return current resolution validity; imported invalid states are rejected. */
     verifyUnknownResolution(unknownId) {
@@ -197,7 +198,7 @@ export class EvidenceLedger {
         return ok({
             valid: unknown.status === "resolved",
             truthVerified: unknown.resolution?.disposition === "verified",
-            unknown,
+            unknown: structuredClone(unknown),
         });
     }
     /** Clear records when the owning session closes. */
@@ -225,10 +226,10 @@ export class EvidenceLedger {
         if (!checked.ok)
             return checked;
         this.#commit(pendingRecords, pendingUnknowns, checked.value);
-        return ok(unknown);
+        return ok(structuredClone(unknown));
     }
     #validateCandidate(records, unknowns) {
-        if (records.size + unknowns.size > this.limits.maxRecords)
+        if (this.#exceedsRecordLimit(records.size, unknowns.size))
             return err(new EvidenceLimitError("records", this.limits.maxRecords));
         const bytes = [...records.values()].reduce((total, evidence) => total + serializedBytes(evidence), 0) +
             [...unknowns.values()].reduce((total, unknown) => total + serializedBytes(unknown), 0);
@@ -242,6 +243,9 @@ export class EvidenceLedger {
         }
         return ok(bytes);
     }
+    #exceedsRecordLimit(recordCount, unknownCount) {
+        return recordCount + unknownCount > this.limits.maxRecords;
+    }
     #commit(records, unknowns, bytes) {
         this.#records.clear();
         for (const [id, evidence] of records)

package/dist/application/InvestigationWorkspaceStore.js

@@ -1,6 +1,7 @@
 import { lstat, open, readFile, realpath, unlink, } from "node:fs/promises";
 import { basename, dirname, isAbsolute, relative, resolve } from "node:path";
 import writeFileAtomic from "write-file-atomic";
+import { isJsonWithinLimits } from "../domain/jsonLimits.js";
 import { InvestigationWorkspaceError } from "../domain/errors.js";
 import { parseInvestigationWorkspace, serializeInvestigationWorkspace, } from "../domain/investigationWorkspace.js";
 import { err, ok } from "../domain/result.js";
@@ -97,7 +98,7 @@ const readWorkspaceFile = async (destination, policy) => {
     catch (cause) {
         return err(new InvestigationWorkspaceError("read", "invalid-json", { cause }));
     }
-    if (!withinJsonLimits(decoded, policy))
+    if (!isJsonWithinLimits(decoded, policy))
         return err(new InvestigationWorkspaceError("read", "too-large"));
     try {
         return ok(parseInvestigationWorkspace(decoded));
@@ -182,31 +183,6 @@ const validateNextRevision = (current, next, expectedRevision) => {
         ? ok(null)
         : err(new InvestigationWorkspaceError("update", "revision-conflict"));
 };
-const withinJsonLimits = (root, policy) => {
-    const pending = [
-        { value: root, depth: 0 },
-    ];
-    let nodes = 0;
-    while (pending.length > 0) {
-        const current = pending.pop();
-        if (current === undefined)
-            break;
-        nodes += 1;
-        if (nodes > policy.maxNodes || current.depth > policy.maxDepth)
-            return false;
-        if (typeof current.value === "string" &&
-            current.value.length > policy.maxStringLength)
-            return false;
-        if (typeof current.value !== "object" || current.value === null)
-            continue;
-        for (const [key, value] of Object.entries(current.value)) {
-            if (key.length > policy.maxStringLength)
-                return false;
-            pending.push({ value, depth: current.depth + 1 });
-        }
-    }
-    return true;
-};
 const isFileNotFound = (cause) => errorCode(cause) === "ENOENT";
 const isAlreadyExists = (cause) => errorCode(cause) === "EEXIST";
 const errorCode = (cause) => typeof cause === "object" && cause !== null && "code" in cause

package/dist/application/PermissionAuthority.js

@@ -150,6 +150,36 @@ export class PermissionAuthority {
         this.policy = candidate;
         return ok(null);
     }
+    /** Atomically replace reloadable ceilings and persisted grants. */
+    async replaceConfiguredPolicy(configuration) {
+        const ceilings = await canonicalizePermissionCeilings(configuration.ceilings);
+        if (!ceilings.ok)
+            return ceilings;
+        const grants = [];
+        for (const grant of [
+            ...configuration.administratorGrants,
+            ...configuration.projectGrants,
+        ]) {
+            const canonical = await canonicalizeGrant(grant);
+            if (!canonical.ok)
+                return canonical;
+            grants.push(canonical.value);
+        }
+        let candidate = {
+            ...reloadPermissionCeilings(this.policy, ceilings.value),
+            grants: this.policy.grants.filter(({ lifetime }) => lifetime !== "administrator" && lifetime !== "project"),
+        };
+        for (const grant of grants) {
+            const added = grantPermission(candidate, grant);
+            if (!added.ok)
+                return err(new PermissionPathError(grant.grant_id, "io", {
+                    cause: added.error,
+                }));
+            candidate = added.value;
+        }
+        this.policy = candidate;
+        return ok(null);
+    }
     /** Replace ceilings without restarting the MCP process. */
     async reload(ceilings) {
         const canonical = await canonicalizePermissionCeilings(ceilings);

package/dist/application/ProcessCaptureAuthority.js

@@ -1,14 +1,15 @@
 import { realpath } from "node:fs/promises";
 import { ProcessCaptureError, processCaptureCancelled, } from "./ProcessCaptureError.js";
+import { canonicalizeConfiguredRoots } from "./ConfiguredRoots.js";
 const isWithin = (candidate, root) => candidate === root ||
     candidate.startsWith(`${root.endsWith("/") ? root.slice(0, -1) : root}/`);
 export const assertRealPathAuthority = async (scenario, policy) => {
     const executable = await realpath(scenario.executable);
-    const executableRoots = await Promise.all(policy.executableRoots.map((root) => realpath(root)));
+    const executableRoots = await canonicalizeConfiguredRoots(policy.executableRoots);
     if (!executableRoots.some((root) => isWithin(executable, root)))
         throw new ProcessCaptureError("resolved executable is outside approved roots");
     const workingDirectory = await realpath(scenario.working_directory);
-    const workingRoots = await Promise.all(policy.workingRoots.map((root) => realpath(root)));
+    const workingRoots = await canonicalizeConfiguredRoots(policy.workingRoots);
     if (!workingRoots.some((root) => isWithin(workingDirectory, root)))
         throw new ProcessCaptureError("resolved working directory is outside approved roots");
     for (const root of scenario.filesystem_roots) {

package/dist/application/ProcessCaptureLifecycle.js

@@ -1,6 +1,6 @@
 import { createHash, randomUUID } from "node:crypto";
 import { createReadStream } from "node:fs";
-import { mkdtemp, rm } from "node:fs/promises";
+import { mkdir, mkdtemp, rm } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { authorizeProcessScenario, digestProcessCommitment, processComparisonContract, processScenarioCommitment, } from "../domain/processCapture.js";
@@ -193,11 +193,7 @@ export const releaseProcessResources = async (options) => {
         failure ??= "filesystem checkpoint cleanup failed";
     }
     if (options.terminal !== undefined && process.platform !== "win32") {
-        const processGroupIds = new Set([
-            options.terminal.pid,
-            ...options.sampledProcessGroupIds,
-        ]);
-        for (const processGroupId of processGroupIds) {
+        for (const processGroupId of new Set(options.capturedProcessGroupIds)) {
             const cleaned = await cleanupOwnedProcessGroup({
                 runId: options.runId,
                 leaderPid: processGroupId,
@@ -219,7 +215,6 @@ export const captureTerminalFrames = (options) => {
     let outputBytes = 0;
     let truncated = false;
     options.terminal.onData((data) => {
-        options.onFirstOutput();
         options.onOutput();
         const bytes = Buffer.byteLength(data);
         if (options.frames.length >= options.scenario.limits.frames ||
@@ -256,7 +251,7 @@ export const resolveProcessResult = (capture, executionFailure, cleanupFailure)
         throw new ProcessCaptureError("process capture produced no result");
     return capture;
 };
-export const prepareProcessCapture = async (scenario, policy, signal) => {
+export const prepareProcessCapture = async (scenario, policy, signal, host = systemProcessPreparationHost) => {
     const decision = authorizeProcessScenario(scenario, policy);
     if (!decision.allowed)
         throw new ProcessCaptureError(decision.reason, {
@@ -266,11 +261,22 @@ export const prepareProcessCapture = async (scenario, policy, signal) => {
     await assertRealPathAuthority(scenario, policy);
     assertNotCancelled(signal);
     const before = await snapshotRoots(scenario, signal);
-    const temporaryRoot = await mkdtemp(join(tmpdir(), "rea-process-"));
-    const runId = randomUUID();
-    const home = join(temporaryRoot, "home");
-    await import("node:fs/promises").then(({ mkdir }) => mkdir(home));
-    return { temporaryRoot, runId, home, before };
+    const temporaryRoot = await host.createTemporaryRoot();
+    try {
+        const runId = randomUUID();
+        const home = join(temporaryRoot, "home");
+        await host.createHome(home);
+        return { temporaryRoot, runId, home, before };
+    }
+    catch (cause) {
+        await host.cleanup(temporaryRoot);
+        throw cause;
+    }
+};
+const systemProcessPreparationHost = {
+    createTemporaryRoot: () => mkdtemp(join(tmpdir(), "rea-process-")),
+    createHome: (path) => mkdir(path),
+    cleanup: (path) => rm(path, { recursive: true, force: true }),
 };
 const processPolicyMessage = (reason) => {
     if (reason === "process capture is disabled")

package/dist/application/ProcessCheckpoints.js

@@ -105,7 +105,7 @@ export class ProcessCheckpoints {
             effects: classifyFilesystemEffects(previous, after.files),
             truncated: after.truncated,
         });
-        return this.#captures;
+        return structuredClone(this.#captures);
     }
     /** Cancel scheduled captures and await any snapshot already in progress. */
     async dispose() {

package/dist/application/ProcessCli.js

@@ -79,7 +79,13 @@ export const compareProcessEvidenceFiles = async (leftPath, rightPath) => {
     }
 };
 const parseCaptureEvidence = (input) => {
-    const evidence = parseEvidence(input);
+    let evidence;
+    try {
+        evidence = parseEvidence(input);
+    }
+    catch {
+        throw invalidCaptureEvidence();
+    }
     if (evidence.operation !== "capture_process_scenario" ||
         evidence.predicate_type !== "rea.process-capture/v4" ||
         evidence.provider.id !== PROCESS_PROVIDER.id ||
@@ -88,11 +94,17 @@ const parseCaptureEvidence = (input) => {
             throw new ProcessCliFailure("invalid_input", LEGACY_PROCESS_CAPTURE_MESSAGE);
         throw new ProcessCliFailure("invalid_input", "Capture evidence is not from the current process-capture workflow. Create new capture evidence, then try again.");
     }
-    return {
-        id: evidence.evidence_id,
-        capture: parseProcessCapture(evidence.normalized_result),
-    };
+    try {
+        return {
+            id: evidence.evidence_id,
+            capture: parseProcessCapture(evidence.normalized_result),
+        };
+    }
+    catch {
+        throw invalidCaptureEvidence();
+    }
 };
+const invalidCaptureEvidence = () => new ProcessCliFailure("invalid_input", "Capture evidence is malformed. Create new capture evidence, then try again.");
 const readJson = async (path) => {
     let bytes;
     try {

package/dist/application/ProcessHarness.js

@@ -10,6 +10,7 @@ import { ProcessCheckpoints } from "./ProcessCheckpoints.js";
 import { TerminalRenderer } from "./TerminalRenderer.js";
 import { startCommandShimReplay, } from "./CommandShimReplay.js";
 import { normalizeProcessText } from "./ProcessNormalization.js";
+import { selectCapturedProcessGroupIds } from "./ProcessOwnership.js";
 import { awaitTerminalExit, buildCaptureResult, captureTerminalFrames, createRunManifest, observeSettlement, prepareProcessCapture, releaseProcessResources, resolveProcessResult, } from "./ProcessCaptureLifecycle.js";
 import { assertNotCancelled } from "./ProcessCaptureAuthority.js";
 export { probeProcessCaptureCapability } from "./ProcessCaptureCapability.js";
@@ -81,21 +82,11 @@ const scheduleScenarioEvents = (options) => {
         timers.add(timer);
     }
 };
-const startScenarioEvents = (options) => {
-    let eventsStarted = false;
-    return () => {
-        if (eventsStarted)
-            return;
-        eventsStarted = true;
-        scheduleScenarioEvents(options);
-    };
-};
-const eventsRequireReadiness = (scenario) => scenario.events.some((event) => event.type === "input" || event.type === "resize");
 const cleanupFailedStartup = async (options) => {
     options.terminal?.kill("SIGKILL");
     const cleanupFailure = await releaseProcessResources({
         ...options,
-        sampledProcessGroupIds: [],
+        capturedProcessGroupIds: options.terminal === undefined ? [] : [options.terminal.pid],
     });
     if (cleanupFailure !== undefined)
         throw new ProcessCaptureError(cleanupFailure, {
@@ -134,24 +125,27 @@ const startCaptureRuntime = async (options) => {
             rows: scenario.terminal.rows,
             name: "xterm-256color",
         });
-        const startEvents = startScenarioEvents({
-            ...options,
-            getTerminal: () => terminal,
-            renderer,
-            started,
-        });
-        if (!eventsRequireReadiness(scenario))
-            startEvents();
         const framesTruncated = captureTerminalFrames({
             ...options,
             terminal,
             started,
             onOutput: () => (lastOutput = Date.now()),
-            onFirstOutput: startEvents,
             renderer,
             checkpoints,
         });
-        const stopSampler = startProcessSampler(terminal.pid, started, scenario.limits.processes, options.samples);
+        scheduleScenarioEvents({
+            ...options,
+            getTerminal: () => terminal,
+            renderer,
+            started,
+        });
+        const stopSampler = startProcessSampler({
+            rootPid: terminal.pid,
+            runId: options.runId,
+            started,
+            limit: scenario.limits.processes,
+            samples: options.samples,
+        });
         return {
             replay,
             renderer,
@@ -195,7 +189,9 @@ const finishProcessRun = async (options) => {
         checkpoints: options.runtime?.checkpoints,
         runId: options.runId,
         temporaryRoot: options.temporaryRoot,
-        sampledProcessGroupIds: options.samples.flatMap(({ process_group_id }) => process_group_id === null ? [] : [process_group_id]),
+        capturedProcessGroupIds: options.runtime === undefined
+            ? []
+            : selectCapturedProcessGroupIds(options.runtime.terminal.pid, options.samples),
     });
     let { capture, executionFailure } = options;
     if (capture !== undefined) {
@@ -222,10 +218,7 @@ const completeCapture = async (options) => {
     const { reason } = options.exit;
     if (reason === "cancelled")
         throw processCaptureCancelled();
-    const settlement = await observeSettlement(options.runId, [
-        runtime.terminal.pid,
-        ...options.samples.flatMap(({ process_group_id }) => process_group_id === null ? [] : [process_group_id]),
-    ], scenario.settle_ms);
+    const settlement = await observeSettlement(options.runId, selectCapturedProcessGroupIds(runtime.terminal.pid, options.samples), scenario.settle_ms);
     runtime.checkpoints.trigger("settled");
     const samplingPartial = (await runtime.stopSampler()).partial;
     assertNotCancelled(options.signal);

package/dist/application/ProcessNormalization.js

@@ -14,7 +14,7 @@ export const normalizeProcessText = (value, scenario, temporaryRoot, pid) => {
             normalized = normalized.replaceAll(root, `<filesystem-root-${String(index)}>`);
     }
     if (scenario.normalization.pids)
-        normalized = normalized.replaceAll(String(pid), "<pid>");
+        normalized = normalizePidTokens(normalized, [pid]);
     if (scenario.normalization.ports)
         normalized = normalized.replaceAll(/(?<=[:=])\d{2,5}\b/g, "<port>");
     for (const pattern of scenario.normalization.patterns)
@@ -35,6 +35,12 @@ export const normalizeProcessSamples = (samples, scenario, rootPid) => {
     for (const identifier of identifiers)
         if (identifier > 0 && !mapping.has(identifier))
             mapping.set(identifier, mapping.size + 1);
+    const normalizeCommand = (command) => {
+        const normalized = normalizeProcessText(command, scenario, "<no-temporary-root>", rootPid);
+        return scenario.normalization.pids
+            ? normalizePidTokens(normalized, identifiers)
+            : normalized;
+    };
     return samples.map((sample) => ({
         at_ms: Math.floor(sample.at_ms / scenario.normalization.time_bucket_ms) *
             scenario.normalization.time_bucket_ms,
@@ -44,9 +50,18 @@ export const normalizeProcessSamples = (samples, scenario, rootPid) => {
             ? null
             : (mapping.get(sample.process_group_id) ?? 0),
         session_id: sample.session_id === null ? null : (mapping.get(sample.session_id) ?? 0),
-        command: normalizeProcessText(sample.command, scenario, "<no-temporary-root>", rootPid),
+        command: normalizeCommand(sample.command),
     }));
 };
+const normalizePidTokens = (value, identifiers) => {
+    const tokens = [...new Set(identifiers)]
+        .filter((identifier) => Number.isSafeInteger(identifier) && identifier > 0)
+        .sort((left, right) => right - left)
+        .map(String);
+    if (tokens.length === 0)
+        return value;
+    return value.replace(new RegExp(`(?<!\\d)(?:${tokens.join("|")})(?!\\d)`, "gu"), "<pid>");
+};
 export const redactProtocolEvents = (events, scenario) => events.map((event) => ({
     ...event,
     data: normalizeProcessText(event.data, scenario, "<no-temporary-root>", -1),

package/dist/application/ProcessOwnership.js

@@ -2,9 +2,23 @@ import { execFile } from "node:child_process";
 import { readFile } from "node:fs/promises";
 import { promisify } from "node:util";
 const execFileAsync = promisify(execFile);
-const parseEnvironment = (value) => Object.fromEntries(value
+/** Select the PTY root group and groups led by an observed captured process. */
+export const selectCapturedProcessGroupIds = (rootPid, samples) => {
+    const processGroupIds = new Set([rootPid]);
+    for (const sample of samples) {
+        // A sampled member may transiently inherit an unrelated group. POSIX group
+        // leaders have pid === pgid, so only that observation establishes that the
+        // group leader itself belonged to the captured tree. Token checks below
+        // remain the final authority immediately before observation or signaling.
+        if (sample.pid === sample.process_group_id)
+            processGroupIds.add(sample.pid);
+    }
+    return [...processGroupIds];
+};
+/** Parse the NUL-delimited Linux process environment without nameless keys. */
+export const parseProcessEnvironment = (value) => Object.fromEntries(value
     .split("\0")
-    .filter((entry) => entry.includes("="))
+    .filter((entry) => entry.indexOf("=") > 0)
     .map((entry) => {
     const separator = entry.indexOf("=");
     return [entry.slice(0, separator), entry.slice(separator + 1)];
@@ -15,23 +29,24 @@ const systemHost = {
             return [];
         const { stdout } = await execFileAsync("ps", [
             "-axo",
-            "pid=,ppid=,pgid=,command=",
+            "pid=,ppid=,pgid=,stat=,command=",
         ]);
         return stdout
             .split("\n")
-            .map((line) => /\s*(\d+)\s+(\d+)\s+(\d+)\s+(.*)/u.exec(line))
+            .map((line) => /\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]),
-            command: match[4] ?? "",
+            state: match[4] ?? "",
+            command: match[5] ?? "",
         }))
             .filter((member) => member.processGroupId === processGroupId);
     },
     async environment(pid) {
         if (process.platform === "linux") {
-            return parseEnvironment(await readFile(`/proc/${pid}/environ`, "utf8"));
+            return parseProcessEnvironment(await readFile(`/proc/${pid}/environ`, "utf8"));
         }
         const { stdout } = await execFileAsync("ps", ["eww", "-p", String(pid)]);
         const environment = {};
@@ -43,6 +58,8 @@ const systemHost = {
         process.kill(-processGroupId, signal);
     },
 };
+/** 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;
 /**
  * Verify run-token ownership before signaling a POSIX process group.
  *
@@ -58,9 +75,10 @@ export const cleanupOwnedProcessGroup = async (ownership, host = systemHost) =>
     catch {
         return { cleaned: false, reason: "process group could not be inspected" };
     }
-    if (members.length === 0)
+    const liveMembers = liveProcessGroupMembers(members);
+    if (liveMembers.length === 0)
         return { cleaned: true, signaled: false };
-    const leader = members.find((member) => member.pid === ownership.leaderPid);
+    const leader = liveMembers.find((member) => member.pid === ownership.leaderPid);
     if (leader !== undefined) {
         if (ownership.expectedParentPid !== undefined &&
             leader.parentPid !== ownership.expectedParentPid)
@@ -75,24 +93,25 @@ export const cleanupOwnedProcessGroup = async (ownership, host = systemHost) =>
                 reason: "owned launcher command identity did not match",
             };
     }
-    for (const member of members) {
-        let environment;
+    const failures = [];
+    for (const member of liveMembers) {
         try {
-            environment = await host.environment(member.pid);
+            const environment = await host.environment(member.pid);
+            if (environment.REA_PROCESS_RUN_ID !== ownership.runId)
+                failures.push({ pid: member.pid, reason: "run-token-mismatch" });
         }
         catch {
-            return {
-                cleaned: false,
-                reason: "process ownership could not be revalidated",
-            };
-        }
-        if (environment.REA_PROCESS_RUN_ID !== ownership.runId) {
-            return {
-                cleaned: false,
-                reason: "process group contains an unowned or PID-reused process",
-            };
+            failures.push({ pid: member.pid, reason: "environment-unreadable" });
         }
     }
+    if (failures.length > 0)
+        return {
+            cleaned: false,
+            reason: failures.some(({ reason }) => reason === "run-token-mismatch")
+                ? "process group contains an unowned or PID-reused process"
+                : "process ownership could not be revalidated",
+            failures,
+        };
     try {
         host.signalGroup(ownership.processGroupId, "SIGKILL");
     }
@@ -115,9 +134,10 @@ export const observeOwnedProcessGroup = async (ownership, host = systemHost) =>
             reason: "process group could not be inspected",
         };
     }
-    if (members.length === 0)
+    const liveMembers = liveProcessGroupMembers(members);
+    if (liveMembers.length === 0)
         return { state: "empty" };
-    for (const member of members) {
+    for (const member of liveMembers) {
         try {
             if ((await host.environment(member.pid)).REA_PROCESS_RUN_ID !==
                 ownership.runId)
@@ -135,6 +155,7 @@ export const observeOwnedProcessGroup = async (ownership, host = systemHost) =>
     }
     return { state: "alive" };
 };
+const liveProcessGroupMembers = (members) => members.filter(({ state }) => !state.startsWith("Z"));
 const commandMatches = (actual, expected) => {
     const normalizedActual = actual.trim();
     const normalizedExpected = expected.trim();