brl-subagent 2.3.8 → 2.4.0

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,27 @@ 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();
+
+/**
+ * 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";
+}
 
 // ---------------------------------------------------------------------------
 // Logger

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)
  *
@@ -23,7 +24,7 @@ import type {
 } from "./types";
 import { resolveThinkingLevel } from "./types";
 import { getAllPresets, getPreset } from "./presets";
-import { autoRoutePreset } from "./router";
+import { classifyTask } from "./router";
 import { normalizeTimeout } from "./validate";
 import type { SessionState } from "./state";
 import type { Logger } from "./logging";
@@ -49,7 +50,7 @@ export const KNOWN_DELEGATE_KEYS = new Set([
 	"outputFile", "label", "model", "timeout", "cwd", "tools",
 	"excludeTools", "noBuiltinTools", "preset", "template", "params",
 	"retryRunId", "gitMode", "retryOnTimeout", "approvalMode", "background",
-	"priority", "chain", "tasks", "graph",
+	"priority", "chain", "tasks", "graph", "force",
 ] as const);
 
 /**
@@ -76,6 +77,11 @@ export function findUnknownParams(
  * degrade retries of that path.
  * NOTE: the schema's `params` (template slots) key is intentionally NOT
  * snapshotted — it is a template-resolution input, not a retry override.
+ * The execution-shape keys (background, gitMode, approvalMode, force) ARE
+ * snapshotted: omitting them is the known failure mode of this design, since
+ * resolveRetryParams rebuilds a fresh literal and a key missing here is both
+ * unrestored AND discarded when passed explicitly on a retry call. Records
+ * written before this change simply lack the keys (additive, undefined-safe).
  */
 export function snapshotOriginalParams(params: {
 	systemPrompt?: string;
@@ -90,6 +96,10 @@ export function snapshotOriginalParams(params: {
 	excludeTools?: string[];
 	noBuiltinTools?: boolean;
 	preset?: string;
+	background?: boolean;
+	gitMode?: string;
+	approvalMode?: string;
+	force?: boolean;
 }): Record<string, unknown> {
 	return {
 		systemPrompt: params.systemPrompt,
@@ -104,6 +114,10 @@ export function snapshotOriginalParams(params: {
 		excludeTools: params.excludeTools,
 		noBuiltinTools: params.noBuiltinTools,
 		preset: params.preset,
+		background: params.background,
+		gitMode: params.gitMode,
+		approvalMode: params.approvalMode,
+		force: params.force,
 	};
 }
 
@@ -124,6 +138,12 @@ export function resolveSubagentParams(
 		gitMode?: string;
 		approvalMode?: string;
 		template?: string;
+		/**
+		 * Capability-block override: carried here so the validation call sites
+		 * (which receive the resolved params) can forward it to validatePreTask.
+		 * Resolution itself ignores it.
+		 */
+		force?: boolean;
 	},
 	state: SessionState,
 	ctx: ExtensionContext,
@@ -133,6 +153,9 @@ export function resolveSubagentParams(
 	resolvedApprovalMode: ApprovalMode;
 	resolvedPreset?: SubagentPreset;
 	autoRoutedPreset?: SubagentPreset; // set only when autoRoutePreset chose it
+	/** Set only when auto-route chose the preset: the keyword that matched —
+	 * the evidence the dispatch result surfaces (auto-route transparency). */
+	autoRouteKeyword?: string;
 } {
 	// E2: Auto-route to best preset only when the conductor expressed NO
 	// explicit preference — an explicit preset, template, or tool
@@ -140,17 +163,19 @@ export function resolveSubagentParams(
 	// that must win over keyword-based routing (issue #57).
 	let resolvedPreset = params.preset;
 	let wasAutoRouted = false;
+	let routeKeyword: string | undefined;
 	const hasExplicitToolPreference =
 		params.tools !== undefined ||
 		params.excludeTools !== undefined ||
 		params.noBuiltinTools !== undefined;
 	if (!resolvedPreset && !params.template && !hasExplicitToolPreference) {
 		const allPresets = getAllPresets(state.builtinPresets, state.customPresets);
-		const suggested = autoRoutePreset(params.task, allPresets);
-		if (suggested) {
-			resolvedPreset = suggested;
+		const matched = classifyTask(params.task, allPresets);
+		if (matched) {
+			resolvedPreset = matched.preset;
 			wasAutoRouted = true;
-			log.info("Auto-routed task to preset", { preset: suggested });
+			routeKeyword = matched.keyword;
+			log.info("Auto-routed task to preset", { preset: matched.preset, keyword: matched.keyword });
 		}
 	}
 
@@ -221,5 +246,6 @@ export function resolveSubagentParams(
 		resolvedApprovalMode,
 		resolvedPreset: preset,
 		autoRoutedPreset,
+		autoRouteKeyword: autoRoutedPreset ? routeKeyword : undefined,
 	};
 }

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)
  *

package/src/prelude.ts

@@ -0,0 +1,207 @@
+// 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).
+ *
+ * delegate_task's mode handlers each open with the same prelude shape:
+ *
+ *   1. session cost gate — perTaskEstimate fallback ($0.05) →
+ *      checkCostLimit → the verbatim "Cannot delegate: session cost limit
+ *      reached …" rejection;
+ *   2. approvalMode 'always' rejection (background paths only) — the verbatim
+ *      "Cannot spawn background agent with approvalMode 'always' …";
+ *   3. cwd → outputFile → H1 pre-task validation — the same "Invalid cwd:" /
+ *      "Invalid outputFile:" / joined-errors messages, optionally
+ *      unit-prefixed (`Task 2 ("two"): …`) for per-unit loops.
+ *
+ * Each helper returns the rejection ToolResult when the gate trips and
+ * `undefined` when it passes, so call sites keep their original gate order:
+ *
+ *     const err = gateSessionCost({ … });
+ *     if (err) return err;
+ *
+ * Exception: runPreTaskValidation returns a { error?, warnings } outcome —
+ * `error` follows the same `if (outcome.error) return outcome.error` shape,
+ * and `warnings` must be surfaced in the returned tool result:
+ *
+ *     const pre = runPreTaskValidation({ … });
+ *     if (pre.error) return pre.error;
+ *
+ * Messages are byte-identical to the pre-extraction copies (the suites pin
+ * them); the parameters absorb only the real differences between sites — the
+ * cost-gate log label and unit count, and the H1 log label / unit prefix /
+ * extra log fields.
+ */
+
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type { ApprovalMode, ToolResult } from "./types";
+import type { SessionState } from "./state";
+import type { Logger } from "./logging";
+import { validateCwd, validateOutputFile } from "./sanitize";
+import { validatePreTask, type ValidateConfig } from "./validate";
+
+/** The standard rejection result shape shared by these gates. */
+function rejection(text: string): ToolResult<undefined> {
+	return {
+		content: [{ type: "text" as const, text }],
+		details: undefined,
+		isError: true,
+	};
+}
+
+// ── Gate 1: session cost ────────────────────────────────────────────────
+
+/**
+ * Session cost gate (R5 / W6): falls back to the $0.05 per-unit estimate,
+ * checks the whole dispatch (units × estimate) against the session limit, and
+ * returns the verbatim rejection result when it would be exceeded.
+ *
+ * This module holds the codebase's SINGLE `checkCostLimit(perTaskEstimate * …)`
+ * site — the duplication that shape caused a mutation-target-drift incident
+ * (issue #201).
+ */
+export function gateSessionCost(input: {
+	state: SessionState;
+	ctx: ExtensionContext;
+	log: Logger;
+	/** Number of units this dispatch would spawn (1 for single-task modes). */
+	units: number;
+	/** e.g. "Parallel delegation" → log line "Parallel delegation rejected: session cost limit reached". */
+	label: string;
+}): ToolResult<undefined> | undefined {
+	const { state, ctx, log, units, label } = input;
+	const perTaskEstimate =
+		state.config.perTaskCostEstimate > 0
+			? state.config.perTaskCostEstimate
+			: 0.05;
+	if (state.checkCostLimit(perTaskEstimate * units, ctx)) {
+		const currentTotal = state.getSessionTotalCost(ctx);
+		const limit = state.config.sessionCostLimit;
+		log.warn(`${label}: session cost limit reached`, {
+			currentTotal,
+			estimatedCost: perTaskEstimate * units,
+			limit,
+		});
+		return rejection(
+			`Cannot delegate: session cost limit reached ` +
+			`($${currentTotal.toFixed(4)} spent of $${limit.toFixed(2)} limit). ` +
+			`Increase the limit via /brl-subagent costlimit or set to 0 for unlimited.`,
+		);
+	}
+	return undefined;
+}
+
+// ── Gate 2: approvalMode 'always' in background ─────────────────────────
+
+/**
+ * Background paths (single spawn and fan-out) reject approvalMode 'always'
+ * before spawning: there is no interactive dialog to approve the diff, so
+ * 'always' cannot work — reject loudly instead of running unattended with
+ * write access (W5, issue #28). Verbatim message, pinned by the suites.
+ */
+export function rejectApprovalAlwaysInBackground(
+	approvalMode: ApprovalMode,
+): ToolResult<undefined> | undefined {
+	if (approvalMode !== "always") return undefined;
+	return rejection(
+		`Cannot spawn background agent with approvalMode 'always': background agents run unattended ` +
+		`and cannot present the approval dialog. Use approvalMode 'auto' (default) or 'writes'.`,
+	);
+}
+
+// ── Gate 3a: cwd (+ outputFile) target validation ───────────────────────
+
+export type DelegationTargetsResult =
+	| { ok: true; cwd: string; outputFile: string | undefined }
+	| { ok: false; error: ToolResult<undefined> };
+
+/**
+ * Validate the dispatch's target cwd, then — when `outputFile` is given — the
+ * outputFile path (F1), returning both resolved values on success. `prefix`
+ * (a per-unit label like `Task 2 ("two")`) is prepended as `${prefix}: ` to
+ * the rejection messages; omit it for the unprefixed single-unit messages.
+ *
+ * Note: the foreground parallel mode historically validates only the cwd
+ * here (no outputFile step) — it simply passes no outputFile.
+ */
+export function validateDelegationTargets(input: {
+	ctx: ExtensionContext;
+	effectiveCwd: string;
+	/** Raw outputFile to path-validate; the step is skipped when omitted. */
+	outputFile?: string;
+	/** Unit prefix for the rejection messages, e.g. `Task 2 ("two")`. */
+	prefix?: string;
+}): DelegationTargetsResult {
+	const prefix = input.prefix ? `${input.prefix}: ` : "";
+
+	const cwdResult = validateCwd(input.effectiveCwd, input.ctx.cwd);
+	if (!cwdResult.ok) {
+		return { ok: false, error: rejection(`${prefix}Invalid cwd: ${cwdResult.error}`) };
+	}
+
+	let outputFile: string | undefined;
+	if (input.outputFile) {
+		const ofResult = validateOutputFile(input.outputFile, cwdResult.value);
+		if (!ofResult.ok) {
+			return { ok: false, error: rejection(`${prefix}Invalid outputFile: ${ofResult.error}`) };
+		}
+		outputFile = ofResult.value;
+	}
+
+	return { ok: true, cwd: cwdResult.value, outputFile };
+}
+
+// ── Gate 3b: H1 pre-task validation ─────────────────────────────────────
+
+/** Outcome of one pre-task validation: the rejection (hard failure) and/or
+ * the warnings the caller must surface in the tool result. */
+export interface PreTaskValidationOutcome {
+	/** Rejection result when validation failed (hard errors); undefined when it passed. */
+	error?: ToolResult<undefined>;
+	/** Validation warnings — surfaced in the returned tool result, not just logged. */
+	warnings: string[];
+}
+
+/**
+ * Render validation warnings for a tool result: one labelled, bulleted
+ * block. Empty input renders the empty string so results stay
+ * byte-identical when there is nothing to say.
+ */
+export function formatValidationWarnings(warnings: string[]): string {
+	if (warnings.length === 0) return "";
+	return `\n\n[pre-task validation warnings]\n` + warnings.map((w) => `- ${w}`).join("\n");
+}
+
+/**
+ * Run validatePreTask (H1) with the site's exact input, warn on warnings,
+ * and return the rejection outcome (joined errors) on hard failure.
+ * `label` names the site in the warn logs ("Parallel pre-task validation
+ * warnings" / "Background fan-out …" / "Background …"); `prefix` is
+ * prepended as `${prefix}: ` to the hard-failure message; `logContext` adds
+ * site fields to both warn entries (the fan-out adds the task index).
+ * The returned warnings are for RESULT surfacing — the log.warn calls stay
+ * regardless (a warning must reach both the log and the conductor).
+ */
+export function runPreTaskValidation(input: {
+	log: Logger;
+	preTask: ValidateConfig;
+	label: string;
+	/** Unit prefix for the rejection message, e.g. `Task 2 ("two")`. */
+	prefix?: string;
+	/** Extra structured fields merged into the warn entries. */
+	logContext?: Record<string, unknown>;
+}): PreTaskValidationOutcome {
+	const { log, preTask, label, prefix, logContext } = input;
+	const validation = validatePreTask(preTask);
+	if (validation.warnings.length > 0) {
+		log.warn(`${label} pre-task validation warnings`, { ...logContext, warnings: validation.warnings });
+	}
+	if (!validation.valid) {
+		const errText = validation.errors.join("; ");
+		log.warn(`${label} pre-task validation failed`, { ...logContext, errors: validation.errors });
+		return {
+			error: rejection(prefix ? `${prefix}: ${errText}` : errText),
+			warnings: validation.warnings,
+		};
+	}
+	return { warnings: validation.warnings };
+}

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/prompt.ts

@@ -1,3 +1,4 @@
+// Purpose: Builds the subagent system prompt, including the task fence and inherited-instruction handling.
 /**
  * brl-subagent — Prompt Builder
  *
@@ -52,7 +53,7 @@ export const SUBAGENT_INSTRUCTIONS =
  * - runner.ts (foreground subprocess: `-p` argument)
  * - session-manager.ts (background session: `session.prompt`)
  *
- * Deliberately applied AFTER {previous}/{otherId} substitution so substituted
+ * Deliberately applied AFTER {previous}/{<nodeId>} substitution so substituted
  * output (which may itself contain untrusted text) lands inside the fence.
  *
  * FIDELITY TRADEOFF (accepted, documented per PR #46 review M2): embedded

package/src/reports.ts

@@ -1,3 +1,4 @@
+// Purpose: Compliance reporting: file-access records and secrets-exposure detection.
 /**
  * brl-subagent — Compliance Reports (E5)
  *
@@ -128,6 +129,11 @@ function extractFilesFromOutputSummary(outputSummary: string): string[] {
 
 /**
  * Check if a file path matches any sensitive file pattern.
+ *
+ * This is the PATH-based detector for the secrets exposure report: it answers
+ * "did this run touch a sensitive FILE?" rather than "did the output text
+ * happen to mention one?". It was previously unreachable dead code; keep it in
+ * sync with SENSITIVE_FILE_PATTERNS / FILE_SEVERITY_MAP above.
  */
 function isSensitiveFile(filePath: string): { match: boolean; pattern?: string; severity?: "high" | "medium" | "low" } {
 	const normalizedPath = filePath.toLowerCase();
@@ -221,20 +227,40 @@ export function buildFileAccessReport(runs: SubagentRun[]): FileAccessReport {
  */
 export function buildSecretsExposureReport(runs: SubagentRun[]): SecretsExposureReport {
 	const exposures: SecretsExposureEntry[] = [];
+	// Dedupe key set: one exposure per (file, runId) regardless of whether the
+	// finding came from the text scan or the path scan.
+	const seen = new Set<string>();
 
 	for (const run of runs) {
 		// Check task description for sensitive keywords
 		const taskCheck = hasSensitiveTaskKeywords(run.task);
 		if (taskCheck.match && taskCheck.keyword) {
-			exposures.push({
-				file: `task:${taskCheck.keyword}`,
-				runId: run.id,
-				runLabel: run.label,
-				severity: "medium",
-			});
+			const file = `task:${taskCheck.keyword}`;
+			const key = `${file}\x00${run.id}`;
+			if (!seen.has(key)) {
+				seen.add(key);
+				exposures.push({
+					file,
+					runId: run.id,
+					runLabel: run.label,
+					severity: "medium",
+				});
+			}
+		}
+
+		// Files this run touched (mirrors buildFileAccessReport). Computed BEFORE
+		// the text scan so a text hit that is only a FRAGMENT of a touched path
+		// (e.g. ".env" inside "config/prod/.env") is not double-reported — the
+		// path scan below reports the real, full path instead.
+		const touched: string[] = [];
+		if (run.fullOutput && run.fullOutput.includes("diff --git")) {
+			touched.push(...extractFilesFromGitDiff(run.fullOutput));
+		}
+		if (touched.length === 0 && run.outputSummary) {
+			touched.push(...extractFilesFromOutputSummary(run.outputSummary));
 		}
 
-		// Check output for sensitive file access
+		// Check output text for sensitive file mentions.
 		const outputToCheck = [
 			run.outputSummary,
 			run.fullOutput,
@@ -254,8 +280,18 @@ export function buildSecretsExposureReport(runs: SubagentRun[]): SecretsExposure
 						}
 					}
 
+					// Report the text that actually matched, not the regex
+					// literal — the `file` field is what a reader acts on.
+					const matched = outputToCheck.match(pattern)?.[0] ?? patternStr;
+					// Fragment of a touched file? The path scan below reports the full
+					// path — skip this fragment so one file yields ONE entry.
+					if (touched.some((p) => p.toLowerCase().includes(matched.toLowerCase()))) continue;
+					const dedupeKey = `${matched}\x00${run.id}`;
+					if (seen.has(dedupeKey)) continue;
+					seen.add(dedupeKey);
+
 					exposures.push({
-						file: patternStr,
+						file: matched,
 						runId: run.id,
 						runLabel: run.label,
 						severity,
@@ -263,6 +299,26 @@ export function buildSecretsExposureReport(runs: SubagentRun[]): SecretsExposure
 				}
 			}
 		}
+
+		// Path-based detection: flag the sensitive FILES this run actually
+		// touched — the full path, even when the output text never names it (and
+		// even when it names it in a different case: the path is normalized
+		// before matching).
+		for (const file of touched) {
+			const check = isSensitiveFile(file);
+			if (!check.match) continue;
+
+			const dedupeKey = `${file}\x00${run.id}`;
+			if (seen.has(dedupeKey)) continue;
+			seen.add(dedupeKey);
+
+			exposures.push({
+				file,
+				runId: run.id,
+				runLabel: run.label,
+				severity: check.severity ?? "high",
+			});
+		}
 	}
 
 	return { exposures };

package/src/router.ts

@@ -1,3 +1,4 @@
+// Purpose: Auto-route: keyword classification of a task description to the best preset.
 /**
  * brl-subagent — Skill-based Routing
  *
@@ -105,15 +106,25 @@ function escapeRegExp(s: string): string {
 // Router
 // ---------------------------------------------------------------------------
 
+/** One auto-route decision: the selected preset AND the keyword that
+ * matched — the evidence the dispatch result must show (transparency). */
+export interface AutoRouteDecision {
+	/** The preset name selected. */
+	preset: string;
+	/** The classification keyword whose match selected the preset. */
+	keyword: string;
+}
+
 /**
- * Auto-classify a task description to the best preset personality.
+ * Auto-classify a task description to the best preset personality, returning
+ * the preset AND the matched keyword (evidence for the dispatch result).
  * Uses case-insensitive keyword matching, checked in priority order.
- * Returns the first matching preset name, or undefined if no match.
+ * Returns the first match, or undefined if no rule matches.
  */
-export function autoRoutePreset(
+export function classifyTask(
 	task: string,
 	presets: SubagentPreset[],
-): string | undefined {
+): AutoRouteDecision | undefined {
 	if (!task || task.trim().length === 0) return undefined;
 
 	const lower = task.toLowerCase();
@@ -124,10 +135,21 @@ export function autoRoutePreset(
 
 		for (const keyword of rule.keywords) {
 			if (keywordMatches(lower, keyword)) {
-				return rule.preset;
+				return { preset: rule.preset, keyword };
 			}
 		}
 	}
 
 	return undefined;
 }
+
+/**
+ * Auto-classify a task description to the best preset personality.
+ * Thin wrapper over classifyTask — preset name only, no evidence.
+ */
+export function autoRoutePreset(
+	task: string,
+	presets: SubagentPreset[],
+): string | undefined {
+	return classifyTask(task, presets)?.preset;
+}

package/src/runner.ts

@@ -1,3 +1,4 @@
+// Purpose: Foreground execution: spawns the `pi` subprocess, parses its JSON-line stream, and folds usage.
 /**
  * brl-subagent — Process Runner
  *
@@ -245,7 +246,13 @@ function emitSubagentUpdate(
 				text: getFinalOutputFn(result.messages) || "(running...)",
 			},
 		],
-		details: { ...result },
+		// Issue #206: this is a STREAMING partial, not a verdict —
+		// isSubagentError is a settled-result predicate (a mid-run stopReason
+		// such as "toolUse" is not an error until the run actually ends), so
+		// stamping the unsettled sentinel (exitCode: -1) keeps the renderer on
+		// its running branch until the real result lands. The accumulator
+		// (`result` itself) is untouched — its exitCode stays the real code.
+		details: { ...result, exitCode: -1 },
 	});
 }
 

package/src/sanitize.ts

@@ -1,3 +1,4 @@
+// Purpose: Input validation, environment allowlisting, and output sanitization (task, cwd, outputFile, agent ids).
 /**
  * brl-subagent — Sanitization (F1, F2, F3)
  *

package/src/scheduler.ts

@@ -1,3 +1,4 @@
+// Purpose: Dependency-graph scheduler: cycle detection, topological waves, and graph validation.
 /**
  * brl-subagent — Dependency Graph Scheduler
  *