@ferris1225/pi-subagents 4.1.3 → 4.1.4

package/README.md

@@ -23,12 +23,12 @@ losing retained context.
 You
  └─ pi main agent
      ├─ explorer ─── maps the codebase
-     ├─ worker ───── implements ─┬─▶ documenter ─▶ reviewer
+     ├─ worker ───── implements ─┬─▶ reviewer ─▶ documenter
      ├─ cleaner ──── cleans up ──┘       (enabled roles only)
      ├─ documenter ─ synchronizes docs ─▶ reviewer
      └─ reviewer ─── advisory report (no VERDICT), or managed gate
-          ├─ REVIEW_PASS + documenter → documenter → fresh reviewer
-          └─ REVIEW_FAIL → worker → optional documenter → reviewer
+          ├─ REVIEW_PASS + documenter → final documentation sync
+          └─ REVIEW_FAIL → worker → reviewer (fix rounds) → final docs
 
 The stable parent run returns one final result when the complete workflow settles.
 ```
@@ -49,11 +49,12 @@ more of it.
   checkouts (worktrees) by default, then apply their changes back without
   touching your index.
 - **Documentation stops drifting.** Enabled `documenter` runs automatically
-  after successful workers/cleaners and before the final reviewer. It can also
-  run an explicitly requested whole-codebase maintenance pass.
-- **Review can close the loop.** A failed gate can automatically dispatch a worker,
-  run documentation sync, request another independent review, and repeat up to a
-  hard limit.
+  once after the review gate settles — after successful workers/cleaners or
+  fix rounds, never per fix round. It can also run an explicitly requested
+  whole-codebase maintenance pass.
+- **Review can close the loop.** A failed gate can automatically dispatch a
+  worker, request another independent review, and repeat up to a hard limit;
+  one final documentation sync follows the settled chain.
 - **Agents remain controllable.** Every run has a stable id and retained session,
   so you can change direction or continue later without starting from zero.
 - **Failures are handled, not hidden.** Model failures can hand the same session to
@@ -67,7 +68,7 @@ more of it.
 | One generic child role | Five focused engineering roles |
 | A one-shot prompt | Retained, steerable, resumable, forkable threads |
 | Concurrent writers in one checkout | Git worktree isolation for parallel workers |
-| A review report you must act on manually | Automatic writer → documenter → reviewer delivery and bounded fix rounds |
+| A review report you must act on manually | Automatic writer → reviewer → documenter delivery and bounded fix rounds |
 | Manual polling or follow-up | Automatic result delivery that resumes the main agent |
 | A hard failure when the selected model is unavailable | Direct handoff to the current main model |
 | Synchronized retries during startup contention | Extended jittered backoff that reduces retry collisions |
@@ -108,6 +109,25 @@ Compare screenshots/settings.png with design.png and report every visual mismatc
 The main agent decides when delegation is useful. You can also call the tools
 explicitly when you want exact control.
 
+## What changed in 4.1.4
+
+### Documentation sync moved after the review gate
+
+`documenter` now runs once at the end of a managed chain instead of before the
+reviewer and once per fix round:
+
+```text
+before: worker → documenter → reviewer → (worker → documenter → reviewer) × N
+after:  worker → reviewer → (worker → reviewer) × N → documenter
+```
+
+Code fixes no longer invalidate a docs pass written moments earlier, fix rounds
+stop paying for documenter runs and re-reviewing their churn, and a direct
+passing gate gets one final documentation sync instead of a second full review.
+Gate reviewers record documentation drift as non-gating `## Documentation notes`
+that the final documenter applies; when `documenter` is disabled, drift stays a
+normal gate finding. The sync is skipped when a chain ends on a failing gate.
+
 ## What changed in 4.1.2
 
 ### Documentation sync as a real workflow stage
@@ -225,22 +245,25 @@ subagent({
 });
 ```
 
-A gate reviewer ends with `REVIEW_PASS` or `REVIEW_FAIL`. A direct pass is not
-accepted as the final gate while `documenter` is enabled: runtime first syncs the
-actual pending diff, then starts a fresh reviewer. A failure uses the bounded loop:
+A gate reviewer ends with `REVIEW_PASS` or `REVIEW_FAIL`. A direct pass is
+final for the code: runtime runs the final documentation sync once (when
+`documenter` is enabled) and delivers. A failure uses the bounded loop:
 
 ```text
