fix(process): enforce stable capacity deadlines and bounded native capture

C02 RED at 31bde9c: 2046 tests, 8 failures, 0 errors/skips.
Use fixed per-client or explicit shared runtimes, monotonic queue/execution budgets,
8MiB stdout and 2MiB stderr caps, per-call cancellation and owned-root cleanup.
Preserve lifecycle reasons, byte counts and unknown descendant status in results.
Quarantine runtimes with unconfirmed owned root/reader cleanup; keep legacy API bridge.
Remote cancellation and unverified descendant ownership are not claimed.

Author: loong10k

src/main/java/io/github/easy4j/opencli/OpenCliProperties.java

@@ -7,119 +7,56 @@
 import lombok.Data;
 
 /**
- * OpenCLI runtime configuration POJO with no Spring dependency.
- * <p>
- * 描述可执行文件、工作目录、超时、全局 argv 前缀、远端 Agent 以及需要注入子进程的环境变量
- *（例如 {@code OPENCLI_CDP_ENDPOINT}）。Spring Boot 可由上层以
- * {@code @ConfigurationProperties(prefix = "opencli")} 绑定同名字段。
- * </p>
- * <p>
- * {@link #commandTimeoutMillis} 在本地模式下用于子进程 Watchdog；在
- * {@link OpenCliExecutionTarget#REMOTE_AGENT_HTTP} 模式下用作 HTTP 客户端超时上限。
- * </p>
- */
-@Data/**
-
- * OpenCLI runtime configuration POJO with no Spring dependency.
- *
- * <p>Describes the executable path, working directory, timeout, global argv prefix,
- * remote Agent settings, and environment variables injected into the subprocess
- * (e.g.&nbsp;{@code OPENCLI_CDP_ENDPOINT}). Spring Boot applications can bind these
- * fields via {@code @ConfigurationProperties(prefix = "opencli")}.</p>
+ * OpenCLI runtime configuration without Spring dependencies.
+ * Local execution uses a monotonic submission-to-exit deadline; cleanup has a
+ * separate finite grace. Remote HTTP retains its own transport timeout semantics.
  *
- * <p>{@link #commandTimeoutMillis} is used as the subprocess watchdog timeout in local
- * mode and as the HTTP client timeout in {@link OpenCliExecutionTarget#REMOTE_AGENT_HTTP} mode.</p>
-
- *
-
  * @author <a href="https://github.com/loong10k">Loong Wan</a>
-
  * @since 3.0.0
-
  */
