rea-agents 1.3.0 → 1.5.0

package/dist/application/PermissionAuthority.js

@@ -0,0 +1,183 @@
+import { realpath } from "node:fs/promises";
+import { basename, dirname, join, resolve } from "node:path";
+import { consumePermission, clearSessionPermissions, createPermissionPolicy, evaluatePermission, grantPermission, reloadPermissionCeilings, revokePermission, } from "../domain/permissionPolicy.js";
+import { PermissionRequiredError } from "../domain/errors.js";
+import { err, ok } from "../domain/result.js";
+/** Failure to establish a filesystem object's canonical authorization identity. */
+export class PermissionPathError extends Error {
+    path;
+    reason;
+    _tag = "PermissionPathError";
+    constructor(path, reason, options) {
+        super(`Cannot canonicalize permission path: ${path}`, options);
+        this.path = path;
+        this.reason = reason;
+    }
+}
+/** Canonicalize administrator ceilings before they become authorization state. */
+export const canonicalizePermissionCeilings = async (ceilings) => {
+    const normalized = [];
+    for (const ceiling of ceilings) {
+        const canonical = await canonicalizeScope(ceiling, "read");
+        if (!canonical.ok)
+            return canonical;
+        normalized.push(canonical.value);
+    }
+    return ok(normalized);
+};
+/** Canonicalize one exact operation request before subset evaluation. */
+export const canonicalizePermissionRequest = async (request, access) => {
+    const canonical = await canonicalizeScope(request, access);
+    return canonical.ok
+        ? ok({ ...canonical.value, operation_identity: request.operation_identity })
+        : canonical;
+};
+const canonicalizeScope = async (scope, access) => {
+    const roots = await canonicalizePaths(scope.roots, access);
+    if (!roots.ok)
+        return roots;
+    const executables = await canonicalizePaths(scope.executables, "read");
+    if (!executables.ok)
+        return executables;
+    return ok({ ...scope, roots: roots.value, executables: executables.value });
+};
+const canonicalizePaths = async (paths, access) => {
+    const canonical = [];
+    for (const path of paths) {
+        const result = await canonicalizePath(path, access);
+        if (!result.ok)
+            return result;
+        canonical.push(result.value);
+    }
+    return ok(canonical);
+};
+const canonicalizePath = async (path, access) => {
+    const requested = resolve(path);
+    try {
+        return ok(await realpath(requested));
+    }
+    catch (cause) {
+        if (access !== "write" || !isNotFound(cause))
+            return err(new PermissionPathError(path, errorReason(cause), { cause }));
+    }
+    try {
+        const parent = await realpath(dirname(requested));
+        return ok(join(parent, basename(requested)));
+    }
+    catch (cause) {
+        return err(new PermissionPathError(path, errorReason(cause), { cause }));
+    }
+};
+const isNotFound = (error) => error instanceof Error && "code" in error && error.code === "ENOENT";
+const errorReason = (error) => isNotFound(error) ? "not_found" : "io";
+/** Stateful owner for permission evaluation, consumption, reload, and revoke. */
+export class PermissionAuthority {
+    policy;
+    constructor(policy) {
+        this.policy = policy;
+    }
+    /** Canonicalize and authorize one exact operation before its side effect. */
+    async authorize(request, access, options = {}) {
+        const evaluated = await this.explain(request, access, options);
+        if (!evaluated.ok)
+            return evaluated;
+        const decision = evaluated.value;
+        this.policy = consumePermission(this.policy, decision);
+        return ok(decision);
+    }
+    /** Dry-run the exact shared evaluation without consuming a once grant. */
+    async explain(request, access, options = {}) {
+        const canonical = await canonicalizePermissionRequest(request, access);
+        if (!canonical.ok)
+            return canonical;
+        const decision = evaluatePermission(this.policy, canonical.value);
+        if (!decision.allowed)
+            return err(new PermissionRequiredError(canonical.value, decision.missing, ceilingFor(this.policy, canonical.value.capability), options.elicitationSupported ?? false, options.restartRequired ?? false));
+        return ok(decision);
+    }
+    /** Add authority beneath the administrator ceiling. */
+    grant(grant) {
+        const result = grantPermission(this.policy, grant);
+        if (result.ok)
+            this.policy = result.value;
+        return result;
+    }
+    /** Revoke authority immediately for subsequent operations. */
+    revoke(grantId) {
+        this.policy = revokePermission(this.policy, grantId);
+    }
+    /** Drop once/session authority when its owning connection ends. */
+    clearSessionGrants() {
+        this.policy = clearSessionPermissions(this.policy);
+    }
+    /** Atomically replace optional persisted project grants. */
+    async replaceProjectGrants(grants) {
+        let candidate = {
+            ...this.policy,
+            grants: this.policy.grants.filter(({ lifetime }) => lifetime !== "project"),
+        };
+        for (const grant of grants) {
+            const canonical = await canonicalizeGrant(grant);
+            if (!canonical.ok)
+                return canonical;
+            const added = grantPermission(candidate, canonical.value);
+            if (!added.ok)
+                return err(new PermissionPathError(grant.grant_id, "io", {
+                    cause: added.error,
+                }));
+            candidate = added.value;
+        }
+        this.policy = candidate;
+        return ok(null);
+    }
+    /** Replace grants derived from the currently loaded administrator ceiling. */
+    async replaceAdministratorGrants(grants) {
+        let candidate = {
+            ...this.policy,
+            grants: this.policy.grants.filter(({ lifetime }) => lifetime !== "administrator"),
+        };
+        for (const grant of grants) {
+            const canonical = await canonicalizeGrant(grant);
+            if (!canonical.ok)
+                return canonical;
+            const added = grantPermission(candidate, canonical.value);
+            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);
+        if (!canonical.ok)
+            return canonical;
+        this.policy = reloadPermissionCeilings(this.policy, canonical.value);
+        return ok(null);
+    }
+}
+/** Create one canonical policy and optional grants at the composition root. */
+export const createPermissionAuthority = async (ceilings, grants = []) => {
+    const canonical = await canonicalizePermissionCeilings(ceilings);
+    if (!canonical.ok)
+        return canonical;
+    let policy = createPermissionPolicy(canonical.value);
+    for (const grant of grants) {
+        const canonicalGrant = await canonicalizeGrant(grant);
+        if (!canonicalGrant.ok)
+            return canonicalGrant;
+        const added = grantPermission(policy, canonicalGrant.value);
+        if (!added.ok)
+            return err(new PermissionPathError(grant.grant_id, "io", { cause: added.error }));
+        policy = added.value;
+    }
+    return ok(new PermissionAuthority(policy));
+};
+const canonicalizeGrant = async (grant) => {
+    const scope = await canonicalizeScope(grant, "read");
+    return scope.ok ? ok({ ...grant, ...scope.value }) : scope;
+};
+const ceilingFor = (policy, capability) => policy.ceilings.find((ceiling) => ceiling.capability === capability) ?? null;

