rea-agents 1.5.0 → 1.6.0

package/dist/application/CrossVersionInvestigationReplay.js

@@ -0,0 +1,170 @@
+import { isDeepStrictEqual } from "node:util";
+import { artifactInventoryResultSchema, } from "../domain/artifactGraph.js";
+import { parseArtifactInventoryEvidence } from "../domain/artifactInventoryEvidence.js";
+import { EvidenceIntegrityError, InvestigationWorkspaceError, } from "../domain/errors.js";
+import { err, ok } from "../domain/result.js";
+import { createArtifactComparisonEvidence, createChangedBehaviorEvidence, } from "./CrossVersionInvestigationEvidence.js";
+import { AUTOMATIC_RUN_LIMITATION } from "./CrossVersionInventory.js";
+import { ARTIFACT_GRAPH_PROVIDER } from "./InvestigationProviders.js";
+/** Select and verify one caller-identified complete run without input access. */
+export const selectCompletedInvestigationReplay = (workspace, input) => {
+    const run = workspace?.runs.find(({ run_id: runId }) => runId === input.replay_run_id);
+    if (workspace === null ||
+        run === undefined ||
+        run.status !== "complete" ||
+        !controlsMatch(run, input))
+        return replayConflict();
+    const records = new Map(workspace.bundle.records.map((record) => [record.evidence_id, record]));
+    const left = inventoryRecords(records, run.left_inventory_evidence_ids);
+    const right = inventoryRecords(records, run.right_inventory_evidence_ids);
+    if (!left.ok)
+        return left;
+    if (!right.ok)
+        return right;
+    if (!pathsMatch(left.value, input.left_path) ||
+        !pathsMatch(right.value, input.right_path))
+        return replayConflict();
+    const validated = validateLinkedEvidence(workspace, run, left.value, right.value);
+    return validated.ok ? ok({ workspace, run }) : validated;
+};
+const controlsMatch = (run, input) => isDeepStrictEqual(run.options, input.options) &&
+    run.integrity_policy === input.integrity_policy &&
+    run.integrity_continue_approved === input.integrity_continue_approved &&
+    run.max_integrity_mismatches === input.max_integrity_mismatches;
+const inventoryRecords = (records, evidenceIds) => {
+    if (new Set(evidenceIds).size !== evidenceIds.length)
+        return replayIntegrity("Investigation replay repeats inventory Evidence");
+    const selected = evidenceIds.flatMap((evidenceId) => {
+        const evidence = records.get(evidenceId);
+        return evidence === undefined ? [] : [evidence];
+    });
+    return selected.length === evidenceIds.length
+        ? ok(selected)
+        : replayIntegrity("Investigation replay is missing inventory Evidence");
+};
+const pathsMatch = (records, path) => records.every(({ subject }) => subject?.local_path === path);
+const validateLinkedEvidence = (workspace, run, leftRecords, rightRecords) => {
+    try {
+        const left = validateInventory(leftRecords, run.left, run);
+        const right = validateInventory(rightRecords, run.right, run);
+        if (!left.ok)
+            return left;
+        if (!right.ok)
+            return right;
+        const expectedLimitations = runLimitations(left.value, right.value);
+        if (!isDeepStrictEqual(run.limitations, expectedLimitations))
+            return replayIntegrity("Investigation replay limitations disagree with inventory Evidence");
+        const comparison = createArtifactComparisonEvidence({ left: left.value.records, right: right.value.records }, run.options.change_limit);
+        const storedComparison = evidenceFor(workspace, run.comparison_evidence_id);
+        if (storedComparison === undefined ||
+            !isDeepStrictEqual(storedComparison, comparison))
+            return replayIntegrity("Investigation replay comparison Evidence is inconsistent");
+        const result = createChangedBehaviorEvidence(workspace, run, comparison);
+        const storedResult = evidenceFor(workspace, run.result_evidence_id);
+        return storedResult !== undefined && isDeepStrictEqual(storedResult, result)
+            ? ok(null)
+            : replayIntegrity("Investigation replay result Evidence is inconsistent");
+    }
+    catch (cause) {
+        return replayIntegrity("Investigation replay linked Evidence is invalid", cause);
+    }
+};
+const validateInventory = (records, target, run) => {
+    const pages = records.map((record) => artifactInventoryResultSchema.parse(record.normalized_result));
+    const expectedPageCount = Math.max(1, Math.ceil((pages[0]?.manifest.node_count ?? 0) / run.options.page_size), Math.ceil((pages[0]?.manifest.occurrence_count ?? 0) / run.options.page_size), Math.ceil((pages[0]?.manifest.edge_count ?? 0) / run.options.page_size));
+    if (records.length !== expectedPageCount)
+        return replayIntegrity("Investigation replay inventory Evidence pagination is inconsistent");
+    if (!sameSnapshotMetadata(pages))
+        return replayIntegrity("Investigation replay inventory pages disagree on snapshot metadata");
+    for (const [index, record] of records.entries()) {
+        const page = pages[index];
+        if (page === undefined || !inventoryRecordMatches(record, page, run, index))
+            return replayIntegrity("Investigation replay inventory Evidence is inconsistent");
+    }
+    const result = parseArtifactInventoryEvidence(records);
+    if (!result.inventory.complete || !targetMatches(result.inventory, target))
+        return replayIntegrity("Investigation replay inventory commitment is inconsistent");
+    return ok({ records, result });
+};
+const inventoryRecordMatches = (record, page, run, index) => {
+    const offset = index * run.options.page_size;
+    const parameters = {
+        node_offset: offset,
+        node_limit: run.options.page_size,
+        occurrence_offset: offset,
+        occurrence_limit: run.options.page_size,
+        edge_offset: offset,
+        edge_limit: run.options.page_size,
+        max_entries: run.options.max_entries,
+        max_total_bytes: run.options.max_total_bytes,
+        max_entry_bytes: run.options.max_entry_bytes,
+        max_compression_ratio: run.options.max_compression_ratio,
+        max_depth: run.options.max_depth,
+        max_path_bytes: run.options.max_path_bytes,
+        integrity_policy: run.integrity_policy,
+        integrity_continue_approved: run.integrity_continue_approved,
+        max_integrity_mismatches: run.max_integrity_mismatches,
+    };
+    const locations = page.occurrences.items.map(({ logical_path: path }) => ({
+        kind: "artifact-path",
+        path,
+    }));
+    return (record.subject !== null &&
+        record.subject.name === record.subject.local_path.split("/").at(-1) &&
+        record.subject.digest.sha256 === page.manifest.root_sha256 &&
+        record.subject.format === page.manifest.root_format &&
+        record.subject.architecture === null &&
+        isDeepStrictEqual(record.provider, ARTIFACT_GRAPH_PROVIDER) &&
+        record.predicate_type === "rea.analysis/v2" &&
+        record.operation === "inventory_artifact" &&
+        isDeepStrictEqual(record.parameters, parameters) &&
+        record.raw_result === null &&
+        record.confidence === "observed" &&
+        record.authority === "shipped-artifact" &&
+        record.environment === null &&
+        isDeepStrictEqual(record.limitations, page.limitations) &&
+        isDeepStrictEqual(record.locations, locations) &&
+        record.evidence_links.length === 0 &&
+        isDeepStrictEqual(page.limits, traversalLimits(run)) &&
+        pageMatches(page.nodes, offset, run.options.page_size, page.manifest.node_count) &&
+        pageMatches(page.occurrences, offset, run.options.page_size, page.manifest.occurrence_count) &&
+        pageMatches(page.edges, offset, run.options.page_size, page.manifest.edge_count));
+};
+const sameSnapshotMetadata = (pages) => {
+    const first = pages[0];
+    return (first !== undefined &&
+        pages.every((page) => isDeepStrictEqual(page.manifest, first.manifest) &&
+            isDeepStrictEqual(page.limits, first.limits) &&
+            isDeepStrictEqual(page.provenance, first.provenance) &&
+            isDeepStrictEqual(page.integrity_contradictions, first.integrity_contradictions) &&
+            isDeepStrictEqual(page.limitations, first.limitations)));
+};
+const pageMatches = (page, offset, limit, total) => page.offset === offset &&
+    page.limit === limit &&
+    page.total === total &&
+    page.items.length === Math.max(0, Math.min(limit, page.total - offset)) &&
+    page.next_offset === (offset + limit < page.total ? offset + limit : null);
+const traversalLimits = (run) => ({
+    max_entries: run.options.max_entries,
+    max_total_bytes: run.options.max_total_bytes,
+    max_entry_bytes: run.options.max_entry_bytes,
+    max_compression_ratio: run.options.max_compression_ratio,
+    max_depth: run.options.max_depth,
+    max_path_bytes: run.options.max_path_bytes,
+});
+const targetMatches = (inventory, target) => inventory.manifest.root_sha256 === target.root_sha256 &&
+    inventory.manifest.graph_sha256 === target.graph_sha256 &&
+    inventory.manifest.manifest_id === target.manifest_id &&
+    inventory.manifest.root_format === target.format;
+const runLimitations = (left, right) => [
+    ...new Set([
+        ...left.result.inventory.limitations.map((item) => `Left: ${item}`),
+        ...right.result.inventory.limitations.map((item) => `Right: ${item}`),
+        AUTOMATIC_RUN_LIMITATION,
+    ]),
+].sort((first, second) => first.localeCompare(second));
+const evidenceFor = (workspace, evidenceId) => evidenceId === null
+    ? undefined
+    : workspace.bundle.records.find(({ evidence_id: current }) => current === evidenceId);
+const replayConflict = () => err(new InvestigationWorkspaceError("read", "revision-conflict"));
+const replayIntegrity = (message, cause) => err(new EvidenceIntegrityError(message, cause === undefined ? undefined : { cause }));

