brl-subagent 2.4.0 → 2.5.1

package/AGENT.md

@@ -64,12 +64,19 @@ delegation-heavy work.
 - Graph with `dependsOn`: subtasks declare edges; the scheduler runs them in waves.
 - Background + act on wake: spawn a background run, then act when the completion message arrives. Never poll between spawn and wake.
 - 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.
+- retryRunId: pass a failed or **interrupted** run's id to re-run it with its recorded task and params; explicit parameters override the originals. A run interrupted before durable task capture (a pre-enrichment registry entry) has no recorded task — pass `task` explicitly for those.
+
+## Interrupted runs and recovery
+
+- An interrupted run (its conductor died mid-run) stays visible with status **Interrupted** in `/brl-subagent history` and is listed by `/brl-subagent retry` alongside failed runs — including after a crash + fresh boot, where it is reconstructed from the durable per-run registry (plus the background agent record). Recover it with `retryRunId: <run-id>` (recorded params restored), or abandon it from that menu — abandon finalizes the run as stopped, drops its persisted session file, and sends **no** completion wake.
+- **Task persistence (O3):** a foreground/unit run persists its task, label, model, thinking level and full `originalParams` snapshot in the durable registry at dispatch, so after a crash + fresh boot its row shows the real task and `retryRunId` restores the recorded shape — the same 17 fields a same-session retry restores (including `force`; explicit caller values still win). A successful retry retires the source entry so the superseded run is not re-offered at the next boot; a failed retry start leaves it intact and retryable.
+- **Legacy rows:** an entry written before task persistence lacks those fields, so its row carries `(task unavailable)` and `retryRunId` cannot restore a task — pass `task` explicitly on the retry call. A background run keeps its task via its agent record.
+- The **recovery posture** (`/brl-subagent recovery`, default `offer`) controls whether a boot surfaces interrupted runs with one turn-boundary notice; `off` silences it. Nothing is auto-resumed today.
 
 ## 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.
+- `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. The same applies to an interrupted run — recovery is always an explicit `retryRunId` call, never automatic (auto mode is not yet accepted).
 
 ## Mechanics pointer
 

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.4.0 · **Author:** Azmeen Afandi / [Beeroo Labs](https://beeroolabs.com) · **License:** MIT
+**Version:** 2.5.1 · **Author:** Azmeen Afandi / [Beeroo Labs](https://beeroolabs.com) · **License:** MIT
 
 ---
 
@@ -14,7 +14,7 @@
 - **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 1200+ 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 1500+ test suite pinning every contract against the real pi SDK.
 
 ---
 
@@ -50,6 +50,7 @@ pi remove npm:brl-subagent    # uninstall
 | `/brl-subagent depth` | Set max recursion depth |
 | `/brl-subagent approval` | Set change approval mode |
 | `/brl-subagent completionnotify` | Set completion-push wake (all/failed/off) |
+| `/brl-subagent recovery` | Set recovery posture for interrupted runs (offer/off) |
 | `/brl-subagent costlimit` | Set session cost limit |
 | `/brl-subagent historyentries` | Set max history entries |
 | `/brl-subagent sla` | Configure SLA tracking |
@@ -104,13 +105,15 @@ All settings persist across sessions.
 | `gitMode` | string | — | `'branch'` creates a work branch, captures the diff, and switches back; `'none'` does nothing. Falls back to the configured default. |
 | `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. |