package/dist/application/PermissionConfiguration.js

@@ -0,0 +1,26 @@
+import { ConfigurationError } from "../domain/errors.js";
+import { err, ok } from "../domain/result.js";
+import { createPermissionAuthority, } from "./PermissionAuthority.js";
+import { readProjectPermissionStore } from "./ProjectPermissionStore.js";
+/** Load the same administrator and optional project policy for CLI and MCP. */
+export const loadConfiguredPermissionAuthority = async (config) => {
+    const authority = await createPermissionAuthority(config.permissionCeilings, config.administratorPermissionGrants);
+    if (!authority.ok)
+        return err(new ConfigurationError("Permission policy could not be loaded", {
+            cause: authority.error,
+        }));
+    if (config.permissionProjectRoot === undefined ||
+        config.permissionProjectStore === undefined)
+        return ok(authority.value);
+    const project = await readProjectPermissionStore(config.permissionProjectStore, config.permissionProjectRoot);
+    if (!project.ok)
+        return err(new ConfigurationError("Project permission policy could not be loaded", {
+            cause: project.error,
+        }));
+    const replaced = await authority.value.replaceProjectGrants(project.value?.grants ?? []);
+    return replaced.ok
+        ? ok(authority.value)
+        : err(new ConfigurationError("Project permission policy could not be applied", {
+            cause: replaced.error,
+        }));
+};

