@ferris1225/pi-subagents 2.0.3 → 2.2.0

package/README.md

@@ -32,15 +32,23 @@ The common quality loop now runs end to end without waking the main agent betwee
 steps:
 
 ```text
-reviewer (find blockers) → worker (fix) → reviewer (verify) → final PASS/FAIL
+reviewer (find issues) → worker (fix every finding) → reviewer (verify) → final PASS/FAIL
 ```
 
+Reviews use a single flat findings list — no severity triage. Every reported
+finding is fixed before the change is accepted, and each re-review converges on
+an open-finding set: the worker's explicit rejections are adjudicated once, only
+defects a fix round introduced or exposed are added, and resolved items never
+re-open. `maxFixRounds` stays the hard cap, so a chain always settles and wakes
+the main agent with the full picture.
+
 Cleanup stays a separate lifecycle: explicit cleanup intent can dispatch the
 evidence-first `cleaner`; any edits still go through the independent `reviewer`
 gate.
 
-Each chain is delivered as one concise completion group, while full per-run
-reports remain available through `subagent_status`. Its parent stays `running`
+Each chain is delivered as one concise completion group whose footer totals the
+aggregate token usage and cost of every included run, while full per-run reports
+remain available through `subagent_status`. Its parent stays `running`
 until the whole chain settles; completed internal rounds leave active status
 immediately, so no `done` row keeps accumulating elapsed time. Selected-to-main
 model handoffs keep the same retained context, and isolated parallel workers use
@@ -63,12 +71,16 @@ index.
   "go check" step. `subagent_wait` is a **non-blocking** in-turn lookup by default
   (pass `timeoutMs` to block); `subagent_status` inspects runs; `subagent_stop`
   cancels one and delivers its partial output.
-- **Active-only live widget** — each queued or running sub-agent gets one compact
-  width-aware primary line with task, effective model/thinking, and elapsed time;
-  current activity appears only when present on an indented second line:
+- **Active-only live widget, as a tree** — each queued or running sub-agent gets one compact
+  width-aware primary line with task, effective model/thinking, and elapsed time; current
+  activity appears only when present on an indented second line. Auto-fix rounds nest under
+  the triggering reviewer row that owns the chain, so it is always visible who dispatched
+  what; no run ids appear here — the tree and the task label identify each row:
   ```text
-  #7 cleaner · remove dead code in src/cache.ts · claude-sonnet-4-5/high · 42s
-    grep cacheKey
+  ● reviewer · review diff of src/foo.ts · claude-sonnet-4-5/high · 42s
+    ├ ● worker · fix round 1 · src/foo.ts · claude-sonnet-4-5/high · 10s
+    │    grep cacheKey
+    └ ○ reviewer · re-review round 1 · claude-sonnet-4-5/high · 3s
   ```
   Long tasks and activity paths truncate first (preserving a useful path tail when
   possible), groups have no blank rows, and settled/parked runs disappear immediately.
@@ -83,7 +95,10 @@ index.
 - **A quality gate that closes the loop** — when a reviewer returns `REVIEW_FAIL`,
   the extension dispatches a worker briefed with the concrete findings, then a
   re-review, up to `maxFixRounds` times — and only then wakes the main agent.
-  Every round stays in the triggering reviewer's cwd, and chains that target the
+  Every reported finding gets fixed (no severity triage), and re-reviews converge
+  on an open-finding set instead of ping-ponging: worker rejections are adjudicated
+  once, only defects the fix round introduced are added, and resolved items never
+  re-open. Every round stays in the triggering reviewer's cwd, and chains that target the
   same repository are serialized so shared-checkout edits cannot race.
 - **Direct fallback with real thinking capabilities** — each agent has at most
   one selected model. An unavailable selection, rate limit, invalid key, quota,
@@ -98,9 +113,9 @@ index.
   `subagent_control` can steer active work, retarget it after a stable abort,
   park/resume it under the same run id, or fork a parked/settled checkpoint into
   a new independent run. Concurrent resume calls are serialized.
