brl-subagent 2.3.9 → 2.5.0

package/src/kill-escalation.ts

@@ -0,0 +1,94 @@
+// Purpose: The one SIGTERM → grace → SIGKILL escalation shared by foreground reap, abort/timeout, and boot recovery.
+/**
+ * Process kill escalation (Option B U1, review items B4 + B7).
+ *
+ * The SIGTERM → grace → SIGKILL sequence was duplicated four times with
+ * inconsistent wait semantics. This module owns the ONE sequence; each site
+ * supplies its own targets and death check:
+ *
+ *   - `runner.ts` `reapActiveChildren` — every tracked foreground child at once
+ *   - `runner.ts` abort handler          — one child
+ *   - `runner.ts` timeout handler        — one child
+ *   - `recovery.ts` `reapPids`           — every marker-verified orphan at once
+ *
+ * Order is terminate → wait → force-kill. With `pollMs` set the wait ends as
+ * soon as every target verifies dead (B4: the shutdown reap no longer blocks
+ * the full 5 s when children exit promptly), bounded by `graceMs`; without it
+ * the helper waits the full grace once (the boot scan's wait-once shape).
+ *
+ * `verifyDeath` is supplied per site but must always answer "is the process
+ * REALLY dead" — for a child, `exitCode`/`signalCode`; for a pid, `kill -0`
+ * liveness. It must never be a "a signal was delivered" check: `child.killed`
+ * 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.
+ */
+
+/** A process handle the escalation helper can signal and liveness-check. */
+export interface EscalationTarget {
+	/** Send SIGTERM; may throw when the target is already gone. */
+	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). */
+	verifyDeath(): boolean;
+}
+
+export interface EscalationOptions {
+	/** Grace window between SIGTERM and SIGKILL (ms). */
+	graceMs: number;
+	/** Sleep between SIGTERM and the liveness re-check (injectable). */
+	sleep(ms: number): Promise<void>;
+	/**
+	 * Poll interval for the early-exit wait (B4). When > 0 the helper returns as
+	 * soon as every target verifies dead, bounded by `graceMs`; when omitted the
+	 * helper waits the full `graceMs` once.
+	 */
+	pollMs?: number;
+	/** Injectable clock for the deadline (defaults to Date.now). */
+	now?(): number;
+}
+
+/**
+ * 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.
+ */
+export async function escalateKill(
+	targets: EscalationTarget[],
+	options: EscalationOptions,
+): Promise<EscalationTarget[]> {
+	for (const target of targets) {
+		try {
+			target.terminate();
+		} catch {
+			// Already gone — the desired end state.
+		}
+	}
+
+	if (targets.length > 0) {
+		const pollMs = options.pollMs ?? 0;
+		if (pollMs > 0) {
+			const now = options.now ?? Date.now;
+			const deadline = now() + options.graceMs;
+			while (now() < deadline && !targets.every((target) => target.verifyDeath())) {
+				const remaining = Math.max(deadline - now(), 1);
+				await options.sleep(Math.min(pollMs, remaining));
+			}
+		} else {
+			await options.sleep(options.graceMs);
+		}
+	}
+
+	const survivors: EscalationTarget[] = [];
+	for (const target of targets) {
+		if (target.verifyDeath()) continue;
+		try {
+			target.forceKill();
+		} catch {
+			// Exited between the liveness check and the signal.
+		}
+		if (!target.verifyDeath()) survivors.push(target);
+	}
+	return survivors;
+}

package/src/logging.ts

@@ -1,3 +1,4 @@
+// Purpose: Leveled structured logging with file output and rotation under `.pi/subagent-logs/`.
 /**
  * brl-subagent — Structured Logging (F10)
  *
@@ -41,8 +42,49 @@ const LOG_LEVELS: Record<LogLevel, number> = {
 	error: 3,
 };
 
+/** The level names BRL_LOG_LEVEL accepts (the keys of LOG_LEVELS). */
+const LOG_LEVEL_NAMES: readonly LogLevel[] = ["debug", "info", "warn", "error"];
+
 /** Current minimum log level — can be changed at runtime */