package/dist/application/ProcessCaptureAuthority.js

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

package/dist/application/ProcessCaptureError.js

@@ -4,14 +4,27 @@ export class ProcessCaptureError extends AnalysisError {
     _tag = "ProcessCaptureError";
     userMessage;
     userCategory;
+    reason;
+    cleanupIncomplete;
+    cleanupResources;
     constructor(message, options) {
         super(message, options);
         this.userMessage = options?.userMessage;
         this.userCategory = options?.userCategory;
+        this.reason =
+            options?.reason ??
+                (options?.userCategory === "permission_required"
+                    ? "permission_required"
+                    : options?.userCategory === "cancelled"
+                        ? "cancelled"
+                        : "capture_failed");
+        this.cleanupIncomplete = this.reason === "cleanup_incomplete";
+        this.cleanupResources = options?.cleanupResources ?? [];
     }
 }
 /** Caller-visible cancellation without exposing capture implementation state. */
 export const processCaptureCancelled = () => new ProcessCaptureError("process capture was cancelled", {
     userCategory: "cancelled",
+    reason: "cancelled",
     userMessage: "Process capture was cancelled. Start it again when ready.",
 });

package/dist/application/ProcessCaptureLifecycle.js

@@ -1,6 +1,6 @@
 import { createHash, randomUUID } from "node:crypto";
 import { createReadStream } from "node:fs";
