rea-agents 3.0.0 → 3.2.0

package/dist/native/NativeMacOSProvider.js

@@ -1,10 +1,10 @@
-import { dirname, isAbsolute, relative, resolve, sep } from "node:path";
-import { realpath, stat } from "node:fs/promises";
+import { dirname, isAbsolute, resolve } from "node:path";
+import { stat } from "node:fs/promises";
 import { parse as parseXmlPlist } from "plist";
 import { z } from "zod";
 import { createAnalysisExecution, } from "../application/AnalysisProvider.js";
 import { NATIVE_TOOL_CONTRACTS, } from "../contracts/nativeToolContracts.js";
-import { AnalysisCancelledError, AnalysisCapabilityUnavailableError, AnalysisOutputError, AnalysisTimeoutError, ProviderAdapterError, } from "../domain/errors.js";
+import { AnalysisCancelledError, AnalysisCapabilityUnavailableError, AnalysisOutputError, ProviderAdapterError, } from "../domain/errors.js";
 import { jsonValueSchema } from "../domain/jsonValue.js";
 import { demangleSwiftSchema, inspectPlistSchema, inspectSignatureSchema, listArchitecturesSchema, } from "../domain/nativeInspection.js";
 import { err, ok } from "../domain/result.js";
@@ -21,8 +21,6 @@ export const NATIVE_MACOS_PROVIDER_IDENTITY = Object.freeze({
     version: null,
 });
 const IDENTITY = NATIVE_MACOS_PROVIDER_IDENTITY;
-const TIMEOUT_MS = 30_000;
-const OUTPUT_LIMIT = 4 * 1024 * 1024;
 /** Read-only semantic provider composed from Xcode command-line utilities. */
 export class NativeMacOSProvider {
     runner;
@@ -41,11 +39,7 @@ export class NativeMacOSProvider {
             return Object.freeze({
                 provider: IDENTITY,
                 operation: contract.name,
-                inputContractVersion: 1,
-                outputContractVersion: 1,
                 ...availability,
-                pagination: "none",
-                exhaustive: contract.name !== "inspect_macho",
                 effects: Object.freeze({
                     mutatesArtifact: false,
                     launchesProcess: true,
@@ -55,11 +49,6 @@ export class NativeMacOSProvider {
                     changesPermissions: false,
                     requiresRoot: false,
                 }),
-                limits: Object.freeze({
-                    maxResults: contract.name === "demangle_swift" ? 500 : null,
-                    maxPayloadBytes: OUTPUT_LIMIT,
-                    timeoutMs: TIMEOUT_MS,
-                }),
                 limitations: Object.freeze([
                     "Availability and textual formats depend on the installed macOS/Xcode toolchain.",
                 ]),
@@ -199,9 +188,9 @@ class NativeMacOSClient {
         });
     }
     async #inspectPlist(parameters, signal) {
-        const requested = parameters.relative_path;
-        if (typeof requested !== "string")
-            return err(new AnalysisOutputError("inspect_plist", "relative_path was not a string"));
+        const requested = parameters.path;
+        if (requested !== undefined && typeof requested !== "string")
+            return err(new AnalysisOutputError("inspect_plist", "path was not a string"));
         const plist = await resolvePlistPath(this.target, requested);
         if (!plist.ok)
             return plist;
@@ -220,7 +209,7 @@ class NativeMacOSClient {
                     ? "xml"
                     : "unknown",
             ...parsed,
-            source_path: requested,
+            source_path: plist.value,
             provenance,
             limitations: [],
         });
@@ -228,7 +217,7 @@ class NativeMacOSClient {
             result: jsonValueSchema.parse(result),
             provenance,
             limitations: [],
-            locations: [{ kind: "artifact-path", path: requested }],
+            locations: [{ kind: "artifact-path", path: plist.value }],
         });
     }
     async #inspectMacho(signal) {
