brl-subagent 2.3.8 → 2.4.0

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';
@@ -10,7 +11,8 @@ import { createEvent } from './event-bus';
 import { assertSafeAgentId, sanitizeErrorMessage } from './sanitize';
 import { wrapTask } from './prompt';
 import { createLogger } from './logging';
-import { getCurrentBranch, createWorkBranch, captureDiff, switchToBranch, deleteBranch, hasUncommittedChanges, commitAll, captureWorkingDiff } from './git';
+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';
@@ -20,7 +22,10 @@ import type { ExtensionAPI, ExtensionContext } from '@earendil-works/pi-coding-a
 var spawnQueue: Promise<void> = Promise.resolve();
 
 // C2: per-repo locks serializing the FULL gitMode=branch lifecycle (setup →
-// settle → teardown). Keyed by cwd because different repos don't conflict.
+// settle → teardown). Keyed by the resolved repository root, falling back to
+// the cwd path for directories that are not inside a repository — different
+// repos don't conflict, but different directories of one repo DO share a
+// working tree and must serialize (issue #224).
 const gitBranchLocks = new Map<string, Promise<void>>();
 
 /**
@@ -114,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
  */
@@ -174,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
  */
@@ -222,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
@@ -278,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');
@@ -348,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 }));
 
@@ -724,16 +671,18 @@ export async function spawnBackgroundSession(
     // would read the first's work branch as its base and both teardowns would
     // fight over the shared working tree (stranding the repo on an orphan
     // branch). The lock is released in cleanupWorkBranch (or on setup throw).
-    const prev = gitBranchLocks.get(gitCwd) ?? Promise.resolve();
+    // Key: resolved repository root, cwd fallback for non-repo paths (#224).
+    const lockKey = getRepoRoot(gitCwd) ?? gitCwd;
+    const prev = gitBranchLocks.get(lockKey) ?? Promise.resolve();
     let release!: () => void;
     const gate = new Promise<void>(r => { release = r; });
     const entry = prev.then(() => gate);
-    gitBranchLocks.set(gitCwd, entry);
+    gitBranchLocks.set(lockKey, entry);
     await prev;
     releaseGitLock = () => {
       // Delete the map entry ONLY if we are still the head of the chain — a
       // queued spawn behind us replaced the entry with its own.
-      if (gitBranchLocks.get(gitCwd) === entry) gitBranchLocks.delete(gitCwd);
+      if (gitBranchLocks.get(lockKey) === entry) gitBranchLocks.delete(lockKey);
       release();
     };
 
@@ -939,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(() => {
@@ -961,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';

package/src/tui-format.ts

@@ -1,3 +1,4 @@
+// Purpose: Pure TUI row formatting shared by the monitor and dashboard (no TUI imports).
 /**
  * brl-subagent — Pure TUI formatting helpers
  *