-reviewer → worker fixes every open finding → optional documenter sync → reviewer checks again → PASS/FAIL
+reviewer → worker fixes every open finding → reviewer checks again → … → final documentation sync
 ```
 
 Each step gets a fresh model context. The chain shares the same code state and
-passes every full reviewer, worker, and documenter report forward; it does not
-reuse one context window. Internal children bypass top-level lifecycle policy, so
-they cannot recursively start another chain.
+passes every full reviewer and worker report forward; it does not reuse one
+context window. Internal children bypass top-level lifecycle policy, so they
+cannot recursively start another chain. Gate reviewers keep documentation drift
+out of the verdict while `documenter` is enabled by recording it as
+`## Documentation notes` for the final documenter.
 
-`maxFixRounds` limits worker fix attempts only. Initial post-writer documentation
-and final review still run when it is `0`. Generic audits and read-only reviews
-are advisory: they omit `VERDICT`, remain read-only, and never trigger edits.
+`maxFixRounds` limits worker fix attempts only. The post-writer review gate and
+the final documentation sync still run when it is `0`. Generic audits and
+read-only reviews are advisory: they omit `VERDICT`, remain read-only, and
+never trigger edits.
 
 ### Clean up without guessing
 
@@ -258,7 +281,7 @@ axes genuinely differ, avoiding a generic abstraction that is worse than the
 duplication.
 
 ```text
-explicit cleanup request → cleaner applies proven cuts → documenter syncs docs → reviewer gates the diff
+explicit cleanup request → cleaner applies proven cuts → reviewer gates the diff → documenter syncs docs
 read-only cleanup audit   → reviewer reports candidates only
 ```
 
@@ -269,10 +292,11 @@ changes, and asking for cleanup does not reward speculative deletion.
 
 `documenter` has two deliberate launch paths.
 
-**For a pending worker or cleaner change**, enable the role. Runtime schedules it
-automatically against the actual diff before the final reviewer; do not dispatch
-a duplicate manual sync. If reviewer is disabled, documenter becomes the final
-managed stage. If documenter is disabled, reviewer follows the writer directly.
+**For a pending worker or cleaner change**, enable the role. Runtime schedules
+one final sync automatically against the actual diff after the review gate
+settles; do not dispatch a duplicate manual sync. If reviewer is disabled,
+documenter becomes the final managed stage directly after the writer. If
+documenter is disabled, reviewer follows the writer directly.
 
 **For an existing project**, explicitly authorize a broad maintenance pass:
 
@@ -308,11 +332,11 @@ filesystem isolation:
   not need a writable checkout.
 
 Worktree mode requires a Git repository with a committed `HEAD`. For an isolated
-writer, automatic documenter/reviewer children run inside that same worktree.
-Those isolated stages can still run in parallel; writer and documentation changes
-are integrated only after the final reviewer settles. Tracked, deleted, untracked,
-and binary changes are then carried back to the original checkout without staging
-or modifying the parent index.
+writer, automatic reviewer/documenter children run inside that same worktree.
+Those isolated stages can still run in parallel; writer, fix, and documentation
+changes are integrated only after the final managed stage settles. Tracked,
+deleted, untracked, and binary changes are then carried back to the original
+checkout without staging or modifying the parent index.
 
 Repository-lane discovery uses the Git top-level even in an empty repository, so
 root and nested paths share one lane before the first commit. Every shared
@@ -384,8 +408,7 @@ The active TUI widget shows queued and running work as a compact tree:
 ● reviewer workflow · review diff of src/cache.ts · 42s
   ├ ● worker · fix round 1 · src/cache.ts · claude-sonnet-4-5/high · 10s
   │    grep cacheKey
