@webpresso/agent-kit 3.3.1 → 3.3.2

package/catalog/agent/rules/pre-implementation.md

@@ -227,16 +227,23 @@ Ultragoal events, or approval frontmatter.
   killed writer is never overwritten. A complete content rejection is terminal
   for that unchanged target, while active provider limits/unavailability remain
   suppressed until their recorded retry window permits another attempt.
-- **Completed rejections have a two-subject circuit breaker.** Plan review
+- **Rejections have a convergence-aware subject budget (4).** Plan review
   lineage uses the canonical `wp-blueprint-v1` subject, so lifecycle/trust
   bookkeeping commits reuse the prior rejection and do not invoke another
-  reviewer. One semantically changed remediation subject may receive the final
-  formal review; its prompt includes the prior rejection artifact and requires
-  all remaining blockers together. After two distinct semantic subjects are
-  rejected, `wp review gate` returns `scope-exhausted` before provider
-  invocation. Stop automated retries and obtain an explicit human scope
-  decision before creating a successor blueprint. Plan and delivery purposes
-  have separate budgets; delivery retains its existing whole-tree subject.
+  reviewer. An identical resubmission of an already-rejected subject is likewise
+  reused for free (no reviewer call). Each genuinely different converging
+  subject — one that addressed the prior findings — is reviewed on its own, and
+  its prompt includes the prior rejection artifacts. After **four** distinct
+  semantic subjects are rejected, `wp review gate` returns `scope-exhausted`
+  before provider invocation. This is an anti-runaway cap, not a hard fork
+  point: automated runs must stop and escalate, but a human who judges the
+  attempt to be good-faith convergence may extend the budget **in place** by
+  setting `WP_REVIEW_SCOPE_CONTINUE=1` (recorded as an audit gate-issue) and keep
+  reviewing THIS blueprint — creating a successor blueprint only launders the
+  counter and is not required. The approval gate itself is unchanged: the
+  reviewer's verdict is still required under scope-continue. Plan and delivery
+  purposes have separate budgets; delivery retains its existing whole-tree
+  subject.
 - **`provider-event-too-large` means one captured provider JSON event exceeded
   the bounded event limit; it is not a reviewer verdict.** Keep the bound in
   place, retry the same gate id, and switch provider/model when possible because

package/catalog/agent/skills/ultragoal/SKILL.md

