@selesai/code 0.2.1 → 0.3.1

package/dist/extensions/pi-subagents/test/unit/nested-events.test.ts

@@ -0,0 +1,329 @@
+import assert from "node:assert/strict";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { afterEach, describe, it } from "node:test";
+import type { AsyncJobState, SubagentState } from "../../src/shared/types.ts";
+import {
+	buildNestedRouteIndex,
+	createNestedRoute,
+	hasLiveNestedDescendants,
+	parseNestedEventRecords,
+	projectNestedEvents,
+	resolveNestedParentAddressFromEnv,
+	resolveNestedRouteFromEnv,
+	updateAsyncJobNestedProjection,
+	updateForegroundNestedProjection,
+	writeNestedEvent,
+} from "../../src/runs/shared/nested-events.ts";
+import {
+	SUBAGENT_PARENT_CAPABILITY_TOKEN_ENV,
+	SUBAGENT_PARENT_CHILD_INDEX_ENV,
+	SUBAGENT_PARENT_CONTROL_INBOX_ENV,
+	SUBAGENT_PARENT_DEPTH_ENV,
+	SUBAGENT_PARENT_EVENT_SINK_ENV,
+	SUBAGENT_PARENT_PATH_ENV,
+	SUBAGENT_PARENT_ROOT_RUN_ID_ENV,
+	SUBAGENT_PARENT_RUN_ID_ENV,
+} from "../../src/runs/shared/pi-args.ts";
+
+const routes: Array<{ eventSink: string }> = [];
+const savedEnv = {
+	[SUBAGENT_PARENT_EVENT_SINK_ENV]: process.env[SUBAGENT_PARENT_EVENT_SINK_ENV],
+	[SUBAGENT_PARENT_CONTROL_INBOX_ENV]: process.env[SUBAGENT_PARENT_CONTROL_INBOX_ENV],
+	[SUBAGENT_PARENT_ROOT_RUN_ID_ENV]: process.env[SUBAGENT_PARENT_ROOT_RUN_ID_ENV],
+	[SUBAGENT_PARENT_RUN_ID_ENV]: process.env[SUBAGENT_PARENT_RUN_ID_ENV],
+	[SUBAGENT_PARENT_CHILD_INDEX_ENV]: process.env[SUBAGENT_PARENT_CHILD_INDEX_ENV],
+	[SUBAGENT_PARENT_DEPTH_ENV]: process.env[SUBAGENT_PARENT_DEPTH_ENV],
+	[SUBAGENT_PARENT_PATH_ENV]: process.env[SUBAGENT_PARENT_PATH_ENV],
+	[SUBAGENT_PARENT_CAPABILITY_TOKEN_ENV]: process.env[SUBAGENT_PARENT_CAPABILITY_TOKEN_ENV],
+};
+
+afterEach(() => {
+	for (const route of routes.splice(0)) {
+		fs.rmSync(path.dirname(route.eventSink), { recursive: true, force: true });
+	}
+	for (const [key, value] of Object.entries(savedEnv)) {
+		if (value === undefined) delete process.env[key];
+		else process.env[key] = value;
+	}
+});
+
+function trackRoute(rootRunId = "root-run") {
+	const route = createNestedRoute(rootRunId);
+	routes.push(route);
+	return route;
+}
+
+function child(id: string, state: "queued" | "running" | "complete" | "failed" | "paused", ts: number, parentRunId = "root-run") {
+	return {
+		id,
+		parentRunId,
+		parentStepIndex: 1,
+		depth: 1,
+		path: [{ runId: parentRunId, stepIndex: 1 }],
+		mode: "single" as const,
+		state,
+		agent: "reviewer",
+		agents: ["reviewer"],
+		startedAt: 10,
+		lastUpdate: ts,
+		steps: [{ agent: "leaf", status: state === "running" ? "running" as const : "complete" as const }],
+	};
+}
+
+describe("nested route index", () => {
+	it("indexes routes by root run id in a single directory scan", () => {
+		const routeA = trackRoute("index-root-a");
+		const routeB = trackRoute("index-root-b");
+
+		const index = buildNestedRouteIndex();
+
+		assert.equal(index.get("index-root-a")?.capabilityToken, routeA.capabilityToken);
+		assert.equal(index.get("index-root-b")?.capabilityToken, routeB.capabilityToken);
+		assert.equal(index.get("missing-root"), undefined);
+	});
+
+	it("keeps at most one route when a root run id has duplicate route dirs", () => {
+		const first = trackRoute("dup-root");
+		const second = trackRoute("dup-root");
+
+		const index = buildNestedRouteIndex();
+
+		// readdir order is not guaranteed, so the contract is deduplication: exactly
+		// one route is indexed per root run id, not a specific winner.
+		const indexed = index.get("dup-root");
+		assert.ok(indexed, "expected one route for dup-root");
+		const tokens = new Set([first.capabilityToken, second.capabilityToken]);
+		assert.ok(tokens.has(indexed.capabilityToken), "indexed route must be one of the two created routes");
+	});
+});
+
+describe("nested event route validation", () => {
+	it("resolves nested parent addresses with full inherited path", () => {
+		process.env[SUBAGENT_PARENT_RUN_ID_ENV] = "nested-parent";
+		process.env[SUBAGENT_PARENT_CHILD_INDEX_ENV] = "2";
+		process.env[SUBAGENT_PARENT_DEPTH_ENV] = "3";
+		process.env[SUBAGENT_PARENT_PATH_ENV] = JSON.stringify([
+			{ runId: "root-run", stepIndex: 0, agent: "root-agent" },
+			{ runId: "../unsafe", stepIndex: 1, agent: "bad" },
+			{ runId: "nested-parent", stepIndex: 2, agent: "nested-agent" },
+		]);
+
+		assert.deepEqual(resolveNestedParentAddressFromEnv(), {
+			parentRunId: "nested-parent",
+			parentStepIndex: 2,
+			depth: 3,
+			path: [
+				{ runId: "root-run", stepIndex: 0, agent: "root-agent" },
+				{ runId: "nested-parent", stepIndex: 2, agent: "nested-agent" },
+			],
+		});
+	});
+
+	it("ignores unsafe nested parent ids from env", () => {
+		process.env[SUBAGENT_PARENT_RUN_ID_ENV] = "../unsafe";
+		process.env[SUBAGENT_PARENT_CHILD_INDEX_ENV] = "2";
+
+		assert.equal(resolveNestedParentAddressFromEnv(), undefined);
+	});
+
+	it("resolves only matching contained routes from env", () => {
+		const route = trackRoute();
+		process.env[SUBAGENT_PARENT_EVENT_SINK_ENV] = route.eventSink;
+		process.env[SUBAGENT_PARENT_CONTROL_INBOX_ENV] = route.controlInbox;
+		process.env[SUBAGENT_PARENT_ROOT_RUN_ID_ENV] = route.rootRunId;
+		process.env[SUBAGENT_PARENT_CAPABILITY_TOKEN_ENV] = route.capabilityToken;
+
+		assert.deepEqual(resolveNestedRouteFromEnv(), route);
+
+		process.env[SUBAGENT_PARENT_CAPABILITY_TOKEN_ENV] = "wrong-token";
+		assert.throws(() => resolveNestedRouteFromEnv(), /capability token/);
+	});
+});
+
+describe("nested event parsing and projection", () => {
+	it("projects started, updated, and completed records into async and foreground parent state", () => {
+		const route = trackRoute();
+		writeNestedEvent(route, {
+			type: "subagent.nested.started",
+			ts: 100,
+			parentRunId: "root-run",
+			parentStepIndex: 1,
+			child: child("nested-a", "running", 100),
+		});
+		writeNestedEvent(route, {
+			type: "subagent.nested.updated",
+			ts: 200,
+			parentRunId: "root-run",
+			parentStepIndex: 1,
+			child: { ...child("nested-a", "running", 200), currentTool: "read" },
+		});
+		writeNestedEvent(route, {
+			type: "subagent.nested.completed",
+			ts: 300,
+			parentRunId: "root-run",
+			parentStepIndex: 1,
+			child: child("nested-a", "complete", 300),
+		});
+
+		const registry = projectNestedEvents(route);
+		assert.equal(registry.children.length, 1);
+		assert.equal(registry.children[0]?.id, "nested-a");
+		assert.equal(registry.children[0]?.state, "complete");
+		assert.equal(registry.children[0]?.steps?.[0]?.agent, "leaf");
+
+		const job: AsyncJobState = {
+			asyncId: "root-run",
+			asyncDir: "/tmp/root-run",
+			status: "running",
+			nestedRoute: route,
+			steps: [
+				{ agent: "owner-0", status: "running", index: 0 },
+				{ agent: "owner-1", status: "running", index: 1 },
+			],
+		};
+		updateAsyncJobNestedProjection(job);
+		assert.equal(job.nestedChildren?.[0]?.id, "nested-a");
+		assert.equal(job.steps?.[1]?.children?.[0]?.id, "nested-a");
+
+		const control: SubagentState["foregroundControls"] extends Map<string, infer T> ? T : never = {
+			runId: "root-run",
+			mode: "single",
+			startedAt: 1,
+			updatedAt: 1,
+			nestedRoute: route,
+		};
+		updateForegroundNestedProjection(control);
+		assert.equal(control.nestedChildren?.[0]?.id, "nested-a");
+	});
+
+	it("attaches root children to visible step slices by original step index", () => {
+		const route = trackRoute();
+		writeNestedEvent(route, {
+			type: "subagent.nested.updated",
+			ts: 100,
+			parentRunId: "root-run",
+			parentStepIndex: 3,
+			child: { ...child("nested-visible", "running", 100), parentStepIndex: 3, path: [{ runId: "root-run", stepIndex: 3 }] },
+		});
+		const job: AsyncJobState = {
+			asyncId: "root-run",
+			asyncDir: "/tmp/root-run",
+			status: "running",
+			nestedRoute: route,
+			steps: [
+				{ agent: "owner-2", status: "running", index: 2 },
+				{ agent: "owner-3", status: "running", index: 3 },
+			],
+		};
+
+		updateAsyncJobNestedProjection(job);
+
+		assert.equal(job.steps?.[0]?.children, undefined);
+		assert.equal(job.steps?.[1]?.children?.[0]?.id, "nested-visible");
+	});
+
+	it("ignores corrupt, partial, wrong-token, duplicate, and stale records while preserving terminal state", () => {
+		const route = trackRoute();
+		fs.writeFileSync(path.join(route.eventSink, "0000000000001-corrupt.json"), "{not json", "utf-8");
+		fs.writeFileSync(
+			path.join(route.eventSink, "0000000000002-partial.jsonl"),
+			`${JSON.stringify({
+				type: "subagent.nested.started",
+				ts: 50,
+				rootRunId: route.rootRunId,
+				parentRunId: "root-run",
+				parentStepIndex: 1,
+				capabilityToken: route.capabilityToken,
+				child: child("partial-good", "running", 50),
+			})}\n{"type":"subagent.nested.started"`,
+			"utf-8",
+		);
+		writeNestedEvent(route, {
+			type: "subagent.nested.completed",
+			ts: 300,
+			parentRunId: "root-run",
+			parentStepIndex: 1,
+			child: child("nested-terminal", "complete", 300),
+		});
+		fs.writeFileSync(path.join(route.eventSink, "0000000000400-stale.json"), `${JSON.stringify({
+			type: "subagent.nested.updated",
+			ts: 400,
+			rootRunId: route.rootRunId,
+			parentRunId: "root-run",
+			parentStepIndex: 1,
+			capabilityToken: route.capabilityToken,
+			child: child("nested-terminal", "running", 100),
+		})}\n`, "utf-8");
+		fs.writeFileSync(path.join(route.eventSink, "0000000000500-wrong-token.json"), `${JSON.stringify({
+			type: "subagent.nested.started",
+			ts: 500,
+			rootRunId: route.rootRunId,
+			parentRunId: "root-run",
+			parentStepIndex: 1,
+			capabilityToken: "wrong",
+			child: child("wrong-token", "running", 500),
+		})}\n`, "utf-8");
+
+		const registry = projectNestedEvents(route);
+		assert.equal(registry.children.find((item) => item.id === "partial-good")?.state, "running");
+		assert.equal(registry.children.find((item) => item.id === "nested-terminal")?.state, "complete");
+		assert.equal(registry.children.some((item) => item.id === "wrong-token"), false);
+		assert.equal(hasLiveNestedDescendants(registry.children), true);
+	});
+
+	it("detects live descendants attached to terminal step children", () => {
+		assert.equal(hasLiveNestedDescendants([{
+			...child("terminal-parent", "complete", 300),
+			steps: [{
+				agent: "owner-step",
+				status: "complete",
+				children: [{
+					...child("running-step-child", "running", 310, "terminal-parent"),
+					parentStepIndex: 0,
+					path: [{ runId: "terminal-parent", stepIndex: 0 }],
+				}],
+			}],
+		}]), true);
+	});
+
+	it("accepts only complete numeric token usage at the nested event boundary", () => {
+		const route = trackRoute();
+		writeNestedEvent(route, {
+			type: "subagent.nested.updated",
+			ts: 100,
+			parentRunId: "root-run",
+			parentStepIndex: 1,
+			child: { ...child("nested-valid-tokens", "running", 100), totalTokens: { input: 10, output: 15, total: 25 } },
+		});
+		fs.writeFileSync(path.join(route.eventSink, "0000000000200-invalid-tokens.json"), `${JSON.stringify({
+			type: "subagent.nested.updated",
+			ts: 200,
+			rootRunId: route.rootRunId,
+			parentRunId: "root-run",
+			parentStepIndex: 1,
+			capabilityToken: route.capabilityToken,
+			child: { ...child("nested-invalid-tokens", "running", 200), totalTokens: { input: 1, output: "bad", total: 1 } },
+		})}\n`, "utf-8");
+
+		const registry = projectNestedEvents(route);
+
+		assert.deepEqual(registry.children.find((item) => item.id === "nested-valid-tokens")?.totalTokens, { input: 10, output: 15, total: 25 });
+		assert.equal(registry.children.find((item) => item.id === "nested-invalid-tokens")?.totalTokens, undefined);
+	});
+
+	it("parses only complete jsonl records", () => {
+		const route = trackRoute();
+		const records = parseNestedEventRecords(`${JSON.stringify({
+			type: "subagent.nested.started",
+			ts: 100,
+			rootRunId: route.rootRunId,
+			parentRunId: "root-run",
+			parentStepIndex: 1,
+			capabilityToken: route.capabilityToken,
+			child: child("jsonl-good", "running", 100),
+		})}\n{"type":"subagent.nested.started"`, route);
+		assert.equal(records.length, 1);
+		assert.equal(records[0]?.child.id, "jsonl-good");
+	});
+});