@@ -246,8 +235,6 @@ class NativeMacOSClient {
     async #run(operation, tool, arguments_, options = {}) {
         const captured = await this.runner.run(tool, arguments_, {
             ...(options.signal === undefined ? {} : { signal: options.signal }),
-            timeoutMs: TIMEOUT_MS,
-            maxOutputBytes: OUTPUT_LIMIT,
             acceptNonZero: options.acceptNonZero ?? false,
         });
         if (captured.ok)
@@ -261,8 +248,6 @@ const translateCommandFailure = (operation, failure) => {
         return new AnalysisCapabilityUnavailableError(IDENTITY.id, operation, `${failure.tool} is unavailable through xcrun.`);
     if (failure.reason === "cancelled")
         return new AnalysisCancelledError(operation);
-    if (failure.reason === "timeout")
-        return new AnalysisTimeoutError(operation, TIMEOUT_MS);
     return new ProviderAdapterError(IDENTITY.id, operation, { cause: failure });
 };
 const invocation = (capture, artifactPath, alias = "$ARTIFACT") => ({
@@ -277,8 +262,6 @@ const invocation = (capture, artifactPath, alias = "$ARTIFACT") => ({
     exit: { code: capture.exitCode, signal: capture.signal },
     stdout_bytes: capture.stdoutBytes,
     stderr_bytes: capture.stderrBytes,
-    stdout_truncated: capture.stdoutTruncated,
-    stderr_truncated: capture.stderrTruncated,
 });
 const parseEntitlements = (output) => {
     const start = output.indexOf("<?xml");
@@ -290,23 +273,15 @@ const parseEntitlements = (output) => {
 const resolvePlistPath = async (target, requested) => {
     try {
         const source = target.sourcePath ?? target.path;
+        if (requested !== undefined && isAbsolute(requested))
+            return ok(resolve(requested));
         const sourceMetadata = await stat(source);
         const root = sourceMetadata.isDirectory() ? source : dirname(target.path);
-        const candidate = resolve(root, requested);
-        if (!within(root, candidate))
-            return err(new ProviderAdapterError(IDENTITY.id, "inspect_plist"));
-        const canonicalRoot = await realpath(root);
-        const canonical = await realpath(candidate);
-        if (!within(canonicalRoot, canonical))
-            return err(new ProviderAdapterError(IDENTITY.id, "inspect_plist"));
-        return ok(canonical);
+        return ok(requested === undefined
+            ? resolve(root, "Contents/Info.plist")
+            : resolve(root, requested));
     }
     catch (cause) {
         return err(new ProviderAdapterError(IDENTITY.id, "inspect_plist", { cause }));
     }
 };
-const within = (root, candidate) => {
-    const child = relative(root, candidate);
-    return (child === "" ||
-        (!child.startsWith(`..${sep}`) && child !== ".." && !isAbsolute(child)));
-};

package/dist/native/NativeMachoInspection.js

@@ -15,7 +15,7 @@ const REQUIRED_COMMANDS = [
 ];
 const OPTIONAL_VTOOL_COMMAND = ["vtool", ["-show-build"]];
 const VTOOL_UNAVAILABLE_LIMITATION = "vtool is unavailable; build metadata is normalized from otool only.";
-/** Inspect one Mach-O with bounded native commands and normalized output. */
+/** Inspect one Mach-O with the required native commands and normalized output. */
 export const inspectNativeMacho = async (context) => {
     const captures = [];
     for (const [tool, prefix] of REQUIRED_COMMANDS) {

package/dist/process/BoundedFileBytes.js

@@ -0,0 +1,17 @@
+/** Read through EOF, returning undefined on overflow; consume at most maxBytes + 1 bytes without closing the handle. */
+export const readBoundedFileBytes = async (handle, maxBytes) => {
+    if (!Number.isSafeInteger(maxBytes) || maxBytes < 0)
+        throw new RangeError("File byte limit must be a nonnegative safe integer");
+    const chunks = [];
+    const buffer = Buffer.allocUnsafe(Math.min(64 * 1_024, maxBytes + 1));
+    let total = 0;
+    for (;;) {
+        const { bytesRead } = await handle.read(buffer, 0, Math.min(buffer.length, maxBytes - total + 1), null);
+        if (bytesRead === 0)
+            return Buffer.concat(chunks, total);
+        total += bytesRead;
+        if (total > maxBytes)
+            return undefined;
+        chunks.push(Buffer.from(buffer.subarray(0, bytesRead)));
+    }
+};

package/dist/process/ExecFileOutput.js

@@ -0,0 +1,11 @@
+import { execFile, } from "node:child_process";
+/** Run a shell-free command while capturing its complete UTF-8 output. */
+export const execFileOutput = (command, arguments_, options = {}) => new Promise((resolve, reject) => {
+    execFile(command, [...arguments_], { ...options, encoding: "utf8", maxBuffer: Number.POSITIVE_INFINITY }, (error, stdout, stderr) => {
+        if (error !== null) {
+            reject(error);
+            return;
+        }
+        resolve({ stdout, stderr });
+    });
+});

package/dist/process/PendingOperations.js

@@ -1,9 +1,8 @@
 /**
  * Correlates event-driven provider replies with bounded waits.
  *
- * The registry owns every request timer and abort listener. Settling, timing
- * out, cancelling, or failing an operation removes both before resolution, so
- * late protocol replies can be ignored without retaining request resources.
+ * The registry owns optional request timers and cancellation listeners.
+ * Settling, timing out, cancelling, or failing removes these before resolution.
  */
 export class PendingOperations {
     #pending = new Map();
@@ -15,7 +14,7 @@ export class PendingOperations {
     has(key) {
         return this.#pending.has(key);
     }
-    /** Register one unique operation key and start its bounded wait. */
+    /** Register one unique operation key and await its reply or cancellation. */
     wait(key, options) {
         if (this.#pending.has(key))
             throw new Error("Pending operation key is already registered");
@@ -25,7 +24,9 @@ export class PendingOperations {
             const onAbort = options.signal === undefined
                 ? undefined
                 : () => this.#finish(key, options.cancelledValue());
-            const timer = setTimeout(() => this.#finish(key, options.timeoutValue()), options.timeoutMs);
+            const timer = options.timeoutMs === undefined
+                ? undefined
+                : setTimeout(() => this.#finish(key, options.timeoutValue()), options.timeoutMs);
             this.#pending.set(key, {
                 resolve,
                 timer,
@@ -50,7 +51,8 @@ export class PendingOperations {
         if (pending === undefined)
             return false;
         this.#pending.delete(key);
-        clearTimeout(pending.timer);
+        if (pending.timer !== undefined)
+            clearTimeout(pending.timer);
         if (pending.signal !== undefined && pending.onAbort !== undefined)
             pending.signal.removeEventListener("abort", pending.onAbort);
         pending.resolve(value);

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,17 @@
 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";
+import { execFileOutput } from "./ExecFileOutput.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)
@@ -48,7 +52,7 @@ const systemHost = {
     async listProcesses() {
         if (process.platform === "win32")
             return [];
-        const { stdout } = await execFileAsync("ps", [
+        const { stdout } = await execFileOutput("ps", [
             "-axo",
             "pid=,ppid=,pgid=,stat=,command=",
         ]);
@@ -68,10 +72,13 @@ const systemHost = {
         if (process.platform === "linux") {
             return parseProcessEnvironment(await readFile(`/proc/${pid}/environ`, "utf8"));
         }
-        const { stdout } = await execFileAsync("ps", ["eww", "-p", String(pid)]);
+        const { stdout } = await execFileOutput("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 +104,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 +129,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 +173,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 +196,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 +220,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 +254,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 +283,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,87 @@
+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: {
+            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;
+};