brl-subagent 2.3.9 → 2.5.0

package/AGENT.md

@@ -66,6 +66,11 @@ delegation-heavy work.
 - Background fan-out: `tasks: [...], background: true` — one background agent per task, one id per task in task order, one wake per agent.
 - retryRunId: pass a failed run's id to re-run it with its recorded task and params; explicit parameters override the originals.
 
+## Deadlines and retries
+
+- `timeout` (ms) is a **deadline, not a ceiling** — an explicit value is honored as given; 30 minutes is only the default for a background run that passes none. Background expiry aborts the session (the run ends `stopped`); foreground expiry kills the process.
+- `retryOnTimeout` applies to **foreground runs only**. A timed-out background run is not auto-retried: re-dispatch it with `retryRunId` if that is the right call.
+
 ## Mechanics pointer
 
 Presets and templates are documented in the schema, not here. Judgment only:

package/README.md

@@ -2,7 +2,7 @@
 
 > Multi-agent orchestration for [pi](https://github.com/earendil-works/pi) — chain, parallel, and dependency-graph delegation to isolated subagents with per-step model routing, preset-driven tool scoping, thinking-level control, and background execution with live monitoring, real abort, and per-agent timeouts.
 
-**Version:** 2.3.9 · **Author:** Azmeen Afandi / [Beeroo Labs](https://beeroolabs.com) · **License:** MIT
+**Version:** 2.5.0 · **Author:** Azmeen Afandi / [Beeroo Labs](https://beeroolabs.com) · **License:** MIT
 
 ---
 
@@ -11,10 +11,10 @@
 `brl-subagent` is **one of the most capable subagent orchestration extensions for pi** — one `delegate_task` tool that spawns fully isolated subagent processes, each with its own model, context window, tool permissions, and thinking level.
 
 - **Multi-step delegation, natively** — chain, parallel, and dependency-graph modes with per-step model routing, so a complex task fans out exactly as you design it.
-- **True background execution** — live monitor, real abort (`stop_subagent`), per-agent timeouts, and hard caps. Nothing orphans; nothing leaks.
+- **True background execution** — live monitor, real abort (`stop_subagent`), per-agent timeouts, and a 30-minute default deadline for runs that don't set one. Nothing orphans; nothing leaks.
 - **Preset-driven tool scoping** — every subagent runs with exactly the tools its job needs, restricted by preset or per-call `tools`/`excludeTools`, with auto-route that picks the right preset when you don't.
 - **Templates with slots** — saved, file-backed task templates with `${param}` placeholders for workflows you run again and again.
-- **Safety by default** — task-fence injection protection, sanitized error paths, owner-only persistence, and a 975+ test suite pinning every contract against the real pi SDK.
+- **Safety by default** — task-fence injection protection, sanitized error paths, owner-only persistence, and a 1300+ test suite pinning every contract against the real pi SDK.
 
 ---
 
@@ -59,11 +59,18 @@ pi remove npm:brl-subagent    # uninstall
 | `/brl-subagent history` | Browse past subagent runs |
 | `/brl-subagent monitor` | Live monitor running subagents |
 | `/brl-subagent dashboard` | Live observability dashboard |
+| `/brl-subagent compliance` | Compliance reports (file access, secrets exposure, full summary) |
 | `/brl-subagent retry` | Browse failed runs to retry |
 | `/brl-subagent reset` | Reset all configuration |
 
 All settings persist across sessions.
 
+### Environment variables
+
+- `BRL_LOG_LEVEL` — minimum level written to the log file. One of `debug`,
+  `info` (default), `warn`, `error`. Read once at module load; unrecognised
+  values fall back to `info`. Runtime changes go through `setLogLevel()`.
+
 ---
 
 ## delegate_task parameters
@@ -82,7 +89,7 @@ All settings persist across sessions.
 | `inheritSystemPrompt` | boolean | `true` | Whether to inherit the main agent's system prompt. Set `false` to save tokens. |
 | `thinkingLevel` | string | — | `off` / `minimal` / `low` / `medium` / `high` / `xhigh`. Capped at user's configured max. |
 | `outputFile` | string | — | Path for the subagent to write full findings. Returns only a summary. |
-| `timeout` | number | — | Max milliseconds. Exceeded → SIGTERM (5s grace) → SIGKILL. Background runs are additionally hard-capped at 30 minutes, so a larger value is silently shortened. |
+| `timeout` | number | — | Max milliseconds. Foreground: exceeded → SIGTERM (5s grace) → SIGKILL. Background: the session is aborted and the run ends `stopped` with the timeout reason. A background run with no explicit `timeout` gets the 30-minute default deadline — an explicit timeout is honored as given (a default, not a ceiling). A raw value `≥ 2^31-1` normalizes to no timeout (for a background run, the 30-minute default then applies). |
 | `cwd` | string | — | Working directory. Defaults to conductor's cwd. |
 | `background` | boolean | `false` | Spawn as an independent background session; returns an ID immediately. With `tasks` it fans out (one background agent per task, one ID per task), and the conductor is woken once per agent as each finishes. See [Background execution](#background-execution). |
 | `priority` | string | — | Concurrency priority: `critical` / `high` / `normal` / `low`. Defaults to `normal`; higher-priority delegations queue ahead. `tasks[]` / `graph[]` steps can set `priority` per unit (see below). |
@@ -98,7 +105,7 @@ All settings persist across sessions.
 | `approvalMode` | string | — | `auto` / `writes` / `always`. Default is user config (`/brl-subagent approval`). `always` is rejected for background runs. |
 | `force` | boolean | `false` | Dispatch anyway past a capability pre-flight block; the block is downgraded to a warning. |
 | `retryRunId` | string | — | Re-run a previously failed run with its recorded task and params. |
-| `retryOnTimeout` | boolean | `false` | Retry once if the subagent times out. The second timeout is a final failure. |
+| `retryOnTimeout` | boolean | `false` | Retry once if a **foreground** subagent times out. The second timeout is a final failure. Background runs are not auto-retried — re-dispatch with `retryRunId`. |
 
 **Capability pre-flight:** before spawning, the extension checks that the resolved toolset can actually do the task — 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`. Such a dispatch is **rejected** by default; `force: true` downgrades the rejection to a **warning**. `force` never suppresses an `outputFile`-without-write conflict — that stays a hard error. Warnings are surfaced in the returned result in every mode.
 
@@ -108,7 +115,7 @@ All settings persist across sessions.
 
 **Fan-out origins are the exception.** Parallel/chain/graph units are recorded per unit, and those records deliberately snapshot **no** `background`, so retrying a unit is a **single run in the foreground**. Pass `background: true` explicitly if you want a background retry.
 
-**Not restored:** `chain` / `tasks` / `graph` and `params` are discarded, so retrying a multi-step run silently degrades to a single task — re-issue it fresh for those shapes. `retryOnTimeout` is **explicit-only**: it is never restored from the recorded run and takes effect only when you pass it on the retry call (it arms a deadline for *this* call).
+**Not restored:** `chain` / `tasks` / `graph` and `params` are discarded, so retrying a multi-step run silently degrades to a single task — re-issue it fresh for those shapes. `retryOnTimeout` is **explicit-only**: it is never restored from the recorded run and takes effect only when you pass it on the retry call (foreground only; it arms a deadline for *this* call).
 
 **`template` is asymmetric:** the original run's template is **not** restored, but a `template` you supply explicitly on the retry call **does** take effect (it is resolved before the retry merge, issue #175) — its body wins over the recorded `task`.
 
@@ -273,7 +280,7 @@ The built-in `code-review` template's slot is `${target}` (its companion `securi
 
 ## Background execution
 
-Set `background: true` to spawn the subagent as an independent session that returns an ID immediately and keeps running. Its progress is tracked via `getAgent` and the live monitor while the main session continues. (Steering via `steerAgent` currently records the message in the transcript and marks the agent as steered — delivery to the live session is pending pi's extension API.)
+Set `background: true` to spawn the subagent as an independent session that returns an ID immediately and keeps running. Its progress is tracked via `getAgent` and the live monitor while the main session continues. Steering via `steerAgent` delivers the message into the agent's live session — it is queued while the agent runs and delivered after the current tool call finishes, before the next model call. Repeat steers work, and a delivery failure surfaces as a real tool error rather than a recorded-but-undelivered steer.
 
 **System prompt semantics:** background sessions are spawned with the same built prompt as foreground subagents (base prompt when `inheritSystemPrompt: true`, custom prompt, preset guidance, and subagent instructions). Like pi's own `--append-system-prompt`, supplying this prompt **replaces** any discovered `.pi/APPEND_SYSTEM.md` / global `APPEND_SYSTEM.md` content — this matches foreground subagent behavior exactly. With `inheritSystemPrompt: true` (the default) your conductor session's instructions — including its own appended content — are inherited through the base prompt.
 
@@ -281,7 +288,7 @@ Set `background: true` to spawn the subagent as an independent session that retu
 
 **Background safety controls (issue #28):** background agents honor the same safety controls as foreground runs — no more unattended sessions that bypass approval, git isolation, deadlines, or cost:
 
-- **Per-agent timeout** — the deadline is armed immediately after the prompt is issued, so in-prompt preflight (auth, model resolution) counts toward it. Background timeouts are hard-capped at 30 minutes — a larger `timeout` is silently shortened. On expiry the session is aborted and the agent ends with status `stopped` and the timeout reason. Timeout values are normalized (`0`/negative/`NaN`/`Infinity`/`≥ 2^31` → no timeout) and a double-fire guard prevents the timer from acting on an already-settled agent.
+- **Per-agent timeout** — the deadline is armed immediately after the prompt is issued, so in-prompt preflight (auth, model resolution) counts toward it. A background run with no explicit `timeout` gets a 30-minute default deadline (the issue #28 orphan protection); an explicit timeout is honored as given — 30 minutes is the default, not a ceiling. On expiry the session is aborted and the agent ends with status `stopped` and the timeout reason. Timeout values are normalized (`0`/negative/`NaN`/`Infinity`/`≥ 2^31` → no timeout, which for a background run means the 30-minute default) and a double-fire guard prevents the timer from acting on an already-settled agent.
 - **Session cost limit (R5)** — the cost check runs before the background spawn, so a session at its limit cannot bypass it by delegating to background. For a background fan-out the whole batch is checked up front as per-task estimate × N.
 - **Approval mode** — `approvalMode: 'always'` is rejected for background agents (there is no interactive dialog to approve a diff while running unattended); `'writes'` silently auto-approves with a warning logged. For a fan-out, `'always'` rejects the whole batch before any spawn and `'writes'` warns once for the batch.
 - **gitMode branch isolation** — with `gitMode: 'branch'` a work branch is created before the run, the agent's changes are committed at teardown so the diff is real, the diff is captured and surfaced via `get_subagent_result`, and the branch is then switched away from and deleted. This requires a clean working tree — a dirty tree is refused loudly rather than risking the base branch. `gitMode: 'branch'` is rejected for background fan-out — see [Background fan-out](#background-fan-out).
@@ -296,6 +303,11 @@ Three checks reject the fan-out up front, before any spawn: `approvalMode: 'alwa
 
 If a spawn fails mid-loop, fan-out stops and reports the failed task plus the IDs already started; an abort mid-loop stops further spawns. Either way, the agents already started stay detached and still wake the conductor. Everything else is unchanged: single background, foreground parallel, the `MAX_PARALLEL_TASKS` cap (8), a live-monitor row per agent, `get_subagent_result` / `steer_subagent` / `stop_subagent` by agent ID, per-agent timeouts, and a single `'writes'` approval warning for the batch.
 
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for setup, the branch model (`main` = releases, `dev` = integration),
+the worktree workflow, and the test gates. Development docs live in [`.development/`](.development/).
+
 ## Changelog
 
 See [CHANGELOG.md](CHANGELOG.md) for the release history.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "brl-subagent",
-  "version": "2.3.9",
-  "description": "Subagent extension for pi with configurable model and thinking mode via selection UI",
+  "version": "2.5.0",
+  "description": "Subagent delegation for pi — blocking or background runs, chain/parallel/graph modes, presets and task templates, live monitor, and dispatch capability guards.",
   "keywords": [
     "pi-package"
   ],
@@ -25,7 +25,9 @@
     ]
   },
   "scripts": {
-    "typecheck": "tsc --noEmit"
+    "typecheck": "tsc --noEmit",
+    "docs:arch": "node scripts/docs-arch.mjs --write",
+    "docs:decisions": "node scripts/docs-decisions.mjs --write"
   },
   "peerDependencies": {
     "@earendil-works/pi-agent-core": "*",
@@ -35,13 +37,13 @@
     "typebox": "*"
   },
   "devDependencies": {
-    "@earendil-works/pi-agent-core": "^0.87.0",
-    "@earendil-works/pi-ai": "^0.87.0",
-    "@earendil-works/pi-coding-agent": "^0.87.0",
-    "@earendil-works/pi-tui": "^0.87.0",
+    "@earendil-works/pi-agent-core": "^1.1.0",
+    "@earendil-works/pi-ai": "^1.1.0",
+    "@earendil-works/pi-coding-agent": "^1.1.0",
+    "@earendil-works/pi-tui": "^1.1.0",
     "jiti": "^2.7.0",
-    "typebox": "^1.3.25",
-    "typescript": "^5.9.3",
+    "typebox": "^1.3.34",
+    "typescript": "7.0.2",
     "vitest": "^5.0.0"
   },
   "overrides": {

package/src/concurrency.ts

@@ -1,3 +1,4 @@
+// Purpose: Session-bound concurrency queue: slot acquisition/release, priority insertion, and progress counters.
 /**
  * brl-subagent — Concurrency Controller (F8)
  *

package/src/diff.ts

@@ -1,3 +1,4 @@
+// Purpose: Parses git unified diffs into structured per-file summaries and hunks for the result UI.
 /**
  * brl-subagent — Git Diff Parser (P5)
  *

package/src/event-bus.ts

@@ -1,4 +1,10 @@
+// Purpose: In-memory lifecycle pub/sub (`subagent:*` events) for extensions and the completion wake.
 import type { SubagentEvent, SubagentEventType, SubagentEventListener } from './types';
+import { createLogger } from './logging';
+
+// Issue #265: listener failures route through the logger (file-only by default)
+// so raw console.error writes cannot corrupt the pi TUI.
+const log = createLogger('event-bus');
 
 // Event listeners by type
 const listeners = new Map<SubagentEventType, Set<SubagentEventListener>>();
@@ -48,7 +54,7 @@ export function emit(event: SubagentEvent): void {
         listener(event);
       } catch (err) {
         // Don't let listener errors break the event loop
-        console.error(`[event-bus] Listener error for ${event.type}:`, err);
+        log.error(`Listener error for ${event.type}`, { error: err instanceof Error ? err.message : String(err) });
       }
     }
   }
@@ -58,7 +64,7 @@ export function emit(event: SubagentEvent): void {
     try {
       listener(event);
     } catch (err) {
-      console.error(`[event-bus] Global listener error:`, err);
+      log.error('Global listener error', { error: err instanceof Error ? err.message : String(err) });
     }
   }
 }

package/src/git.ts

@@ -1,3 +1,4 @@
+// Purpose: Branch-based git workflow for worktree runs: branch creation, diff capture, switch-back, cleanup.
 /**
  * brl-subagent — Git Integration (P3)
  *
@@ -16,6 +17,11 @@ function gitOpts(cwd: string) {
 		cwd,
 		encoding: "utf-8" as const,
 		timeout: 10_000,
+		// Capture child stderr instead of inheriting it: expected git failures
+		// (e.g. deleting a checked-out branch) are caught and returned as
+		// {ok:false, error}; execFileSync still puts the captured stderr in the
+		// thrown error's message, so real failures stay diagnosable.
+		stdio: ["ignore", "pipe", "pipe"] as ["ignore", "pipe", "pipe"],
 	};
 }
 
@@ -32,6 +38,46 @@ export function getCurrentBranch(cwd: string): string {
 	return output.trim();
 }
 
+/**
+ * The starting state of HEAD, captured at spawn so teardown can restore it.
+ *
+ * `getCurrentBranch` alone is NOT enough to restore a detached HEAD: it
+ * returns the "HEAD" pseudo-ref, so a `git checkout HEAD` teardown is a no-op
+ * that stays on the work branch (stranding it and leaking the branch in CI PR
+ * builds, which check out a detached HEAD). The sha + attached-ness must be
+ * captured together.
+ *
+ * `detached` also governs DATA SAFETY at teardown (#308): a detached start has
+ * no branch of its own to retain a merged work branch, so the auto-approve path
+ * MUST preserve the work branch as the durable ref rather than delete it.
+ */
+export interface HeadState {
+	/** Commit HEAD pointed at when captured. */
+	sha: string;
+	/** True when HEAD was detached (no symbolic ref) at capture time. */
+	detached: boolean;
+	/**
+	 * Branch name when attached; the literal "HEAD" pseudo-ref when detached.
+	 * Attached callers can pass it straight to createWorkBranch/captureDiff.
+	 */
+	branch: string;
+}
+
+/**
+ * Capture the current HEAD state (sha + attached-ness) for later restoration.
+ * Throws if the cwd is not a git repository.
+ */
+export function getHeadState(cwd: string): HeadState {
+	const sha = execFileSync("git", ["rev-parse", "HEAD"], gitOpts(cwd)).trim();
+	try {
+		// Exits non-zero when HEAD is detached — that is the discriminator.
+		const branch = execFileSync("git", ["symbolic-ref", "--short", "-q", "HEAD"], gitOpts(cwd)).trim();
+		return { sha, detached: false, branch };
+	} catch {
+		return { sha, detached: true, branch: "HEAD" };
+	}
+}
+
 /**
  * Resolve the repository root that contains the given directory.
  * Returns undefined when the directory is not inside a repository, or when
@@ -104,6 +150,28 @@ export function switchToBranch(
 	}
 }
 
+/**
+ * Restore HEAD to the state captured by getHeadState.
+ * Detached starts are re-detached at the captured sha (`git checkout
+ * --detach <sha>`) instead of switching to the useless "HEAD" pseudo-ref;
+ * attached starts switch back to the original branch.
+ * Returns { ok: true } on success, { ok: false, error } on failure.
+ */
+export function restoreHead(
+	cwd: string,
+	state: HeadState,
+): { ok: true } | { ok: false; error: string } {
+	try {
+		const args = state.detached
+			? ["checkout", "--detach", state.sha]
+			: ["checkout", state.branch];
+		execFileSync("git", args, gitOpts(cwd));
+		return { ok: true };
+	} catch (err) {
+		return { ok: false, error: (err as Error).message };
+	}
+}
+
 /**
  * Merge a work branch into the current branch.
  * Uses --no-edit to prevent opening an editor.

package/src/history.ts

@@ -1,3 +1,4 @@
+// Purpose: Run-record store: creation, finalization, retry lookup, and history pruning.
 /**
  * brl-subagent — Run History
  *
@@ -6,7 +7,9 @@
  */
 
 import type { SubagentRun, SubagentResult } from "./types";
-import { isSubagentError, getFinalOutput, isSubagentRunShape, classifyError, coherentFailureReason, CUSTOM_ENTRY_TYPES, MAX_RUN_HISTORY_ENTRIES } from "./types";
+import { isSubagentError, getFinalOutput, isSubagentRunShape, classifyError, coherentFailureReason, CUSTOM_ENTRY_TYPES, MAX_RUN_HISTORY_ENTRIES, DEFAULT_OUTPUT_CAP_BYTES } from "./types";
+import { isOutputTruncated } from "./sanitize";
+import { transcriptDisplayPath } from "./transcript-path";
 import type { ExtensionContext, SessionManager } from "@earendil-works/pi-coding-agent";
 
 // ---------------------------------------------------------------------------
@@ -199,3 +202,58 @@ export function formatRunDuration(ms: number): string {
 	const secs = Math.round((ms % 60_000) / 1000);
 	return `${min}m ${secs}s`;
 }
+
+// ---------------------------------------------------------------------------
+// Full-output honesty lines (issue #261)
+// ---------------------------------------------------------------------------
+
+/**
+ * Human-readable size for an output cap, e.g. `100 * 1024` → "100 KB".
+ * Byte caps are whole-KB by construction; sub-KB values (mostly tests) render
+ * as plain bytes.
+ */
+function formatCapSize(capBytes: number): string {
+	if (capBytes > 0 && capBytes % 1024 === 0) return `${capBytes / 1024} KB`;
+	return `${capBytes} B`;
+}
+
+/**
+ * Honest disclosure lines for a settled run's full-output view (issue #261).
+ *
+ * Always returns the transcript pointer. When the stored output hit the
+ * `capBytes` cap it also adds a disclosure that points at the transcript for
+ * the rest. Detection is deliberately two-signal:
+ *
+ *   1. `isOutputTruncated(run.fullOutput)` — the exact `capOutput` notice, true
+ *      only when the stored text was genuinely truncated;
+ *   2. `Buffer.byteLength` at/over `capBytes` — the length fallback, so an
+ *      UNCAPPED record (background/crash paths store raw `liveOutput`) that
+ *      already sits at or over the cap budget is still disclosed instead of
+ *      pretending the panel can show more than the cap's worth.
+ *
+ * Boundary precision: `capOutput` truncates only when the byte length is
+ * STRICTLY greater than the cap, so an output of exactly `capBytes` takes the
+ * length branch and is disclosed as "at or over" without carrying the notice.
+ * The notice branch alone is exact for "was truncated".
+ *
+ * Pure and pi-tui-free, so it is unit-testable in isolation.
+ */
+export function buildOutputHonestyLines(
+	run: Pick<SubagentRun, "id" | "fullOutput">,
+	capBytes: number = DEFAULT_OUTPUT_CAP_BYTES,
+): string[] {
+	const transcriptPath = transcriptDisplayPath(run.id);
+	const lines = [`Transcript: ${transcriptPath}`];
+	const output = run.fullOutput;
+	const size = formatCapSize(capBytes);
+	if (isOutputTruncated(output)) {
+		lines.push(
+			`Output was truncated at the ${size} cap — full text in the transcript: ${transcriptPath}`,
+		);
+	} else if (output && Buffer.byteLength(output, "utf8") >= capBytes) {
+		lines.push(
+			`Stored output is at or over the ${size} cap — full transcript: ${transcriptPath}`,
+		);
+	}
+	return lines;
+}