+| `retryRunId` | string | — | Re-run a previously failed or interrupted run with its recorded task and params. |
 | `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.
 
 **Retries (`retryRunId`):** a retry rebuilds the parameter object from a fixed set of fields, falling back to the original run's recorded values, with explicit values on the retry call winning: `task`, `label`, `model`, `preset`, `systemPrompt`, `inheritSystemPrompt`, `thinkingLevel`, `priority`, `outputFile`, `timeout`, `cwd`, `tools`, `excludeTools`, `noBuiltinTools`, plus the four **execution-shape** fields `background`, `gitMode`, `approvalMode` and `force`.
 
+**Interrupted runs:** a run whose conductor died mid-run is marked interrupted (it keeps its persisted session file) and is surfaced as **Interrupted** in `/brl-subagent history` and in `/brl-subagent retry` — including after a crash + fresh boot, when it is reconstructed from the durable per-run registry (plus the background agent record). Recover one with `retryRunId: <run-id>`, or abandon it from the retry menu — abandon finalizes it as stopped, prunes its session file, and sends no completion wake. A **foreground** run's task is not persisted, so its crashed row shows no task and a retry needs the task supplied explicitly; a background run keeps its task in its agent record. The recovery posture (`/brl-subagent recovery`, default `offer`) controls whether a boot announces interrupted runs with one turn-boundary notice; `off` silences it. Recovery is never automatic — there is no `auto` mode.
+
 **The execution-shape fields are restored, so a retry keeps the original's shape:** retrying a background run re-runs it in the background (with its completion wake), a `gitMode: 'branch'` retry keeps its work branch, an `approvalMode`-constrained retry keeps that gating, and a retry that was capability-blocked keeps its `force`. Passing any of them explicitly on the retry call overrides the recorded value. One qualification on `gitMode`: when neither the record nor the call carries one, the **configured** default still applies — so a user with a global `gitMode: 'branch'` gets a work branch on every retry, and one with the default `'none'` gets none. Do not assume "no work branch" without checking the effective `gitMode`.
 
 **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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "brl-subagent",
-  "version": "2.4.0",
+  "version": "2.5.1",
   "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"
@@ -37,12 +37,12 @@
     "typebox": "*"
   },
   "devDependencies": {
-    "@earendil-works/pi-agent-core": "^1.0.0",
-    "@earendil-works/pi-ai": "^1.0.0",
-    "@earendil-works/pi-coding-agent": "^1.0.0",
-    "@earendil-works/pi-tui": "^1.0.0",
+    "@earendil-works/pi-agent-core": "^1.2.0",
+    "@earendil-works/pi-ai": "^1.2.0",
+    "@earendil-works/pi-coding-agent": "^1.2.0",
+    "@earendil-works/pi-tui": "^1.2.0",
     "jiti": "^2.7.0",
-    "typebox": "^1.3.34",
+    "typebox": "1.3.27",
     "typescript": "7.0.2",
     "vitest": "^5.0.0"
   },

package/src/event-bus.ts

@@ -1,5 +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>>();
@@ -49,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) });
       }
     }
   }
@@ -59,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

@@ -17,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"],
 	};
 }
 
@@ -33,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
@@ -105,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

@@ -7,30 +7,42 @@
  */
 
 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";
 
 // ---------------------------------------------------------------------------
 // Run pruning — R2: Disk usage policy
 // ---------------------------------------------------------------------------
 
+/**
+ * Order run records NEWEST-FIRST by `startedAt`, without mutating the input.
+ *
+ * The ONE ordering authority for run records (issue #330): sorts by
+ * `startedAt` descending using `Date.parse` comparisons and returns a new
+ * array. `Array.prototype.sort` is stable, so records sharing a `startedAt`
+ * keep their relative order (spawn-before-terminal for a finalized run).
+ */
+export function sortNewestFirst(runs: SubagentRun[]): SubagentRun[] {
+	return [...runs].sort(
+		(a, b) => Date.parse(b.startedAt) - Date.parse(a.startedAt),
+	);
+}
+
 /**
  * Prune a SubagentRun array to keep only the newest entries up to maxEntries.
- * Uses startedAt timestamp for ordering (newest first). If maxEntries is 0,
- * returns all entries (no limit). Returns a new array; does not mutate input.
+ * The result is always ordered NEWEST-FIRST by `startedAt` — including the
+ * `maxEntries === 0` unlimited path, which keeps every entry but still sorts.
+ * Returns a new array; does not mutate the input.
  */
 export function cleanupRuns(
 	runs: SubagentRun[],
 	maxEntries: number = MAX_RUN_HISTORY_ENTRIES,
 ): SubagentRun[] {
 	if (runs.length === 0) return [];
-	if (maxEntries === 0) return runs;
-
-	// Always sort newest-first for consistency, even when not truncating
-	const sorted = [...runs].sort(
-		(a, b) => new Date(b.startedAt).getTime() - new Date(a.startedAt).getTime(),
-	);
-
+	const sorted = sortNewestFirst(runs);
+	if (maxEntries === 0) return sorted;
 	if (sorted.length <= maxEntries) return sorted;
 	return sorted.slice(0, maxEntries);
 }
@@ -200,3 +212,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;
+}