brl-subagent 2.3.4

package/src/unit-run.ts

@@ -0,0 +1,269 @@
+/**
+ * Per-unit run-entry helpers extracted from src/index.ts (issue #132).
+ *
+ * Chain, parallel and graph modes each build a per-unit SubagentRun entry,
+ * wrap onUpdate for live-monitor progress, and finalize the entry on the
+ * success path. Those blocks were duplicated 4x/3x/3x; these helpers make the
+ * behavior single-source. This is a behavior-identical refactor (the one
+ * intentional delta: the mode-specific finalize debug line is replaced by a
+ * single generic log inside finalizeUnitRun).
+ *
+ * The crash paths (buildCrashResult + finalizeLiveSubagent + finalizeRunRecord
+ * + classify + persistRun + rethrow) are extracted as finalizeUnitRunCrash;
+ * the per-unit live registration and the history prune are extracted as
+ * registerLiveRun and pruneHistoryIfNeeded. Single mode's record creation
+ * block and the background/retry registration paths remain in index.ts.
+ */
+
+import type {
+	AgentToolResult,
+	AgentToolUpdateCallback,
+} from "@earendil-works/pi-agent-core";
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+
+import type {
+	SubagentResult,
+	SubagentRun,
+	SubagentToolOptions,
+	Priority,
+} from "./types";
+import { getFinalOutput, classifyError } from "./types";
+import { snapshotOriginalParams } from "./params";
+import { capOutput, stripAnsi, buildCrashResult } from "./sanitize";
+import { finalizeRunRecord, pruneSessionRuns } from "./history";
+import type { Logger } from "./logging";
+import { SessionState } from "./state";
+
+// ---------------------------------------------------------------------------
+// Structural source for a per-unit run entry
+// ---------------------------------------------------------------------------
+
+/**
+ * The per-unit fields shared by chain/parallel/graph modes (`merged` from
+ * mergeSubTaskParams). Kept structural so the call sites verify by shape —
+ * mergeSubTaskParams itself is not imported (it lives in index.ts).
+ */
+export interface UnitRunSource {
+	task: string;
+	label?: string;
+	customSP?: string;
+	inheritSP: boolean;
+	model?: string;
+	thinkingLevel: string;
+	priority?: Priority;
+	outputFile?: string;
+	timeout?: number;
+	effectiveCwd: string;
+	toolOptions?: SubagentToolOptions;
+}
+
+// ---------------------------------------------------------------------------
+// makeLiveOnUpdate
+// ---------------------------------------------------------------------------
+
+/**
+ * Wrap a foreground `onUpdate` callback so partial results also stream into
+ * the live monitor for this run's `runId`. Returns undefined when `onUpdate`
+ * is undefined (the callers then pass the unwrapped value through).
+ */
+export function makeLiveOnUpdate(
+	state: SessionState,
+	runId: string,
+	onUpdate?: AgentToolUpdateCallback<SubagentResult>,
+): AgentToolUpdateCallback<SubagentResult> | undefined {
+	return onUpdate
+		? (partial: AgentToolResult<SubagentResult>) => {
+				onUpdate(partial);
+				if (partial.details) {
+					state.updateLiveSubagent(
+						runId,
+						getFinalOutput(partial.details.messages),
+						partial.details.usage.input,
+						partial.details.usage.output,
+						partial.details.liveTranscript,
+					);
+				}
+			}
+		: undefined;
+}
+
+// ---------------------------------------------------------------------------
+// createUnitRun
+// ---------------------------------------------------------------------------
+
+/**
+ * Create the per-unit SubagentRun entry for a chain/parallel/graph unit and
+ * return it with a fresh runId (the runId doubles as the live id, so
+ * sweepStaleLiveSubagents finds a 'running' record for every foreground live
+ * entry). `priorityFloor` is the call-level floor for this mode; `source.priority`
+ * wins when present. `presetName` feeds snapshotOriginalParams (issue #114
+ * retry-snapshot visibility).
+ */
+export function createUnitRun(
+	source: UnitRunSource,
+	stepModel: { provider: string; id: string },
+	priorityFloor: Priority,
+	presetName?: string,
+): { runId: string; run: SubagentRun } {
+	const runId = crypto.randomUUID();
+	const run: SubagentRun = {
+		id: runId,
+		task: source.task,
+		label: source.label,
+		// Issue #98 symmetry: the background entry carries the caller
+		// label as `description` — kept separate from `label`.
+		description: source.label,
+		status: "running",
+		model: `${stepModel.provider}/${stepModel.id}`,
+		thinkingLevel: source.thinkingLevel,
+		// Issue #114: per-unit priority wins; the call-level floor is the
+		// fallback when the unit declares none. Issue #119 R3: snapshot the
+		// RESOLVED priority so a retry of a fallback-priority unit restores the
+		// same priority the run entry itself carried.
+		priority: source.priority ?? priorityFloor,
+		startedAt: new Date().toISOString(),
+		originalParams: snapshotOriginalParams({
+			systemPrompt: source.customSP,
+			inheritSystemPrompt: source.inheritSP,
+			model: source.model,
+			thinkingLevel: source.thinkingLevel,
+			priority: source.priority ?? priorityFloor,
+			outputFile: source.outputFile,
+			timeout: source.timeout,
+			cwd: source.effectiveCwd,
+			tools: source.toolOptions?.tools,
+			excludeTools: source.toolOptions?.excludeTools,
+			noBuiltinTools: source.toolOptions?.noBuiltinTools,
+			preset: presetName,
+		}),
+	};
+	return { runId, run };
+}
+
+// ---------------------------------------------------------------------------
+// finalizeUnitRun
+// ---------------------------------------------------------------------------
+
+/**
+ * Finalize a per-unit run entry on the success path: status/duration/cost/
+ * tokens/sanitized output land on the entry, the errorCategory is classified
+ * onto originalParams, the entry is persisted, run history is pruned past
+ * maxHistoryEntries, and the live entry is released. `runId` is `run.id` (the
+ * run entry carries the same id used as the live id).
+ */
+export function finalizeUnitRun(
+	state: SessionState,
+	pi: ExtensionAPI,
+	ctx: ExtensionContext,
+	run: SubagentRun,
+	result: SubagentResult,
+	log: Logger,
+): void {
+	const finalOutput = capOutput(stripAnsi(getFinalOutput(result.messages)));
+	finalizeRunRecord(run, result, finalOutput, new Date(run.startedAt).getTime());
+	run.originalParams = { ...run.originalParams, errorCategory: result.errorCategory };
+	state.persistRun(pi, run);
+	pruneHistoryIfNeeded(state, ctx, log);
+	state.finalizeLiveSubagent(run.id);
+	log.debug("Unit run finalized", { runId: run.id, status: run.status });
+}
+
+// ---------------------------------------------------------------------------
+// finalizeUnitRunCrash
+// ---------------------------------------------------------------------------
+
+/**
+ * Finalize a per-unit run entry on the crash path and rethrow the original
+ * error (returns `never`). Single-source for the near-identical crash blocks
+ * that chain/parallel/graph modes each duplicated: build the crash result,
+ * release the live entry, land the failure + classified errorCategory on the
+ * record, persist it, log the mode-specific failure, and rethrow so the
+ * caller's outer catch/`finally` semantics are preserved.
+ *
+ * `modeLabel` is the human label ("Chain step", "Parallel subtask", "Graph
+ * node"); `logContext` carries the mode-specific context fields (chain passes
+ * the step index, parallel passes the task index, graph passes the node id)
+ * spread into the log call alongside runId/error.
+ */
+export function finalizeUnitRunCrash(
+	state: SessionState,
+	pi: ExtensionAPI,
+	run: SubagentRun,
+	err: unknown,
+	modeLabel: string,
+	resolvedCwd: string,
+	log: Logger,
+	logContext?: Record<string, unknown>,
+): never {
+	const crash = buildCrashResult(modeLabel, err, resolvedCwd);
+	state.finalizeLiveSubagent(run.id);
+	const crashOutput = state.subagentSessions.get(run.id)?.liveOutput ?? "";
+	finalizeRunRecord(run, crash.details, crashOutput, new Date(run.startedAt).getTime());
+	// buildCrashResult.details carries no errorCategory — classify it
+	// so the entry follows the completion path's errorCategory
+	// convention (issue #114 retry-snapshot visibility).
+	run.originalParams = {
+		...run.originalParams,
+		errorCategory: classifyError(crash.details),
+	};
+	state.persistRun(pi, run);
+	log.error(`${modeLabel} crashed`, {
+		...logContext,
+		runId: run.id,
+		error: crash.details.errorMessage,
+	});
+	throw err;
+}
+
+// ---------------------------------------------------------------------------
+// pruneHistoryIfNeeded
+// ---------------------------------------------------------------------------
+
+/**
+ * Prune persisted run history when `maxHistoryEntries` is configured, logging
+ * the count when any entries are removed. Single-source for the identical
+ * prune block that chain/parallel/graph/single modes each repeated.
+ */
+export function pruneHistoryIfNeeded(
+	state: SessionState,
+	ctx: ExtensionContext,
+	log: Logger,
+): void {
+	if (state.config.maxHistoryEntries > 0) {
+		const p = pruneSessionRuns(ctx, state.config.maxHistoryEntries);
+		if (p > 0) log.debug("Run history pruned", { pruned: p });
+	}
+}
+
+// ---------------------------------------------------------------------------
+// registerLiveRun
+// ---------------------------------------------------------------------------
+
+/**
+ * Register a per-unit run in the live monitor from its `SubagentRun` entry.
+ * label/task/model/thinkingLevel/priority and startedAt (converted to epoch ms
+ * for the LiveSubagent shape) all derive from the record, so the registration
+ * is single-source. `run.startedAt` is used as the live timestamp (more
+ * correct than `Date.now()` at registration; display-identical).
+ *
+ * `labelOverride` supplies the live entry's label when the caller wants one
+ * that differs from `run.label` (e.g. chain's unlabeled-step fallback).
+ * When omitted the live label defaults to `run.label`.
+ */
+export function registerLiveRun(
+	state: SessionState,
+	run: SubagentRun,
+	ctx: ExtensionContext,
+	labelOverride?: string,
+): void {
+	state.registerLiveSubagent(run.id, {
+		id: run.id,
+		label: labelOverride ?? run.label,
+		task: run.task,
+		model: run.model,
+		thinkingLevel: run.thinkingLevel,
+		priority: run.priority,
+		startedAt: new Date(run.startedAt).getTime(),
+		ctx,
+	});
+}