-- **Concise but honest completions** — a clean process that contained failed tool
-  calls adds one short warning with its run id; individual errors stay out of the
-  main context and remain available through `subagent_status`. Actual process,
+- **Concise but honest completions** — group completions end with aggregate token
+  and cost totals across every included run; failed-tool diagnostics stay out of the
+  delivered message and remain one `subagent_status` call away. Actual process,
   model, and integration failures still surface as failures.
 - **Parallel fan-out with filesystem isolation** — independent tasks run up to a
   configurable limit (default 4). Parallel workers default to detached Git
@@ -123,8 +138,9 @@ an undifferentiated child-agent launcher:
   independent reviewer gate;
 - isolated, retained threads that can be steered, parked, resumed, retargeted, or
   forked under stable run ids;
-- the reviewer → worker auto-fix → reviewer loop;
-- compact failed-tool warnings with full diagnostics available by run id;
+- the reviewer → worker auto-fix → reviewer loop, fixing every finding under a
+  convergence contract with a hard round cap;
+- failed-tool diagnostics available by run id through `subagent_status`;
 - direct selected→main fallback plus capability-aware Auto thinking;
 - detached Git worktree isolation for parallel workers and opt-in write-capable
   cleaner runs.
@@ -226,7 +242,8 @@ because they may need to inspect the same images.
 ### Controlling and stopping
 
 Dispatch confirmations, tool result rows, and completion blocks all show the
-stable `#id`, so a thread remains directly controllable after its live UI is gone.
+stable `#id`, so a thread remains directly controllable after its live UI is gone
+(the widget itself identifies rows by tree position and task instead of ids).
 
 - `subagent_control` — `steer`, `retarget`, `park`, `resume`, or `fork` a logical
   thread by stable run id. Resume accepts an optional replacement objective;
@@ -317,7 +334,7 @@ direct-file settings.
 | `proactiveInjection` | Whether to add the delegation directive to the main system prompt. |
 | `agentScope` | `user`, `project`, or `both`; controls which user/project agent directories are discovered. |
 | `maxConcurrency` | Max sub-agent processes running at once (1–16, default 4), and the max tasks one parallel `subagent` call accepts. Extra work waits in the queue. |
-| `maxFixRounds` | Auto-fix rounds when a reviewer returns `REVIEW_FAIL` (default 2; `0` disables the loop). |
+| `maxFixRounds` | Auto-fix rounds when a reviewer returns `REVIEW_FAIL` (default 2; `0` disables the loop). Hard cap: the chain always settles, delivers its condensed summary, and wakes the main agent. |
 | `idleTimeoutSec` | Idle watchdog: a sub-agent whose stdout goes silent for this long is terminated; a selected model then hands to current main. `0` disables it. Default 90. |
 
 ### Model routing and thinking