-let minLevel: LogLevel = "info";
+let minLevel: LogLevel = resolveInitialLogLevel();
+
+/**
+ * Whether the console mirror is enabled — opt-in via BRL_LOG_CONSOLE (issue #265).
+ * File-only is the default so extension logging never corrupts the pi TUI.
+ */
+let consoleOutput: boolean = resolveInitialConsoleOutput();
+
+/**
+ * Issue #235: the log verbosity knob was never wired, so the three `log.debug()`
+ * call sites were permanently suppressed with no way to turn them on.
+ * `BRL_LOG_LEVEL` is read ONCE at module load (logger call sites are spread
+ * across the codebase, and re-reading env per call would be wasteful and
+ * non-deterministic mid-run). `setLogLevel()` remains the programmatic override.
+ * Anything outside debug|info|warn|error falls back to "info".
+ */
+function resolveInitialLogLevel(): LogLevel {
+	const raw = process.env.BRL_LOG_LEVEL?.trim().toLowerCase();
+	if (raw && (LOG_LEVEL_NAMES as readonly string[]).includes(raw)) {
+		return raw as LogLevel;
+	}
+	return "info";
+}
+
+/**
+ * Issue #265: extension code runs inside pi's TUI process, so a raw console
+ * write lands wherever the renderer's cursor sits and corrupts the display.
+ * File-only is the default; `BRL_LOG_CONSOLE` opts the terminal mirror back in.
+ * Read ONCE at module load for the same reason as BRL_LOG_LEVEL — logger call
+ * sites are spread across the codebase. Accepts `1|true|yes`; anything else is
+ * off. `setConsoleOutput()` remains the programmatic override.
+ *
+ * Explicitly NOT gated on process.stdout.isTTY: in pi print mode stdout IS the
+ * result channel, so that test is exactly backwards.
+ */
+function resolveInitialConsoleOutput(): boolean {
+	const raw = process.env.BRL_LOG_CONSOLE?.trim().toLowerCase();
+	return raw === "1" || raw === "true" || raw === "yes";
+}
 
 // ---------------------------------------------------------------------------
 // Logger
@@ -59,6 +101,15 @@ export function setLogLevel(level: LogLevel): void {
 	minLevel = level;
 }
 
+/**
+ * Programmatic override for the console mirror (issue #265). Mirrors
+ * setLogLevel: module-level state, so tests can toggle it without re-reading
+ * the environment.
+ */
+export function setConsoleOutput(enabled: boolean): void {
+	consoleOutput = enabled;
+}
+
 // Issue #179 (D6): createLogger() runs at MODULE LOAD (index.ts,
 // session-manager.ts) where the session cwd does not exist yet. The cwd is set
 // later from the session_start hook (ctx.cwd). All logger instances share this