-  ├ ● documenter · docs round 1 · claude-haiku-4-5/low · 4s
-  └ ○ reviewer · re-review round 1 · claude-sonnet-4-5/high · 3s
+  └ ○ documenter · final documentation sync · claude-haiku-4-5/low · 3s
 ```
 
 A managed root keeps its original top-level role and workflow-wide elapsed
@@ -506,7 +529,7 @@ Configuration is stored at `~/.pi/agent/pi-subagents.json` and follows
 | `proactiveInjection` | Teach the main model when and how to delegate. Default `true`. |
 | `agentScope` | Discover `user`, `project`, or `both` agent directories. Default `user`. |
 | `maxConcurrency` | Running process limit and maximum tasks in one parallel call, from `1` to `16`. Default `4`. |
-| `maxFixRounds` | Maximum worker fixes after `REVIEW_FAIL`; each fix is followed by optional documenter and reviewer. `0` disables fixes but not initial post-writer docs/review. Default `2`. |
+| `maxFixRounds` | Maximum worker fixes after `REVIEW_FAIL`; each fix is re-reviewed by a reviewer, and one final documentation sync runs after the chain settles. `0` disables fixes but not the post-writer review gate or final docs. Default `2`. |
 | `idleTimeoutSec` | Seconds without RPC output before termination. `0` disables the watchdog. Default `90`. |
 
 Invalid values fall back safely. Older configs are normalized automatically. The

package/agents/cleaner.md

@@ -43,9 +43,9 @@ Never simplify away authorization, validation at trust boundaries, security cont
 - Do not weaken a meaningful check to force a cut through. Repair or revert only the current batch when evidence fails.
 
 ## Release boundary
-Never commit, push, publish, tag, release, or bump a package version. The parent workflow owns documentation synchronization, the final independent review, and every release action—even when repository instructions normally automate release after green checks.
+Never commit, push, publish, tag, release, or bump a package version. The parent workflow owns the independent review gate, the final documentation sync, and every release action—even when repository instructions normally automate release after green checks.
 
 ## Final response
 Return only the cleanup outcome: exact files/contracts removed or consolidated, measurable net reduction, behavior tradeoffs, and checks actually run. Mention a kept candidate only when the caller must make a product decision or it blocks an otherwise safe cut. If no safe cut was proved, say so and make no edits. Do not repeat the task brief or evidence-gathering chronology. Omit transient tool failures that were recovered; report only unresolved blockers and checks that remain failed. Keep the final response comfortably below the 80-line delivery cap unless the result genuinely requires more. Never equate green tests with proof, or deletion volume with value.
 
-The parent runtime automatically runs enabled `documenter` and `reviewer` stages after a successful top-level cleaner. Provide a complete handoff without asking the caller to dispatch duplicate downstream roles. Documenter is the last writer; reviewer is the final pre-commit gate.
+The parent runtime automatically runs the enabled `reviewer` gate and final `documenter` sync after a successful top-level cleaner. Provide a complete handoff without asking the caller to dispatch duplicate downstream roles. Reviewer gates the code; documenter is the final stage before delivery.

package/agents/documenter.md

@@ -1,6 +1,6 @@
 ---
 name: documenter
-description: "Write-capable documentation synchronizer with two modes: pre-commit diff sync before reviewer, or an explicitly requested whole-codebase comment/README/docs maintenance pass. May make zero edits and never changes runtime behavior."
+description: "Write-capable documentation synchronizer with two modes: final diff sync after the review gate settles, or an explicitly requested whole-codebase comment/README/docs maintenance pass. May make zero edits and never changes runtime behavior."
 tools: read, grep, find, ls, bash, edit, write
 # At launch, this shell slot follows the parent and parent-active plugin tools
 # are appended; the listed non-shell Pi built-ins remain the permission boundary.
@@ -15,7 +15,7 @@ You are a documenter agent: a write-capable specialist for keeping comments, REA
 You may edit documentation and comments, but you must never change runtime behavior to make the documentation true. Finding no drift and making zero edits is valid.
 
 ## Choose the mode
-- **Pre-commit diff sync (default for a concrete change):** run after implementation, cleanup, or an auto-fix worker and before the final read-only reviewer. Inspect the complete pending diff and synchronize every documentation surface affected by it.
+- **Pre-commit diff sync (default for a concrete change):** run after the code review gate settles — following implementation, cleanup, or auto-fix rounds — as the final managed stage before delivery. Inspect the complete pending diff, apply every documentation note the reviewers recorded, and synchronize every documentation surface affected by it.
 - **Whole-codebase maintenance:** run only when the user explicitly asks to refresh, re-document, or audit-and-update comments/README/docs across an existing project. Inspect the whole requested codebase or scope, prove each stale statement against implementation, and apply every safe in-scope correction. Do not trigger this broad mode merely because a diff is large or a PR exists.
 - If the brief does not explicitly authorize a whole-codebase pass, stay in diff mode. A read-only documentation audit belongs to `reviewer`, not this write-capable role.
 
@@ -43,4 +43,4 @@ Return only the documentation outcome:
 
 Do not repeat the task brief, diff walkthrough, generic root-cause explanation, or tool chronology. Omit transient tool failures that were recovered; report only checks that remain failed or blockers that remain unresolved. Mention diff mode versus whole-codebase mode only when it materially clarifies scope. Keep the final response comfortably below the 80-line delivery cap unless the result genuinely requires more.
 
-The parent runtime automatically launches a fresh read-only `reviewer` after a successful top-level documenter when that role is enabled. Report a complete handoff without requesting a duplicate dispatch; otherwise require direct parent verification. You are the last writer, never the final approver.
+A successful top-level `documenter` still gets a fresh read-only `reviewer` gate when that role is enabled; report a complete handoff without requesting a duplicate dispatch. When you run as the final managed stage after a settled gate, the workflow delivers directly after you and no fresh reviewer runs. You are always the last writer, never the code approver.

package/agents/reviewer.md

@@ -41,8 +41,8 @@ You are a senior, adversarial code reviewer. Find genuine defects and risks rath
 ## Reporting discipline
 - Report only defensible defects or risks with file:line evidence; omit preferences and optional nits.
 - Return only the review result. Do not repeat the task brief, summarize the implementation, narrate inspection/tool chronology, or explain a root cause when no finding depends on it. Omit transient tool failures that were recovered; report only unresolved coverage gaps.
-- Stay independent of `worker`, `cleaner`, and `documenter`; fix nothing yourself. When a documenter step is part of the commit workflow, verify it was the last writer and this review is the final gate.
-- In a gate, every finding enters auto-fix, with no severity tiers. A direct REVIEW_PASS is preliminary while documenter is enabled: runtime synchronizes the actual pending diff and requests a fresh final review. 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.
+- Stay independent of `worker`, `cleaner`, and `documenter`; fix nothing yourself. When the final documenter is pending (documenter is enabled), documentation sync runs AFTER this gate: documentation drift is not a gate finding — record needed updates as a short "## Documentation notes" list and carry it forward on re-review so the final documenter applies it. When documenter is disabled, documentation drift is a normal finding.
+- In a gate, every finding enters auto-fix, with no severity tiers. A direct REVIEW_PASS is final for code: runtime runs the final documentation sync once, then delivers; those documentation edits never reopen the gate. 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

package/agents/worker.md

@@ -28,13 +28,13 @@ Run the project's format/build/tests when they exist (e.g. `tsc --noEmit`, the t
 Return only the concrete outcome so the caller can verify it and, if needed, hand it to a `reviewer`. Do not repeat the task brief, plan, root-cause investigation, or tool chronology. Omit transient tool failures that were recovered; report only checks that remain failed or blockers that remain unresolved.
 
 ## Release boundary
-Never commit, push, publish, tag, release, or bump a package version. The parent workflow owns documentation synchronization, the final independent review, and every release action—even when repository instructions normally automate release after green checks.
+Never commit, push, publish, tag, release, or bump a package version. The parent workflow owns the independent review gate, the final documentation sync, and every release action—even when repository instructions normally automate release after green checks.
 
 ## Collaboration
 - You cannot dispatch sub-agents (children are leaf processes with no `subagent` tool). When the
   brief lacks context that needs broad code discovery, state concretely what an `explorer` should
   retrieve for the caller — do not guess.
-- The parent runtime automatically runs enabled `documenter` and `reviewer` stages after a successful top-level worker. Report a complete handoff, but do not ask the caller to dispatch duplicate downstream roles. Never treat your own verification as the final gate.
+- The parent runtime automatically runs the enabled `reviewer` gate and final `documenter` sync after a successful top-level worker. Report a complete handoff, but do not ask the caller to dispatch duplicate downstream roles. Never treat your own verification as the final gate.
 
 ## Output format
 ## Completed

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ferris1225/pi-subagents",
-  "version": "4.1.3",
+  "version": "4.1.4",
   "description": "A managed sub-agent team for pi: specialized roles, pre-commit documentation sync, retained threads, auto-fix chains, model fallback, and Git worktree isolation.",
   "type": "module",
   "license": "MIT",

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.`;
+}

