brl-subagent 2.4.0 → 2.5.1

package/src/types.ts

@@ -22,6 +22,15 @@ export type CompletionNotifyMode = (typeof COMPLETION_NOTIFY_MODES)[number];
 
 export const DEFAULT_COMPLETION_NOTIFY: CompletionNotifyMode = "all";
 
+// Option B U3 (D4): boot recovery posture. "offer" surfaces interrupted runs
+// (Run History row + one boot notice); "off" silences the notice and marks
+// newly dispatched runs so they are never offered. "auto" is deliberately NOT
+// a member (U4 territory), enforced by RECOVERY_MODES being the shape guard.
+export const RECOVERY_MODES = ["offer", "off"] as const;
+export type RecoveryMode = (typeof RECOVERY_MODES)[number];
+
+export const DEFAULT_RECOVERY: RecoveryMode = "offer";
+
 export type ThinkingLevel = "off" | "minimal" | "low" | "medium" | "high" | "xhigh";
 
 export const THINKING_LEVELS: ThinkingLevel[] = ["off", "minimal", "low", "medium", "high", "xhigh"];
@@ -62,6 +71,15 @@ export type ErrorCategory =
 // literal in sync with classifyError — do NOT reword one without the other.
 export const SUBAGENT_ABORTED_MESSAGE = "Subagent aborted by user";
 
+// Issue #295: external-signal kill stamp. A SIGKILL/SIGTERM that was NOT staged
+// by our own timeout/abort handler leaves no terminal event, and Node reports
+// code === null for a signal death. The foreground close handler stamps this
+// message (with the signal name) so classifyError can record the honest cause
+// instead of the false 'done' that a fabricated exit 0 produced. Matched below
+// on its distinctive "killed by external signal" substring (mirroring the
+// SUBAGENT_ABORTED_MESSAGE match) — keep the literal in sync with classifyError.
+export const SUBAGENT_SIGNAL_KILLED_MESSAGE = "Subagent killed by external signal";
+
 /**
  * Classify a subagent result into an error category based on its errorMessage,
  * stopReason, exitCode, and stderr content. Inspects patterns in priority order.
@@ -96,6 +114,15 @@ export function classifyError(result: SubagentResult): ErrorCategory {
 	// clobbered by the exitError/unknown fallbacks below.
 	if (msg.includes("aborted by user")) return "aborted";
 
+	// Issue #295: a signal death we did NOT stage (no timeout/abort reason) is
+	// stamped with SUBAGENT_SIGNAL_KILLED_MESSAGE + the signal name by the
+	// foreground close handler. classifyError cannot infer it from the dead
+	// process (a signal death carries no numeric code), so the stamp must survive
+	// reclassification as a genuine crash — checked before the exitCode fallback,
+	// which the -1 signal sentinel would otherwise turn into exit_error. Keep this
+	// substring in sync with the constant above.
+	if (msg.includes("killed by external signal")) return "crash";
+
 	if (msg.includes("model not found") || msg.includes("model unavailable"))
 		return "model_unavailable";
 
@@ -220,6 +247,9 @@ export interface SubagentState {
 	// state, "failed" wakes only on failed/stopped, "off" never wakes (still
 	// delivers passively at the next user prompt).
 	completionNotify: CompletionNotifyMode;
+	// Option B U3 (D4): recovery posture for the session. Applies to newly
+	// dispatched runs (snapshotted per run) and to the boot notice.
+	recovery: RecoveryMode;
 	maxHistoryEntries: number; // 0 = unlimited
 	sessionCostLimit: number; // 0 = unlimited
 	perTaskCostEstimate: number; // 0 = no estimate, use default
@@ -243,6 +273,21 @@ export interface SubagentState {
  */
 export type ToolResult<T = unknown> = AgentToolResult<T> & { isError?: boolean };
 