package/dist/application/Doctor.js

@@ -37,23 +37,28 @@ export const runDoctor = async (target, host = systemDoctorHost()) => {
         remediation: "REA supports macOS 12+, Ubuntu 24.04+, Fedora 41+, and 64-bit Arch Linux.",
         classification: "unsupported_host",
     }));
-    const candidates = [
-        host.configuredHopperPath,
-        DEFAULT_HOPPER,
-        SYSTEM_LINUX_HOPPER,
-        linuxHopperLauncherPath(homedir()),
-        ...(await host.manualHopperPaths()),
-        await host.brewHopperPath(),
-    ].filter((value) => value !== undefined);
+    const candidates = host.configuredHopperPath === undefined
+        ? [
+            DEFAULT_HOPPER,
+            SYSTEM_LINUX_HOPPER,
+            linuxHopperLauncherPath(homedir()),
+            ...(await host.manualHopperPaths()),
+            await host.brewHopperPath(),
+        ].filter((value) => value !== undefined)
+        : [host.configuredHopperPath];
     let hopperPath;
     for (const candidate of new Set(candidates))
         if (await host.executable(candidate)) {
             hopperPath = candidate;
             break;
         }
-    checks.push(check("hopper", hopperPath !== undefined, hopperPath, {
-        remediation: "Run rea setup to install Hopper, or set HOPPER_LAUNCHER_PATH.",
-        classification: "missing_analysis_engine",
+    checks.push(check("hopper", hopperPath !== undefined, hopperPath ?? host.configuredHopperPath, {
+        remediation: host.configuredHopperPath === undefined
+            ? "Run rea setup to install Hopper, or set HOPPER_LAUNCHER_PATH."
+            : "Unset or update HOPPER_LAUNCHER_PATH to an executable Hopper launcher.",
+        classification: host.configuredHopperPath === undefined
+            ? "missing_analysis_engine"
+            : "config_drift",
     }));
     if (host.platform === "linux" && hopperPath !== undefined)
         checks.push(check("hopper-version", await host.supportedLinuxHopper(hopperPath), hopperPath, {

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)
@@ -229,7 +229,7 @@ export class EvidenceLedger {
         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);
@@ -243,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/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/ProcessCaptureLifecycle.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,

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";
@@ -85,7 +86,7 @@ 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, {
@@ -138,7 +139,13 @@ const startCaptureRuntime = async (options) => {
             renderer,
             started,
         });
-        const stopSampler = startProcessSampler(terminal.pid, started, scenario.limits.processes, options.samples);
+        const stopSampler = startProcessSampler({
+            rootPid: terminal.pid,
+            runId: options.runId,
+            started,
+            limit: scenario.limits.processes,
+            samples: options.samples,
+        });
         return {
             replay,
             renderer,
@@ -182,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) {
@@ -209,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/ProcessOwnership.js

@@ -2,6 +2,19 @@ import { execFile } from "node:child_process";
 import { readFile } from "node:fs/promises";
 import { promisify } from "node:util";
 const execFileAsync = promisify(execFile);
+/** 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")
@@ -16,17 +29,18 @@ 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);
     },
@@ -44,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.
  *
@@ -59,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)
@@ -76,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");
     }
@@ -116,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)
@@ -136,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();

package/dist/application/ProcessSampling.js

@@ -1,8 +1,19 @@
 import { execFile } from "node:child_process";
 import { readFile, readdir } from "node:fs/promises";
 import { promisify } from "node:util";
+import { readProcessRunId } from "./ProcessOwnership.js";
 const execFileAsync = promisify(execFile);
 const PROC_READ_CONCURRENCY = 64;
+/** Prove that forkpty completed session setup and installed the run token. */
+export const isInitializedPtyRoot = (options) => options.before.pid === options.rootPid &&
+    options.before.process_group_id === options.rootPid &&
+    options.before.session_id === options.rootPid &&
+    options.after.pid === options.rootPid &&
+    options.after.parent_pid === options.before.parent_pid &&
+    options.after.process_group_id === options.rootPid &&
+    options.after.session_id === options.rootPid &&
+    options.after.startTime === options.before.startTime &&
+    options.observedRunId === options.expectedRunId;
 const isExpectedProcReadFailure = (cause) => cause instanceof Error &&
     "code" in cause &&
     (cause.code === "ENOENT" ||
@@ -214,6 +225,34 @@ const readPsRows = async (signal) => {
         row.parent_pid >= 0)
         .sort((left, right) => left.pid - right.pid);
 };
+const readRootIdentity = async (rootPid, signal) => process.platform === "linux"
+    ? readProcessStat(rootPid, signal)
+    : (await readPsRows(signal)).find(({ pid }) => pid === rootPid);
+const inspectInitializedPtyRoot = async (rootPid, runId, signal) => {
+    const before = await readRootIdentity(rootPid, signal);
+    if (before === undefined ||
+        before.process_group_id !== rootPid ||
+        before.session_id !== rootPid)
+        return undefined;
+    let observedRunId;
+    try {
+        observedRunId = await readProcessRunId(rootPid);
+    }
+    catch {
+        return undefined;
+    }
+    const after = await readRootIdentity(rootPid, signal);
+    if (after === undefined ||
+        !isInitializedPtyRoot({
+            rootPid,
+            expectedRunId: runId,
+            before,
+            observedRunId,
+            after,
+        }))
+        return undefined;
+    return { startTime: after.startTime };
+};
 const samplePs = async (context) => {
     const { rootPid, limit, signal } = context;
     if (limit <= 0)
@@ -277,25 +316,37 @@ const sampleProcesses = async (context) => {
     return samples;
 };
 /** Start bounded process-tree sampling and expose an awaited stop. */
-export const startProcessSampler = (rootPid, started, limit, samples) => {
+export const startProcessSampler = (options) => {
+    const { rootPid, runId, started, limit, samples } = options;
     const identities = new Map();
     const lastObservations = new Map();
     let pending;
     let stopped = false;
     let abortCurrent;
     let partial = false;
+    let rootInitialized = false;
     const sample = () => {
         if (stopped || pending !== undefined)
             return;
         const controller = new AbortController();
         abortCurrent = () => controller.abort();
-        pending = sampleProcesses({
-            rootPid,
-            elapsedMs: Date.now() - started,
-            limit: limit + 1,
-            identities,
-            signal: controller.signal,
-        })
+        pending = (async () => {
+            if (!rootInitialized) {
+                const identity = await inspectInitializedPtyRoot(rootPid, runId, controller.signal);
+                if (identity === undefined)
+                    return [];
+                if (identity.startTime !== undefined)
+                    identities.set(rootPid, identity.startTime);
+                rootInitialized = true;
+            }
+            return sampleProcesses({
+                rootPid,
+                elapsedMs: Date.now() - started,
+                limit: limit + 1,
+                identities,
+                signal: controller.signal,
+            });
+        })()
             .then((values) => {
             for (const value of values) {
                 const observation = JSON.stringify({

package/dist/application/ProjectPermissionStore.js

@@ -10,6 +10,7 @@ const grantSchema = z.object({
     capability: z.enum([
         "process_capture",
         "browser_observe",
+        "electron_observe",
         "evidence_read",
         "evidence_write",
         "investigation_input",