brl-subagent 2.3.9 → 2.4.0

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

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

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

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
  *

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
  *

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
  *

package/src/schema.ts

@@ -0,0 +1,254 @@
+// Purpose: The registered `delegate_task` parameter schema — the single source of truth for its types.
+/**
+ * delegate_task parameter schema — the SINGLE source of truth (issue #239).
+ * index.ts registers this object; DelegateTaskParams (types.ts) is
+ * Static<typeof delegateTaskParamsSchema>, so schema and types cannot drift.
+ */
+import { Type } from "typebox";
+import { MAX_CHAIN_STEPS, MAX_PARALLEL_TASKS, MAX_GRAPH_TASKS } from "./types";
+
+export const delegateTaskParamsSchema = Type.Object({
+			task: Type.Optional(Type.String({
+				description: "Detailed description of the task for the subagent to complete (required for single mode, optional for chain/tasks/graph)",
+			})),
+			systemPrompt: Type.Optional(
+				Type.String({
+					description:
+						"Custom system prompt or additional instructions for the subagent. " +
+						"When inheritSystemPrompt is true (default), this is appended after the inherited prompt. " +
+						"When inheritSystemPrompt is false, this replaces the inherited prompt entirely.",
+				}),
+			),
+			inheritSystemPrompt: Type.Optional(
+				Type.Boolean({
+					description:
+						"Whether to inherit the main agent's system prompt. " +
+						"Default: true. Set to false to use only your custom systemPrompt, " +
+						"or to avoid passing a large inherited prompt to the subagent.",
+				}),
+			),
+			thinkingLevel: Type.Optional(
+				Type.String({
+					description:
+						"Requested thinking level for this subagent call. " +
+						"One of: off, minimal, low, medium, high, xhigh. " +
+						"Capped at the user's configured maximum. If omitted, the user's configured level is used.",
+				}),
+			),
+			outputFile: Type.Optional(
+				Type.String({
+					description:
+						"Project-relative path where the subagent should write its full findings. " +
+						"When provided, the subagent is instructed to write complete output to this file " +
+						"and return only a structured summary.",
+				}),
+			),
+			label: Type.Optional(
+				Type.String({
+					description:
+						"Human-readable label for this subagent (e.g., 'security-audit', 'docs-review'). " +
+						"Appears in the status bar and tool call display. " +
+						"Omit to use the default anonymous counter.",
+				}),
+			),
+			model: Type.Optional(Type.String({ description: "Model override (provider/model-id). Defaults to the global subagent model." })),
+			timeout: Type.Optional(
+				Type.Number({
+					description:
+						"Maximum time in milliseconds the subagent is allowed to run. " +
+						"If exceeded, the subagent is killed and an error is returned. " +
+						"Background runs default to a 30-minute deadline when no timeout is given; an explicit timeout is honored as given (30 minutes is a default, not a ceiling). A raw value ≥ 2^31-1 normalizes to the default.",
+				}),
+			),
+			cwd: Type.Optional(
+				Type.String({
+					description:
+						"Working directory for the subagent. Must be an existing directory. " +
+						"Defaults to the conductor's current working directory.",
+				}),
+			),
+			tools: Type.Optional(
+				Type.Array(Type.String(), {
+					description:
+						"Explicit allowlist of tool names for the subagent. Maps to pi's --tools flag.",
+				}),
+			),
+			excludeTools: Type.Optional(
+				Type.Array(Type.String(), {
+					description:
+						"Tool names to disable for the subagent. Maps to pi's --exclude-tools flag.",
+				}),
+			),
+			noBuiltinTools: Type.Optional(
+				Type.Boolean({
+					description:
+						"Disable all built-in tools for the subagent. Maps to pi's --no-builtin-tools flag.",
+				}),
+			),
+			preset: Type.Optional(
+				Type.String({
+					description:
+						"Name of a saved delegation preset (created via /brl-subagent preset). " +
+						"Preset values are used as defaults; explicit parameters on this call override them.",
+				}),
+			),
+			template: Type.Optional(
+				Type.String({
+					description:
+						"Name of a saved task template. Use with params to fill template slots. " +
+						"Templates are file-backed: 9 builtin templates ship with the extension " +
+						"(browse via /brl-subagent templates); override or add via .md files in " +
+						"~/.pi/agent/brl-subagent/templates/ or .pi/brl-subagent/templates/ " +
+						"(project-local wins over user-global over builtin).",
+				}),
+			),
+			params: Type.Optional(
+				Type.Record(Type.String(), Type.String(), {
+					description:
+						"Parameter values for template ${param} slots. " +
+						"Keys are param names, values are the substitution text.",
+				}),
+			),
+			retryRunId: Type.Optional(
+				Type.String({
+					description:
+						"ID of a previously failed subagent run to retry. " +
+						"The retry rebuilds the parameter object from a fixed field set, falling back to the " +
+						"original run's recorded values, with explicit values on this call winning: task, label, " +
+						"model, preset, systemPrompt, inheritSystemPrompt, thinkingLevel, priority, outputFile, " +
+						"timeout, cwd, tools, excludeTools, noBuiltinTools, background, gitMode, approvalMode, force. " +
+						"The execution-shape fields ARE restored: a retried background run stays background (with its " +
+						"completion wake), and a retried branch-mode run keeps its work branch, its approvalMode " +
+						"gating and its force override. Qualify that by the effective gitMode - when neither the record " +
+						"nor this call carries one, the configured default applies, which may still be 'branch'. " +
+						"Not restored: chain/tasks/graph and params, so a retried multi-step run silently degrades to a " +
+						"single task - re-issue it fresh. retryOnTimeout is explicit-only: never restored, honoured when passed. " +
+						"template is asymmetric: the original's template is NOT restored, but a template passed on the " +
+						"retry call DOES take effect (it is resolved before the retry merge). " +
+						"Fan-out units (parallel/chain/graph origin) record no background, so retrying one is a single " +
+						"foreground run - pass background: true for a background retry. " +
+						"Only works with runs that ended in failure (exitCode != 0, timeout, error, or abort).",
+				}),
+			),
+			gitMode: Type.Optional(
+				Type.String({
+					description:
+						"Git integration mode for this subagent call. " +
+						"'branch' creates a work branch, captures the diff, and switches back. " +
+						"'none' (default) does nothing. Falls back to the configured default.",
+				}),
+			),
+			retryOnTimeout: Type.Optional(
+				Type.Boolean({
+					description:
+						"If true and a FOREGROUND subagent times out, automatically retry with the same parameters. " +
+						"Only retries once — the second timeout is treated as a final failure. " +
+						"Background runs are not auto-retried; re-dispatch with retryRunId.",
+				}),
+			),
+			approvalMode: Type.Optional(
+				Type.String({
+					description:
+						"Change approval mode: auto (never ask), writes (ask when files changed), " +
+						"always (ask every time). Default is user config (/brl-subagent approval).",
+				}),
+			),
+			force: Type.Optional(
+				Type.Boolean({
+					description:
+						"Override for capability pre-flight errors (default false). A dispatch is blocked when the task clearly needs a capability the resolved toolset lacks — " +
+						"a run/execute/test/compile/benchmark task with no bash, or an exploration task (search/grep/find/list/locate/glob) with none of find/ls/grep/bash. " +
+						"Set force: true to dispatch anyway: the mismatch is then delivered as a warning in the result instead of rejecting the call. " +
+						"Warnings are surfaced either way. force never suppresses outputFile-without-write conflicts.",
+				}),
+			),
+			background: Type.Optional(
+				Type.Boolean({
+					description:
+						"Run the subagent in the background without blocking the conductor. " +
+						"When true, the tool returns immediately with an agent ID. " +
+						"The conductor is woken with a completion message; use get_subagent_result for post-wake retrieval and stall checks. " +
+						"Supports a single task or the tasks array (a fan-out that starts one background agent per task; with tasks the call returns one ID per task and the conductor is woken once per agent as each finishes); combining background with chain or graph is rejected. " +
+						"Default: false (blocking mode).",
+				}),
+			),
+			priority: Type.Optional(
+				Type.Union([
+					Type.Literal("critical"),
+					Type.Literal("high"),
+					Type.Literal("normal"),
+					Type.Literal("low"),
+				], {
+					description: "Concurrency priority for this delegation: critical, high, normal, or low. Higher-priority delegations queue ahead. Defaults to normal.",
+				})
+			),
+			// Issue #114: NO per-step `priority` on chain[] — chain steps never
+			// compete for concurrency slots (the chain holds ONE slot for its whole
+			// duration); array order IS the priority.
+			chain: Type.Optional(Type.Array(Type.Object({
+				task: Type.String({ description: "Task description. Use {previous} to reference the previous step output." }),
+				label: Type.Optional(Type.String({})),
+				model: Type.Optional(Type.String({ description: "Model override for this step (provider/model-id). Defaults to the global subagent model." })),
+				thinkingLevel: Type.Optional(Type.String({})),
+				cwd: Type.Optional(Type.String({})),
+				timeout: Type.Optional(Type.Number({})),
+				outputFile: Type.Optional(Type.String({})),
+				tools: Type.Optional(Type.Array(Type.String({}))),
+				excludeTools: Type.Optional(Type.Array(Type.String({}))),
+				noBuiltinTools: Type.Optional(Type.Boolean({})),
+				systemPrompt: Type.Optional(Type.String({})),
+				inheritSystemPrompt: Type.Optional(Type.Boolean({})),
+			}), {
+				description: "Sequential chain of tasks. Each step receives the previous step output via {previous} placeholder in the task string. Chain stops at the first failure. Max " + MAX_CHAIN_STEPS + " steps."
+			})),
+			tasks: Type.Optional(Type.Array(Type.Object({
+				task: Type.String({ description: "Task description for this parallel subtask" }),
+				label: Type.Optional(Type.String({})),
+				model: Type.Optional(Type.String({ description: "Model override for this step (provider/model-id). Defaults to the global subagent model." })),
+				thinkingLevel: Type.Optional(Type.String({})),
+				priority: Type.Optional(
+					Type.Union([
+						Type.Literal("critical"),
+						Type.Literal("high"),
+						Type.Literal("normal"),
+						Type.Literal("low"),
+					], { description: "Concurrency priority for this subtask (overrides the call-level default)." })
+				),
+				cwd: Type.Optional(Type.String({})),
+				timeout: Type.Optional(Type.Number({})),
+				outputFile: Type.Optional(Type.String({})),
+				tools: Type.Optional(Type.Array(Type.String({}))),
+				excludeTools: Type.Optional(Type.Array(Type.String({}))),
+				noBuiltinTools: Type.Optional(Type.Boolean({})),
+				systemPrompt: Type.Optional(Type.String({})),
+				inheritSystemPrompt: Type.Optional(Type.Boolean({})),
+			}), {
+				description: "Parallel tasks to execute concurrently. All tasks run regardless of individual failures. Max " + MAX_PARALLEL_TASKS + " tasks."
+			})),
+			graph: Type.Optional(Type.Array(Type.Object({
+				id: Type.String({ description: "Unique identifier for this task node" }),
+				task: Type.String({ description: "Task description. Use {<nodeId>} to reference output from another task (the referenced node's own id, which must be a word-character id - letters, digits, underscore; ids like 'step-1' or 'node.a' are not matched and the braces are left as literal text)." }),
+				label: Type.Optional(Type.String({})),
+				model: Type.Optional(Type.String({ description: "Model override for this step (provider/model-id). Defaults to the global subagent model." })),
+				dependsOn: Type.Optional(Type.Array(Type.String({}), { description: "IDs of tasks that must complete before this one starts" })),
+				thinkingLevel: Type.Optional(Type.String({})),
+				priority: Type.Optional(
+					Type.Union([
+						Type.Literal("critical"),
+						Type.Literal("high"),
+						Type.Literal("normal"),
+						Type.Literal("low"),
+					], { description: "Concurrency priority for this subtask (overrides the call-level default)." })
+				),
+				cwd: Type.Optional(Type.String({})),
+				timeout: Type.Optional(Type.Number({})),
+				outputFile: Type.Optional(Type.String({})),
+				tools: Type.Optional(Type.Array(Type.String({}))),
+				excludeTools: Type.Optional(Type.Array(Type.String({}))),
+				noBuiltinTools: Type.Optional(Type.Boolean({})),
+				systemPrompt: Type.Optional(Type.String({})),
+				inheritSystemPrompt: Type.Optional(Type.Boolean({})),
+			}), {
+				description: "Declare tasks with dependencies. The scheduler parallelizes independent tasks and sequences dependent ones. Max " + MAX_GRAPH_TASKS + " tasks."
+			})),
+		});