@@ -109,24 +109,11 @@ Resolve models from the live catalog every time:
 opencode models opencode-go
 ```
 
-Pick by purpose (same intent as the committed OpenCode reviewer policy / `opencode-go` skill):
-
-| Purpose                                     | Preferred family (live catalog)                                                                  | Why                        |
-| ------------------------------------------- | ------------------------------------------------------------------------------------------------ | -------------------------- |
-| Plan / architecture critique                | DeepSeek **Pro** (`opencode-go/deepseek…-pro`)                                                   | Deeper plan review depth   |
-| Coding / implementation quality             | Kimi **Code** first (`…kimi…-code`)                                                              | Coding quality lane        |
-| Cheap recheck / high-availability follow-up | DeepSeek **Flash** (`…deepseek…-flash`)                                                          | Fast secondary pass        |
-| Aggregate / unspecified                     | Follow `opencode-go` skill order: Kimi Code → DeepSeek Pro → DeepSeek Flash → remaining families | Default outside-voice lane |
-
-Resolve the actual model ID with catalog greps (never paste a fixed model string into agent instructions as the only option):
-
-```bash
-CATALOG=$(opencode models opencode-go)
-# plan critique example:
-MODEL=$(echo "$CATALOG" | grep '^opencode-go/deepseek' | grep -- '-pro$' | sort -V | tail -1)
-# coding example:
-# MODEL=$(echo "$CATALOG" | grep '^opencode-go/kimi' | grep -- '-code$' | sort -V | tail -1)
-```
+**Selection order and the purpose→family mapping live in one place: the committed
+reviewer policy (`packages/workflow-skills/src/opencode-reviewer-policy.ts`),
+rendered into the `opencode-go` skill and drift-gated against it.** Follow that
+skill; do not restate the ordering here. A second copy of a preference list is a
+second thing to update, and the copy that goes stale is the one an agent reads.
 
 Treat a provider-wide usage limit as terminal for every OpenCode Go model in the current review window; do not hop families to evade a usage block on the same provider.
 

package/dist/esm/blueprint/core/validation/task-blocks.js

@@ -1,6 +1,12 @@
 import { z } from "zod";
 import { executionBackendSchema } from "#types/execution-backend";
-const TASK_HEADING_REGEX = /^####\s+Task\s+(\d+\.\d+):/;
+import { buildTaskHeadingRegex } from "#markdown/task-heading";
+/**
+ * Non-global on purpose: this regex is tested line-by-line via `.exec`, and a
+ * shared `g`-flagged instance would carry `lastIndex` between lines and skip
+ * alternating headings.
+ */
+const TASK_HEADING_REGEX = buildTaskHeadingRegex("m");
 /**
  * Zod schema for optional TASK-level frontmatter fields.
  *

package/dist/esm/blueprint/markdown/task-heading.d.ts

@@ -5,3 +5,24 @@ export declare function buildTaskHeadingRegex(flags?: string): RegExp;
 export declare function buildTaskHeaderRegexForId(taskId: string, flags?: string): RegExp;
 export declare function buildTaskSectionBoundaryRegex(flags?: string): RegExp;
 export declare function isTaskHeaderLine(line: string): boolean;
+/**
+ * Detect a task heading written at the wrong depth (`###` instead of `####`).
+ *
+ * Shares {@link TASK_HEADING_PREFIX_PATTERN} and {@link TASK_ID_PATTERN} with
+ * the canonical matcher so the "you used three hashes" diagnostic can never
+ * drift from the grammar it is diagnosing against — a detector built from a
+ * private copy of the pattern silently stops recognizing headings the moment
+ * the real grammar gains a prefix or id shape.
+ */
+export declare function buildWrongDepthTaskHeadingRegex(flags?: string): RegExp;
+/**
+ * Serialize a task heading. The single writer-side counterpart to
+ * {@link buildTaskHeadingRegex}: every emitter goes through here so the
+ * written form and the parsed form cannot diverge.
+ *
+ * Lane is deliberately not a parameter. The reader accepts an optional
+ * `[lane]` heading prefix for hand-authored blueprints, but the writer emits
+ * lane as a `**Lane:**` body line instead, so round-tripping never has to
+ * reconstruct a prefix the writer does not produce.
+ */
+export declare function formatTaskHeading(taskId: string, title: string): string;

package/dist/esm/blueprint/markdown/task-heading.js