package/src/update.ts

@@ -0,0 +1,109 @@
+/**
+ * brl-subagent — Version Update Notifier
+ *
+ * Checks GitHub releases for newer versions of brl-subagent.
+ * Runs non-blocking with a 5-second timeout on session start.
+ */
+
+import type { Logger } from "./logging";
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export interface UpdateCheckResult {
+	available: boolean;
+	version?: string;
+	url?: string;
+}
+
+// ---------------------------------------------------------------------------
+// Semver comparison
+// ---------------------------------------------------------------------------
+
+/**
+ * Compare two semver strings (e.g., "2.1.0" vs "2.0.1").
+ * Returns 1 if a > b, -1 if a < b, 0 if equal.
+ */
+function compareSemver(a: string, b: string): number {
+	const aParts = a.split(".").map(Number);
+	const bParts = b.split(".").map(Number);
+	const len = Math.max(aParts.length, bParts.length);
+
+	for (let i = 0; i < len; i++) {
+		const aVal = aParts[i] ?? 0;
+		const bVal = bParts[i] ?? 0;
+		if (aVal > bVal) return 1;
+		if (aVal < bVal) return -1;
+	}
+	return 0;
+}
+
+// ---------------------------------------------------------------------------
+// Main export
+// ---------------------------------------------------------------------------
+
+/**
+ * Check GitHub for a newer release of brl-subagent.
+ *
+ * @param currentVersion - The current version string (e.g., "2.0.1")
+ * @param log - Optional logger for debug output
+ * @returns Update check result, or null on any error (never throws)
+ */
+export async function checkForUpdates(
+	currentVersion: string,
+	log?: Logger,
+): Promise<UpdateCheckResult | null> {
+	try {
+		const controller = new AbortController();
+		const timeoutId = setTimeout(() => controller.abort(), 5_000);
+
+		const response = await fetch(
+			"https://api.github.com/repos/azmeenafandi/brl-subagent/releases/latest",
+			{
+				headers: {
+					Accept: "application/vnd.github+json",
+					"User-Agent": "brl-subagent",
+				},
+				signal: controller.signal,
+			},
+		);
+
+		clearTimeout(timeoutId);
+
+		if (!response.ok) {
+			log?.debug("Update check: non-OK response", { status: response.status });
+			return null;
+		}
+
+		const data = (await response.json()) as {
+			tag_name?: string;
+			html_url?: string;
+		};
+
+		if (!data.tag_name || !data.html_url) {
+			log?.debug("Update check: missing tag_name or html_url in response");
+			return null;
+		}
+
+		// Strip "v" prefix from tag_name (e.g., "v2.1.0" → "2.1.0")
+		const latestVersion = data.tag_name.replace(/^v/, "");
+
+		const cmp = compareSemver(latestVersion, currentVersion);
+
+		if (cmp > 0) {
+			return {
+				available: true,
+				version: latestVersion,
+				url: data.html_url,
+			};
+		}
+
+		return { available: false };
+	} catch (err) {
+		log?.debug("Update check failed", {
+			error: err instanceof Error ? err.message : String(err),
+		});
+		return null;
+	}
+}