-
+@Data
 public class OpenCliProperties {
-
-    /**
-     * 执行目标：本机进程或与 opencli-admin 兼容的远端 Agent。
-     */
     private OpenCliExecutionTarget executionTarget = OpenCliExecutionTarget.LOCAL_PROCESS;
-
-    /**
-     * 远端 Agent 根 URL（不含尾斜杠），例如 {@code http://192.168.1.10:19823}。
-     * <p>仅当 {@link #executionTarget} 为 {@link OpenCliExecutionTarget#REMOTE_AGENT_HTTP} 时必填。</p>
-     */
+    /** Root URL of an opencli-admin compatible Agent. */
     private String remoteAgentBaseUrl;
-
-    /**
-     * 传给 Agent collect 的 {@code mode}：{@code bridge} 或 {@code cdp}（与 Agent 环境一致）。
-     */
     private String remoteCollectMode = "cdp";
-
-    /**
-     * 传给 Agent collect 的默认 {@code format}（可被 argv 中的 {@code -f} 覆盖）。
-     */
     private String remoteOutputFormat = "json";
-
-    /**
-     * 对应 collect body 的 {@code cdp_endpoint}；空表示由 Agent 使用自身 {@code OPENCLI_CDP_ENDPOINT}。
-     */
     private String remoteCdpEndpoint = "";
-
-    /**
-     * 为 true 时，远程模式下将 Agent HTTP 响应原文写入 {@link io.github.easy4j.opencli.core.OpenCliResult} 的
-     * {@code remoteRawHttpBody} 字段；
-     * 本地模式无效果。大响应时请谨慎开启。
-     */
+    /** Raw HTTP capture is explicitly opt-in and may contain sensitive business data. */
     private boolean remoteCaptureRawHttpResponse = false;
-
-    /**
-     * OpenCLI 可执行文件名或绝对路径；默认假定已在 {@code PATH} 中。
-     */
     private String executable = "opencli";
-
-    /**
-     * 子进程工作目录；为空时使用 JVM 当前目录。
-     */
     private String workingDirectory;
-
-    /**
-     * 单次调用超时（毫秒）：本地模式用于子进程 Watchdog；远程模式用于 Agent HTTP 请求。
-     */
+    /** Total local queue plus execution budget; remote mode uses an HTTP timeout. */
     private long commandTimeoutMillis = 300_000L;
-
-    /**
-     * 本机 CLI 子进程最大并发数；小于等于 0 时使用 CPU 核心数与 2 的较大值。
-     */
+    /** Positive per-client capacity, zero for max(2, cores); negative is invalid. Captured at construction. */
     private int maxConcurrentExecutions = 0;
-
-    /**
-     * 启动探测（{@code opencli list}）专用超时（毫秒）；小于等于 0 时探测使用 30 秒。
-     */
+    /** Maximum bytes retained from stdout for one local invocation. */
+    private int maxStdoutBytes = 8 * 1024 * 1024;
+    /** Maximum bytes retained from stderr for one local invocation. */
+    private int maxStderrBytes = 2 * 1024 * 1024;
+    /** Independent bounded cleanup grace, in milliseconds. */
+    private long cleanupGraceMillis = 5_000L;
     private long startupProbeTimeoutMillis = 30_000L;
-
-    /**
-     * 附加到 {@code opencli} 之后的<strong>最前</strong>参数（在 adapter 名之前），便于预留 profile 等扩展。
-     */
+    /** Literal prefix arguments placed before the command identifier. */
     private List<String> leadingArguments = new ArrayList<>();
-
-    /**
-     * 合并进子进程环境的键值；覆盖同名系统环境变量。
-     */
+    /** Variables overlaying the inherited process environment. */
     private Map<String, String> environment = new LinkedHashMap<>();
 
     /**
-     * 复制为「仅本机子进程」配置，供边缘 WebSocket Agent 处理中心下发的 {@code collect} 时使用，
-     * 避免误将 collect 再次转发为 {@link OpenCliExecutionTarget#REMOTE_AGENT_HTTP} 而形成回路。
+     * Copy into a local-only configuration for reverse-Agent execution without
+     * forwarding a received command back to a remote Agent.
      *
-     * @return 新实例，不会改变当前对象
+     * @return an independent local configuration
      */
     public OpenCliProperties copyForLocalCliExecution() {
         OpenCliProperties c = new OpenCliProperties();
         c.setExecutable(this.executable);
         c.setWorkingDirectory(this.workingDirectory);
         c.setCommandTimeoutMillis(this.commandTimeoutMillis);
         c.setMaxConcurrentExecutions(this.maxConcurrentExecutions);
+        c.setMaxStdoutBytes(this.maxStdoutBytes);
+        c.setMaxStderrBytes(this.maxStderrBytes);
+        c.setCleanupGraceMillis(this.cleanupGraceMillis);
         c.setStartupProbeTimeoutMillis(this.startupProbeTimeoutMillis);
         c.setLeadingArguments(new ArrayList<>(this.leadingArguments));
         c.setEnvironment(new LinkedHashMap<>(this.environment));

src/main/java/io/github/easy4j/opencli/core/OpenCliCancellationToken.java

@@ -0,0 +1,14 @@
+package io.github.easy4j.opencli.core;
+
+import java.util.concurrent.atomic.AtomicBoolean;
+
+/** Cooperative cancellation for one local invocation; cancellation never affects another invocation. */
+public final class OpenCliCancellationToken {
+    private final AtomicBoolean cancelled = new AtomicBoolean();
+
+    /** Request cancellation. This operation is idempotent. */
+    public void cancel() { cancelled.set(true); }
+
+    /** @return whether cancellation has been requested */
+    public boolean isCancelled() { return cancelled.get(); }
+}

src/main/java/io/github/easy4j/opencli/core/OpenCliExecutionDetails.java

@@ -0,0 +1,33 @@
+package io.github.easy4j.opencli.core;
+
+import lombok.Builder;
+import lombok.Getter;
+
+/** Immutable execution evidence. Observed byte counts describe bytes read, not bytes produced remotely. */
+@Getter
+@Builder
+public final class OpenCliExecutionDetails {
+    /** First terminal condition selected by the invocation owner. */
+    public enum TerminationReason {
+        PROCESS_EXIT, QUEUE_TIMEOUT, EXECUTION_TIMEOUT, OUTPUT_LIMIT,
+        CANCELLED, SPAWN_FAILED, IO_FAILURE, CLEANUP_UNCONFIRMED, RUNTIME_UNAVAILABLE
+    }
+
+    /** Confirmation concerns the directly owned child, not an arbitrary process tree. */
+    public enum CleanupState { NOT_STARTED, ROOT_EXIT_CONFIRMED, UNCONFIRMED }
+
+    private final TerminationReason terminationReason;
+    private final CleanupState cleanupState;
+    private final boolean processStarted;
+    private final boolean streamsDrained;
+    private final long stdoutCapturedBytes;
+    private final long stdoutObservedBytes;
+    private final boolean stdoutTruncated;
+    private final long stderrCapturedBytes;
+    private final long stderrObservedBytes;
+    private final boolean stderrTruncated;
+    private final long elapsedMillis;
+    private final long queueWaitMillis;
+    /** This portable backend does not claim ownership/termination of detached daemon descendants. */
+    private final boolean descendantsExitConfirmed;
+}