@@ -101,9 +152,12 @@ export function createLogger(prefix: string, cwd?: string): Logger {
 
 		const line = JSON.stringify(entry);
 
-		// Console output
-		const consoleMethod = level === "error" ? console.error : level === "warn" ? console.warn : console.log;
-		consoleMethod(`[${prefix}] ${level.toUpperCase()}: ${message}`);
+		// Console mirror — opt-in (issue #265). Off by default so a logger call
+		// can never corrupt the pi TUI renderer; BRL_LOG_CONSOLE opts back in.
+		if (consoleOutput) {
+			const consoleMethod = level === "error" ? console.error : level === "warn" ? console.warn : console.log;
+			consoleMethod(`[${prefix}] ${level.toUpperCase()}: ${message}`);
+		}
 
 		// File output — resolved on each call because the cwd may be set after
 		// createLogger ran (module load) but before the first entry.

package/src/messaging.ts

@@ -1,3 +1,4 @@
+// Purpose: Inter-subagent messaging: the Intercom channel and `[TO:id]` output parsing.
 /**
  * brl-subagent — Subagent-to-Subagent Messaging (E10)
  *

package/src/metrics.ts

@@ -1,3 +1,4 @@
+// Purpose: SLA metrics over run history: p50/p95/p99 latency, success and cost rates, degradation detection.
 /**
  * brl-subagent — SLA Metrics (E4)
  *

package/src/model-availability.ts

@@ -1,3 +1,4 @@
+// Purpose: Auth-aware model availability: distinguishes catalog presence from configured provider auth.
 /**
  * Auth-aware model availability check (issue #4).
  *

package/src/notify-completion.ts

@@ -1,3 +1,4 @@
+// Purpose: Builds and sends the completion-push wake message for terminal background runs.
 /**
  * brl-subagent — Completion-push wake (issue #147)
  *

package/src/params.ts

@@ -1,3 +1,4 @@
+// Purpose: Param resolution: per-call + preset merge, thinking caps, timeout normalization, tool and git/approval resolution, auto-routing.
 /**
  * brl-subagent — Parameter Resolution (issue #59)
  *

package/src/paths.ts

@@ -1,3 +1,4 @@
+// Purpose: Package-root path resolution (`pkgPath()`) so shipped assets resolve from the extension directory.
 /**
  * brl-subagent — Package-root path resolution
  *

package/src/preflight.ts

@@ -1,3 +1,4 @@
+// Purpose: Pre-spawn environment checks: pi binary, temp-dir writability, cwd readability.
 /**
  * brl-subagent — Pre-flight Checks (R3)
  *
@@ -21,6 +22,33 @@ export type PreflightResult = { ok: true } | { ok: false; error: string };
 // Checks
 // ---------------------------------------------------------------------------
 
+/**
+ * Walk PATH for an executable `pi`, returning the first match.
+ *
+ * Mirrors the spawn-time fallback in `getPiInvocation` (the bare `"pi"`
+ * case). Shared with the Tier-2 e2e harness (issue #271) so the preflight
+ * check and the harness resolve the real binary identically.
+ */
+export function resolvePiOnPath(): string | undefined {
+	const pathDirs = (process.env.PATH || "").split(path.delimiter);
+	const isWindows = process.platform === "win32";
+	const piNames = isWindows ? ["pi.cmd", "pi.exe", "pi"] : ["pi"];
+
+	for (const dir of pathDirs) {
+		for (const name of piNames) {
+			const fullPath = path.join(dir, name);
+			try {
+				fs.accessSync(fullPath, fs.constants.X_OK);
+				return fullPath;
+			} catch {
+				// Not found in this directory — continue searching
+			}
+		}
+	}
+
+	return undefined;
+}
+
 /**
  * Verify the pi binary is accessible via the same resolution logic used
  * at spawn time. When `getPiInvocation` falls back to "pi" on PATH, we
@@ -44,20 +72,8 @@ function checkPiBinary(): PreflightResult {
 	}
 
 	// "pi" fallback — search PATH
-	const pathDirs = (process.env.PATH || "").split(path.delimiter);
-	const isWindows = process.platform === "win32";
-	const piNames = isWindows ? ["pi.cmd", "pi.exe", "pi"] : ["pi"];
-
-	for (const dir of pathDirs) {
-		for (const name of piNames) {
-			const fullPath = path.join(dir, name);
-			try {
-				fs.accessSync(fullPath, fs.constants.X_OK);
-				return { ok: true };
-			} catch {
-				// Not found in this directory — continue searching
-			}
-		}
+	if (resolvePiOnPath()) {
+		return { ok: true };
 	}
 
 	return {

package/src/prelude.ts

@@ -1,3 +1,4 @@
+// Purpose: Shared guard/validation prelude opening every delegation mode (cost gate, approval, H1 validation, dispatch guards).
 /**
  * Shared guard/validation prelude for delegation modes (issue #201).
  *

package/src/presets.ts

@@ -1,3 +1,4 @@
+// Purpose: Preset loading, parsing, validation, and the file-backed custom-preset tier.
 /**
  * brl-subagent — Presets
  *

package/src/proc.ts

@@ -0,0 +1,140 @@
+// Purpose: Production process primitives — Linux/POSIX /proc reads, feature detection, and the default recovery deps.
+/**
+ * Option B U1 — production process wiring for the recovery engine.
+ *
+ * The recovery decision engine (`src/recovery-engine.ts`) is pure over the
+ * injected `RecoveryDeps`. This module supplies the REAL deps: the Linux/POSIX
+ * `/proc` start-time token (`/proc/<pid>/stat` field 22), the child-marker scan
+ * (`/proc/<pid>/environ`), cross-platform pid liveness, and the default
+ * `RecoveryDeps` assembly.
+ *
+ * PLATFORM BOUNDARY (required): the start token and marker scan are Linux/POSIX
+ * reads. `isProcAvailable()` feature-detects them (cached; the answer cannot
+ * change mid-process). Where they are unavailable, `pidAlive` still works but
+ * on its own cannot rule out pid reuse — so the boot scan skips entirely and
+ * nothing is killed or marked unverified (`recoverProduction`, src/recovery.ts).
+ *
+ * `__setProcAvailableForTest` is the injectable seam that lets a test exercise
+ * that platform guard without mocking `node:fs` module-wide.
+ */
+
+import * as fs from "node:fs";
+import * as path from "node:path";
+import type { ProcessOwner } from "./types";
+import { SIGKILL_GRACE_MS } from "./types";
+import { CHILD_MARKER_ENV_KEY } from "./sanitize";
+import type { RecoveryDeps } from "./recovery-engine";
+
+const PROC_ROOT = "/proc";
+
+let procAvailable: boolean | undefined;
+let procAvailableOverride: boolean | undefined;
+
+/**
+ * TEST-ONLY: force the `/proc` feature-detection answer (undefined restores the
+ * real detection and clears the cache). The production scan consults this
+ * through `isProcAvailable`, so the platform guard is exercisable in-repo.
+ */
+export function __setProcAvailableForTest(value: boolean | undefined): void {
+	procAvailableOverride = value;
+	procAvailable = undefined;
+}
+
+/**
+ * Feature-detect the Linux/POSIX `/proc` surface this module needs. Cached:
+ * the answer cannot change mid-process. Exported so the entry point can skip
+ * the whole scan with one log line on platforms without /proc.
+ */
+export function isProcAvailable(): boolean {
+	if (procAvailableOverride !== undefined) return procAvailableOverride;
+	if (procAvailable === undefined) {
+		try {
+			procAvailable = fs.existsSync(path.join(PROC_ROOT, "self", "stat"));
+		} catch {
+			procAvailable = false;
+		}
+	}
+	return procAvailable;
+}
+
+/**
+ * Read a process's start-time token — `/proc/<pid>/stat` field 22 (1-indexed),
+ * i.e. index 19 of the whitespace-split fields AFTER the `(comm)` field. The
+ * comm field is skipped by slicing at the LAST `)` so a name containing spaces
+ * or parens cannot shift the parse. Returns undefined when /proc is
+ * unavailable, the pid is invalid, or the process vanished.
+ */
+export function readStartToken(pid: number): string | undefined {
+	if (!isProcAvailable() || !Number.isInteger(pid) || pid <= 0) return undefined;
+	try {
+		const stat = fs.readFileSync(path.join(PROC_ROOT, String(pid), "stat"), "utf-8");
+		const close = stat.lastIndexOf(")");
+		if (close < 0) return undefined;
+		const rest = stat.slice(close + 1).trim();
+		if (!rest) return undefined;
+		const fields = rest.split(/\s+/);
+		const token = fields[19];
+		return token && /^\d+$/.test(token) ? token : undefined;
+	} catch {
+		return undefined;
+	}
+}
+
+/** The CURRENT process's owner identity (pid + start token; empty string when unavailable). */
+export function currentProcessOwner(): ProcessOwner {
+	return { pid: process.pid, start: readStartToken(process.pid) ?? "" };
+}
+
+/** Cross-platform pid liveness (`kill -0`). EPERM means the process exists. */
+export function pidAlive(pid: number): boolean {
+	if (!Number.isInteger(pid) || pid <= 0) return false;
+	try {
+		process.kill(pid, 0);
+		return true;
+	} catch (err) {
+		return (err as NodeJS.ErrnoException).code === "EPERM";
+	}
+}
+
+/**
+ * Pids whose environment carries the marker. Scans `/proc/<pid>/environ` (NUL
+ * separated). Skips this process; unreadable/vanished processes are ignored.
+ * Returns [] — never a kill — when /proc is unavailable.
+ */
+export function findByMarker(marker: string): number[] {
+	if (!marker || !isProcAvailable()) return [];
+	const needle = `${CHILD_MARKER_ENV_KEY}=${marker}`;
+	const found: number[] = [];
+	let entries: string[];
+	try {
+		entries = fs.readdirSync(PROC_ROOT);
+	} catch {
+		return [];
+	}
+	for (const entry of entries) {
+		if (!/^\d+$/.test(entry)) continue;
+		const pid = Number(entry);
+		if (pid === process.pid) continue;
+		try {
+			const environ = fs.readFileSync(path.join(PROC_ROOT, entry, "environ"), "utf-8");
+			if (environ.split("\0").includes(needle)) found.push(pid);
+		} catch {
+			// Vanished or not readable by this user — not a verified match.
+		}
+	}
+	return found;
+}
+
+/** The real production dependencies (Linux/POSIX /proc reads + process signals). */
+export function defaultRecoveryDeps(): RecoveryDeps {
+	return {
+		pidAlive,
+		startTokenOf: readStartToken,
+		findByMarker,
+		kill: (pid, signal) => {
+			process.kill(pid, signal);
+		},
+		sleep: (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
+		graceMs: SIGKILL_GRACE_MS,
+	};
+}

package/src/prompt.ts

@@ -1,3 +1,4 @@
+// Purpose: Builds the subagent system prompt, including the task fence and inherited-instruction handling.
 /**
  * brl-subagent — Prompt Builder
  *