package/src/config.ts

@@ -72,9 +72,9 @@ export const DEFAULT_MAX_CONCURRENCY = 4;
 /** Upper bound accepted for maxConcurrency (defensive clamp). */
 export const MAX_CONCURRENCY_LIMIT = 16;
 /**
- * Maximum worker fixes after REVIEW_FAIL. Each fix is followed by optional
- * documenter and reviewer; this cap does not suppress the initial post-writer
- * documentation/final-review workflow. 0 disables fixes. Default: 2.
+ * Maximum worker fixes after REVIEW_FAIL. Each fix is followed by a reviewer
+ * re-review; this cap does not suppress the post-writer review gate or the
+ * final documentation sync. 0 disables fixes. Default: 2.
  */
 export const DEFAULT_MAX_FIX_ROUNDS = 2;
 /** Upper bound accepted for maxFixRounds (defensive clamp). 0 disables the loop. */
@@ -116,8 +116,8 @@ export interface SubagentsConfig {
 	maxConcurrency: number;
 	/**
 	 * Maximum worker fixes after REVIEW_FAIL. Every fix receives the full review,
-	 * then enabled documenter/reviewer stages run. Initial post-writer docs/review
-	 * do not consume this budget. 0 disables fixes. Default: 2.
+	 * then a re-review runs; one final documentation sync follows the settled
+	 * chain and does not consume this budget. 0 disables fixes. Default: 2.
 	 */
 	maxFixRounds: number;
 	/**