package/src/session-manager.ts

@@ -1,8 +1,9 @@
+// Purpose: Background execution: SDK sessions (`createAgentSession`), agent records, timeouts, steering, and settle paths.
 import { randomUUID } from 'crypto';
 import { join } from 'path';
-import { mkdirSync, writeFileSync, readFileSync, existsSync, readdirSync } from 'fs';
+import { mkdirSync, writeFileSync, readFileSync, existsSync } from 'fs';
 import type { BackgroundAgent, AgentStatus, GitMode, SubagentResult, SubagentRun, ThinkingLevel, SubagentToolOptions, UsageStats, ErrorCategory } from './types';
-import { EMPTY_USAGE, CUSTOM_ENTRY_TYPES, classifyError, classifyTerminalOutcome, isSubagentError, isProviderError, coherentFailureReason, SUBAGENT_ABORTED_MESSAGE } from './types';
+import { EMPTY_USAGE, CUSTOM_ENTRY_TYPES, classifyError, classifyTerminalOutcome, isProviderError, coherentFailureReason, SUBAGENT_ABORTED_MESSAGE } from './types';
 import { accumulateUsage } from './runner';
 import * as eventBus from './event-bus';
 import * as transcript from './transcript';
@@ -11,6 +12,7 @@ import { assertSafeAgentId, sanitizeErrorMessage } from './sanitize';
 import { wrapTask } from './prompt';
 import { createLogger } from './logging';
 import { getCurrentBranch, createWorkBranch, captureDiff, switchToBranch, deleteBranch, hasUncommittedChanges, getRepoRoot, commitAll, captureWorkingDiff } from './git';