@@ -16,3 +16,28 @@ export function buildTaskSectionBoundaryRegex(flags = "m") {
 export function isTaskHeaderLine(line) {
     return buildTaskHeadingRegex("m").test(line);
 }
+/**
+ * Detect a task heading written at the wrong depth (`###` instead of `####`).
+ *
+ * Shares {@link TASK_HEADING_PREFIX_PATTERN} and {@link TASK_ID_PATTERN} with
+ * the canonical matcher so the "you used three hashes" diagnostic can never
+ * drift from the grammar it is diagnosing against — a detector built from a
+ * private copy of the pattern silently stops recognizing headings the moment
+ * the real grammar gains a prefix or id shape.
+ */
+export function buildWrongDepthTaskHeadingRegex(flags = "gm") {
+    return new RegExp(`^###\\s+${TASK_HEADING_PREFIX_PATTERN}Task\\s+(${TASK_ID_PATTERN}):`, flags);
+}
+/**
+ * Serialize a task heading. The single writer-side counterpart to
+ * {@link buildTaskHeadingRegex}: every emitter goes through here so the
+ * written form and the parsed form cannot diverge.
+ *
+ * Lane is deliberately not a parameter. The reader accepts an optional
+ * `[lane]` heading prefix for hand-authored blueprints, but the writer emits
+ * lane as a `**Lane:**` body line instead, so round-tripping never has to
+ * reconstruct a prefix the writer does not produce.
+ */
+export function formatTaskHeading(taskId, title) {
+    return `#### Task ${taskId}: ${title}`;
+}

package/dist/esm/blueprint/trust/command-runner.d.ts

@@ -1,6 +1,7 @@
 import { spawnSync } from "node:child_process";
 export declare const ALLOWED_WP_COMMAND_TIMEOUT_MS = 30000;
 export declare const ALLOWED_WP_COMMAND_STDIO_TAIL_LIMIT = 500;
+export declare const ALLOWED_WP_COMMAND_CAPTURE_LIMIT = 1000000;
 export type AllowedWpCommandOutcome = "passed" | "failed" | "timed-out";
 export interface AllowedWpCommandResult {
     readonly command: string;
@@ -21,6 +22,45 @@ export interface ExecuteAllowedWpCommandInput {
     readonly env?: NodeJS.ProcessEnv;
     readonly spawn?: typeof spawnSync;
 }
+export interface ResolvedWpInvocation {
+    readonly command: string;
+    readonly args: string[];
+    readonly env: NodeJS.ProcessEnv;
+}
+export interface ResolveInvocationOptions {
+    /**
+     * Replace `process.env` with `extraEnv` as the base environment instead of
+     * spreading over it. Used by the sandboxed delivery path so caller secrets
+     * never reach the child; the promotion path keeps the default spread.
+     */
+    readonly replaceProcessEnv?: boolean;
+}
+export interface RunResolvedInvocationContext {
+    /** The original human-readable command string, for logging/reporting. */
+    readonly command: string;
+    readonly executionRoot: string;
+    readonly logRoot: string;
+    readonly startedAt: number;
+    readonly spawn?: typeof spawnSync;
+    readonly signal?: AbortSignal;
+}
 export declare function executeAllowedWpCommand(input: ExecuteAllowedWpCommandInput): AllowedWpCommandResult;
+/** Parses an allowed `wp` command string and resolves it to a spawnable invocation. */
+export declare function resolveInvocationFromCommand(executionRoot: string, command: string, env: NodeJS.ProcessEnv | undefined, options?: ResolveInvocationOptions): ResolvedWpInvocation;
+/** Builds the `command-policy-rejected` result (invocation could not be resolved). */
+export declare function rejectedInvocationResult(command: string, logRoot: string, startedAt: number, error: unknown): AllowedWpCommandResult;
+/** Runs a resolved invocation synchronously (promotion trust path). */
+export declare function runResolvedInvocationSync(invocation: ResolvedWpInvocation, context: RunResolvedInvocationContext): AllowedWpCommandResult;
+/**
+ * Runs a resolved invocation asynchronously with bounded process-tree
+ * termination. The child leads its own process group (`detached`), so a manual
+ * timeout, an abort signal, or normal completion all `SIGKILL` the whole group —
+ * reaping descendants a hostile gate may have forked. On Linux srt's bwrap
+ * `--unshare-pid` already reaps the sandbox PID namespace; this is the macOS
+ * backstop (a descendant that calls `setsid()` can still escape the group — a
+ * documented residual, contained by the disposable checkout and network deny).
+ */
+export declare function runResolvedInvocationAsync(invocation: ResolvedWpInvocation, context: RunResolvedInvocationContext): Promise<AllowedWpCommandResult>;
 export declare function tailBounded(text: string): string;
 export declare function relativeCommandLogPath(root: string, logPath: string | undefined): string | undefined;
+export declare function resolveAllowedWpInvocation(executionRoot: string, binary: string, args: readonly string[], extraEnv: NodeJS.ProcessEnv | undefined, options?: ResolveInvocationOptions): ResolvedWpInvocation;

package/dist/esm/blueprint/trust/command-runner.js

@@ -1,70 +1,294 @@
-import { spawnSync } from "node:child_process";
+import { spawn as spawnChild, spawnSync } from "node:child_process";
 import { existsSync, mkdirSync, writeFileSync } from "node:fs";
 import { join, relative } from "node:path";
 import { parseAllowedWpCommand } from "./gates.js";
 import { resolvePackageAssetPreferred } from "#utils/package-assets.js";
 export const ALLOWED_WP_COMMAND_TIMEOUT_MS = 30_000;
 export const ALLOWED_WP_COMMAND_STDIO_TAIL_LIMIT = 500;
+// Per-stream capture ceiling. `spawnSync` enforced this implicitly via
+// `maxBuffer` (default 1 MB); the async runner must replace that bound or a
+// target-controlled gate can stream output fast enough to exhaust reviewer
+// memory before the timeout fires. On breach we stop accumulating and kill the
+// process group, mirroring spawnSync's ENOBUFS termination.
+export const ALLOWED_WP_COMMAND_CAPTURE_LIMIT = 1_000_000;
 export function executeAllowedWpCommand(input) {
-    const started = Date.now();
+    const startedAt = Date.now();
+    const context = {
+        command: input.command,
+        executionRoot: input.executionRoot,
+        logRoot: input.logRoot,
+        startedAt,
+        ...(input.spawn ? { spawn: input.spawn } : {}),
+    };
     let invocation;
     try {
-        const argv = parseAllowedWpCommand(input.command);
-        const [binary, ...args] = argv;
-        if (binary === undefined)
-            throw new Error(`Promotion gate command is empty: ${input.command}`);
-        invocation = resolveAllowedWpInvocation(input.executionRoot, binary, args, input.env);
+        invocation = resolveInvocationFromCommand(input.executionRoot, input.command, input.env);
     }
     catch (error) {
-        const message = error instanceof Error ? error.message : String(error);
-        const result = {
-            command: input.command,
-            outcome: "failed",
-            durationMs: Date.now() - started,
-            exitCode: null,
-            stdout: "",
-            stderr: message,
-            failureCode: "command-policy-rejected",
-            errorMessage: message,
-        };
-        return {
-            ...result,
-            logPath: writeAllowedWpCommandLog(input.logRoot, input.command, null, result),
-        };
+        return rejectedInvocationResult(input.command, input.logRoot, startedAt, error);
     }
-    const spawn = input.spawn ?? spawnSync;
+    return runResolvedInvocationSync(invocation, context);
+}
+/** Parses an allowed `wp` command string and resolves it to a spawnable invocation. */
+export function resolveInvocationFromCommand(executionRoot, command, env, options) {
+    const argv = parseAllowedWpCommand(command);
+    const [binary, ...args] = argv;
+    if (binary === undefined)
+        throw new Error(`Promotion gate command is empty: ${command}`);
+    return resolveAllowedWpInvocation(executionRoot, binary, args, env, options);
+}
+/** Builds the `command-policy-rejected` result (invocation could not be resolved). */
+export function rejectedInvocationResult(command, logRoot, startedAt, error) {
+    const message = error instanceof Error ? error.message : String(error);
+    const result = {
+        command,
+        outcome: "failed",
+        durationMs: Date.now() - startedAt,
+        exitCode: null,
+        stdout: "",
+        stderr: message,
+        failureCode: "command-policy-rejected",
+        errorMessage: message,
+    };
+    return { ...result, logPath: writeAllowedWpCommandLog(logRoot, command, null, result) };
+}
+/** Runs a resolved invocation synchronously (promotion trust path). */
+export function runResolvedInvocationSync(invocation, context) {
+    const spawn = context.spawn ?? spawnSync;
     const result = spawn(invocation.command, invocation.args, {
-        cwd: input.executionRoot,
+        cwd: context.executionRoot,
         encoding: "utf8",
         stdio: ["ignore", "pipe", "pipe"],
         timeout: ALLOWED_WP_COMMAND_TIMEOUT_MS,
         env: invocation.env,
     });
-    const durationMs = Date.now() - started;
     const stdout = typeof result.stdout === "string" ? result.stdout : "";
     const stderr = typeof result.stderr === "string" ? result.stderr : "";
     const timedOut = result.error ? errorCode(result.error) === "ETIMEDOUT" : false;
+    return shapeInvocationResult(context.command, invocation, {
+        status: typeof result.status === "number" ? result.status : null,
+        signal: result.signal ?? null,
+        error: result.error,
+        stdout,
+        stderr,
+        timedOut,
+        durationMs: Date.now() - context.startedAt,
+    }, context.logRoot);
+}
+/**
+ * Runs a resolved invocation asynchronously with bounded process-tree
+ * termination. The child leads its own process group (`detached`), so a manual
+ * timeout, an abort signal, or normal completion all `SIGKILL` the whole group —
+ * reaping descendants a hostile gate may have forked. On Linux srt's bwrap
+ * `--unshare-pid` already reaps the sandbox PID namespace; this is the macOS
+ * backstop (a descendant that calls `setsid()` can still escape the group — a
+ * documented residual, contained by the disposable checkout and network deny).
+ */
+export function runResolvedInvocationAsync(invocation, context) {
+    return new Promise((resolve) => {
+        const child = spawnChild(invocation.command, invocation.args, {
+            cwd: context.executionRoot,
+            env: invocation.env,
+            stdio: ["ignore", "pipe", "pipe"],
+            detached: true,
+        });
+        let stdout = "";
+        let stderr = "";
+        let timedOut = false;
+        let captureExceeded = false;
+        let settled = false;
+        const appendBounded = (current, chunk) => {
+            if (current.length >= ALLOWED_WP_COMMAND_CAPTURE_LIMIT)
+                return current;
+            return (current + chunk.toString("utf8")).slice(0, ALLOWED_WP_COMMAND_CAPTURE_LIMIT);
+        };
+        const enforceCapture = () => {
+            if (!captureExceeded &&
+                (stdout.length >= ALLOWED_WP_COMMAND_CAPTURE_LIMIT ||
+                    stderr.length >= ALLOWED_WP_COMMAND_CAPTURE_LIMIT)) {
+                captureExceeded = true;
+                killProcessGroup(child.pid);
+            }
+        };
+        child.stdout?.on("data", (chunk) => {
+            stdout = appendBounded(stdout, chunk);
+            enforceCapture();
+        });
+        child.stderr?.on("data", (chunk) => {
+            stderr = appendBounded(stderr, chunk);
+            enforceCapture();
+        });
+        const timer = setTimeout(() => {
+            timedOut = true;
+            killProcessGroup(child.pid);
+        }, ALLOWED_WP_COMMAND_TIMEOUT_MS);
+        let aborted = false;
+        const onAbort = () => {
+            aborted = true;
+            killProcessGroup(child.pid);
+        };
+        context.signal?.addEventListener("abort", onAbort, { once: true });
+        // Close the abort race: a signal that fired between the caller's pre-check
+        // and this listener registration does not replay, so recheck now and kill
+        // immediately if it is already aborted.
+        if (context.signal?.aborted)
+            onAbort();
+        const finish = (status, signal, error) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            context.signal?.removeEventListener("abort", onAbort);
+            killProcessGroup(child.pid);
+            // Confirm the process GROUP is actually dead before resolving, so the
+            // caller's sandbox/filesystem cleanup cannot race a descendant a hostile
+            // gate forked: SIGKILL is delivered above but reaping is asynchronous. A
+            // DETECTABLE survivor still in the group fails the gate (reapUnconfirmed,
+            // never silent). A descendant that ESCAPED the group (macOS `setsid()`) is
+            // invisible here — the documented, contained residual (see
+            // awaitProcessGroupExit).
+            void awaitProcessGroupExit(child.pid).then((reaped) => {
+                resolve(shapeInvocationResult(context.command, invocation, {
+                    status,
+                    signal,
+                    error: error ? { message: error.message, code: errorCode(error) } : undefined,
+                    stdout,
+                    stderr,
+                    timedOut,
+                    captureExceeded,
+                    aborted,
+                    reapUnconfirmed: !reaped,
+                    durationMs: Date.now() - context.startedAt,
+                }, context.logRoot));
+            });
+        };
+        let exitCode = null;
+        let exitSignal = null;
+        // B1: on macOS a setsid() descendant can leave the process group while still
+        // holding inherited stdout/stderr write ends. Node fires `exit` when the
+        // direct child ends, but `close` only after all stdio ends — so a survivor
+        // wedging the pipes would hang forever. On `exit`, start a stdio grace equal
+        // to PROCESS_GROUP_REAP_TIMEOUT_MS; if `close` has not settled by then,
+        // destroy the streams and finish anyway (reapUnconfirmed already reports
+        // detectable survivors).
+        let stdioGrace;
+        child.on("error", (error) => {
+            if (stdioGrace !== undefined)
+                clearTimeout(stdioGrace);
+            finish(null, null, error);
+        });
+        child.on("exit", (code, signal) => {
+            exitCode = code;
+            exitSignal = signal;
+            // Reap backgrounded descendants still holding the stdio pipes so `close`
+            // can fire promptly (a hostile gate may fork a child that outlives it).
+            killProcessGroup(child.pid);
+            if (settled)
+                return;
+            stdioGrace = setTimeout(() => {
+                if (settled)
+                    return;
+                child.stdout?.destroy();
+                child.stderr?.destroy();
+                finish(exitCode, exitSignal);
+            }, PROCESS_GROUP_REAP_TIMEOUT_MS);
+        });
+        child.on("close", () => {
+            if (stdioGrace !== undefined)
+                clearTimeout(stdioGrace);
+            finish(exitCode, exitSignal);
+        });
+    });
+}
+// Poll interval and ceiling for confirming a killed process group has actually
+// exited. Short interval; the normal case (no surviving descendant) resolves on
+// the first probe. The ceiling bounds a wedged/escaped descendant.
+const PROCESS_GROUP_REAP_POLL_MS = 20;
+const PROCESS_GROUP_REAP_TIMEOUT_MS = 2_000;
+function processGroupAlive(pid) {
+    try {
+        // Signal 0 to the NEGATIVE pid probes the whole group without delivering a
+        // signal: no error => a member is alive; ESRCH => the group is empty.
+        process.kill(-pid, 0);
+        return true;
+    }
+    catch (error) {
+        // EPERM means a member exists but is not signalable by us — treat as alive.
+        return error instanceof Error && errorCode(error) === "EPERM";
+    }
+}
+// Confirm a killed process group has actually exited. Returns true when the
+// group is empty; false when a member is still alive after the ceiling — a
+// DETECTABLE survivor that must surface as a failed verification, not be
+// swallowed silently.
+//
+// macOS RESIDUAL: a descendant that calls `setsid()` LEAVES this group and
+// reparents to launchd, so it is invisible here. macOS has no PID
+// namespace/cgroup to track it, and `ps` cannot enumerate a descendant's env
+// either (verified), so such a process cannot be guaranteed-reaped in
+// unprivileged userspace. It is contained by the network deny (no exfiltration)
+// and the disposable checkout (no persistence) and can only spin CPU until it
+// exits. On Linux, srt's bwrap `--unshare-pid` reaps the whole tree, so this
+// ceiling is never reached there.
+async function awaitProcessGroupExit(pid) {
+    if (pid === undefined)
+        return true;
+    const deadline = Date.now() + PROCESS_GROUP_REAP_TIMEOUT_MS;
+    while (processGroupAlive(pid)) {
+        if (Date.now() >= deadline)
+            return false;
+        await new Promise((resolve) => {
+            setTimeout(resolve, PROCESS_GROUP_REAP_POLL_MS);
+        });
+    }
+    return true;
+}
+function shapeInvocationResult(command, invocation, parts, logRoot) {
     const output = {
-        command: input.command,
-        outcome: result.status === 0 && !result.error && result.signal === null
+        command,
+        outcome: parts.status === 0 &&
+            !parts.error &&
+            parts.signal === null &&
+            !parts.captureExceeded &&
+            !parts.aborted &&
+            !parts.reapUnconfirmed
             ? "passed"
-            : timedOut
+            : parts.timedOut
                 ? "timed-out"
                 : "failed",
-        durationMs,
-        exitCode: typeof result.status === "number" ? result.status : null,
-        ...(result.signal ? { signal: result.signal } : {}),
-        stdout,
-        stderr,
-        ...(timedOut ? { failureCode: "command-timed-out" } : {}),
-        ...(result.error ? { errorMessage: result.error.message } : {}),
+        durationMs: parts.durationMs,
+        exitCode: parts.status,
+        ...(parts.signal ? { signal: parts.signal } : {}),
+        stdout: parts.stdout,
+        stderr: parts.stderr,
+        ...(parts.aborted
+            ? { failureCode: "command-cancelled" }
+            : parts.timedOut
+                ? { failureCode: "command-timed-out" }
+                : parts.captureExceeded
+                    ? { failureCode: "command-output-exceeded" }
+                    : parts.reapUnconfirmed
+                        ? { failureCode: "process-reap-unconfirmed" }
+                        : {}),
+        ...(parts.error
+            ? { errorMessage: parts.error.message }
+            : parts.captureExceeded
+                ? { errorMessage: "gate output exceeded the capture limit (possible resource exhaustion)" }
+                : {}),
     };
     if (output.outcome === "passed")
         return output;
-    return {
-        ...output,
-        logPath: writeAllowedWpCommandLog(input.logRoot, input.command, invocation, output),
-    };
+    return { ...output, logPath: writeAllowedWpCommandLog(logRoot, command, invocation, output) };
+}
+function killProcessGroup(pid) {
+    if (pid === undefined)
+        return;
+    try {
+        process.kill(-pid, "SIGKILL");
+    }
+    catch {
+        // The group is already gone (normal completion) — nothing to reap.
+    }
 }
 export function tailBounded(text) {
     if (text.length <= ALLOWED_WP_COMMAND_STDIO_TAIL_LIMIT)
@@ -77,8 +301,8 @@ export function relativeCommandLogPath(root, logPath) {
     const rel = relative(root, logPath).replace(/\\/gu, "/");
     return rel === "" || rel.startsWith("../") ? logPath : rel;
 }
-function resolveAllowedWpInvocation(executionRoot, binary, args, extraEnv) {
-    const baseEnv = { ...process.env, ...extraEnv };
+export function resolveAllowedWpInvocation(executionRoot, binary, args, extraEnv, options) {
+    const baseEnv = options?.replaceProcessEnv ? { ...extraEnv } : { ...process.env, ...extraEnv };
     if (binary === "./bin/wp" || binary === "wp") {
         const localLauncher = resolveRepoWpLauncher(executionRoot);
         if (localLauncher !== null) {

package/dist/esm/build/cli-mcp-parity.js

@@ -50,6 +50,11 @@ export const CLI_MCP_PARITY_CLASSIFICATION = {
         classification: "follow-up-candidate",
         reason: "local pre-push aggregator of the required-check verbs; CLI-only dev gate with no dedicated MCP tool",
     },
+    "release-progress": {
+        command: "release-progress",
+        classification: "follow-up-candidate",
+        reason: "operator/agent Release workflow phase reporter (detect/native-matrix/publish); CLI-only, uses gh API",
+    },
     cleanup: {
         command: "cleanup",
         classification: "unsafe-credentialed-destructive",

package/dist/esm/ci/native-session-memory-cache.d.ts

@@ -22,7 +22,8 @@ export declare const NATIVE_SESSION_MEMORY_CACHE_SUBDIR = "session-memory-engine
 export declare const NATIVE_SESSION_MEMORY_TRUST_CACHED_NODE_ENV = "WP_NATIVE_SESSION_MEMORY_TRUST_CACHED_NODE";
 /**
  * Relative path fragments used in GHA `hashFiles` for the warm-cache key.
- * Must match the Test job warm step in ci.agent-kit.yml exactly (contract test).
+ * Must match the Test job warm step in ci.agent-kit.yml and the release native
+ * matrix `sm-release-node-*` key in release.yml exactly (contract tests).
  * Absolute cache dir still comes from env-paths / CACHE_ROOT override at runtime.
  */
 export declare const NATIVE_SESSION_MEMORY_CACHE_HASH_GLOBS: readonly ["native/session-memory-engine/Cargo.lock", "native/session-memory-engine/Cargo.toml", "native/session-memory-engine/crates/**/*.rs", "native/session-memory-engine/crates/**/Cargo.toml"];

package/dist/esm/ci/native-session-memory-cache.js

@@ -22,7 +22,8 @@ export const NATIVE_SESSION_MEMORY_CACHE_SUBDIR = "session-memory-engine";
 export const NATIVE_SESSION_MEMORY_TRUST_CACHED_NODE_ENV = "WP_NATIVE_SESSION_MEMORY_TRUST_CACHED_NODE";
 /**
  * Relative path fragments used in GHA `hashFiles` for the warm-cache key.
- * Must match the Test job warm step in ci.agent-kit.yml exactly (contract test).
+ * Must match the Test job warm step in ci.agent-kit.yml and the release native
+ * matrix `sm-release-node-*` key in release.yml exactly (contract tests).
  * Absolute cache dir still comes from env-paths / CACHE_ROOT override at runtime.
  */
 export const NATIVE_SESSION_MEMORY_CACHE_HASH_GLOBS = [

package/dist/esm/ci/release-progress.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Classify a GitHub Actions Release run into operator-facing progress phases.
+ *
+ * After Version Packages merge, agents must not sit on silent `npm view` polls:
+ * merge, native matrix, and npm publish are separate states. This pure helper
+ * maps job list snapshots (from `gh run view --json jobs`) into those states.
+ */
+export type ReleaseProgressPhase = "detect" | "native-matrix" | "publish" | "done" | "failed";
+export interface ReleaseJobSnapshot {
+    readonly name: string;
+    readonly status: string;
+    readonly conclusion: string | null | undefined;
+}
+export interface ReleaseProgress {
+    readonly phase: ReleaseProgressPhase;
+    readonly detail: string;
+    readonly native: {
+        readonly done: number;
+        readonly total: number;
+        readonly failed: number;
+        readonly inProgress: number;
+    };
+    readonly publishRunning: boolean;
+    readonly publishDone: boolean;
+    readonly publishFailed: boolean;
+}
+/**
+ * Classify release workflow jobs into a single progress phase for agent/ops reporting.
+ */
+export declare function classifyReleaseRunProgress(jobs: readonly ReleaseJobSnapshot[]): ReleaseProgress;
+/** Format one line for agent/ops logs (merge vs matrix vs publish). */
+export declare function formatReleaseProgressLine(progress: ReleaseProgress): string;
+/**
+ * Parse `gh run view <id> --json jobs` (or full run object with `jobs`) into snapshots.
+ * Production CLI and tests share this path so classification is never reimplemented.
+ */
+export declare function jobsFromGhRunViewJson(payload: unknown): ReleaseJobSnapshot[];