-import { mkdtemp, rm } from "node:fs/promises";
+import { mkdir, mkdtemp, rm } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { authorizeProcessScenario, digestProcessCommitment, processComparisonContract, processScenarioCommitment, } from "../domain/processCapture.js";
@@ -219,7 +219,6 @@ export const captureTerminalFrames = (options) => {
     let outputBytes = 0;
     let truncated = false;
     options.terminal.onData((data) => {
-        options.onFirstOutput();
         options.onOutput();
         const bytes = Buffer.byteLength(data);
         if (options.frames.length >= options.scenario.limits.frames ||
@@ -249,12 +248,14 @@ export const resolveProcessResult = (capture, executionFailure, cleanupFailure)
             cause: executionFailure,
         });
     if (cleanupFailure !== undefined)
-        throw new ProcessCaptureError(cleanupFailure);
+        throw new ProcessCaptureError(cleanupFailure, {
+            reason: "cleanup_incomplete",
+        });
     if (capture === undefined)
         throw new ProcessCaptureError("process capture produced no result");
     return capture;
 };
-export const prepareProcessCapture = async (scenario, policy, signal) => {
+export const prepareProcessCapture = async (scenario, policy, signal, host = systemProcessPreparationHost) => {
     const decision = authorizeProcessScenario(scenario, policy);
     if (!decision.allowed)
         throw new ProcessCaptureError(decision.reason, {
@@ -264,11 +265,22 @@ export const prepareProcessCapture = async (scenario, policy, signal) => {
     await assertRealPathAuthority(scenario, policy);
     assertNotCancelled(signal);
     const before = await snapshotRoots(scenario, signal);
-    const temporaryRoot = await mkdtemp(join(tmpdir(), "rea-process-"));
-    const runId = randomUUID();
-    const home = join(temporaryRoot, "home");
-    await import("node:fs/promises").then(({ mkdir }) => mkdir(home));
-    return { temporaryRoot, runId, home, before };
+    const temporaryRoot = await host.createTemporaryRoot();
+    try {
+        const runId = randomUUID();
+        const home = join(temporaryRoot, "home");
+        await host.createHome(home);
+        return { temporaryRoot, runId, home, before };
+    }
+    catch (cause) {
+        await host.cleanup(temporaryRoot);
+        throw cause;
+    }
+};
+const systemProcessPreparationHost = {
+    createTemporaryRoot: () => mkdtemp(join(tmpdir(), "rea-process-")),
+    createHome: (path) => mkdir(path),
+    cleanup: (path) => rm(path, { recursive: true, force: true }),
 };
 const processPolicyMessage = (reason) => {
     if (reason === "process capture is disabled")

package/dist/application/ProcessCheckpoints.js

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

package/dist/application/ProcessCli.js

@@ -1,21 +1,13 @@
 import { readFile } from "node:fs/promises";
 import { parseConfig } from "../config.js";
-import { AnalysisError, projectAnalysisError } from "../domain/errors.js";
+import { AnalysisError, AnalysisProtocolError, PermissionRequiredError, projectAnalysisError, } from "../domain/errors.js";
 import { createEvidence, parseEvidence } from "../domain/evidence.js";
 import { jsonValueSchema } from "../domain/jsonValue.js";
 import { compareProcessCaptures, LEGACY_PROCESS_CAPTURE_MESSAGE, parseProcessScenario, parseProcessCapture, } from "../domain/processCapture.js";
 import { captureProcessScenario } from "./ProcessHarness.js";
 import { PROCESS_PROVIDER, createProcessCaptureEvidence, } from "./ProcessEvidence.js";
+import { loadConfiguredPermissionAuthority } from "./PermissionConfiguration.js";
 const MAX_INPUT_BYTES = 64 * 1024 * 1024;
-/** Distinguish a safe process-command failure from successful Evidence. */
-export const isProcessCliErrorOutput = (value) => typeof value === "object" &&
-    value !== null &&
-    "error" in value &&
-    value.error === "Process command failed" &&
-    "category" in value &&
-    typeof value.category === "string" &&
-    "message" in value &&
-    typeof value.message === "string";
 /** Capture one JSON scenario through the same policy and evidence contract as MCP. */
 export const captureProcessScenarioFile = async (path) => {
     try {
@@ -30,6 +22,27 @@ export const captureProcessScenarioFile = async (path) => {
         const config = parseConfig(process.env);
         if (!config.ok)
             return cliAnalysisError(config.error);
+        const authority = await loadConfiguredPermissionAuthority(config.value);
+        if (!authority.ok)
+            return cliAnalysisError(authority.error);
+        const authorized = await authority.value.authorize({
+            capability: "process_capture",
+            roots: [scenario.working_directory, ...scenario.filesystem_roots],
+            executables: [scenario.executable],
+            environment_names: [
+                ...Object.keys(scenario.environment),
+                ...scenario.inherit_environment,
+            ],
+            network: scenario.network_access === "host" ? "external" : "none",
+            mount: false,
+            operation_identity: `capture_process_scenario:${scenario.executable}`,
+        }, "read");
+        if (!authorized.ok)
+            return cliAnalysisError(authorized.error instanceof PermissionRequiredError
+                ? authorized.error
+                : new AnalysisProtocolError(authorized.error.message, {
+                    cause: authorized.error,
+                }));
         const captured = await captureProcessScenario(scenario, config.value.processExecutionPolicy);
         if (!captured.ok)
             return cliAnalysisError(captured.error);
@@ -66,7 +79,13 @@ export const compareProcessEvidenceFiles = async (leftPath, rightPath) => {
     }
 };
 const parseCaptureEvidence = (input) => {
-    const evidence = parseEvidence(input);
+    let evidence;
+    try {
+        evidence = parseEvidence(input);
+    }
+    catch {
+        throw invalidCaptureEvidence();
+    }
     if (evidence.operation !== "capture_process_scenario" ||
         evidence.predicate_type !== "rea.process-capture/v4" ||
         evidence.provider.id !== PROCESS_PROVIDER.id ||
@@ -75,11 +94,17 @@ const parseCaptureEvidence = (input) => {
             throw new ProcessCliFailure("invalid_input", LEGACY_PROCESS_CAPTURE_MESSAGE);
         throw new ProcessCliFailure("invalid_input", "Capture evidence is not from the current process-capture workflow. Create new capture evidence, then try again.");
     }
-    return {
-        id: evidence.evidence_id,
-        capture: parseProcessCapture(evidence.normalized_result),
-    };
+    try {
+        return {
+            id: evidence.evidence_id,
+            capture: parseProcessCapture(evidence.normalized_result),
+        };
+    }
+    catch {
+        throw invalidCaptureEvidence();
+    }
 };
+const invalidCaptureEvidence = () => new ProcessCliFailure("invalid_input", "Capture evidence is malformed. Create new capture evidence, then try again.");
 const readJson = async (path) => {
     let bytes;
     try {

package/dist/application/ProcessHarness.js

@@ -81,16 +81,6 @@ const scheduleScenarioEvents = (options) => {
         timers.add(timer);
     }
 };
-const startScenarioEvents = (options) => {
-    let eventsStarted = false;
-    return () => {
-        if (eventsStarted)
-            return;
-        eventsStarted = true;
-        scheduleScenarioEvents(options);
-    };
-};
-const eventsRequireReadiness = (scenario) => scenario.events.some((event) => event.type === "input" || event.type === "resize");
 const cleanupFailedStartup = async (options) => {
     options.terminal?.kill("SIGKILL");
     const cleanupFailure = await releaseProcessResources({
@@ -98,7 +88,10 @@ const cleanupFailedStartup = async (options) => {
         sampledProcessGroupIds: [],
     });
     if (cleanupFailure !== undefined)
-        throw new ProcessCaptureError(cleanupFailure, { cause: options.cause });
+        throw new ProcessCaptureError(cleanupFailure, {
+            cause: options.cause,
+            reason: "cleanup_incomplete",
+        });
     throw options.cause;
 };
 const createTerminalRenderer = (scenario, temporaryRoot, terminalPid) => new TerminalRenderer({
@@ -131,23 +124,20 @@ const startCaptureRuntime = async (options) => {
             rows: scenario.terminal.rows,
             name: "xterm-256color",
         });
-        const startEvents = startScenarioEvents({
-            ...options,
-            getTerminal: () => terminal,
-            renderer,
-            started,
-        });
-        if (!eventsRequireReadiness(scenario))
-            startEvents();
         const framesTruncated = captureTerminalFrames({
             ...options,
             terminal,
             started,
             onOutput: () => (lastOutput = Date.now()),
-            onFirstOutput: startEvents,
             renderer,
             checkpoints,
         });
+        scheduleScenarioEvents({
+            ...options,
+            getTerminal: () => terminal,
+            renderer,
+            started,
+        });
         const stopSampler = startProcessSampler(terminal.pid, started, scenario.limits.processes, options.samples);
         return {
             replay,

package/dist/application/ProcessNormalization.js

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

package/dist/application/ProcessOwnership.js

@@ -2,9 +2,10 @@ import { execFile } from "node:child_process";
 import { readFile } from "node:fs/promises";
 import { promisify } from "node:util";
 const execFileAsync = promisify(execFile);
-const parseEnvironment = (value) => Object.fromEntries(value
+/** Parse the NUL-delimited Linux process environment without nameless keys. */
+export const parseProcessEnvironment = (value) => Object.fromEntries(value
     .split("\0")
-    .filter((entry) => entry.includes("="))
+    .filter((entry) => entry.indexOf("=") > 0)
     .map((entry) => {
     const separator = entry.indexOf("=");
     return [entry.slice(0, separator), entry.slice(separator + 1)];
@@ -31,7 +32,7 @@ const systemHost = {
     },
     async environment(pid) {
         if (process.platform === "linux") {
-            return parseEnvironment(await readFile(`/proc/${pid}/environ`, "utf8"));
+            return parseProcessEnvironment(await readFile(`/proc/${pid}/environ`, "utf8"));
         }
         const { stdout } = await execFileAsync("ps", ["eww", "-p", String(pid)]);
         const environment = {};

package/dist/application/ProcessSampling.js

@@ -1,5 +1,5 @@
 import { execFile } from "node:child_process";
-import { readFile } from "node:fs/promises";
+import { readFile, readdir } from "node:fs/promises";
 import { promisify } from "node:util";
 const execFileAsync = promisify(execFile);
 const PROC_READ_CONCURRENCY = 64;
@@ -67,23 +67,58 @@ const readProcessCommand = async (pid, signal) => {
         return handleProcReadFailure(cause);
     }
 };
-const readLinuxChildren = async (pid, signal) => {
-    let text;
-    try {
-        text = await readFile(`/proc/${String(pid)}/task/${String(pid)}/children`, {
-            encoding: "utf8",
-            signal,
-        });
-    }
-    catch (cause) {
-        return handleProcReadFailure(cause);
+const systemLinuxChildrenHost = {
+    async taskIds(pid, signal) {
+        try {
+            signal.throwIfAborted();
+            const entries = await readdir(`/proc/${String(pid)}/task`);
+            signal.throwIfAborted();
+            return entries
+                .filter((entry) => /^\d+$/.test(entry))
+                .map(Number)
+                .filter((taskId) => Number.isSafeInteger(taskId) && taskId > 0)
+                .sort((left, right) => left - right);
+        }
+        catch (cause) {
+            return handleProcReadFailure(cause);
+        }
+    },
+    async children(pid, taskId, signal) {
+        try {
+            return await readFile(`/proc/${String(pid)}/task/${String(taskId)}/children`, { encoding: "utf8", signal });
+        }
+        catch (cause) {
+            return handleProcReadFailure(cause);
+        }
+    },
+};
+/** Read the deduplicated children created by every thread in a Linux process. */
+export const readLinuxChildren = async (pid, signal, host = systemLinuxChildrenHost) => {
+    const taskIds = await host.taskIds(pid, signal);
+    if (taskIds === undefined)
+        return undefined;
+    const children = new Set();
+    let successfulReads = 0;
+    for (let offset = 0; offset < taskIds.length; offset += PROC_READ_CONCURRENCY) {
+        const texts = await Promise.all(taskIds
+            .slice(offset, offset + PROC_READ_CONCURRENCY)
+            .map((taskId) => host.children(pid, taskId, signal)));
+        for (const text of texts) {
+            if (text === undefined)
+                continue;
+            successfulReads += 1;
+            for (const value of text.trim().split(/\s+/)) {
+                if (!/^\d+$/.test(value))
+                    continue;
+                const child = Number(value);
+                if (Number.isSafeInteger(child) && child > 0)
+                    children.add(child);
+            }
+        }
     }
-    return text
-        .trim()
-        .split(/\s+/)
-        .filter((value) => /^\d+$/.test(value))
-        .map(Number)
-        .filter((child) => Number.isSafeInteger(child) && child > 0);
+    return successfulReads === 0
+        ? undefined
+        : [...children].sort((left, right) => left - right);
 };
 const inspectProcess = async (pid, expectedParent, signal, identities) => {
     const before = await readProcessStat(pid, signal);

package/dist/application/ProgressReporter.js

@@ -0,0 +1,30 @@
+/** Create a monotonic, rate-bounded reporter around a surface-specific sink. */
+export const createProgressReporter = (sink, options = {}) => {
+    const minimumIntervalMs = options.minimumIntervalMs ?? 100;
+    const now = options.now ?? Date.now;
+    let lastCompleted = -1;
+    let lastSentAt = Number.NEGATIVE_INFINITY;
+    let sequence = 0;
+    return {
+        async report(update) {
+            if (!Number.isFinite(update.completed) || update.completed < 0)
+                throw new TypeError("Progress completed must be a nonnegative number");
+            if (update.total !== null && update.total < update.completed)
+                throw new TypeError("Progress total cannot be less than completed");
+            if (update.completed < lastCompleted)
+                throw new TypeError("Progress cannot move backwards");
+            lastCompleted = update.completed;
+            const observedAt = now();
+            if (update.terminal !== true &&
+                observedAt - lastSentAt < minimumIntervalMs)
+                return;
+            lastSentAt = observedAt;
+            sequence += 1;
+            await sink({ ...update, sequence });
+        },
+    };
+};
+/** Surface that deliberately ignores progress while preserving one workflow API. */
+export const silentProgressReporter = {
+    report: () => Promise.resolve(),
+};