+import { normalizeTimeout, DEFAULT_BACKGROUND_DEADLINE_MS } from './validate';
 
 const log = createLogger('brl-subagent');
 import type { ExtensionAPI, ExtensionContext } from '@earendil-works/pi-coding-agent';
@@ -117,49 +119,6 @@ function loadAgent(id: string): BackgroundAgent | null {
   }
 }
 
-/**
- * Create a new background agent session
- * 
- * NOTE: In v2.0.3, this creates a record but does NOT actually spawn a pi session.
- * The actual session spawning will be implemented when pi's ExtensionAPI supports it.
- * For now, this is a placeholder that creates the agent record.
- */
-export function createSession(params: {
-  task: string;
-  type?: string;
-  description?: string;
-  model?: string;
-  thinkingLevel?: ThinkingLevel;
-  systemPrompt?: string;
-}): BackgroundAgent {
-  const id = generateUUID();
-  const agent: BackgroundAgent = {
-    id,
-    sessionId: `session-${id}`,
-    type: params.type || 'general-purpose',
-    description: params.description || params.task.slice(0, 50),
-    status: 'pending',
-    startedAt: Date.now(),
-    task: params.task,
-    model: params.model || 'unknown',
-    thinkingLevel: params.thinkingLevel || 'medium',
-  };
-  
-  agents.set(id, agent);
-  persistAgent(agent);
-
-  // Start transcript for this agent
-  transcript.startTranscript(agent.id, params.task);
-
-  eventBus.emit(eventBus.createEvent('subagent:created', agent.id, {
-    type: agent.type,
-    description: agent.description,
-    task: agent.task,
-  }));
-
-  return agent;
-}
-
 /**
  * Get agent record by ID
  */
