brl-subagent 2.5.0 → 2.5.1

package/src/kill-escalation.ts

@@ -22,6 +22,49 @@
  * flips when SIGTERM is SENT, so gating SIGKILL on it skips escalation for a
  * SIGTERM-ignoring child (issue #303). What is shared is the
  * terminate-then-escalate order and the no-throw-on-vanished discipline.
+ *
+ * #299 Option B adds two target shapes and one sequence addition:
+ *   - `groupTarget` signals the process GROUP best-effort AND the pid directly
+ *     (D2/D3) — the group catches env-scrubbed descendants the marker cannot;
+ *     the direct signal is never replaced (a `#322` non-detached child has no
+ *     group of its own, so `-pid` is ESRCH while the direct signal still lands).
+ *   - `processTarget` picks the group shape when a `killGroup` primitive is
+ *     supplied (POSIX; D4), else the direct-only `pidTarget` (Windows; D6).
+ *   - after the grace window `escalateKill` calls an optional `forceKillGroup`
+ *     UNCONDITIONALLY (D5), so a TERM-stubborn member survives neither the
+ *     leader exiting early nor the leader-based survivor check.
+ *
+ * #299 REVIEW FIX (review round on `62e2537`) closes the two majors:
+ *   - Major 1 (pid reuse): a marker pid verified by a `/proc` scan at SCAN time
+ *     may exit and be reused before the signal. `SignalGuard` re-reads the live
+ *     marker IMMEDIATELY before every marker-derived signal; a pid that is alive
+ *     but no longer carries the marker (the reuse case) is never signaled, group
+ *     or direct. The residual read→`kill` window is documented on the guard.
+ *   - Major 2 (grace bypassed): a group target's `verifyDeath` is now LEADER DEAD
+ *     **AND** GROUP EMPTY (`groupHasMembers`), so a dead leader no longer reads
+ *     as "all dead" and the escalation honours the grace window for a member's
+ *     cleanup. The unconditional `forceKillGroup` still ends a TERM-stubborn
+ *     member, but only after the grace window. `verifyProcessAlive` keeps the
+ *     direct `forceKill` (and the survivor report) honest for a group target
+ *     whose leader already exited, so the final group SIGKILL stays the sole
+ *     mechanism for that case (the D5 tripwire).
+ *
+ * #299 RE-REVIEW FIX A.1 closes one more major on `0fa2fc2`:
+ *   - A reaped pid must classify as GONE in `pidGone` (positive `kill(pid,0)`
+ *     sample + `/proc/<pid>/stat` ENOENT — see src/proc.ts), so our own reaped
+ *     leader is not mistaken for a live FOREIGN pid and refused its group kill.
+ *   - Honest reporting: a REFUSED final group SIGKILL over a group that still
+ *     has live members is counted as a survivor (`refusedForceKillGroup`), so a
+ *     guard decision can never yield a clean `survivors=[]` over a live group we
+ *     targeted. The skip log is unchanged.
+ *
+ * #299 FIX A.2 closes one more major on `ae6d313`:
+ *   - Group membership is THREE-state (`true` / positively-empty `false` /
+ *     `unknown` = `undefined`). A partial or unavailable inspection must never
+ *     read as empty: `groupTarget.verifyDeath` treats `unknown` as NOT dead (no
+ *     early-exit; the unconditional final group SIGKILL still fires) and
+ *     `refusedForceKillGroup` treats `unknown` as a survivor (fail-safe
+ *     reporting). Only a POSITIVELY empty group may report clean.
  */
 
 /** A process handle the escalation helper can signal and liveness-check. */
@@ -30,8 +73,260 @@ export interface EscalationTarget {
 	terminate(): void;
 	/** Send SIGKILL; may throw when the target is already gone. */
 	forceKill(): void;
-	/** True when the target is confirmed dead (so no SIGKILL is needed). */
+	/** True when the target is confirmed dead (group-empty for a group target). */
 	verifyDeath(): boolean;
+	/**
+	 * #299 review Major 2: true when the DIRECT process the target names is still
+	 * alive. A group target's `verifyDeath` is group-empty (a dead leader with a
+	 * live member is NOT dead), but `forceKill` signals the leader directly; the
+	 * escalation consults this so it never force-kills an already-exited leader.
+	 * Such a group is ended by the unconditional `forceKillGroup` instead, which
+	 * keeps D5's tripwire honest. Absent = treat as alive (direct-only targets).
+	 */
+	verifyProcessAlive?(): boolean;
+	/**
+	 * #299 Option B D5: optional UNCONDITIONAL final group SIGKILL, called for
+	 * every target after the grace window even when `verifyDeath()` reports the
+	 * leader dead. A group target's `verifyDeath` is group-empty, so a
+	 * TERM-stubborn member whose group leader already exited would otherwise never
+	 * be force-killed. Must tolerate ESRCH (a vanished/empty group is the desired
+	 * end state). Absent on direct-only pid targets.
+	 */
+	forceKillGroup?(): void;
+	/**
+	 * #299 re-review A.1: true when the FINAL group SIGKILL above was REFUSED by
+	 * the signal guard AND the targeted group still has live members — i.e. the
+	 * escalation deliberately left a live group it could not verify as ours.
+	 * `escalateKill` counts such a target as a survivor, so a refused group kill
+	 * can never be reported as a clean `survivors=[]`. Absent on direct-only
+	 * targets (no group to leave behind).
+	 */
+	refusedForceKillGroup?(): boolean;
+}
+
+/**
+ * True when the platform offers POSIX process groups: `detached: true` makes a
+ * child a session/group leader and `kill(-pgid)` signals the whole group.
+ * Windows has neither, so every group path falls back to direct signals (D6).
+ *
+ * `__setProcessGroupKillSupportedForTest` is the injectable seam that lets a
+ * test prove the Windows fallback without running on Windows.
+ */
+let processGroupKillOverride: boolean | undefined;
+
+export function supportsProcessGroupKill(): boolean {
+	if (processGroupKillOverride !== undefined) return processGroupKillOverride;
+	return process.platform !== "win32";
+}
+
+/**
+ * TEST-ONLY: force the process-group capability answer (undefined restores real
+ * platform detection), mirroring `__setProcAvailableForTest` in `src/proc.ts`.
+ */
+export function __setProcessGroupKillSupportedForTest(value: boolean | undefined): void {
+	processGroupKillOverride = value;
+}
+
+/**
+ * #299 review Major 1 — signal-time identity guard for MARKER-DERIVED targets.
+ *
+ * A marker pid comes from a `/proc` scan at SCAN time; between that scan and the
+ * signal the pid may exit and be reused by an unrelated process. Every signal
+ * derived from a marker pid must therefore be preceded by an immediate
+ * re-verification that the pid is still OURS. `isOwn(pid)` performs that read
+ * (the LIVE `/proc/<pid>/environ` marker) and is consulted at each dispatch:
+ *
+ *   - direct pid signal — allowed only when `isOwn(pid)` is true;
+ *   - group signal — allowed when `isOwn(pid)` is true OR the pid is confirmed
+ *     GONE (`!pidAlive(pid)`). A dead leader's pgid cannot have been reused by a
+ *     LIVE foreign leader, so `kill(-pgid)` can only reach our surviving members
+ *     (this keeps D5's group SIGKILL for a TERM-stubborn member working after the
+ *     leader exits). An ALIVE pid that no longer carries the marker IS the
+ *     review's reused-pid case: EVERY signal is skipped, never unverified.
+ *
+ * `onSkip` records a refused signal. A skipped signal is never retried
+ * unverified.
+ *
+ * `isGone(pid)` separates a REUSED pid from a merely GONE one: a zombie (not yet
+ * reaped) and a reaped pid are both "gone", while an alive process that no
+ * longer carries the marker is the reuse case. The group signal is skipped ONLY
+ * for the alive-foreign case — a gone/zombie leader's pgid must still be signaled
+ * so its surviving members (D5) are reached.
+ *
+ * RESIDUAL (documented at the call sites too): the re-check narrows the reuse
+ * window to the read→`kill` syscall boundary — the same exposure the direct
+ * signals have carried since Option A. It is narrowed, not eliminated.
+ */
+export interface SignalGuard {
+	/** True when `pid` still carries OUR marker at this instant. */
+	isOwn(pid: number): boolean;
+	/** True when `pid` is gone: reaped OR a not-yet-reaped zombie. */
+	isGone(pid: number): boolean;
+	/** Called when a signal is refused (verification failed). */
+	onSkip?(pid: number, signal: NodeJS.Signals, phase: SignalPhase): void;
+}
+
+/** Which dispatch attempt a guard check precedes (for skip logging). */
+export type SignalPhase = "terminate" | "forceKill" | "forceKillGroup";
+
+/**
+ * The DIRECT-signal guard dispatch shared by `pidTarget` and `groupTarget`: the
+ * signal runs only while `pid` still carries OUR marker, otherwise the refusal
+ * is recorded and the signal is skipped (Major 1). `groupTarget` keeps a
+ * separate dispatch for the GROUP signal, which additionally honours a
+ * confirmed-gone leader and remembers a refused final group SIGKILL.
+ */
+function dispatchIfOwned(
+	pid: number,
+	guard: SignalGuard | undefined,
+	signal: NodeJS.Signals,
+	phase: SignalPhase,
+	run: () => void,
+): void {
+	if (guard && !guard.isOwn(pid)) {
+		guard.onSkip?.(pid, signal, phase);
+		return;
+	}
+	run();
+}
+
+/**
+ * Build the `EscalationTarget` for ONE pid from injected kill/liveness
+ * primitives. Shared by the boot-scan reap (`reapPids`) and the marker sweeps
+ * (`reapActiveChildren`, the run-exit sweep) so the pid-target shape —
+ * SIGTERM, SIGKILL, `verifyDeath` = pid-not-alive — cannot drift between sites.
+ *
+ * `guard` (optional) re-verifies a marker-derived pid at signal time (Major 1);
+ * an absent guard leaves the historical unconditional direct target.
+ */
+export function pidTarget(
+	pid: number,
+	kill: (pid: number, signal: NodeJS.Signals) => void,
+	pidAlive: (pid: number) => boolean,
+	guard?: SignalGuard,
+): EscalationTarget {
+	return {
+		terminate: () => dispatchIfOwned(pid, guard, "SIGTERM", "terminate", () => kill(pid, "SIGTERM")),
+		forceKill: () => dispatchIfOwned(pid, guard, "SIGKILL", "forceKill", () => kill(pid, "SIGKILL")),
+		verifyDeath: () => {
+			if (guard) return guard.isGone(pid) || !guard.isOwn(pid);
+			return !pidAlive(pid);
+		},
+	};
+}
+
+/** Best-effort group signal: a vanished/empty group (ESRCH) is success. */
+function bestEffortGroupKill(
+	killGroup: (pgid: number, signal: NodeJS.Signals) => void,
+	pgid: number,
+	signal: NodeJS.Signals,
+): void {
+	try {
+		killGroup(pgid, signal);
+	} catch {
+		// Best-effort per D2/D3: the group may not exist (a non-detached target,
+		// or a leader that already exited). The direct signal is never skipped.
+	}
+}
+
+/**
+ * #299 Option B D2/D3: build a GROUP-reaching target for one pid — signal the
+ * process group (`kill(-pid)`) best-effort AND the pid directly. The direct
+ * signal is never replaced: a `#322` test-seam child may not be a group leader,
+ * so `-pid` names no group (ESRCH) while the direct signal still lands.
+ *
+ * #299 review Major 2: `verifyDeath` is LEADER DEAD **AND** GROUP EMPTY — a
+ * leader exiting does not empty the group, so the escalation waits out the grace
+ * for a member's cleanup. `groupHasMembers` is the injected /proc reader; when
+ * absent (no /proc platform) it degrades to leader liveness (documented
+ * boundary). #299 fix A.2 makes that reader THREE-state: `undefined` (inspection
+ * unavailable or partial) is UNKNOWN and must never read as empty, so
+ * `verifyDeath` reports NOT dead until a COMPLETED inspection proves emptiness.
+ * `verifyProcessAlive` exposes the DIRECT leader liveness so `forceKill` is never
+ * sent to an already-exited leader — the unconditional `forceKillGroup` below
+ * remains the sole end for a stubborn GROUP member after the leader is gone
+ * (D5).
+ *
+ * `guard` (optional) re-verifies a marker-derived pid at signal time (Major 1).
+ */
+export function groupTarget(
+	pid: number,
+	kill: (pid: number, signal: NodeJS.Signals) => void,
+	killGroup: (pgid: number, signal: NodeJS.Signals) => void,
+	pidAlive: (pid: number) => boolean,
+	groupHasMembers?: (pgid: number) => boolean | undefined,
+	guard?: SignalGuard,
+): EscalationTarget {
+	// A group signal is skipped ONLY for a live pid that is no longer ours (the
+	// reused-pid case). A gone/zombie leader's pgid can only name our surviving
+	// members, so the group signal must still land (D5).
+	// #299 re-review A.1: remember a REFUSED final group SIGKILL so the escalation
+	// can report the still-live group it could not end (never a clean report).
+	let finalGroupRefused = false;
+	const dispatchGroup = (signal: NodeJS.Signals, phase: SignalPhase, run: () => void): void => {
+		if (guard && !guard.isOwn(pid) && !guard.isGone(pid)) {
+			guard.onSkip?.(pid, signal, phase);
+			if (phase === "forceKillGroup") finalGroupRefused = true;
+			return;
+		}
+		run();
+	};
+	return {
+		terminate: () => {
+			dispatchGroup("SIGTERM", "terminate", () => bestEffortGroupKill(killGroup, pid, "SIGTERM"));
+			dispatchIfOwned(pid, guard, "SIGTERM", "terminate", () => kill(pid, "SIGTERM"));
+		},
+		forceKill: () => {
+			dispatchGroup("SIGKILL", "forceKill", () => bestEffortGroupKill(killGroup, pid, "SIGKILL"));
+			dispatchIfOwned(pid, guard, "SIGKILL", "forceKill", () => kill(pid, "SIGKILL"));
+		},
+		verifyProcessAlive: () => (guard ? !guard.isGone(pid) && guard.isOwn(pid) : pidAlive(pid)),
+		verifyDeath: () => {
+			// A live member keeps the group (and so the target) alive even after the
+			// leader is gone — including a not-yet-reaped ZOMBIE leader, which
+			// `pidAlive` still reports as alive (Major 2).
+			//
+			// #299 fix A.2: membership is THREE-state. `true` (live members) and
+			// `undefined` (inspection unavailable or partial — UNKNOWN) both mean the
+			// group is NOT confirmed empty, so the target is NOT dead and the escalation
+			// honours the full grace window. Only `false` (a COMPLETED inspection found
+			// no live member) lets the leader-liveness check decide. An ABSENT reader (no
+			// /proc platform) keeps the documented leader-only fallback.
+			if (groupHasMembers && groupHasMembers(pid) !== false) return false;
+			if (guard) return guard.isGone(pid) || !guard.isOwn(pid);
+			return !pidAlive(pid); // no guard: leader-only fallback
+		},
+		forceKillGroup: () => {
+			dispatchGroup("SIGKILL", "forceKillGroup", () => bestEffortGroupKill(killGroup, pid, "SIGKILL"));
+		},
+		// #299 re-review A.1: a refused final group SIGKILL over a group that still
+		// has live members is a real survivor — the escalation left a live group it
+		// could not verify as ours.
+		//
+		// #299 fix A.2: only a POSITIVELY empty group (`false`) may report clean.
+		// `undefined` (unknown inspection) and an ABSENT reader both mean emptiness
+		// could not be established, so the fail-safe is to count a survivor.
+		refusedForceKillGroup: () =>
+			finalGroupRefused && (groupHasMembers ? groupHasMembers(pid) !== false : true),
+	};
+}
+
+/**
+ * Choose the group-reaching target when a group primitive is available (POSIX;
+ * D4), else the direct-only `pidTarget` (Windows fallback; D6). The presence of
+ * `killGroup` IS the capability gate — callers pass it only where supported.
+ */
+export function processTarget(
+	pid: number,
+	kill: (pid: number, signal: NodeJS.Signals) => void,
+	pidAlive: (pid: number) => boolean,
+	killGroup?: (pgid: number, signal: NodeJS.Signals) => void,
+	groupHasMembers?: (pgid: number) => boolean | undefined,
+	guard?: SignalGuard,
+): EscalationTarget {
+	return killGroup
+		? groupTarget(pid, kill, killGroup, pidAlive, groupHasMembers, guard)
+		: pidTarget(pid, kill, pidAlive, guard);
 }
 
 export interface EscalationOptions {
@@ -51,8 +346,21 @@ export interface EscalationOptions {
 
 /**
  * Escalate every target together: SIGTERM all, wait (at most) one grace window,
- * then SIGKILL every target that still verifies alive. Returns the survivors.
- * Never throws on a target that vanished mid-sequence.
+ * then SIGKILL every target that still verifies alive (direct), then the
+ * unconditional final group SIGKILL, then report survivors. Never throws on a
+ * target that vanished mid-sequence.
+ *
+ * #299 review Major 2: the wait uses `verifyDeath`, which for a group target is
+ * LEADER DEAD **AND** GROUP EMPTY, so a leader that dies promptly no longer
+ * short-circuits the grace window for a member still doing cleanup. The direct
+ * `forceKill` (and the survivor report) consult `verifyProcessAlive` so a group
+ * whose leader already exited is not direct-signaled — its surviving member is
+ * ended by the unconditional `forceKillGroup` below (the D5 mechanism).
+ *
+ * #299 re-review A.1: after the unconditional group SIGKILL loop, any target
+ * whose final group signal was REFUSED while its group still had live members is
+ * appended to the survivors (`refusedForceKillGroup`), so a refined guard
+ * decision can never report a clean result over a live group we targeted.
  */
 export async function escalateKill(
 	targets: EscalationTarget[],
@@ -83,12 +391,36 @@ export async function escalateKill(
 	const survivors: EscalationTarget[] = [];
 	for (const target of targets) {
 		if (target.verifyDeath()) continue;
+		// Only force-kill the DIRECT process while it is still alive; a group whose
+		// leader already exited is ended by the unconditional group SIGKILL below.
+		if (target.verifyProcessAlive?.() ?? true) {
+			try {
+				target.forceKill();
+			} catch {
+				// Exited between the liveness check and the signal.
+			}
+		}
+		if (!target.verifyDeath() && (target.verifyProcessAlive?.() ?? true)) survivors.push(target);
+	}
+
+	// D5 (option b): the final GROUP SIGKILL is UNCONDITIONAL. `verifyDeath` is
+	// group-empty (Major 2), so the escalation may reach here while a group is
+	// still non-empty; a TERM-stubborn member whose leader has already exited must
+	// still be killed, and this is the only signal that reaches it. Group targets
+	// swallow ESRCH; pid targets have no `forceKillGroup` and are untouched.
+	for (const target of targets) {
+		if (!target.forceKillGroup) continue;
 		try {
-			target.forceKill();
+			target.forceKillGroup();
 		} catch {
-			// Exited between the liveness check and the signal.
+			// Vanished group — the desired end state.
+		}
+		// #299 re-review A.1: a REFUSED final group SIGKILL over a still-live group
+		// leaves members we targeted alive. Surface that as a survivor so a refined
+		// guard decision can never produce a dishonest `survivors=[]`.
+		if (target.refusedForceKillGroup?.() && !survivors.includes(target)) {
+			survivors.push(target);
 		}
-		if (!target.verifyDeath()) survivors.push(target);
 	}
 	return survivors;
 }

package/src/metrics.ts

@@ -6,7 +6,7 @@
  * against a baseline.
  */
 
-import type { SubagentRun, SLAMetrics, DegradationReport, ErrorCategory } from "./types";
+import { isAbortedRun, type SubagentRun, type SLAMetrics, type DegradationReport, type ErrorCategory } from "./types";
 
 // ---------------------------------------------------------------------------
 // Percentile helper
@@ -58,9 +58,11 @@ export function computeSLAMetrics(runs: SubagentRun[]): SLAMetrics {
 		};
 	}
 
-	// Count successes and failures (running runs are neither)
+	// Count successes and failures (running runs are neither). Aborted runs
+	// (abandoned or user-stopped) are excluded from the failure tally — see
+	// `isAbortedRun`; they are also not successes, so they leave the denominator.
 	const succeeded = runs.filter((r) => r.status === "done").length;
-	const failed = runs.filter((r) => r.status === "failed").length;
+	const failed = runs.filter((r) => r.status === "failed" && !isAbortedRun(r)).length;
 	const finishedRuns = succeeded + failed;
 
 	const successRate = finishedRuns > 0 ? succeeded / finishedRuns : 0;

package/src/notify-completion.ts

@@ -219,6 +219,29 @@ export function markTerminalSeen(seen: Set<string>, id: string, cap = DEDUPE_CAP
 	return true;
 }
 
+/**
+ * Shared terminal-notice claim set (issue #315). ONE module-level surface so
+ * the event-bus wake (`subagent-completion`) and the poller's crash notices
+ * (`subagent-notification`) can never both fire for the same run id. Wraps
+ * `markTerminalSeen`, so the dedupe + cap rule lives in exactly one place.
+ */
+const terminalClaims = new Set<string>();
+
+/**
+ * Claim the single terminal notice for `id`. Returns true when THIS caller
+ * wins the claim (and must deliver), false when another terminal path already
+ * claimed the id. The wake is canonical: its subscriber claims synchronously
+ * on the terminal event, so a later crash notice is suppressed.
+ */
+export function claimTerminalNotice(id: string): boolean {
+	return markTerminalSeen(terminalClaims, id);
+}
+
+/** TEST-ONLY: clear the shared terminal-claim set between test cases. */
+export function __resetTerminalClaims(): void {
+	terminalClaims.clear();
+}
+
 /**
  * THIN sender — the only `pi.sendMessage` call site. One call, no logic.
  * The `delivery` is the resolved output of `resolveDelivery` (D1+D2); it