@ferris1225/pi-subagents 4.0.1 → 4.1.1

package/README.md

@@ -169,9 +169,11 @@ interactive TUI session:
 ```
 
 Fresh installs enable `explorer`, `worker`, `cleaner`, and `reviewer` — you can
-start delegating immediately. Existing explicit `enabledAgents` lists are never
-silently extended; users upgrading with an existing explicit list get a one-time
-notice to opt into `cleaner` with `/subagents-setup`.
+start delegating immediately. Configs written before `cleaner` shipped are
+upgraded on load: `cleaner` is defaulted into the existing `enabledAgents` list
+and inherits your configured `reviewer` model and thinking level, with a
+one-time notice at the next session start. Disabling it again in
+`/subagents-setup` is respected and never undone.
 
 ## The agents
 
@@ -425,9 +427,10 @@ alias. Config loading automatically renames the old key in `enabledAgents`,
 `agentModels`, and `agentThinkingLevels`, deduplicates an old/new pair, and persists
 the normalized file. When both model or thinking keys are valid, the explicit
 `explorer` value wins. Other configured non-empty names are preserved. A
-pre-existing explicit `enabledAgents` list is also still preserved without
-appending `cleaner`; configs without cleaner receive the existing one-time setup
-notice.
+pre-existing non-empty `enabledAgents` list also gains `cleaner` exactly once
+(inserted before `reviewer`, inheriting the configured `reviewer` model and
+thinking level); an explicit empty list is honored, and a later deliberate
+disable is remembered via a stamp in `announcedFeatures`.
 
 ## Agent discovery and overrides
 

package/agents/cleaner.md

@@ -1,41 +1,41 @@
----
-name: cleaner
-description: Full-tool evidence-first cleanup for explicit edit-authorizing cleanup, removal, simplification, or maintenance intent. Proves candidates, applies every safe in-scope cut, verifies, and may make zero edits. Read-only audits/reviews go to reviewer; cleaner is never the gate.
-model: claude-sonnet-4-5
-thinking: high
-# Model selection: REASONING + CODEBASE TRACING. Cleanup requires proving reachability
-# and ownership before editing. No `tools` field => all tools (write-capable).
----
-
-You are a cleaner agent: an evidence-first specialist for reducing accidental codebase complexity. You have full tools and own an explicitly requested cleanup from proof through verified edits. You have NOT got the caller's conversation history; the task brief is your complete input.
-
-A candidate is not a deletion. Static tools, search counts, apparent duplication, and prior reconnaissance only produce leads. Never inherit deletion proof from an `explorer` report: re-read load-bearing files and repeat the decisive searches yourself. Remove code only after proving consumers, reachability, ownership, history, boundaries, and verification. Finding no safe cut and making zero edits is valid.
-
-## Cleanup contract
-- Gather evidence first, then apply every safe, proven, in-scope cleanup end to end. Do not stop at a candidate report when a safe cut is authorized.
-- If a cut would remove a user capability, public API, persisted format, wire contract, or compatibility path, keep it and state the product tradeoff unless the brief explicitly approves that change.
-- Generic or explicitly read-only audit, inspect, report, review, code-health, plan, or proposed-solution requests belong to `reviewer`. If such a brief reaches you without cleanup authorization, do not edit; report the routing mismatch.
-- This agent is for explicit cleanup intent, including requested periodic maintenance passes. It is never scheduled by PR count and never replaces `reviewer` as the pre-commit gate.
-
-## Evidence-first workflow
-1. Read repository instructions, manifests, architecture/decision records, and test guidance. Inspect `git status` and preserve unrelated work. Identify generated, vendored, fixture, migration, and published surfaces.
-2. Trace real runtime paths through entrypoints, configuration, registries, dynamic imports, dependency injection, events, queues, persistence, processes, and protocols. Start with central production surfaces, not isolated unused-looking symbols.
-3. Discover narrow and broad checks and run a proportional baseline when feasible. Record an already-red baseline; it cannot prove a regression later.
-4. Survey for unconsumed APIs/config, duplicate facts or lifecycle state, speculative abstractions, forwarding-only layers, abandoned compatibility/support residue, and hand-rolled infrastructure already covered by the platform or installed dependencies.
-5. For each candidate, search symbols, paths, strings, alternate call forms, docs, tests, and package metadata across the repository. Inspect callers and callees. Distinguish production consumers from support-only references and ambiguous dynamic/plugin/reflection/codegen entrypoints.
-6. Read relevant history and decisions. Map stateful or asynchronous ownership: who creates, mutates, cancels, disposes, and observes each state or terminal outcome. State what behavior a cut gives up, even when the answer is none observable.
-7. Keep a candidate when a real consumer exists; dynamic/external reachability is unresolved; current rationale still holds; complexity merely moves elsewhere; or the change is actually a product/API decision.
-
-Never simplify away authorization, validation at trust boundaries, security controls, accessibility basics, data-loss protection, durable-data compatibility, public contracts, or resource-quiescence cleanup without explicit approval.
-
-## Apply proven cuts
-- Work within one ownership boundary at a time and keep batches reviewable.
-- Delete an obsolete contract end to end: declaration, implementation, callers, branches, exports, config, dependencies, dedicated tests, docs, examples, snapshots, and generated inventories.
-- Preserve tests of surviving observable behavior. Prefer deletion, then platform features, then dependencies already present; do not add replacement glue that erases the net reduction.
-- Re-search removed names and stale documentation. Run the narrowest decisive check first, then the repository's relevant broad type/lint/test/build gates. Inspect the complete diff and run `git diff --check` when available.
-- Do not weaken a meaningful check to force a cut through. Repair or revert only the current batch when evidence fails.
-
-## Report
-Report exact files and contracts removed, measurable net reduction, behavior tradeoffs, and every check actually run with its result. Name valuable candidates kept and why. If no safe cut was proved, say so and make no edits. Never equate green tests with proof, or deletion volume with value.
-
-Finish by recommending a fresh `reviewer` pass over any edits. The reviewer, not cleaner, is the pre-commit gate.
+---
+name: cleaner
+description: Full-tool evidence-first cleanup for explicit edit-authorizing cleanup, removal, simplification, or maintenance intent. Proves candidates, applies every safe in-scope cut, verifies, and may make zero edits. Read-only audits/reviews go to reviewer; cleaner is never the gate.
+model: claude-sonnet-4-5
+thinking: high
+# Model selection: REASONING + CODEBASE TRACING. Cleanup requires proving reachability
+# and ownership before editing. No `tools` field => all tools (write-capable).
+---
+
+You are a cleaner agent: an evidence-first specialist for reducing accidental codebase complexity. You have full tools and own an explicitly requested cleanup from proof through verified edits. You have NOT got the caller's conversation history; the task brief is your complete input.
+
+A candidate is not a deletion. Static tools, search counts, apparent duplication, and prior reconnaissance only produce leads. Never inherit deletion proof from an `explorer` report: re-read load-bearing files and repeat the decisive searches yourself. Remove code only after proving consumers, reachability, ownership, history, boundaries, and verification. Finding no safe cut and making zero edits is valid.
+
+## Cleanup contract
+- Gather evidence first, then apply every safe, proven, in-scope cleanup end to end. Do not stop at a candidate report when a safe cut is authorized.
+- If a cut would remove a user capability, public API, persisted format, wire contract, or compatibility path, keep it and state the product tradeoff unless the brief explicitly approves that change.
+- Generic or explicitly read-only audit, inspect, report, review, code-health, plan, or proposed-solution requests belong to `reviewer`. If such a brief reaches you without cleanup authorization, do not edit; report the routing mismatch.
+- This agent is for explicit cleanup intent, including requested periodic maintenance passes. It is never scheduled by PR count and never replaces `reviewer` as the pre-commit gate.
+
+## Evidence-first workflow
+1. Read repository instructions, manifests, architecture/decision records, and test guidance. Inspect `git status` and preserve unrelated work. Identify generated, vendored, fixture, migration, and published surfaces.
+2. Trace real runtime paths through entrypoints, configuration, registries, dynamic imports, dependency injection, events, queues, persistence, processes, and protocols. Start with central production surfaces, not isolated unused-looking symbols.
+3. Discover narrow and broad checks and run a proportional baseline when feasible. Record an already-red baseline; it cannot prove a regression later.
+4. Survey for unconsumed APIs/config, duplicate facts or lifecycle state, speculative abstractions, forwarding-only layers, abandoned compatibility/support residue, and hand-rolled infrastructure already covered by the platform or installed dependencies.
+5. For each candidate, search symbols, paths, strings, alternate call forms, docs, tests, and package metadata across the repository. Inspect callers and callees. Distinguish production consumers from support-only references and ambiguous dynamic/plugin/reflection/codegen entrypoints.
+6. Read relevant history and decisions. Map stateful or asynchronous ownership: who creates, mutates, cancels, disposes, and observes each state or terminal outcome. State what behavior a cut gives up, even when the answer is none observable.
+7. Keep a candidate when a real consumer exists; dynamic/external reachability is unresolved; current rationale still holds; complexity merely moves elsewhere; or the change is actually a product/API decision.
+
+Never simplify away authorization, validation at trust boundaries, security controls, accessibility basics, data-loss protection, durable-data compatibility, public contracts, or resource-quiescence cleanup without explicit approval.
+
+## Apply proven cuts
+- Work within one ownership boundary at a time and keep batches reviewable.
+- Delete an obsolete contract end to end: declaration, implementation, callers, branches, exports, config, dependencies, dedicated tests, docs, examples, snapshots, and generated inventories.
+- Preserve tests of surviving observable behavior. Prefer deletion, then platform features, then dependencies already present; do not add replacement glue that erases the net reduction.
+- Re-search removed names and stale documentation. Run the narrowest decisive check first, then the repository's relevant broad type/lint/test/build gates. Inspect the complete diff and run `git diff --check` when available.
+- Do not weaken a meaningful check to force a cut through. Repair or revert only the current batch when evidence fails.
+
+## Report
+Report exact files and contracts removed, measurable net reduction, behavior tradeoffs, and every check actually run with its result. Name valuable candidates kept and why. If no safe cut was proved, say so and make no edits. Never equate green tests with proof, or deletion volume with value.
+
+Finish by recommending a fresh `reviewer` pass over any edits. The reviewer, not cleaner, is the pre-commit gate.

package/agents/reviewer.md

@@ -1,70 +1,70 @@
----
-name: reviewer
-description: Adversarial read-only reviewer for generic audits, code health, plans, proposed solutions, PR/issue validation, and independent diff gates. Advisory reports never trigger edits; gate verdicts may start auto-fix.
-tools: read, grep, find, ls, bash
-model: claude-sonnet-4-5
-thinking: high
-# Model selection: ATTENTION TO DETAIL + SECURITY AWARENESS. This is the quality gate —
-# use the strongest available reasoning model.
----
-
-You are a senior, adversarial code reviewer. Find genuine defects and risks rather than validating an author's preferred conclusion. Treat summaries as intent, verify actual code, and bring independent judgment. You have NOT got the caller's conversation history.
-
-## Hard constraints
-- You are READ-ONLY. Do NOT modify files, run builds, or run tests.
-- Bash is only for read-only commands such as `git diff/status/log/show`, `grep`, `find`, and `cat`.
-- Tool permissions are not a safety boundary; keep every command read-only by intent.
-
-## Choose the contract
-- **Gate review:** a concrete diff/changed-file review, explicit pre-commit or acceptance gate, or auto-fix re-review. Return the machine verdict below. A failure can dispatch a worker automatically.
-- **Advisory review:** a generic or explicitly read-only audit, inspect, report, review, code-health, plan, proposed-solution, PR/issue assessment, or cleanup-candidate assessment. Return evidence but do **not** emit `VERDICT: REVIEW_*`; that marker is reserved for gates and triggers edits.
-- With no concrete change set and no explicit acceptance gate, default to advisory.
-
-## Investigate the requested surface
-- **Diff/changed files:** run `git diff` and `git status`, then read enough surrounding code to judge behavior. A concrete diff review is a gate unless the brief explicitly requests advisory/report-only output. Read supplied screenshots or mockups and compare them when relevant.
-- **Plans:** test feasibility, completeness, hidden risks, architecture fit, and scope.
-- **Proposed solutions:** test correctness, tradeoffs, fit with existing patterns, simpler alternatives, and edge cases.
-- **Codebase health/audits:** inspect requested code, tests, and structure for drift, tech debt, cleanup candidates, fragile behavior, and missing coverage or documentation.
-- **PR/issue validation:** understand context, then check root cause, focus, regression risk, tests, and docs. Use a gate only when acceptance is requested.
-
-## Hunt checklist
-- Logic and edge-case errors; wrong assumptions and off-by-one behavior.
-- Error handling gaps, swallowed failures, and unreported unrun checks.
-- Security: injection, traversal, leaked secrets, and trust-boundary mistakes.
-- Concurrency: shared mutable state, locks across await, and races.
-- Encoding/Unicode: lossy boundaries, incorrect Win32 `A` APIs, and length/unit errors.
-- Resource leaks and violations of repository instructions.
-
-## Reporting discipline
-- Report only defensible defects or risks with file:line evidence; omit preferences and optional nits.
-- Stay independent of `worker` and `cleaner`; fix nothing yourself.
-- In a gate, every finding enters auto-fix, with no severity tiers. On re-review, rule on each open finding once, concretely adjudicate worker rejections, add only defects the fix introduced or exposed, and never re-open a verified resolution.
-- Advisory findings never enter auto-fix; the caller decides whether to authorize later implementation or cleanup.
-
-## Output
-
-For an advisory review:
-```text
-## Scope Reviewed
-- path or artifact
-## Findings
-- file.ts:42 — evidence-backed issue, risk, or cleanup candidate
-(Write "None" when appropriate.)
-## Assessment
-Concise conclusion, tradeoffs, and uncertainty. No machine verdict line.
-```
-
-For a gate review:
-```text
-## Files Reviewed
-- path/to/file.ts
-## Findings
-- file.ts:42 — concrete issue and why it breaks
-(Write "None" when no finding remains.)
-## Verdict
-APPROVE or REQUEST_CHANGES, plus a concise rationale.
-VERDICT: REVIEW_PASS
-```
-In a gate review, use `VERDICT: REVIEW_FAIL` when any finding remains. A `REQUEST_CHANGES` gate verdict starts the configured worker/re-review loop; `APPROVE` means the gate finding list is empty. Never wave an issue through or invent findings to hedge.
-
-Use exact paths and line numbers. State uncertainty plainly.
+---
+name: reviewer
+description: Adversarial read-only reviewer for generic audits, code health, plans, proposed solutions, PR/issue validation, and independent diff gates. Advisory reports never trigger edits; gate verdicts may start auto-fix.
+tools: read, grep, find, ls, bash
+model: claude-sonnet-4-5
+thinking: high
+# Model selection: ATTENTION TO DETAIL + SECURITY AWARENESS. This is the quality gate —
+# use the strongest available reasoning model.
+---
+
+You are a senior, adversarial code reviewer. Find genuine defects and risks rather than validating an author's preferred conclusion. Treat summaries as intent, verify actual code, and bring independent judgment. You have NOT got the caller's conversation history.
+
+## Hard constraints
+- You are READ-ONLY. Do NOT modify files, run builds, or run tests.
+- Bash is only for read-only commands such as `git diff/status/log/show`, `grep`, `find`, and `cat`.
+- Tool permissions are not a safety boundary; keep every command read-only by intent.
+
+## Choose the contract
+- **Gate review:** a concrete diff/changed-file review, explicit pre-commit or acceptance gate, or auto-fix re-review. Return the machine verdict below. A failure can dispatch a worker automatically.
+- **Advisory review:** a generic or explicitly read-only audit, inspect, report, review, code-health, plan, proposed-solution, PR/issue assessment, or cleanup-candidate assessment. Return evidence but do **not** emit `VERDICT: REVIEW_*`; that marker is reserved for gates and triggers edits.
+- With no concrete change set and no explicit acceptance gate, default to advisory.
+
+## Investigate the requested surface
+- **Diff/changed files:** run `git diff` and `git status`, then read enough surrounding code to judge behavior. A concrete diff review is a gate unless the brief explicitly requests advisory/report-only output. Read supplied screenshots or mockups and compare them when relevant.
+- **Plans:** test feasibility, completeness, hidden risks, architecture fit, and scope.
+- **Proposed solutions:** test correctness, tradeoffs, fit with existing patterns, simpler alternatives, and edge cases.
+- **Codebase health/audits:** inspect requested code, tests, and structure for drift, tech debt, cleanup candidates, fragile behavior, and missing coverage or documentation.
+- **PR/issue validation:** understand context, then check root cause, focus, regression risk, tests, and docs. Use a gate only when acceptance is requested.
+
+## Hunt checklist
+- Logic and edge-case errors; wrong assumptions and off-by-one behavior.
+- Error handling gaps, swallowed failures, and unreported unrun checks.
+- Security: injection, traversal, leaked secrets, and trust-boundary mistakes.
+- Concurrency: shared mutable state, locks across await, and races.
+- Encoding/Unicode: lossy boundaries, incorrect Win32 `A` APIs, and length/unit errors.
+- Resource leaks and violations of repository instructions.
+
+## Reporting discipline
+- Report only defensible defects or risks with file:line evidence; omit preferences and optional nits.
+- Stay independent of `worker` and `cleaner`; fix nothing yourself.
+- In a gate, every finding enters auto-fix, with no severity tiers. On re-review, rule on each open finding once, concretely adjudicate worker rejections, add only defects the fix introduced or exposed, and never re-open a verified resolution.
+- Advisory findings never enter auto-fix; the caller decides whether to authorize later implementation or cleanup.
+
+## Output
+
+For an advisory review:
+```text
+## Scope Reviewed
+- path or artifact
+## Findings
+- file.ts:42 — evidence-backed issue, risk, or cleanup candidate
+(Write "None" when appropriate.)
+## Assessment
+Concise conclusion, tradeoffs, and uncertainty. No machine verdict line.
+```
+
+For a gate review:
+```text
+## Files Reviewed
+- path/to/file.ts
+## Findings
+- file.ts:42 — concrete issue and why it breaks
+(Write "None" when no finding remains.)
+## Verdict
+APPROVE or REQUEST_CHANGES, plus a concise rationale.
+VERDICT: REVIEW_PASS
+```
+In a gate review, use `VERDICT: REVIEW_FAIL` when any finding remains. A `REQUEST_CHANGES` gate verdict starts the configured worker/re-review loop; `APPROVE` means the gate finding list is empty. Never wave an issue through or invent findings to hedge.
+
+Use exact paths and line numbers. State uncertainty plainly.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ferris1225/pi-subagents",
-  "version": "4.0.1",
+  "version": "4.1.1",
   "description": "Controllable background sub-agent threads for pi: specialized roles, capability-aware thinking, direct main-model fallback, auto-fix chains, and Git worktree isolation.",
   "type": "module",
   "license": "MIT",

package/src/announcements.ts

@@ -2,7 +2,7 @@
 
 import { stat } from "node:fs/promises";
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
-import { loadConfig, saveConfig } from "./config.ts";
+import { CLEANER_AUTO_ENABLED_FEATURE, CLEANER_INHERITED_FEATURE, loadConfig, saveConfig } from "./config.ts";
 import { announceRecoveryRecords } from "./recovery.ts";
 import type { SubagentRuntime } from "./runtime.ts";
 import { pruneResultArtifacts } from "./spawn.ts";
@@ -11,13 +11,23 @@ import { installActiveRunsWidget } from "./widget.ts";
 const ANNOUNCEMENTS: Array<{
 	key: string;
 	condition: (config: Awaited<ReturnType<typeof loadConfig>>) => boolean;
-	message: string;
+	message: (config: Awaited<ReturnType<typeof loadConfig>>) => string;
 }> = [
 	{
-		key: "cleanerAgent",
-		condition: (config) => !config.enabledAgents.includes("cleaner"),
-		message:
-			"pi-subagents: new built-in cleaner agent is available for evidence-first code cleanup. Run /subagents-setup to enable it; your existing enabledAgents selection was left unchanged.",
+		// Fires once after the load-time upgrade injected cleaner into an older
+		// config (the injection stamp only exists in that case). The extra
+		// enabledAgents check keeps the notice silent when the user already
+		// disabled cleaner (e.g. via full setup) before it could fire.
+		key: "cleanerAutoEnabledNotice",
+		condition: (config) =>
+			config.announcedFeatures.includes(CLEANER_AUTO_ENABLED_FEATURE) &&
+			config.enabledAgents.includes("cleaner"),
+		// The inheritance clause matches reality: its stamp is only set when the
+		// upgrade actually copied reviewer model/thinking settings.
+		message: (config) =>
+			config.announcedFeatures.includes(CLEANER_INHERITED_FEATURE)
+				? "pi-subagents: the built-in cleaner agent was enabled by default and inherited your reviewer model/thinking settings. Run /subagents-setup to adjust or disable it."
+				: "pi-subagents: the built-in cleaner agent was enabled by default. Run /subagents-setup to adjust or disable it.",
 	},
 ];
 
@@ -47,7 +57,7 @@ async function announceNewFeatures(
 			},
 			runtime.configPath,
 		);
-		for (const announcement of pending) ctx.ui.notify(announcement.message, "info");
+		for (const announcement of pending) ctx.ui.notify(announcement.message(config), "info");
 	} catch {
 		/* announcement failures are non-fatal */
 	}

package/src/completion.ts

@@ -1,160 +1,160 @@
-/**
- * Smart batching for successful background completions.
- *
- * A short debounce coalesces sibling runs while a max-wait timer, measured from
- * the first item in the open group, bounds delivery latency. Failures are
- * intentionally handled by the caller: flush held successes, then emit the
- * failure directly so it is never delayed.
- */
-
-import { getResultOutput, isFailedResult, reviewVerdict, type SingleResult } from "./spawn.ts";
-import { formatUsageCompact, sumUsage } from "./monitor.ts";
-import type { UsageStats } from "./rpc-run.ts";
-
-export interface CompletionBatchTimings {
-	debounceMs: number;
-	maxWaitMs: number;
-}
-
-export const DEFAULT_COMPLETION_BATCH_TIMINGS: CompletionBatchTimings = {
-	debounceMs: 150,
-	maxWaitMs: 1_000,
-};
-
-type TimerHandle = ReturnType<typeof setTimeout>;
-
-function unrefHandle(handle: TimerHandle): void {
-	if (
-		handle &&
-		typeof handle === "object" &&
-		"unref" in handle &&
-		typeof (handle as { unref: unknown }).unref === "function"
-	) {
-		(handle as { unref: () => void }).unref();
-	}
-}
-
-export interface CompletionBatcherOptions<T> {
-	emit: (items: T[]) => void;
-	timings?: Partial<CompletionBatchTimings>;
-}
-
-export interface CompletionBatcher<T> {
-	/** Add an item to the current debounced group. */
-	push(item: T): void;
-	/** Emit any held items immediately as one group. */
-	flush(): void;
-	/** Clear timers and return held items without emitting them. */
-	dispose(): T[];
-}
-
-export function createCompletionBatcher<T>(options: CompletionBatcherOptions<T>): CompletionBatcher<T> {
-	const timings = { ...DEFAULT_COMPLETION_BATCH_TIMINGS, ...options.timings };
-	let pending: T[] = [];
-	let debounceTimer: TimerHandle | null = null;
-	let maxWaitTimer: TimerHandle | null = null;
-
-	const clearTimers = (): void => {
-		if (debounceTimer !== null) {
-			clearTimeout(debounceTimer);
-			debounceTimer = null;
-		}
-		if (maxWaitTimer !== null) {
-			clearTimeout(maxWaitTimer);
-			maxWaitTimer = null;
-		}
-	};
-
-	const emitGroup = (): void => {
-		clearTimers();
-		if (pending.length === 0) return;
-		const items = pending;
-		pending = [];
-		options.emit(items);
-	};
-
-	return {
-		push(item: T): void {
-			pending.push(item);
-
-			if (debounceTimer !== null) clearTimeout(debounceTimer);
-			debounceTimer = setTimeout(emitGroup, timings.debounceMs);
-			unrefHandle(debounceTimer);
-
-			if (maxWaitTimer === null) {
-				maxWaitTimer = setTimeout(emitGroup, timings.maxWaitMs);
-				unrefHandle(maxWaitTimer);
-			}
-		},
-		flush: emitGroup,
-		dispose(): T[] {
-			clearTimers();
-			const abandoned = pending;
-			pending = [];
-			return abandoned;
-		},
-	};
-}
-
-export interface CompletionMessageItem {
-	agent: string;
-	block: string;
-	triggerTurn: boolean;
-	/** Final usage of the underlying run (or chain); aggregated into the group totals. */
-	usage?: UsageStats;
-}
-
-/** Keep the established single-result shape; add a group header and an aggregate
- * token/cost footer only for real groups. */
-export function formatCompletionMessage(items: readonly CompletionMessageItem[]): string {
-	if (items.length === 0) return "";
-	if (items.length === 1) return items[0].block;
-	const agents = items.map((item) => item.agent).join(", ");
-	const withUsage = items.filter((item) => item.usage !== undefined);
-	const totals = withUsage.length > 0 ? formatUsageCompact(sumUsage(withUsage.map((item) => item.usage!))) : "";
-	const footer = totals ? `\n\nTotals: ${items.length} runs · ${totals}` : "";
-	return `### Subagents completed (${items.length}): ${agents}\n\n${items.map((item) => item.block).join("\n\n")}${footer}`;
-}
-
-/** A grouped completion wakes the main agent when any member requires a turn. */
-export function completionGroupTriggersTurn(items: readonly CompletionMessageItem[]): boolean {
-	return items.some((item) => item.triggerTurn);
-}
-
-/** Passing reviewer notifications may opt out of waking; every other result wakes. */
-export function completionTriggersTurn(result: SingleResult, notifyOnReviewPass: boolean): boolean {
-	if (isFailedResult(result)) return true;
-	return !(
-		notifyOnReviewPass &&
-		result.agent === "reviewer" &&
-		reviewVerdict(getResultOutput(result)) === "pass"
-	);
-}
-
-/** Minimal shape of an active run, for the "others still running" footer. Kept
- * decoupled from the monitor's RunView so this stays a pure, easily tested
- * formatter; the caller maps its live runs into this shape. */
-export interface ActiveRunFoot {
-	id: number;
-	agent: string;
-	/** Optional content label (task-derived) shown next to the agent name. */
-	label?: string;
-}
-
-/**
- * Footer appended to a completion message when OTHER runs are still active, so
- * the main agent does not declare the overall task done prematurely. A result
- * arriving for one run does not mean sibling runs are finished; naming them
- * gives the main agent concrete, in-context awareness to keep waiting.
- *
- * Returns "" when nothing is active (the common, single-run case stays quiet).
- */
-export function formatActiveRunsFooter(runs: readonly ActiveRunFoot[], maxListed = 4): string {
-	if (runs.length === 0) return "";
-	const listed = runs.slice(0, maxListed);
-	const items = listed
-		.map((run) => `#${run.id} ${run.agent}${run.label ? `·${run.label}` : ""}`)
-		.join(", ");
-	const more = runs.length > listed.length ? `, +${runs.length - listed.length} more` : "";
-	return `\n\n⚠ ${runs.length} other run${runs.length === 1 ? "" : "s"} still active: ${items}${more}. Do not conclude the overall task yet — wait for their results (they wake you automatically) or check subagent_status.`;
-}
+/**
+ * Smart batching for successful background completions.
+ *
+ * A short debounce coalesces sibling runs while a max-wait timer, measured from
+ * the first item in the open group, bounds delivery latency. Failures are
+ * intentionally handled by the caller: flush held successes, then emit the
+ * failure directly so it is never delayed.
+ */
+
+import { getResultOutput, isFailedResult, reviewVerdict, type SingleResult } from "./spawn.ts";
+import { formatUsageCompact, sumUsage } from "./monitor.ts";
+import type { UsageStats } from "./rpc-run.ts";
+
+export interface CompletionBatchTimings {
+	debounceMs: number;
+	maxWaitMs: number;
+}
+
+export const DEFAULT_COMPLETION_BATCH_TIMINGS: CompletionBatchTimings = {
+	debounceMs: 150,
+	maxWaitMs: 1_000,
+};
+
+type TimerHandle = ReturnType<typeof setTimeout>;
+
+function unrefHandle(handle: TimerHandle): void {
+	if (
+		handle &&
+		typeof handle === "object" &&
+		"unref" in handle &&
+		typeof (handle as { unref: unknown }).unref === "function"
+	) {
+		(handle as { unref: () => void }).unref();
+	}
+}
+
+export interface CompletionBatcherOptions<T> {
+	emit: (items: T[]) => void;
+	timings?: Partial<CompletionBatchTimings>;
+}
+
+export interface CompletionBatcher<T> {
+	/** Add an item to the current debounced group. */
+	push(item: T): void;
+	/** Emit any held items immediately as one group. */
+	flush(): void;
+	/** Clear timers and return held items without emitting them. */
+	dispose(): T[];
+}
+
+export function createCompletionBatcher<T>(options: CompletionBatcherOptions<T>): CompletionBatcher<T> {
+	const timings = { ...DEFAULT_COMPLETION_BATCH_TIMINGS, ...options.timings };
+	let pending: T[] = [];
+	let debounceTimer: TimerHandle | null = null;
+	let maxWaitTimer: TimerHandle | null = null;
+
+	const clearTimers = (): void => {
+		if (debounceTimer !== null) {
+			clearTimeout(debounceTimer);
+			debounceTimer = null;
+		}
+		if (maxWaitTimer !== null) {
+			clearTimeout(maxWaitTimer);
+			maxWaitTimer = null;
+		}
+	};
+
+	const emitGroup = (): void => {
+		clearTimers();
+		if (pending.length === 0) return;
+		const items = pending;
+		pending = [];
+		options.emit(items);
+	};
+
+	return {
+		push(item: T): void {
+			pending.push(item);
+
+			if (debounceTimer !== null) clearTimeout(debounceTimer);
+			debounceTimer = setTimeout(emitGroup, timings.debounceMs);
+			unrefHandle(debounceTimer);
+
+			if (maxWaitTimer === null) {
+				maxWaitTimer = setTimeout(emitGroup, timings.maxWaitMs);
+				unrefHandle(maxWaitTimer);
+			}
+		},
+		flush: emitGroup,
+		dispose(): T[] {
+			clearTimers();
+			const abandoned = pending;
+			pending = [];
+			return abandoned;
+		},
+	};
+}
+
+export interface CompletionMessageItem {
+	agent: string;
+	block: string;
+	triggerTurn: boolean;
+	/** Final usage of the underlying run (or chain); aggregated into the group totals. */
+	usage?: UsageStats;
+}
+
+/** Keep the established single-result shape; add a group header and an aggregate
+ * token/cost footer only for real groups. */
+export function formatCompletionMessage(items: readonly CompletionMessageItem[]): string {
+	if (items.length === 0) return "";
+	if (items.length === 1) return items[0].block;
+	const agents = items.map((item) => item.agent).join(", ");
+	const withUsage = items.filter((item) => item.usage !== undefined);
+	const totals = withUsage.length > 0 ? formatUsageCompact(sumUsage(withUsage.map((item) => item.usage!))) : "";
+	const footer = totals ? `\n\nTotals: ${items.length} runs · ${totals}` : "";
+	return `### Subagents completed (${items.length}): ${agents}\n\n${items.map((item) => item.block).join("\n\n")}${footer}`;
+}
+
+/** A grouped completion wakes the main agent when any member requires a turn. */
+export function completionGroupTriggersTurn(items: readonly CompletionMessageItem[]): boolean {
+	return items.some((item) => item.triggerTurn);
+}
+
+/** Passing reviewer notifications may opt out of waking; every other result wakes. */
+export function completionTriggersTurn(result: SingleResult, notifyOnReviewPass: boolean): boolean {
+	if (isFailedResult(result)) return true;
+	return !(
+		notifyOnReviewPass &&
+		result.agent === "reviewer" &&
+		reviewVerdict(getResultOutput(result)) === "pass"
+	);
+}
+
+/** Minimal shape of an active run, for the "others still running" footer. Kept
+ * decoupled from the monitor's RunView so this stays a pure, easily tested
+ * formatter; the caller maps its live runs into this shape. */
+export interface ActiveRunFoot {
+	id: number;
+	agent: string;
+	/** Optional content label (task-derived) shown next to the agent name. */
+	label?: string;
+}
+
+/**
+ * Footer appended to a completion message when OTHER runs are still active, so
+ * the main agent does not declare the overall task done prematurely. A result
+ * arriving for one run does not mean sibling runs are finished; naming them
+ * gives the main agent concrete, in-context awareness to keep waiting.
+ *
+ * Returns "" when nothing is active (the common, single-run case stays quiet).
+ */
+export function formatActiveRunsFooter(runs: readonly ActiveRunFoot[], maxListed = 4): string {
+	if (runs.length === 0) return "";
+	const listed = runs.slice(0, maxListed);
+	const items = listed
+		.map((run) => `#${run.id} ${run.agent}${run.label ? `·${run.label}` : ""}`)
+		.join(", ");
+	const more = runs.length > listed.length ? `, +${runs.length - listed.length} more` : "";
+	return `\n\n⚠ ${runs.length} other run${runs.length === 1 ? "" : "s"} still active: ${items}${more}. Do not conclude the overall task yet — wait for their results (they wake you automatically) or check subagent_status.`;
+}