@@ -177,23 +136,6 @@ export function getAgent(id: string): BackgroundAgent | null {
   return agents.get(id) || loadAgent(id);
 }
 
-/**
- * List all background agents
- */
-export function listAgents(): BackgroundAgent[] {
-  ensureStorageDir();
-  const files = readdirSync(STORAGE_DIR).filter(f => f.endsWith('.json'));
-  const result: BackgroundAgent[] = [];
-  
-  for (const file of files) {
-    const id = file.replace('.json', '');
-    const agent = agents.get(id) || loadAgent(id);
-    if (agent) result.push(agent);
-  }
-  
-  return result.sort((a, b) => b.startedAt - a.startedAt);
-}
-
 /**
  * Update agent status
  */
@@ -225,25 +167,6 @@ export function updateAgentStatus(id: string, status: AgentStatus, error?: strin
   return agent;
 }
 
-/**
- * Set agent result
- */
-export function setAgentResult(id: string, result: SubagentResult): BackgroundAgent | null {
-  const agent = getAgent(id);
-  if (!agent) return null;
-  
-  agent.result = result;
-  // Issue #179 (D1): honor the full terminal reason (stopReason error/aborted/
-  // length/incomplete), not exitCode alone — a mid-run provider death resolves
-  // with exitCode 0 and was previously recorded as 'completed'.
-  agent.status = isSubagentError(result) ? 'failed' : 'completed';
-  agent.completedAt = Date.now();
-  
-  agents.set(id, agent);
-  persistAgent(agent);
-  return agent;
-}
-
 /**
  * Issue #179 (D4): when a run ends in a failure, the prose extracted by
  * extractFinalOutput may come from an EARLIER turn — the failing turn carries
@@ -281,7 +204,7 @@ function defaultTerminalMessage(stopReason: string | undefined): string {
  * Extract the final assistant text from a session's messages.
  * Falls back to the LAST assistant message with non-empty text content — the
  * final message is often a tool-call-only turn (agent stopped mid-turn, failed,
- * or hit the hard cap), and that turn carries no text of its own.
+ * or hit the deadline), and that turn carries no text of its own.
  */
 export function extractFinalOutput(session: { messages: Array<{ role: string; content?: Array<{ type: string; text?: string }> | string | null }> }): string {
   const assistants = [...session.messages].reverse().filter(m => m.role === 'assistant');
@@ -351,24 +274,45 @@ export async function stopAgent(id: string): Promise<BackgroundAgent | null> {
 }
 
 /**
- * Steer a running agent by injecting a message
- * 
- * NOTE: In v2.0.3, this is a placeholder.
- * Actual message injection will be implemented when pi's ExtensionAPI supports it.
+ * Steer a running agent by injecting a message into its live session.
+ *
+ * Issue #241: steering DELIVERS via the SDK's `AgentSession.steer()` — the
+ * message is queued while the agent is running and delivered after the current
+ * assistant turn finishes its tool calls, before the next model call.
+ *
+ * Steering is NOT a state transition: the agent stays 'running' (no status
+ * flip, no persistAgent) so REPEAT steers keep working. Delivery failures
+ * propagate to the caller — a false success would tell the conductor a steer
+ * landed when the agent never saw it. The transcript line is an audit record
+ * written AFTER successful delivery, best-effort: a landed steer must never be
+ * reported as failed because the audit write failed.
  */
-export function steerAgent(id: string, message: string): BackgroundAgent | null {
+export async function steerAgent(id: string, message: string): Promise<BackgroundAgent | null> {
   const agent = getAgent(id);
   if (!agent) return null;
   if (agent.status !== 'running') {
     throw new Error(`Cannot steer agent ${id}: status is ${agent.status}, not running`);
   }
 
-  // Record steering in transcript
-  transcript.appendEntry(id, 'user', `Steering: ${message}`);
+  const session = agent._sessionRef;
+  if (!session) {
+    throw new Error(`Cannot steer agent ${id}: no live session (the run may be settling)`);
+  }
+  if (typeof session.steer !== 'function') {
+    throw new Error('installed pi SDK has no AgentSession.steer — steering unsupported');
+  }
+
+  // Deliver FIRST — a rejection here must surface as a real tool error, never
+  // a recorded-but-undelivered steer.
+  await session.steer(message);
 
-  agent.status = 'steered';
-  agents.set(id, agent);
-  persistAgent(agent);
+  // Audit line — best-effort. The steer already landed; an append failure is
+  // logged, not propagated.
+  try {
+    transcript.appendEntry(id, 'user', `Steering: ${message}`);
+  } catch (err) {
+    log.warn(`steerAgent: transcript append failed for ${id}`, { error: (err as Error).message });
+  }
 
   eventBus.emit(eventBus.createEvent('subagent:steered', agent.id, { message }));
 
@@ -944,9 +888,13 @@ export async function spawnBackgroundSession(
   // Armed immediately after the prompt call so in-prompt preflight (auth
   // check, model resolution) counts toward the deadline; the abort lands in
   // the .then below as an aborted run (probe contract). We pre-set the status
-  // so the .then keeps 'stopped' with the timeout reason recorded. The value
-  // is normalized upstream (normalizeTimeout) but clamp again here — a raw
-  // >=2^31 or Infinity would make Node fire the timer at ~1ms (instant kill).
+  // so the .then keeps 'stopped' with the timeout reason recorded. The raw
+  // value is normalized here (issue #240): a raw >=2^31 or Infinity would make
+  // Node fire the timer at ~1ms (instant kill), so normalizeTimeout maps it to
+  // undefined. An explicit timeout is HONORED verbatim (no ceiling); only the
+  // no-timeout fallback uses the 30m background default. The `params.timeout`
+  // guard below keeps this timer unarmed on the no-timeout path, where the
+  // index.ts deadline timer owns the no-timeout default (no redundant timer).
   let timeoutHandle: ReturnType<typeof setTimeout> | undefined;
   if (params.timeout && params.timeout > 0) {
     timeoutHandle = setTimeout(() => {
@@ -966,7 +914,7 @@ export async function spawnBackgroundSession(
           error: (err as Error).message,
         });
       }
-    }, Math.min(params.timeout, 30 * 60 * 1000));
+    }, normalizeTimeout(params.timeout) ?? DEFAULT_BACKGROUND_DEADLINE_MS);
   }
 
   runPromise.then(() => {

package/src/state.ts

@@ -1,3 +1,4 @@
+// Purpose: Session-bound state container with versioned validation and migration for persisted settings.
 /**
  * brl-subagent — State Management (F5, F7, F9)
  *

package/src/templates.ts

@@ -1,3 +1,4 @@
+// Purpose: Task-template resolution: `${param}` substitution over the file-backed template tiers.
 /**
  * brl-subagent — Task Templates
  *

package/src/transcript-tail.ts

@@ -1,3 +1,4 @@
+// Purpose: Pure line-planning for the drill-in transcript overlay (no TUI imports).
 /**
  * brl-subagent — Pure transcript-tail rendering for the drill-in overlay
  *

package/src/transcript.ts

@@ -1,3 +1,4 @@
+// Purpose: JSONL transcript recording for every agent run (`.pi/output/agent-<id>.jsonl`).
 import { join } from 'path';
 import { mkdirSync, appendFileSync, readFileSync, existsSync } from 'fs';
 import type { TranscriptEntry, TranscriptEntryType } from './types';