package/src/validate.ts

@@ -0,0 +1,302 @@
+/**
+ * H1: Pre-task validation
+ *
+ * Deterministic checks that validate a subagent's tool configuration
+ * and thinking level match the task description. Runs in code (not
+ * LLM context), so it's consistent regardless of conductor state.
+ */
+
+import type { ThinkingLevel, SubagentToolOptions } from './types';
+import { THINKING_LEVELS } from './types';
+
+// ── Types ────────────────────────────────────────────────────────────
+
+export interface ValidateConfig {
+  task: string;
+  toolOptions?: SubagentToolOptions;
+  thinkingLevel?: ThinkingLevel;
+  gitMode?: string;
+  outputFile?: string;
+}
+
+export interface ValidateResult {
+  valid: boolean;
+  warnings: string[];
+  errors: string[];
+}
+
+// ── Keyword patterns ─────────────────────────────────────────────────
+
+interface ToolRequirement {
+  patterns: RegExp[];
+  requiredTools: string[];
+  description: string;
+}
+
+const TOOL_REQUIREMENTS: ToolRequirement[] = [
+  {
+    patterns: [/\b(write|create|generate|build|implement|add|insert|append)\b/i],
+    requiredTools: ['write', 'edit'],
+    description: 'task involves writing/creating files',
+  },
+  {
+    patterns: [/\b(edit|modify|update|change|fix|patch|refactor|rename)\b/i],
+    requiredTools: ['write', 'edit'],
+    description: 'task involves editing files',
+  },
+  {
+    patterns: [/\b(run|execute|test|benchmark|compile|install|deploy|npm|yarn|pnpm|cargo|pip|vitest)\b/i],
+    requiredTools: ['bash'],
+    description: 'task involves running commands',
+  },
+  {
+    patterns: [/\b(delete|remove|clean|prune|uninstall|rm)\b/i],
+    requiredTools: ['write', 'bash'],
+    description: 'task involves deleting files',
+  },
+  {
+    patterns: [/\b(commit|push|pull|merge|rebase|checkout|branch)\b/i],
+    requiredTools: ['bash'],
+    description: 'task involves git operations',
+  },
+  {
+    patterns: [/\b(audit|review|analyze|examine|check|inspect|scan|read)\b/i],
+    requiredTools: ['read'],
+    description: 'task involves reading/analyzing files',
+  },
+];
+
+interface ThinkingRequirement {
+  patterns: RegExp[];
+  minLevel: ThinkingLevel;
+  description: string;
+}
+
+const THINKING_REQUIREMENTS: ThinkingRequirement[] = [
+  {
+    patterns: [/\b(security|vulnerability|exploit|injection|attack|penetration)\b/i],
+    minLevel: 'high',
+    description: 'security analysis',
+  },
+  {
+    patterns: [/\b(debug|diagnose|root.cause|race.condition|deadlock|memory.leak)\b/i],
+    minLevel: 'high',
+    description: 'complex debugging',
+  },
+  {
+    patterns: [/\b(architecture|design|refactor|migration|breaking.change)\b/i],
+    minLevel: 'medium',
+    description: 'architectural work',
+  },
+  {
+    patterns: [/\b(implement|develop|build|feature)\b/i],
+    minLevel: 'medium',
+    description: 'implementation work',
+  },
+];
+
+// ── Helpers ──────────────────────────────────────────────────────────
+
+function thinkingLevelIndex(level: ThinkingLevel): number {
+  return THINKING_LEVELS.indexOf(level);
+}
+
+function isToolAvailable(
+  toolName: string,
+  toolOptions?: SubagentToolOptions,
+): boolean {
+  // noBuiltinTools disables ALL built-in tools (read, bash, edit, write, ...)
+  // while keeping extension/custom tools — so no built-in is available.
+  if (toolOptions?.noBuiltinTools && isBuiltinTool(toolName)) return false;
+  if (toolOptions?.excludeTools?.includes(toolName)) return false;
+  if (toolOptions?.tools && !toolOptions.tools.includes(toolName)) return false;
+  return true;
+}
+
+// Built-in tool names pi ships (runner.ts maps noBuiltinTools → --no-builtin-tools).
+const BUILTIN_TOOLS = new Set(['read', 'bash', 'edit', 'write', 'grep', 'find', 'ls']);
+
+function isBuiltinTool(toolName: string): boolean {
+  return BUILTIN_TOOLS.has(toolName);
+}
+
+// ── Post-mortem diagnostics (H3) ─────────────────────────────────────
+
+export interface DiagnoseConfig {
+	task: string;
+	toolOptions?: SubagentToolOptions;
+	thinkingLevel?: ThinkingLevel;
+	gitMode?: string;
+	errorMessage?: string;
+	exitCode?: number;
+	timeout?: number;
+}
+
+export function diagnoseFailure(config: DiagnoseConfig): string[] {
+	const suggestions: string[] = [];
+	const taskText = (config.task || '').toLowerCase();
+	const errMsg = (config.errorMessage || '').toLowerCase();
+
+	// Rule 1: Git mode mismatch — task needs git but gitMode is 'none'
+	const gitPatterns = /\b(commit|push|merge|branch)\b/i;
+	if (gitPatterns.test(taskText) && config.gitMode === 'none') {
+		suggestions.push(
+			"Set gitMode to 'branch' or 'auto' to enable git operations",
+		);
+	}
+
+	// Rule 2: Thinking level too low for security
+	const securityPatterns = /\b(security|vulnerability|audit)\b/i;
+	if (
+		securityPatterns.test(taskText) &&
+		(config.thinkingLevel === 'off' || config.thinkingLevel === 'low')
+	) {
+		suggestions.push(
+			"Set thinkingLevel to 'high' or 'xhigh' for security analysis",
+		);
+	}
+
+	// Rule 3: Thinking level too low for debugging
+	const debugPatterns = /\b(debug|diagnose|root.cause)\b/i;
+	if (
+		debugPatterns.test(taskText) &&
+		(config.thinkingLevel === 'off' || config.thinkingLevel === 'low')
+	) {
+		suggestions.push(
+			"Set thinkingLevel to 'high' for complex debugging",
+		);
+	}
+
+	// Rule 4: Write/edit tool excluded but task needs file creation/editing
+	const writePatterns = /\b(write|create|edit|implement)\b/i;
+	if (writePatterns.test(taskText)) {
+		const excluded = config.toolOptions?.excludeTools ?? [];
+		if (excluded.includes('write') || excluded.includes('edit')) {
+			suggestions.push(
+				"Remove 'write' and 'edit' from excludeTools",
+			);
+		}
+	}
+
+	// Rule 5: Bash tool excluded but task needs command execution
+	const runPatterns = /\b(run|execute|test|vitest)\b/i;
+	if (runPatterns.test(taskText)) {
+		const excluded = config.toolOptions?.excludeTools ?? [];
+		if (excluded.includes('bash')) {
+			suggestions.push(
+				"Remove 'bash' from excludeTools to enable command execution",
+			);
+		}
+	}
+
+	// Rule 6: Timeout with xhigh thinking
+	if (
+		errMsg.includes('timed out') &&
+		config.thinkingLevel === 'xhigh'
+	) {
+		suggestions.push(
+			"xhigh thinking is expensive — try 'high' or increase timeout",
+		);
+	}
+
+	// Rule 7: Very low timeout
+	if (errMsg.includes('timed out') && config.timeout !== undefined && config.timeout < 30000) {
+		suggestions.push(
+			"Timeout is very low — consider increasing timeout",
+		);
+	}
+
+	return suggestions;
+}
+
+// ── Main validation ──────────────────────────────────────────────────
+
+export function validatePreTask(config: ValidateConfig): ValidateResult {
+  const warnings: string[] = [];
+  const errors: string[] = [];
+  const taskText = config.task || '';
+
+  // Skip validation for empty tasks (chain/parallel/graph don't always have
+  // task). Exception: an outputFile is a HARD conflict check (block C below)
+  // that must run even with empty top-level task text — chain/parallel/graph
+  // validate the mode-level outputFile at mode entry (issue #34). Empty text
+  // matches no keyword patterns, so no warnings can false-fire from this path.
+  if (!taskText.trim() && !config.outputFile) {
+    return { valid: true, warnings: [], errors: [] };
+  }
+
+  // Check tool requirements (warnings, not errors — conductor can override)
+  for (const req of TOOL_REQUIREMENTS) {
+    const matches = req.patterns.some(p => p.test(taskText));
+    if (!matches) continue;
+
+    for (const tool of req.requiredTools) {
+      if (!isToolAvailable(tool, config.toolOptions)) {
+        warnings.push(
+          `Task ${req.description} but '${tool}' is not available (tools=${config.toolOptions?.tools?.join(',') ?? 'all'}, excludeTools=${config.toolOptions?.excludeTools?.join(',') ?? 'none'})`,
+        );
+      }
+    }
+  }
+
+  // Check git mode
+  const gitPatterns = [/\b(commit|push|pull|merge|rebase|checkout|branch|pr|pull.request)\b/i];
+  if (gitPatterns.some(p => p.test(taskText)) && config.gitMode === 'none') {
+    warnings.push(
+      `Task involves git operations but gitMode is 'none' — subagent cannot create commits or branches`,
+    );
+  }
+
+  // Check thinking level recommendations
+  for (const req of THINKING_REQUIREMENTS) {
+    const matches = req.patterns.some(p => p.test(taskText));
+    if (!matches) continue;
+
+    const taskLevel = config.thinkingLevel ? thinkingLevelIndex(config.thinkingLevel) : -1;
+    const minLevel = thinkingLevelIndex(req.minLevel);
+
+    if (taskLevel >= 0 && taskLevel < minLevel) {
+      warnings.push(
+        `Task involves ${req.description} but thinkingLevel is '${config.thinkingLevel}' — consider '${req.minLevel}' or higher`,
+      );
+    }
+  }
+
+  // C: outputFile requires the write tool — a hard conflict, not a warning.
+  // The extension instructs the subagent to write findings to outputFile,
+  // but a preset's excludeTools is a hard constraint nothing can override.
+  // Reject before any tokens are spent (loud failure).
+  if (config.outputFile && !isToolAvailable('write', config.toolOptions)) {
+    errors.push(
+      `outputFile is set but the 'write' tool is not available ` +
+      `(tools=${config.toolOptions?.tools?.join(',') ?? 'all'}, excludeTools=${config.toolOptions?.excludeTools?.join(',') ?? 'none'}). ` +
+      `The subagent cannot write the report. Remove outputFile or adjust the preset/tool restrictions.`
+    );
+  }
+
+  return {
+    valid: errors.length === 0, // Errors are hard conflicts; warnings are informational
+    warnings,
+    errors,
+  };
+}
+
+/**
+ * Normalize a user-supplied timeout to a safe deadline value, or undefined for
+ * "no timeout". Guards the setTimeout boundary — Node fires `setTimeout(fn, 0)`,
+ * negative, NaN, and >=2^31-1 delays immediately (~1ms), so an unvalidated
+ * timeout is an instant kill, not a generous deadline (issue #28, PR #49
+ * review M1/m1).
+ *
+ * Returns undefined for: undefined, 0, negative, NaN, Infinity, >=2^31-1.
+ * Returns the value unchanged otherwise (foreground permits >30min timeouts;
+ * the background hard cap applies its own 30min Math.min).
+ */
+export function normalizeTimeout(timeout: number | undefined): number | undefined {
+	if (timeout === undefined) return undefined;
+	if (!Number.isFinite(timeout)) return undefined;
+	if (timeout <= 0) return undefined;
+	// Node's setTimeout overflows to ~1ms at 2^31-1 (TimeoutOverflowWarning).
+	if (timeout >= 2 ** 31 - 1) return undefined;
+	return timeout;
+}

package/templates/analyze-data.md

@@ -0,0 +1,9 @@
+---
+name: analyze-data
+description: Data analysis with patterns and recommendations
+preset: data-analyst
+thinkingLevel: medium
+---
+Analyze ${dataset}. Find patterns, outliers, and trends.
+
+Summarize with concrete numbers and a recommendation.

package/templates/code-review.md

@@ -0,0 +1,10 @@
+---
+name: code-review
+description: Review code for correctness, security, and style
+preset: code-reviewer
+thinkingLevel: medium
+---
+Review ${target} for correctness, security, and style.
+
+Report findings as a numbered list with file:line references,
+prioritized blocker → nit. Read-only — no edits.