pi-subagents 0.65.0 → 0.66.0

package/src/runs/background/control-channel.ts

@@ -275,28 +275,36 @@ function parseSteerRequest(raw: unknown): SteerRequest | undefined {
 	};
 }
 
-export function consumeSteerRequestsFromDir(dir: string, fsImpl: Pick<typeof fs, "existsSync" | "rmSync" | "readdirSync" | "readFileSync"> = fs): SteerRequest[] {
-	if (!fsImpl.existsSync(dir)) return [];
+export function consumeSteerRequestsFromDir(dir: string, fsImpl: Pick<typeof fs, "existsSync" | "rmSync" | "readdirSync" | "readFileSync"> = fs, onError: (error: unknown) => void = () => {}): SteerRequest[] {
 	let entries: string[];
 	try {
 		entries = fsImpl.readdirSync(dir).filter((name) => name.endsWith(".json")).sort();
-	} catch {
+	} catch (error) {
 		// Leave requests in place so the periodic poll can retry the scan.
+		if ((error as NodeJS.ErrnoException).code !== "ENOENT") onError(error);
 		return [];
 	}
 	const requests: SteerRequest[] = [];
 	for (const entry of entries) {
 		const requestPath = path.join(dir, entry);
 		let parsed: SteerRequest | undefined;
+		let text: string;
+		try {
+			text = fsImpl.readFileSync(requestPath, "utf-8");
+		} catch (error) {
+			if ((error as NodeJS.ErrnoException).code !== "ENOENT") onError(error);
+			continue;
+		}
 		try {
-			parsed = parseSteerRequest(JSON.parse(fsImpl.readFileSync(requestPath, "utf-8")));
+			parsed = parseSteerRequest(JSON.parse(text));
 		} catch {
 			parsed = undefined;
 		}
 		try {
 			fsImpl.rmSync(requestPath, { recursive: true });
-		} catch {
+		} catch (error) {
 			// Already removed by a concurrent check — do not execute it twice.
+			if ((error as NodeJS.ErrnoException).code !== "ENOENT") onError(error);
 			continue;
 		}
 		if (parsed) requests.push(parsed);
@@ -304,8 +312,8 @@ export function consumeSteerRequestsFromDir(dir: string, fsImpl: Pick<typeof fs,
 	return requests.sort((left, right) => left.ts - right.ts || left.id.localeCompare(right.id));
 }
 
-export function consumeSteerRequests(asyncDir: string, fsImpl: Pick<typeof fs, "existsSync" | "rmSync" | "readdirSync" | "readFileSync"> = fs): SteerRequest[] {
-	return consumeSteerRequestsFromDir(steerRequestsDir(asyncDir), fsImpl);
+export function consumeSteerRequests(asyncDir: string, fsImpl: Pick<typeof fs, "existsSync" | "rmSync" | "readdirSync" | "readFileSync"> = fs, onError?: (error: unknown) => void): SteerRequest[] {
+	return consumeSteerRequestsFromDir(steerRequestsDir(asyncDir), fsImpl, onError);
 }
 
 export function queueRevivalBrief(asyncDir: string, request: SteerRequest): string {
@@ -387,17 +395,26 @@ function parseStopRequest(raw: unknown): StopRequest | undefined {
 function consumeStopRequestFile(
 	requestPath: string,
 	fsImpl: Pick<typeof fs, "rmSync" | "readFileSync">,
+	onError?: (error: unknown) => void,
 ): StopRequest | undefined {
+	let text: string;
+	try {
+		text = fsImpl.readFileSync(requestPath, "utf-8");
+	} catch (error) {
+		if (!(error instanceof Error && "code" in error && error.code === "ENOENT")) onError?.(error);
+		return undefined;
+	}
 	let request: StopRequest | undefined;
 	try {
-		request = parseStopRequest(JSON.parse(fsImpl.readFileSync(requestPath, "utf-8")));
+		request = parseStopRequest(JSON.parse(text));
 	} catch {
 		request = undefined;
 	}
 	try {
 		fsImpl.rmSync(requestPath, { force: true, recursive: true });
-	} catch {
-		// Already removed by a concurrent check — do not execute it twice.
+	} catch (error) {
+		// Execute only after successful removal.
+		if (!(error instanceof Error && "code" in error && error.code === "ENOENT")) onError?.(error);
 		return undefined;
 	}
 	return request;
@@ -406,6 +423,7 @@ function consumeStopRequestFile(
 export function consumeStopRequestPayloads(
 	asyncDir: string,
 	fsImpl: Pick<typeof fs, "existsSync" | "rmSync" | "readdirSync" | "readFileSync"> = fs,
+	onError?: (error: unknown) => void,
 ): StopRequest[] {
 	const dir = stopRequestsDir(asyncDir);
 	const requests: StopRequest[] = [];
@@ -413,18 +431,19 @@ export function consumeStopRequestPayloads(
 		let entries: string[];
 		try {
 			entries = fsImpl.readdirSync(dir).filter((name) => name.endsWith(".json")).sort();
-		} catch {
+		} catch (error) {
+			if (!(error instanceof Error && "code" in error && error.code === "ENOENT")) onError?.(error);
 			entries = [];
 		}
 		for (const entry of entries) {
-			const request = consumeStopRequestFile(path.join(dir, entry), fsImpl);
+			const request = consumeStopRequestFile(path.join(dir, entry), fsImpl, onError);
 			if (request) requests.push(request);
 		}
 	}
 
 	const legacyPath = stopRequestPath(asyncDir);
 	if (fsImpl.existsSync(legacyPath)) {
-		const request = consumeStopRequestFile(legacyPath, fsImpl);
+		const request = consumeStopRequestFile(legacyPath, fsImpl, onError);
 		if (request) requests.push(request);
 	}
 	return requests.sort((left, right) => (left.ts ?? 0) - (right.ts ?? 0));
@@ -470,19 +489,21 @@ export function deliverStopRequest(input: {
 	requestAsyncStop(input.asyncDir, { ...(input.source ? { source: input.source } : {}), ...(input.targetIndex !== undefined ? { targetIndex: input.targetIndex } : {}), ...(input.childId ? { childId: input.childId } : {}) }, { now: input.now });
 }
 
+
 /**
- * Runner side: watch the control inbox and route interrupt requests into
- * `onInterrupt`. Uses `fs.watch` when available and starts interval polling
+ * Active owner: watch and consume only kinds with installed handlers.
+ * Uses `fs.watch` when available and starts interval polling
  * only when native watching is unavailable or fails. Fires once per distinct
  * request. Returns a disposer.
  */
 export function watchAsyncControlInbox(
 	asyncDir: string,
 	opts: {
-		onInterrupt: () => void;
+		onInterrupt?: () => void;
 		onTimeout?: () => void;
 		onStop?: (request: StopRequest) => void;
 		onSteer?: (request: SteerRequest) => void;
+		onError?: (error: unknown, phase: "install" | "scan" | "callback", request?: SteerRequest) => void;
 		pollIntervalMs?: number;
 		safetyPollIntervalMs?: number;
 		platform?: NodeJS.Platform;
@@ -493,22 +514,44 @@ export function watchAsyncControlInbox(
 	const fsImpl = opts.fs ?? fs;
 	const timers = opts.timers ?? { setInterval, clearInterval };
 	const dir = controlInboxDir(asyncDir);
+	const report = (error: unknown, phase: "install" | "scan" | "callback", request?: SteerRequest): void => {
+		try {
+			if (opts.onError) opts.onError(error, phase, request);
+			else console.error(`Control inbox ${phase} failed:`, error);
+		} catch (reportError) {
+			console.error("Control inbox error reporter failed:", reportError);
+		}
+	};
+	const dirs = [
+		...(opts.onInterrupt || opts.onTimeout || opts.onStop ? [dir] : []),
+		...(opts.onStop ? [stopRequestsDir(asyncDir)] : []),
+		...(opts.onSteer ? [steerRequestsDir(asyncDir)] : []),
+	];
+	if (dirs.length === 0) return () => {};
 	try {
-		fsImpl.mkdirSync(dir, { recursive: true });
-	} catch {
-		// Best effort — the poll/watch below tolerates a missing dir.
+		for (const target of dirs) fsImpl.mkdirSync(target, { recursive: true });
+	} catch (error) {
+		report(error, "install");
 	}
 
 	let disposed = false;
 	const check = (): void => {
 		if (disposed) return;
 		try {
-			for (const stopRequest of consumeStopRequestPayloads(asyncDir, fsImpl)) opts.onStop?.(stopRequest);
-			if (consumeTimeoutRequest(asyncDir, fsImpl)) opts.onTimeout?.();
-			if (consumeInterruptRequest(asyncDir, fsImpl)) opts.onInterrupt();
-			for (const request of consumeSteerRequests(asyncDir, fsImpl)) opts.onSteer?.(request);
-		} catch {
-			// Never let inbox errors crash the runner.
+			if (opts.onStop) for (const request of consumeStopRequestPayloads(asyncDir, fsImpl, (error) => report(error, "scan"))) {
+				try { opts.onStop(request); } catch (error) { report(error, "callback"); }
+			}
+			if (opts.onTimeout && consumeTimeoutRequest(asyncDir, fsImpl)) {
+				try { opts.onTimeout(); } catch (error) { report(error, "callback"); }
+			}
+			if (opts.onInterrupt && consumeInterruptRequest(asyncDir, fsImpl)) {
+				try { opts.onInterrupt(); } catch (error) { report(error, "callback"); }
+			}
+			if (opts.onSteer) for (const request of consumeSteerRequestsFromDir(steerRequestsDir(asyncDir), fsImpl, (error) => report(error, "scan"))) {
+				try { opts.onSteer(request); } catch (error) { report(error, "callback", request); }
+			}
+		} catch (error) {
+			report(error, "scan");
 		}
 	};
 
@@ -516,40 +559,31 @@ export function watchAsyncControlInbox(
 	check();
 
 	const watchers: fs.FSWatcher[] = [];
-	const watchedDirs = new Set<string>();
 	let interval: ReturnType<typeof setInterval> | undefined;
 	let safetyInterval: ReturnType<typeof setInterval> | undefined;
 	const startPolling = (): void => {
 		if (interval || disposed) return;
+		if (safetyInterval) { timers.clearInterval(safetyInterval); safetyInterval = undefined; }
 		interval = timers.setInterval(check, opts.pollIntervalMs ?? POLL_INTERVAL_MS);
 		interval.unref?.();
 	};
-	const startSafetyPolling = (): void => {
-		if (safetyInterval || disposed) return;
-		safetyInterval = timers.setInterval(check, opts.safetyPollIntervalMs ?? CONTROL_SAFETY_POLL_INTERVAL_MS);
-		safetyInterval.unref?.();
-	};
-	const watchDir = (target: string, create = false): void => {
-		if (disposed || watchedDirs.has(target)) return;
-		if (create) fsImpl.mkdirSync(target, { recursive: true });
-		const watcher = fsImpl.watch(resolveWatchPath(target, fsImpl.realpathSync.native), () => check());
-		watcher.on?.("error", startPolling);
-		watchers.push(watcher);
-		watchedDirs.add(target);
-	};
 	try {
 		if (shouldUseNativeFsWatch("runner-control-inbox", opts.platform)) {
-			watchDir(dir);
-			watchDir(stopRequestsDir(asyncDir), true);
-			watchDir(steerRequestsDir(asyncDir), true);
-			startSafetyPolling();
+			for (const target of dirs) {
+				const watcher = fsImpl.watch(resolveWatchPath(target, fsImpl.realpathSync.native), check);
+				watcher.on?.("error", startPolling);
+				watchers.push(watcher);
+			}
+			if (!interval) {
+				safetyInterval = timers.setInterval(check, opts.safetyPollIntervalMs ?? CONTROL_SAFETY_POLL_INTERVAL_MS);
+				safetyInterval.unref?.();
+			}
 		} else {
 			startPolling();
 		}
 	} catch {
 		startPolling();
 	}
-
 	return () => {
 		if (disposed) return;
 		disposed = true;

package/src/runs/background/notify.ts

@@ -6,6 +6,7 @@
  * observation channel, not a delivery acknowledgement.
  */
 
+import { debuglog } from "node:util";
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { buildCompletionKey, markSeenWithTtl } from "./completion-dedupe.ts";
 import {
@@ -34,6 +35,7 @@ export interface SubagentNotifyChildOutput {
 export type SubagentNotifyWatchdogBlocker = Pick<ChildWatchdogWarningSummary, "summary" | "addressed" | "stalemate"> & { agent: string };
 
 export interface SubagentNotifyDetails {
+	workflowReceiptPath?: string;
 	agent: string;
 	status: "completed" | "failed" | "paused" | "stopped";
 	source?: "async" | "foreground";
@@ -123,6 +125,7 @@ export interface RegisterSubagentNotifyOptions {
 
 export interface CompletionNotifier {
 	deliver(result: CompletionNotification): Promise<boolean>;
+	hasPendingDelivery(): boolean;
 	dispose(): void;
 }
 
@@ -188,11 +191,17 @@ function structuredOutputText(value: unknown): string | undefined {
 	}
 }
 
+function isDegenerateOutput(text: string): boolean {
+	return !text.trim() || text.trim() === "</think>";
+}
+
 function childInlinePreview(child: CompletionChild): { preview?: string; truncated?: boolean; unavailableReason?: string } {
 	const output = typeof child.output === "string" ? child.output : "";
 	const outputReference = childSavedOutputPath(child);
 	const referenceOnly = Boolean(outputReference && output.trim().startsWith("Output saved to:"));
-	const raw = child.outputState === "absent" || referenceOnly ? structuredOutputText(child.structuredOutput) : output || structuredOutputText(child.structuredOutput);
+	const raw = child.outputState === "absent" || referenceOnly
+		? structuredOutputText(child.structuredOutput)
+		: isDegenerateOutput(output) ? structuredOutputText(child.structuredOutput) ?? output : output;
 	if (!raw?.trim()) {
 		return { unavailableReason: referenceOnly ? "saved output is file-only" : "no safe inline output" };
 	}
@@ -282,6 +291,7 @@ export function formatSingleCompletion(details: SubagentNotifyDetails): string {
 		: undefined;
 	return [
 		`${taskKind} ${details.status}: **${details.agent}**${details.taskInfo ?? ""}`,
+		details.workflowReceiptPath ? `Workflow receipt: ${details.workflowReceiptPath}` : undefined,
 		"",
 		scheduleLine,
 		scheduleLine ? "" : undefined,
@@ -302,7 +312,11 @@ export function parseSubagentNotifyContent(content: string): SubagentNotifyDetai
 	const lines = content.split("\n");
 	const match = (lines[0] ?? "").match(/^(Background task|Detached foreground task) (completed|failed|paused|stopped): \*\*(.+?)\*\*(?:\s+(\([^)]*\)))?$/);
 	if (!match) return undefined;
-	let body = lines.slice(2);
+	// Only the header slot before the blank separator can carry a receipt.
+	// Identical lines anywhere in model output remain preview text.
+	const receiptHeader = lines[1]?.startsWith("Workflow receipt: ") && lines[2] === "";
+	const workflowReceiptPath = receiptHeader ? lines[1]!.slice("Workflow receipt: ".length) : undefined;
+	let body = lines.slice(receiptHeader ? 3 : 2);
 	// Restore the schedule origin so a re-rendered notice keeps its attribution and
 	// does not fold the line into the result preview.
 	const scheduleMatch = (body[0] ?? "").match(/^Scheduled run from \*\*(.+?)\*\* \(schedule (.+?)\)\.$/);
@@ -358,6 +372,7 @@ export function parseSubagentNotifyContent(content: string): SubagentNotifyDetai
 		...(match[1] === "Detached foreground task" ? { source: "foreground" as const } : {}),
 		...(match[4] ? { taskInfo: match[4] } : {}),
 		...(parsedScheduleOrigin ? { scheduleOrigin: parsedScheduleOrigin } : {}),
+		...(workflowReceiptPath ? { workflowReceiptPath } : {}),
 		resultPreview,
 		...(handoffPath ? { handoffPath } : {}),
 		...(workflowRunId ? { workflowRunId } : {}),
@@ -376,6 +391,7 @@ export function formatGroupedCompletion(details: SubagentNotifyDetails[]): strin
 		if (!detail) continue;
 		const sessionLine = formatSessionLine(detail);
 		blocks.push(`${index + 1}. ${detail.agent}${detail.taskInfo ?? ""}${detail.scheduleOrigin ? ` — scheduled run from ${detail.scheduleOrigin.name ?? detail.scheduleOrigin.id} (schedule ${detail.scheduleOrigin.id})` : ""}`);
+		if (detail.workflowReceiptPath) blocks.push(`Workflow receipt: ${detail.workflowReceiptPath}`);
 		blocks.push(formatResultPreview(detail));
 		blocks.push(...formatWatchdogBlockerLines(detail));
 		if (detail.handoffPath) blocks.push(`Parallel handoff: ${detail.handoffPath}`);
@@ -386,7 +402,31 @@ export function formatGroupedCompletion(details: SubagentNotifyDetails[]): strin
 	return blocks.join("\n").trimEnd();
 }
 
+const notificationDebug = debuglog("pi-subagents-notify");
+type TraceIdentity = Pick<CompletionNotification, "id" | "runId" | "source">;
+type NotificationReason = "disposed" | "missing_session" | "foreground_session_mismatch" | "not_owned"
+	| "intercom_delivered" | "deduped_ttl" | "deduped_pending" | "batch_deferred"
+	| "emit_foreground_session_mismatch" | "emit_not_owned" | "send_accepted" | "send_failed" | "dispose_pending";
+
+// Slice before sanitizing: diagnostic work and each identity are bounded even for
+// malformed result metadata. Never include task/output, paths, or error bodies.
+function traceIdentity(result: TraceIdentity): TraceIdentity {
+	const identity = (value: unknown) => typeof value === "string"
+		? value.slice(0, 128).replace(/[^a-zA-Z0-9_.:-]/g, "_") : undefined;
+	return { id: identity(result.id), runId: identity(result.runId), source: result.source === "foreground" ? "foreground" : "async" };
+}
+
+function traceNotification(reason: NotificationReason, result?: TraceIdentity): void {
+	if (!notificationDebug.enabled) return;
+	try {
+		notificationDebug("%s", JSON.stringify({ reason, ...(result ? traceIdentity(result) : {}) }));
+	} catch {
+		// Diagnostics must never change delivery acknowledgement.
+	}
+}
+
 interface PendingCompletion {
+	trace?: TraceIdentity;
 	key: string;
 	details: SubagentNotifyDetails;
 	sessionId: string;
@@ -447,6 +487,10 @@ export function buildCompletionDetails(result: CompletionNotification): Subagent
 		? result.parallelHandoff as { path?: unknown }
 		: undefined;
 	const handoffPath = typeof parallelHandoff?.path === "string" ? parallelHandoff.path : undefined;
+	const receipt = result.workflowReceipt;
+	const receiptPath = receipt && typeof receipt === "object" && !Array.isArray(receipt)
+		? (receipt as Record<string, unknown>).path : undefined;
+	const workflowReceiptPath = typeof receiptPath === "string" && receiptPath ? receiptPath : undefined;
 	const rawRunId = typeof result.runId === "string" ? result.runId : typeof result.id === "string" ? result.id : undefined;
 	const workflowRunId = (result.mode === "workflow" || agent === "workflow") && rawRunId ? rawRunId : undefined;
 	const directChild = !workflowRunId && result.results?.length === 1 ? result.results[0]! : undefined;
@@ -455,10 +499,17 @@ export function buildCompletionDetails(result: CompletionNotification): Subagent
 		: undefined;
 	const directSummary = summary.trim();
 	const directAgent = typeof directChild?.agent === "string" ? directChild.agent : agent;
+	const directSummaryBody = directAgent && summary.trimStart().startsWith(`${directAgent}:\n`)
+		? summary.trimStart().slice(directAgent.length + 2)
+		: directSummary;
+	const directDegenerateSummary = directChild
+		&& isDegenerateOutput(typeof directChild.output === "string" ? directChild.output : "")
+		&& isDegenerateOutput(directSummaryBody)
+		&& structuredOutputText(directChild.structuredOutput) !== undefined;
 	const directNoOutputSummary = directChild && (!directSummary
 		|| directSummary === "(no output)"
 		|| (directAgent && directSummary === `${directAgent}:\n(no output)`));
-	const resultPreview = directStructuredPreview && directNoOutputSummary
+	const resultPreview = directStructuredPreview && (directNoOutputSummary || directDegenerateSummary)
 		? `Structured output:\n${directStructuredPreview}`
 		: summary;
 	const childRuns = result.results?.flatMap((child) => {
@@ -516,6 +567,7 @@ export function buildCompletionDetails(result: CompletionNotification): Subagent
 		agent,
 		status,
 		...(scheduleOrigin ? { scheduleOrigin } : {}),
+		...(workflowReceiptPath ? { workflowReceiptPath } : {}),
 		...(result.source ? { source: result.source } : {}),
 		...(taskInfo ? { taskInfo } : {}),
 		resultPreview,
@@ -547,8 +599,9 @@ export default function registerSubagentNotify(
 			&& typeof completionOwnerId === "string"
 			&& completionOwnerId === state.completionOwnerId);
 
-	const settle = (items: PendingCompletion[], accepted: boolean) => {
+	const settle = (items: PendingCompletion[], accepted: boolean, reason?: NotificationReason) => {
 		for (const item of items) {
+			if (reason) traceNotification(reason, item.trace);
 			pending.delete(item.key);
 			if (accepted) markSeenWithTtl(seen, item.key, now(), ttlMs);
 			item.resolve(accepted);
@@ -561,10 +614,12 @@ export default function registerSubagentNotify(
 			const owned = item.details.source === "foreground"
 				? item.sessionId === state.currentSessionId
 				: ownsResult(item.sessionId, item.completionOwnerId);
+			if (!owned) traceNotification(item.details.source === "foreground" ? "emit_foreground_session_mismatch" : "emit_not_owned", item.trace);
 			(owned ? accepted : rejected).push(item);
 		}
 		settle(rejected, false);
-		settle(accepted, sendCompletion(pi, accepted));
+		const sent = sendCompletion(pi, accepted);
+		settle(accepted, sent, sent ? "send_accepted" : "send_failed");
 	};
 	const getBatcher = (result: CompletionNotification) => {
 		const key = completionBatchKey(result);
@@ -582,17 +637,35 @@ export default function registerSubagentNotify(
 	};
 
 	const deliver = (result: CompletionNotification): Promise<boolean> => {
-		if (disposed || typeof result.sessionId !== "string") return Promise.resolve(false);
+		if (disposed || typeof result.sessionId !== "string") {
+			traceNotification(disposed ? "disposed" : "missing_session", result);
+			return Promise.resolve(false);
+		}
 		if (result.source === "foreground") {
-			if (result.sessionId !== state.currentSessionId) return Promise.resolve(false);
-		} else if (!ownsResult(result.sessionId, result.completionOwnerId)) return Promise.resolve(false);
-		if (result.intercomDelivered === true) return Promise.resolve(true);
+			if (result.sessionId !== state.currentSessionId) {
+				traceNotification("foreground_session_mismatch", result);
+				return Promise.resolve(false);
+			}
+		} else if (!ownsResult(result.sessionId, result.completionOwnerId)) {
+			traceNotification("not_owned", result);
+			return Promise.resolve(false);
+		}
+		if (result.intercomDelivered === true) {
+			traceNotification("intercom_delivered", result);
+			return Promise.resolve(true);
+		}
 		const key = buildCompletionKey(result, "notify");
 		const seenAt = seen.get(key);
-		if (seenAt !== undefined && now() - seenAt <= ttlMs) return Promise.resolve(true);
+		if (seenAt !== undefined && now() - seenAt <= ttlMs) {
+			traceNotification("deduped_ttl", result);
+			return Promise.resolve(true);
+		}
 		if (seenAt !== undefined) seen.delete(key);
 		const inFlight = pending.get(key);
-		if (inFlight) return inFlight;
+		if (inFlight) {
+			traceNotification("deduped_pending", result);
+			return inFlight;
+		}
 		const details = buildCompletionDetails(result);
 		let resolve!: (accepted: boolean) => void;
 		const completion = new Promise<boolean>((settleCompletion) => { resolve = settleCompletion; });
@@ -605,6 +678,7 @@ export default function registerSubagentNotify(
 			triggerTurn: result.triggerTurn !== false,
 			resolve,
 		};
+		if (notificationDebug.enabled) item.trace = traceIdentity(result);
 		if (details.source === "foreground") {
 			emit([item]);
 			return completion;
@@ -615,6 +689,7 @@ export default function registerSubagentNotify(
 			emit([item]);
 			return completion;
 		}
+		if (batchConfig.enabled) traceNotification("batch_deferred", item.trace);
 		batcher.push(item);
 		return completion;
 	};
@@ -628,10 +703,11 @@ export default function registerSubagentNotify(
 
 	return {
 		deliver,
+		hasPendingDelivery: () => pending.size > 0,
 		dispose() {
 			if (disposed) return;
 			disposed = true;
-			for (const batcher of batchers.values()) settle(batcher.dispose(), false);
+			for (const batcher of batchers.values()) settle(batcher.dispose(), false, "dispose_pending");
 			batchers.clear();
 			for (const unsubscribe of [unsubscribeAsync, unsubscribeForeground]) {
 				try {

package/src/runs/background/owned-process-tree.ts

@@ -1,5 +1,5 @@
 import { spawnSync } from "node:child_process";
-import type { ProcessTreeTerminalV1 } from "../../shared/types.ts";
+import type { ProcessTreeTerminal } from "../../shared/types.ts";
 
 const DEFAULT_TERM_GRACE_MS = 3000;
 const DEFAULT_KILL_VERIFY_MS = 1000;
@@ -52,25 +52,25 @@ async function waitUntilGroupTerminal(
 	}
 }
 
-function observed(processGroupId: number): ProcessTreeTerminalV1 {
+function observed(processGroupId: number): ProcessTreeTerminal {
 	return { state: "observed", mechanism: "posix-process-group", processGroupId, verifiedAt: Date.now() };
 }
 
 /** Owns one writer process group and arbitrates its cleanup exactly once. */
 export interface OwnedProcessTreeController {
-	terminate(): Promise<ProcessTreeTerminalV1>;
-	finishAfterWriterClose(): Promise<ProcessTreeTerminalV1>;
+	terminate(): Promise<ProcessTreeTerminal>;
+	finishAfterWriterClose(): Promise<ProcessTreeTerminal>;
 }
 
 export function createOwnedProcessTreeController(
 	pid: number,
 	options: { termGraceMs?: number; killVerifyMs?: number } = {},
 ): OwnedProcessTreeController {
-	let termination: Promise<ProcessTreeTerminalV1> | undefined;
+	let termination: Promise<ProcessTreeTerminal> | undefined;
 	const posixGroupOwned = process.platform !== "win32";
 	const target = posixGroupOwned ? -pid : pid;
 
-	const terminate = (): Promise<ProcessTreeTerminalV1> => {
+	const terminate = (): Promise<ProcessTreeTerminal> => {
 		if (termination) return termination;
 		termination = (async () => {
 			if (!posixGroupOwned) {