+/**
+ * Option B U1: identity of the conductor process that owns a run record.
+ *
+ * `pid` plus `start` (the process start-time token — `/proc/<pid>/stat` field
+ * 22 on Linux) lets a fresh process distinguish "a live conductor still owns
+ * this record" from "its conductor is dead", including two conductors sharing
+ * one cwd (which would otherwise be indistinguishable by pid alone after a
+ * reboot). `start` is `""` when the platform cannot supply a start token; the
+ * boot scan then treats ownership as unverifiable and never marks the record.
+ */
+export interface ProcessOwner {
+	pid: number;
+	start: string;
+}
+
 export interface SubagentRun {
 	id: string;
 	task: string;
@@ -278,6 +323,25 @@ export interface SubagentRun {
 	// Issue #114: per-unit priority (may be absent — the run's slot priority
 	// then fell back to the call-level default, which is not recorded here).
 	priority?: string;
+	// Option B U1 (D3/D4): additive durability identity — all optional, so
+	// records written before this change simply lack the keys.
+	// - dispatchId: uuid of the logical dispatch; a retry inherits it.
+	// - resumeOf: the run id a retry resumes (retries only).
+	// - attempt: 1 at first dispatch, (prior.attempt ?? 1) + 1 on a retry.
+	// - interruptedAt: D3 mark set by the boot scan when the conductor died;
+	//   status stays "running" (see isInterruptedRun).
+	// - owner: conductor process identity written at dispatch.
+	// - childMarker: uuid injected into the child process env on the foreground
+	//   path; the boot scan discovers the orphan via /proc/*/environ.
+	dispatchId?: string;
+	resumeOf?: string;
+	attempt?: number;
+	interruptedAt?: string;
+	owner?: ProcessOwner;
+	childMarker?: string;
+	// Option B U3 (D4): the recovery posture in force when this run was
+	// dispatched. Additive: a pre-U3 record lacks it and reads as "offer".
+	recoveryPosture?: RecoveryMode;
 	startedAt: string;
 	finishedAt?: string;
 	durationMs?: number;
@@ -600,6 +664,8 @@ export const EMPTY_USAGE: UsageStats = {
 export const NAV_FOOTER = "\u2191\u2193 navigate \u2022 enter select \u2022 esc cancel";
 
 export const SIGKILL_GRACE_MS = 5000;
+/** Poll interval while waiting for a reaped child to die (B4 early exit, bounded by SIGKILL_GRACE_MS). */
+export const SIGKILL_POLL_MS = 100;
 export const STATUS_RESET_DELAY_MS = 3000;
 export const TEMP_FILE_MODE = 0o600;
 export const TASK_PREVIEW_MAX_LENGTH = 80;
@@ -656,7 +722,7 @@ export const RESERVED_NAME_PATTERN = /^__.*__$/;
 export const RESERVED_COMMAND_NAMES = new Set([
 	"model", "thinking", "concurrency", "depth", "history", "monitor",
 	"preset", "retry", "reset", "priority", "templates", "dashboard", "approval",
- "costlimit", "historyentries", "sla", "completionnotify",
+ "costlimit", "historyentries", "sla", "completionnotify", "recovery",
 	"graph", "sla-stats", "compliance",
 ]);
 
@@ -684,6 +750,27 @@ export interface BackgroundAgent {
 	finalOutput?: string;
 	/** @internal — session reference for live monitor polling */
 	_sessionRef?: import('@earendil-works/pi-coding-agent').AgentSession;
+	/**
+	 * @internal — Option B U2: the on-disk session file for this run, captured
+	 * from `SessionManager.getSessionFile()` at spawn. Used by the settle path to
+	 * prune the EXACT per-run directory. Live-only: stripped by `persistAgent`,
+	 * never a persisted record field (D4).
+	 */
+	_sessionFile?: string;
+	// Option B U1 (D3/D4): additive durability identity, mirroring SubagentRun.
+	// Background records carry dispatchId/owner/attempt. `childMarker` is
+	// declared for round-trip tolerance with the run-record/agent-record JSON
+	// shape (`isSubagentRunShape`) — no background path sets it, because the
+	// session is in-process and has no child process to mark.
+	dispatchId?: string;
+	resumeOf?: string;
+	attempt?: number;
+	interruptedAt?: string;
+	owner?: ProcessOwner;
+	childMarker?: string;
+	// Option B U3 (D4): the recovery posture at dispatch, mirrored from the
+	// run record. Additive (absent reads as "offer").
+	recoveryPosture?: RecoveryMode;
 }
 
 // ---------------------------------------------------------------------------
@@ -748,6 +835,40 @@ export function isSubagentError(result: SubagentResult): boolean {
 		|| result.stopReason === "pending";
 }
 
+/**
+ * Issue #298 (C2): the ONE home for the partial-vs-settled renderer decision.
+ *
+ * `exitCode === -1` is overloaded. Since #206 it is the UNSETTLED streaming
+ * sentinel (`emitSubagentUpdate` in runner.ts stamps `{ ...result, exitCode: -1 }`
+ * on every live partial). Since #295 a SETTLED signal death — external kill,
+ * staged timeout, staged abort — also settles at -1, so the sentinel alone no
+ * longer means "still running":
+ *
+ *   - a live partial carries the sentinel and normally no errorCategory — the
+ *     exception is the abort stamp: `runner.ts` sets `errorCategory: "aborted"`
+ *     on the live result before close, so a post-abort partial can carry both.
+ *     The predicate then returns false and it renders the failure branch — the
+ *     same outcome as the local logic this replaces (the qualifier is comment
+ *     precision, not a behavior change; #311 review nit);
+ *   - every FINALIZED foreground result carries an errorCategory because
+ *     `runSubagent` ends with `result.errorCategory = classifyError(result)`
+ *     and classifyError is total (its `unknown` fallback means it never returns
+ *     undefined). A classified -1 is a settled FAILURE and must take the verdict
+ *     branch, never the raw running text.
+ *
+ * Encoding that (exitCode, errorCategory) invariant EXACTLY ONCE here is the
+ * point of #298: the local disambiguation it replaces (the F1 fix, PR #297) was
+ * the same defect class it fixed — inferring liveness from a correlated field
+ * in the renderer. Callers must use this predicate rather than re-deriving the
+ * pair; the terminal-status structural ratchet in
+ * `src/__tests__/terminal-status-consistency.test.ts` fails a local copy.
+ */
+export function isUnsettledPartial(
+	details: { exitCode: number; errorCategory?: ErrorCategory } | undefined,
+): boolean {
+	return !details || (details.exitCode === -1 && !details.errorCategory);
+}
+
 /**
  * Issue #179 (review ratchet): the NARROWER question — was the terminal turn a
  * provider/model error specifically?
@@ -914,6 +1035,11 @@ export function isSubagentStateShape(value: unknown): value is SubagentState {
 		if (!COMPLETION_NOTIFY_MODES.includes(v.completionNotify as CompletionNotifyMode)) return false;
 	}
 
+	// recovery must be one of RECOVERY_MODES if present ("auto" is rejected)
+	if (v.recovery !== undefined) {
+		if (!RECOVERY_MODES.includes(v.recovery as RecoveryMode)) return false;
+	}
+
 	// maxHistoryEntries must be a non-negative number if present
 	if (v.maxHistoryEntries !== undefined) {
 		if (typeof v.maxHistoryEntries !== "number" || v.maxHistoryEntries < 0) return false;
@@ -949,9 +1075,55 @@ export function isSubagentRunShape(value: unknown): value is SubagentRun {
 	if (typeof v.id !== "string") return false;
 	if (typeof v.task !== "string") return false;
 	if (!["running", "done", "failed"].includes(v.status as string)) return false;
+	// U3 (D4): a malformed snapshot is rejected like any other bad field; an
+	// absent one is fine (pre-U3 records) and reads as "offer" via the helper.
+	if (v.recoveryPosture !== undefined) {
+		if (!RECOVERY_MODES.includes(v.recoveryPosture as RecoveryMode)) return false;
+	}
 	return true;
 }
 
+/**
+ * Option B U3 (D4): the recovery posture recorded for a run. Absent (pre-U3
+ * records) or an unrecognized value reads as the default "offer" — the
+ * additive-field contract (no migration).
+ */
+export function runRecoveryPosture(
+	run: Pick<SubagentRun, "recoveryPosture">,
+): RecoveryMode {
+	return run.recoveryPosture === "off" ? "off" : DEFAULT_RECOVERY;
+}
+
+/**
+ * Option B U1 (D3): the ONE interrupted-state predicate. Status deliberately
+ * stays "running" (a new status value would be dropped by old readers and
+ * misread as resolved by the `!== "running"` guards); the additive
+ * `interruptedAt` mark is the only signal. Consumers must key on THIS helper,
+ * never on a raw status compare.
+ */
+export function isInterruptedRun(run: SubagentRun): boolean {
+	return run.status === "running" && !!run.interruptedAt;
+}
+
+/**
+ * Fix B (item 2): TRUE when a terminal run record represents an ABORT rather
+ * than a genuine failure. Abandon writes the store's ONLY stopped-outcome
+ * shape — `failed` + `stopReason`/`errorCategory` "aborted" (D5 mapping) — and
+ * a user `stop_subagent` writes the same. Failure tallies (SLA) must exclude
+ * these. The run record carries no dedicated "abandoned" marker and D5 forbids
+ * adding one, so a user-ABANDONED run and a user-STOPPED run are
+ * indistinguishable here; both are treated as non-failures.
+ */
+export function isAbortedRun(
+	run: Pick<SubagentRun, "stopReason" | "errorCategory" | "originalParams">,
+): boolean {
+	return (
+		run.stopReason === "aborted" ||
+		run.errorCategory === "aborted" ||
+		run.originalParams?.errorCategory === "aborted"
+	);
+}
+
 /**
  * Type guard: checks if a value is a valid MultiSubagentDetails shape.
  */

package/src/unit-run.ts

@@ -27,9 +27,11 @@ import type {
 	SubagentRun,
 	SubagentToolOptions,
 	Priority,
+	RecoveryMode,
 } from "./types";
-import { getFinalOutput, classifyError } from "./types";
+import { getFinalOutput, classifyError, DEFAULT_RECOVERY } from "./types";
 import { snapshotOriginalParams } from "./params";
+import { currentProcessOwner } from "./recovery";
 import { capOutput, stripAnsi, buildCrashResult } from "./sanitize";
 import { finalizeRunRecord, pruneSessionRuns } from "./history";
 import type { Logger } from "./logging";
@@ -105,6 +107,9 @@ export function createUnitRun(
 	stepModel: { provider: string; id: string },
 	priorityFloor: Priority,
 	presetName?: string,
+	// U3 (D4): the session recovery posture at dispatch. Optional so existing
+	// callers/tests stay valid; production passes `state.config.recovery`.
+	recoveryPosture: RecoveryMode = DEFAULT_RECOVERY,
 ): { runId: string; run: SubagentRun } {
 	const runId = crypto.randomUUID();
 	const run: SubagentRun = {
@@ -123,6 +128,16 @@ export function createUnitRun(
 		// same priority the run entry itself carried.
 		priority: source.priority ?? priorityFloor,
 		startedAt: new Date().toISOString(),
+		// Option B U1: durability identity. Fan-out units are never a retry
+		// target (a retried unit degrades to a single foreground run), so a
+		// fresh dispatchId/attempt=1 and a fresh child marker always apply.
+		dispatchId: crypto.randomUUID(),
+		attempt: 1,
+		owner: currentProcessOwner(),
+		childMarker: crypto.randomUUID(),
+		// U3 (D4): snapshot the posture so the boot notice/offer reads what was
+		// in force at dispatch.
+		recoveryPosture,
 		// The execution-shape fields (background/gitMode/approvalMode/force) are
 		// deliberately omitted: a fan-out unit retries as a SINGLE run, so it must
 		// not inherit the fan-out's background-ness. A retry that wants background