rea-agents 3.0.0 → 3.1.0

package/dist/main/transport.js

@@ -1,28 +1,30 @@
 import { createServer, } from "../server/createServer.js";
 import { MCP_CONNECTION_LOST, MCP_CONNECTION_START_FAILED, } from "./messages.js";
 export const startMcpTransport = async (dependencies, session, serverContext) => {
-    const liveServers = new Set();
     const { serverLogger } = serverContext;
+    let optionalProviders = {};
+    try {
+        optionalProviders = await serverContext.loadOptionalProviders();
+    }
+    catch {
+        serverLogger.warn("Optional MCP providers could not load; affected tools remain unavailable");
+    }
     let handle;
     try {
-        handle = dependencies.serve(() => {
-            const server = (dependencies.createServer ?? createServer)(session, session, {
-                logger: serverContext.logger,
-                processPolicy: serverContext.runtimeState.processPolicy,
-                evidenceFilePolicy: serverContext.runtimeState.evidencePolicy,
-                investigationInputRoots: serverContext.runtimeState.investigationRoots,
-                analysisSnapshotFilePolicy: serverContext.runtimeState.snapshotPolicy,
-                permissionAuthority: serverContext.permissionAuthority,
-                loadOptionalProviders: serverContext.loadOptionalProviders,
-                artifactIntegrityContinueEnabled: () => serverContext.runtimeState.currentConfig
-                    .artifactIntegrityContinueEnabled,
-                javascriptReplayPolicy: serverContext.runtimeState.javascriptReplayPolicy,
-                managedRuntimePolicy: serverContext.runtimeState.managedRuntimePolicy,
-                availabilityPolicy: () => runtimeAvailability(serverContext.runtimeState),
-            });
-            liveServers.add(server);
-            return server;
-        }, {
+        handle = dependencies.serve(() => (dependencies.createServer ?? createServer)(session, session, {
+            logger: serverContext.logger,
+            processPolicy: () => serverContext.runtimeState.currentConfig.processExecutionPolicy,
+            evidenceFilePolicy: serverContext.runtimeState.evidencePolicy,
+            investigationInputRoots: serverContext.runtimeState.investigationRoots,
+            analysisSnapshotFilePolicy: serverContext.runtimeState.snapshotPolicy,
+            permissionAuthority: serverContext.permissionAuthority,
+            ...optionalProviders,
+            artifactIntegrityContinueEnabled: () => serverContext.runtimeState.currentConfig
+                .artifactIntegrityContinueEnabled,
+            javascriptReplayPolicy: () => serverContext.runtimeState.currentConfig.javascriptReplayPolicy,
+            managedRuntimePolicy: () => serverContext.runtimeState.currentConfig.managedRuntimePolicy,
+            availabilityPolicy: () => runtimeAvailability(serverContext.runtimeState),
+        }), {
             onerror: () => {
                 serverLogger.error(MCP_CONNECTION_LOST);
                 dependencies.writeStderr(`${MCP_CONNECTION_LOST}\n`);
@@ -35,26 +37,17 @@ export const startMcpTransport = async (dependencies, session, serverContext) =>
         dependencies.writeStderr(`${MCP_CONNECTION_START_FAILED}\n`);
         return { ok: false };
     }
-    return { ok: true, handle, liveServers };
+    return { ok: true, handle };
 };
 const runtimeAvailability = (state) => ({
-    processCaptureEnabled: state.currentConfig.processExecutionPolicy.enabled,
+    processCaptureEnabled: state.currentConfig.processExecutionPolicy.status === "enabled",
     evidenceFileRoots: state.currentConfig.evidenceFilePolicy.roots.length,
     investigationInputRoots: state.currentConfig.investigationInputRoots.length,
-    browserObservationEnabled: state.currentConfig.browserObservationEnabled &&
-        state.currentConfig.browserCdpEndpoints.length > 0 &&
-        state.currentConfig.browserAllowedOrigins.length > 0,
-    browserScenarioEnabled: state.currentConfig.browserScenarioPolicy.enabled &&
-        state.currentConfig.browserScenarioPolicy.allowedOrigins.length > 0 &&
-        (state.currentConfig.browserScenarioPolicy.executableRoots.length > 0 ||
-            state.currentConfig.browserScenarioPolicy.cdpEndpoints.length > 0),
-    electronObservationEnabled: state.currentConfig.electronObservationEnabled &&
-        state.currentConfig.electronCdpEndpoints.length > 0 &&
-        state.currentConfig.electronFileRoots.length > 0,
-    v8InspectorObservationEnabled: state.currentConfig.v8InspectorObservationEnabled &&
-        state.currentConfig.v8InspectorEndpoints.length > 0 &&
-        (state.currentConfig.v8InspectorFileRoots.length > 0 ||
-            state.currentConfig.v8InspectorAllowedOrigins.length > 0),
-    javascriptReplayEnabled: state.currentConfig.javascriptReplayPolicy.enabled,
-    managedRuntimeEnabled: state.currentConfig.managedRuntimePolicy.enabled,
+    browserObservationEnabled: state.currentConfig.browserObservationPolicy.status === "enabled",
+    browserScenarioEnabled: state.currentConfig.browserScenarioPolicy.status === "enabled",
+    electronObservationEnabled: state.currentConfig.electronObservationPolicy.status === "enabled",
+    electronAutomationEnabled: state.currentConfig.electronAutomationPolicy.status === "enabled",
+    v8InspectorObservationEnabled: state.currentConfig.v8InspectorObservationPolicy.status === "enabled",
+    javascriptReplayEnabled: state.currentConfig.javascriptReplayPolicy.status === "enabled",
+    managedRuntimeEnabled: state.currentConfig.managedRuntimePolicy.status === "enabled",
 });

package/dist/main.js

@@ -63,20 +63,23 @@ export const run = async (dependencies = runtimeDependencies()) => {
     const transport = await startMcpTransport(dependencies, session, {
         logger,
         serverLogger,
-        loadOptionalProviders: async () => {
-            const [{ CdpBrowserProvider }, { PlaywrightBrowserScenarioProvider }, { CdpElectronProvider }, { V8InspectorProvider },] = await Promise.all([
-                import("./browser/CdpBrowserProvider.js"),
-                import("./browser/PlaywrightBrowserScenarioProvider.js"),
-                import("./browser/CdpElectronProvider.js"),
-                import("./browser/V8InspectorProvider.js"),
-            ]);
-            return {
-                browserObservation: new CdpBrowserProvider(),
-                browserScenarioCapture: new PlaywrightBrowserScenarioProvider(),
-                electronObservation: new CdpElectronProvider(),
-                javascriptRuntimeObservation: new V8InspectorProvider(),
-            };
-        },
+        loadOptionalProviders: dependencies.loadOptionalProviders ??
+            (async () => {
+                const [{ CdpBrowserProvider }, { PlaywrightBrowserScenarioProvider }, { CdpElectronProvider }, { PlaywrightElectronActiveProvider }, { V8InspectorProvider },] = await Promise.all([
+                    import("./browser/CdpBrowserProvider.js"),
+                    import("./browser/PlaywrightBrowserScenarioProvider.js"),
+                    import("./browser/CdpElectronProvider.js"),
+                    import("./browser/PlaywrightElectronActiveProvider.js"),
+                    import("./browser/V8InspectorProvider.js"),
+                ]);
+                return {
+                    browserObservation: new CdpBrowserProvider(),
+                    browserScenarioCapture: new PlaywrightBrowserScenarioProvider(),
+                    electronObservation: new CdpElectronProvider(),
+                    electronActiveObservation: new PlaywrightElectronActiveProvider(),
+                    javascriptRuntimeObservation: new V8InspectorProvider(),
+                };
+            }),
         permissionAuthority: permissionAuthority.value,
         runtimeState,
     });
@@ -86,7 +89,6 @@ export const run = async (dependencies = runtimeDependencies()) => {
         dependencies,
         permissionAuthority: permissionAuthority.value,
         runtimeState,
-        liveServers: transport.liveServers,
         serverLogger,
     });
     createShutdown({

package/dist/mcpDoctor.js

@@ -4,6 +4,7 @@ import { Formatter } from "incur";
 import { resolve } from "node:path";
 import { CATALOG_IDENTITY, MCP_RESOURCE_CATALOG, MCP_RESOURCE_TEMPLATE_CATALOG, } from "./catalogIdentity.js";
 import { PROMPT_CONTRACTS } from "./contracts/promptContracts.js";
+import { TOOL_CONTRACTS } from "./contracts/toolContracts.js";
 import { PRODUCT_IDENTITY } from "./identity.js";
 import { MCP_STARTUP_POLICY } from "./mcpStartupPolicy.js";
 const STDERR_LIMIT_BYTES = 64 * 1_024;
@@ -63,9 +64,8 @@ const inspectProductionMcpSession = async (client, deadline, signal) => {
         client.readResource({ uri: "rea://server/identity" }, request),
         client.callTool({ name: "binary_session", arguments: { detail: "full" } }, request),
     ]);
-    const expectedToolNames = availableToolNames(requestFlow.structuredContent) ?? [];
     const inventory = {
-        tools: compareInventory(expectedToolNames, tools.tools.map(({ name }) => name)),
+        tools: compareInventory(TOOL_CONTRACTS.map(({ name }) => name), tools.tools.map(({ name }) => name)),
         prompts: compareInventory(PROMPT_CONTRACTS.map(({ name }) => name), prompts.prompts.map(({ name }) => name)),
         resources: compareInventory(MCP_RESOURCE_CATALOG.map(({ name }) => name), resources.resources.map(({ name }) => name)),
         resource_templates: compareInventory(MCP_RESOURCE_TEMPLATE_CATALOG.map(({ name }) => name), templates.resourceTemplates.map(({ name }) => name)),
@@ -117,28 +117,6 @@ const inspectProductionMcpSession = async (client, deadline, signal) => {
         checks,
     };
 };
-const availableToolNames = (structuredContent) => {
-    if (typeof structuredContent !== "object" || structuredContent === null)
-        return undefined;
-    const result = Reflect.get(structuredContent, "result");
-    if (typeof result !== "object" || result === null)
-        return undefined;
-    const availability = Reflect.get(result, "tool_availability");
-    if (!Array.isArray(availability))
-        return undefined;
-    const names = [];
-    for (const item of availability) {
-        if (typeof item !== "object" || item === null)
-            return undefined;
-        const name = Reflect.get(item, "name");
-        const available = Reflect.get(item, "available");
-        if (typeof name !== "string" || typeof available !== "boolean")
-            return undefined;
-        if (available)
-            names.push(name);
-    }
-    return names;
-};
 /**
  * Dispatcher entry for `rea mcp doctor`, kept separate from Incur MCP setup.
  * @public

package/dist/process/PrivateRuntimeRoot.js

@@ -1,6 +1,19 @@
 import { chmod, mkdtemp, rm } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
+import { windowsNativeCapabilities, } from "./WindowsAuthority.js";
+/** Report whether this process can establish a private runtime root. */
+export const privateRuntimeRootCapability = (platform = process.platform) => platform === "win32"
+    ? windowsNativeCapabilities(platform).private_runtime_dacl
+    : { available: true, reason: null, proof: "posix-mode-0700" };
+/** Expected failure when a runtime root's privacy boundary is unavailable. */
+export class PrivateRuntimeRootUnavailableError extends Error {
+    code = "private-runtime-root-authority-unavailable";
+    constructor(message) {
+        super(message);
+        this.name = "PrivateRuntimeRootUnavailableError";
+    }
+}
 /**
  * Owns one POSIX mode-0700 temporary runtime root and removes it idempotently.
  *
@@ -16,6 +29,10 @@ export class PrivateRuntimeRoot {
     }
     /** Allocate a new private runtime root without performing protocol work. */
     static async create(options = {}) {
+        const platform = options.platform ?? process.platform;
+        const capability = privateRuntimeRootCapability(platform);
+        if (!capability.available)
+            throw new PrivateRuntimeRootUnavailableError(capability.reason);
         const path = await mkdtemp(join(options.parent ?? tmpdir(), options.prefix ?? "rea-provider-"));
         try {
             await chmod(path, 0o700);

package/dist/process/ProcessOwnership.js

@@ -1,13 +1,16 @@
 import { execFile } from "node:child_process";
 import { readFile } from "node:fs/promises";
 import { promisify } from "node:util";
-import { matchesOwnedProcessCommand } from "./ProcessCommandIdentity.js";
+import { observeOwnedProcessGroupWithHost, observeOwnedProcessLineageWithHost, } from "./ProcessOwnershipObservation.js";
+import { launcherIdentityFailure } from "./ProcessOwnershipIdentity.js";
+import { descendantsOf, liveProcesses } from "./ProcessOwnershipProcessTree.js";
 const execFileAsync = promisify(execFile);
 /**
  * Terminate one Windows process tree through the platform utility.
  *
  * This is a bounded P0 cleanup mechanism, not Job Object ownership proof. The
- * caller-visible Windows limitations must preserve that distinction.
+ * caller-visible Windows capability report remains unavailable until a native
+ * authority verifies Job Object creation, membership, and cleanup semantics.
  */
 export const cleanupWindowsProcessTree = async (rootPid, host = systemWindowsProcessTreeHost) => {
     if (!Number.isSafeInteger(rootPid) || rootPid <= 0)
@@ -70,8 +73,11 @@ const systemHost = {
         }
         const { stdout } = await execFileAsync("ps", ["eww", "-p", String(pid)]);
         const environment = {};
-        for (const match of stdout.matchAll(/(?:^|\s)([A-Za-z_][A-Za-z0-9_]*)=([^\s]*)/gu))
-            environment[match[1]] = match[2] ?? "";
+        for (const match of stdout.matchAll(/(?:^|\s)([A-Za-z_][A-Za-z0-9_]*)=([^\s]*)/gu)) {
+            const name = match[1];
+            if (name !== undefined)
+                environment[name] = match[2] ?? "";
+        }
         return environment;
     },
     signalGroup(processGroupId, signal) {
@@ -97,13 +103,9 @@ const systemWindowsProcessTreeHost = {
 export const readProcessRunId = async (pid, host = systemHost) => (await host.environment(pid)).REA_PROCESS_RUN_ID;
 /** Token-validate every rooted POSIX process group before signaling any. */
 export const cleanupOwnedProcessGroup = async (ownership, host = systemHost) => {
-    let processes;
-    try {
-        processes = liveProcesses(await host.listProcesses());
-    }
-    catch {
+    const processes = await readLiveProcessTable(host);
+    if (processes === undefined)
         return { cleaned: false, reason: "process table could not be inspected" };
-    }
     const plan = await createOwnedCleanupPlan(ownership, processes, host);
     if ("cleaned" in plan)
         return plan;
@@ -126,10 +128,38 @@ export const cleanupOwnedProcessGroup = async (ownership, host = systemHost) =>
     }
     return { cleaned: true, signaled };
 };
+/** Verify that no live process still carries an owned capture run token. */
+export const verifyNoTokenOwnedProcesses = async (runId, host = systemHost) => {
+    const processes = await readLiveProcessTable(host);
+    if (processes === undefined)
+        return { cleaned: false, reason: "process table could not be inspected" };
+    const scan = await scanTokenOwnedProcesses(processes, runId, host);
+    if (scan.failures.length > 0)
+        return cleanupValidationFailure(scan.failures);
+    return scan.owned.length === 0
+        ? { cleaned: true, signaled: false }
+        : { cleaned: false, reason: "token-owned process remained after cleanup" };
+};
+const readLiveProcessTable = async (host) => {
+    try {
+        return liveProcesses(await host.listProcesses());
+    }
+    catch {
+        return undefined;
+    }
+};
 const createOwnedCleanupPlan = async (ownership, processes, host) => {
+    const tokenOwned = ownership.sweepTokenOwnedProcesses === true
+        ? await scanTokenOwnedProcesses(processes, ownership.runId, host)
+        : { owned: [], failures: [] };
+    if (tokenOwned.failures.length > 0)
+        return cleanupValidationFailure(tokenOwned.failures);
+    const tokenOwnedGroupIds = new Set(tokenOwned.owned.map(({ processGroupId }) => processGroupId));
     const launcher = processes.find(({ pid }) => pid === ownership.leaderPid);
     const rootMembers = processes.filter(({ processGroupId }) => processGroupId === ownership.processGroupId);
-    if (launcher === undefined && rootMembers.length === 0)
+    if (launcher === undefined &&
+        rootMembers.length === 0 &&
+        tokenOwned.owned.length === 0)
         return { cleaned: true, signaled: false };
     let descendants = [];
     if (launcher !== undefined) {
@@ -142,11 +172,14 @@ const createOwnedCleanupPlan = async (ownership, processes, host) => {
     const processGroupIds = new Set([ownership.processGroupId]);
     for (const descendant of descendants)
         processGroupIds.add(descendant.processGroupId);
+    for (const process of tokenOwned.owned)
+        processGroupIds.add(process.processGroupId);
     for (const processGroupId of processGroupIds) {
         if (processGroupId === ownership.processGroupId)
             continue;
         const groupLeader = processes.find(({ pid, processGroupId: observedGroupId }) => pid === processGroupId && observedGroupId === processGroupId);
-        if (groupLeader === undefined || !descendantPids.has(groupLeader.pid))
+        if ((groupLeader === undefined || !descendantPids.has(groupLeader.pid)) &&
+            !tokenOwnedGroupIds.has(processGroupId))
             return {
                 cleaned: false,
                 reason: "descendant process-group leader identity could not be verified",
@@ -162,17 +195,6 @@ const createOwnedCleanupPlan = async (ownership, processes, host) => {
             .sort((left, right) => left - right)),
     };
 };
-const launcherIdentityFailure = (launcher, ownership) => {
-    if (launcher.processGroupId !== ownership.processGroupId)
-        return "owned launcher process-group identity did not match";
-    if (ownership.expectedParentPid !== undefined &&
-        launcher.parentPid !== ownership.expectedParentPid)
-        return "owned launcher parent identity did not match";
-    if (ownership.expectedCommand !== undefined &&
-        !matchesOwnedProcessCommand(launcher.command, ownership.expectedCommand))
-        return `owned launcher command identity did not match (observed=${launcher.command}; expected=${ownership.expectedCommand})`;
-    return null;
-};
 const revalidateOwnedProcessGroup = async (processGroupId, ownership, host) => {
     let members;
     try {
@@ -197,7 +219,8 @@ const revalidateOwnedProcessGroup = async (processGroupId, ownership, host) => {
     }
     if (processGroupId !== ownership.processGroupId &&
         members.length > 0 &&
-        !members.some(({ pid }) => pid === processGroupId))
+        !members.some(({ pid }) => pid === processGroupId) &&
+        ownership.sweepTokenOwnedProcesses !== true)
         return {
             cleaned: false,
             reason: "descendant process-group leader identity could not be revalidated",
@@ -230,39 +253,28 @@ const processOwnershipFailures = async (members, runId, host) => {
     }
     return failures;
 };
-/** Observe one group without signaling it, failing closed on identity doubt. */
-export const observeOwnedProcessGroup = async (ownership, host = systemHost) => {
-    let members;
-    try {
-        members = (await host.listProcesses()).filter(({ processGroupId }) => processGroupId === ownership.processGroupId);
-    }
-    catch {
-        return {
-            state: "unverifiable",
-            reason: "process group could not be inspected",
-        };
-    }
-    const liveMembers = liveProcesses(members);
-    if (liveMembers.length === 0)
-        return { state: "empty" };
-    for (const member of liveMembers) {
+const scanTokenOwnedProcesses = async (processes, runId, host) => {
+    const owned = [];
+    const failures = [];
+    for (const process of processes) {
         try {
-            if ((await host.environment(member.pid)).REA_PROCESS_RUN_ID !==
-                ownership.runId)
-                return {
-                    state: "unverifiable",
-                    reason: "process ownership did not match",
-                };
+            if ((await host.environment(process.pid)).REA_PROCESS_RUN_ID === runId)
+                owned.push(process);
         }
         catch {
-            return {
-                state: "unverifiable",
-                reason: "process ownership could not be revalidated",
-            };
+            try {
+                const live = liveProcesses(await host.listProcesses());
+                if (!live.some(({ pid }) => pid === process.pid))
+                    continue;
+            }
+            catch { }
+            failures.push({ pid: process.pid, reason: "environment-unreadable" });
         }
     }
-    return { state: "alive" };
+    return { owned, failures };
 };
+/** Observe one group without signaling it, failing closed on identity doubt. */
+export const observeOwnedProcessGroup = async (ownership, host = systemHost) => observeOwnedProcessGroupWithHost(ownership, host);
 /**
  * Record the live launcher and descendant lineage after run-token validation.
  *
@@ -270,80 +282,4 @@ export const observeOwnedProcessGroup = async (ownership, host = systemHost) =>
  * list means no descendants were live during this observation, not that the
  * run never created a short-lived child.
  */
-export const observeOwnedProcessLineage = async (ownership, host = systemHost) => {
-    let processes;
-    try {
-        processes = liveProcesses(await host.listProcesses());
-    }
-    catch {
-        return unavailableLineage(ownership, "process table could not be inspected");
-    }
-    const launcher = processes.find(({ pid }) => pid === ownership.leaderPid);
-    if (launcher === undefined)
-        return unavailableLineage(ownership, "owned launcher is not live");
-    if (launcher.processGroupId !== ownership.processGroupId)
-        return unavailableLineage(ownership, "owned launcher process-group identity did not match");
-    if (ownership.expectedParentPid !== undefined &&
-        launcher.parentPid !== ownership.expectedParentPid)
-        return unavailableLineage(ownership, "owned launcher parent identity did not match");
-    if (ownership.expectedCommand !== undefined &&
-        !matchesOwnedProcessCommand(launcher.command, ownership.expectedCommand))
-        return unavailableLineage(ownership, `owned launcher command identity did not match (observed=${launcher.command}; expected=${ownership.expectedCommand})`);
-    const descendants = descendantsOf(launcher.pid, processes);
-    for (const member of [launcher, ...descendants]) {
-        try {
-            if ((await host.environment(member.pid)).REA_PROCESS_RUN_ID !==
-                ownership.runId)
-                return unavailableLineage(ownership, "process lineage contains an unowned or PID-reused process");
-        }
-        catch {
-            return unavailableLineage(ownership, "process ownership could not be revalidated");
-        }
-    }
-    return {
-        status: "verified",
-        observedAt: new Date().toISOString(),
-        lineage: {
-            schemaVersion: 1,
-            runId: ownership.runId,
-            launcherPid: launcher.pid,
-            launcherParentPid: launcher.parentPid,
-            processGroupId: launcher.processGroupId,
-            descendants: descendants
-                .sort((left, right) => left.pid - right.pid)
-                .map(({ pid, parentPid, processGroupId }) => ({
-                pid,
-                parentPid,
-                processGroupId,
-            })),
-        },
-    };
-};
-const descendantsOf = (launcherPid, processes) => {
-    const childrenByParent = new Map();
-    for (const process of processes) {
-        const siblings = childrenByParent.get(process.parentPid) ?? [];
-        siblings.push(process);
-        childrenByParent.set(process.parentPid, siblings);
-    }
-    const descendants = [];
-    const pending = [...(childrenByParent.get(launcherPid) ?? [])];
-    const visited = new Set([launcherPid]);
-    for (const process of pending) {
-        if (visited.has(process.pid))
-            continue;
-        visited.add(process.pid);
-        descendants.push(process);
-        pending.push(...(childrenByParent.get(process.pid) ?? []));
-    }
-    return descendants;
-};
-const unavailableLineage = (ownership, reason) => ({
-    status: "unavailable",
-    observedAt: new Date().toISOString(),
-    runId: ownership.runId,
-    launcherPid: ownership.leaderPid,
-    processGroupId: ownership.processGroupId,
-    reason,
-});
-const liveProcesses = (members) => members.filter(({ state }) => !state.startsWith("Z"));
+export const observeOwnedProcessLineage = async (ownership, host = systemHost) => observeOwnedProcessLineageWithHost(ownership, host);

package/dist/process/ProcessOwnershipIdentity.js

@@ -0,0 +1,13 @@
+import { matchesOwnedProcessCommand } from "./ProcessCommandIdentity.js";
+/** Compare a live launcher against the identity committed at process launch. */
+export const launcherIdentityFailure = (launcher, ownership) => {
+    if (launcher.processGroupId !== ownership.processGroupId)
+        return "owned launcher process-group identity did not match";
+    if (ownership.expectedParentPid !== undefined &&
+        launcher.parentPid !== ownership.expectedParentPid)
+        return "owned launcher parent identity did not match";
+    if (ownership.expectedCommand !== undefined &&
+        !matchesOwnedProcessCommand(launcher.command, ownership.expectedCommand))
+        return `owned launcher command identity did not match (observed=${launcher.command}; expected=${ownership.expectedCommand})`;
+    return null;
+};

package/dist/process/ProcessOwnershipObservation.js

@@ -0,0 +1,88 @@
+import { launcherIdentityFailure } from "./ProcessOwnershipIdentity.js";
+import { descendantsOf, liveProcesses } from "./ProcessOwnershipProcessTree.js";
+/** Observe one group without signaling it, failing closed on identity doubt. */
+export const observeOwnedProcessGroupWithHost = async (ownership, host) => {
+    let members;
+    try {
+        members = (await host.listProcesses()).filter(({ processGroupId }) => processGroupId === ownership.processGroupId);
+    }
+    catch {
+        return {
+            state: "unverifiable",
+            reason: "process group could not be inspected",
+        };
+    }
+    const liveMembers = liveProcesses(members);
+    if (liveMembers.length === 0)
+        return { state: "empty" };
+    for (const member of liveMembers) {
+        try {
+            if ((await host.environment(member.pid)).REA_PROCESS_RUN_ID !==
+                ownership.runId)
+                return {
+                    state: "unverifiable",
+                    reason: "process ownership did not match",
+                };
+        }
+        catch {
+            return {
+                state: "unverifiable",
+                reason: "process ownership could not be revalidated",
+            };
+        }
+    }
+    return { state: "alive" };
+};
+/** Record the live launcher and descendant lineage after run-token validation. */
+export const observeOwnedProcessLineageWithHost = async (ownership, host) => {
+    let processes;
+    try {
+        processes = liveProcesses(await host.listProcesses());
+    }
+    catch {
+        return unavailableLineage(ownership, "process table could not be inspected");
+    }
+    const launcher = processes.find(({ pid }) => pid === ownership.leaderPid);
+    if (launcher === undefined)
+        return unavailableLineage(ownership, "owned launcher is not live");
+    const identityFailure = launcherIdentityFailure(launcher, ownership);
+    if (identityFailure !== null)
+        return unavailableLineage(ownership, identityFailure);
+    const descendants = descendantsOf(launcher.pid, processes);
+    for (const member of [launcher, ...descendants]) {
+        try {
+            if ((await host.environment(member.pid)).REA_PROCESS_RUN_ID !==
+                ownership.runId)
+                return unavailableLineage(ownership, "process lineage contains an unowned or PID-reused process");
+        }
+        catch {
+            return unavailableLineage(ownership, "process ownership could not be revalidated");
+        }
+    }
+    return {
+        status: "verified",
+        observedAt: new Date().toISOString(),
+        lineage: {
+            schemaVersion: 1,
+            runId: ownership.runId,
+            launcherPid: launcher.pid,
+            launcherParentPid: launcher.parentPid,
+            processGroupId: launcher.processGroupId,
+            descendants: descendants
+                .sort((left, right) => left.pid - right.pid)
+                .map(({ pid, parentPid, processGroupId }) => ({
+                pid,
+                parentPid,
+                processGroupId,
+            })),
+        },
+    };
+};
+const unavailableLineage = (ownership, reason) => ({
+    status: "unavailable",
+    observedAt: new Date().toISOString(),
+    runId: ownership.runId,
+    launcherPid: ownership.leaderPid,
+    processGroupId: ownership.processGroupId,
+    reason,
+});

package/dist/process/ProcessOwnershipProcessTree.js

@@ -0,0 +1,22 @@
+/** 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) => {
+    const childrenByParent = new Map();
+    for (const process of processes) {
+        const siblings = childrenByParent.get(process.parentPid) ?? [];
+        siblings.push(process);
+        childrenByParent.set(process.parentPid, siblings);
+    }
+    const descendants = [];
+    const pending = [...(childrenByParent.get(launcherPid) ?? [])];
+    const visited = new Set([launcherPid]);
+    for (const process of pending) {
+        if (visited.has(process.pid))
+            continue;
+        visited.add(process.pid);
+        descendants.push(process);
+        pending.push(...(childrenByParent.get(process.pid) ?? []));
+    }
+    return descendants;
+};

package/dist/process/ProviderDeadline.js

@@ -26,8 +26,7 @@ export class ProviderStartupDeadline {
     #externalSignal;
     #onExternalAbort;
     #timer;
-    #timedOut = false;
-    #cancelled = false;
+    #interruption;
     constructor(timeoutMs, signal) {
         this.timeoutMs = timeoutMs;
         if (!Number.isFinite(timeoutMs) || timeoutMs <= 0)
@@ -38,11 +37,11 @@ export class ProviderStartupDeadline {
             if (this.#controller.signal.aborted)
                 return;
             if (Date.now() >= this.#deadlineAt) {
-                this.#timedOut = true;
+                this.#interruption = "timeout";
                 this.#abort(new DOMException("Provider startup deadline elapsed", "TimeoutError"));
                 return;
             }
-            this.#cancelled = true;
+            this.#interruption = "cancelled";
             this.#abort(signal?.reason);
         };
         if (signal?.aborted === true) {
@@ -53,7 +52,7 @@ export class ProviderStartupDeadline {
         this.#timer = setTimeout(() => {
             if (this.#controller.signal.aborted)
                 return;
-            this.#timedOut = true;
+            this.#interruption = "timeout";
             this.#abort(new DOMException("Provider startup deadline elapsed", "TimeoutError"));
         }, timeoutMs);
     }
@@ -61,13 +60,10 @@ export class ProviderStartupDeadline {
     get signal() {
         return this.#controller.signal;
     }
-    /** True only when the external caller signal initiated cancellation. */
-    get cancelled() {
-        return this.#cancelled;
-    }
-    /** True when the absolute startup deadline has elapsed. */
-    get timedOut() {
-        return (this.#timedOut || (!this.#cancelled && Date.now() >= this.#deadlineAt));
+    /** First control path that interrupted startup, if any. */
+    get interruption() {
+        return (this.#interruption ??
+            (Date.now() >= this.#deadlineAt ? "timeout" : undefined));
     }
     /** Milliseconds still available to the next startup phase. */
     remainingMs() {