package/dist/extensions/pi-subagents/test/unit/notify.test.ts

@@ -0,0 +1,319 @@
+import assert from "node:assert/strict";
+import { EventEmitter } from "node:events";
+import { describe, it } from "node:test";
+import registerSubagentNotify, {
+	buildCompletionDetails,
+	formatGroupedCompletion,
+	formatSingleCompletion,
+	type RegisterSubagentNotifyOptions,
+	type SubagentNotifyDetails,
+} from "../../src/runs/background/notify.ts";
+import { SUBAGENT_ASYNC_COMPLETE_EVENT } from "../../src/shared/types.ts";
+
+function createPi(currentSessionId = "session-1", registerOptions: RegisterSubagentNotifyOptions = {}) {
+	const events = new EventEmitter();
+	const sent: Array<{ message: unknown; options: unknown }> = [];
+	const pi = {
+		events,
+		sendMessage(message: unknown, options: unknown) {
+			sent.push({ message, options });
+		},
+	};
+
+	// Formatting-focused tests run with batching disabled so single completions
+	// emit synchronously. Batching behavior is covered by the dedicated suite below.
+	registerSubagentNotify(pi as never, { currentSessionId }, { batchConfig: { enabled: false }, ...registerOptions });
+
+	return { events, sent };
+}
+
+function createBatchingPi(clock: ReturnType<typeof createFakeClock>, currentSessionId = "session-a") {
+	const events = new EventEmitter();
+	const sent: Array<{ message: unknown; options: unknown }> = [];
+	const pi = {
+		events,
+		sendMessage(message: unknown, options: unknown) {
+			sent.push({ message, options });
+		},
+	};
+	registerSubagentNotify(pi as never, { currentSessionId }, {
+		batchConfig: { enabled: true, debounceMs: 150, maxWaitMs: 1000, stragglerDebounceMs: 75, stragglerMaxWaitMs: 400, stragglerWindowMs: 2000 },
+		timers: clock.api,
+		now: clock.now,
+	});
+	return { events, sent };
+}
+
+interface FakeJob {
+	id: number;
+	fireAt: number;
+	handler: () => void;
+}
+
+function createFakeClock() {
+	let now = 0;
+	let nextId = 1;
+	const jobs = new Map<number, FakeJob>();
+	const api = {
+		setTimeout(handler: () => void, delayMs: number): unknown {
+			const id = nextId++;
+			jobs.set(id, { id, fireAt: now + delayMs, handler });
+			return id;
+		},
+		clearTimeout(handle: unknown): void {
+			if (typeof handle === "number") jobs.delete(handle);
+		},
+	};
+	return {
+		api,
+		now: () => now,
+		advance(ms: number): void {
+			now += ms;
+			const due = [...jobs.values()].filter((job) => job.fireAt <= now).sort((a, b) => a.fireAt - b.fireAt);
+			for (const job of due) {
+				if (!jobs.has(job.id)) continue;
+				jobs.delete(job.id);
+				job.handler();
+			}
+		},
+	};
+}
+
+function completionResult(overrides: Record<string, unknown> = {}) {
+	return {
+		id: `notify-${Math.random().toString(36).slice(2)}`,
+		agent: "worker",
+		success: true,
+		summary: "Done",
+		exitCode: 0,
+		timestamp: 123,
+		sessionId: "session-a",
+		...overrides,
+	};
+}
+
+describe("registerSubagentNotify", () => {
+	it("uses a fallback summary when a background completion is empty", () => {
+		const { events, sent } = createPi();
+
+		events.emit(SUBAGENT_ASYNC_COMPLETE_EVENT, {
+			id: "notify-empty-1",
+			agent: "worker",
+			success: true,
+			summary: "",
+			exitCode: 0,
+			timestamp: 123,
+			sessionId: "session-1",
+		});
+
+		assert.equal(sent.length, 1);
+		assert.deepEqual(sent[0], {
+			message: {
+				customType: "subagent-notify",
+				content: "Background task completed: **worker**\n\n(no output)",
+				display: true,
+			},
+			options: { triggerTurn: true },
+		});
+	});
+
+	it("preserves non-empty completion summaries", () => {
+		const { events, sent } = createPi();
+		const summary = "  Done streaming\nAll clear  ";
+
+		events.emit(SUBAGENT_ASYNC_COMPLETE_EVENT, {
+			id: "notify-summary-1",
+			agent: "worker",
+			success: true,
+			summary,
+			exitCode: 0,
+			timestamp: 456,
+			taskIndex: 1,
+			totalTasks: 3,
+			sessionId: "session-1",
+		});
+
+		assert.equal(sent.length, 1);
+		assert.deepEqual(sent[0], {
+			message: {
+				customType: "subagent-notify",
+				content: `Background task completed: **worker** (2/3)\n\n${summary}`,
+				display: true,
+			},
+			options: { triggerTurn: true },
+		});
+	});
+
+	it("preserves session paths in notification content", () => {
+		const { events, sent } = createPi();
+
+		events.emit(SUBAGENT_ASYNC_COMPLETE_EVENT, {
+			id: "notify-path-1",
+			agent: "worker",
+			success: true,
+			summary: "Done",
+			exitCode: 0,
+			timestamp: 456,
+			sessionFile: "/tmp/session.jsonl",
+			sessionId: "session-1",
+		});
+
+		assert.deepEqual(sent, [{
+			message: {
+				customType: "subagent-notify",
+				content: "Background task completed: **worker**\n\nDone\n\nSession file: /tmp/session.jsonl",
+				display: true,
+			},
+			options: { triggerTurn: true },
+		}]);
+	});
+
+	it("labels paused completions as paused even without an exit code", () => {
+		const { events, sent } = createPi();
+
+		events.emit(SUBAGENT_ASYNC_COMPLETE_EVENT, {
+			id: "notify-paused-1",
+			agent: "worker",
+			success: false,
+			state: "paused",
+			summary: "Paused after interrupt. Waiting for explicit next action.",
+			timestamp: 789,
+			sessionId: "session-1",
+		});
+
+		assert.equal(sent.length, 1);
+		assert.deepEqual(sent[0], {
+			message: {
+				customType: "subagent-notify",
+				content: "Background task paused: **worker**\n\nPaused after interrupt. Waiting for explicit next action.",
+				display: true,
+			},
+			options: { triggerTurn: true },
+		});
+	});
+
+	it("ignores completions for other or missing session ids", () => {
+		const { events, sent } = createPi("session-owner");
+
+		events.emit(SUBAGENT_ASYNC_COMPLETE_EVENT, {
+			id: "notify-other-session",
+			agent: "worker",
+			success: true,
+			summary: "Other done",
+			timestamp: 100,
+			sessionId: "session-other",
+		});
+		events.emit(SUBAGENT_ASYNC_COMPLETE_EVENT, {
+			id: "notify-sessionless",
+			agent: "worker",
+			success: true,
+			summary: "Legacy cwd-scoped done",
+			timestamp: 101,
+			cwd: "/repo",
+		});
+
+		assert.deepEqual(sent, []);
+	});
+
+	it("emits failed completions immediately even while successes are held", () => {
+		const clock = createFakeClock();
+		const { events, sent } = createBatchingPi(clock);
+
+		events.emit(SUBAGENT_ASYNC_COMPLETE_EVENT, completionResult({ id: "ok-1", agent: "ok-1", summary: "ok-1 done" }));
+		events.emit(SUBAGENT_ASYNC_COMPLETE_EVENT, completionResult({ id: "fail-1", agent: "fail-1", success: false, summary: "boom", exitCode: 1 }));
+
+		// The failure must arrive immediately, and the held success must be
+		// flushed ahead of it rather than waiting on the debounce timer.
+		assert.equal(sent.length, 2);
+		assert.match((sent[0]!.message as { content: string }).content, /Background task completed: \*\*ok-1\*\*/);
+		assert.match((sent[1]!.message as { content: string }).content, /Background task failed: \*\*fail-1\*\*/);
+
+		// No deferred emission should arrive later.
+		clock.advance(1000);
+		assert.equal(sent.length, 2);
+	});
+
+	it("groups sibling successes into a single notification after the debounce window", () => {
+		const clock = createFakeClock();
+		const { events, sent } = createBatchingPi(clock);
+
+		events.emit(SUBAGENT_ASYNC_COMPLETE_EVENT, completionResult({ id: "g-1", agent: "alpha", summary: "alpha done", sessionId: "session-a" }));
+		events.emit(SUBAGENT_ASYNC_COMPLETE_EVENT, completionResult({ id: "g-2", agent: "beta", summary: "beta done", sessionId: "session-a" }));
+		events.emit(SUBAGENT_ASYNC_COMPLETE_EVENT, completionResult({ id: "g-3", agent: "gamma", summary: "gamma done", sessionId: "session-a" }));
+		assert.equal(sent.length, 0);
+
+		clock.advance(150);
+		assert.equal(sent.length, 1);
+		const content = (sent[0]!.message as { content: string }).content;
+		assert.match(content, /^Background tasks completed \(3\): \*\*alpha\*\*, \*\*beta\*\*, \*\*gamma\*\*/);
+		assert.match(content, /1\. alpha\nalpha done/);
+		assert.match(content, /3\. gamma\ngamma done/);
+		assert.deepEqual(sent[0]!.options, { triggerTurn: true });
+	});
+
+	it("ignores successes from other sessions instead of grouping them", () => {
+		const clock = createFakeClock();
+		const { events, sent } = createBatchingPi(clock, "session-a");
+
+		events.emit(SUBAGENT_ASYNC_COMPLETE_EVENT, completionResult({ id: "s-1", agent: "alpha", summary: "alpha done", sessionId: "session-a" }));
+		events.emit(SUBAGENT_ASYNC_COMPLETE_EVENT, completionResult({ id: "s-2", agent: "beta", summary: "beta done", sessionId: "session-b" }));
+		clock.advance(150);
+
+		assert.equal(sent.length, 1);
+		assert.match((sent[0]!.message as { content: string }).content, /^Background task completed: \*\*alpha\*\*/);
+		assert.doesNotMatch((sent[0]!.message as { content: string }).content, /beta done/);
+	});
+
+	it("does not let another session failure flush held successes", () => {
+		const clock = createFakeClock();
+		const { events, sent } = createBatchingPi(clock, "session-a");
+
+		events.emit(SUBAGENT_ASYNC_COMPLETE_EVENT, completionResult({ id: "held-a-1", agent: "alpha", summary: "alpha done", sessionId: "session-a" }));
+		events.emit(SUBAGENT_ASYNC_COMPLETE_EVENT, completionResult({ id: "fail-b-1", agent: "beta", success: false, summary: "boom", exitCode: 1, sessionId: "session-b" }));
+		assert.equal(sent.length, 0);
+
+		clock.advance(150);
+		assert.equal(sent.length, 1);
+		assert.match((sent[0]!.message as { content: string }).content, /^Background task completed: \*\*alpha\*\*/);
+		assert.doesNotMatch((sent[0]!.message as { content: string }).content, /boom/);
+	});
+});
+
+describe("completion formatting helpers", () => {
+	it("formatSingleCompletion mirrors the in-handler single message shape", () => {
+		const content = formatSingleCompletion({
+			agent: "worker",
+			status: "completed",
+			taskInfo: " (2/3)",
+			resultPreview: "Done",
+			sessionLabel: "Session file",
+			sessionValue: "/tmp/session.jsonl",
+		});
+		assert.equal(content, "Background task completed: **worker** (2/3)\n\nDone\n\nSession file: /tmp/session.jsonl");
+	});
+
+	it("formatGroupedCompletion lists each agent with its summary and session", () => {
+		const content = formatGroupedCompletion([
+			{ agent: "alpha", status: "completed", resultPreview: "alpha done" },
+			{ agent: "beta", status: "completed", taskInfo: " (1/2)", resultPreview: "", sessionLabel: "Session", sessionValue: "https://share/abc" },
+		]);
+		assert.equal(
+			content,
+			"Background tasks completed (2): **alpha**, **beta** (1/2)\n\n"
+			+ "1. alpha\nalpha done\n\n"
+			+ "2. beta (1/2)\n(no output)\nSession: https://share/abc",
+		);
+	});
+
+	it("buildCompletionDetails derives paused status from state and summary", () => {
+		assert.equal(buildCompletionDetails({ id: "x", agent: "w", success: false, state: "paused", summary: "Paused after interrupt.", timestamp: 1 }).status, "paused");
+		assert.equal(buildCompletionDetails({ id: "x", agent: "w", success: false, summary: "boom", exitCode: 1, timestamp: 1 }).status, "failed");
+		assert.equal(buildCompletionDetails({ id: "x", agent: "w", success: true, summary: "ok", exitCode: 0, timestamp: 1 }).status, "completed");
+	});
+
+	it("buildCompletionDetails falls back to the unknown agent label", () => {
+		const details: SubagentNotifyDetails = buildCompletionDetails({ id: "x", agent: null, success: true, summary: "ok", timestamp: 1 });
+		assert.equal(details.agent, "unknown");
+		assert.equal(details.status, "completed");
+	});
+});