@@ -429,12 +446,13 @@ npm run check
 npm test
 ```
 
-The source is modular: `dispatch.ts` (dispatch, controls, isolation, auto-fix),
+The source is modular: `dispatch.ts` (public dispatch contract + auto-fix),
+`thread-lifecycle.ts` (queued generations, resume/fork, and isolation settlement),
 `rpc-run.ts` / `spawn.ts` (persistent child transport + selected→main handoff),
 `worktree.ts` / `session-fork.ts` (filesystem/session branching), `tools.ts`
 (wait/status/control/stop), `widget.ts` (active-only TUI status), `announcements.ts`
-(recovery and feature notices), and `runtime.ts` (session-scoped ownership). No runtime dependencies beyond pi peer
-dependencies.
+(recovery and feature notices), and `runtime.ts` (session-scoped ownership). No runtime
+dependencies beyond pi peer dependencies.
 
 ## License
 

package/agents/reviewer.md

@@ -42,25 +42,23 @@ Understand the context first, then verify: the fix addresses the root cause, cha
 - Concurrency: shared mutable state, locks held across await, races.
 - Encoding/Unicode: assuming `char*`/files/CLI text is UTF-8; wrong `A` vs `W` Win32 APIs; boundary conversions.
 - Resource leaks; violations of the project's stated conventions.
-- Classify severity honestly. Distinguish blockers from nits; do not pad with style preferences.
+- Every finding you report gets fixed by the auto-fix loop — there are no severity tiers and no optional nits. Report genuine defects and risks only, each defensible with file:line evidence; leave out style preferences and anything you would merely "suggest". Order findings most important first.
 
 ## Collaboration
 - Independent of `worker` by design — your verdict is the gate before commit. Fix nothing yourself; report so the caller can dispatch a worker.
+- Re-reviews converge on an open-finding set: rule on each previously reported finding once (adjudicating the worker's explicit rejections — uphold only with a concrete refutation), add only defects the fix round introduced or exposed, and never re-open an item you verified resolved. Rounds are hard-capped, so padding a re-review with restated findings just burns them.
 
 ## Output format
 ## Files Reviewed
 - `path/to/file.ts`
-## Critical (must fix)
+## Findings
 - `file.ts:42` — concrete issue and why it breaks.
-## Warnings (should fix)
-- `file.ts:10` — issue and suggested direction.
-## Suggestions (consider)
-- Optional improvements.
+(Write "None" when you found nothing; an empty findings list is a valid, honest result.)
 ## Verdict
-One of: APPROVE / APPROVE_WITH_NITS / REQUEST_CHANGES, plus a 2-3 sentence rationale.
-End with exactly one machine-readable line: `VERDICT: REVIEW_PASS` for APPROVE or APPROVE_WITH_NITS; `VERDICT: REVIEW_FAIL` for REQUEST_CHANGES.
+One of: APPROVE / REQUEST_CHANGES, plus a 2-3 sentence rationale.
+End with exactly one machine-readable line: `VERDICT: REVIEW_PASS` for APPROVE; `VERDICT: REVIEW_FAIL` for REQUEST_CHANGES.
 
-REQUEST_CHANGES (or review-blocking concern) on this extension automatically starts an auto-fix loop: a worker is briefed with your findings, then you re-review, up to the configured round limit. Choose REVIEW_PASS when nothing objectively blocks the change (style preferences, optional refactors, or items the caller can knowingly accept are not blockers) — do not force a verdict that would trigger another loop just to hedge.
+REQUEST_CHANGES whenever even one finding remains. On this extension REQUEST_CHANGES automatically starts an auto-fix loop: a worker is briefed with your findings, fixes every one of them, and you re-review, up to the configured round limit. APPROVE means the findings list is empty — or, on a re-review, that every previously reported finding is resolved. Never quietly wave an issue through, and never invent findings to hedge: report each genuine issue once, accurately.
 
 ## Quality standards
 Specific file paths and line numbers. No vague feedback. A clean report means you looked hard, not that you found nothing to say.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ferris1225/pi-subagents",
-  "version": "2.0.3",
+  "version": "2.2.0",
   "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

@@ -1,70 +1,70 @@
-/** Session-start recovery and one-time feature announcements. */
-
-import { stat } from "node:fs/promises";
-import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
-import { loadConfig, saveConfig } from "./config.ts";
-import { announceRecoveryRecords } from "./recovery.ts";
-import type { SubagentRuntime } from "./runtime.ts";
-import { pruneResultArtifacts } from "./spawn.ts";
-import { installActiveRunsWidget } from "./widget.ts";
-
-const ANNOUNCEMENTS: Array<{
-	key: string;
-	condition: (config: Awaited<ReturnType<typeof loadConfig>>) => boolean;
-	message: string;
-}> = [
-	{
-		key: "visionModel",
-		condition: (config) => config.visionModel === undefined,
-		message:
-			"pi-subagents: new — a vision-capable model can now handle image tasks (screenshots, mockups, designs). Run /subagents-setup to configure it; until set, vision tasks use the main session's current model.",
-	},
-	{
-		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.",
-	},
-];
-
-async function announceNewFeatures(
-	ctx: { ui: { notify: (message: string, kind: "info" | "warning" | "error") => void } },
-	runtime: SubagentRuntime,
-): Promise<void> {
-	try {
-		let configExists = true;
-		try {
-			await stat(runtime.configPath);
-		} catch {
-			configExists = false;
-		}
-		if (!configExists) return;
-
-		const config = await loadConfig(runtime.configPath);
-		const pending = ANNOUNCEMENTS.filter(
-			(announcement) =>
-				announcement.condition(config) && !config.announcedFeatures.includes(announcement.key),
-		);
-		if (pending.length === 0) return;
-		await saveConfig(
-			{
-				...config,
-				announcedFeatures: [...config.announcedFeatures, ...pending.map((announcement) => announcement.key)],
-			},
-			runtime.configPath,
-		);
-		for (const announcement of pending) ctx.ui.notify(announcement.message, "info");
-	} catch {
-		/* announcement failures are non-fatal */
-	}
-}
-
-export function registerAnnouncements(pi: ExtensionAPI, runtime: SubagentRuntime): void {
-	pi.on("session_start", async (_event, ctx) => {
-		pruneResultArtifacts();
-		await announceRecoveryRecords(runtime.configPath, ctx);
-		if (ctx.mode !== "tui") return;
-		installActiveRunsWidget(ctx);
-		await announceNewFeatures(ctx, runtime);
-	});
-}
+/** Session-start recovery and one-time feature announcements. */
+
+import { stat } from "node:fs/promises";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { loadConfig, saveConfig } from "./config.ts";
+import { announceRecoveryRecords } from "./recovery.ts";
+import type { SubagentRuntime } from "./runtime.ts";
+import { pruneResultArtifacts } from "./spawn.ts";
+import { installActiveRunsWidget } from "./widget.ts";
+
+const ANNOUNCEMENTS: Array<{
+	key: string;
+	condition: (config: Awaited<ReturnType<typeof loadConfig>>) => boolean;
+	message: string;
+}> = [
+	{
+		key: "visionModel",
+		condition: (config) => config.visionModel === undefined,
+		message:
+			"pi-subagents: new — a vision-capable model can now handle image tasks (screenshots, mockups, designs). Run /subagents-setup to configure it; until set, vision tasks use the main session's current model.",
+	},
+	{
+		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.",
+	},
+];
+
+async function announceNewFeatures(
+	ctx: { ui: { notify: (message: string, kind: "info" | "warning" | "error") => void } },
+	runtime: SubagentRuntime,
+): Promise<void> {
+	try {
+		let configExists = true;
+		try {
+			await stat(runtime.configPath);
+		} catch {
+			configExists = false;
+		}
+		if (!configExists) return;
+
+		const config = await loadConfig(runtime.configPath);
+		const pending = ANNOUNCEMENTS.filter(
+			(announcement) =>
+				announcement.condition(config) && !config.announcedFeatures.includes(announcement.key),
+		);
+		if (pending.length === 0) return;
+		await saveConfig(
+			{
+				...config,
+				announcedFeatures: [...config.announcedFeatures, ...pending.map((announcement) => announcement.key)],
+			},
+			runtime.configPath,
+		);
+		for (const announcement of pending) ctx.ui.notify(announcement.message, "info");
+	} catch {
+		/* announcement failures are non-fatal */
+	}
+}
+
+export function registerAnnouncements(pi: ExtensionAPI, runtime: SubagentRuntime): void {
+	pi.on("session_start", async (_event, ctx) => {
+		pruneResultArtifacts();
+		await announceRecoveryRecords(runtime.configPath, ctx);
+		if (ctx.mode !== "tui") return;
+		installActiveRunsWidget(ctx);
+		await announceNewFeatures(ctx, runtime);
+	});
+}

package/src/completion.ts

@@ -8,6 +8,8 @@
  */
 
 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;
@@ -98,14 +100,20 @@ 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 summary only for real groups. */
+/** 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(", ");
-	return `### Subagents completed (${items.length}): ${agents}\n\n${items.map((item) => item.block).join("\n\n")}`;
+	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. */